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.
24 @node Emacs Initial Setup
25 @subsection Initial Setup
27 On the Guix System Distribution (@pxref{GNU Distribution}), ``guix.el''
28 is ready to use, provided Guix is installed system-wide, which is the
29 case by default. So if that is what you're using, you can happily skip
30 this section and read about the fun stuff.
32 If you're not yet a happy user of GSD, a little bit of setup is needed.
33 To be able to use ``guix.el'', you need to install the following
38 @uref{http://www.gnu.org/software/emacs/, GNU Emacs}, version 24.3 or
42 @uref{http://nongnu.org/geiser/, Geiser}, version 0.3 or later: it is
43 used for interacting with the Guile process.
47 When it is done, add the following into your init file (@pxref{Init
48 File,,, emacs, The GNU Emacs Manual}):
51 (require 'guix-init nil t)
54 However there is a chance that @code{load-path} of your Emacs does not
55 contain a directory with ``guix.el'' (usually it is
56 @file{/usr/share/emacs/site-lisp/}). In that case you need to add it
57 before requiring (@pxref{Lisp Libraries,,, emacs, The GNU Emacs
61 (add-to-list 'load-path "/path/to/directory-with-guix.el")
65 By default, along with autoloading (@pxref{Autoload,,, elisp, The GNU
66 Emacs Lisp Reference Manual}) the main interactive commands for
67 ``guix.el'' (@pxref{Emacs Commands}), requiring @code{guix-init} will
68 also autoload commands for the Emacs packages installed in your user
71 To disable automatic loading of installed Emacs packages, set
72 @code{guix-package-enable-at-startup} variable to @code{nil} before
73 requiring @code{guix-init}. This variable has the same meaning for
74 Emacs packages installed with Guix, as @code{package-enable-at-startup}
75 for the built-in Emacs package system (@pxref{Package Installation,,,
76 emacs, The GNU Emacs Manual}).
78 You can activate Emacs packages installed in your profile whenever you
79 want using @kbd{M-x@tie{}guix-emacs-load-autoloads}.
84 Once ``guix.el'' has been successfully configured, you should be able to
85 use commands for displaying packages and generations. This information
86 can be displayed in a ``list'' or ``info'' buffer.
89 * Commands: Emacs Commands. @kbd{M-x guix-@dots{}}
90 * General information: Emacs General info. Common for both interfaces.
91 * ``List'' buffer: Emacs List buffer. List-like interface.
92 * ``Info'' buffer: Emacs Info buffer. Help-like interface.
96 @subsubsection Commands
98 All commands for displaying packages and generations use the current
99 profile, which can be changed with
100 @kbd{M-x@tie{}guix-set-current-profile}. Alternatively, if you call any
101 of these commands with prefix argument (@kbd{C-u}), you will be prompted
102 for a profile just for that command.
104 Commands for displaying packages:
108 @item M-x guix-all-available-packages
109 @itemx M-x guix-newest-available-packages
110 Display all/newest available packages.
112 @item M-x guix-installed-packages
113 Display all installed packages.
115 @item M-x guix-obsolete-packages
116 Display obsolete packages (the packages that are installed in a profile
117 but cannot be found among available packages).
119 @item M-x guix-search-by-name
120 Display package(s) with the specified name.
122 @item M-x guix-search-by-regexp
123 Search for packages by a specified regexp. By default ``name'',
124 ``synopsis'' and ``description'' of the packages will be searched. This
125 can be changed by modifying @code{guix-search-params} variable.
129 By default, these commands display each output on a separate line. If
130 you prefer to see a list of packages---i.e., a list with a package per
131 line, use the following setting:
134 (setq guix-package-list-type 'package)
137 Commands for displaying generations:
141 @item M-x guix-generations
142 List all the generations.
144 @item M-x guix-last-generations
145 List the @var{N} last generations. You will be prompted for the number
148 @item M-x guix-generations-by-time
149 List generations matching time period. You will be prompted for the
150 period using Org mode time prompt based on Emacs calendar (@pxref{The
151 date/time prompt,,, org, The Org Manual}).
155 You can also invoke the @command{guix pull} command (@pxref{Invoking
156 guix pull}) from Emacs using:
160 With @kbd{C-u}, make it verbose.
163 Once @command{guix pull} has succeeded, the Guix REPL is restared. This
164 allows you to keep using the Emacs interface with the updated Guix.
166 @node Emacs General info
167 @subsubsection General information
169 The following keys are available for both ``list'' and ``info'' types of
175 Go backward/forward by the history of the displayed results (this
176 history is similar to the history of the Emacs @code{help-mode} or
180 Revert current buffer: update information about the displayed
181 packages/generations and redisplay it.
184 Redisplay current buffer (without updating information).
187 Go to the Guix REPL (@pxref{The REPL,,, geiser, Geiser User Manual}).
191 Describe current mode to see all available bindings.
195 @emph{Hint:} If you need several ``list'' or ``info'' buffers, you can
196 simlpy @kbd{M-x clone-buffer} them, and each buffer will have its own
199 @emph{Warning:} Name/version pairs cannot be used to identify packages
200 (because a name is not necessarily unique), so ``guix.el'' uses special
201 identifiers that live only during a guile session, so if the Guix REPL
202 was restarted, you may want to revert ``list'' buffer (by pressing
205 @node Emacs List buffer
206 @subsubsection ``List'' buffer
208 An interface of a ``list'' buffer is similar to the interface provided
209 by ``package.el'' (@pxref{Package Menu,,, emacs, The GNU Emacs Manual}).
211 Default key bindings available for both ``package-list'' and
212 ``generation-list'' buffers:
216 Mark the current entry.
220 Unmark the current entry (with prefix, unmark all entries).
224 Sort entries by a specified column.
227 A ``package-list'' buffer additionally provides the following bindings:
231 Describe marked packages (display available information in a
232 ``package-info'' buffer).
234 Mark the current package for installation.
236 Mark the current package for deletion.
238 Mark the current package for upgrading.
240 Mark all obsolete packages for upgrading.
242 Execute actions on the marked packages.
245 A ``generation-list'' buffer additionally provides the following
250 List packages installed in the current generation.
252 Describe marked generations (display available information in a
253 ``generation-info'' buffer).
255 Switch profile to the current generation.
257 Mark the current generation for deletion (with prefix, mark all
260 Execute actions on the marked generations---i.e., delete generations.
262 Run Ediff (@pxref{Top,,, ediff, The Ediff Manual}) on package outputs
263 installed in the 2 marked generations. With prefix argument, run Ediff
264 on manifests of the marked generations.
267 Run Diff (@pxref{Diff Mode,,, emacs, The GNU Emacs Manual}) on package
268 outputs installed in the 2 marked generations. With prefix argument,
269 run Diff on manifests of the marked generations.
271 List package outputs added to the latest marked generation comparing
272 with another marked generation.
274 List package outputs removed from the latest marked generation comparing
275 with another marked generation.
278 @node Emacs Info buffer
279 @subsubsection ``Info'' buffer
281 The interface of an ``info'' buffer is similar to the interface of
282 @code{help-mode} (@pxref{Help Mode,,, emacs, The GNU Emacs Manual}).
284 ``Info'' buffer contains some buttons (as usual you may use @key{TAB} /
285 @kbd{S-@key{TAB}} to move between buttons---@pxref{Mouse References,,,
286 emacs, The GNU Emacs Manual}) which can be used to:
289 @item (in a ``package-info'' buffer)
292 @item install/remove a package;
293 @item jump to a package location;
294 @item browse home page of a package;
295 @item describe packages from ``Inputs'' fields.
298 @item (in a ``generation-info'' buffer)
301 @item remove a generation;
302 @item switch to a generation;
303 @item list packages installed in a generation;
304 @item jump to a generation directory.
309 It is also possible to copy a button label (a link to an URL or a file)
310 by pressing @kbd{c} on a button.
313 @node Emacs Configuration
314 @subsection Configuration
316 There are many variables you can modify to change the appearance or
317 behavior of Emacs user interface. Some of these variables are described
318 in this section. Also you can use Custom Interface (@pxref{Easy
319 Customization,,, emacs, The GNU Emacs Manual}) to explore/set variables
323 * Guile and Build Options: Emacs Build Options. Specifying how packages are built.
324 * Buffer Names: Emacs Buffer Names. Names of Guix buffers.
325 * Keymaps: Emacs Keymaps. Configuring key bindings.
326 * Appearance: Emacs Appearance. Settings for visual appearance.
329 @node Emacs Build Options
330 @subsubsection Guile and Build Options
333 @item guix-guile-program
334 If you have some special needs for starting a Guile process, you may set
335 this variable, for example:
338 (setq guix-guile-program '("/bin/guile" "--no-auto-compile"))
341 @item guix-use-substitutes
342 Has the same meaning as @code{--no-substitutes} option (@pxref{Invoking
346 Has the same meaning as @code{--dry-run} option (@pxref{Invoking guix
351 @node Emacs Buffer Names
352 @subsubsection Buffer Names
354 Default names of ``guix.el'' buffers (``*Guix@tie{}@dots{}*'') may be
355 changed with the following variables:
358 @item guix-package-list-buffer-name
359 @item guix-output-list-buffer-name
360 @item guix-generation-list-buffer-name
361 @item guix-package-info-buffer-name
362 @item guix-output-info-buffer-name
363 @item guix-generation-info-buffer-name
364 @item guix-repl-buffer-name
365 @item guix-internal-repl-buffer-name
368 By default, the name of a profile is also displayed in a ``list'' or
369 ``info'' buffer name. To change this behavior, use
370 @code{guix-buffer-name-function} variable.
372 For example, if you want to display all types of results in a single
373 buffer (in such case you will probably use a history (@kbd{l}/@kbd{r})
374 extensively), you may do it like this:
377 (let ((name "Guix Universal"))
379 guix-package-list-buffer-name name
380 guix-output-list-buffer-name name
381 guix-generation-list-buffer-name name
382 guix-package-info-buffer-name name
383 guix-output-info-buffer-name name
384 guix-generation-info-buffer-name name
385 guix-buffer-name-function #'guix-buffer-name-simple))
389 @subsubsection Keymaps
391 If you want to change default key bindings, use the following keymaps
392 (@pxref{Init Rebinding,,, emacs, The GNU Emacs Manual}):
395 @item guix-list-mode-map
396 Parent keymap with general keys for ``list'' buffers.
398 @item guix-package-list-mode-map
399 Keymap with specific keys for ``package-list'' buffers.
401 @item guix-output-list-mode-map
402 Keymap with specific keys for ``output-list'' buffers.
404 @item guix-generation-list-mode-map
405 Keymap with specific keys for ``generation-list'' buffers.
407 @item guix-info-mode-map
408 Parent keymap with general keys for ``info'' buffers.
410 @item guix-package-info-mode-map
411 Keymap with specific keys for ``package-info'' buffers.
413 @item guix-output-info-mode-map
414 Keymap with specific keys for ``output-info'' buffers.
416 @item guix-generation-info-mode-map
417 Keymap with specific keys for ``generation-info'' buffers.
419 @item guix-info-button-map
420 Keymap with keys available when a point is placed on a button.
424 @node Emacs Appearance
425 @subsubsection Appearance
427 You can change almost any aspect of ``list'' / ``info'' buffers using
428 the following variables:
431 @item guix-list-column-format
432 @itemx guix-list-column-titles
433 @itemx guix-list-column-value-methods
434 Specify the columns, their names, what and how is displayed in ``list''
437 @item guix-info-displayed-params
438 @itemx guix-info-insert-methods
439 @itemx guix-info-ignore-empty-vals
440 @itemx guix-info-param-title-format
441 @itemx guix-info-multiline-prefix
442 @itemx guix-info-indent
443 @itemx guix-info-fill-column
444 @itemx guix-info-delimiter
445 Various settings for ``info'' buffers.
451 @subsection Guix Prettify Mode
453 Along with ``guix.el'', GNU@tie{}Guix comes with ``guix-prettify.el''.
454 It provides a minor mode for abbreviating store file names by replacing
455 hash sequences of symbols with ``@dots{}'':
458 /gnu/store/72f54nfp6g1hz873w8z3gfcah0h4nl9p-foo-0.1
459 @result{} /gnu/store/…-foo-0.1
462 Once you set up ``guix.el'' (@pxref{Emacs Initial Setup}), the following
463 commands become available:
467 @item M-x guix-prettify-mode
468 Enable/disable prettifying for the current buffer.
470 @item M-x global-guix-prettify-mode
471 Enable/disable prettifying globally.
475 To automatically enable @code{guix-prettify-mode} globally on Emacs
476 start, add the following line to your init file:
479 (global-guix-prettify-mode)
482 If you want to enable it only for specific major modes, add it to the
483 mode hooks (@pxref{Hooks,,, emacs, The GNU Emacs Manual}), for example:
486 (add-hook 'shell-mode-hook 'guix-prettify-mode)
487 (add-hook 'dired-mode-hook 'guix-prettify-mode)