src/README.txt

   1 README for the Vim source code
   2
   3 Here are a few hints for finding your way around the source code.  This
   4 doesn't make it less complex than it is, but it gets you started.
   5
   6 You might also want to read ":help development".
   7
   8
   9 JUMPING AROUND
  10
  11 First of all, use ":make tags" to generate a tags file, so that you can use
  12 the ":tag" command to jump around the source code.
  13
  14 To jump to a function or variable definition, move the cursor on the name and
  15 use the CTRL-] command.  Use CTRL-T or CTRL-O to jump back.
  16
  17 To jump to a file, move the cursor on its name and use the "gf" command.
  18
  19 Most code can be found in a file with an obvious name (incomplete list):
  20         buffer.c        manipulating buffers (loaded files)
  21         diff.c          diff mode (vimdiff)
  22         eval.c          expression evaluation
  23         fileio.c        reading and writing files
  24         fold.c          folding
  25         getchar.c       getting characters and key mapping
  26         mark.c          marks
  27         mbyte.c         multy-byte character handling
  28         memfile.c       storing lines for buffers in a swapfile
  29         memline.c       storing lines for buffers in memory
  30         menu.c          menus
  31         message.c       (error) messages
  32         ops.c           handling operators ("d", "y", "p")
  33         option.c        options
  34         quickfix.c      quickfix commands (":make", ":cn")
  35         regexp.c        pattern matching
  36         screen.c        updating the windows
  37         search.c        pattern searching
  38         spell.c         spell checking
  39         syntax.c        syntax and other highlighting
  40         tag.c           tags
  41         term.c          terminal handling, termcap codes
  42         undo.c          undo and redo
  43         window.c        handling split windows
  44
  45
  46 IMPORTANT VARIABLES
  47
  48 The current mode is stored in "State".  The values it can have are NORMAL,
  49 INSERT, CMDLINE, and a few others.
  50
  51 The current window is "curwin".  The current buffer is "curbuf".  These point
  52 to structures with the cursor position in the window, option values, the file
  53 name, etc.  These are defined in structs.h.
  54
  55 All the global variables are declared in globals.h.
  56
  57
  58 THE MAIN LOOP
  59
  60 This is conveniently called main_loop().  It updates a few things and then
  61 calls normal_cmd() to process a command.  This returns when the command is
  62 finished.
  63
  64 The basic idea is that Vim waits for the user to type a character and
  65 processes it until another character is needed.  Thus there are several places
  66 where Vim waits for a character to be typed.  The vgetc() function is used for
  67 this.  It also handles mapping.
  68
  69 Updating the screen is mostly postponed until a command or a sequence of
  70 commands has finished.  The work is done by update_screen(), which calls
  71 win_update() for every window, which calls win_line() for every line.
  72 See the start of screen.c for more explanations.
  73
  74
  75 COMMAND-LINE MODE
  76
  77 When typing a ":", normal_cmd() will call getcmdline() to obtain a line with
  78 an Ex command.  getcmdline() contains a loop that will handle each typed
  79 character.  It returns when hitting <CR> or <Esc> or some other character that
  80 ends the command line mode.
  81
  82
  83 EX COMMANDS
  84
  85 Ex commands are handled by the function do_cmdline().  It does the generic
  86 parsing of the ":" command line and calls do_one_cmd() for each separate
  87 command.  It also takes care of while loops.
  88
  89 do_one_cmd() parses the range and generic arguments and puts them in the
  90 exarg_t and passes it to the function that handles the command.
  91
  92 The ":" commands are listed in ex_cmds.h.  The third entry of each item is the
  93 name of the function that handles the command.  The last entry are the flags
  94 that are used for the command.
  95
  96
  97 NORMAL MODE COMMANDS
  98
  99 The Normal mode commands are handled by the normal_cmd() function.  It also
 100 handles the optional count and an extra character for some commands.  These
 101 are passed in a cmdarg_t to the function that handles the command.
 102
 103 There is a table nv_cmds in normal.c which lists the first character of every
 104 command.  The second entry of each item is the name of the function that
 105 handles the command.
 106
 107
 108 INSERT MODE COMMANDS
 109
 110 When doing an "i" or "a" command, normal_cmd() will call the edit() function.
 111 It contains a loop that waits for the next character and handles it.  It
 112 returns when leaving Insert mode.
 113
 114
 115 OPTIONS
 116
 117 There is a list with all option names in option.c, called options[].
 118
 119
 120 THE GUI
 121
 122 Most of the GUI code is implemented like it was a clever terminal.  Typing a
 123 character, moving a scrollbar, clicking the mouse, etc. are all translated
 124 into events which are written in the input buffer.  These are read by the
 125 main code, just like reading from a terminal.  The code for this is scattered
 126 through gui.c.  For example: gui_send_mouse_event() for a mouse click and
 127 gui_menu_cb() for a menu action.  Key hits are handled by the system-specific
 128 GUI code, which calls add_to_input_buf() to send the key code.
 129
 130 Updating the GUI window is done by writing codes in the output buffer, just
 131 like writing to a terminal.  When the buffer gets full or is flushed,
 132 gui_write() will parse the codes and draw the appropriate items.  Finally the
 133 system-specific GUI code will be called to do the work.
 134
 135
 136 DEBUGGING THE GUI
 137
 138 Remember to prevent that gvim forks and the debugger thinks Vim has exited,
 139 add the "-f" argument.  In gdb: "run -f -g".
 140
 141 When stepping through display updating code, the focus event is triggered
 142 when going from the debugger to Vim and back.  To avoid this, recompile with
 143 some code in gui_focus_change() disabled.