Commit | Line | Data |
---|---|---|
457f60fa AK |
1 | @node Emacs Interface |
2 | @section Emacs Interface | |
3 | ||
bd53d327 | 4 | @cindex Emacs |
457f60fa AK |
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: | |
9 | ||
10 | @itemize | |
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. | |
15 | @end itemize | |
16 | ||
17 | @menu | |
bd53d327 AK |
18 | * Initial Setup: Emacs Initial Setup. Preparing @file{~/.emacs}. |
19 | * Usage: Emacs Usage. Using the interface. | |
20 | * Configuration: Emacs Configuration. Configuring the interface. | |
9a130e19 | 21 | * Prettify Mode: Emacs Prettify. Abbreviating @file{/gnu/store/@dots{}} file names. |
00a8dae2 | 22 | * Completions: Emacs Completions. Completing @command{guix} shell command. |
457f60fa AK |
23 | @end menu |
24 | ||
bd53d327 | 25 | @node Emacs Initial Setup |
457f60fa AK |
26 | @subsection Initial Setup |
27 | ||
80ae897f LC |
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. | |
32 | ||
ba3bcec9 | 33 | If you're not yet a happy user of GuixSD, a little bit of setup is needed. |
457f60fa AK |
34 | To be able to use ``guix.el'', you need to install the following |
35 | packages: | |
36 | ||
37 | @itemize | |
38 | @item | |
39 | @uref{http://www.gnu.org/software/emacs/, GNU Emacs}, version 24.3 or | |
40 | later; | |
41 | ||
42 | @item | |
43 | @uref{http://nongnu.org/geiser/, Geiser}, version 0.3 or later: it is | |
44 | used for interacting with the Guile process. | |
45 | ||
46 | @end itemize | |
47 | ||
48 | When it is done, add the following into your init file (@pxref{Init | |
773bab64 | 49 | File,,, emacs, The GNU Emacs Manual}): |
457f60fa AK |
50 | |
51 | @example | |
52 | (require 'guix-init nil t) | |
53 | @end example | |
54 | ||
55 | However there is a chance that @code{load-path} of your Emacs does not | |
56 | contain a directory with ``guix.el'' (usually it is | |
57 | @file{/usr/share/emacs/site-lisp/}). In that case you need to add it | |
773bab64 AK |
58 | before requiring (@pxref{Lisp Libraries,,, emacs, The GNU Emacs |
59 | Manual}): | |
457f60fa AK |
60 | |
61 | @example | |
62 | (add-to-list 'load-path "/path/to/directory-with-guix.el") | |
63 | (require 'guix-init) | |
64 | @end example | |
65 | ||
a7f862e4 AK |
66 | By default, along with autoloading (@pxref{Autoload,,, elisp, The GNU |
67 | Emacs Lisp Reference Manual}) the main interactive commands for | |
68 | ``guix.el'' (@pxref{Emacs Commands}), requiring @code{guix-init} will | |
69 | also autoload commands for the Emacs packages installed in your user | |
70 | profile. | |
71 | ||
72 | To disable automatic loading of installed Emacs packages, set | |
73 | @code{guix-package-enable-at-startup} variable to @code{nil} before | |
74 | requiring @code{guix-init}. This variable has the same meaning for | |
75 | Emacs packages installed with Guix, as @code{package-enable-at-startup} | |
5ec98c3d | 76 | for the built-in Emacs package system (@pxref{Package Installation,,, |
a7f862e4 AK |
77 | emacs, The GNU Emacs Manual}). |
78 | ||
79 | You can activate Emacs packages installed in your profile whenever you | |
80 | want using @kbd{M-x@tie{}guix-emacs-load-autoloads}. | |
457f60fa | 81 | |
bd53d327 | 82 | @node Emacs Usage |
457f60fa AK |
83 | @subsection Usage |
84 | ||
85 | Once ``guix.el'' has been successfully configured, you should be able to | |
86 | use commands for displaying packages and generations. This information | |
87 | can be displayed in a ``list'' or ``info'' buffer. | |
88 | ||
89 | @menu | |
bd53d327 AK |
90 | * Commands: Emacs Commands. @kbd{M-x guix-@dots{}} |
91 | * General information: Emacs General info. Common for both interfaces. | |
92 | * ``List'' buffer: Emacs List buffer. List-like interface. | |
93 | * ``Info'' buffer: Emacs Info buffer. Help-like interface. | |
457f60fa AK |
94 | @end menu |
95 | ||
bd53d327 | 96 | @node Emacs Commands |
457f60fa AK |
97 | @subsubsection Commands |
98 | ||
23459fa5 AK |
99 | All commands for displaying packages and generations use the current |
100 | profile, which can be changed with | |
101 | @kbd{M-x@tie{}guix-set-current-profile}. Alternatively, if you call any | |
102 | of these commands with prefix argument (@kbd{C-u}), you will be prompted | |
103 | for a profile just for that command. | |
104 | ||
105 | Commands for displaying packages: | |
457f60fa AK |
106 | |
107 | @table @kbd | |
23459fa5 | 108 | |
457f60fa AK |
109 | @item M-x guix-all-available-packages |
110 | @itemx M-x guix-newest-available-packages | |
111 | Display all/newest available packages. | |
112 | ||
113 | @item M-x guix-installed-packages | |
23459fa5 | 114 | Display all installed packages. |
457f60fa AK |
115 | |
116 | @item M-x guix-obsolete-packages | |
23459fa5 AK |
117 | Display obsolete packages (the packages that are installed in a profile |
118 | but cannot be found among available packages). | |
457f60fa AK |
119 | |
120 | @item M-x guix-search-by-name | |
121 | Display package(s) with the specified name. | |
122 | ||
123 | @item M-x guix-search-by-regexp | |
124 | Search for packages by a specified regexp. By default ``name'', | |
125 | ``synopsis'' and ``description'' of the packages will be searched. This | |
126 | can be changed by modifying @code{guix-search-params} variable. | |
127 | ||
457f60fa AK |
128 | @end table |
129 | ||
23459fa5 AK |
130 | By default, these commands display each output on a separate line. If |
131 | you prefer to see a list of packages---i.e., a list with a package per | |
132 | line, use the following setting: | |
a54a237b AK |
133 | |
134 | @example | |
135 | (setq guix-package-list-type 'package) | |
136 | @end example | |
137 | ||
23459fa5 AK |
138 | Commands for displaying generations: |
139 | ||
140 | @table @kbd | |
141 | ||
142 | @item M-x guix-generations | |
143 | List all the generations. | |
144 | ||
145 | @item M-x guix-last-generations | |
146 | List the @var{N} last generations. You will be prompted for the number | |
147 | of generations. | |
148 | ||
149 | @item M-x guix-generations-by-time | |
150 | List generations matching time period. You will be prompted for the | |
151 | period using Org mode time prompt based on Emacs calendar (@pxref{The | |
773bab64 | 152 | date/time prompt,,, org, The Org Manual}). |
23459fa5 AK |
153 | |
154 | @end table | |
457f60fa | 155 | |
2d7bf949 AK |
156 | You can also invoke the @command{guix pull} command (@pxref{Invoking |
157 | guix pull}) from Emacs using: | |
158 | ||
159 | @table @kbd | |
160 | @item M-x guix-pull | |
161 | With @kbd{C-u}, make it verbose. | |
162 | @end table | |
163 | ||
164 | Once @command{guix pull} has succeeded, the Guix REPL is restared. This | |
165 | allows you to keep using the Emacs interface with the updated Guix. | |
166 | ||
bd53d327 | 167 | @node Emacs General info |
457f60fa AK |
168 | @subsubsection General information |
169 | ||
170 | The following keys are available for both ``list'' and ``info'' types of | |
171 | buffers: | |
172 | ||
173 | @table @kbd | |
174 | @item l | |
175 | @itemx r | |
176 | Go backward/forward by the history of the displayed results (this | |
177 | history is similar to the history of the Emacs @code{help-mode} or | |
178 | @code{Info-mode}). | |
179 | ||
180 | @item g | |
181 | Revert current buffer: update information about the displayed | |
182 | packages/generations and redisplay it. | |
183 | ||
184 | @item R | |
185 | Redisplay current buffer (without updating information). | |
186 | ||
5a727cdf AK |
187 | @item M |
188 | Apply manifest to the current profile or to a specified profile, if | |
189 | prefix argument is used. This has the same meaning as @code{--manifest} | |
190 | option (@pxref{Invoking guix package}). | |
191 | ||
457f60fa AK |
192 | @item C-c C-z |
193 | Go to the Guix REPL (@pxref{The REPL,,, geiser, Geiser User Manual}). | |
194 | ||
195 | @item h | |
196 | @itemx ? | |
197 | Describe current mode to see all available bindings. | |
198 | ||
199 | @end table | |
200 | ||
201 | @emph{Hint:} If you need several ``list'' or ``info'' buffers, you can | |
202 | simlpy @kbd{M-x clone-buffer} them, and each buffer will have its own | |
203 | history. | |
204 | ||
205 | @emph{Warning:} Name/version pairs cannot be used to identify packages | |
206 | (because a name is not necessarily unique), so ``guix.el'' uses special | |
207 | identifiers that live only during a guile session, so if the Guix REPL | |
208 | was restarted, you may want to revert ``list'' buffer (by pressing | |
209 | @kbd{g}). | |
210 | ||
bd53d327 | 211 | @node Emacs List buffer |
457f60fa AK |
212 | @subsubsection ``List'' buffer |
213 | ||
214 | An interface of a ``list'' buffer is similar to the interface provided | |
773bab64 | 215 | by ``package.el'' (@pxref{Package Menu,,, emacs, The GNU Emacs Manual}). |
457f60fa AK |
216 | |
217 | Default key bindings available for both ``package-list'' and | |
218 | ``generation-list'' buffers: | |
219 | ||
220 | @table @kbd | |
221 | @item m | |
578b98da | 222 | Mark the current entry (with prefix, mark all entries). |
457f60fa | 223 | @item u |
91cc37a1 | 224 | Unmark the current entry (with prefix, unmark all entries). |
457f60fa AK |
225 | @item @key{DEL} |
226 | Unmark backward. | |
457f60fa AK |
227 | @item S |
228 | Sort entries by a specified column. | |
229 | @end table | |
230 | ||
231 | A ``package-list'' buffer additionally provides the following bindings: | |
232 | ||
233 | @table @kbd | |
234 | @item @key{RET} | |
235 | Describe marked packages (display available information in a | |
236 | ``package-info'' buffer). | |
237 | @item i | |
a54a237b | 238 | Mark the current package for installation. |
457f60fa | 239 | @item d |
a54a237b | 240 | Mark the current package for deletion. |
91cc37a1 | 241 | @item U |
a54a237b | 242 | Mark the current package for upgrading. |
457f60fa | 243 | @item ^ |
91cc37a1 | 244 | Mark all obsolete packages for upgrading. |
457f60fa | 245 | @item x |
a54a237b | 246 | Execute actions on the marked packages. |
457f60fa AK |
247 | @end table |
248 | ||
249 | A ``generation-list'' buffer additionally provides the following | |
250 | bindings: | |
251 | ||
252 | @table @kbd | |
253 | @item @key{RET} | |
254 | List packages installed in the current generation. | |
255 | @item i | |
256 | Describe marked generations (display available information in a | |
257 | ``generation-info'' buffer). | |
af874238 AK |
258 | @item s |
259 | Switch profile to the current generation. | |
cb6a5c71 AK |
260 | @item d |
261 | Mark the current generation for deletion (with prefix, mark all | |
262 | generations). | |
263 | @item x | |
264 | Execute actions on the marked generations---i.e., delete generations. | |
d38bd08c AK |
265 | @item e |
266 | Run Ediff (@pxref{Top,,, ediff, The Ediff Manual}) on package outputs | |
267 | installed in the 2 marked generations. With prefix argument, run Ediff | |
268 | on manifests of the marked generations. | |
269 | @item D | |
270 | @itemx = | |
271 | Run Diff (@pxref{Diff Mode,,, emacs, The GNU Emacs Manual}) on package | |
272 | outputs installed in the 2 marked generations. With prefix argument, | |
273 | run Diff on manifests of the marked generations. | |
274 | @item + | |
275 | List package outputs added to the latest marked generation comparing | |
276 | with another marked generation. | |
277 | @item - | |
278 | List package outputs removed from the latest marked generation comparing | |
279 | with another marked generation. | |
457f60fa AK |
280 | @end table |
281 | ||
bd53d327 | 282 | @node Emacs Info buffer |
457f60fa AK |
283 | @subsubsection ``Info'' buffer |
284 | ||
285 | The interface of an ``info'' buffer is similar to the interface of | |
773bab64 | 286 | @code{help-mode} (@pxref{Help Mode,,, emacs, The GNU Emacs Manual}). |
457f60fa AK |
287 | |
288 | ``Info'' buffer contains some buttons (as usual you may use @key{TAB} / | |
289 | @kbd{S-@key{TAB}} to move between buttons---@pxref{Mouse References,,, | |
773bab64 | 290 | emacs, The GNU Emacs Manual}) which can be used to: |
457f60fa AK |
291 | |
292 | @itemize @bullet | |
293 | @item (in a ``package-info'' buffer) | |
294 | ||
295 | @itemize @minus | |
296 | @item install/remove a package; | |
297 | @item jump to a package location; | |
298 | @item browse home page of a package; | |
299 | @item describe packages from ``Inputs'' fields. | |
300 | @end itemize | |
301 | ||
302 | @item (in a ``generation-info'' buffer) | |
303 | ||
304 | @itemize @minus | |
305 | @item remove a generation; | |
af874238 | 306 | @item switch to a generation; |
457f60fa AK |
307 | @item list packages installed in a generation; |
308 | @item jump to a generation directory. | |
309 | @end itemize | |
310 | ||
311 | @end itemize | |
312 | ||
56149217 AK |
313 | It is also possible to copy a button label (a link to an URL or a file) |
314 | by pressing @kbd{c} on a button. | |
315 | ||
457f60fa | 316 | |
bd53d327 | 317 | @node Emacs Configuration |
457f60fa AK |
318 | @subsection Configuration |
319 | ||
320 | There are many variables you can modify to change the appearance or | |
321 | behavior of Emacs user interface. Some of these variables are described | |
322 | in this section. Also you can use Custom Interface (@pxref{Easy | |
773bab64 AK |
323 | Customization,,, emacs, The GNU Emacs Manual}) to explore/set variables |
324 | (not all) and faces. | |
457f60fa AK |
325 | |
326 | @menu | |
bd53d327 AK |
327 | * Guile and Build Options: Emacs Build Options. Specifying how packages are built. |
328 | * Buffer Names: Emacs Buffer Names. Names of Guix buffers. | |
329 | * Keymaps: Emacs Keymaps. Configuring key bindings. | |
330 | * Appearance: Emacs Appearance. Settings for visual appearance. | |
457f60fa AK |
331 | @end menu |
332 | ||
bd53d327 | 333 | @node Emacs Build Options |
457f60fa AK |
334 | @subsubsection Guile and Build Options |
335 | ||
336 | @table @code | |
337 | @item guix-guile-program | |
338 | If you have some special needs for starting a Guile process, you may set | |
339 | this variable, for example: | |
340 | ||
341 | @example | |
342 | (setq guix-guile-program '("/bin/guile" "--no-auto-compile")) | |
343 | @end example | |
344 | ||
345 | @item guix-use-substitutes | |
346 | Has the same meaning as @code{--no-substitutes} option (@pxref{Invoking | |
347 | guix build}). | |
348 | ||
349 | @item guix-dry-run | |
350 | Has the same meaning as @code{--dry-run} option (@pxref{Invoking guix | |
351 | build}). | |
352 | ||
353 | @end table | |
354 | ||
bd53d327 | 355 | @node Emacs Buffer Names |
a54a237b AK |
356 | @subsubsection Buffer Names |
357 | ||
358 | Default names of ``guix.el'' buffers (``*Guix@tie{}@dots{}*'') may be | |
359 | changed with the following variables: | |
360 | ||
361 | @table @code | |
362 | @item guix-package-list-buffer-name | |
363 | @item guix-output-list-buffer-name | |
364 | @item guix-generation-list-buffer-name | |
365 | @item guix-package-info-buffer-name | |
366 | @item guix-output-info-buffer-name | |
367 | @item guix-generation-info-buffer-name | |
368 | @item guix-repl-buffer-name | |
369 | @item guix-internal-repl-buffer-name | |
a54a237b AK |
370 | @end table |
371 | ||
23459fa5 AK |
372 | By default, the name of a profile is also displayed in a ``list'' or |
373 | ``info'' buffer name. To change this behavior, use | |
374 | @code{guix-buffer-name-function} variable. | |
375 | ||
376 | For example, if you want to display all types of results in a single | |
a54a237b AK |
377 | buffer (in such case you will probably use a history (@kbd{l}/@kbd{r}) |
378 | extensively), you may do it like this: | |
379 | ||
380 | @example | |
381 | (let ((name "Guix Universal")) | |
382 | (setq | |
383 | guix-package-list-buffer-name name | |
384 | guix-output-list-buffer-name name | |
385 | guix-generation-list-buffer-name name | |
386 | guix-package-info-buffer-name name | |
387 | guix-output-info-buffer-name name | |
23459fa5 AK |
388 | guix-generation-info-buffer-name name |
389 | guix-buffer-name-function #'guix-buffer-name-simple)) | |
a54a237b AK |
390 | @end example |
391 | ||
bd53d327 | 392 | @node Emacs Keymaps |
457f60fa AK |
393 | @subsubsection Keymaps |
394 | ||
395 | If you want to change default key bindings, use the following keymaps | |
773bab64 | 396 | (@pxref{Init Rebinding,,, emacs, The GNU Emacs Manual}): |
457f60fa AK |
397 | |
398 | @table @code | |
399 | @item guix-list-mode-map | |
400 | Parent keymap with general keys for ``list'' buffers. | |
401 | ||
402 | @item guix-package-list-mode-map | |
403 | Keymap with specific keys for ``package-list'' buffers. | |
404 | ||
a54a237b AK |
405 | @item guix-output-list-mode-map |
406 | Keymap with specific keys for ``output-list'' buffers. | |
407 | ||
457f60fa AK |
408 | @item guix-generation-list-mode-map |
409 | Keymap with specific keys for ``generation-list'' buffers. | |
410 | ||
411 | @item guix-info-mode-map | |
412 | Parent keymap with general keys for ``info'' buffers. | |
413 | ||
414 | @item guix-package-info-mode-map | |
415 | Keymap with specific keys for ``package-info'' buffers. | |
416 | ||
a54a237b AK |
417 | @item guix-output-info-mode-map |
418 | Keymap with specific keys for ``output-info'' buffers. | |
419 | ||
457f60fa AK |
420 | @item guix-generation-info-mode-map |
421 | Keymap with specific keys for ``generation-info'' buffers. | |
422 | ||
56149217 AK |
423 | @item guix-info-button-map |
424 | Keymap with keys available when a point is placed on a button. | |
425 | ||
457f60fa AK |
426 | @end table |
427 | ||
bd53d327 | 428 | @node Emacs Appearance |
457f60fa AK |
429 | @subsubsection Appearance |
430 | ||
431 | You can change almost any aspect of ``list'' / ``info'' buffers using | |
432 | the following variables: | |
433 | ||
434 | @table @code | |
435 | @item guix-list-column-format | |
436 | @itemx guix-list-column-titles | |
437 | @itemx guix-list-column-value-methods | |
438 | Specify the columns, their names, what and how is displayed in ``list'' | |
439 | buffers. | |
440 | ||
441 | @item guix-info-displayed-params | |
442 | @itemx guix-info-insert-methods | |
443 | @itemx guix-info-ignore-empty-vals | |
444 | @itemx guix-info-param-title-format | |
445 | @itemx guix-info-multiline-prefix | |
446 | @itemx guix-info-indent | |
447 | @itemx guix-info-fill-column | |
448 | @itemx guix-info-delimiter | |
449 | Various settings for ``info'' buffers. | |
450 | ||
451 | @end table | |
9a130e19 AK |
452 | |
453 | ||
454 | @node Emacs Prettify | |
455 | @subsection Guix Prettify Mode | |
456 | ||
457 | Along with ``guix.el'', GNU@tie{}Guix comes with ``guix-prettify.el''. | |
458 | It provides a minor mode for abbreviating store file names by replacing | |
459 | hash sequences of symbols with ``@dots{}'': | |
460 | ||
461 | @example | |
462 | /gnu/store/72f54nfp6g1hz873w8z3gfcah0h4nl9p-foo-0.1 | |
463 | @result{} /gnu/store/…-foo-0.1 | |
464 | @end example | |
465 | ||
466 | Once you set up ``guix.el'' (@pxref{Emacs Initial Setup}), the following | |
467 | commands become available: | |
468 | ||
469 | @table @kbd | |
470 | ||
471 | @item M-x guix-prettify-mode | |
472 | Enable/disable prettifying for the current buffer. | |
473 | ||
474 | @item M-x global-guix-prettify-mode | |
475 | Enable/disable prettifying globally. | |
476 | ||
477 | @end table | |
478 | ||
479 | To automatically enable @code{guix-prettify-mode} globally on Emacs | |
480 | start, add the following line to your init file: | |
481 | ||
482 | @example | |
483 | (global-guix-prettify-mode) | |
484 | @end example | |
485 | ||
486 | If you want to enable it only for specific major modes, add it to the | |
487 | mode hooks (@pxref{Hooks,,, emacs, The GNU Emacs Manual}), for example: | |
488 | ||
489 | @example | |
490 | (add-hook 'shell-mode-hook 'guix-prettify-mode) | |
491 | (add-hook 'dired-mode-hook 'guix-prettify-mode) | |
492 | @end example | |
00a8dae2 AK |
493 | |
494 | ||
495 | @node Emacs Completions | |
496 | @subsection Shell Completions | |
497 | ||
498 | Another feature that becomes available after configuring Emacs interface | |
499 | (@pxref{Emacs Initial Setup}) is completing of @command{guix} | |
500 | subcommands, options, packages and other things in @code{shell} | |
501 | (@pxref{Interactive Shell,,, emacs, The GNU Emacs Manual}) and | |
502 | @code{eshell} (@pxref{Top,,, eshell, Eshell: The Emacs Shell}). | |
503 | ||
504 | It works the same way as other completions do. Just press @key{TAB} | |
505 | when your intuition tells you. | |
506 | ||
507 | And here are some examples, where pressing @key{TAB} may complete | |
508 | something: | |
509 | ||
510 | @itemize @w{} | |
511 | ||
512 | @item @code{guix pa}@key{TAB} | |
513 | @item @code{guix package -}@key{TAB} | |
514 | @item @code{guix package --}@key{TAB} | |
515 | @item @code{guix package -i gei}@key{TAB} | |
516 | @item @code{guix build -L/tm}@key{TAB} | |
517 | @item @code{guix build --sy}@key{TAB} | |
518 | @item @code{guix build --system=i}@key{TAB} | |
519 | @item @code{guix system rec}@key{TAB} | |
520 | @item @code{guix lint --checkers=sy}@key{TAB} | |
521 | @item @code{guix lint --checkers=synopsis,des}@key{TAB} | |
522 | ||
523 | @end itemize |