neovim/runtime/doc/pi_health.txt

*pi_health.txt*   Healthcheck framework

Author: TJ DeVries <devries.timothyj@gmail.com>

                                      Type |gO| to see the table of contents.

==============================================================================
Introduction                            *health*

health.vim is a minimal framework to help with troubleshooting user
configuration. Nvim ships with healthchecks for configuration, performance,
python support, ruby support, clipboard support, and more.

To run the healthchecks, use this command: >

        :checkhealth
<
Plugin authors are encouraged to write new healthchecks. |health-dev|

==============================================================================
Commands                                *health-commands*

                                        *:checkhealth* *:CheckHealth*
:checkhealth          Run all healthchecks.
                                        *E5009*
                Nvim depends on |$VIMRUNTIME|, 'runtimepath' and 'packpath' to
                find the standard "runtime files" for syntax highlighting,
                filetype-specific behavior, and standard plugins (including
                :checkhealth).  If the runtime files cannot be found then
                those features will not work.

:checkhealth {plugins}
                Run healthcheck(s) for one or more plugins. E.g. to run only
                the standard Nvim healthcheck: >
                        :checkhealth nvim
<
                To run the healthchecks for the "foo" and "bar" plugins
                (assuming these plugins are on 'runtimepath' or 'packpath' and
                they have implemented the Lua or Vimscript interface
                require("foo.health").check() and health#bar#check(),
                respectively): >
                        :checkhealth foo bar
<
                To run healthchecks for lua submodules, use dot notation or
                "*" to refer to all submodules. For example nvim provides
                `vim.lsp` and `vim.treesitter`  >
                        :checkhealth vim.lsp vim.treesitter
                        :checkhealth vim*
<
==============================================================================
Lua Functions                       *health-functions-lua* *health-lua* *vim.health*

The Lua "health" module can be used to create new healthchecks (see also
|health-functions-vim|). To get started, simply use:

vim.health.report_start({name})                         *vim.health.report_start()*
        Starts a new report. Most plugins should call this only once, but if
        you want different sections to appear in your report, call this once
        per section.

vim.health.report_info({msg})                           *vim.health.report_info()*
        Reports an informational message.

vim.health.report_ok({msg})                             *vim.health.report_ok()*
        Reports a "success" message.

vim.health.report_warn({msg} [, {advice}])              *vim.health.report_warn()*
        Reports a warning. {advice} is an optional List of suggestions.

vim.health.report_error({msg} [, {advice}])             *vim.health.report_error()*
        Reports an error. {advice} is an optional List of suggestions.

==============================================================================
Create a Lua healthcheck                *health-dev-lua*

Healthchecks are functions that check the user environment, configuration,
etc. Nvim has built-in healthchecks in $VIMRUNTIME/autoload/health/.

To add a new healthcheck for your own plugin, simply define a Lua module in
your plugin that returns a table with a "check()" function. |:checkhealth|
will automatically find and invoke this function.

If your plugin is named "foo", then its healthcheck module should be a file in
one of these locations on 'runtimepath' or 'packpath':
        - lua/foo/health/init.lua
        - lua/foo/health.lua

If your plugin provides a submodule named "bar" for which you want a separate
healthcheck, define the healthcheck at one of these locations on 'runtimepath'
or 'packpath':
        - lua/foo/bar/health/init.lua
        - lua/foo/bar/health.lua

All submodules should return a Lua table containing the method `check()`.

Copy this sample code into `lua/foo/health/init.lua` or `lua/foo/health.lua`,
replacing "foo" in the path with your plugin name: >

        local M = {}

        M.check = function()
          vim.health.report_start("my_plugin report")
          -- make sure setup function parameters are ok
          if check_setup() then
            vim.health.report_ok("Setup function is correct")
          else
            vim.health.report_error("Setup function is incorrect")
          end
          -- do some more checking
          -- ...
        end

        return M

==============================================================================
Vimscript Functions             *health-functions-vimscript* *health-vimscript*

health.vim functions are for creating new healthchecks. (See also
|health-functions-lua|)

health#report_start({name})                             *health#report_start*
        Starts a new report. Most plugins should call this only once, but if
        you want different sections to appear in your report, call this once
        per section.

health#report_info({msg})                               *health#report_info*
        Reports an informational message.

health#report_ok({msg})                                 *health#report_ok*
        Reports a "success" message.

health#report_warn({msg} [, {advice}])                  *health#report_warn*
        Reports a warning. {advice} is an optional List of suggestions.

health#report_error({msg} [, {advice}])                 *health#report_error*
        Reports an error. {advice} is an optional List of suggestions.

health#{plugin}#check()                                 *health.user_checker*
        Healthcheck function for {plugin}. Called by |:checkhealth|
        automatically. Example: >

        function! health#my_plug#check() abort
          silent call s:check_environment_vars()
          silent call s:check_python_configuration()
        endfunction
<
==============================================================================
Create a healthcheck                    *health-dev-vim*

Healthchecks are functions that check the user environment, configuration,
etc. Nvim has built-in healthchecks in $VIMRUNTIME/autoload/health/.

To add a new healthcheck for your own plugin, simply define a
health#{plugin}#check() function in autoload/health/{plugin}.vim.
|:checkhealth| automatically finds and invokes such functions.

If your plugin is named "foo", then its healthcheck function must be >
        health#foo#check()

defined in this file on 'runtimepath' or 'packpath':
        - autoload/health/foo.vim

Copy this sample code into autoload/health/foo.vim and replace "foo" with your
plugin name: >
        function! health#foo#check() abort
          call health#report_start('sanity checks')
          " perform arbitrary checks
          " ...
        
          if looks_good
            call health#report_ok('found required dependencies')
          else
            call health#report_error('cannot find foo', 
              \ ['npm install --save foo'])
          endif
        endfunction

vim:et:tw=78:ts=8:ft=help:fdm=marker