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