2 @chapter Emacs Interface
5 GNU Guix comes with several useful modules (known as ``guix.el'') for
6 GNU@tie{}Emacs which are intended to make an Emacs user interaction with
7 Guix convenient and fun.
10 * Initial Setup: Emacs Initial Setup. Preparing @file{~/.emacs}.
11 * Package Management: Emacs Package Management. Managing packages and generations.
12 * Popup Interface: Emacs Popup Interface. Magit-like interface for guix commands.
13 * Prettify Mode: Emacs Prettify. Abbreviating @file{/gnu/store/@dots{}} file names.
14 * Build Log Mode: Emacs Build Log. Highlighting Guix build logs.
15 * Completions: Emacs Completions. Completing @command{guix} shell command.
16 * Development: Emacs Development. Tools for Guix developers.
17 * Hydra: Emacs Hydra. Interface for Guix build farm.
21 @node Emacs Initial Setup
22 @section Initial Setup
24 On the Guix System Distribution (@pxref{GNU Distribution}), ``guix.el''
25 is ready to use, provided Guix is installed system-wide, which is the
26 case by default. So if that is what you're using, you can happily skip
27 this section and read about the fun stuff.
29 If you're not yet a happy user of GuixSD, a little bit of setup is needed.
30 To be able to use ``guix.el'', you need to install the following
35 @uref{http://www.gnu.org/software/emacs/, GNU Emacs}, version 24.3 or
39 @uref{http://nongnu.org/geiser/, Geiser}, version 0.3 or later: it is
40 used for interacting with the Guile process.
43 @uref{https://github.com/magit/magit/, magit-popup library}. You
44 already have this library if you use Magit 2.1.0 or later. This library
45 is an optional dependency---it is required only for @kbd{M-x@tie{}guix}
46 command (@pxref{Emacs Popup Interface}).
50 When it is done ``guix.el'' may be configured by requiring a special
51 @code{guix-init} file---i.e., by adding the following code into your
52 init file (@pxref{Init File,,, emacs, The GNU Emacs Manual}):
55 (add-to-list 'load-path "/path/to/directory-with-guix.el")
56 (require 'guix-init nil t)
59 So the only thing you need to figure out is where the directory with
60 elisp files for Guix is placed. It depends on how you installed Guix:
64 If it was installed by a package manager of your distribution or by a
65 usual @code{./configure && make && make install} command sequence, then
66 elisp files are placed in a standard directory with Emacs packages
67 (usually it is @file{/usr/share/emacs/site-lisp/}), which is already in
68 @code{load-path}, so there is no need to add that directory there.
71 If you used a binary installation method (@pxref{Binary Installation}),
72 then Guix is installed somewhere in the store, so the elisp files are
73 placed in @file{/gnu/store/@dots{}-guix-0.8.2/share/emacs/site-lisp/} or
74 alike. However it is not recommended to refer directly to a store
75 directory. Instead you can install Guix using Guix itself with
76 @command{guix package -i guix} command (@pxref{Invoking guix package})
77 and add @file{~/.guix-profile/share/emacs/site-lisp/} directory to
78 @code{load-path} variable.
81 If you did not install Guix at all and prefer a hacking way
82 (@pxref{Running Guix Before It Is Installed}), along with augmenting
83 @code{load-path} you need to set @code{guix-load-path} variable to the
84 same directory, so your final configuration will look like this:
87 (let ((dir "/path/to/your-guix-git-tree/emacs"))
88 (add-to-list 'load-path dir)
89 (setq guix-load-path dir))
90 (require 'guix-init nil t)
94 By default, along with autoloading (@pxref{Autoload,,, elisp, The GNU
95 Emacs Lisp Reference Manual}) the main interactive commands for
96 ``guix.el'' (@pxref{Emacs Commands}), requiring @code{guix-init} will
97 also autoload commands for the Emacs packages installed in your user
100 To disable automatic loading of installed Emacs packages, set
101 @code{guix-package-enable-at-startup} variable to @code{nil} before
102 requiring @code{guix-init}. This variable has the same meaning for
103 Emacs packages installed with Guix, as @code{package-enable-at-startup}
104 for the built-in Emacs package system (@pxref{Package Installation,,,
105 emacs, The GNU Emacs Manual}).
107 You can activate Emacs packages installed in your profile whenever you
108 want using @kbd{M-x@tie{}guix-emacs-load-autoloads}.
111 @node Emacs Package Management
112 @section Package Management
114 Once ``guix.el'' has been successfully configured, you should be able to
115 use a visual interface for routine package management tasks, pretty much
116 like the @command{guix package} command (@pxref{Invoking guix package}).
117 Specifically, it makes it easy to:
120 @item browse and display packages and generations;
121 @item search, install, upgrade and remove packages;
122 @item display packages from previous generations;
123 @item do some other useful things.
127 * Commands: Emacs Commands. @kbd{M-x guix-@dots{}}
128 * General information: Emacs General info. Common for both interfaces.
129 * ``List'' buffer: Emacs List buffer. List-like interface.
130 * ``Info'' buffer: Emacs Info buffer. Help-like interface.
131 * Configuration: Emacs Configuration. Configuring the interface.
137 All commands for displaying packages and generations use the current
138 profile, which can be changed with
139 @kbd{M-x@tie{}guix-set-current-profile}. Alternatively, if you call any
140 of these commands with prefix argument (@kbd{C-u}), you will be prompted
141 for a profile just for that command.
143 Commands for displaying packages:
147 @item M-x guix-all-available-packages
148 @itemx M-x guix-newest-available-packages
149 Display all/newest available packages.
151 @item M-x guix-installed-packages
152 Display all installed packages.
154 @item M-x guix-obsolete-packages
155 Display obsolete packages (the packages that are installed in a profile
156 but cannot be found among available packages).
158 @item M-x guix-search-by-name
159 Display package(s) with the specified name.
161 @item M-x guix-search-by-regexp
162 Search for packages by a specified regexp. By default ``name'',
163 ``synopsis'' and ``description'' of the packages will be searched. This
164 can be changed by modifying @code{guix-package-search-params} variable.
168 By default, these commands display each output on a separate line. If
169 you prefer to see a list of packages---i.e., a list with a package per
170 line, use the following setting:
173 (setq guix-package-list-type 'package)
176 Commands for displaying generations:
180 @item M-x guix-generations
181 List all the generations.
183 @item M-x guix-last-generations
184 List the @var{N} last generations. You will be prompted for the number
187 @item M-x guix-generations-by-time
188 List generations matching time period. You will be prompted for the
189 period using Org mode time prompt based on Emacs calendar (@pxref{The
190 date/time prompt,,, org, The Org Manual}).
194 Analogously on GuixSD you can also display system generations:
197 @item M-x guix-system-generations
198 @item M-x guix-last-system-generations
199 @item M-x guix-system-generations-by-time
202 You can also invoke the @command{guix pull} command (@pxref{Invoking
203 guix pull}) from Emacs using:
207 With @kbd{C-u}, make it verbose.
210 Once @command{guix pull} has succeeded, the Guix REPL is restared. This
211 allows you to keep using the Emacs interface with the updated Guix.
213 @node Emacs General info
214 @subsection General information
216 The following keys are available for both ``list'' and ``info'' types of
222 Go backward/forward by the history of the displayed results (this
223 history is similar to the history of the Emacs @code{help-mode} or
227 Revert current buffer: update information about the displayed
228 packages/generations and redisplay it.
231 Redisplay current buffer (without updating information).
234 Apply manifest to the current profile or to a specified profile, if
235 prefix argument is used. This has the same meaning as @code{--manifest}
236 option (@pxref{Invoking guix package}).
240 @cindex read-eval-print loop
241 Go to the Guix REPL (@pxref{The REPL,,, geiser, Geiser User Manual}).
245 Describe current mode to see all available bindings.
249 @emph{Hint:} If you need several ``list'' or ``info'' buffers, you can
250 simlpy @kbd{M-x clone-buffer} them, and each buffer will have its own
253 @emph{Warning:} Name/version pairs cannot be used to identify packages
254 (because a name is not necessarily unique), so ``guix.el'' uses special
255 identifiers that live only during a guile session, so if the Guix REPL
256 was restarted, you may want to revert ``list'' buffer (by pressing
259 @node Emacs List buffer
260 @subsection ``List'' buffer
262 An interface of a ``list'' buffer is similar to the interface provided
263 by ``package.el'' (@pxref{Package Menu,,, emacs, The GNU Emacs Manual}).
265 Default key bindings available for both ``package-list'' and
266 ``generation-list'' buffers:
270 Mark the current entry (with prefix, mark all entries).
272 Unmark the current entry (with prefix, unmark all entries).
276 Sort entries by a specified column.
279 A ``package-list'' buffer additionally provides the following bindings:
283 Describe marked packages (display available information in a
284 ``package-info'' buffer).
286 Mark the current package for installation.
288 Mark the current package for deletion.
290 Mark the current package for upgrading.
292 Mark all obsolete packages for upgrading.
294 Edit the definition of the curent package (go to its location). This is
295 similar to @command{guix edit} command (@pxref{Invoking guix edit}), but
296 for opening a package recipe in the current Emacs instance.
298 Execute actions on the marked packages.
300 Display latest builds of the current package (@pxref{Emacs Hydra}).
303 A ``generation-list'' buffer additionally provides the following
308 List packages installed in the current generation.
310 Describe marked generations (display available information in a
311 ``generation-info'' buffer).
313 Switch profile to the current generation.
315 Mark the current generation for deletion (with prefix, mark all
318 Execute actions on the marked generations---i.e., delete generations.
320 Run Ediff (@pxref{Top,,, ediff, The Ediff Manual}) on package outputs
321 installed in the 2 marked generations. With prefix argument, run Ediff
322 on manifests of the marked generations.
325 Run Diff (@pxref{Diff Mode,,, emacs, The GNU Emacs Manual}) on package
326 outputs installed in the 2 marked generations. With prefix argument,
327 run Diff on manifests of the marked generations.
329 List package outputs added to the latest marked generation comparing
330 with another marked generation.
332 List package outputs removed from the latest marked generation comparing
333 with another marked generation.
336 @node Emacs Info buffer
337 @subsection ``Info'' buffer
339 The interface of an ``info'' buffer is similar to the interface of
340 @code{help-mode} (@pxref{Help Mode,,, emacs, The GNU Emacs Manual}).
342 ``Info'' buffer contains some buttons (as usual you may use @key{TAB} /
343 @kbd{S-@key{TAB}} to move between buttons---@pxref{Mouse References,,,
344 emacs, The GNU Emacs Manual}) which can be used to:
347 @item (in a ``package-info'' buffer)
350 @item install/remove a package;
351 @item jump to a package location;
352 @item browse home page of a package;
353 @item describe packages from ``Inputs'' fields.
356 @item (in a ``generation-info'' buffer)
359 @item remove a generation;
360 @item switch to a generation;
361 @item list packages installed in a generation;
362 @item jump to a generation directory.
367 It is also possible to copy a button label (a link to an URL or a file)
368 by pressing @kbd{c} on a button.
371 @node Emacs Configuration
372 @subsection Configuration
374 There are many variables you can modify to change the appearance or
375 behavior of Emacs user interface. Some of these variables are described
376 in this section. Also you can use Custom Interface (@pxref{Easy
377 Customization,,, emacs, The GNU Emacs Manual}) to explore/set variables
381 * Guile and Build Options: Emacs Build Options. Specifying how packages are built.
382 * Buffer Names: Emacs Buffer Names. Names of Guix buffers.
383 * Keymaps: Emacs Keymaps. Configuring key bindings.
384 * Appearance: Emacs Appearance. Settings for visual appearance.
387 @node Emacs Build Options
388 @subsubsection Guile and Build Options
391 @item guix-guile-program
392 If you have some special needs for starting a Guile process, you may set
393 this variable, for example:
396 (setq guix-guile-program '("/bin/guile" "--no-auto-compile"))
399 @item guix-use-substitutes
400 Has the same meaning as @code{--no-substitutes} option (@pxref{Invoking
404 Has the same meaning as @code{--dry-run} option (@pxref{Invoking guix
409 @node Emacs Buffer Names
410 @subsubsection Buffer Names
412 Default names of ``guix.el'' buffers (``*Guix@tie{}@dots{}*'') may be
413 changed with the following variables:
416 @item guix-package-list-buffer-name
417 @item guix-output-list-buffer-name
418 @item guix-generation-list-buffer-name
419 @item guix-package-info-buffer-name
420 @item guix-output-info-buffer-name
421 @item guix-generation-info-buffer-name
422 @item guix-repl-buffer-name
423 @item guix-internal-repl-buffer-name
426 By default, the name of a profile is also displayed in a ``list'' or
427 ``info'' buffer name. To change this behavior, use
428 @code{guix-ui-buffer-name-function} variable.
430 For example, if you want to display all types of results in a single
431 buffer (in such case you will probably use a history (@kbd{l}/@kbd{r})
432 extensively), you may do it like this:
435 (let ((name "Guix Universal"))
437 guix-package-list-buffer-name name
438 guix-output-list-buffer-name name
439 guix-generation-list-buffer-name name
440 guix-package-info-buffer-name name
441 guix-output-info-buffer-name name
442 guix-generation-info-buffer-name name))
446 @subsubsection Keymaps
448 If you want to change default key bindings, use the following keymaps
449 (@pxref{Init Rebinding,,, emacs, The GNU Emacs Manual}):
452 @item guix-buffer-map
453 Parent keymap with general keys for any buffer type.
456 Parent keymap with general keys for buffers used for Guix package
457 management (for packages, outputs and generations).
459 @item guix-list-mode-map
460 Parent keymap with general keys for ``list'' buffers.
462 @item guix-package-list-mode-map
463 Keymap with specific keys for ``package-list'' buffers.
465 @item guix-output-list-mode-map
466 Keymap with specific keys for ``output-list'' buffers.
468 @item guix-generation-list-mode-map
469 Keymap with specific keys for ``generation-list'' buffers.
471 @item guix-info-mode-map
472 Parent keymap with general keys for ``info'' buffers.
474 @item guix-package-info-mode-map
475 Keymap with specific keys for ``package-info'' buffers.
477 @item guix-output-info-mode-map
478 Keymap with specific keys for ``output-info'' buffers.
480 @item guix-generation-info-mode-map
481 Keymap with specific keys for ``generation-info'' buffers.
483 @item guix-info-button-map
484 Keymap with keys available when a point is placed on a button.
488 @node Emacs Appearance
489 @subsubsection Appearance
491 You can change almost any aspect of ``list'' / ``info'' buffers using
492 the following variables (@dfn{ENTRY-TYPE} means @code{package},
493 @code{output} or @code{generation}):
496 @item guix-ENTRY-TYPE-list-format
497 @itemx guix-ENTRY-TYPE-list-titles
498 Specify the columns, their names, what and how is displayed in ``list''
501 @item guix-ENTRY-TYPE-info-format
502 @itemx guix-ENTRY-TYPE-info-titles
503 @itemx guix-info-ignore-empty-values
504 @itemx guix-info-param-title-format
505 @itemx guix-info-multiline-prefix
506 @itemx guix-info-indent
507 @itemx guix-info-fill
508 @itemx guix-info-delimiter
509 Various settings for ``info'' buffers.
514 @node Emacs Popup Interface
515 @section Popup Interface
517 If you ever used Magit, you know what ``popup interface'' is
518 (@pxref{Top,,, magit-popup, Magit-Popup User Manual}). Even if you are
519 not acquainted with Magit, there should be no worries as it is very
522 So @kbd{M-x@tie{}guix} command provides a top-level popup interface for
523 all available guix commands. When you select an option, you'll be
524 prompted for a value in the minibuffer. Many values have completions,
525 so don't hesitate to press @key{TAB} key. Multiple values (for example,
526 packages or lint checkers) should be separated by commas.
528 After specifying all options and switches for a command, you may choose
529 one of the available actions. The following default actions are
530 available for all commands:
535 Run the command in the Guix REPL. It is faster than running
536 @code{guix@tie{}@dots{}} command directly in shell, as there is no
537 need to run another guile process and to load required modules there.
540 Run the command in a shell buffer. You can set
541 @code{guix-run-in-shell-function} variable to fine tune the shell buffer
545 Add the command line to the kill ring (@pxref{Kill Ring,,, emacs, The
550 Several commands (@command{guix graph}, @command{guix system dmd-graph}
551 and @command{guix system extension-graph}) also have a ``View graph''
552 action, which allows you to view a generated graph using @command{dot}
553 command (specified by @code{guix-dot-program} variable). By default a
554 PNG file will be saved in @file{/tmp} directory and will be opened
555 directly in Emacs. This behavior may be changed with the following
560 @item guix-find-file-function
561 Function used to open a generated graph. If you want to open a graph in
562 an external program, you can do it by modifying this variable---for
563 example, you can use a functionality provided by the Org Mode
564 (@pxref{Top,,, org, The Org Manual}):
567 (setq guix-find-file-function 'org-open-file)
568 (add-to-list 'org-file-apps '("\\.png\\'" . "sxiv %s"))
571 @item guix-dot-default-arguments
572 Command line arguments to run @command{dot} command. If you change an
573 output format (for example, into @code{-Tpdf}), you also need to change
576 @item guix-dot-file-name-function
577 Function used to define a name of the generated graph file. Default
578 name is @file{/tmp/guix-emacs-graph-XXXXXX.png}.
582 So, for example, if you want to generate and open a PDF file in your
583 Emacs, you may change the settings like this:
586 (defun my-guix-pdf-graph ()
587 "/tmp/my-current-guix-graph.pdf")
589 (setq guix-dot-default-arguments '("-Tpdf")
590 guix-dot-file-name-function 'my-guix-pdf-graph)
595 @section Guix Prettify Mode
597 GNU@tie{}Guix also comes with ``guix-prettify.el''. It provides a minor
598 mode for abbreviating store file names by replacing hash sequences of
599 symbols with ``@dots{}'':
602 /gnu/store/72f54nfp6g1hz873w8z3gfcah0h4nl9p-foo-0.1
603 @result{} /gnu/store/…-foo-0.1
606 Once you set up ``guix.el'' (@pxref{Emacs Initial Setup}), the following
607 commands become available:
611 @item M-x guix-prettify-mode
612 Enable/disable prettifying for the current buffer.
614 @item M-x global-guix-prettify-mode
615 Enable/disable prettifying globally.
619 To automatically enable @code{guix-prettify-mode} globally on Emacs
620 start, add the following line to your init file:
623 (global-guix-prettify-mode)
626 If you want to enable it only for specific major modes, add it to the
627 mode hooks (@pxref{Hooks,,, emacs, The GNU Emacs Manual}), for example:
630 (add-hook 'shell-mode-hook 'guix-prettify-mode)
631 (add-hook 'dired-mode-hook 'guix-prettify-mode)
635 @node Emacs Build Log
636 @section Build Log Mode
638 GNU@tie{}Guix provides major and minor modes for highlighting build
639 logs. So when you have a file with a package build output---for
640 example, a file returned by @command{guix build --log-file @dots{}}
641 command (@pxref{Invoking guix build}), you may call @kbd{M-x
642 guix-build-log-mode} command in the buffer with this file. This major
643 mode highlights some lines specific to build output and provides the
644 following key bindings:
649 Move to the next build phase.
652 Move to the previous build phase.
655 Toggle (show/hide) the body of the current build phase.
658 Toggle (show/hide) the bodies of all build phases.
662 There is also @kbd{M-x guix-build-log-minor-mode} which also provides
663 the same highlighting and the same key bindings as the major mode, but
664 prefixed with @kbd{C-c}. By default, this minor mode is enabled in
665 shell buffers (@pxref{Interactive Shell,,, emacs, The GNU Emacs
666 Manual}). If you don't like it, set
667 @code{guix-build-log-minor-mode-activate} to nil.
670 @node Emacs Completions
671 @section Shell Completions
673 Another feature that becomes available after configuring Emacs interface
674 (@pxref{Emacs Initial Setup}) is completing of @command{guix}
675 subcommands, options, packages and other things in @code{shell}
676 (@pxref{Interactive Shell,,, emacs, The GNU Emacs Manual}) and
677 @code{eshell} (@pxref{Top,,, eshell, Eshell: The Emacs Shell}).
679 It works the same way as other completions do. Just press @key{TAB}
680 when your intuition tells you.
682 And here are some examples, where pressing @key{TAB} may complete
687 @item @code{guix pa}@key{TAB}
688 @item @code{guix package -}@key{TAB}
689 @item @code{guix package --}@key{TAB}
690 @item @code{guix package -i gei}@key{TAB}
691 @item @code{guix build -L/tm}@key{TAB}
692 @item @code{guix build --sy}@key{TAB}
693 @item @code{guix build --system=i}@key{TAB}
694 @item @code{guix system rec}@key{TAB}
695 @item @code{guix lint --checkers=sy}@key{TAB}
696 @item @code{guix lint --checkers=synopsis,des}@key{TAB}
701 @node Emacs Development
704 By default, when you open a Scheme file, @code{guix-devel-mode} will be
705 activated (if you don't want it, set @code{guix-devel-activate-mode} to
706 nil). This minor mode provides the following key bindings:
711 Copy the name of the current Guile module into kill ring
712 (@code{guix-devel-copy-module-as-kill}).
715 Use the current Guile module. Often after opening a Scheme file, you
716 want to use a module it defines, so you switch to the Geiser REPL and
717 write @code{,use (some module)} there. You may just use this command
718 instead (@code{guix-devel-use-module}).
721 Build a package defined by the current variable definition. The
722 building process is run in the current Geiser REPL. If you modified the
723 current package definition, don't forget to reevaluate it before calling
724 this command---for example, with @kbd{C-M-x} (@pxref{To eval or not to
725 eval,,, geiser, Geiser User Manual})
726 (@code{guix-devel-build-package-definition}).
729 Build a source derivation of the package defined by the current variable
730 definition. This command has the same meaning as @code{guix build -S}
731 shell command (@pxref{Invoking guix build})
732 (@code{guix-devel-build-package-source}).
735 Lint (check) a package defined by the current variable definition
736 (@pxref{Invoking guix lint}) (@code{guix-devel-lint-package}).
740 Unluckily, there is a limitation related to long-running REPL commands.
741 When there is a running process in a Geiser REPL, you are not supposed
742 to evaluate anything in a scheme buffer, because this will ``freeze''
743 the REPL: it will stop producing any output (however, the evaluating
744 process will continue---you will just not see any progress anymore). Be
745 aware: even moving the point in a scheme buffer may ``break'' the REPL
746 if Autodoc (@pxref{Autodoc and friends,,, geiser, Geiser User Manual})
747 is enabled (which is the default).
749 So you have to postpone editing your scheme buffers until the running
750 evaluation will be finished in the REPL.
752 Alternatively, to avoid this limitation, you may just run another Geiser
753 REPL, and while something is being evaluated in the previous REPL, you
754 can continue editing a scheme file with the help of the current one.
760 The continuous integration server at @code{hydra.gnu.org} builds all
761 the distribution packages on the supported architectures and serves
762 them as substitutes (@pxref{Substitutes}). Continuous integration is
763 currently orchestrated by @uref{https://nixos.org/hydra/, Hydra}.
765 This section describes an Emacs interface to query Hydra to know the
766 build status of specific packages, discover recent and ongoing builds,
767 view build logs, and so on. This interface is mostly the same as the
768 ``list''/``info'' interface for displaying packages and generations
769 (@pxref{Emacs Package Management}).
771 The following commands are available:
775 @item M-x guix-hydra-latest-builds
776 Display latest failed or successful builds (you will be prompted for a
777 number of builds). With @kbd{C-u}, you will also be prompted for other
778 parameters (project, jobset, job and system).
780 @item M-x guix-hydra-queued-builds
781 Display scheduled or currently running builds (you will be prompted for
784 @item M-x guix-hydra-jobsets
785 Display available jobsets (you will be prompted for a project).
789 In a list of builds you can press @kbd{L} key to display a build log of
790 the current build. Also both a list of builds and a list of jobsets
791 provide @kbd{B} key to display latest builds of the current job or
792 jobset (don't forget about @kbd{C-u}).