-
Notifications
You must be signed in to change notification settings - Fork 11
/
osv.txt
208 lines (159 loc) · 6.76 KB
/
osv.txt
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
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
one-small-step-for-vimkind *one-small-step-for-vimkind* *osv*
|one-small-step-for-vimkind| (osv) is an adapter for Lua running inside Neovim.
It will allow you to:
* Debug Lua scripts
* Debug a running component inside Neovim (like a plug-in)
* Debug Neovim internal Lua scripts
In order to use |one-small-step-for-vimkind|, you will need a DAP client.
You can choose between two alternatives which are:
nvim-dap: https://github.com/mfussenegger/nvim-dap
vimspector: https://github.com/puremourning/vimspector
|one-small-step-for-vimkind| was mainly developed with nvim-dap which
is the one recommended.
Type |gO| to the table of contents.
=========================================================================
nvim-dap *osv-dap*
Please refer |dap-adapter| and |dap-configuration| to know about about
nvim-dap configurations.
The following configuration will allow you to attach a nvim-dap
client to |osv|.
>
local dap = require"dap"
dap.configurations.lua = {
{
type = 'nlua',
request = 'attach',
name = "Attach to running Neovim instance",
}
}
dap.adapters.nlua = function(callback, config)
callback({ type = 'server', host = config.host or "127.0.0.1", port = config.port or 8086 })
end
<
QUICKSTART
The following steps will guide you through the process to start
a debugging session using nvim-dap.
Let's say you have a lua script `myscript.lua` in your home directory.
It has the following content: >
print("start")
for i=1,10 do
print(i)
end
print("end")
<
1. Open a Neovim instance (instance A)
2. Launch the DAP server with (A) >
:lua require"osv".launch({port=8086})
3. Open another Neovim instance (instance B)
4. Open `myscript.lua` (B)
5. Place a breakpoint on line 2 using (B) >
:lua require"dap".toggle_breakpoint()
6. Connect the DAP client using (B) >
:lua require"dap".continue()
7. Run `myscript.lua` in the other instance (A) >
:luafile myscript.lua
8. The breakpoint should hit and freeze the instance (B)
=========================================================================
vimspector configuration *lua-debug-vimspector*
>
{
"$schema": "https://puremourning.github.io/vimspector/schema/vimspector.schema.json#",
"adapters": {
"nlua": {
"host": "127.0.0.1",
"port": "8086"
}
},
"configurations": {
"osv": {
"adapter": "nlua",
"configuration": {
"request": "attach"
}
}
}
}
<
=========================================================================
Launch server *osv-server*
To start a debugging session, you will first need to launch the server.
launch({opts}) *osv.launch()*
This command will launch the DAP server awaiting any connections. On
execution, a prompt message will display the port it's running on.
Parameters:
{opts} Optional parameters.
• `host`: defaults to "127.0.0.1"
• `port`: Specify a port number or if nil, lets the server
choose it.
• `config_file`: Specify a configuration file used when
spawning nvim
• `lvim`: Set this to true if you're using LunarVim.
choose an available port.
• `log`: boolean to enable logging
Return:
An server info object which contains
{host = {host}, port = {port}}
or nil on failure
The |osv.launch()| function will actually not
run the server in the running process but spawn a child process.
This ensures that DAP requests are still processed even in a
frozen state.
run_this({opts}) *osv.run_this()*
Parameters:
{opts} Optional parameters.
• `config_file`: See |osv.launch()|
• `lvim`: See |osv.launch()|
• `log`: boolean to enable logging
This command will automatically start the DAP server and connect
nvim-dap to it. You still need to set the `dap.adapters.nlua` as
explained in the configuration section.
stop() *osv.stop()*
This command will stop the running dap server. Following the DAP
standard, an "exited" event + an "terminated" will be sent to the client
so that it knows the server has exited.
start_trace() *osv.start_trace()*
Start a tracing session which records every line that gets executed
in the current Neovim instance. Stop it with |osv.stop_trace()|.
stop_trace() *osv.stop_trace()*
Stop the tracing session.
Return:~
A dictionary with the source path as key and a table
for each key with the executed line numbers.
is_running() *osv.is_running()*
Checks whether |osv| is currently running.
Return:~
True if osv is running.
=========================================================================
osv logging *osv-logging*
Logging can be enabled by passing the corresponding parameter in
|osv.launch|. The log will be written in:
>
vim.fn.stdpath('data') .. '/osv.log'
<
=========================================================================
osv plugins debugging *osv-plugins-debugging
Note: These explanations only are valid if you're using packer.nvim for
other plugin managers such as vim-plug you don't need to take special
precautions to debug plugins
As an example, let's say you're developing a plugin which is located
in a directory on your system. You would install it using:
>
use '...path to your plugin.../my-plugin.nvim'
<
After installing `my-plugin.nvim` using packer.nvim, a symlink will be created
inside the `nvim-data` which points to your local plugin directory.
The symlink is located in `nvim-data/pack/packer/start/my-plugin.nvim`. See
`:echo stdpath('data')` to check where your `nvim-data` directory is located.
When your plugin is executed from within nvim, it won't call the files
located inside your local directory but go through the symlink.
This means that breakpoints should also be set in the files which are
located inside the symlink so that executed files and the files which
contain breakpoints match and stop on trigger.
In consequence, reopen the files through the symlink and place the breakpoints
there to properly trigger them.
=========================================================================
osv repl *osv-repl*
The REPL supports evaluation of expression. It will prepend a "return "
statement which will return the value of the expression to the debugger.
This means expressions such as assignments will not be valid syntax.
vim:tw=78:ts=8:ft=help:norl: