mirror of
https://github.com/neovim/neovim.git
synced 2026-05-02 12:04:58 +00:00
docs(runtime/health): update with new lua support
- describe how the lua support works - explain new behavior of :checkhealth * - fixed formatting to use tab instead of spaces
This commit is contained in:
Javier López
@@ -13,7 +13,7 @@ python support, ruby support, clipboard support, and more.
|
||||
|
||||
To run the healthchecks, use this command: >
|
||||
|
||||
:checkhealth
|
||||
:checkhealth
|
||||
<
|
||||
Plugin authors are encouraged to write new healthchecks. |health-dev|
|
||||
|
||||
@@ -23,32 +23,107 @@ Commands *health-commands*
|
||||
*:checkhealth* *:CheckHealth*
|
||||
:checkhealth Run all healthchecks.
|
||||
*E5009*
|
||||
Nvim depends on |$VIMRUNTIME| and 'runtimepath' 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.
|
||||
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 your 'runtimepath' and
|
||||
they have implemented health#foo#check() and
|
||||
health#bar#check(), respectively): >
|
||||
:checkhealth foo bar
|
||||
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*
|
||||
<
|
||||
==============================================================================
|
||||
Functions *health-functions*
|
||||
Lua Functions *health-functions-lua* *health-lua*
|
||||
|
||||
health.vim functions are for creating new healthchecks. They mostly just do
|
||||
some layout and formatting, to give users a consistent presentation.
|
||||
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.
|
||||
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.
|
||||
@@ -56,27 +131,23 @@ health#report_info({msg}) *health#report_info*
|
||||
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_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#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: >
|
||||
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
|
||||
function! health#my_plug#check() abort
|
||||
silent call s:check_environment_vars()
|
||||
silent call s:check_python_configuration()
|
||||
endfunction
|
||||
<
|
||||
All output will be captured from the healthcheck. Use the
|
||||
health#report_* functions so that your healthcheck has a format
|
||||
consistent with the standard healthchecks.
|
||||
|
||||
==============================================================================
|
||||
Create a healthcheck *health-dev*
|
||||
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/.
|
||||
@@ -86,26 +157,24 @@ 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()
|
||||
health#foo#check()
|
||||
|
||||
defined in this file on 'runtimepath': >
|
||||
autoload/health/foo.vim
|
||||
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
|
||||
" ...
|
||||
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
|
||||
|
||||
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:tw=78:ts=8:ft=help:fdm=marker
|
||||
vim:noet tw=78:ts=8:ft=help:fdm=marker
|
||||
|
||||
Reference in New Issue
Block a user