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