Mercurial > vim
annotate src/README.txt @ 14384:6f01954c86e5
Added tag v8.1.0206 for changeset 8846b83444309722d72d62961e6eebe4df5846f2
| author | Christian Brabandt <cb@256bit.org> |
|---|---|
| date | Mon, 23 Jul 2018 05:00:06 +0200 |
| parents | 8412df1479a3 |
| children | a6330a49e036 |
| rev | line source |
|---|---|
| 7 | 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 | |
|
13353
8412df1479a3
patch 8.0.1550: various small problems in source files
Christian Brabandt <cb@256bit.org>
parents:
2577
diff
changeset
|
11 First of all, use ":make tags" to generate a tags file, so that you can jump |
|
8412df1479a3
patch 8.0.1550: various small problems in source files
Christian Brabandt <cb@256bit.org>
parents:
2577
diff
changeset
|
12 around in the source code. |
| 7 | 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 | |
|
2577
073ff46fe397
Fold Vim 7.2 default branch back to trunk to avoid two heads. (Tony
Bram Moolenaar <bram@vim.org>
parents:
2165
diff
changeset
|
27 mbyte.c multi-byte character handling |
| 7 | 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") | |
| 372 | 35 regexp.c pattern matching |
| 7 | 36 screen.c updating the windows |
| 37 search.c pattern searching | |
| 372 | 38 spell.c spell checking |
| 39 syntax.c syntax and other highlighting | |
| 7 | 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 | |
|
13353
8412df1479a3
patch 8.0.1550: various small problems in source files
Christian Brabandt <cb@256bit.org>
parents:
2577
diff
changeset
|
46 DEBUGGING |
|
8412df1479a3
patch 8.0.1550: various small problems in source files
Christian Brabandt <cb@256bit.org>
parents:
2577
diff
changeset
|
47 |
|
8412df1479a3
patch 8.0.1550: various small problems in source files
Christian Brabandt <cb@256bit.org>
parents:
2577
diff
changeset
|
48 If you have a reasonable recent version of gdb, you can use the :Termdebug |
|
8412df1479a3
patch 8.0.1550: various small problems in source files
Christian Brabandt <cb@256bit.org>
parents:
2577
diff
changeset
|
49 command to debug Vim. See ":help :Termdebug". |
|
8412df1479a3
patch 8.0.1550: various small problems in source files
Christian Brabandt <cb@256bit.org>
parents:
2577
diff
changeset
|
50 |
|
8412df1479a3
patch 8.0.1550: various small problems in source files
Christian Brabandt <cb@256bit.org>
parents:
2577
diff
changeset
|
51 When something is time critical or stepping through code is a hassle, use the |
|
8412df1479a3
patch 8.0.1550: various small problems in source files
Christian Brabandt <cb@256bit.org>
parents:
2577
diff
changeset
|
52 channel logging to create a time-stamped log file. Add lines to the code like |
|
8412df1479a3
patch 8.0.1550: various small problems in source files
Christian Brabandt <cb@256bit.org>
parents:
2577
diff
changeset
|
53 this: |
|
8412df1479a3
patch 8.0.1550: various small problems in source files
Christian Brabandt <cb@256bit.org>
parents:
2577
diff
changeset
|
54 ch_log(NULL, "Value is now %02x", value); |
|
8412df1479a3
patch 8.0.1550: various small problems in source files
Christian Brabandt <cb@256bit.org>
parents:
2577
diff
changeset
|
55 After compiling and starting Vim, do: |
|
8412df1479a3
patch 8.0.1550: various small problems in source files
Christian Brabandt <cb@256bit.org>
parents:
2577
diff
changeset
|
56 :call ch_logfile('debuglog', 'w') |
|
8412df1479a3
patch 8.0.1550: various small problems in source files
Christian Brabandt <cb@256bit.org>
parents:
2577
diff
changeset
|
57 And edit "debuglog" to see what happens. The channel functions already have |
|
8412df1479a3
patch 8.0.1550: various small problems in source files
Christian Brabandt <cb@256bit.org>
parents:
2577
diff
changeset
|
58 ch_log() calls, thus you always see that in the log. |
|
8412df1479a3
patch 8.0.1550: various small problems in source files
Christian Brabandt <cb@256bit.org>
parents:
2577
diff
changeset
|
59 |
|
8412df1479a3
patch 8.0.1550: various small problems in source files
Christian Brabandt <cb@256bit.org>
parents:
2577
diff
changeset
|
60 |
| 7 | 61 IMPORTANT VARIABLES |
| 62 | |
| 63 The current mode is stored in "State". The values it can have are NORMAL, | |
| 64 INSERT, CMDLINE, and a few others. | |
| 65 | |
| 66 The current window is "curwin". The current buffer is "curbuf". These point | |
| 67 to structures with the cursor position in the window, option values, the file | |
| 68 name, etc. These are defined in structs.h. | |
| 69 | |
| 70 All the global variables are declared in globals.h. | |
| 71 | |
| 72 | |
| 73 THE MAIN LOOP | |
| 74 | |
| 75 This is conveniently called main_loop(). It updates a few things and then | |
| 76 calls normal_cmd() to process a command. This returns when the command is | |
| 77 finished. | |
| 78 | |
| 79 The basic idea is that Vim waits for the user to type a character and | |
| 80 processes it until another character is needed. Thus there are several places | |
| 81 where Vim waits for a character to be typed. The vgetc() function is used for | |
| 82 this. It also handles mapping. | |
| 83 | |
| 84 Updating the screen is mostly postponed until a command or a sequence of | |
| 85 commands has finished. The work is done by update_screen(), which calls | |
| 86 win_update() for every window, which calls win_line() for every line. | |
| 87 See the start of screen.c for more explanations. | |
| 88 | |
| 89 | |
| 90 COMMAND-LINE MODE | |
| 91 | |
| 92 When typing a ":", normal_cmd() will call getcmdline() to obtain a line with | |
| 93 an Ex command. getcmdline() contains a loop that will handle each typed | |
| 94 character. It returns when hitting <CR> or <Esc> or some other character that | |
| 95 ends the command line mode. | |
| 96 | |
| 97 | |
| 98 EX COMMANDS | |
| 99 | |
| 100 Ex commands are handled by the function do_cmdline(). It does the generic | |
| 101 parsing of the ":" command line and calls do_one_cmd() for each separate | |
| 102 command. It also takes care of while loops. | |
| 103 | |
| 104 do_one_cmd() parses the range and generic arguments and puts them in the | |
| 105 exarg_t and passes it to the function that handles the command. | |
| 106 | |
| 107 The ":" commands are listed in ex_cmds.h. The third entry of each item is the | |
| 108 name of the function that handles the command. The last entry are the flags | |
| 109 that are used for the command. | |
| 110 | |
| 111 | |
| 112 NORMAL MODE COMMANDS | |
| 113 | |
| 114 The Normal mode commands are handled by the normal_cmd() function. It also | |
| 115 handles the optional count and an extra character for some commands. These | |
| 116 are passed in a cmdarg_t to the function that handles the command. | |
| 117 | |
| 118 There is a table nv_cmds in normal.c which lists the first character of every | |
| 119 command. The second entry of each item is the name of the function that | |
| 120 handles the command. | |
| 121 | |
| 122 | |
| 123 INSERT MODE COMMANDS | |
| 124 | |
| 125 When doing an "i" or "a" command, normal_cmd() will call the edit() function. | |
| 126 It contains a loop that waits for the next character and handles it. It | |
| 127 returns when leaving Insert mode. | |
| 128 | |
| 129 | |
| 130 OPTIONS | |
| 131 | |
| 132 There is a list with all option names in option.c, called options[]. | |
| 133 | |
| 134 | |
| 135 THE GUI | |
| 136 | |
| 137 Most of the GUI code is implemented like it was a clever terminal. Typing a | |
| 138 character, moving a scrollbar, clicking the mouse, etc. are all translated | |
| 139 into events which are written in the input buffer. These are read by the | |
| 140 main code, just like reading from a terminal. The code for this is scattered | |
| 141 through gui.c. For example: gui_send_mouse_event() for a mouse click and | |
| 142 gui_menu_cb() for a menu action. Key hits are handled by the system-specific | |
| 143 GUI code, which calls add_to_input_buf() to send the key code. | |
| 144 | |
| 145 Updating the GUI window is done by writing codes in the output buffer, just | |
| 146 like writing to a terminal. When the buffer gets full or is flushed, | |
| 147 gui_write() will parse the codes and draw the appropriate items. Finally the | |
| 148 system-specific GUI code will be called to do the work. | |
| 149 | |
| 150 | |
| 151 DEBUGGING THE GUI | |
| 152 | |
| 153 Remember to prevent that gvim forks and the debugger thinks Vim has exited, | |
| 154 add the "-f" argument. In gdb: "run -f -g". | |
| 155 | |
| 1197 | 156 When stepping through display updating code, the focus event is triggered |
| 7 | 157 when going from the debugger to Vim and back. To avoid this, recompile with |
| 158 some code in gui_focus_change() disabled. |