Building "vanilla" emacs on macOS, with MacPorts, and more...

6/12/2024 update

My version of macOS is too old to be able to use brew reliably since the package manager deprecated support for Monterey (macOS 12) as of its latest release. I had to remove all traces of brew on my machine and moved to MacPorts that still provides support back to macOS 10.5 (Leopard !!!).

I modified the text to only cover a MacPorts installation. People who rely on brew will know how to change the commands. I have also updated a few links.

---

Table of contents

1. Free software = build your software yourself →
2. Required dependencies for building emacs on macOS →
3. Extra dependencies that will add features to your emacs →
4. 8 lines of instructions →
5. emacs documentation →
6. To use emacs from the command line →
7. Updating the code requires 2 instructions →
8. Free Software = you can write code and contribute →
9. References →

---

This is Free Software!

Lots of people seem to wonder, "what is the best emacs for macOS"?

Their criteria for "best" being not always clear, the answer I systematically give is: "Clone the repository and build it yourself. This is free software!"

Since I always forget the dependencies and the steps, this page is a memo for myself, and for curious people who want to try themselves.

Note: I am not a programmer. I just follow instructions. There is nothing magic in the few instruction lines that follow. Before, or after you've cloned emacs, you can read the INSTALL.REPO file where basically everything I write here is found, along with the README and the INSTALL files where you'll find additional or redundant information. It's basically all there. This page is just a summary for me.

ToC

Required dependencies

The dependencies below are the minimum emacs requires, and you can find them by running ./autogen.sh first and then ./configure yourself before using MacPorts to install them: the two scripts will just choke every time they don't find the required libraries.

What I did to come up with that list is just add dependencies until the scripts ran their course without error.

If this is your first "development" attempt, you will need the XCode command line tools, basically because you'll need gcc and git for the whole process. Follow the instructions on the "Intalling MacPorts" page to find how to install them. And don’t forget to install MacPorts too.

The first time you run git, for example to clone emacs, macOS will tell you that you need to install them and prompt you with a nice dialog.

The required dependencies are the following:

• Autoconf
  "Autoconf is an extensible package of M4 macros that produce shell scripts to automatically configure software source code packages."
• texinfo
  "Texinfo is the official documentation format of the GNU project."
• GNU Mailutils
  "Mailutils is a swiss army knife of electronic mail handling. It offers a rich set of utilities and daemons for processing e-mail."
• GnuTLS
  "GnuTLS is a secure communications library implementing the SSL, TLS and DTLS protocols and technologies around them."

ToC

Extra dependencies

I sent the link to this article to the emacs-devel mailing list for verification and Pankaj Jangid was nice enough to tell me about his own experiences and suggested a list of non-required but recommended packages that emacs would notice during the configuration process. Alan Third, the ns-port maintainer, also chimed in to indicate that some of Pankaj proposed libraries were in fact ignored since the image types they correspond to are handled by macOS proper.

The recomended dependencies are the following:

• librsvg
  "This is librsvg - A small library to render Scalable Vector Graphics (SVG), associated with the GNOME Project."
• libxpm
  "X11 pixmap library"
• lcms2
  "Little CMS intends to be a small-footprint color management engine, with special focus on accuracy and performance."
• jansson
  "Jansson is a C library for encoding, decoding and manipulating JSON data."

If you want to install the above recommended dependencies, you'll need to add a port install instruction as shown below.

ToC

The instructions

# install required dependencies
# or jump to "configure, etc." below and install them one by one
sudo port install autoconf texinfo gnutls mailutils

# install recommended dependencies, but only after you've checked what they do by following the links above...

sudo port install librsvg libxpm lcms2 jansson

# clone emacs
# URL: https://savannah.gnu.org/projects/emacs
git clone -b master git://git.sv.gnu.org/emacs.git

# configure, build and install emacs
cd emacs
./autogen.sh
./configure
make install

Et voilà! Emacs.app now resides in emacs/nextstep/Emacs.app.

ToC

Documentation

I don't suppose you'd want to install emacs from scratch without knowing how to use it, but if that's the case, and that's totally OK, emacs comes with thousands of pages of manuals that are just a ctrl-h i away.

That shortcut means hit the control key, hold it pressed, hit the h key, release both, and hit the i key. That shortcut calls the info function, which bring up the list of manuals included in emacs.

You can also start a tutorial with ctrl-h t, which means hit the control key, hold it pressed, hit the h key, release both, and hit the t key. That shortcut calls the help-with-tutorial function.

The manuals are online, if you feel more confortable reading in a web browser: GNU Emacs Manuals Online

ToC

A few extra settings

If you need to use emacs from the command line you may need to update your .profile file with aliases like this:

alias emacs='path/to/emacs/nextstep/Emacs.app/Contents/MacOS/Emacs'
alias emacsclient='path/to/emacs/nextstep/Emacs.app/Contents/MacOS/bin/emacsclient'
alias ctags='path/to/emacs/nextstep/Emacs.app/Contents/MacOS/bin/ctags'
alias ebrowse='path/to/emacs/nextstep/Emacs.app/Contents/MacOS/bin/ebrowse'
alias etags='path/to/emacs/nextstep/Emacs.app/Contents/MacOS/bin/etags'

and that's basically it.

ToC

Updating the thing

The first time you build emacs, along with installing all the dependencies, etc. might take some time, maybe a good 30 minutes, maybe more. But then, you end up with a configuration where you just need to update the code once in a while, and make install the thing again to have the latest version running.

Basically, all is needed is to run this:

# inside the cloned emacs directory
# update the code
git pull

# build and install the new version
make install

And the next time to start emacs, you run the lastest master branch code.

ToC

This it Free Software! 2

The whole point of Free Software is that is gives you the tools necessary to understand what is going on, to learn how to do things yourself and to control your environement.

So, yes, emacs is free software, and now you're all set to play with the code and do your own thing, that will eventually lead to first contribute small things, and then bigger and bigger things to emacs proper.

For that, you just need to create your own development branch and code there:

# inside the cloned emacs directory
# update the code, just to have the latest one
git pull

# create your development/test branch, for example "myEmacs"
git checkout -b myEmacs

# open that new branch in Finder
open .

Everything you do there will never impact the master branch from which you have built emacs. You can always git checkout master back to go back to a clean slate (git will eventually ask you to git stash away your modifications before switching to master, so just follow the instructions).

ToC

References

Now, you may want to know a bit more about Emacs Lisp, about git, about how to contribute to emacs, so here are some references:

• The "Introduction to Programming in Emacs Lisp" is the entry point for Emacs Lisp development. It is available from inside emacs (type ctrl-h i to find the list of manuals available right at your finger tips) and also online:
  An Introduction to Programming in Emacs Lisp
• git comes with excellent documentation, and a free book too:
  Git Documentation
• If you want to practice your Emacs Lisp skills, the "Exercism" site has a track for you:
  Emacs Lisp on Exercism
• You will quickly find that you need to have a good Emacs Lisp reference to go further. emacs provides you with an excellent reference for pretty much everything you need to know, here again, just a ctrl-h i away, but it is also online:
  GNU Emacs Lisp Reference Manual
• If you need general help, there is a help-gnu-emacs list and for development help there is the emacs-devel list, along with a lot of other emacs related lists, hosted on the emacs development site:
  emacs - Mailing Lists
• And here is a tutorial about the procedure to follow if you want to propose your code for inclusion into emacs, by Colin Woodbury:
  Contributing to Emacs

ToC