Skip to content

install.md

Latest commit

 

History

History
754 lines (552 loc) · 22.3 KB

install.md

File metadata and controls

754 lines (552 loc) · 22.3 KB
Raw

Installing Emacs

Install git

Windows

On Windows, the best way to do this is to install Git for Windows. Enabling cache during installation is recommended for a massive speedup.

macOS

On macOS, the best way to do this is to install Xcode from App Store.

(macOS only) Install Homebrew

You may want to pick up Homebrew for easier installation of other useful tools, though it's not a strict requirement.

Homebrew 6+ warns about non-official taps until you trust them. Prefer trusting only the specific formula or cask you need (see Tap Trust). Each macOS section below includes a brew trust line immediately before any third-party install. The emacs-plus tap is an exception where we trust the whole tap; see the Install Emacs on macOS section for why.

(Windows only) Install chocolatey

It's recommended to do an individual install of Chocolatey to make it easier to install several other dependencies later on.

(Windows only) Install MSYS2

You'll need a working version of make.exe in order to complete the bootstrap script. Here's the recommended steps for that:

  • Download the MSYS2 installer, choosing the one for x86_64
  • Run the installer, choosing the default install location (or if you change it, replacing paths as appropriate below)
  • Close the command prompt that came with the installer
  • Use the Start Menu to search for and open the task Edit the System Environment Variables. It may pop behind any open windows - if so, bring it to the front. Click Environment Variables. In the System variables section, double-click on Path. Add entries for C:\msys64\usr\bin and C:\msys64\ucrt64\bin (in that order) and move them to the very bottom of the list. Click OK until all of those windows close.
  • Open an "MSYS2 MinGW 64-bit" window and run these commands:
pacman -Sy pacman
pacman -Syu
pacman -Su
pacman -S --needed base-devel libssh2-devel msys/man-db xmlto
pacman -S --needed mingw-w64-ucrt-x86_64-{asciidoc,aspell-en,clang-tools-extra,cmake,fd,gcc,gnutls,go,libgccjit,make,ninja,ripgrep,rust,ty}
  • Make sure you do not have git installed through MSYS2 (we want it to come from Git For Windows instead so we get caching) by running this and ignoring any "target not found" errors:
pacman -R git

(Windows only) Install Visual Studio Build tools

In an Administrator PowerShell, run:

winget install --id Microsoft.VisualStudio.2022.BuildTools -e --source winget --override "--add Microsoft.VisualStudio.Component.Windows11SDK.22621 --add Microsoft.VisualStudio.Workload.VCTools --add Microsoft.VisualStudio.Component.VC.Runtimes.x86.x64.Spectre --add Microsoft.VisualStudio.Component.VC.ATL.Spectre --add Microsoft.VisualStudio.Component.VC.ATLMFC.Spectre"

Note: This is taken from the VSCode build instructions.

(Arch Linux only) Install utilities

It's assumed that you have installed paru already. If you haven't yet, do this:

sudo pacman -Sy --needed base-devel
mkdir -p ~/pkgbuilds
cd ~/pkgbuilds
git clone https://aur.archlinux.org/paru-bin.git
cd paru-bin
makepkg -si

Minimal install:

paru -Sy --needed aspell-en base-devel clang cmake fd gnutls gopls make man-db \
    man-pages mise ninja openssh python ripgrep rust-analyzer ty usage zls

For a full install, in addition to the above also run:

paru -Sy --needed clojure clojure-lsp-bin elixir jdtls leiningen \
    omnisharp-roslyn-bin zprint-bin
mise use -g elixir-ls@latest

Install mise

It's recommended to install mise and optionally usage for commandline help (as done in the Arch instructions above) to make it easier to manage and version different tools.

Configure your shell to work with it and restart any open terminals. We'll refer to mise in other installation sections.

For zsh, I find adding the following works well, and avoids problems with running zsh in a subshell. For ~/.zshenv:

