1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
|
*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*
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
|
