annotate src/README.md @ 34057:4635e43f2c6f v9.1.0 v9.1.0000

patch 9.1.0000: Vim 9.1 release Commit: https://github.com/vim/vim/commit/b4ddc6c11e95cef4b372e239871fae1c8d4f72b6 Author: Christian Brabandt <cb@256bit.org> Date: Tue Jan 2 16:51:11 2024 +0100 patch 9.1.0000: Vim 9.1 release Problem: Need a new release Solution: Release Vim 9.1 Signed-off-by: Christian Brabandt <cb@256bit.org>
author Christian Brabandt <cb@256bit.org>
date Tue, 02 Jan 2024 18:45:09 +0100
parents f8116058ca76
children 500731fe8161
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
16129
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
1 ![Vim Logo](https://github.com/vim/vim/blob/master/runtime/vimlogo.gif)
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
2
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
3 # Vim source code #
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
4
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
5 Here are a few hints for finding your way around the source code. This
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
6 doesn't make it less complex than it is, but it gets you started.
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
7
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
8 You might also want to read
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
9 [`:help development`](http://vimdoc.sourceforge.net/htmldoc/develop.html#development).
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
10
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
11
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
12 ## Jumping around ##
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
13
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
14 First of all, use `:make tags` to generate a tags file, so that you can jump
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
15 around in the source code.
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
16
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
17 To jump to a function or variable definition, move the cursor on the name and
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
18 use the `CTRL-]` command. Use `CTRL-T` or `CTRL-O` to jump back.
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
19
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
20 To jump to a file, move the cursor on its name and use the `gf` command.
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
21
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
22 Most code can be found in a file with an obvious name (incomplete list):
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
23
17377
cb008de2a6ec patch 8.1.1687: the evalfunc.c file is too big
Bram Moolenaar <Bram@vim.org>
parents: 17370
diff changeset
24 File name | Description
cb008de2a6ec patch 8.1.1687: the evalfunc.c file is too big
Bram Moolenaar <Bram@vim.org>
parents: 17370
diff changeset
25 --------------- | -----------
25529
bb1097899693 patch 8.2.3301: memory allocation functions don't have their own place
Bram Moolenaar <Bram@vim.org>
parents: 25206
diff changeset
26 alloc.c | memory management
17744
4a3dca734d36 patch 8.1.1869: code for the argument list is spread out
Bram Moolenaar <Bram@vim.org>
parents: 17652
diff changeset
27 arglist.c | handling argument list
16129
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
28 autocmd.c | autocommands
17652
9efb4dda9720 patch 8.1.1823: command line history code is spread out
Bram Moolenaar <Bram@vim.org>
parents: 17576
diff changeset
29 blob.c | blob data type
16129
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
30 buffer.c | manipulating buffers (loaded files)
18199
e2be5a6485f5 patch 8.1.2094: the fileio.c file is too big
Bram Moolenaar <Bram@vim.org>
parents: 18174
diff changeset
31 bufwrite.c | writing a buffer to file
16632
30de89c1d090 patch 8.1.1318: code for text changes is in a "misc" file
Bram Moolenaar <Bram@vim.org>
parents: 16411
diff changeset
32 change.c | handling changes to text
18265
fe5afdc03bd2 patch 8.1.2127: the indent.c file is a bit big
Bram Moolenaar <Bram@vim.org>
parents: 18199
diff changeset
33 cindent.c | C and Lisp indentation
19920
5e41b2e63c73 patch 8.2.0516: client-server code is spread out
Bram Moolenaar <Bram@vim.org>
parents: 19774
diff changeset
34 clientserver.c | client server functionality
19774
00a1b89256ea patch 8.2.0443: clipboard code is spread out
Bram Moolenaar <Bram@vim.org>
parents: 19396
diff changeset
35 clipboard.c | handling the clipboard
17779
87a8760babec patch 8.1.1886: command line expansion code is spread out
Bram Moolenaar <Bram@vim.org>
parents: 17744
diff changeset
36 cmdexpand.c | command-line completion
17652
9efb4dda9720 patch 8.1.1823: command line history code is spread out
Bram Moolenaar <Bram@vim.org>
parents: 17576
diff changeset
37 cmdhist.c | command-line history
16391
3fc956fc63b6 patch 8.1.1200: old style comments in debugger source
Bram Moolenaar <Bram@vim.org>
parents: 16186
diff changeset
38 debugger.c | vim script debugger
16129
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
39 diff.c | diff mode (vimdiff)
18124
2a806e3c39f6 patch 8.1.2057: the screen.c file is much too big
Bram Moolenaar <Bram@vim.org>
parents: 18100
diff changeset
40 drawline.c | drawing a window line
2a806e3c39f6 patch 8.1.2057: the screen.c file is much too big
Bram Moolenaar <Bram@vim.org>
parents: 18100
diff changeset
41 drawscreen.c | drawing the windows
16129
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
42 eval.c | expression evaluation
18010
cf8e0c7e0cb9 patch 8.1.2001: some source files are too big
Bram Moolenaar <Bram@vim.org>
parents: 17966
diff changeset
43 evalbuffer.c | buffer related built-in functions
16411
5b5c5daf57de patch 8.1.1210: support for user commands is spread out
Bram Moolenaar <Bram@vim.org>
parents: 16407
diff changeset
44 evalfunc.c | built-in functions
17873
d50a5faa75bd patch 8.1.1933: the eval.c file is too big
Bram Moolenaar <Bram@vim.org>
parents: 17861
diff changeset
45 evalvars.c | vim variables
18010
cf8e0c7e0cb9 patch 8.1.2001: some source files are too big
Bram Moolenaar <Bram@vim.org>
parents: 17966
diff changeset
46 evalwindow.c | window related built-in functions
16129
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
47 fileio.c | reading and writing files
17966
46f95606b9ec patch 8.1.1979: code for handling file names is spread out
Bram Moolenaar <Bram@vim.org>
parents: 17873
diff changeset
48 filepath.c | dealing with file names and paths
16129
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
49 findfile.c | search for files in 'path'
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
50 fold.c | folding
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
51 getchar.c | getting characters and key mapping
21423
5db63c2c6929 patch 8.2.1262: src/ex_cmds.c file is too big
Bram Moolenaar <Bram@vim.org>
parents: 21054
diff changeset
52 help.c | vim help related functions
17389
635d7f5010b8 patch 8.1.1693: syntax coloring and highlighting is in one big file
Bram Moolenaar <Bram@vim.org>
parents: 17377
diff changeset
53 highlight.c | syntax highlighting
18265
fe5afdc03bd2 patch 8.1.2127: the indent.c file is a bit big
Bram Moolenaar <Bram@vim.org>
parents: 18199
diff changeset
54 indent.c | text indentation
16186
e12336bb8ced patch 8.1.1098: quickfix code duplication
Bram Moolenaar <Bram@vim.org>
parents: 16129
diff changeset
55 insexpand.c | Insert mode completion
21437
b32b67a108f2 patch 8.2.1269: language and locale code spread out
Bram Moolenaar <Bram@vim.org>
parents: 21423
diff changeset
56 locale.c | locale/language handling
21054
b1fac55cf8a3 patch 8.2.1078: highlight and match functionality together in one file
Bram Moolenaar <Bram@vim.org>
parents: 20587
diff changeset
57 map.c | mapping and abbreviations
16129
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
58 mark.c | marks
21054
b1fac55cf8a3 patch 8.2.1078: highlight and match functionality together in one file
Bram Moolenaar <Bram@vim.org>
parents: 20587
diff changeset
59 match.c | highlight matching
24780
7bc92a651472 patch 8.2.2928: the evalfunc.c file is too big
Bram Moolenaar <Bram@vim.org>
parents: 21437
diff changeset
60 float.c | floating point functions
16129
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
61 mbyte.c | multi-byte character handling
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
62 memfile.c | storing lines for buffers in a swapfile
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
63 memline.c | storing lines for buffers in memory
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
64 menu.c | menus
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
65 message.c | (error) messages
18135
1868ec23360e patch 8.1.2062: the mouse code is spread out
Bram Moolenaar <Bram@vim.org>
parents: 18124
diff changeset
66 mouse.c | handling the mouse
16411
5b5c5daf57de patch 8.1.1210: support for user commands is spread out
Bram Moolenaar <Bram@vim.org>
parents: 16407
diff changeset
67 ops.c | handling operators ("d", "y", "p")
16129
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
68 option.c | options
18100
df5778d73320 patch 8.1.2045: the option.c file is too big
Bram Moolenaar <Bram@vim.org>
parents: 18010
diff changeset
69 optionstr.c | handling string options
18174
1ec6539cef68 patch 8.1.2082: some files have a weird name to fit in 8.3 characters
Bram Moolenaar <Bram@vim.org>
parents: 18172
diff changeset
70 popupmenu.c | popup menu
17377
cb008de2a6ec patch 8.1.1687: the evalfunc.c file is too big
Bram Moolenaar <Bram@vim.org>
parents: 17370
diff changeset
71 popupwin.c | popup window
17370
ba06a1c42274 patch 8.1.1684: profiling functionality is spread out
Bram Moolenaar <Bram@vim.org>
parents: 16632
diff changeset
72 profiler.c | vim script profiler
16129
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
73 quickfix.c | quickfix commands (":make", ":cn")
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
74 regexp.c | pattern matching
18164
f57481564f2c patch 8.1.2077: the ops.c file is too big
Bram Moolenaar <Bram@vim.org>
parents: 18135
diff changeset
75 register.c | handling registers
17861
0a5c615cd949 patch 8.1.1927: code for dealing with script files is spread out
Bram Moolenaar <Bram@vim.org>
parents: 17779
diff changeset
76 scriptfile.c | runtime directory handling and sourcing scripts
18135
1868ec23360e patch 8.1.2062: the mouse code is spread out
Bram Moolenaar <Bram@vim.org>
parents: 18124
diff changeset
77 screen.c | lower level screen functions
16129
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
78 search.c | pattern searching
17536
e00d12c085a5 patch 8.1.1766: code for writing session file is spread out
Bram Moolenaar <Bram@vim.org>
parents: 17464
diff changeset
79 session.c | sessions and views
16129
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
80 sign.c | signs
18172
6e53d83e021d patch 8.1.2081: the spell.c file is too big
Bram Moolenaar <Bram@vim.org>
parents: 18164
diff changeset
81 spell.c | spell checking core
6e53d83e021d patch 8.1.2081: the spell.c file is too big
Bram Moolenaar <Bram@vim.org>
parents: 18164
diff changeset
82 spellfile.c | spell file handling
6e53d83e021d patch 8.1.2081: the spell.c file is too big
Bram Moolenaar <Bram@vim.org>
parents: 18164
diff changeset
83 spellsuggest.c | spell correction suggestions
25206
dc66d0284518 patch 8.2.3139: functions for string manipulation are spread out
Bram Moolenaar <Bram@vim.org>
parents: 24780
diff changeset
84 strings.c | string manipulation functions
17370
ba06a1c42274 patch 8.1.1684: profiling functionality is spread out
Bram Moolenaar <Bram@vim.org>
parents: 16632
diff changeset
85 syntax.c | syntax and other highlighting
16411
5b5c5daf57de patch 8.1.1210: support for user commands is spread out
Bram Moolenaar <Bram@vim.org>
parents: 16407
diff changeset
86 tag.c | tags
16129
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
87 term.c | terminal handling, termcap codes
17377
cb008de2a6ec patch 8.1.1687: the evalfunc.c file is too big
Bram Moolenaar <Bram@vim.org>
parents: 17370
diff changeset
88 testing.c | testing: assert and test functions
20237
918245588b50 patch 8.2.0674: some source files are too big
Bram Moolenaar <Bram@vim.org>
parents: 20209
diff changeset
89 textformat.c | text formatting
20209
6ca6a372fef6 patch 8.2.0660: the search.c file is a bit big
Bram Moolenaar <Bram@vim.org>
parents: 19920
diff changeset
90 textobject.c | text objects
17377
cb008de2a6ec patch 8.1.1687: the evalfunc.c file is too big
Bram Moolenaar <Bram@vim.org>
parents: 17370
diff changeset
91 textprop.c | text properties
19396
a961efb326e5 patch 8.2.0256: time and timer related code is spread out
Bram Moolenaar <Bram@vim.org>
parents: 18879
diff changeset
92 time.c | time and timer functions
20587
f502455965c0 patch 8.2.0847: typval related code is spread out
Bram Moolenaar <Bram@vim.org>
parents: 20237
diff changeset
93 typval.c | vim script type/value functions
16129
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
94 undo.c | undo and redo
16411
5b5c5daf57de patch 8.1.1210: support for user commands is spread out
Bram Moolenaar <Bram@vim.org>
parents: 16407
diff changeset
95 usercmd.c | user defined commands
5b5c5daf57de patch 8.1.1210: support for user commands is spread out
Bram Moolenaar <Bram@vim.org>
parents: 16407
diff changeset
96 userfunc.c | user defined functions
17464
3e708b5c0509 patch 8.1.1730: wrong place for mark viminfo support
Bram Moolenaar <Bram@vim.org>
parents: 17389
diff changeset
97 viminfo.c | viminfo handling
16129
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
98 window.c | handling split windows
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
99
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
100
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
101 ## Debugging ##
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
102
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
103 If you have a reasonable recent version of gdb, you can use the `:Termdebug`
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
104 command to debug Vim. See `:help :Termdebug`.
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
105
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
106 When something is time critical or stepping through code is a hassle, use the
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
107 channel logging to create a time-stamped log file. Add lines to the code like
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
108 this:
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
109
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
110 ch_log(NULL, "Value is now %02x", value);
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
111
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
112 After compiling and starting Vim, do:
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
113
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
114 :call ch_logfile('debuglog', 'w')
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
115
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
116 And edit `debuglog` to see what happens. The channel functions already have
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
117 `ch_log()` calls, thus you always see that in the log.
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
118
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
119
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
120 ## Important Variables ##
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
121
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
122 The current mode is stored in `State`. The values it can have are `NORMAL`,
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
123 `INSERT`, `CMDLINE`, and a few others.
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
124
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
125 The current window is `curwin`. The current buffer is `curbuf`. These point
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
126 to structures with the cursor position in the window, option values, the file
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
127 name, etc. These are defined in
16407
cbb6e28af4cb patch 8.1.1208: links to repository use wrong file name
Bram Moolenaar <Bram@vim.org>
parents: 16391
diff changeset
128 [`structs.h`](https://github.com/vim/vim/blob/master/src/structs.h).
16129
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
129
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
130 All the global variables are declared in
16407
cbb6e28af4cb patch 8.1.1208: links to repository use wrong file name
Bram Moolenaar <Bram@vim.org>
parents: 16391
diff changeset
131 [`globals.h`](https://github.com/vim/vim/blob/master/src/globals.h).
16129
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
132
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
133
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
134 ## The main loop ##
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
135
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
136 This is conveniently called `main_loop()`. It updates a few things and then
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
137 calls `normal_cmd()` to process a command. This returns when the command is
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
138 finished.
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
139
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
140 The basic idea is that Vim waits for the user to type a character and
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
141 processes it until another character is needed. Thus there are several places
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
142 where Vim waits for a character to be typed. The `vgetc()` function is used
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
143 for this. It also handles mapping.
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
144
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
145 Updating the screen is mostly postponed until a command or a sequence of
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
146 commands has finished. The work is done by `update_screen()`, which calls
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
147 `win_update()` for every window, which calls `win_line()` for every line.
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
148 See the start of
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
149 [`screen.c`](https://github.com/vim/vim/blob/master/src/screen.c)
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
150 for more explanations.
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
151
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
152
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
153 ## Command-line mode ##
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
154
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
155 When typing a `:`, `normal_cmd()` will call `getcmdline()` to obtain a line
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
156 with an Ex command. `getcmdline()` contains a loop that will handle each typed
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
157 character. It returns when hitting `CR` or `Esc` or some other character that
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
158 ends the command line mode.
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
159
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
160
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
161 ## Ex commands ##
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
162
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
163 Ex commands are handled by the function `do_cmdline()`. It does the generic
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
164 parsing of the `:` command line and calls `do_one_cmd()` for each separate
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
165 command. It also takes care of while loops.
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
166
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
167 `do_one_cmd()` parses the range and generic arguments and puts them in the
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
168 `exarg_t` and passes it to the function that handles the command.
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
169
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
170 The `:` commands are listed in `ex_cmds.h`. The third entry of each item is
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
171 the name of the function that handles the command. The last entry are the
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
172 flags that are used for the command.
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
173
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
174
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
175 ## Normal mode commands ##
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
176
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
177 The Normal mode commands are handled by the `normal_cmd()` function. It also
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
178 handles the optional count and an extra character for some commands. These
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
179 are passed in a `cmdarg_t` to the function that handles the command.
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
180
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
181 There is a table `nv_cmds` in
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
182 [`normal.c`](https://github.com/vim/vim/blob/master/src/normal.c)
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
183 which lists the first character of every command. The second entry of each
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
184 item is the name of the function that handles the command.
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
185
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
186
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
187 ## Insert mode commands ##
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
188
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
189 When doing an `i` or `a` command, `normal_cmd()` will call the `edit()`
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
190 function. It contains a loop that waits for the next character and handles it.
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
191 It returns when leaving Insert mode.
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
192
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
193
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
194 ## Options ##
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
195
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
196 There is a list with all option names in
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
197 [`option.c`](https://github.com/vim/vim/blob/master/src/option.c),
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
198 called `options[]`.
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
199
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
200
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
201 ## The GUI ##
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
202
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
203 Most of the GUI code is implemented like it was a clever terminal. Typing a
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
204 character, moving a scrollbar, clicking the mouse, etc. are all translated
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
205 into events which are written in the input buffer. These are read by the
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
206 main code, just like reading from a terminal. The code for this is scattered
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
207 through [`gui.c`](https://github.com/vim/vim/blob/master/src/gui.c).
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
208 For example, `gui_send_mouse_event()` for a mouse click and `gui_menu_cb()` for
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
209 a menu action. Key hits are handled by the system-specific GUI code, which
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
210 calls `add_to_input_buf()` to send the key code.
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
211
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
212 Updating the GUI window is done by writing codes in the output buffer, just
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
213 like writing to a terminal. When the buffer gets full or is flushed,
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
214 `gui_write()` will parse the codes and draw the appropriate items. Finally the
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
215 system-specific GUI code will be called to do the work.
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
216
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
217
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
218 ## Debugging the GUI ##
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
219
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
220 Remember to prevent that gvim forks and the debugger thinks Vim has exited,
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
221 add the `-f` argument. In gdb: `run -f -g`.
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
222
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
223 When stepping through display updating code, the focus event is triggered
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
224 when going from the debugger to Vim and back. To avoid this, recompile with
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
225 some code in `gui_focus_change()` disabled.
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
226
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
227
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
228 ## Contributing ##
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
229
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
230 If you would like to help making Vim better, see the
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
231 [`CONTRIBUTING.md`](https://github.com/vim/vim/blob/master/CONTRIBUTING.md)
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
232 file.
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
233
52ae47071830 patch 8.1.1069: source README file doesn't look nice on github
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
234
34057
4635e43f2c6f patch 9.1.0000: Vim 9.1 release
Christian Brabandt <cb@256bit.org>
parents: 29314
diff changeset
235 This is `README.md` for version 9.1 of the Vim source code.