*pi_health.txt* Healthcheck framework Author: TJ DeVries 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* The Lua "health" module can be used to create new healthchecks (see also |health-functions-vim|). To get started, simply use: > local health = require('health') < 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. ============================================================================== 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 = {} local health = require("health") M.check = function() health.report_start("my_plugin report") -- make sure setup function parameters are ok if check_setup() then health.report_ok("Setup function is correct") else 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