2 @section Emacs Interface
5 GNU Guix comes with a visual user interface for GNU@tie{}Emacs, known
6 as ``guix.el''. It can be used for routine package management tasks,
7 pretty much like the @command{guix package} command (@pxref{Invoking
8 guix package}). Specifically, ``guix.el'' makes it easy to:
11 @item browse and display packages and generations;
12 @item search, install, upgrade and remove packages;
13 @item display packages from previous generations;
14 @item do some other useful things.
18 * Initial Setup: Emacs Initial Setup. Preparing @file{~/.emacs}.
19 * Usage: Emacs Usage. Using the interface.
20 * Configuration: Emacs Configuration. Configuring the interface.
21 * Prettify Mode: Emacs Prettify. Abbreviating @file{/gnu/store/@dots{}} file names.
22 * Completions: Emacs Completions. Completing @command{guix} shell command.
25 @node Emacs Initial Setup
26 @subsection Initial Setup
28 On the Guix System Distribution (@pxref{GNU Distribution}), ``guix.el''
29 is ready to use, provided Guix is installed system-wide, which is the
30 case by default. So if that is what you're using, you can happily skip
31 this section and read about the fun stuff.
33 If you're not yet a happy user of GuixSD, a little bit of setup is needed.
34 To be able to use ``guix.el'', you need to install the following
39 @uref{http://www.gnu.org/software/emacs/, GNU Emacs}, version 24.3 or
43 @uref{http://nongnu.org/geiser/, Geiser}, version 0.3 or later: it is
44 used for interacting with the Guile process.
48 When it is done ``guix.el'' may be configured by requiring a special
49 @code{guix-init} file---i.e., by adding the following code into your
50 init file (@pxref{Init File,,, emacs, The GNU Emacs Manual}):
53 (add-to-list 'load-path "/path/to/directory-with-guix.el")
54 (require 'guix-init nil t)
57 So the only thing you need to figure out is where the directory with
58 elisp files for Guix is placed. It depends on how you installed Guix:
62 If it was installed by a package manager of your distribution or by a
63 usual @code{./configure && make && make install} command sequence, then
64 elisp files are placed in a standard directory with Emacs packages
65 (usually it is @file{/usr/share/emacs/site-lisp/}), which is already in
66 @code{load-path}, so there is no need to add that directory there.
69 If you used a binary installation method (@pxref{Binary Installation}),
70 then Guix is installed somewhere in the store, so the elisp files are
71 placed in @file{/gnu/store/@dots{}-guix-0.8.2/share/emacs/site-lisp/} or
72 alike. However it is not recommended to refer directly to a store
73 directory. Instead you can install Guix using Guix itself with
74 @command{guix package -i guix} command (@pxref{Invoking guix package})
75 and add @file{~/.guix-profile/share/emacs/site-lisp/} directory to
76 @code{load-path} variable.
79 If you did not install Guix at all and prefer a hacking way
80 (@pxref{Running Guix Before It Is Installed}), along with augmenting
81 @code{load-path} you need to set @code{guix-load-path} variable to the
82 same directory, so your final configuration will look like this:
85 (let ((dir "/path/to/your-guix-git-tree/emacs"))
86 (add-to-list 'load-path dir)
87 (setq guix-load-path dir))
88 (require 'guix-init nil t)
92 By default, along with autoloading (@pxref{Autoload,,, elisp, The GNU
93 Emacs Lisp Reference Manual}) the main interactive commands for
94 ``guix.el'' (@pxref{Emacs Commands}), requiring @code{guix-init} will
95 also autoload commands for the Emacs packages installed in your user
98 To disable automatic loading of installed Emacs packages, set
99 @code{guix-package-enable-at-startup} variable to @code{nil} before
100 requiring @code{guix-init}. This variable has the same meaning for
101 Emacs packages installed with Guix, as @code{package-enable-at-startup}
102 for the built-in Emacs package system (@pxref{Package Installation,,,
103 emacs, The GNU Emacs Manual}).
105 You can activate Emacs packages installed in your profile whenever you
106 want using @kbd{M-x@tie{}guix-emacs-load-autoloads}.
111 Once ``guix.el'' has been successfully configured, you should be able to
112 use commands for displaying packages and generations. This information
113 can be displayed in a ``list'' or ``info'' buffer.
116 * Commands: Emacs Commands. @kbd{M-x guix-@dots{}}
117 * General information: Emacs General info. Common for both interfaces.
118 * ``List'' buffer: Emacs List buffer. List-like interface.
119 * ``Info'' buffer: Emacs Info buffer. Help-like interface.
123 @subsubsection Commands
125 All commands for displaying packages and generations use the current
126 profile, which can be changed with
127 @kbd{M-x@tie{}guix-set-current-profile}. Alternatively, if you call any
128 of these commands with prefix argument (@kbd{C-u}), you will be prompted
129 for a profile just for that command.
131 Commands for displaying packages:
135 @item M-x guix-all-available-packages
136 @itemx M-x guix-newest-available-packages
137 Display all/newest available packages.
139 @item M-x guix-installed-packages
140 Display all installed packages.
142 @item M-x guix-obsolete-packages
143 Display obsolete packages (the packages that are installed in a profile
144 but cannot be found among available packages).
146 @item M-x guix-search-by-name
147 Display package(s) with the specified name.
149 @item M-x guix-search-by-regexp
150 Search for packages by a specified regexp. By default ``name'',
151 ``synopsis'' and ``description'' of the packages will be searched. This
152 can be changed by modifying @code{guix-search-params} variable.
156 By default, these commands display each output on a separate line. If
157 you prefer to see a list of packages---i.e., a list with a package per
158 line, use the following setting:
161 (setq guix-package-list-type 'package)
164 Commands for displaying generations:
168 @item M-x guix-generations
169 List all the generations.
171 @item M-x guix-last-generations
172 List the @var{N} last generations. You will be prompted for the number
175 @item M-x guix-generations-by-time
176 List generations matching time period. You will be prompted for the
177 period using Org mode time prompt based on Emacs calendar (@pxref{The
178 date/time prompt,,, org, The Org Manual}).
182 You can also invoke the @command{guix pull} command (@pxref{Invoking
183 guix pull}) from Emacs using:
187 With @kbd{C-u}, make it verbose.
190 Once @command{guix pull} has succeeded, the Guix REPL is restared. This
191 allows you to keep using the Emacs interface with the updated Guix.
193 @node Emacs General info
194 @subsubsection General information
196 The following keys are available for both ``list'' and ``info'' types of
202 Go backward/forward by the history of the displayed results (this
203 history is similar to the history of the Emacs @code{help-mode} or
207 Revert current buffer: update information about the displayed
208 packages/generations and redisplay it.
211 Redisplay current buffer (without updating information).
214 Apply manifest to the current profile or to a specified profile, if
215 prefix argument is used. This has the same meaning as @code{--manifest}
216 option (@pxref{Invoking guix package}).
219 Go to the Guix REPL (@pxref{The REPL,,, geiser, Geiser User Manual}).
223 Describe current mode to see all available bindings.
227 @emph{Hint:} If you need several ``list'' or ``info'' buffers, you can
228 simlpy @kbd{M-x clone-buffer} them, and each buffer will have its own
231 @emph{Warning:} Name/version pairs cannot be used to identify packages
232 (because a name is not necessarily unique), so ``guix.el'' uses special
233 identifiers that live only during a guile session, so if the Guix REPL
234 was restarted, you may want to revert ``list'' buffer (by pressing
237 @node Emacs List buffer
238 @subsubsection ``List'' buffer
240 An interface of a ``list'' buffer is similar to the interface provided
241 by ``package.el'' (@pxref{Package Menu,,, emacs, The GNU Emacs Manual}).
243 Default key bindings available for both ``package-list'' and
244 ``generation-list'' buffers:
248 Mark the current entry (with prefix, mark all entries).
250 Unmark the current entry (with prefix, unmark all entries).
254 Sort entries by a specified column.
257 A ``package-list'' buffer additionally provides the following bindings:
261 Describe marked packages (display available information in a
262 ``package-info'' buffer).
264 Mark the current package for installation.
266 Mark the current package for deletion.
268 Mark the current package for upgrading.
270 Mark all obsolete packages for upgrading.
272 Edit the definition of the curent package (go to its location). This is
273 similar to @command{guix edit} command (@pxref{Invoking guix edit}), but
274 for opening a package recipe in the current Emacs instance.
276 Execute actions on the marked packages.
279 A ``generation-list'' buffer additionally provides the following
284 List packages installed in the current generation.
286 Describe marked generations (display available information in a
287 ``generation-info'' buffer).
289 Switch profile to the current generation.
291 Mark the current generation for deletion (with prefix, mark all
294 Execute actions on the marked generations---i.e., delete generations.
296 Run Ediff (@pxref{Top,,, ediff, The Ediff Manual}) on package outputs
297 installed in the 2 marked generations. With prefix argument, run Ediff
298 on manifests of the marked generations.
301 Run Diff (@pxref{Diff Mode,,, emacs, The GNU Emacs Manual}) on package
302 outputs installed in the 2 marked generations. With prefix argument,
303 run Diff on manifests of the marked generations.
305 List package outputs added to the latest marked generation comparing
306 with another marked generation.
308 List package outputs removed from the latest marked generation comparing
309 with another marked generation.
312 @node Emacs Info buffer
313 @subsubsection ``Info'' buffer
315 The interface of an ``info'' buffer is similar to the interface of
316 @code{help-mode} (@pxref{Help Mode,,, emacs, The GNU Emacs Manual}).
318 ``Info'' buffer contains some buttons (as usual you may use @key{TAB} /
319 @kbd{S-@key{TAB}} to move between buttons---@pxref{Mouse References,,,
320 emacs, The GNU Emacs Manual}) which can be used to:
323 @item (in a ``package-info'' buffer)
326 @item install/remove a package;
327 @item jump to a package location;
328 @item browse home page of a package;
329 @item describe packages from ``Inputs'' fields.
332 @item (in a ``generation-info'' buffer)
335 @item remove a generation;
336 @item switch to a generation;
337 @item list packages installed in a generation;
338 @item jump to a generation directory.
343 It is also possible to copy a button label (a link to an URL or a file)
344 by pressing @kbd{c} on a button.
347 @node Emacs Configuration
348 @subsection Configuration
350 There are many variables you can modify to change the appearance or
351 behavior of Emacs user interface. Some of these variables are described
352 in this section. Also you can use Custom Interface (@pxref{Easy
353 Customization,,, emacs, The GNU Emacs Manual}) to explore/set variables
357 * Guile and Build Options: Emacs Build Options. Specifying how packages are built.
358 * Buffer Names: Emacs Buffer Names. Names of Guix buffers.
359 * Keymaps: Emacs Keymaps. Configuring key bindings.
360 * Appearance: Emacs Appearance. Settings for visual appearance.
363 @node Emacs Build Options
364 @subsubsection Guile and Build Options
367 @item guix-guile-program
368 If you have some special needs for starting a Guile process, you may set
369 this variable, for example:
372 (setq guix-guile-program '("/bin/guile" "--no-auto-compile"))
375 @item guix-use-substitutes
376 Has the same meaning as @code{--no-substitutes} option (@pxref{Invoking
380 Has the same meaning as @code{--dry-run} option (@pxref{Invoking guix
385 @node Emacs Buffer Names
386 @subsubsection Buffer Names
388 Default names of ``guix.el'' buffers (``*Guix@tie{}@dots{}*'') may be
389 changed with the following variables:
392 @item guix-package-list-buffer-name
393 @item guix-output-list-buffer-name
394 @item guix-generation-list-buffer-name
395 @item guix-package-info-buffer-name
396 @item guix-output-info-buffer-name
397 @item guix-generation-info-buffer-name
398 @item guix-repl-buffer-name
399 @item guix-internal-repl-buffer-name
402 By default, the name of a profile is also displayed in a ``list'' or
403 ``info'' buffer name. To change this behavior, use
404 @code{guix-buffer-name-function} variable.
406 For example, if you want to display all types of results in a single
407 buffer (in such case you will probably use a history (@kbd{l}/@kbd{r})
408 extensively), you may do it like this:
411 (let ((name "Guix Universal"))
413 guix-package-list-buffer-name name
414 guix-output-list-buffer-name name
415 guix-generation-list-buffer-name name
416 guix-package-info-buffer-name name
417 guix-output-info-buffer-name name
418 guix-generation-info-buffer-name name
419 guix-buffer-name-function #'guix-buffer-name-simple))
423 @subsubsection Keymaps
425 If you want to change default key bindings, use the following keymaps
426 (@pxref{Init Rebinding,,, emacs, The GNU Emacs Manual}):
430 Parent keymap with general keys for all guix modes.
432 @item guix-list-mode-map
433 Parent keymap with general keys for ``list'' buffers.
435 @item guix-package-list-mode-map
436 Keymap with specific keys for ``package-list'' buffers.
438 @item guix-output-list-mode-map
439 Keymap with specific keys for ``output-list'' buffers.
441 @item guix-generation-list-mode-map
442 Keymap with specific keys for ``generation-list'' buffers.
444 @item guix-info-mode-map
445 Parent keymap with general keys for ``info'' buffers.
447 @item guix-package-info-mode-map
448 Keymap with specific keys for ``package-info'' buffers.
450 @item guix-output-info-mode-map
451 Keymap with specific keys for ``output-info'' buffers.
453 @item guix-generation-info-mode-map
454 Keymap with specific keys for ``generation-info'' buffers.
456 @item guix-info-button-map
457 Keymap with keys available when a point is placed on a button.
461 @node Emacs Appearance
462 @subsubsection Appearance
464 You can change almost any aspect of ``list'' / ``info'' buffers using
465 the following variables:
468 @item guix-list-column-format
469 @itemx guix-list-column-titles
470 @itemx guix-list-column-value-methods
471 Specify the columns, their names, what and how is displayed in ``list''
474 @item guix-info-displayed-params
475 @itemx guix-info-insert-methods
476 @itemx guix-info-ignore-empty-vals
477 @itemx guix-info-param-title-format
478 @itemx guix-info-multiline-prefix
479 @itemx guix-info-indent
480 @itemx guix-info-fill-column
481 @itemx guix-info-delimiter
482 Various settings for ``info'' buffers.
488 @subsection Guix Prettify Mode
490 Along with ``guix.el'', GNU@tie{}Guix comes with ``guix-prettify.el''.
491 It provides a minor mode for abbreviating store file names by replacing
492 hash sequences of symbols with ``@dots{}'':
495 /gnu/store/72f54nfp6g1hz873w8z3gfcah0h4nl9p-foo-0.1
496 @result{} /gnu/store/…-foo-0.1
499 Once you set up ``guix.el'' (@pxref{Emacs Initial Setup}), the following
500 commands become available:
504 @item M-x guix-prettify-mode
505 Enable/disable prettifying for the current buffer.
507 @item M-x global-guix-prettify-mode
508 Enable/disable prettifying globally.
512 To automatically enable @code{guix-prettify-mode} globally on Emacs
513 start, add the following line to your init file:
516 (global-guix-prettify-mode)
519 If you want to enable it only for specific major modes, add it to the
520 mode hooks (@pxref{Hooks,,, emacs, The GNU Emacs Manual}), for example:
523 (add-hook 'shell-mode-hook 'guix-prettify-mode)
524 (add-hook 'dired-mode-hook 'guix-prettify-mode)
528 @node Emacs Completions
529 @subsection Shell Completions
531 Another feature that becomes available after configuring Emacs interface
532 (@pxref{Emacs Initial Setup}) is completing of @command{guix}
533 subcommands, options, packages and other things in @code{shell}
534 (@pxref{Interactive Shell,,, emacs, The GNU Emacs Manual}) and
535 @code{eshell} (@pxref{Top,,, eshell, Eshell: The Emacs Shell}).
537 It works the same way as other completions do. Just press @key{TAB}
538 when your intuition tells you.
540 And here are some examples, where pressing @key{TAB} may complete
545 @item @code{guix pa}@key{TAB}
546 @item @code{guix package -}@key{TAB}
547 @item @code{guix package --}@key{TAB}
548 @item @code{guix package -i gei}@key{TAB}
549 @item @code{guix build -L/tm}@key{TAB}
550 @item @code{guix build --sy}@key{TAB}
551 @item @code{guix build --system=i}@key{TAB}
552 @item @code{guix system rec}@key{TAB}
553 @item @code{guix lint --checkers=sy}@key{TAB}
554 @item @code{guix lint --checkers=synopsis,des}@key{TAB}