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--------------- | ----------- 26alloc.c | memory management 27arglist.c | handling argument list 28autocmd.c | autocommands 29blob.c | blob data type 30buffer.c | manipulating buffers (loaded files) 31bufwrite.c | writing a buffer to file 32change.c | handling changes to text 33cindent.c | C and Lisp indentation 34clientserver.c | client server functionality 35clipboard.c | handling the clipboard 36cmdexpand.c | command-line completion 37cmdhist.c | command-line history 38debugger.c | vim script debugger 39diff.c | diff mode (vimdiff) 40drawline.c | drawing a window line 41drawscreen.c | drawing the windows 42eval.c | expression evaluation 43evalbuffer.c | buffer related built-in functions 44evalfunc.c | built-in functions 45evalvars.c | vim variables 46evalwindow.c | window related built-in functions 47fileio.c | reading and writing files 48filepath.c | dealing with file names and paths 49findfile.c | search for files in 'path' 50fold.c | folding 51getchar.c | getting characters and key mapping 52help.c | vim help related functions 53highlight.c | syntax highlighting 54indent.c | text indentation 55insexpand.c | Insert mode completion 56locale.c | locale/language handling 57map.c | mapping and abbreviations 58mark.c | marks 59match.c | highlight matching 60float.c | floating point functions 61mbyte.c | multi-byte character handling 62memfile.c | storing lines for buffers in a swapfile 63memline.c | storing lines for buffers in memory 64menu.c | menus 65message.c | (error) messages 66mouse.c | handling the mouse 67ops.c | handling operators ("d", "y", "p") 68option.c | options 69optionstr.c | handling string options 70popupmenu.c | popup menu 71popupwin.c | popup window 72profiler.c | vim script profiler 73quickfix.c | quickfix commands (":make", ":cn") 74regexp.c | pattern matching 75register.c | handling registers 76scriptfile.c | runtime directory handling and sourcing scripts 77screen.c | lower level screen functions 78search.c | pattern searching 79session.c | sessions and views 80sign.c | signs 81spell.c | spell checking core 82spellfile.c | spell file handling 83spellsuggest.c | spell correction suggestions 84strings.c | string manipulation functions 85syntax.c | syntax and other highlighting 86tag.c | tags 87term.c | terminal handling, termcap codes 88testing.c | testing: assert and test functions 89textformat.c | text formatting 90textobject.c | text objects 91textprop.c | text properties 92time.c | time and timer functions 93typval.c | vim script type/value functions 94undo.c | undo and redo 95usercmd.c | user defined commands 96userfunc.c | user defined functions 97viminfo.c | viminfo handling 98window.c | handling split windows 99 100 101## Debugging ## 102 103If you have a reasonable recent version of gdb, you can use the `:Termdebug` 104command to debug Vim. See `:help :Termdebug`. 105 106When something is time critical or stepping through code is a hassle, use the 107channel logging to create a time-stamped log file. Add lines to the code like 108this: 109 110 ch_log(NULL, "Value is now %02x", value); 111 112After compiling and starting Vim, do: 113 114 :call ch_logfile('debuglog', 'w') 115 116And edit `debuglog` to see what happens. The channel functions already have 117`ch_log()` calls, thus you always see that in the log. 118 119 120## Important Variables ## 121 122The current mode is stored in `State`. The values it can have are `NORMAL`, 123`INSERT`, `CMDLINE`, and a few others. 124 125The current window is `curwin`. The current buffer is `curbuf`. These point 126to structures with the cursor position in the window, option values, the file 127name, etc. These are defined in 128[`structs.h`](https://github.com/vim/vim/blob/master/src/structs.h). 129 130All the global variables are declared in 131[`globals.h`](https://github.com/vim/vim/blob/master/src/globals.h). 132 133 134## The main loop ## 135 136This is conveniently called `main_loop()`. It updates a few things and then 137calls `normal_cmd()` to process a command. This returns when the command is 138finished. 139 140The basic idea is that Vim waits for the user to type a character and 141processes it until another character is needed. Thus there are several places 142where Vim waits for a character to be typed. The `vgetc()` function is used 143for this. It also handles mapping. 144 145Updating the screen is mostly postponed until a command or a sequence of 146commands has finished. The work is done by `update_screen()`, which calls 147`win_update()` for every window, which calls `win_line()` for every line. 148See the start of 149[`screen.c`](https://github.com/vim/vim/blob/master/src/screen.c) 150for more explanations. 151 152 153## Command-line mode ## 154 155When typing a `:`, `normal_cmd()` will call `getcmdline()` to obtain a line 156with an Ex command. `getcmdline()` contains a loop that will handle each typed 157character. It returns when hitting `CR` or `Esc` or some other character that 158ends the command line mode. 159 160 161## Ex commands ## 162 163Ex commands are handled by the function `do_cmdline()`. It does the generic 164parsing of the `:` command line and calls `do_one_cmd()` for each separate 165command. It also takes care of while loops. 166 167`do_one_cmd()` parses the range and generic arguments and puts them in the 168`exarg_t` and passes it to the function that handles the command. 169 170The `:` commands are listed in `ex_cmds.h`. The third entry of each item is 171the name of the function that handles the command. The last entry are the 172flags that are used for the command. 173 174 175## Normal mode commands ## 176 177The Normal mode commands are handled by the `normal_cmd()` function. It also 178handles the optional count and an extra character for some commands. These 179are passed in a `cmdarg_t` to the function that handles the command. 180 181There is a table `nv_cmds` in 182[`normal.c`](https://github.com/vim/vim/blob/master/src/normal.c) 183which lists the first character of every command. The second entry of each 184item is the name of the function that handles the command. 185 186 187## Insert mode commands ## 188 189When doing an `i` or `a` command, `normal_cmd()` will call the `edit()` 190function. It contains a loop that waits for the next character and handles it. 191It returns when leaving Insert mode. 192 193 194## Options ## 195 196There is a list with all option names in 197[`option.c`](https://github.com/vim/vim/blob/master/src/option.c), 198called `options[]`. 199 200 201## The GUI ## 202 203Most of the GUI code is implemented like it was a clever terminal. Typing a 204character, moving a scrollbar, clicking the mouse, etc. are all translated 205into events which are written in the input buffer. These are read by the 206main code, just like reading from a terminal. The code for this is scattered 207through [`gui.c`](https://github.com/vim/vim/blob/master/src/gui.c). 208For example, `gui_send_mouse_event()` for a mouse click and `gui_menu_cb()` for 209a menu action. Key hits are handled by the system-specific GUI code, which 210calls `add_to_input_buf()` to send the key code. 211 212Updating the GUI window is done by writing codes in the output buffer, just 213like writing to a terminal. When the buffer gets full or is flushed, 214`gui_write()` will parse the codes and draw the appropriate items. Finally the 215system-specific GUI code will be called to do the work. 216 217 218## Debugging the GUI ## 219 220Remember to prevent that gvim forks and the debugger thinks Vim has exited, 221add the `-f` argument. In gdb: `run -f -g`. 222 223When stepping through display updating code, the focus event is triggered 224when going from the debugger to Vim and back. To avoid this, recompile with 225some code in `gui_focus_change()` disabled. 226 227 228## Contributing ## 229 230If you would like to help making Vim better, see the 231[`CONTRIBUTING.md`](https://github.com/vim/vim/blob/master/CONTRIBUTING.md) 232file. 233 234 235This is `README.md` for version 8.2 of the Vim source code. 236
){kind=link}