Skip to content

Building

Jump to bottom
Yee Cheng Chin edited this page Feb 26, 2023 · 66 revisions

Installing MacVim

For installing MacVim, it's recommended to use the official binary releases. See Installing. Below are instructions for building MacVim if you would like to modify it.

How to get the MacVim source code

Open up Terminal and type (this requires that you have Git installed):

$ git clone https://github.com/macvim-dev/macvim.git

(If you do not have Git installed the "Zip" button under the "Code" tab lets you download an archive containing the source code.)

How to build MacVim

First clone the repo as above, then configure with the flags you want, e.g.:

$ cd macvim/src
$ ./configure

Note: On Mac OS X versions where gcc is not an alias for clang (such as 10.7 or 10.8) you must set the environment variable CC=clang before calling configure, e.g. type CC=clang ./configure and then add any flags to configure. If you want to build with clang on earlier platforms then you have to switch vim/MacVim/MacVim.xcodeproj to clang too, else IPC between backend and GUI won't work.

Once this has finished, build the project:

$ make

The resulting app bundle will reside under MacVim/build/Release. To try it out quickly, type:

$ open MacVim/build/Release/MacVim.app

To open the terminal version of MacVim, type:

$ MacVim/build/Release/MacVim.app/Contents/bin/vim

To install MacVim, type

$ open MacVim/build/Release

and drag the MacVim icon into your Applications folder.

Using Xcode to build

If you are making changes to MacVim, it could be easier to build/test MacVim from within Xcode instead of invoking make. Simply open src/MacVim/MacVim.xcodeproj and build from there.

Note: You have to build Vim separately first before you can build the xcodeproj file, as MacVim.xcodeproj assumes that the Vim binary already exists. Every time you modify Vim source code (e.g. src/*.c or src/MacVim/gui_macvim.m), you have to build Vim separately before building the xcodeproj. You can build Vim by running the following:

$ cd src; make Vim

Legacy builds (macOS 10.9 - 10.12)

If you are building for legacy macOS versions (10.9 - 10.12), they should still work but some features may be missing. In particular, only Sparkle 1 is supported. Make sure you either disable Sparkle or configure MacVim to use Sparkle 1 (see below instructions), as the default (Sparkle 2) will not work as it requires 10.13 or above. If you used the --disable-sparkle option, make sure you do the recommended step to remove Sparkle.framework from the output app because Sparkle 2 would fail the app launch as it's configured to only run on 10.13+.

Enabling extra features

You can enable extra Vim features by passing the appropriate flags to configure. You don't really need to turn on any flags unless there are specific features you want. These are the parameters to configure you may want to enable:

  • All standard features (this is turned on by default and only for reference): --with-features=huge
  • Cscope support: --enable-cscope
  • Scripting support:
  • macOS build configuration:
    • Universal binary: --with-macarchs=ARCHS (ARCHS examples: x86_64,arm64,…. To build universal binary, separate the different values with space, e.g. --with-macarchs="x86_64 arm64")
    • macOS SDK version: --with-macsdk=$VER ($VER examples: 10.15,13.0,…)
    • macOS deployment target (the minimum macOS version that can run the built app): Instead of a configure flag, set environment variable MACOSX_DEPLOYMENT_TARGET=$VER when running configure and make ($VER examples: 10.15, 13.0, …).
      • Example (targeting 10.13): MACOSX_DEPLOYMENT_TARGET=10.13 ./configure; MACOSX_DEPLOYMENT_TARGET=10.13 make.
  • Sparkle (this is the software updater MacVim uses to keep itself up to date):
    • Disable Sparkle:
      1. Run configure with --disable-sparkle. Build as normal.
      2. After you have finished building, it's recommended you remove the src/MacVim/build/Release/MacVim.app/Contents/Frameworks/Sparkle.framework folder manually. The framework is copied over to MacVim but it is not used at all and it's safe to remove. We may make it so that the build script will automatically remove it in the future.
    • Use Sparkle 1. By default MacVim uses Sparkle 2, which has higher OS requirements than Sparkle 1.
      1. First, change the Sparkle.framework symlink: ln -fsh Sparkle_1.framework src/MacVim/Sparkle.framework
      2. Run configure with --enable-sparkle-1
  • Optional libraries
    • Enable/Disable gettext (localization). It should be enabled by default (if gettext exists): --enable-nls / --disable-nls
    • Enable/Disable sodium (encryption support). It should be enabled by default (if sodium exists): --enable-libsodium / --disable-libsodium
    • Use Homebrew libraries (e.g. gettext/libsodium) on Apple Silicon: --with-local-dir=/opt/homebrew

To see all available flags, type ./configure --help.

Easiest way to clean all configured results is by using make distclean which will remove all built binary and configuration and you can call configure again from a clean slate.

How to debug MacVim

If you would like to debug MacVim using Xcode, you first have to build Vim using make Vim, then open src/MacVim/MacVim.xcodeproj and you can build, run, and debug MacVim code from within Xcode. See above. Also, see this document for more info of how the code is structured.

If you would like to debug the Vim process instead (MacVim hosts each window in a separate Vim process and talks to them via Distributed Objects), do the following for best results:

  1. Build using make "CFLAGS=-O0 -g" XCODEFLAGS="-configuration Debug" to build Vim without optimizations, and to build a debug Xcode build.
  2. Turn off QuickStart in Advanced Preferences. When that option is on there is a shadow Vim process which makes it more annoying to figure out one is the one you want to debug.
  3. Run MacVim from Xcode, wait for the Vim window to show up.
  4. Find out the PID of the Vim process by running the following in the MacVim source folder: ps aux | grep "`pwd`.*/Contents/MacOS/Vim" | grep -v grep. The first number you see is the PID.
  5. In Xcode (it should already be debugging MacVim itself), select Debug → Attach to Process by PID or Name, and paste in the PID of Vim. Xcode should now be able to debug and set breakpoints within the Vim process.

For simplicity and efficiency, you can combine step 4 and 5 instead a single convenient command:

ps aux | grep "`pwd`.*/Vim" | grep -v grep | cut -w -f 2 | tee /dev/tty | pbcopy && osascript -e "tell application \"Xcode\" to attach active workspace document to process identifier `pbpaste` suspended false"
Clone this wiki locally