mirror of
https://github.com/neovim/neovim.git
synced 2025-09-05 19:08:15 +00:00
81 lines
2.9 KiB
Plaintext
81 lines
2.9 KiB
Plaintext
*dev_arch.txt* Nvim
|
|
|
|
|
|
NVIM REFERENCE MANUAL
|
|
|
|
|
|
How to develop Nvim, explanation of modules and subsystems *dev-arch*
|
|
|
|
The top of each major module has (or should have) an overview in a comment at
|
|
the top of its file. The purpose of this document is to give:
|
|
|
|
1. an overview of how it all fits together
|
|
2. how-to guides for common tasks such as:
|
|
- deprecating public functions
|
|
- adding a new public (API) function
|
|
- adding a new public (UI) event
|
|
3. TODO: move src/nvim/README.md into this doc.
|
|
|
|
Type |gO| to see the table of contents.
|
|
|
|
==============================================================================
|
|
Data structures
|
|
|
|
Use `kvec.h` for most lists. When you absolutely need a linked list, use
|
|
`lib/queue_defs.h` which defines an "intrusive" linked list.
|
|
|
|
==============================================================================
|
|
UI events
|
|
|
|
The source files most directly involved with UI events are:
|
|
1. `src/nvim/ui.*`: calls handler functions of registered UI structs (independent from msgpack-rpc)
|
|
2. `src/nvim/api/ui.*`: forwards messages over msgpack-rpc to remote UIs.
|
|
|
|
UI events are defined in `src/nvim/api/ui_events.in.h` , this file is not
|
|
compiled directly, rather it parsed by
|
|
`src/nvim/generators/gen_api_ui_events.lua` which autogenerates wrapper
|
|
functions used by the source files above. It also generates metadata
|
|
accessible as `api_info().ui_events`.
|
|
|
|
See commit d3a8e9217f39c59dd7762bd22a76b8bd03ca85ff for an example of adding
|
|
a new UI event.
|
|
|
|
UI events are deferred to UIs, which implies a deepcopy of the UI event data.
|
|
|
|
Remember to bump NVIM_API_LEVEL if it wasn't already during this development
|
|
cycle.
|
|
|
|
Other references:
|
|
- |msgpack-rpc|
|
|
- |ui|
|
|
- https://github.com/neovim/neovim/pull/3246
|
|
- https://github.com/neovim/neovim/pull/18375
|
|
- https://github.com/neovim/neovim/pull/21605
|
|
|
|
|
|
==============================================================================
|
|
API
|
|
|
|
*dev-api-fast*
|
|
API functions and Vimscript "eval" functions may be marked as |api-fast| which
|
|
means they are safe to call in Lua callbacks and other scenarios. A functions
|
|
CANNOT be marked as "fast" if could trigger `os_breakcheck()`, which may
|
|
"yield" the current execution and start a new execution of code not expecting
|
|
this:
|
|
- accidentally recursing into a function not expecting this.
|
|
- changing (global) state without restoring it before returning to the
|
|
"yielded" callsite.
|
|
|
|
In practice, this means any code that could trigger `os_breakcheck()` cannot
|
|
be "fast". For example, commit 3940c435e405 fixed such a bug with
|
|
`nvim__get_runtime` by explicitly disallowing `os_breakcheck()` via the
|
|
`EW_NOBREAK` flag.
|
|
|
|
Common examples of non-fast code: regexp matching, wildcard expansion,
|
|
expression evaluation.
|
|
|
|
|
|
==============================================================================
|
|
|
|
vim:tw=78:ts=8:sw=4:et:ft=help:norl:
|