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