# Setup mise for non-interactive sessions (shims only)
if (( $+commands[mise] )); then
    # Remove existing mise installs and shims entries
    path=("${path[@]:#*/mise/installs/*}")
    path=("${path[@]:#*/mise/shims}")

    if [[ ! -o interactive ]]; then
        # Interactive sessions will get activation later in .zshrc
        eval "$(mise activate zsh --shims)"
    fi
fi

For ~/.zshrc:

if (( ! $+commands[mise] )); then
    echo >&2 "Warning: mise is not installed yet, it manages tool versions"
else
    # Setup mise for interactive sessions
    if (( ! $+commands[usage] )) && \
       [[ ! -e ~/.local/share/mise/shims/usage ]]; then
        echo >&2 "Warning: usage is not installed yet, mise completions will not work"
    fi
    eval "$(mise activate zsh --shims)"
fi

Restart your terminal afterwards to apply the changes.

Install clangd

You'll need to install clangd in order to support language server features for C/C++. On Mac, install the llvm package from homebrew. For Windows, we've already done this for Windows in the Install MSYS2 section.

(Optional) Install clojure, clojure-lsp, cljstyle, and leiningen

You'll need to install clojure, install clojure-lsp, install leiningen, and install zprint in order to support Clojure. On Mac:

brew install --cask temurin@21
brew trust --formula clojure/tools/clojure
brew install clojure/tools/clojure leiningen
brew trust --formula clojure-lsp/brew/clojure-lsp-native
brew install clojure-lsp/brew/clojure-lsp-native
brew install --cask zprint
# do this to avoid failures when starting CIDER for the first time
mkdir -p ~/.lein

Note that on macOS: You'll need to attempt to run /opt/homebrew/bin/zprint --version and then go into System Settings -> Privacy & Security -> Security -> Allow, run it one more time, and click Run Anyway. You may also need to restart any open terminals so that the version of zprint in /usr/bin doesn't shadow the one in /opt/homebrew/bin.

You'll also want to create a ~/.zprintrc file with these contents:

;; -*- clojure -*-
{:search-config? true, :style [:how-to-ns]}

(Optional) Install Elixir and ElixirLS

You'll need to install Elixir (which includes Erlang/OTP as a dependency) and ElixirLS in order to support language server features for Elixir. On Mac:

brew install elixir
mise use -g elixir-ls@latest

On Arch Linux, these are covered by the full install packages above.

Install fd

fd is helpful for reducing time for locating files in project directories in some cases. On Mac, install the fd package from homebrew. For Windows, we've already done this for Windows in the Install MSYS2 section.

Install gopls

You'll need to install gopls in order to support language server features for C/C++. On Mac, install the go and gopls packages from homebrew. For Windows, we've already done this for Windows in the Install MSYS2 section.

Install jdtls (optional)

You'll need to install both a v21 or higher JDK/JRE and a JD-TLS in order to support language server features for Java. On Mac, install the jdtls package from homebrew. Since this requires a JDK/JRE, and is extremely slow, it can be skipped if you don't need these features for Java code.

Note that the first time you visit a Java file in a large project, JD-TLS might take a minute to initialize.

Install ninja

You'll need to install ninja in order to support fast execution of Magit. On Mac, install the ninja package from homebrew. For Windows, we've already done this for Windows in the Install MSYS2 section.

Install node.js

It's recommended to install mise, configure your shell to work with it, restart any open terminals, and then install the latest LTS node.js version and aube with:

mise use -g node@lts aube@latest
mise settings add idiomatic_version_file_enable_tools node

Install Omnisharp (optional)

Since this requires installing a .NET SDK, it's optional.

Windows

Run choco install omnisharp

Mac OS

Run:

brew trust --formula omnisharp/omnisharp-roslyn/omnisharp-mono
brew install omnisharp/omnisharp-roslyn/omnisharp-mono
sudo mkdir -p /usr/local/opt
sudo ln -s /opt/homebrew/opt/omnisharp-mono /usr/local/opt

Confirm that you can run omnisharp --help and get a help menu. If you get "assembly not found", make sure to create /usr/local/opt and set up the symlink as above.

Arch Linux

Run paru -S omnisharp-roslyn-bin

Install ripgrep

