/build-emacs-macos

Build script for emacs and macos

Primary LanguageShellMIT LicenseMIT

Here you’ll find a shell script for building emacs on macos, along with a few other useful bits.

There is, of course, the great Emacs for macos. This is probably the most straightforward way to get emacs for the mac. There is also homebrew and the various ways of building emacs for that. Three great ones are:

There are also a few great sources for looking at how to build emacs on macos. See for example:

So why another build script? Well, in keeping with the way I use emacs, I wanted to be able to build it in the way that I preferred, using all the options that I thought important. Plus I also wanted to understand more about the build process. Since I’m not a programmer, I tried to write a shell script that would be as accessible to other non-programmers as possible. It was this latter that I found particularly lacking in my search on the internet for instructions about how to build emacs using any but the most basic of settings. So below you’ll find a discussion of the various contents of this repo, what they do (to the best of my very limited knowledge) and why they are there. Hopefully this will be of help to those people who, like myself, want more control over how emacs works but lack much of the programming knowledge that is assumed for building it.

Note that this build process currently works well for me using a 2021 M1 Macbook Pro with Monterey 12.0.1. It should build either the latest emacs release, emacs 28, or the master branch just fine. I have not tested this on other machines or for other kinds of build. Builds are specific to the machine on which they are created, and not guaranteed to work without breakage on other machines (no dylibs are included though see here if you want something more self-contained).

Emacs & Git

The first thing one needs to do in building emacs from the source files is clone the emacs git repository. You can do this either by cloning from the main repo: git clone https://git.savannah.gnu.org/git/emacs.git or from the github mirror: git clone https://github.com/emacs-mirror/emacs.git. It doesn’t really matter which one you choose. Clone it to somewhere convenient on your system (I clone it to a subdirectory of this build-emacs dir).

Build Requirements

You’ll need to install the following to build emacs. For convenience, you can use the install script that I’ve provided in the repo. From the emacs-build directory run chmod u+x bemacs-requirements.sh and then ./bemacs-requirements.sh and you should be all set.

  • Xcode command line tools
  • Homebrew
  • autoconf
  • automake
  • jpeg
  • gnutls
  • texinfo
  • gcc
  • libgccjit
  • pkg-config
  • jansson

Config Options

Config-options.txt lists the various options one can use to build emacs. It is generated by running ./autogen.sh in the emacs git repo. There are many to choose from, though slightly less so on macos.

The options I use to build emacs currently are:

./configure \
    --with-ns \
    --with-native-compilation \
    --with-xwidgets \
    --with-mailutils \
    --with-json \
    --with-modules \
    --without-compress-install \  # don't compress things like help & info files
    --with-dbus \ # this is mostly useless on mac but harmless to include
    --program-transform-name='s/^ctags$/emctags/' \ # avoid ctags namespace conflict

Depending on what version you’re building you might also want to add --with-treesitter or other options new with emacs 29. For info consult Emacs 29 News.

Patches

These patches are various modifications applied to emacs during the build process. You can read more about the patch command by running man patch on the command line or looking at some of the examples here. Currently the build script uses all patches. If you don’t want to use one of the patches below, remove it from the patches directory or modify the build script (e.g by applying the patches individually rather than as part of a for loop). Here are the patches currently included:

  • Emacs git version: allows for showing git sha1 version of the built emacs in emacs-version command
  • Lion fullscreen: allow native fullscreen (especially useful for the new “notched” macbooks)
  • No window refocus: better treatment of window focus transfer
  • System appearance: allows for automatic theme switching with macos theme change; for an example of how to set it up see the patch or see the description here
  • Windowing: better treatment with window managers; see here for further discussion

Build-emacs.sh

Please note that large portions of the build script are derived from, or inspired by:

By default the build script builds off of the master branch but you can also specify the version you want to build from any commit within recent Emacs history (i.e. Emacs >= 24).

To use the build script simply:

  1. Clone this repo.
  2. Make sure that you have cloned the emacs source (e.g. git clone https://github.com/emacs-mirror/emacs.git).
  3. Get all requirements for build (chmod u+x ./bemacs-requirements.sh and ./bemacs-requirements.sh)
  4. Set the variables in the build script appropriately. Note that the Emacs source repo is set by default as being in the ~/Documents directory.
  5. Make the script executable using chmod u+x build-emacs.sh and have the script in your path.
  6. Run ./build-emacs.sh (if you don’t want to build from HEAD of the master branch you also need to include either the git sha1 or source/branch from which you are building)
  7. Add emacs and emacsclient to your PATH by adding the following to your .zshrc or .zprofile (assuming you use zsh): 
    export PATH=$PATH:/Applications/Emacs.app/Contents/MacOS
export PATH=$PATH:/Applications/Emacs.app/Contents/MacOS/bin

If you’re wondering whether the most recent commit on master is stable, you might check out jimeh’s “good-version” list of emacs-main versions to see which git sha points to a stable commit.

Build-logs

Each build with build-emacs.sh generates a subdirectory in build-logs with a set of build logs organized by name, date, and commit.

Materials

I’ve included a big-sur icon by memeplex (from here). There is an info.plist to transfer to the emacs build along with it. There is also an elisp file into which the emacs build git sha1 will be inscribed and the file copied to the emacs build’s site-lisp (see the SITELISP variable in build-emacs.sh).