1 2 3# Vim source code # 4 5Here are a few hints for finding your way around the source code. This 6doesn't make it less complex than it is, but it gets you started. 7 8You might also want to read 9[`:help development`](http://vimdoc.sourceforge.net/htmldoc/develop.html#development). 10 11 12## Jumping around ## 13 14First of all, use `:make tags` to generate a tags file, so that you can jump 15around in the source code. 16 17To jump to a function or variable definition, move the cursor on the name and 18use the `CTRL-]` command. Use `CTRL-T` or `CTRL-O` to jump back. 19 20To jump to a file, move the cursor on its name and use the `gf` command. 21 22Most code can be found in a file with an obvious name (incomplete list): 23 24File name | Description 25--------- | ----------- 26autocmd.c | autocommands 27buffer.c | manipulating buffers (loaded files) 28diff.c | diff mode (vimdiff) 29eval.c | expression evaluation 30fileio.c | reading and writing files 31findfile.c | search for files in 'path' 32fold.c | folding 33getchar.c | getting characters and key mapping 34indent.c | C and Lisp indentation 35mark.c | marks 36mbyte.c | multi-byte character handling 37memfile.c | storing lines for buffers in a swapfile 38memline.c | storing lines for buffers in memory 39menu.c | menus 40message.c | (error) messages 41ops.c | handling operators ("d", "y", "p") 42option.c | options 43quickfix.c | quickfix commands (":make", ":cn") 44regexp.c | pattern matching 45screen.c | updating the windows 46search.c | pattern searching 47sign.c | signs 48spell.c | spell checking 49syntax.c | syntax and other highlighting 50tag.c | tags 51term.c | terminal handling, termcap codes 52undo.c | undo and redo 53window.c | handling split windows 54 55 56## Debugging ## 57 58If you have a reasonable recent version of gdb, you can use the `:Termdebug` 59command to debug Vim. See `:help :Termdebug`. 60 61When something is time critical or stepping through code is a hassle, use the 62channel logging to create a time-stamped log file. Add lines to the code like 63this: 64 65 ch_log(NULL, "Value is now %02x", value); 66 67After compiling and starting Vim, do: 68 69 :call ch_logfile('debuglog', 'w') 70 71And edit `debuglog` to see what happens. The channel functions already have 72`ch_log()` calls, thus you always see that in the log. 73 74 75## Important Variables ## 76 77The current mode is stored in `State`. The values it can have are `NORMAL`, 78`INSERT`, `CMDLINE`, and a few others. 79 80The current window is `curwin`. The current buffer is `curbuf`. These point 81to structures with the cursor position in the window, option values, the file 82name, etc. These are defined in 83[`structs.h`](https://github.com/vim/vim/blob/master/src/globals.h). 84 85All the global variables are declared in 86[`globals.h`](https://github.com/vim/vim/blob/master/src/structs.h). 87 88 89## The main loop ## 90 91This is conveniently called `main_loop()`. It updates a few things and then 92calls `normal_cmd()` to process a command. This returns when the command is 93finished. 94 95The basic idea is that Vim waits for the user to type a character and 96processes it until another character is needed. Thus there are several places 97where Vim waits for a character to be typed. The `vgetc()` function is used 98for this. It also handles mapping. 99 100Updating the screen is mostly postponed until a command or a sequence of 101commands has finished. The work is done by `update_screen()`, which calls 102`win_update()` for every window, which calls `win_line()` for every line. 103See the start of 104[`screen.c`](https://github.com/vim/vim/blob/master/src/screen.c) 105for more explanations. 106 107 108## Command-line mode ## 109 110When typing a `:`, `normal_cmd()` will call `getcmdline()` to obtain a line 111with an Ex command. `getcmdline()` contains a loop that will handle each typed 112character. It returns when hitting `CR` or `Esc` or some other character that 113ends the command line mode. 114 115 116## Ex commands ## 117 118Ex commands are handled by the function `do_cmdline()`. It does the generic 119parsing of the `:` command line and calls `do_one_cmd()` for each separate 120command. It also takes care of while loops. 121 122`do_one_cmd()` parses the range and generic arguments and puts them in the 123`exarg_t` and passes it to the function that handles the command. 124 125The `:` commands are listed in `ex_cmds.h`. The third entry of each item is 126the name of the function that handles the command. The last entry are the 127flags that are used for the command. 128 129 130## Normal mode commands ## 131 132The Normal mode commands are handled by the `normal_cmd()` function. It also 133handles the optional count and an extra character for some commands. These 134are passed in a `cmdarg_t` to the function that handles the command. 135 136There is a table `nv_cmds` in 137[`normal.c`](https://github.com/vim/vim/blob/master/src/normal.c) 138which lists the first character of every command. The second entry of each 139item is the name of the function that handles the command. 140 141 142## Insert mode commands ## 143 144When doing an `i` or `a` command, `normal_cmd()` will call the `edit()` 145function. It contains a loop that waits for the next character and handles it. 146It returns when leaving Insert mode. 147 148 149## Options ## 150 151There is a list with all option names in 152[`option.c`](https://github.com/vim/vim/blob/master/src/option.c), 153called `options[]`. 154 155 156## The GUI ## 157 158Most of the GUI code is implemented like it was a clever terminal. Typing a 159character, moving a scrollbar, clicking the mouse, etc. are all translated 160into events which are written in the input buffer. These are read by the 161main code, just like reading from a terminal. The code for this is scattered 162through [`gui.c`](https://github.com/vim/vim/blob/master/src/gui.c). 163For example, `gui_send_mouse_event()` for a mouse click and `gui_menu_cb()` for 164a menu action. Key hits are handled by the system-specific GUI code, which 165calls `add_to_input_buf()` to send the key code. 166 167Updating the GUI window is done by writing codes in the output buffer, just 168like writing to a terminal. When the buffer gets full or is flushed, 169`gui_write()` will parse the codes and draw the appropriate items. Finally the 170system-specific GUI code will be called to do the work. 171 172 173## Debugging the GUI ## 174 175Remember to prevent that gvim forks and the debugger thinks Vim has exited, 176add the `-f` argument. In gdb: `run -f -g`. 177 178When stepping through display updating code, the focus event is triggered 179when going from the debugger to Vim and back. To avoid this, recompile with 180some code in `gui_focus_change()` disabled. 181 182 183## Contributing ## 184 185If you would like to help making Vim better, see the 186[`CONTRIBUTING.md`](https://github.com/vim/vim/blob/master/CONTRIBUTING.md) 187file. 188 189 190This is `README.md` for version 8.1 of the Vim source code. 191
){kind=link}