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