Skip to content

Building

Jump to bottom
Yee Cheng Chin edited this page Oct 22, 2023 · 66 revisions

Building 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.

Minimum Requirements

In order to build MacVim, you have to be on at least macOS 10.11 / Xcode 8. See Legacy builds (macOS 10.9 - 10.12) below for more info if you are using older versions of macOS.

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. This will also default to building in Debug instead of Release (which make builds in).

If you have an older version of Xcode (older than Xcode 12) that refuses to open the xcodeproj file, you can open src/MacVim/MacVim_xcode8.xcodeproj instead. The xib files are built for the Xcode 8 format, so if you use Xcode 7 you have to manually convert them before you build them.

Note: You have to build MacVim on the command-line using the Makefile once before you try to build in Xcode. This is because the MacVim.xcodeproj build is the last step in the build chain, and relies on Vim having been built separately, and a runtime_folder_list.xcfilelist to be populated by the build. Every time you modify Vim source code (e.g. src/*.c or src/MacVim/gui_macvim.m), you also 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.

Also, note that currently MacVim is only build-able with Xcode 8 or above (due to usage of new Objective C features, and xib files saved in Xcode 8 formats), which is only available for macOS 10.11. If you want to build a binary for 10.9 - 10.10, you will need to build it on macOS 10.11 or newer, but set the deployment target to 10.9.

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 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.
    • macOS SDK version: --with-macsdk=$VER ($VER examples: 10.15,13.0,…). The SDK needs to be installed. If you want to use older SDKs than the one bundled in Xcode, you can copy them from older versions of Xcode into /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/. You can use otool -l src/MacVim/build/Release/MacVim.app/Contents/MacOS/*Vim | grep sdk to confirm that it's built using the correct SDK.
  • 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.
    • 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
  • Debugging support:
    • Build Vim with debugging info / without optimizations: Set CFLAGS="-g3 -O0" when calling configure.
    • Build MacVim in Debug configuration when built from command-line: --with-xcodecfg=Debug.
    • To combine both: CFLAGS="-g3 -O0" ./configure --with-xcodecfg=Debug

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.

Debugging 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. See "Debugging support" above for how to configure MacVim to be built with debugging symbols without optimizations.
    • Alternatively, if you don't want to re-run configure, build using make "CFLAGS=-g3 -O0" XCODEFLAGS="-configuration Debug".
  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