diff options
Diffstat (limited to 'runtime/doc/develop.txt')
| -rw-r--r-- | runtime/doc/develop.txt | 225 |
1 files changed, 136 insertions, 89 deletions
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 6ecbf9fb0d..e244072c66 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -1,88 +1,54 @@ -*develop.txt* +*develop.txt* Nvim NVIM REFERENCE MANUAL -Development of Nvim. *development* +Development of Nvim *development* -1. Design goals |design-goals| -2. Design decisions |design-decisions| +This reference describes design constraints and guidelines, for developing +Nvim applications or Nvim itself. +Architecture and internal concepts are covered in src/nvim/README.md -Nvim is open source software. Everybody is encouraged to contribute. +Nvim is free and open source. Everybody is encouraged to contribute. https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md -See src/nvim/README.md for a high-level overview of the source code: - https://github.com/neovim/neovim/blob/master/src/nvim/README.md + Type |gO| to see the table of contents. ============================================================================== -1. Design goals *design-goals* +Design goals *design-goals* -Most important things come first (roughly). - -Note that quite a few items are contradicting. This is intentional. A -balance must be found between them. +Most important things come first (roughly). Some items conflict; this is +intentional. A balance must be found. NVIM IS... IMPROVED *design-improved* -The IMproved bits of Vim should make it a better Vi, without becoming a -completely different editor. Extensions are done with a "Vi spirit". -- Use the keyboard as much as feasible. The mouse requires a third hand, - which we don't have. Many terminals don't have a mouse. -- When the mouse is used anyway, avoid the need to switch back to the - keyboard. Avoid mixing mouse and keyboard handling. -- Add commands and options in a consistent way. Otherwise people will have a - hard time finding and remembering them. Keep in mind that more commands and - options will be added later. +The Neo bits of Nvim should make it a better Vim, without becoming a +completely different editor. +- In matters of taste, prefer Vim/Unix tradition. If there is no relevant + Vim/Unix tradition, consider the "common case". - A feature that people do not know about is a useless feature. Don't add obscure features, or at least add hints in documentation that they exist. -- Minimize using CTRL and other modifiers, they are more difficult to type. -- There are many first-time and inexperienced Vim users. Make it easy for - them to start using Vim and learn more over time. - There is no limit to the features that can be added. Selecting new features - is one based on (1) what users ask for, (2) how much effort it takes to + is based on (1) what users ask for, (2) how much effort it takes to implement and (3) someone actually implementing it. - - -NVIM IS... MULTI PLATFORM *design-multi-platform* - -Vim tries to help as many users on as many platforms as possible. -- Support many kinds of terminals. The minimal demands are cursor positioning - and clear-screen. Commands should only use key strokes that most keyboards - have. Support all the keys on the keyboard for mapping. -- Support many platforms. A condition is that there is someone willing to do - Vim development on that platform, and it doesn't mean messing up the code. -- Support many compilers and libraries. Not everybody is able or allowed to - install another compiler or GUI library. -- People switch from one platform to another, and from GUI to terminal - version. Features should be present in all versions, or at least in as many - as possible with a reasonable effort. Try to avoid that users must switch - between platforms to accomplish their work efficiently. -- That a feature is not possible on some platforms, or only possible on one - platform, does not mean it cannot be implemented. [This intentionally - contradicts the previous item, these two must be balanced.] +- Backwards compatibility is a feature. The RPC API in particular should + never break. NVIM IS... WELL DOCUMENTED *design-documented* - A feature that isn't documented is a useless feature. A patch for a new feature must include the documentation. -- Documentation should be comprehensive and understandable. Using examples is - recommended. +- Documentation should be comprehensive and understandable. Use examples. - Don't make the text unnecessarily long. Less documentation means that an item is easier to find. -- Do not prefix doc-tags with "nvim-". Use |vim_diff.txt| to document - differences from Vim. The {Nvim} annotation is also available - to mark a specific feature. No other distinction is necessary. -- If a feature is removed, delete its doc entry and move its tag to - |vim_diff.txt|. NVIM IS... HIGH SPEED AND SMALL IN SIZE *design-speed-size* -Using Vim must not be a big attack on system resources. Keep it small and -fast. +Keep Nvim small and fast. - Computers are becoming faster and bigger each year. Vim can grow too, but no faster than computers are growing. Keep Vim usable on older systems. - Many users start Vim from a shell very often. Startup time must be short. @@ -105,47 +71,18 @@ NVIM IS... MAINTAINABLE *design-maintain* knowledge spread to other parts of the code. -NVIM IS... FLEXIBLE *design-flexible* - -Vim should make it easy for users to work in their preferred styles rather -than coercing its users into particular patterns of work. This can be for -items with a large impact or for details. The defaults are carefully chosen -such that most users will enjoy using Vim as it is. Commands and options can -be used to adjust Vim to the desire of the user and its environment. - - NVIM IS... NOT *design-not* Nvim is not an operating system; instead it should be composed with other tools or hosted as a component. Marvim once said: "Unlike Emacs, Nvim does not -include the kitchen sink... but you can use it for plumbing." +include the kitchen sink... but it's good for plumbing." ============================================================================== -2. Design decisions *design-decisions* - -Jargon *dev-jargon* - -Host ~ -A plugin "host" is both a client (of the Nvim API) and a server (of an -external platform, e.g. python). It is a remote plugin that hosts other -plugins. +Developer guidelines *dev* -Window ~ -The word "window" is commonly used for several things: A window on the screen, -the xterm window, a window inside Vim to view a buffer. -To avoid confusion, other items that are sometimes called window have been -given another name. Here is an overview of the related items: -screen The whole display. For the GUI it's something like 1024x768 - pixels. The Vim shell can use the whole screen or part of it. -shell The Vim application. This can cover the whole screen (e.g., - when running in a console) or part of it (xterm or GUI). -window View on a buffer. There can be several windows in Vim, - together with the command line, menubar, toolbar, etc. they - fit in the shell. - -Providers *dev-provider* +PROVIDERS *dev-provider* A goal of Nvim is to allow extension of the editor without special knowledge in the core. But some Vim components are too tightly coupled; in those cases @@ -188,9 +125,119 @@ defined if a valid external Python host is found. That works well with the Python host isn't installed then the plugin will "think" it is running in a Vim compiled without the |+python| feature. +DOCUMENTATION *dev-doc* + +- Do not prefix help tags with "nvim-". Use |vim_diff.txt| to document + differences from Vim; no other distinction is necessary. +- If a Vim feature is removed, delete its help section and move its tag to + |vim_diff.txt|. +- Move deprecated features to |deprecated.txt|. +- Use consistent language. + - "terminal" in a help tag always means "the embedded terminal emulator", not + "the user host terminal". + - Use "tui-" to prefix help tags related to the host terminal, and "TUI" + in prose if possible. +- Docstrings: do not start parameter descriptions with "The" or "A" unless it + is critical to avoid ambiguity. + GOOD: > + /// @param dirname Path fragment before `pend` +< BAD: > + /// @param dirname The path fragment before `pend` +< + +API *dev-api* + +Use this template to name new API functions: + nvim_{thing}_{action}_{arbitrary-qualifiers} + +If the function acts on an object then {thing} is the name of that object +(e.g. "buf" or "win"). If the function operates in a "global" context then +{thing} is usually omitted (but consider "namespacing" your global operations +with a {thing} that groups functions under a common concept). + +Use existing common {action} names if possible: + add Append to, or insert into, a collection + get Get a thing (or subset of things by some query) + set Set a thing + del Delete a thing (or group of things) + list Get all things + +Use consistent names for {thing} in all API functions. E.g. a buffer is called +"buf" everywhere, not "buffer" in some places and "buf" in others. + +Example: `nvim_get_current_line` acts on the global editor state; the common +{action} "get" is used but {thing} is omitted. + +Example: `nvim_buf_add_highlight` acts on a `Buffer` object (the first +parameter) and uses the common {action} "add". + +Example: `nvim_list_bufs` operates in a global context (first parameter is +_not_ a Buffer). The common {action} "list" indicates that it lists all +bufs (plural) in the global context. + +Use this template to name new API events: + nvim_{thing}_{event}_event + +Example: `nvim_buf_changedtick_event`. + + +API-CLIENT *dev-api-client* + +Standard Features ~ + +- 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. +- Clients should handle |nvim_error_event| notifications, which will be sent + if an async request to nvim was rejected or caused an error. + +Package Naming ~ + +API client packages should NOT be named something ambiguous like "neovim" or +"python-client". Use "nvim" as a prefix/suffix to some other identifier +following ecosystem conventions. + +For example, Python packages tend to have "py" in the name, so "pynvim" is +a good name: it's idiomatic and unambiguous. If the package is named "neovim", +it confuses users, and complicates documentation and discussions. + +Examples of API-client package names: + GOOD: nvim-racket + GOOD: pynvim + BAD: python-client + BAD: neovim + +Implementation ~ + +Consider using libmpack instead of the msgpack.org C/C++ library. libmpack is +small (can be inlined into your C/C++ project) and efficient (no allocations). +It also implements msgpack-RPC. +https://github.com/libmpack/libmpack/ + +EXTERNAL UI *dev-ui* + +External UIs should be aware of the |api-contract|. In particular, future +versions of Nvim may add new items to existing events. The API is strongly +backwards-compatible, but clients must not break if new (optional) fields are +added to existing events. + +Standard Features ~ + +External UIs are expected to implement these common features: + +- Call |nvim_set_client_info()| after connecting, so users and plugins can + detect the UI by handling the |ChanInfo| event. This avoids the need for + special variables and UI-specific config files (gvimrc, macvimrc, …). +- Cursor style (shape, color) should conform to the 'guicursor' properties + delivered with the mode_info_set UI event. +- Send the ALT/META ("Option" on macOS) key as a |<M-| chord. +- Send the "super" key (Windows key, Apple key) as a |<D-| chord. +- Avoid mappings that conflict with the Nvim keymap-space; GUIs have many new + chords (<C-,> <C-Enter> <C-S-x> <D-x>) and patterns ("shift shift") that do + not potentially conflict with Nvim defaults, plugins, etc. +- Consider the "option_set" |ui-global| event as a hint for other GUI + behaviors. UI-related options ('guifont', 'ambiwidth', …) are published in + this event. -RPC API -API client -remote plugin - vim:tw=78:ts=8:ft=help:norl: + vim:tw=78:ts=8:noet:ft=help:norl: |