From 071d4279d6ab81b7187b48f3a0fc61e587b6db6c Mon Sep 17 00:00:00 2001 From: Bram Moolenaar Date: Sun, 13 Jun 2004 20:20:40 +0000 Subject: updated for version 7.0001 --- src/README.txt | 140 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 140 insertions(+) create mode 100644 src/README.txt (limited to 'src/README.txt') diff --git a/src/README.txt b/src/README.txt new file mode 100644 index 000000000..05b864fa7 --- /dev/null +++ b/src/README.txt @@ -0,0 +1,140 @@ +README for the Vim source code + +Here are a few hints for finding your way around the source code. This +doesn't make it less complex than it is, but it gets you started. + +You might also want to read ":help development". + + +JUMPING AROUND + +First of all, use ":make tags" to generate a tags file, so that you can use +the ":tag" command to jump around the source code. + +To jump to a function or variable definition, move the cursor on the name and +use the CTRL-] command. Use CTRL-T or CTRL-O to jump back. + +To jump to a file, move the cursor on its name and use the "gf" command. + +Most code can be found in a file with an obvious name (incomplete list): + buffer.c manipulating buffers (loaded files) + diff.c diff mode (vimdiff) + eval.c expression evaluation + fileio.c reading and writing files + fold.c folding + getchar.c getting characters and key mapping + mark.c marks + memfile.c storing lines for buffers in a swapfile + memline.c storing lines for buffers in memory + menu.c menus + message.c (error) messages + mbyte.c multy-byte character handling + ops.c handling operators ("d", "y", "p") + option.c options + quickfix.c quickfix commands (":make", ":cn") + screen.c updating the windows + search.c pattern searching + tag.c tags + term.c terminal handling, termcap codes + undo.c undo and redo + window.c handling split windows + + +IMPORTANT VARIABLES + +The current mode is stored in "State". The values it can have are NORMAL, +INSERT, CMDLINE, and a few others. + +The current window is "curwin". The current buffer is "curbuf". These point +to structures with the cursor position in the window, option values, the file +name, etc. These are defined in structs.h. + +All the global variables are declared in globals.h. + + +THE MAIN LOOP + +This is conveniently called main_loop(). It updates a few things and then +calls normal_cmd() to process a command. This returns when the command is +finished. + +The basic idea is that Vim waits for the user to type a character and +processes it until another character is needed. Thus there are several places +where Vim waits for a character to be typed. The vgetc() function is used for +this. It also handles mapping. + +Updating the screen is mostly postponed until a command or a sequence of +commands has finished. The work is done by update_screen(), which calls +win_update() for every window, which calls win_line() for every line. +See the start of screen.c for more explanations. + + +COMMAND-LINE MODE + +When typing a ":", normal_cmd() will call getcmdline() to obtain a line with +an Ex command. getcmdline() contains a loop that will handle each typed +character. It returns when hitting or or some other character that +ends the command line mode. + + +EX COMMANDS + +Ex commands are handled by the function do_cmdline(). It does the generic +parsing of the ":" command line and calls do_one_cmd() for each separate +command. It also takes care of while loops. + +do_one_cmd() parses the range and generic arguments and puts them in the +exarg_t and passes it to the function that handles the command. + +The ":" commands are listed in ex_cmds.h. The third entry of each item is the +name of the function that handles the command. The last entry are the flags +that are used for the command. + + +NORMAL MODE COMMANDS + +The Normal mode commands are handled by the normal_cmd() function. It also +handles the optional count and an extra character for some commands. These +are passed in a cmdarg_t to the function that handles the command. + +There is a table nv_cmds in normal.c which lists the first character of every +command. The second entry of each item is the name of the function that +handles the command. + + +INSERT MODE COMMANDS + +When doing an "i" or "a" command, normal_cmd() will call the edit() function. +It contains a loop that waits for the next character and handles it. It +returns when leaving Insert mode. + + +OPTIONS + +There is a list with all option names in option.c, called options[]. + + +THE GUI + +Most of the GUI code is implemented like it was a clever terminal. Typing a +character, moving a scrollbar, clicking the mouse, etc. are all translated +into events which are written in the input buffer. These are read by the +main code, just like reading from a terminal. The code for this is scattered +through gui.c. For example: gui_send_mouse_event() for a mouse click and +gui_menu_cb() for a menu action. Key hits are handled by the system-specific +GUI code, which calls add_to_input_buf() to send the key code. + +Updating the GUI window is done by writing codes in the output buffer, just +like writing to a terminal. When the buffer gets full or is flushed, +gui_write() will parse the codes and draw the appropriate items. Finally the +system-specific GUI code will be called to do the work. + + +DEBUGGING THE GUI + +Remember to prevent that gvim forks and the debugger thinks Vim has exited, +add the "-f" argument. In gdb: "run -f -g". + +When stepping through display updating code, the focus event is triggerred +when going from the debugger to Vim and back. To avoid this, recompile with +some code in gui_focus_change() disabled. -- cgit v1.2.1