pyrox.dev
1# Emacs {#module-services-emacs}
2
3<!--
4 Documentation contributors:
5 Damien Cassou @DamienCassou
6 Thomas Tuegel @ttuegel
7 Rodney Lorrimar @rvl
8 Adam Hoese @adisbladis
9 -->
10
11[Emacs](https://www.gnu.org/software/emacs/) is an
12extensible, customizable, self-documenting real-time display editor — and
13more. At its core is an interpreter for Emacs Lisp, a dialect of the Lisp
14programming language with extensions to support text editing.
15
16Emacs runs within a graphical desktop environment using the X Window System,
17but works equally well on a text terminal. Under
18macOS, a "Mac port" edition is available, which
19uses Apple's native GUI frameworks.
20
21Nixpkgs provides a superior environment for
22running Emacs. It's simple to create custom builds
23by overriding the default packages. Chaotic collections of Emacs Lisp code
24and extensions can be brought under control using declarative package
25management. NixOS even provides a
26{command}`systemd` user service for automatically starting the Emacs
27daemon.
28
29## Installing Emacs {#module-services-emacs-installing}
30
31Emacs can be installed in the normal way for Nix (see
32[](#sec-package-management)). In addition, a NixOS
33*service* can be enabled.
34
35### The Different Releases of Emacs {#module-services-emacs-releases}
36
37Nixpkgs defines several basic Emacs packages.
38The following are attributes belonging to the {var}`pkgs` set:
39
40 {var}`emacs`
41 : The latest stable version of Emacs using the [GTK 2](http://www.gtk.org)
42 widget toolkit.
43
44 {var}`emacs-nox`
45 : Emacs built without any dependency on X11 libraries.
46
47 {var}`emacsMacport`
48 : Emacs with the "Mac port" patches, providing a more native look and
49 feel under macOS.
50
51If those aren't suitable, then the following imitation Emacs editors are
52also available in Nixpkgs:
53[Zile](https://www.gnu.org/software/zile/),
54[mg](http://homepage.boetes.org/software/mg/),
55[Yi](http://yi-editor.github.io/),
56[jmacs](https://joe-editor.sourceforge.io/).
57
58### Adding Packages to Emacs {#module-services-emacs-adding-packages}
59
60Emacs includes an entire ecosystem of functionality beyond text editing,
61including a project planner, mail and news reader, debugger interface,
62calendar, and more.
63
64Most extensions are gotten with the Emacs packaging system
65({file}`package.el`) from
66[Emacs Lisp Package Archive (ELPA)](https://elpa.gnu.org/),
67[MELPA](https://melpa.org/),
68[MELPA Stable](https://stable.melpa.org/), and
69[Org ELPA](http://orgmode.org/elpa.html). Nixpkgs is
70regularly updated to mirror all these archives.
71
72Under NixOS, you can continue to use
73`package-list-packages` and
74`package-install` to install packages. You can also
75declare the set of Emacs packages you need using the derivations from
76Nixpkgs. The rest of this section discusses declarative installation of
77Emacs packages through nixpkgs.
78
79The first step to declare the list of packages you want in your Emacs
80installation is to create a dedicated derivation. This can be done in a
81dedicated {file}`emacs.nix` file such as:
82
83::: {.example #ex-emacsNix}
84### Nix expression to build Emacs with packages (`emacs.nix`)
85
86```nix
87/*
88This is a nix expression to build Emacs and some Emacs packages I like
89from source on any distribution where Nix is installed. This will install
90all the dependencies from the nixpkgs repository and build the binary files
91without interfering with the host distribution.
92
93To build the project, type the following from the current directory:
94
95$ nix-build emacs.nix
96
97To run the newly compiled executable:
98
99$ ./result/bin/emacs
100*/
101
102# The first non-comment line in this file indicates that
103# the whole file represents a function.
104{ pkgs ? import <nixpkgs> {} }:
105
106let
107 # The let expression below defines a myEmacs binding pointing to the
108 # current stable version of Emacs. This binding is here to separate
109 # the choice of the Emacs binary from the specification of the
110 # required packages.
111 myEmacs = pkgs.emacs;
112 # This generates an emacsWithPackages function. It takes a single
113 # argument: a function from a package set to a list of packages
114 # (the packages that will be available in Emacs).
115 emacsWithPackages = (pkgs.emacsPackagesFor myEmacs).emacsWithPackages;
116in
117 # The rest of the file specifies the list of packages to install. In the
118 # example, two packages (magit and zerodark-theme) are taken from
119 # MELPA stable.
120 emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [
121 magit # ; Integrate git <C-x g>
122 zerodark-theme # ; Nicolas' theme
123 ])
124 # Two packages (undo-tree and zoom-frm) are taken from MELPA.
125 ++ (with epkgs.melpaPackages; [
126 undo-tree # ; <C-x u> to show the undo tree
127 zoom-frm # ; increase/decrease font size for all buffers %lt;C-x C-+>
128 ])
129 # Three packages are taken from GNU ELPA.
130 ++ (with epkgs.elpaPackages; [
131 auctex # ; LaTeX mode
132 beacon # ; highlight my cursor when scrolling
133 nameless # ; hide current package name everywhere in elisp code
134 ])
135 # notmuch is taken from a nixpkgs derivation which contains an Emacs mode.
136 ++ [
137 pkgs.notmuch # From main packages set
138 ])
139```
140:::
141
142The result of this configuration will be an {command}`emacs`
143command which launches Emacs with all of your chosen packages in the
144{var}`load-path`.
145
146You can check that it works by executing this in a terminal:
147```ShellSession
148$ nix-build emacs.nix
149$ ./result/bin/emacs -q
150```
151and then typing `M-x package-initialize`. Check that you
152can use all the packages you want in this Emacs instance. For example, try
153switching to the zerodark theme through `M-x load-theme <RET> zerodark <RET> y`.
154
155::: {.tip}
156A few popular extensions worth checking out are: auctex, company,
157edit-server, flycheck, helm, iedit, magit, multiple-cursors, projectile,
158and yasnippet.
159:::
160
161The list of available packages in the various ELPA repositories can be seen
162with the following commands:
163::: {.example #module-services-emacs-querying-packages}
164### Querying Emacs packages
165
166```
167nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.elpaPackages
168nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.melpaPackages
169nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.melpaStablePackages
170nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.orgPackages
171```
172:::
173
174If you are on NixOS, you can install this particular Emacs for all users by
175putting the `emacs.nix` file in `/etc/nixos` and adding it to the list of
176system packages (see [](#sec-declarative-package-mgmt)). Simply modify your
177file {file}`configuration.nix` to make it contain:
178::: {.example #module-services-emacs-configuration-nix}
179### Custom Emacs in `configuration.nix`
180
181```nix
182{
183 environment.systemPackages = [
184 # [...]
185 (import ./emacs.nix { inherit pkgs; })
186 ];
187}
188```
189:::
190
191In this case, the next {command}`nixos-rebuild switch` will take
192care of adding your {command}`emacs` to the {var}`PATH`
193environment variable (see [](#sec-changing-config)).
194
195<!-- fixme: i think the following is better done with config.nix
196https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides
197-->
198
199If you are not on NixOS or want to install this particular Emacs only for
200yourself, you can do so by putting `emacs.nix` in `~/.config/nixpkgs` and
201adding it to your {file}`~/.config/nixpkgs/config.nix` (see
202[Nixpkgs manual](https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides)):
203::: {.example #module-services-emacs-config-nix}
204### Custom Emacs in `~/.config/nixpkgs/config.nix`
205
206```nix
207{
208 packageOverrides = super: let self = super.pkgs; in {
209 myemacs = import ./emacs.nix { pkgs = self; };
210 };
211}
212```
213:::
214
215In this case, the next `nix-env -f '<nixpkgs>' -iA
216myemacs` will take care of adding your emacs to the
217{var}`PATH` environment variable.
218
219### Advanced Emacs Configuration {#module-services-emacs-advanced}
220
221If you want, you can tweak the Emacs package itself from your
222{file}`emacs.nix`. For example, if you want to have a
223GTK 3-based Emacs instead of the default GTK 2-based binary and remove the
224automatically generated {file}`emacs.desktop` (useful if you
225only use {command}`emacsclient`), you can change your file
226{file}`emacs.nix` in this way:
227
228::: {.example #ex-emacsGtk3Nix}
229### Custom Emacs build
230
231```nix
232{ pkgs ? import <nixpkgs> {} }:
233let
234 myEmacs = (pkgs.emacs.override {
235 # Use gtk3 instead of the default gtk2
236 withGTK3 = true;
237 withGTK2 = false;
238 }).overrideAttrs (attrs: {
239 # I don't want emacs.desktop file because I only use
240 # emacsclient.
241 postInstall = (attrs.postInstall or "") + ''
242 rm $out/share/applications/emacs.desktop
243 '';
244 });
245in [ /* ... */ ]
246```
247:::
248
249After building this file as shown in [](#ex-emacsNix), you
250will get an GTK 3-based Emacs binary pre-loaded with your favorite packages.
251
252## Running Emacs as a Service {#module-services-emacs-running}
253
254NixOS provides an optional
255{command}`systemd` service which launches
256[Emacs daemon](https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html)
257with the user's login session.
258
259*Source:* {file}`modules/services/editors/emacs.nix`
260
261### Enabling the Service {#module-services-emacs-enabling}
262
263To install and enable the {command}`systemd` user service for Emacs
264daemon, add the following to your {file}`configuration.nix`:
265```nix
266{
267 services.emacs.enable = true;
268}
269```
270
271The {var}`services.emacs.package` option allows a custom
272derivation to be used, for example, one created by
273`emacsWithPackages`.
274
275Ensure that the Emacs server is enabled for your user's Emacs
276configuration, either by customizing the {var}`server-mode`
277variable, or by adding `(server-start)` to
278{file}`~/.emacs.d/init.el`.
279
280To start the daemon, execute the following:
281```ShellSession
282$ nixos-rebuild switch # to activate the new configuration.nix
283$ systemctl --user daemon-reload # to force systemd reload
284$ systemctl --user start emacs.service # to start the Emacs daemon
285```
286The server should now be ready to serve Emacs clients.
287
288### Starting the client {#module-services-emacs-starting-client}
289
290Ensure that the Emacs server is enabled, either by customizing the
291{var}`server-mode` variable, or by adding
292`(server-start)` to {file}`~/.emacs`.
293
294To connect to the Emacs daemon, run one of the following:
295```
296emacsclient FILENAME
297emacsclient --create-frame # opens a new frame (window)
298emacsclient --create-frame --tty # opens a new frame on the current terminal
299```
300
301### Configuring the {var}`EDITOR` variable {#module-services-emacs-editor-variable}
302
303<!--<title>{command}`emacsclient` as the Default Editor</title>-->
304
305If [](#opt-services.emacs.defaultEditor) is
306`true`, the {var}`EDITOR` variable will be set
307to a wrapper script which launches {command}`emacsclient`.
308
309Any setting of {var}`EDITOR` in the shell config files will
310override {var}`services.emacs.defaultEditor`. To make sure
311{var}`EDITOR` refers to the Emacs wrapper script, remove any
312existing {var}`EDITOR` assignment from
313{file}`.profile`, {file}`.bashrc`,
314{file}`.zshenv` or any other shell config file.
315
316If you have formed certain bad habits when editing files, these can be
317corrected with a shell alias to the wrapper script:
318```
319alias vi=$EDITOR
320```
321
322### Per-User Enabling of the Service {#module-services-emacs-per-user}
323
324In general, {command}`systemd` user services are globally enabled
325by symlinks in {file}`/etc/systemd/user`. In the case where
326Emacs daemon is not wanted for all users, it is possible to install the
327service but not globally enable it:
328```nix
329{
330 services.emacs.enable = false;
331 services.emacs.install = true;
332}
333```
334
335To enable the {command}`systemd` user service for just the
336currently logged in user, run:
337```
338systemctl --user enable emacs
339```
340This will add the symlink
341{file}`~/.config/systemd/user/emacs.service`.
342
343## Configuring Emacs {#module-services-emacs-configuring}
344
345If you want to only use extension packages from Nixpkgs, you can add
346`(setq package-archives nil)` to your init file.
347
348After the declarative Emacs package configuration has been tested,
349previously downloaded packages can be cleaned up by removing
350{file}`~/.emacs.d/elpa` (do make a backup first, in case you
351forgot a package).
352
353<!--
354 todo: is it worth documenting customizations for
355 server-switch-hook, server-done-hook?
356 -->
357
358### A Major Mode for Nix Expressions {#module-services-emacs-major-mode}
359
360Of interest may be {var}`melpaPackages.nix-mode`, which
361provides syntax highlighting for the Nix language. This is particularly
362convenient if you regularly edit Nix files.
363
364### Accessing man pages {#module-services-emacs-man-pages}
365
366You can use `woman` to get completion of all available
367man pages. For example, type `M-x woman <RET> nixos-rebuild <RET>.`
368