Mercurial > vim

comparison src/README.md @ 16129:52ae47071830 v8.1.1069

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
patch 8.1.1069: source README file doesn't look nice on github commit https://github.com/vim/vim/commit/8ac8a77f24098b58316bbfdf2f6c2c3f7f2b35c2 Author: Bram Moolenaar <Bram@vim.org> Date: Fri Mar 29 13:10:08 2019 +0100 patch 8.1.1069: source README file doesn't look nice on github Problem: Source README file doesn't look nice on github. Solution: Turn it into markdown, still readable as plain text. (WenxuanHuang, closes #4141)
author Bram Moolenaar <Bram@vim.org>
date Fri, 29 Mar 2019 13:15:05 +0100
parents
children e12336bb8ced
comparison
equal deleted inserted replaced
16128:ae53fd4cbc59 16129:52ae47071830
1 ![Vim Logo](https://github.com/vim/vim/blob/master/runtime/vimlogo.gif)
2
3 # Vim source code #
4
5 Here are a few hints for finding your way around the source code. This
6 doesn't make it less complex than it is, but it gets you started.
7
8 You might also want to read
9 [`:help development`](http://vimdoc.sourceforge.net/htmldoc/develop.html#development).
10
11
12 ## Jumping around ##
13
14 First of all, use `:make tags` to generate a tags file, so that you can jump
15 around in the source code.
16
17 To jump to a function or variable definition, move the cursor on the name and
18 use the `CTRL-]` command. Use `CTRL-T` or `CTRL-O` to jump back.
19
20 To jump to a file, move the cursor on its name and use the `gf` command.
21
22 Most code can be found in a file with an obvious name (incomplete list):
23
24 File name | Description
25 --------- | -----------
26 autocmd.c | autocommands
27 buffer.c | manipulating buffers (loaded files)
28 diff.c | diff mode (vimdiff)
29 eval.c | expression evaluation
30 fileio.c | reading and writing files
31 findfile.c | search for files in 'path'
32 fold.c | folding
33 getchar.c | getting characters and key mapping
34 indent.c | C and Lisp indentation
35 mark.c | marks
36 mbyte.c | multi-byte character handling
37 memfile.c | storing lines for buffers in a swapfile
38 memline.c | storing lines for buffers in memory
39 menu.c | menus
40 message.c | (error) messages
41 ops.c | handling operators ("d", "y", "p")
42 option.c | options
43 quickfix.c | quickfix commands (":make", ":cn")
44 regexp.c | pattern matching
45 screen.c | updating the windows
46 search.c | pattern searching
47 sign.c | signs
48 spell.c | spell checking
49 syntax.c | syntax and other highlighting
50 tag.c | tags
51 term.c | terminal handling, termcap codes
52 undo.c | undo and redo
53 window.c | handling split windows
54
55
56 ## Debugging ##
57
58 If you have a reasonable recent version of gdb, you can use the `:Termdebug`
59 command to debug Vim. See `:help :Termdebug`.
60
61 When something is time critical or stepping through code is a hassle, use the
62 channel logging to create a time-stamped log file. Add lines to the code like
63 this:
64
65 ch_log(NULL, "Value is now %02x", value);
66
67 After compiling and starting Vim, do:
68
69 :call ch_logfile('debuglog', 'w')
70
71 And edit `debuglog` to see what happens. The channel functions already have
72 `ch_log()` calls, thus you always see that in the log.
73
74
75 ## Important Variables ##
76
77 The current mode is stored in `State`. The values it can have are `NORMAL`,
78 `INSERT`, `CMDLINE`, and a few others.
79
80 The current window is `curwin`. The current buffer is `curbuf`. These point
81 to structures with the cursor position in the window, option values, the file
82 name, etc. These are defined in
83 [`structs.h`](https://github.com/vim/vim/blob/master/src/globals.h).
84
85 All the global variables are declared in
86 [`globals.h`](https://github.com/vim/vim/blob/master/src/structs.h).
87
88
89 ## The main loop ##
90
91 This is conveniently called `main_loop()`. It updates a few things and then
92 calls `normal_cmd()` to process a command. This returns when the command is
93 finished.
94
95 The basic idea is that Vim waits for the user to type a character and
96 processes it until another character is needed. Thus there are several places
97 where Vim waits for a character to be typed. The `vgetc()` function is used
98 for this. It also handles mapping.
99
100 Updating the screen is mostly postponed until a command or a sequence of
101 commands has finished. The work is done by `update_screen()`, which calls
102 `win_update()` for every window, which calls `win_line()` for every line.
103 See the start of
104 [`screen.c`](https://github.com/vim/vim/blob/master/src/screen.c)
105 for more explanations.
106
107
108 ## Command-line mode ##
109
110 When typing a `:`, `normal_cmd()` will call `getcmdline()` to obtain a line
111 with an Ex command. `getcmdline()` contains a loop that will handle each typed
112 character. It returns when hitting `CR` or `Esc` or some other character that
113 ends the command line mode.
114
115
116 ## Ex commands ##
117
118 Ex commands are handled by the function `do_cmdline()`. It does the generic
119 parsing of the `:` command line and calls `do_one_cmd()` for each separate
120 command. It also takes care of while loops.
121
122 `do_one_cmd()` parses the range and generic arguments and puts them in the
123 `exarg_t` and passes it to the function that handles the command.
124
125 The `:` commands are listed in `ex_cmds.h`. The third entry of each item is
126 the name of the function that handles the command. The last entry are the
127 flags that are used for the command.
128
129
130 ## Normal mode commands ##
131
132 The Normal mode commands are handled by the `normal_cmd()` function. It also
133 handles the optional count and an extra character for some commands. These
134 are passed in a `cmdarg_t` to the function that handles the command.
135
136 There is a table `nv_cmds` in
137 [`normal.c`](https://github.com/vim/vim/blob/master/src/normal.c)
138 which lists the first character of every command. The second entry of each
139 item is the name of the function that handles the command.
140
141
142 ## Insert mode commands ##
143
144 When doing an `i` or `a` command, `normal_cmd()` will call the `edit()`
145 function. It contains a loop that waits for the next character and handles it.
146 It returns when leaving Insert mode.
147
148
149 ## Options ##
150
151 There is a list with all option names in
152 [`option.c`](https://github.com/vim/vim/blob/master/src/option.c),
153 called `options[]`.
154
155
156 ## The GUI ##
157
158 Most of the GUI code is implemented like it was a clever terminal. Typing a
159 character, moving a scrollbar, clicking the mouse, etc. are all translated
160 into events which are written in the input buffer. These are read by the
161 main code, just like reading from a terminal. The code for this is scattered
162 through [`gui.c`](https://github.com/vim/vim/blob/master/src/gui.c).
163 For example, `gui_send_mouse_event()` for a mouse click and `gui_menu_cb()` for
164 a menu action. Key hits are handled by the system-specific GUI code, which
165 calls `add_to_input_buf()` to send the key code.
166
167 Updating the GUI window is done by writing codes in the output buffer, just
168 like writing to a terminal. When the buffer gets full or is flushed,
169 `gui_write()` will parse the codes and draw the appropriate items. Finally the
170 system-specific GUI code will be called to do the work.
171
172
173 ## Debugging the GUI ##
174
175 Remember to prevent that gvim forks and the debugger thinks Vim has exited,
176 add the `-f` argument. In gdb: `run -f -g`.
177
178 When stepping through display updating code, the focus event is triggered
179 when going from the debugger to Vim and back. To avoid this, recompile with
180 some code in `gui_focus_change()` disabled.
181
182
183 ## Contributing ##
184
185 If you would like to help making Vim better, see the
186 [`CONTRIBUTING.md`](https://github.com/vim/vim/blob/master/CONTRIBUTING.md)
187 file.
188
189
190 This is `README.md` for version 8.1 of the Vim source code.