Developer Overview

IRC Channel

Feel free to join #vis-editor on libera to discuss development related issues.

Build System

We use a handwritten, POSIX shell compliant configure script based on the one used by musl which generates a config.mk file with all detected compiler flags.

The main Makefile strives to be POSIX compliant in order to support BSD make (on Linux this can be tested by installing bmake(1)).

GNU make specific features can be used in the GNUmakefile used to implement the developer oriented make standalone target.

During development it is recommended to build the project using make debug which uses stricter compiler flags and enables debugging.

Test Suite

To make sure your modifications do not break existing functionality, you should run the test suite by executing make test.

The test suite is currently located in a separate repository included as a git submodule.

Testing infrastructure for the low level core data structures, vim compatibility, sam compatibility, vis specific features and the Lua API is in place, but code coverage should be improved further.

Manual Pages

We ship a set of manual pages stored the man/ sub folder. They are written in mdoc(7) format. If you have mandoc(1) installed you can invoke make man which will check them for errors and generate HTML output.

Lua

The C core currently requires at least Lua 5.2. However, we might want to support LuaJIT at some point. Hence we try to avoid unnecessary use of unsupported language constructs in the Lua files shipped by vis.

Luacheck

You should run luacheck on your Lua files. If they are placed within the vis source tree, the following should work:

$ make luacheck

API Documentation

When modifying the exposed Lua API you should update the corresponding Lua documentation written in LDoc format. make luadoc will produce HTML output.

Coding Style

We currently do not enforce a strict coding style, use common sense and good taste: try to keep the code consistent with what is already there, avoid unnecessary white space only changes etc.

Use tabs for indentation, spaces for alignment. Avoid overly long lines (except if it significantly improves readability) and deep nesting levels.

Source Tree Layout

A quick overview over the code structure to get you started:

File(s)	Description
configure	Handwritten, POSIX shell compliant configure script derived from musl
Makefile	Standard make targets, BSD make(1) compatible
GNUmakefile	Developer targets (e.g. for standalone builds)
config.def.h	definition of default key bindings, will be copied to config.h
array.[ch]	dynamically growing array, can store arbitrarily sized objects
buffer.[ch]	dynamically growing buffer used for registers and macros
ring-buffer.[ch]	fixed size ring buffer used for the jump list
map.[ch]	crit-bit tree based map supporting unique prefix lookups and ordered iteration
register.[ch]	register implementation, system clipboard integration via vis-clipboard
text.[ch]	low level text / marks / {un,re}do tree / piece table implementation
text-motions.[ch]	movement functions take a file position and return a new one
text-objects.[ch]	functions take a file position and return a file range
text-regex.[ch]	text regex search functionality, based on libc regex(3)
text-regex-tre.c	text regex search functionality, based on libtre
text-util.[ch]	text related utility functions mostly dealing with file ranges
ui.h	abstract interface which has to be implemented by ui backends
ui-terminal.[ch]	a terminal based user interface managing the 2D-cell grid
ui-terminal-curses.[ch]	a curses based terminal output backend
ui-terminal-vt100.[ch]	a minimal terminal backend using raw escape sequences
view.[ch]	ui-independent viewport, shows part of a file, cursor placement, selection handling
sam.[ch]	structural regular expression based command language
vis-cmds.c	vi(m) :-command implementation, #included from sam.c
vis-core.h	internal header file, various structs for core editor primitives
vis.c	vi(m) specific editor frontend implementation
vis.h	vi(m) specific editor frontend library public API
vis-lua.[ch]	Lua bindings, exposing core vis APIs for in process extension
vis-modes.c	vi(m) mode switching, enter/leave event handling
vis-motions.c	vi(m) cursor motion implementations, uses text-motions.h internally
vis-operators.c	vi(m) operator implementation
vis-prompt.c	:, / and ? prompt implemented as a regular file/window with custom key bindings
vis-text-objects.c	vi(m) text object implementations, uses text-objects.h internally
main.c	Key action definitions, program entry point
lua/	Lua runtime files
lua/visrc.lua	Lua startup and configuration script
lua/*.lua	Lua library for vis, providing parts of the exposed API, syntax highlighting, status bar
lua/lexers/	Lua LPeg based lexers used for syntax highlighting
lua/themes/	Color themes as used by the lexers
lua/plugins/	Non-essential functionality extending core editor primitives
lua/doc/	LDoc generated Lua API documentation
man/	Manual pages in mdoc(7) format
vis-menu.c	Interactive menu utility used for file and word completion
vis-open	Simple directory browser based on vis-menu
vis-complete	Simple file and word completion wrapper based on vis-menu
vis-digraph.c	Utility to print Unicode characters using mnemonics
vis-clipboard	Shell script to abstract system clipboard handling for X, macOS and Cygwin
vis-single.sh	Shell script used to produce a self-extracting executable