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