Skip to content

Latest commit

 

History

History
502 lines (333 loc) · 18 KB

install.md

File metadata and controls

502 lines (333 loc) · 18 KB

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.

(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,gopls,make,ninja,ripgrep,rust}
  • 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

(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:

sudo paru -S asdf-vm aspell-en base-devel basedpyright clang cmake fd gnutls gopls libssh2-devel make man-db man-pages ninja openssh ripgrep rust-analyzer zls

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

sudo paru -S clojure clojure-lsp-bin jdtls leiningen omnisharp-roslyn-bin zprint-bin

(Optional) Install aider

You'll need to install aider in order to use some AI features with aidermacs. It's recommended to install uv first, and then do:

uv tool install --force --python python3.12 aider-chat@latest

Make sure to also add export PATH=~/.local/bin:"$PATH" or similar to your .bashrc or .zshenv file and then restart the shell to make the aider command available.

Install basedpyright

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

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 install clojure/tools/clojure leiningen
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]}

Install cmake

You'll need to install cmake in order to build vterm, a terminal emulator for Emacs. On Mac, install the cmake and libtool packages from homebrew.

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 do a manual install of asdf, configure your shell to work with it, restart any open terminals, and then install the latest LTS node.js version and pnpm with:

asdf plugin add nodejs https://github.com/taybart/asdf-nodejs
asdf cmd nodejs update-nodebuild
asdf install nodejs $(asdf cmd nodejs resolve lts --latest-available)
asdf set -u nodejs $(asdf cmd nodejs resolve lts --latest-installed)

asdf plugin add pnpm
asdf install pnpm latest
asdf set -u pnpm latest

Install Omnisharp (optional)

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

Note: C-c . . currently doesn't work as of Emacs 29.4.

Windows

Run choco install omnisharp

Mac OS

Run:

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.

(Optional) Install vterm shell integration

In order to get the most use out of vterm, be sure to configure your shell for vterm.

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 29.4. 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-29.4\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-29.4\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-29.4\bin\runemacs.exe.

Install Emacs on macOS

We'll install the emacs-plus version from Homebrew:

brew tap d12frosted/emacs-plus
brew install emacs-plus@29
osascript -e 'tell application "Finder" to make alias file to posix file "/opt/homebrew/opt/emacs-plus@29/Emacs.app" at POSIX file "/Applications" with properties {name:"Emacs.app"}'

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.

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 are on Wayland (the default window system), install the emacs-wayland package, otherwise install emacs.

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-29.4.tar.gz | tar -xzf -
cd emacs-29.4
./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-29.4/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-29.4/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-email-address "[email protected]")
(setq my-full-name     "Your Name")
(setq my-emacs-path    "~/emacs-shared/")

;; Load shared early init file
(load-file (concat my-emacs-path "init/early-shared-init.el"))

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 any AI passwords
(setopt auth-sources '("~/.emacs.d/.authinfo"))

;; Load shared init file
(load-file (concat my-emacs-path "init/shared-init.el"))

Start Emacs

Windows

Open Start Menu -> Emacs. This should point to the file C:\Program Files\Emacs\emacs-29.4\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-29.4\bin\emacs.exe" to "C:\Program Files\Emacs\emacs-29.4\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 pull
./bootstrap.sh

Maintenance

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

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-29.4
git checkout emacs-29.4
popd

Back to README.md