Installation on macOS

This page explains how to install EXWM as the XQuartz window manager on macOS.

Note that EXWM cannot manage native macOS applications at all, only X11 applications will be managed.

The following instructions assume a bash shell.

1. Install XQuartz

   Follow instructions at https://www.xquartz.org.

2. Install the X11 version of Emacs.

   Emacs with X11 support is seldom packaged for macOS. For example, the Homebrew package manager only distributes Emacs with Cocoa support. In that case, Emacs can be build from source with X11 support.

   NOTE: Please, report whether other package managers (MacPorts, Fink, ...) distribute the X11 version of Emacs.

   Using different versions of Emacs can lead to issues with byte-compiled code; make sure to check out the branch corresponding to other installed Emacsen. In the instructions below, we assume Emacs 26 is already installed on the machine, therefore select the emacs-26 branch.

   Note as well that Xft fonts look blurry on Retina displays (see https://bugs.freedesktop.org/show_bug.cgi?id=92777 for details). This can be worked-around by avoiding the use of Xft fonts within Emacs. The instructions below check whether the system has a Retina display and compile Emacs without Xft support if that is the case.

   Difficulties finding Emacs with X11 support on macOS apply as well to Gtk with X11 support. Were that the case, one may simply use the lucid backend (--with-x-toolkit=lucid in the installation script).

   At last, note that the documentation is not built and GIF support is disabled in the script below. Would you want to enable them, simply delete the --without-makeinfo and --without-gif arguments.

   $ git clone --branch emacs-26 'git://git.sv.gnu.org/emacs.git /opt/src/emacs-x11'
   $ cd /opt/src/emacs-x11
   $ sh autogen.sh
   $ mkdir build
   $ cd build
   $ system_profiler SPDisplaysDataType | grep -q Retina && WITH_XFT='no' || WITH_XFT='yes'
   $ ../configure --prefix='/opt/emacs-x11' --without-ns --with-x --with-x-toolkit='lucid' --with-xft="$WITH_XFT" --without-makeinfo --with-gif='no' --enable-symbols PKG_CONFIG_PATH='/opt/X11/lib/pkgconfig/'

3. In order to substitute the default XQuartz window manager (named quartz-wm) with EXWM, a file named $HOME/.xinitrd.d/NN-xxx.sh must be created which launches our X11 Emacs as its last action. This will prevent quartz-wm from starting.

   $ mkdir "$HOME/.xinitrc.d"
   $ cat <<EOF >"$HOME/.xinitrc.d/99-exwm.sh"
   exec /opt/emacs-x11/bin/emacs --eval "(add-hook 'after-init-hook #'exwm-enable)"
   EOF
   $ chmod +x "$HOME/.xinitrc.d/99-exwm.sh"

   The --eval above makes sure EXWM is enabled when launching Emacs. Can be removed if EXWM is started from your configuration.

Optional configuration

Character composition

By default, XQuartz maps both option keys to Mode_Switch (which composes characters), and knows nothing about Super. This behaviour can be changed by editing $HOME/.Xmodmap. The following example configures the left option to be interpreted as Super, and leaves the right option to its default of composing characters.

$ cat <<EOF >"$HOME/.Xmodmap"
keycode 66 = Super_L
clear mod1
add mod1 = Super_L
EOF

Disable startup program

XQuartz defaults to launching XTerm at startup. This behaviour can be disabled by issuing the following command:

defaults write org.macosforge.xquartz.X11 app_to_run /usr/bin/true

Visit the following link for more details: https://apple.stackexchange.com/questions/53734/how-do-i-prevent-x11-opening-an-xterm-when-it-starts.