Building Emacs from source on MacOS

Posted: 08 Sep, 2022; Updated: 27 Oct, 2022 emacs

This is a guide for building Emacs from source for Mac OSX (tested on 12.4, M1) with native compilation enabled. If you don't want native compilation (though I highly recommend it), feel free to drop the the --with-native-compilation flag when you run the ./configure script.

Prerequisites

Xcode command line tools
libgccjit, required for native compilation

Building Emacs

First, clone the repo (you can also use the Github mirror instead):

git clone https://git.savannah.gnu.org/git/emacs.git

These next few steps are taken straight from the INSTALL.REPO file in the source repository, with the addition of a few options during configuration.

Run autogen

After the code is pulled down, cd into the directory and run the autogen.sh script. This initial script generates another script (configure) that you'll use to actually configure the Emacs Makefile to build on your OS.

cd emacs/
./autogen.sh

Run configure

You can view all of the available options for configure by passing in the --help flag:

./configure --help

Here is the list of options that are recommended for Mac OS, compiled from various sources. I've included the --help output with each option:

--with-native-compilation: compile with Emacs Lisp native compiler support
--with-json: compile with native JSON support
--with-ns: use Nextstep (macOS Cocoa or GNUstep) windowing system. On by default on macOS
--with-xwidgets: enable use of xwidgets in Emacs buffers (requires macOS Cocoa, more info)
--without-dbus: don't compile with D-Bus support (more info)
--without-compress-install: don't compress some files (.el, .info, etc.) when installing
--disable-silent-rules: enable verbose build output

Run the configure script with these options to create the Makefile you'll use to build Emacs.

./configure --with-native-compilation \
            --with-json \
            --with-ns \
            --with-xwidgets \
            --without-dbus \
            --without-compress-install \
            --disable-silent-rules

After this finishes, it's time to build Emacs proper.

Build emacs

Note: if make fails, take a look at "Troubleshooting" down below. Your best bet is to run make bootstrap instead.

make

This creates an Emacs binary at src/emacs. You can verify that everything worked properly by running emacs -Q, launching it with no configuration.

src/emacs -Q

After you've verified that everything is good to go, the last step is to assemble Emacs.app proper:

make install

You'll notice that a hefty Emacs.app application now lives in the nextstep/ directory. Go ahead and move it into your /Applications/ directory.

mv nextstep/Emacs.app /Applications/

I also like to include src and lib-src on PATH so I can run Emacs from the CLI (particularly important for emacsclient):

# Syntax for fish shell
set PATH $HOME/projects/emacs/src $PATH
set PATH $HOME/projects/emacs/lib-src $PATH

Congratulations, you have officially built Emacs from source!

Next steps

With everything running smoothly, you're now ready to make your first contributions to the Emacs codebase. Here are some excellent guides to get started:

Contributing to Emacs by Colin Woodbury
Welcome, New Emacs Developers by Lars Ingebrigtsen

Best of luck, new Emacs contributor!

Troubleshooting

If make fails, one of the easiest ways to resolve most problems is to use the bootstrap script instead:

# Clean out any dangling build artifacts
make clean

make bootstrap

This is effectively a "slower and more thorough" build of the application, and successfully resolved a few issues I ran into when I updated from Emacs 28 to 29.