···
1
+
<chapter xmlns="http://docbook.org/ns/docbook"
2
+
xmlns:xlink="http://www.w3.org/1999/xlink"
3
+
xmlns:xi="http://www.w3.org/2001/XInclude"
5
+
xml:id="module-services-emacs">
10
+
Documentation contributors:
11
+
Damien Cassou @DamienCassou
12
+
Thomas Tuegel @ttuegel
13
+
Rodney Lorrimar @rvl
17
+
<link xlink:href="http://www.gnu.org/software/emacs/">Emacs</link>
18
+
is an extensible, customizable, self-documenting real-time display
19
+
editor — and more. At its core is an interpreter for Emacs Lisp, a
20
+
dialect of the Lisp programming language with extensions to
21
+
support text editing.
25
+
Emacs runs within a graphical desktop environment using the X
26
+
Window System, but works equally well on a text terminal. Under
27
+
<productname>OS X</productname>, a "Mac port" edition is
28
+
available, which uses Apple's native GUI frameworks.
32
+
<productname>Nixpkgs</productname> provides a superior environment
33
+
for running <application>Emacs</application>. It's simple to
34
+
create custom builds by overriding the default packages. Chaotic
35
+
collections of Emacs Lisp code and extensions can be brought under
36
+
control using declarative package
37
+
management. <productname>NixOS</productname> even provides a
38
+
<command>systemd</command> user service for automatically
39
+
starting the Emacs daemon.
43
+
<title>Installing <application>Emacs</application></title>
46
+
Emacs can installed in the normal way for Nix (see <xref
47
+
linkend="sec-package-management" />). In addition, a NixOS
48
+
<emphasis>service</emphasis> can be enabled.
52
+
<title>The Different Releases of Emacs</title>
55
+
<productname>Nixpkgs</productname> defines several basic Emacs
56
+
packages. The following are attributes belonging to the
57
+
<varname>pkgs</varname> set:
61
+
<term><varname>emacs</varname></term>
62
+
<term><varname>emacs24</varname></term>
65
+
The latest stable version of Emacs 24 using the <link
66
+
xlink:href="http://www.gtk.org">GTK+ 2</link> widget
72
+
<term><varname>emacs24-nox</varname></term>
75
+
Emacs 24 built without any dependency on X11
81
+
<term><varname>emacs24Macport</varname></term>
84
+
Emacs 24 with the "Mac port" patches, providing a more
85
+
native look and feel under OS X.
90
+
<term><varname>emacs25pre</varname></term>
93
+
A pretest version of what will become the first
94
+
version of Emacs 25.
102
+
If those aren't suitable, then the following imitation Emacs
103
+
editors are also available in Nixpkgs:
104
+
<link xlink:href="https://www.gnu.org/software/zile/">Zile</link>,
105
+
<link xlink:href="http://homepage.boetes.org/software/mg/">mg</link>,
106
+
<link xlink:href="http://yi-editor.github.io/">Yi</link>.
111
+
<title>Adding Packages to Emacs</title>
113
+
Emacs includes an entire ecosystem of functionality beyond
114
+
text editing, including a project planner, mail and news
115
+
reader, debugger interface, calendar, and more.
119
+
Most extensions are gotten with the Emacs packaging system
120
+
(<filename>package.el</filename>) from <link
121
+
xlink:href="https://elpa.gnu.org/">Emacs Lisp Package Archive
122
+
(<acronym>ELPA</acronym>)</link>,
123
+
<link xlink:href="https://melpa.org/"><acronym>MELPA</acronym></link>,
124
+
<link xlink:href="https://stable.melpa.org/">MELPA Stable</link>,
125
+
and <link xlink:href="http://orgmode.org/elpa.html">Org ELPA</link>.
126
+
Nixpkgs is regularly updated to mirror all these archives.
130
+
Under NixOS, you can continue to use
131
+
<function>package-list-packages</function> and
132
+
<function>package-install</function> to install packages. You
133
+
can also declare the set of Emacs packages you need using the
134
+
derivations from Nixpkgs. The rest of this section discusses
135
+
declarative installation of Emacs packages through nixpkgs.
140
+
This documentation describes the new Emacs packages
141
+
framework in NixOS 16.03
142
+
(<varname>emacsPackagesNg</varname>) which should not be
143
+
confused with the previous and deprecated framework
144
+
(<varname>emacs24Packages</varname>).
149
+
The first step to declare the list of packages you want in
150
+
your Emacs installation is to create a dedicated
151
+
derivation. This can be done in a dedicated
152
+
<filename>emacs.nix</filename> file such as:
154
+
<example xml:id="ex-emacsNix">
155
+
<title>Nix expression to build Emacs with packages (<filename>emacs.nix</filename>)</title>
156
+
<programlisting language="nix">
158
+
This is a nix expression to build Emacs and some Emacs packages I like
159
+
from source on any distribution where Nix is installed. This will install
160
+
all the dependencies from the nixpkgs repository and build the binary files
161
+
without interfering with the host distribution.
163
+
To build the project, type the following from the current directory:
165
+
$ nix-build emacs.nix
167
+
To run the newly compiled executable:
169
+
$ ./result/bin/emacs
171
+
{ pkgs ? import <nixpkgs> {} }: <co xml:id="ex-emacsNix-1" />
174
+
myEmacs = pkgs.emacs; <co xml:id="ex-emacsNix-2" />
175
+
emacsWithPackages = (pkgs.emacsPackagesNgGen myEmacs).emacsWithPackages; <co xml:id="ex-emacsNix-3" />
177
+
emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [ <co xml:id="ex-emacsNix-4" />
178
+
magit # ; Integrate git <C-x g>
179
+
zerodark-theme # ; Nicolas' theme
180
+
]) ++ (with epkgs.melpaPackages; [ <co xml:id="ex-emacsNix-5" />
181
+
undo-tree # ; <C-x u> to show the undo tree
182
+
zoom-frm # ; increase/decrease font size for all buffers %lt;C-x C-+>
183
+
]) ++ (with epkgs.elpaPackages; [ <co xml:id="ex-emacsNix-6" />
184
+
auctex # ; LaTeX mode
185
+
beacon # ; highlight my cursor when scrolling
186
+
nameless # ; hide current package name everywhere in elisp code
188
+
pkgs.notmuch # From main packages set <co xml:id="ex-emacsNix-7" />
194
+
<callout arearefs="ex-emacsNix-1">
196
+
The first non-comment line in this file
197
+
(<literal>{ pkgs ? ... }</literal>)
198
+
indicates that the whole file represents a function.
202
+
<callout arearefs="ex-emacsNix-2">
204
+
The <varname>let</varname> expression below defines a
205
+
<varname>myEmacs</varname> binding pointing to the current
206
+
stable version of Emacs. This binding is here to separate the
207
+
choice of the Emacs binary from the specification of the
212
+
<callout arearefs="ex-emacsNix-3">
214
+
This generates an <varname>emacsWithPackages</varname>
215
+
function. It takes a single argument: a function from a
216
+
package set to a list of packages (the packages that will
217
+
be available in Emacs).
221
+
<callout arearefs="ex-emacsNix-4">
223
+
The rest of the file specifies the list of packages to
224
+
install. In the example, two packages
225
+
(<varname>magit</varname> and
226
+
<varname>zerodark-theme</varname>) are taken from MELPA
231
+
<callout arearefs="ex-emacsNix-5">
233
+
Two packages (<varname>undo-tree</varname> and
234
+
<varname>zoom-frm</varname>) are taken from MELPA.
238
+
<callout arearefs="ex-emacsNix-6">
239
+
<para>Three packages are taken from GNU ELPA.</para>
242
+
<callout arearefs="ex-emacsNix-7">
244
+
<varname>notmuch</varname> is taken from a nixpkgs derivation
245
+
which contains an Emacs mode.
253
+
The result of this configuration will be an
254
+
<command>emacs</command> command which launches Emacs with all
255
+
of your chosen packages in the <varname>load-path</varname>.
259
+
You can check that it works by executing this in a terminal:
262
+
$ nix-build emacs.nix
263
+
$ ./result/bin/emacs -q
266
+
and then typing <literal>M-x package-initialize</literal>.
267
+
Check that you can use all the packages you want in this
268
+
Emacs instance. For example, try switching to the zerodark
270
+
<literal>M-x load-theme <RET> zerodark <RET> y</literal>.
275
+
A few popular extensions worth checking out are: auctex,
276
+
company, edit-server, flycheck, helm, iedit, magit,
277
+
multiple-cursors, projectile, and yasnippet.
282
+
The list of available packages in the various ELPA
283
+
repositories can be seen with the following commands:
285
+
<title>Querying Emacs packages</title>
286
+
<programlisting><![CDATA[
287
+
nix-env -f "<nixpkgs>" -qaP -A emacsPackagesNg.elpaPackages
288
+
nix-env -f "<nixpkgs>" -qaP -A emacsPackagesNg.melpaPackages
289
+
nix-env -f "<nixpkgs>" -qaP -A emacsPackagesNg.melpaStablePackages
290
+
nix-env -f "<nixpkgs>" -qaP -A emacsPackagesNg.orgPackages
291
+
]]></programlisting>
296
+
If you are on NixOS, you can install this particular Emacs for
297
+
all users by adding it to the list of system packages
298
+
(see <xref linkend="sec-declarative-package-mgmt" />). Simply
299
+
modify your file <filename>configuration.nix</filename> to
302
+
<title>Custom Emacs in <filename>configuration.nix</filename></title>
303
+
<programlisting><![CDATA[
305
+
environment.systemPackages = [
307
+
(import /path/to/emacs.nix { inherit pkgs; })
310
+
]]></programlisting>
315
+
In this case, the next <command>nixos-rebuild switch</command>
316
+
will take care of adding your <command>emacs</command> to the
317
+
<varname>PATH</varname> environment variable
318
+
(see <xref linkend="sec-changing-config" />).
321
+
<!-- fixme: i think the following is better done with config.nix
322
+
https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides
325
+
If you are not on NixOS or want to install this particular
326
+
Emacs only for yourself, you can do so by adding it to your
327
+
<filename>~/.nixpkgs/config.nix</filename>
328
+
(see <link xlink:href="http://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides">Nixpkgs manual</link>):
330
+
<title>Custom Emacs in <filename>~/.nixpkgs/system.nix</filename></title>
331
+
<programlisting><![CDATA[
333
+
packageOverrides = super: let self = super.pkgs; in {
334
+
myemacs = import /path/to/emacs.nix { pkgs = self; };
337
+
]]></programlisting>
342
+
In this case, the next
343
+
<literal>nix-env -f '<nixpkgs>' -iA myemacs</literal>
344
+
will take care of adding your emacs to the
345
+
<varname>PATH</varname> environment variable.
350
+
<title>Advanced Emacs Configuration</title>
353
+
If you want, you can tweak the Emacs package itself from your
354
+
<filename>emacs.nix</filename>. For example, if you want to
355
+
have a GTK+3-based Emacs instead of the default GTK+2-based
356
+
binary and remove the automatically generated
357
+
<filename>emacs.desktop</filename> (useful is you only use
358
+
<command>emacsclient</command>), you can change your file
359
+
<filename>emacs.nix</filename> in this way:
362
+
<example xml:id="ex-emacsGtk3Nix">
363
+
<title>Custom Emacs build</title>
364
+
<programlisting><![CDATA[
365
+
{ pkgs ? import <nixpkgs> {} }:
367
+
myEmacs = pkgs.lib.overrideDerivation (pkgs.emacs.override {
368
+
# Use gtk3 instead of the default gtk2
372
+
# I don't want emacs.desktop file because I only use
374
+
postInstall = attrs.postInstall + ''
375
+
rm $out/share/applications/emacs.desktop
379
+
]]></programlisting>
383
+
After building this file as shown in <xref linkend="ex-emacsNix" />,
384
+
you will get an GTK3-based Emacs binary pre-loaded with your
391
+
<title>Running Emacs as a Service</title>
393
+
<productname>NixOS</productname> provides an optional
394
+
<command>systemd</command> service which launches
395
+
<link xlink:href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html">
398
+
with the user's login session.
402
+
<emphasis>Source:</emphasis>
403
+
<filename>modules/services/editors/emacs.nix</filename>
407
+
<title>Enabling the Service</title>
410
+
To install and enable the <command>systemd</command>
411
+
user service for Emacs daemon, add the following to your
412
+
<filename>configuration.nix</filename>:
414
+
<programlisting><![CDATA[
415
+
services.emacs.enable = true;
416
+
services.emacs.package = import /home/cassou/.emacs.d { pkgs = pkgs; };
417
+
]]></programlisting>
421
+
The <varname>services.emacs.package</varname> option allows a
422
+
custom derivation to be used, for example, one created by
423
+
<function>emacsWithPackages</function>.
427
+
Ensure that the Emacs server is enabled for your user's Emacs
428
+
configuration, either by customizing the
429
+
<varname>server-mode</varname> variable, or by adding
430
+
<literal>(server-start)</literal> to
431
+
<filename>~/.emacs.d/init.el</filename>.
435
+
To start the daemon, execute the following:
438
+
$ nixos-rebuild switch # to activate the new configuration.nix
439
+
$ systemctl --user daemon-reload # to force systemd reload
440
+
$ systemctl --user start emacs.service # to start the Emacs daemon
443
+
The server should now be ready to serve Emacs clients.
449
+
<title>Starting the client</title>
451
+
Ensure that the emacs server is enabled, either by customizing
452
+
the <varname>server-mode</varname> variable, or by adding
453
+
<literal>(server-start)</literal> to
454
+
<filename>~/.emacs</filename>.
458
+
To connect to the emacs daemon, run one of the following:
459
+
<programlisting><![CDATA[
460
+
emacsclient FILENAME
461
+
emacsclient --create-frame # opens a new frame (window)
462
+
emacsclient --create-frame --tty # opens a new frame on the current terminal
463
+
]]></programlisting>
468
+
<title>Configuring the <varname>EDITOR</varname> variable</title>
469
+
<!--<title><command>emacsclient</command> as the Default Editor</title>-->
472
+
If <varname>services.emacs.defaultEditor</varname> is
473
+
<literal>true</literal>, the <varname>EDITOR</varname> variable
474
+
will be set to a wrapper script which launches
475
+
<command>emacsclient</command>.
479
+
Any setting of <varname>EDITOR</varname> in the shell config
480
+
files will override
481
+
<varname>services.emacs.defaultEditor</varname>.
482
+
To make sure <varname>EDITOR</varname> refers to the Emacs
483
+
wrapper script, remove any existing <varname>EDITOR</varname>
484
+
assignment from <filename>.profile</filename>,
485
+
<filename>.bashrc</filename>, <filename>.zshenv</filename> or
486
+
any other shell config file.
490
+
If you have formed certain bad habits when editing files,
491
+
these can be corrected with a shell alias to the wrapper
493
+
<programlisting>alias vi=$EDITOR</programlisting>
498
+
<title>Per-User Enabling of the Service</title>
501
+
In general, <command>systemd</command> user services
502
+
are globally enabled by symlinks in
503
+
<filename>/etc/systemd/user</filename>. In the case where
504
+
Emacs daemon is not wanted for all users, it is possible to
505
+
install the service but not globally enable it:
507
+
<programlisting><![CDATA[
508
+
services.emacs.enable = false;
509
+
services.emacs.install = true;
510
+
]]></programlisting>
514
+
To enable the <command>systemd</command> user service for just
515
+
the currently logged in user, run:
517
+
<programlisting>systemctl --user enable emacs</programlisting>
519
+
This will add the symlink
520
+
<filename>~/.config/systemd/user/emacs.service</filename>.
526
+
<title>Configuring Emacs</title>
529
+
The Emacs init file should be changed to load the extension
530
+
packages at startup:
533
+
<title>Package initialization in <filename>.emacs</filename></title>
534
+
<programlisting><![CDATA[
537
+
;; optional. makes unpure packages archives unavailable
538
+
(setq package-archives nil)
540
+
(setq package-enable-at-startup nil)
541
+
(package-initialize)
542
+
]]></programlisting>
547
+
After the declarative emacs package configuration has been
548
+
tested, previously downloaded packages can be cleaned up by
549
+
removing <filename>~/.emacs.d/elpa</filename> (do make a backup
550
+
first, in case you forgot a package).
554
+
todo: is it worth documenting customizations for
555
+
server-switch-hook, server-done-hook?
559
+
<title>A Major Mode for Nix Expressions</title>
562
+
Of interest may be <varname>melpaPackages.nix-mode</varname>,
563
+
which provides syntax highlighting for the Nix language. This is
564
+
particularly convenient if you regularly edit Nix files.
569
+
<title>Accessing man pages</title>
571
+
You can use <function>woman</function> to get completion of all
572
+
available man pages. For example, type <literal>M-x woman
573
+
<RET> nixos-rebuild <RET>.</literal>
pyrox.dev