pyrox.dev
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"
4 version="5.0"
5 xml:id="module-services-emacs">
6
7 <title>Emacs</title>
8
9 <!--
10 Documentation contributors:
11 Damien Cassou @DamienCassou
12 Thomas Tuegel @ttuegel
13 Rodney Lorrimar @rvl
14 -->
15
16 <para>
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.
22 </para>
23
24 <para>
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>macOS</productname>, a "Mac port" edition is
28 available, which uses Apple's native GUI frameworks.
29 </para>
30
31 <para>
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.
40 </para>
41
42 <section>
43 <title>Installing <application>Emacs</application></title>
44
45 <para>
46 Emacs can be installed in the normal way for Nix (see
47 <xref linkend="sec-package-management" />).
48 In addition, a NixOS <emphasis>service</emphasis>
49 can be enabled.
50 </para>
51
52 <section>
53 <title>The Different Releases of Emacs</title>
54
55 <para>
56 <productname>Nixpkgs</productname> defines several basic Emacs
57 packages. The following are attributes belonging to the
58 <varname>pkgs</varname> set:
59
60 <variablelist>
61 <varlistentry>
62 <term><varname>emacs</varname></term>
63 <term><varname>emacs25</varname></term>
64 <listitem>
65 <para>
66 The latest stable version of Emacs 25 using the <link
67 xlink:href="http://www.gtk.org">GTK+ 2</link> widget
68 toolkit.
69 </para>
70 </listitem>
71 </varlistentry>
72 <varlistentry>
73 <term><varname>emacs25-nox</varname></term>
74 <listitem>
75 <para>
76 Emacs 25 built without any dependency on X11
77 libraries.
78 </para>
79 </listitem>
80 </varlistentry>
81 <varlistentry>
82 <term><varname>emacsMacport</varname></term>
83 <term><varname>emacs25Macport</varname></term>
84 <listitem>
85 <para>
86 Emacs 25 with the "Mac port" patches, providing a more
87 native look and feel under macOS.
88 </para>
89 </listitem>
90 </varlistentry>
91 </variablelist>
92 </para>
93
94 <para>
95 If those aren't suitable, then the following imitation Emacs
96 editors are also available in Nixpkgs:
97 <link xlink:href="https://www.gnu.org/software/zile/">Zile</link>,
98 <link xlink:href="http://homepage.boetes.org/software/mg/">mg</link>,
99 <link xlink:href="http://yi-editor.github.io/">Yi</link>.
100 </para>
101
102 </section>
103 <section>
104 <title>Adding Packages to Emacs</title>
105 <para>
106 Emacs includes an entire ecosystem of functionality beyond
107 text editing, including a project planner, mail and news
108 reader, debugger interface, calendar, and more.
109 </para>
110
111 <para>
112 Most extensions are gotten with the Emacs packaging system
113 (<filename>package.el</filename>) from <link
114 xlink:href="https://elpa.gnu.org/">Emacs Lisp Package Archive
115 (<acronym>ELPA</acronym>)</link>,
116 <link xlink:href="https://melpa.org/"><acronym>MELPA</acronym></link>,
117 <link xlink:href="https://stable.melpa.org/">MELPA Stable</link>,
118 and <link xlink:href="http://orgmode.org/elpa.html">Org ELPA</link>.
119 Nixpkgs is regularly updated to mirror all these archives.
120 </para>
121
122 <para>
123 Under NixOS, you can continue to use
124 <function>package-list-packages</function> and
125 <function>package-install</function> to install packages. You
126 can also declare the set of Emacs packages you need using the
127 derivations from Nixpkgs. The rest of this section discusses
128 declarative installation of Emacs packages through nixpkgs.
129 </para>
130
131 <note>
132 <para>
133 This documentation describes the new Emacs packages
134 framework in NixOS 16.03
135 (<varname>emacsPackagesNg</varname>) which should not be
136 confused with the previous and deprecated framework
137 (<varname>emacs24Packages</varname>).
138 </para>
139 </note>
140
141 <para>
142 The first step to declare the list of packages you want in
143 your Emacs installation is to create a dedicated
144 derivation. This can be done in a dedicated
145 <filename>emacs.nix</filename> file such as:
146
147 <example xml:id="ex-emacsNix">
148 <title>Nix expression to build Emacs with packages (<filename>emacs.nix</filename>)</title>
149 <programlisting language="nix">
150/*
151This is a nix expression to build Emacs and some Emacs packages I like
152from source on any distribution where Nix is installed. This will install
153all the dependencies from the nixpkgs repository and build the binary files
154without interfering with the host distribution.
155
156To build the project, type the following from the current directory:
157
158$ nix-build emacs.nix
159
160To run the newly compiled executable:
161
162$ ./result/bin/emacs
163*/
164{ pkgs ? import <nixpkgs> {} }: <co xml:id="ex-emacsNix-1" />
165
166let
167 myEmacs = pkgs.emacs; <co xml:id="ex-emacsNix-2" />
168 emacsWithPackages = (pkgs.emacsPackagesNgGen myEmacs).emacsWithPackages; <co xml:id="ex-emacsNix-3" />
169in
170 emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [ <co xml:id="ex-emacsNix-4" />
171 magit # ; Integrate git <C-x g>
172 zerodark-theme # ; Nicolas' theme
173 ]) ++ (with epkgs.melpaPackages; [ <co xml:id="ex-emacsNix-5" />
174 undo-tree # ; <C-x u> to show the undo tree
175 zoom-frm # ; increase/decrease font size for all buffers %lt;C-x C-+>
176 ]) ++ (with epkgs.elpaPackages; [ <co xml:id="ex-emacsNix-6" />
177 auctex # ; LaTeX mode
178 beacon # ; highlight my cursor when scrolling
179 nameless # ; hide current package name everywhere in elisp code
180 ]) ++ [
181 pkgs.notmuch # From main packages set <co xml:id="ex-emacsNix-7" />
182 ])
183</programlisting>
184 </example>
185
186 <calloutlist>
187 <callout arearefs="ex-emacsNix-1">
188 <para>
189 The first non-comment line in this file
190 (<literal>{ pkgs ? ... }</literal>)
191 indicates that the whole file represents a function.
192 </para>
193 </callout>
194
195 <callout arearefs="ex-emacsNix-2">
196 <para>
197 The <varname>let</varname> expression below defines a
198 <varname>myEmacs</varname> binding pointing to the current
199 stable version of Emacs. This binding is here to separate the
200 choice of the Emacs binary from the specification of the
201 required packages.
202 </para>
203 </callout>
204
205 <callout arearefs="ex-emacsNix-3">
206 <para>
207 This generates an <varname>emacsWithPackages</varname>
208 function. It takes a single argument: a function from a
209 package set to a list of packages (the packages that will
210 be available in Emacs).
211 </para>
212 </callout>
213
214 <callout arearefs="ex-emacsNix-4">
215 <para>
216 The rest of the file specifies the list of packages to
217 install. In the example, two packages
218 (<varname>magit</varname> and
219 <varname>zerodark-theme</varname>) are taken from MELPA
220 stable.
221 </para>
222 </callout>
223
224 <callout arearefs="ex-emacsNix-5">
225 <para>
226 Two packages (<varname>undo-tree</varname> and
227 <varname>zoom-frm</varname>) are taken from MELPA.
228 </para>
229 </callout>
230
231 <callout arearefs="ex-emacsNix-6">
232 <para>Three packages are taken from GNU ELPA.</para>
233 </callout>
234
235 <callout arearefs="ex-emacsNix-7">
236 <para>
237 <varname>notmuch</varname> is taken from a nixpkgs derivation
238 which contains an Emacs mode.
239 </para>
240 </callout>
241
242 </calloutlist>
243 </para>
244
245 <para>
246 The result of this configuration will be an
247 <command>emacs</command> command which launches Emacs with all
248 of your chosen packages in the <varname>load-path</varname>.
249 </para>
250
251 <para>
252 You can check that it works by executing this in a terminal:
253
254<screen>
255$ nix-build emacs.nix
256$ ./result/bin/emacs -q
257</screen>
258
259 and then typing <literal>M-x package-initialize</literal>.
260 Check that you can use all the packages you want in this
261 Emacs instance. For example, try switching to the zerodark
262 theme through
263 <literal>M-x load-theme <RET> zerodark <RET> y</literal>.
264 </para>
265
266 <tip>
267 <para>
268 A few popular extensions worth checking out are: auctex,
269 company, edit-server, flycheck, helm, iedit, magit,
270 multiple-cursors, projectile, and yasnippet.
271 </para>
272 </tip>
273
274 <para>
275 The list of available packages in the various ELPA
276 repositories can be seen with the following commands:
277 <example>
278 <title>Querying Emacs packages</title>
279 <programlisting><![CDATA[
280nix-env -f "<nixpkgs>" -qaP -A emacsPackagesNg.elpaPackages
281nix-env -f "<nixpkgs>" -qaP -A emacsPackagesNg.melpaPackages
282nix-env -f "<nixpkgs>" -qaP -A emacsPackagesNg.melpaStablePackages
283nix-env -f "<nixpkgs>" -qaP -A emacsPackagesNg.orgPackages
284]]></programlisting>
285 </example>
286 </para>
287
288 <para>
289 If you are on NixOS, you can install this particular Emacs for
290 all users by adding it to the list of system packages
291 (see <xref linkend="sec-declarative-package-mgmt" />). Simply
292 modify your file <filename>configuration.nix</filename> to
293 make it contain:
294 <example>
295 <title>Custom Emacs in <filename>configuration.nix</filename></title>
296 <programlisting><![CDATA[
297{
298 environment.systemPackages = [
299 # [...]
300 (import /path/to/emacs.nix { inherit pkgs; })
301 ];
302}
303]]></programlisting>
304 </example>
305 </para>
306
307 <para>
308 In this case, the next <command>nixos-rebuild switch</command>
309 will take care of adding your <command>emacs</command> to the
310 <varname>PATH</varname> environment variable
311 (see <xref linkend="sec-changing-config" />).
312 </para>
313
314<!-- fixme: i think the following is better done with config.nix
315https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides
316-->
317 <para>
318 If you are not on NixOS or want to install this particular
319 Emacs only for yourself, you can do so by adding it to your
320 <filename>~/.config/nixpkgs/config.nix</filename>
321 (see <link xlink:href="http://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides">Nixpkgs manual</link>):
322 <example>
323 <title>Custom Emacs in <filename>~/.config/nixpkgs/config.nix</filename></title>
324 <programlisting><![CDATA[
325{
326 packageOverrides = super: let self = super.pkgs; in {
327 myemacs = import /path/to/emacs.nix { pkgs = self; };
328 };
329}
330]]></programlisting>
331 </example>
332 </para>
333
334 <para>
335 In this case, the next
336 <literal>nix-env -f '<nixpkgs>' -iA myemacs</literal>
337 will take care of adding your emacs to the
338 <varname>PATH</varname> environment variable.
339 </para>
340 </section>
341
342 <section>
343 <title>Advanced Emacs Configuration</title>
344
345 <para>
346 If you want, you can tweak the Emacs package itself from your
347 <filename>emacs.nix</filename>. For example, if you want to
348 have a GTK+3-based Emacs instead of the default GTK+2-based
349 binary and remove the automatically generated
350 <filename>emacs.desktop</filename> (useful is you only use
351 <command>emacsclient</command>), you can change your file
352 <filename>emacs.nix</filename> in this way:
353 </para>
354
355 <example xml:id="ex-emacsGtk3Nix">
356 <title>Custom Emacs build</title>
357 <programlisting><![CDATA[
358{ pkgs ? import <nixpkgs> {} }:
359let
360 myEmacs = (pkgs.emacs.override {
361 # Use gtk3 instead of the default gtk2
362 withGTK3 = true;
363 withGTK2 = false;
364 }).overrideAttrs (attrs: {
365 # I don't want emacs.desktop file because I only use
366 # emacsclient.
367 postInstall = (attrs.postInstall or "") + ''
368 rm $out/share/applications/emacs.desktop
369 '';
370 });
371in [...]
372]]></programlisting>
373 </example>
374
375 <para>
376 After building this file as shown in <xref linkend="ex-emacsNix" />,
377 you will get an GTK3-based Emacs binary pre-loaded with your
378 favorite packages.
379 </para>
380 </section>
381 </section>
382
383<section>
384 <title>Running Emacs as a Service</title>
385 <para>
386 <productname>NixOS</productname> provides an optional
387 <command>systemd</command> service which launches
388 <link xlink:href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html">
389 Emacs daemon
390 </link>
391 with the user's login session.
392 </para>
393
394 <para>
395 <emphasis>Source:</emphasis>
396 <filename>modules/services/editors/emacs.nix</filename>
397 </para>
398
399 <section>
400 <title>Enabling the Service</title>
401
402 <para>
403 To install and enable the <command>systemd</command>
404 user service for Emacs daemon, add the following to your
405 <filename>configuration.nix</filename>:
406
407 <programlisting><![CDATA[
408services.emacs.enable = true;
409services.emacs.package = import /home/cassou/.emacs.d { pkgs = pkgs; };
410]]></programlisting>
411 </para>
412
413 <para>
414 The <varname>services.emacs.package</varname> option allows a
415 custom derivation to be used, for example, one created by
416 <function>emacsWithPackages</function>.
417 </para>
418
419 <para>
420 Ensure that the Emacs server is enabled for your user's Emacs
421 configuration, either by customizing the
422 <varname>server-mode</varname> variable, or by adding
423 <literal>(server-start)</literal> to
424 <filename>~/.emacs.d/init.el</filename>.
425 </para>
426
427 <para>
428 To start the daemon, execute the following:
429
430<screen>
431$ nixos-rebuild switch # to activate the new configuration.nix
432$ systemctl --user daemon-reload # to force systemd reload
433$ systemctl --user start emacs.service # to start the Emacs daemon
434</screen>
435
436 The server should now be ready to serve Emacs clients.
437 </para>
438
439 </section>
440
441 <section>
442 <title>Starting the client</title>
443 <para>
444 Ensure that the emacs server is enabled, either by customizing
445 the <varname>server-mode</varname> variable, or by adding
446 <literal>(server-start)</literal> to
447 <filename>~/.emacs</filename>.
448 </para>
449
450 <para>
451 To connect to the emacs daemon, run one of the following:
452 <programlisting><![CDATA[
453emacsclient FILENAME
454emacsclient --create-frame # opens a new frame (window)
455emacsclient --create-frame --tty # opens a new frame on the current terminal
456]]></programlisting>
457 </para>
458 </section>
459
460 <section>
461 <title>Configuring the <varname>EDITOR</varname> variable</title>
462 <!--<title><command>emacsclient</command> as the Default Editor</title>-->
463
464 <para>
465 If <varname>services.emacs.defaultEditor</varname> is
466 <literal>true</literal>, the <varname>EDITOR</varname> variable
467 will be set to a wrapper script which launches
468 <command>emacsclient</command>.
469 </para>
470
471 <para>
472 Any setting of <varname>EDITOR</varname> in the shell config
473 files will override
474 <varname>services.emacs.defaultEditor</varname>.
475 To make sure <varname>EDITOR</varname> refers to the Emacs
476 wrapper script, remove any existing <varname>EDITOR</varname>
477 assignment from <filename>.profile</filename>,
478 <filename>.bashrc</filename>, <filename>.zshenv</filename> or
479 any other shell config file.
480 </para>
481
482 <para>
483 If you have formed certain bad habits when editing files,
484 these can be corrected with a shell alias to the wrapper
485 script:
486 <programlisting>alias vi=$EDITOR</programlisting>
487 </para>
488 </section>
489
490 <section>
491 <title>Per-User Enabling of the Service</title>
492
493 <para>
494 In general, <command>systemd</command> user services
495 are globally enabled by symlinks in
496 <filename>/etc/systemd/user</filename>. In the case where
497 Emacs daemon is not wanted for all users, it is possible to
498 install the service but not globally enable it:
499
500 <programlisting><![CDATA[
501services.emacs.enable = false;
502services.emacs.install = true;
503]]></programlisting>
504 </para>
505
506 <para>
507 To enable the <command>systemd</command> user service for just
508 the currently logged in user, run:
509
510 <programlisting>systemctl --user enable emacs</programlisting>
511
512 This will add the symlink
513 <filename>~/.config/systemd/user/emacs.service</filename>.
514 </para>
515 </section>
516</section>
517
518<section>
519 <title>Configuring Emacs</title>
520
521 <para>
522 The Emacs init file should be changed to load the extension
523 packages at startup:
524
525 <example>
526 <title>Package initialization in <filename>.emacs</filename></title>
527 <programlisting><![CDATA[
528(require 'package)
529
530;; optional. makes unpure packages archives unavailable
531(setq package-archives nil)
532
533(setq package-enable-at-startup nil)
534(package-initialize)
535]]></programlisting>
536 </example>
537 </para>
538
539 <para>
540 After the declarative emacs package configuration has been
541 tested, previously downloaded packages can be cleaned up by
542 removing <filename>~/.emacs.d/elpa</filename> (do make a backup
543 first, in case you forgot a package).
544 </para>
545
546 <!--
547 todo: is it worth documenting customizations for
548 server-switch-hook, server-done-hook?
549 -->
550
551 <section>
552 <title>A Major Mode for Nix Expressions</title>
553
554 <para>
555 Of interest may be <varname>melpaPackages.nix-mode</varname>,
556 which provides syntax highlighting for the Nix language. This is
557 particularly convenient if you regularly edit Nix files.
558 </para>
559 </section>
560
561 <section>
562 <title>Accessing man pages</title>
563 <para>
564 You can use <function>woman</function> to get completion of all
565 available man pages. For example, type <literal>M-x woman
566 <RET> nixos-rebuild <RET>.</literal>
567 </para>
568 </section>
569
570 <section xml:id="sec-emacs-docbook-xml">
571 <title>Editing DocBook 5 XML Documents</title>
572 <para>
573 Emacs includes <link
574 xlink:href="https://www.gnu.org/software/emacs/manual/html_node/nxml-mode/Introduction.html">nXML</link>,
575 a major-mode for validating and editing XML documents.
576 When editing DocBook 5.0 documents, such as
577 <link linkend="book-nixos-manual">this one</link>,
578 nXML needs to be configured with the relevant schema, which is
579 not included.
580 </para>
581
582 <para>
583 To install the DocBook 5.0 schemas, either add
584 <varname>pkgs.docbook5</varname> to
585 <varname>environment.systemPackages</varname> (<link
586 linkend="sec-declarative-package-mgmt">NixOS</link>), or run
587 <literal>nix-env -i pkgs.docbook5</literal>
588 (<link linkend="sec-ad-hoc-packages">Nix</link>).
589 </para>
590
591 <para>
592 Then customize the variable <varname>rng-schema-locating-files</varname> to include <filename>~/.emacs.d/schemas.xml</filename> and put the following text into that file:
593 <example xml:id="ex-emacs-docbook-xml">
594 <title>nXML Schema Configuration (<filename>~/.emacs.d/schemas.xml</filename>)</title>
595 <programlisting language="xml"><![CDATA[
596<?xml version="1.0"?>
597<!--
598 To let emacs find this file, evaluate:
599 (add-to-list 'rng-schema-locating-files "~/.emacs.d/schemas.xml")
600-->
601<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
602 <!--
603 Use this variation if pkgs.docbook5 is added to environment.systemPackages
604 -->
605 <namespace ns="http://docbook.org/ns/docbook"
606 uri="/run/current-system/sw/share/xml/docbook-5.0/rng/docbookxi.rnc"/>
607 <!--
608 Use this variation if installing schema with "nix-env -iA pkgs.docbook5".
609 <namespace ns="http://docbook.org/ns/docbook"
610 uri="../.nix-profile/share/xml/docbook-5.0/rng/docbookxi.rnc"/>
611 -->
612</locatingRules>
613]]></programlisting>
614 </example>
615 </para>
616
617 </section>
618</section>
619
620</chapter>