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>OS X</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 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.
49 </para>
50
51 <section>
52 <title>The Different Releases of Emacs</title>
53
54 <para>
55 <productname>Nixpkgs</productname> defines several basic Emacs
56 packages. The following are attributes belonging to the
57 <varname>pkgs</varname> set:
58
59 <variablelist>
60 <varlistentry>
61 <term><varname>emacs</varname></term>
62 <term><varname>emacs24</varname></term>
63 <listitem>
64 <para>
65 The latest stable version of Emacs 24 using the <link
66 xlink:href="http://www.gtk.org">GTK+ 2</link> widget
67 toolkit.
68 </para>
69 </listitem>
70 </varlistentry>
71 <varlistentry>
72 <term><varname>emacs24-nox</varname></term>
73 <listitem>
74 <para>
75 Emacs 24 built without any dependency on X11
76 libraries.
77 </para>
78 </listitem>
79 </varlistentry>
80 <varlistentry>
81 <term><varname>emacs24Macport</varname></term>
82 <listitem>
83 <para>
84 Emacs 24 with the "Mac port" patches, providing a more
85 native look and feel under OS X.
86 </para>
87 </listitem>
88 </varlistentry>
89 <varlistentry>
90 <term><varname>emacs25pre</varname></term>
91 <listitem>
92 <para>
93 A pretest version of what will become the first
94 version of Emacs 25.
95 </para>
96 </listitem>
97 </varlistentry>
98 </variablelist>
99 </para>
100
101 <para>
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>.
107 </para>
108
109 </section>
110 <section>
111 <title>Adding Packages to Emacs</title>
112 <para>
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.
116 </para>
117
118 <para>
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.
127 </para>
128
129 <para>
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.
136 </para>
137
138 <note>
139 <para>
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>).
145 </para>
146 </note>
147
148 <para>
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:
153
154 <example xml:id="ex-emacsNix">
155 <title>Nix expression to build Emacs with packages (<filename>emacs.nix</filename>)</title>
156 <programlisting language="nix">
157/*
158This is a nix expression to build Emacs and some Emacs packages I like
159from source on any distribution where Nix is installed. This will install
160all the dependencies from the nixpkgs repository and build the binary files
161without interfering with the host distribution.
162
163To build the project, type the following from the current directory:
164
165$ nix-build emacs.nix
166
167To run the newly compiled executable:
168
169$ ./result/bin/emacs
170*/
171{ pkgs ? import <nixpkgs> {} }: <co xml:id="ex-emacsNix-1" />
172
173let
174 myEmacs = pkgs.emacs; <co xml:id="ex-emacsNix-2" />
175 emacsWithPackages = (pkgs.emacsPackagesNgGen myEmacs).emacsWithPackages; <co xml:id="ex-emacsNix-3" />
176in
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
187 ]) ++ [
188 pkgs.notmuch # From main packages set <co xml:id="ex-emacsNix-7" />
189 ])
190</programlisting>
191 </example>
192
193 <calloutlist>
194 <callout arearefs="ex-emacsNix-1">
195 <para>
196 The first non-comment line in this file
197 (<literal>{ pkgs ? ... }</literal>)
198 indicates that the whole file represents a function.
199 </para>
200 </callout>
201
202 <callout arearefs="ex-emacsNix-2">
203 <para>
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
208 required packages.
209 </para>
210 </callout>
211
212 <callout arearefs="ex-emacsNix-3">
213 <para>
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).
218 </para>
219 </callout>
220
221 <callout arearefs="ex-emacsNix-4">
222 <para>
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
227 stable.
228 </para>
229 </callout>
230
231 <callout arearefs="ex-emacsNix-5">
232 <para>
233 Two packages (<varname>undo-tree</varname> and
234 <varname>zoom-frm</varname>) are taken from MELPA.
235 </para>
236 </callout>
237
238 <callout arearefs="ex-emacsNix-6">
239 <para>Three packages are taken from GNU ELPA.</para>
240 </callout>
241
242 <callout arearefs="ex-emacsNix-7">
243 <para>
244 <varname>notmuch</varname> is taken from a nixpkgs derivation
245 which contains an Emacs mode.
246 </para>
247 </callout>
248
249 </calloutlist>
250 </para>
251
252 <para>
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>.
256 </para>
257
258 <para>
259 You can check that it works by executing this in a terminal:
260
261<screen>
262$ nix-build emacs.nix
263$ ./result/bin/emacs -q
264</screen>
265
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
269 theme through
270 <literal>M-x load-theme <RET> zerodark <RET> y</literal>.
271 </para>
272
273 <tip>
274 <para>
275 A few popular extensions worth checking out are: auctex,
276 company, edit-server, flycheck, helm, iedit, magit,
277 multiple-cursors, projectile, and yasnippet.
278 </para>
279 </tip>
280
281 <para>
282 The list of available packages in the various ELPA
283 repositories can be seen with the following commands:
284 <example>
285 <title>Querying Emacs packages</title>
286 <programlisting><![CDATA[
287nix-env -f "<nixpkgs>" -qaP -A emacsPackagesNg.elpaPackages
288nix-env -f "<nixpkgs>" -qaP -A emacsPackagesNg.melpaPackages
289nix-env -f "<nixpkgs>" -qaP -A emacsPackagesNg.melpaStablePackages
290nix-env -f "<nixpkgs>" -qaP -A emacsPackagesNg.orgPackages
291]]></programlisting>
292 </example>
293 </para>
294
295 <para>
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
300 make it contain:
301 <example>
302 <title>Custom Emacs in <filename>configuration.nix</filename></title>
303 <programlisting><![CDATA[
304{
305 environment.systemPackages = [
306 # [...]
307 (import /path/to/emacs.nix { inherit pkgs; })
308 ];
309}
310]]></programlisting>
311 </example>
312 </para>
313
314 <para>
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" />).
319 </para>
320
321<!-- fixme: i think the following is better done with config.nix
322https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides
323-->
324 <para>
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>):
329 <example>
330 <title>Custom Emacs in <filename>~/.nixpkgs/system.nix</filename></title>
331 <programlisting><![CDATA[
332{
333 packageOverrides = super: let self = super.pkgs; in {
334 myemacs = import /path/to/emacs.nix { pkgs = self; };
335 };
336}
337]]></programlisting>
338 </example>
339 </para>
340
341 <para>
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.
346 </para>
347 </section>
348
349 <section>
350 <title>Advanced Emacs Configuration</title>
351
352 <para>
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:
360 </para>
361
362 <example xml:id="ex-emacsGtk3Nix">
363 <title>Custom Emacs build</title>
364 <programlisting><![CDATA[
365{ pkgs ? import <nixpkgs> {} }:
366let
367 myEmacs = pkgs.lib.overrideDerivation (pkgs.emacs.override {
368 # Use gtk3 instead of the default gtk2
369 withGTK3 = true;
370 withGTK2 = false;
371 }) (attrs: {
372 # I don't want emacs.desktop file because I only use
373 # emacsclient.
374 postInstall = attrs.postInstall + ''
375 rm $out/share/applications/emacs.desktop
376 '';
377 });
378in [...]
379]]></programlisting>
380 </example>
381
382 <para>
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
385 favorite packages.
386 </para>
387 </section>
388 </section>
389
390<section>
391 <title>Running Emacs as a Service</title>
392 <para>
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">
396 Emacs daemon
397 </link>
398 with the user's login session.
399 </para>
400
401 <para>
402 <emphasis>Source:</emphasis>
403 <filename>modules/services/editors/emacs.nix</filename>
404 </para>
405
406 <section>
407 <title>Enabling the Service</title>
408
409 <para>
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>:
413
414 <programlisting><![CDATA[
415services.emacs.enable = true;
416services.emacs.package = import /home/cassou/.emacs.d { pkgs = pkgs; };
417]]></programlisting>
418 </para>
419
420 <para>
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>.
424 </para>
425
426 <para>
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>.
432 </para>
433
434 <para>
435 To start the daemon, execute the following:
436
437<screen>
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
441</screen>
442
443 The server should now be ready to serve Emacs clients.
444 </para>
445
446 </section>
447
448 <section>
449 <title>Starting the client</title>
450 <para>
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>.
455 </para>
456
457 <para>
458 To connect to the emacs daemon, run one of the following:
459 <programlisting><![CDATA[
460emacsclient FILENAME
461emacsclient --create-frame # opens a new frame (window)
462emacsclient --create-frame --tty # opens a new frame on the current terminal
463]]></programlisting>
464 </para>
465 </section>
466
467 <section>
468 <title>Configuring the <varname>EDITOR</varname> variable</title>
469 <!--<title><command>emacsclient</command> as the Default Editor</title>-->
470
471 <para>
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>.
476 </para>
477
478 <para>
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.
487 </para>
488
489 <para>
490 If you have formed certain bad habits when editing files,
491 these can be corrected with a shell alias to the wrapper
492 script:
493 <programlisting>alias vi=$EDITOR</programlisting>
494 </para>
495 </section>
496
497 <section>
498 <title>Per-User Enabling of the Service</title>
499
500 <para>
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:
506
507 <programlisting><![CDATA[
508services.emacs.enable = false;
509services.emacs.install = true;
510]]></programlisting>
511 </para>
512
513 <para>
514 To enable the <command>systemd</command> user service for just
515 the currently logged in user, run:
516
517 <programlisting>systemctl --user enable emacs</programlisting>
518
519 This will add the symlink
520 <filename>~/.config/systemd/user/emacs.service</filename>.
521 </para>
522 </section>
523</section>
524
525<section>
526 <title>Configuring Emacs</title>
527
528 <para>
529 The Emacs init file should be changed to load the extension
530 packages at startup:
531
532 <example>
533 <title>Package initialization in <filename>.emacs</filename></title>
534 <programlisting><![CDATA[
535(require 'package)
536
537;; optional. makes unpure packages archives unavailable
538(setq package-archives nil)
539
540(setq package-enable-at-startup nil)
541(package-initialize)
542]]></programlisting>
543 </example>
544 </para>
545
546 <para>
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).
551 </para>
552
553 <!--
554 todo: is it worth documenting customizations for
555 server-switch-hook, server-done-hook?
556 -->
557
558 <section>
559 <title>A Major Mode for Nix Expressions</title>
560
561 <para>
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.
565 </para>
566 </section>
567
568 <section>
569 <title>Accessing man pages</title>
570 <para>
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>
574 </para>
575 </section>
576</section>
577
578</chapter>