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