src/MacVim/README

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