ripgrep is the fastest project search command available. On Mac, install the ripgrep package from homebrew. For Windows, we've already done this for Windows in the Install MSYS2 section.

Install rust-analyzer

You'll need to install rust analyzer in order to support language server features for Rust. On Mac, install the rust and rust-analyzer packages from homebrew. For Windows, we've already done this for Windows in the Install MSYS2 section.

Install ty

You'll need to install ty in order to support language server features for Python. On Mac, install the ty package from homebrew.

Install zls

You'll need to install ZLS in order to support language server features for Zig. On Mac, install the zls package from homebrew.

Install Emacs

The recommended version is Emacs 30.2. The recommended ways to install Emacs for each OS are as follows.

Install Emacs on Windows

  • Download and install emacs.
  • When done, you should verify that a file named C:\Program Files\Emacs\emacs-30.2\bin\runemacs.exe exists.
  • If you change the location, you may want to update the my-system-paths option later.
  • Adjust some environment variables so that Emacs can be started successfully
    • Use the Start Menu to search for and open the task Edit the System Environment Variables. It may pop behind any open windows - if so, bring it to the front. Click Environment Variables.
    • Note: If any of the below variables aren't present, click on "Add" to add them
    • In User Variables, Inspect HOME and make sure it points to something like C:\Users\You.
    • In System Variables, double-click Path and make sure an entry for %USERPROFILE%\emacs-shared\bin is present at the very top.
    • In System Variables, double-click Path and make sure an entry for C:\Program Files\Emacs\emacs-30.2\bin is present at the end. If you see an entry for a different version of Emacs, change it to have this content instead and remove any duplicates of it.
    • Click OK
    • Relaunch any open Git Bash or MSYS2 windows

If upgrading:

  • Unpin any pinned Emacs icons
  • Change any existing desktop icons to point to C:\Program Files\Emacs\emacs-30.2\bin\runemacs.exe.

Install Emacs on macOS

We'll install the emacs-plus cask from Homebrew. Use the stable cask (emacs-plus-app, currently Emacs 30.2). Trust the whole tap rather than the individual cask: brew upgrade evaluates the tap's other casks, so trusting only emacs-plus-app still fails later with a Refusing to load cask ... emacs-plus-app@master from untrusted tap error when upgrading.

brew tap d12frosted/emacs-plus
brew trust d12frosted/emacs-plus
brew install --cask emacs-plus-app

If you prefer the development cask instead (emacs-plus-app@master, Emacs 32 from master):

brew tap d12frosted/emacs-plus
brew trust d12frosted/emacs-plus
brew install --cask emacs-plus-app@master

Ignore unrelated Homebrew warnings such as Cask emacs was renamed to emacs-app; that refers to the official emacs cask, not emacs-plus.

If you get an error when starting Emacs like "dyld[48068]: Library not loaded: /opt/homebrew/opt/tree-sitter/lib/libtree-sitter.0.23.dylib", when you may need to reinstall the XCode Commandline Tools, then check System Update for any updates to it, and then reboot to make the changes take effect. After that, try installing emacs-plus again per the above instructions.

