diff options
Diffstat (limited to 'runtime/doc/develop.txt')
| -rw-r--r-- | runtime/doc/develop.txt | 44 |
1 files changed, 36 insertions, 8 deletions
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 3262d9dec7..90c2e30771 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -185,11 +185,25 @@ Example: API-CLIENT *dev-api-client* + *api-client* +API clients wrap the Nvim |API| to provide idiomatic "SDKs" for their +respective platforms (see |jargon|). You can build a new API client for your +favorite platform or programming language. + +List of API clients: + https://github.com/neovim/neovim/wiki/Related-projects#api-clients + + *pynvim* +The Python client is the reference implementation for API clients. + https://github.com/neovim/pynvim + Standard Features ~ +- API clients exist to hide msgpack-rpc details. The wrappers can be + automatically generated by reading the |api-metadata| from Nvim. |api-mapping| - Clients should call |nvim_set_client_info()| after connecting, so users and - plugins can detect the client by handling the |ChanInfo| event. This - avoids the need for special variables or other client hints. + plugins can detect the client by handling the |ChanInfo| event. This avoids + the need for special variables or other client hints. - Clients should handle |nvim_error_event| notifications, which will be sent if an async request to nvim was rejected or caused an error. @@ -209,15 +223,29 @@ Examples of API-client package names: BAD: python-client BAD: neovim -Implementation ~ - -For C/C++ projects, consider libmpack instead of the msgpack.org library. +API client implementation guidelines ~ + +- Separate the transport layer from the rest of the library. |rpc-connecting| +- Use a MessagePack library that implements at least version 5 of the + MessagePack spec, which supports the BIN and EXT types used by Nvim. +- Use a single-threaded event loop library/pattern. +- Use a fiber/coroutine library for the language being used for implementing + a client. These greatly simplify concurrency and allow the library to + expose a blocking API on top of a non-blocking event loop without the + complexity that comes with preemptive multitasking. +- Don't assume anything about the order of responses to RPC requests. +- Clients should expect requests, which must be handled immediately because + Nvim is blocked while waiting for the client response. +- Clients should expect notifications, but these can be handled "ASAP" (rather + than immediately) because they won't block Nvim. +- For C/C++ projects, consider libmpack instead of the msgpack.org library. https://github.com/libmpack/libmpack/ -libmpack is small (no dependencies, can inline into your C/C++ project) and -efficient (no allocations). It also implements msgpack-RPC, the protocol -required by Nvim. + libmpack is small (no dependencies, can inline into your C/C++ project) and + efficient (no allocations). It also implements msgpack-RPC, the protocol + required by Nvim. https://github.com/msgpack-rpc/msgpack-rpc + EXTERNAL UI *dev-ui* External UIs should be aware of the |api-contract|. In particular, future |