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/*
88 This is a nix expression to build Emacs and some Emacs packages I like
89 from source on any distribution where Nix is installed. This will install
90 all the dependencies from the nixpkgs repository and build the binary files
91 without interfering with the host distribution.
92
93 To build the project, type the following from the current directory:
94
95 $ nix-build emacs.nix
96
97 To 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{
105 pkgs ? import <nixpkgs> { },
106}:
107
108let
109 # The let expression below defines a myEmacs binding pointing to the
110 # current stable version of Emacs. This binding is here to separate
111 # the choice of the Emacs binary from the specification of the
112 # required packages.
113 myEmacs = pkgs.emacs;
114 # This generates an emacsWithPackages function. It takes a single
115 # argument: a function from a package set to a list of packages
116 # (the packages that will be available in Emacs).
117 emacsWithPackages = (pkgs.emacsPackagesFor myEmacs).emacsWithPackages;
118 # The rest of the file specifies the list of packages to install. In the
119 # example, two packages (magit and zerodark-theme) are taken from
120 # MELPA stable.
121in
122emacsWithPackages (
123 epkgs:
124 (with epkgs.melpaStablePackages; [
125 magit # ; Integrate git <C-x g>
126 zerodark-theme # ; Nicolas' theme
127 ])
128 # Two packages (undo-tree and zoom-frm) are taken from MELPA.
129 ++ (with epkgs.melpaPackages; [
130 undo-tree # ; <C-x u> to show the undo tree
131 zoom-frm # ; increase/decrease font size for all buffers %lt;C-x C-+>
132 ])
133 # Three packages are taken from GNU ELPA.
134 ++ (with epkgs.elpaPackages; [
135 auctex # ; LaTeX mode
136 beacon # ; highlight my cursor when scrolling
137 nameless # ; hide current package name everywhere in elisp code
138 ])
139 # notmuch is taken from a nixpkgs derivation which contains an Emacs mode.
140 ++ [
141 pkgs.notmuch # From main packages set
142 ]
143)
144```
145:::
146
147The result of this configuration will be an {command}`emacs`
148command which launches Emacs with all of your chosen packages in the
149{var}`load-path`.
150
151You can check that it works by executing this in a terminal:
152```ShellSession
153$ nix-build emacs.nix
154$ ./result/bin/emacs -q
155```
156and then typing `M-x package-initialize`. Check that you
157can use all the packages you want in this Emacs instance. For example, try
158switching to the zerodark theme through `M-x load-theme <RET> zerodark <RET> y`.
159
160::: {.tip}
161A few popular extensions worth checking out are: auctex, company,
162edit-server, flycheck, helm, iedit, magit, multiple-cursors, projectile,
163and yasnippet.
164:::
165
166The list of available packages in the various ELPA repositories can be seen
167with the following commands:
168::: {.example #module-services-emacs-querying-packages}
169### Querying Emacs packages
170
171```
172nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.elpaPackages
173nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.melpaPackages
174nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.melpaStablePackages
175nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.orgPackages
176```
177:::
178
179If you are on NixOS, you can install this particular Emacs for all users by
180putting the `emacs.nix` file in `/etc/nixos` and adding it to the list of
181system packages (see [](#sec-declarative-package-mgmt)). Simply modify your
182file {file}`configuration.nix` to make it contain:
183::: {.example #module-services-emacs-configuration-nix}
184### Custom Emacs in `configuration.nix`
185
186```nix
187{
188 environment.systemPackages = [
189 # [...]
190 (import ./emacs.nix { inherit pkgs; })
191 ];
192}
193```
194:::
195
196In this case, the next {command}`nixos-rebuild switch` will take
197care of adding your {command}`emacs` to the {var}`PATH`
198environment variable (see [](#sec-changing-config)).
199
200<!-- fixme: i think the following is better done with config.nix
201https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides
202-->
203
204If you are not on NixOS or want to install this particular Emacs only for
205yourself, you can do so by putting `emacs.nix` in `~/.config/nixpkgs` and
206adding it to your {file}`~/.config/nixpkgs/config.nix` (see
207[Nixpkgs manual](https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides)):
208::: {.example #module-services-emacs-config-nix}
209### Custom Emacs in `~/.config/nixpkgs/config.nix`
210
211```nix
212{
213 packageOverrides =
214 super:
215 let
216 self = super.pkgs;
217 in
218 {
219 myemacs = import ./emacs.nix { pkgs = self; };
220 };
221}
222```
223:::
224
225In this case, the next `nix-env -f '<nixpkgs>' -iA
226myemacs` will take care of adding your emacs to the
227{var}`PATH` environment variable.
228
229### Advanced Emacs Configuration {#module-services-emacs-advanced}
230
231If you want, you can tweak the Emacs package itself from your
232{file}`emacs.nix`. For example, if you want to have a
233GTK 3-based Emacs instead of the default GTK 2-based binary and remove the
234automatically generated {file}`emacs.desktop` (useful if you
235only use {command}`emacsclient`), you can change your file
236{file}`emacs.nix` in this way:
237
238::: {.example #ex-emacsGtk3Nix}
239### Custom Emacs build
240
241```nix
242{
243 pkgs ? import <nixpkgs> { },
244}:
245let
246 myEmacs =
247 (pkgs.emacs.override {
248 # Use gtk3 instead of the default gtk2
249 withGTK3 = true;
250 withGTK2 = false;
251 }).overrideAttrs
252 (attrs: {
253 # I don't want emacs.desktop file because I only use
254 # emacsclient.
255 postInstall = (attrs.postInstall or "") + ''
256 rm $out/share/applications/emacs.desktop
257 '';
258 });
259in
260[
261 # ...
262]
263```
264:::
265
266After building this file as shown in [](#ex-emacsNix), you
267will get an GTK 3-based Emacs binary pre-loaded with your favorite packages.
268
269## Running Emacs as a Service {#module-services-emacs-running}
270
271NixOS provides an optional
272{command}`systemd` service which launches
273[Emacs daemon](https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html)
274with the user's login session.
275
276*Source:* {file}`modules/services/editors/emacs.nix`
277
278### Enabling the Service {#module-services-emacs-enabling}
279
280To install and enable the {command}`systemd` user service for Emacs
281daemon, add the following to your {file}`configuration.nix`:
282```nix
283{ services.emacs.enable = true; }
284```
285
286The {var}`services.emacs.package` option allows a custom
287derivation to be used, for example, one created by
288`emacsWithPackages`.
289
290Ensure that the Emacs server is enabled for your user's Emacs
291configuration, either by customizing the {var}`server-mode`
292variable, or by adding `(server-start)` to
293{file}`~/.emacs.d/init.el`.
294
295To start the daemon, execute the following:
296```ShellSession
297$ nixos-rebuild switch # to activate the new configuration.nix
298$ systemctl --user daemon-reload # to force systemd reload
299$ systemctl --user start emacs.service # to start the Emacs daemon
300```
301The server should now be ready to serve Emacs clients.
302
303### Starting the client {#module-services-emacs-starting-client}
304
305Ensure that the Emacs server is enabled, either by customizing the
306{var}`server-mode` variable, or by adding
307`(server-start)` to {file}`~/.emacs`.
308
309To connect to the Emacs daemon, run one of the following:
310```
311emacsclient FILENAME
312emacsclient --create-frame # opens a new frame (window)
313emacsclient --create-frame --tty # opens a new frame on the current terminal
314```
315
316### Configuring the {var}`EDITOR` variable {#module-services-emacs-editor-variable}
317
318<!--<title>{command}`emacsclient` as the Default Editor</title>-->
319
320If [](#opt-services.emacs.defaultEditor) is
321`true`, the {var}`EDITOR` variable will be set
322to a wrapper script which launches {command}`emacsclient`.
323
324Any setting of {var}`EDITOR` in the shell config files will
325override {var}`services.emacs.defaultEditor`. To make sure
326{var}`EDITOR` refers to the Emacs wrapper script, remove any
327existing {var}`EDITOR` assignment from
328{file}`.profile`, {file}`.bashrc`,
329{file}`.zshenv` or any other shell config file.
330
331If you have formed certain bad habits when editing files, these can be
332corrected with a shell alias to the wrapper script:
333```
334alias vi=$EDITOR
335```
336
337### Per-User Enabling of the Service {#module-services-emacs-per-user}
338
339In general, {command}`systemd` user services are globally enabled
340by symlinks in {file}`/etc/systemd/user`. In the case where
341Emacs daemon is not wanted for all users, it is possible to install the
342service but not globally enable it:
343```nix
344{
345 services.emacs.enable = false;
346 services.emacs.install = true;
347}
348```
349
350To enable the {command}`systemd` user service for just the
351currently logged in user, run:
352```
353systemctl --user enable emacs
354```
355This will add the symlink
356{file}`~/.config/systemd/user/emacs.service`.
357
358## Configuring Emacs {#module-services-emacs-configuring}
359
360If you want to only use extension packages from Nixpkgs, you can add
361`(setq package-archives nil)` to your init file.
362
363After the declarative Emacs package configuration has been tested,
364previously downloaded packages can be cleaned up by removing
365{file}`~/.emacs.d/elpa` (do make a backup first, in case you
366forgot a package).
367
368<!--
369 todo: is it worth documenting customizations for
370 server-switch-hook, server-done-hook?
371 -->
372
373### A Major Mode for Nix Expressions {#module-services-emacs-major-mode}
374
375Of interest may be {var}`melpaPackages.nix-mode`, which
376provides syntax highlighting for the Nix language. This is particularly
377convenient if you regularly edit Nix files.
378
379### Accessing man pages {#module-services-emacs-man-pages}
380
381You can use `woman` to get completion of all available
382man pages. For example, type `M-x woman <RET> nixos-rebuild <RET>.`
383