If native compilation starts failing with errors like ld: library 'emutls_w' not found and libgccjit.so: error: error invoking gcc driver, the installed Emacs bundle was built against an older gcc/libgccjit than the one Homebrew currently has (a brew upgrade of gcc removes the older version's runtime libraries). Upgrade to the latest build of the cask to fix it:

brew upgrade --cask emacs-plus-app

You'll also probably want to go into System Settings -> Privacy & Security -> Full Disk Acccess and add Emacs, so that it can open files from any location.

Install Emacs on Arch Linux

  • If you want Emacs to be hyper-fast and stable but require a bit of extra setup, install the emacs-lucid AUR package.
  • If you want Emacs to be reasonably fast, install the emacs package.
  • If you are on Wayland (the default window system) and want better font hinting at the cost of much slower editing, install the emacs-wayland package.

Emacs Lucid Setup

If you're using emacs-lucid, you'll probably want Xresource settings like this for dark background menus on a 4k hi-res display, stored in a file called ~/.Xresources:

Emacs.pane.menubar.buttonForeground: white
Emacs.pane.menubar.cursor: left_ptr
Emacs.pane.menubar.horizontalSpacing: 12
Emacs.pane.menubar.verticalSpacing: 8

To apply the changes, run xrdb -merge ~/.Xresources and then restart Emacs. On most window environments, the ~/.Xresources file should be automatically read after logging in.

Install Emacs on Ubuntu

We'll build from scratch, since no PPAs have consistently had latest version releases in a timely way.

  • Uninstall any versions of Emacs that were previously installed by apt or dpkg.
  • Edit /etc/apt/sources.list and uncomment all #deb-src lines that match deb lines and run sudo apt update.
  • Follow these instructions, derived from this post:
sudo apt build-dep -y emacs
sudo apt install libjansson4 libjansson-dev gnutls-bin
cd build/emacs
curl -o - https://ftp.gnu.org/gnu/emacs/emacs-30.2.tar.gz | tar -xzf -
cd emacs-30.2
./autogen.sh
./configure
make -j$(proc)
sudo make install

Fonts

Typically we install the Fira Code font. This can be configured with the my-default-font setting.

macOS

Download Fira Code, open the zip, open the ttf folder, select all fonts, control-click and choose Open to install them.

Windows

Download Fira Code and follow the instructions.

Arch Linux

paru -S ttf-fira-code

Ubuntu

apt-get install fonts-firacode

Download the emacs-shared code

cd ~/
git clone https://github.com/mwolson/emacs-shared.git

Set up PATH

macOS

You'll want to make sure that your path includes the correct version of Emacs and some helper scripts, ahead of the ancient version that comes with macOS. To do this, edit ~/.profile and add:

export PATH=~/emacs-shared/bin:~/bin:"$PATH"

Restart your Terminal app to make the change take effect. Sourcing the file is not enough, since macOS seems to perform indexing of location on program name.

Linux

You'll want to make sure that your path includes the correct version of Emacs and some helper scripts. To do this, edit ~/.bashrc and add:

export PATH=~/emacs-shared/bin:~/bin:"$PATH"

Restart your Terminal program to make the change take effect, or source the file.

Windows

We already took care of this earlier before setting up MSYS2.

Run bootstrap.sh

On Windows:

  • You will need to do the "Set up PATH" step first, otherwise it will fail.
  • For Git Bash and MSYS2 support, you may need to add something like this to .bashrc and restart any open Terminal windows:
if uname | grep "MINGW64_NT" > /dev/null 2>&1; then
    # for MSYS2
    export PATH="~/emacs-shared/bin":"/c/Windows/System32/OpenSSH":"/c/Program Files/Emacs/emacs-30.2/bin":/ucrt64/bin:"/c/Program Files/Git/bin":"$PATH"
elif uname | grep "MSYS_NT" > /dev/null 2>&1; then
    # for Git Bash
    export PATH="/c/Windows/System32/OpenSSH":"$PATH"
fi
  • Check .bashrc and update any PATH entries which have a different version of Emacs to instead point to /c/Program Files/Emacs/emacs-30.2/bin and restart Terminal.
  • You will want to open an "MSYS2 MinGW 64-bit" window (not Git Bash) and run the commands from there.

Commands to run regardless of OS:

cd ~/emacs-shared
./bootstrap.sh

To verify that PATH now has the correct entries, run emacs --version and make sure it shows the version number you'd expect.

Create a ~/.emacs.d/early-init.el file

mkdir -p ~/.emacs.d
cd ~/.emacs.d
emacs -q early-init.el  # or other editing command

early-init.el contents, change these as appropriate:

;; Configure emacs-shared
(setq my-emacs-path    "~/emacs-shared/")
(setq my-email-address "you@example.com")
(setq my-full-name     "Your Name")

;; Note - change the following to allow mise to automatically enable specific
;; versions of tools like nodejs from .tool-versions or mise.toml files in project
;; directories.
;;
;; Default value: disable it for all directories:
;; (setq my-mise-exclude-file-regexps '(".*"))
;;
;; Insecure: enable it for all directories:
;; (setq my-mise-exclude-file-regexps '())
;;
;; Better: disable it for a directory tree that has downloaded content:
;; (setq my-mise-exclude-file-regexps '("devel/github"))

;; Load shared early init file
(setq load-prefer-newer t)
(load (concat my-emacs-path "init/early-shared-init") nil nil nil t)

Create a ~/.emacs.d/init.el file

mkdir -p ~/.emacs.d
cd ~/.emacs.d
emacs -q init.el  # or other editing command

init.el contents, change these as appropriate:

;; Authinfo location for passwords and tokens
(setopt auth-sources '("~/.emacs.d/.authinfo"))

;; Load shared init file
(load (concat my-emacs-path "init/shared-init") nil nil nil t)

Start Emacs

Windows

Open Start Menu -> Emacs. This should point to the file C:\Program Files\Emacs\emacs-30.2\bin\runemacs.exe.

Windows Taskbar

To pin Emacs to the Taskbar / Quick Launch bar and have it behave correctly:

  • If an older version is already there, unpin Emacs from the launcher menu
  • Run Emacs from Start menu or a desktop shortcut
  • Pin it
  • Then right-click its Taskbar button, right-click "Emacs", click "Properties"
  • Change "C:\Program Files\Emacs\emacs-30.2\bin\emacs.exe" to "C:\Program Files\Emacs\emacs-30.2\bin\runemacs.exe"

macOS

Open Applications -> Emacs.

Linux

GUI frame:

emacs -n -c

Console frame:

emacs -nw

Extras

The following are optional steps.

Install Aspell

Install Aspell and an Aspell dictionary for your language if you want to support spell-checking. We've already done this for Windows in the Install MSYS2 section.

(macOS only) Install docker manpages

This isn't really related to Emacs, but if you're using Docker on macOS, it might not install the manpages. Here's how to do that:

git clone https://github.com/docker/docker.git
cd docker
make manpages
cd man
cp -R man* /usr/local/share/man/

(macOS only) Update man database

To force XCode manpages to be generated (may require granting your terminal program the ability to modify apps), along with the homebrew manpages, run the following:

sudo /usr/libexec/makewhatis /Applications/Xcode.app/Contents/Developer/usr/share/man
sudo /usr/libexec/makewhatis /opt/homebrew/share/man

(macOS only) Enable keyboard autorepeat

Run this in a Terminal window:

defaults write NSGlobalDomain ApplePressAndHoldEnabled -bool false

Then restart any open applications to apply the change to them.

Install grip or marked for markdown preview

By default marked is used to preview markdown pages.

Another option with slightly better output (though not apprioriate for private data) is grip. This will send the content to Github's API for rendering. Customize the Emacs markdown-command option if you would like to use grip.

Updating

To keep up-to-date on the latest emacs-shared changes, do:

cd ~/emacs-shared
git config submodule.recurse false
git pull
./bootstrap.sh

Maintenance

The following are tasks used to maintain the repo, and not required for a typical installation.

Set up hooks and tools for this repo

To initialize hooks, install the configured mise dependencies, and install the aube dependencies:

aubr init

To install the configured mise dependencies and aube dependencies:

aubr up

Build Git manpages

The Windows installer for Git doesn't include manpages. Some prebuilt ones will be made available after running bootstrap.sh.

If you want them to rebuild them to reflect the latest git-for-windows changes, do this:

pushd extra/git
git pull
popd

BUILD_GIT_MANPAGES=y ./bootstrap.sh

pushd share/man
git add . ; git add -u .
git commit -m "Build for commit ..."
git push upstream main
popd

Add New Submodules

Do this:

git submodule add --depth 1 https://github.com/path/to/module elisp/my-new-module

Ensure that the shallow = true line is present for that submodule in .gitmodules and sort the config.

Update bootstrap.sh to initialize the submodule and init/shared-init.el to add the load path.

Update Emacs Source Code

Do this:

pushd extra/emacs
git fetch --depth 1 origin tag emacs-30.2
git checkout emacs-30.2
popd

Back to README.md