-
Notifications
You must be signed in to change notification settings - Fork 398
/
README
164 lines (123 loc) · 7.45 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
This README contains an overview of the MacVim source code and a very short
description on how to build the application.
The information in here is not meant to be exhaustive. A lot more information
can be found in the source code comments.
Source code overview:
MacVim.app consists of two executables: MacVim and Vim. MacVim is a Cocoa app
which does all the window management including drawing and receiving input.
Vim is the actual editor which receives input from MacVim and sends output
back when there is something to draw.
As far as the source code files goes, MacVim.[m|h] contains code shared
between MacVim and Vim, gui_macvim.m and MMBackend.[m|h] belongs to Vim,
everything else belongs to MacVim. (The source code is all Objective-C which
is very easy to pick up if you know C and some object oriented programming.)
Each editor window in MacVim runs its own Vim process (but there is always
only one MacVim process). Communication between MacVim and a Vim process is
done using Distributed Objects (DO). Each Vim process is represented by a
backend object (MMBackend) and it communicates with a frontend object in the
Vim process (MMVimController). The interface between the backend and frontend
is defined in MacVim.h.
The frontend sends input to the backend by calling
-[MMBackend processInput:data:]. The backend queues output on a command queue
and sends it to the frontend at opportune times by calling
-[MMVimController processCommandQueue:]. These are both asynchronous calls so
MacVim can keep drawing and receiving input while Vim is working away, thus
always keeping the user interface responsive.
The state of each editor window is kept entirely in the Vim process. MacVim
should remain "ignorant" in the sense that it knows nothing of the actual
state of a Vim process. Typically this is not a problem, but sometimes MacVim
must change state without going via Vim, and sometimes MacVim needs immediate
access to the state from Vim. The former happens e.g. when the user drags to
resize a window (MacVim changes the window dimensions immediately without
asking Vim first), the second can happen when some option variable affects the
way something is presented visually (e.g. MacVim needs immediate access to the
'mousehide' option so that it can hide the mouse cursor when input is
received). State information that may be required in this way can be "pushed"
to MacVim inside -[MMBackend queueVimStateMessage].
Vim:
Hooks from within Vim are implmented in gui_macvim.m, the name of such
functions usually start with "gui_mch_" and they should simply put a message
on the output queue, by calling queueMessage:properties: on the singleton
MMBackend object [MMBackend sharedInstance] (see e.g. gui_mch_destroy_menu()).
The output queue is flushed when requested (in -[MMBackend flushQueue]) or
before Vim takes a nap whilst waiting for new input (in
-[MMBackend waitForInput]).
Note that each Vim process has its own run loop (it is required for DO) and
since Vim is in charge of its thread it needs to "update" the run loop
manually. This can happen in -[MMBackend update], which returns immediately
if nothing is pending on the run loop, or in -[MMBackend waitForInput], which
can possibly block until input appears on the run loop. In any case, if Vim
for some reason fails to update the run loop then incoming DO calls will not
be processed and for this reason it is best to avoid making synchronous DO
calls from MacVim. (If synchronous calls must be made then it is important to
set proper timeouts so that MacVim doesn't "hang", see
-[MMVimConroller sendMessageNow:::] to see how this can be done.)
MacVim:
The main nib of MacVim.app is MainMenu.nib which contains the default menu and
an instance of MMAppController, which is connected as the delegate of
NSApplication. That mens, when MacVim starts it will load this nib file and
automatically create an instance of the MMAppController singleton.
A new editor window is opened by calling
-[MMAppController launchVimProcessWithArguments:]. This functions starts a
new Vim process (by executing the Vim binary). The Vim process lets MacVim
know when it has launched by calling -[MMAppController connectBackend:pid:]
and MacVim responds to this message by calling a new frontend object
(MMVimController) and returns a proxy to this object back to the Vim process.
From this point onward the Vim process communicates directly with the
MMVimController.
The MMVimController represents the frontend of a Vim process inside MacVim.
It coordinates all communication with the Vim process and delegates output
that affects visual presentation to a MMWindowController object. Read the
Cocoa documentation on the responsibilities of a window controller.
Input (keyboard & mouse) handling and drawing is handled by a MMTextView
object.
Distributed Object dangers:
Distributed Object messages are handled whenever the run loop is updated.
Since the run loop can be updated at unpredictable times some care has to be
taken when implementing DO messages. Some unexpected examples of when the run
loop is updated:
1. When a synchronous DO message is sent. The run loop goes into a loop
waiting for a return to the synchronous message; During this wait another DO
message may arrive.
2. When a modal loop is entered. For example, when a user presses a Cmd-key
the menu flashes briefly. During this "flash" a modal loop is entered.
Item 1 can cause a problem if MacVim sends a synchronous message and before a
reply reacheds MacVim another message is received. From the source code it
looks like the synchronous message blocks but in fact the other message is
executed during this "block". If the other message changes state radically
something may go wrong after the synchronous DO message returns.
Item 2 can cause similar problems but it may happen deep inside a Cocoa call
which may be even more puzzling.
One way to alleviate these problems is to ensure a DO message isn't entered
twice by setting a boolean at the beginning of the message and clearing it
afterwards. If the boolean is already set when entering the call must somehow
be delayed. See -[MMVimController processCommandQueue:] for a concrete
example.
Another danger is that we must take care when releasing objects that Cocoa may
be using. See -[MMVimController connectionDidDie:] how MacVim releases
MMVimControllers when the Vim process they control exits.
Source code file organisation:
Here is an incomplete list of source code files with a short explanation of
what they contain:
MMAppController.* Everything related to running the application
MMBackend.* Object representing a Vim process in backend
MMTextView.* Handles input and drawing
MMVimController.* Object representing a Vim Process in frontend
MMVimView.* Cocoa view object
MMWindowController.* Coordinates visual presentation
MacVim.* Code shared between MacVim and Vim
gui_macvim.m Hooks from Vim
Building:
You will need to install the Xcode tools before building the source code.
Nothing else needs to be installed in order to build MacVim.
Steps to build MacVim.app (the text before the '$' shows the folder you should
be in when executing these commands):
1. Configure Vim
src/$ configure --enable-gui=macvim
2. Build Vim executable
src/$ make
3. Build MacVim.app application bundle
src/MacVim/$ xcodebuild
The application bundle can be found inside "src/MacVim/build/Release".
Bjorn Winckler <bjorn.winckler@gmail.com>
June 22, 2008