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