Commit | Line | Data |
---|---|---|
457f60fa | 1 | @node Emacs Interface |
c554de89 | 2 | @chapter Emacs Interface |
457f60fa | 3 | |
bd53d327 | 4 | @cindex Emacs |
c554de89 AK |
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. | |
457f60fa AK |
8 | |
9 | @menu | |
bd53d327 | 10 | * Initial Setup: Emacs Initial Setup. Preparing @file{~/.emacs}. |
c554de89 | 11 | * Package Management: Emacs Package Management. Managing packages and generations. |
687c9bc0 | 12 | * Licenses: Emacs Licenses. Interface for licenses of Guix packages. |
b5e3cbbb | 13 | * Package Source Locations: Emacs Package Locations. Interface for package location files. |
9b0afb0d | 14 | * Popup Interface: Emacs Popup Interface. Magit-like interface for guix commands. |
9a130e19 | 15 | * Prettify Mode: Emacs Prettify. Abbreviating @file{/gnu/store/@dots{}} file names. |
34850cd5 | 16 | * Build Log Mode: Emacs Build Log. Highlighting Guix build logs. |
187f80c6 AK |
17 | * Completions: Emacs Completions. Completing @command{guix} shell command. |
18 | * Development: Emacs Development. Tools for Guix developers. | |
32950fc8 | 19 | * Hydra: Emacs Hydra. Interface for Guix build farm. |
457f60fa AK |
20 | @end menu |
21 | ||
c554de89 | 22 | |
bd53d327 | 23 | @node Emacs Initial Setup |
c554de89 | 24 | @section Initial Setup |
457f60fa | 25 | |
80ae897f LC |
26 | On the Guix System Distribution (@pxref{GNU Distribution}), ``guix.el'' |
27 | is ready to use, provided Guix is installed system-wide, which is the | |
28 | case by default. So if that is what you're using, you can happily skip | |
29 | this section and read about the fun stuff. | |
30 | ||
ba3bcec9 | 31 | If you're not yet a happy user of GuixSD, a little bit of setup is needed. |
457f60fa AK |
32 | To be able to use ``guix.el'', you need to install the following |
33 | packages: | |
34 | ||
35 | @itemize | |
36 | @item | |
37 | @uref{http://www.gnu.org/software/emacs/, GNU Emacs}, version 24.3 or | |
38 | later; | |
39 | ||
40 | @item | |
41 | @uref{http://nongnu.org/geiser/, Geiser}, version 0.3 or later: it is | |
42 | used for interacting with the Guile process. | |
43 | ||
9b0afb0d AK |
44 | @item |
45 | @uref{https://github.com/magit/magit/, magit-popup library}. You | |
46 | already have this library if you use Magit 2.1.0 or later. This library | |
47 | is an optional dependency---it is required only for @kbd{M-x@tie{}guix} | |
48 | command (@pxref{Emacs Popup Interface}). | |
49 | ||
457f60fa AK |
50 | @end itemize |
51 | ||
ff4455e6 | 52 | When it is done, ``guix.el'' may be configured by requiring |
6667af6a AK |
53 | @code{guix-autoloads} file. If you install Guix in your user profile, |
54 | this auto-loading is done automatically by our Emacs package | |
55 | (@pxref{Application Setup}), so a universal recipe for configuring | |
56 | ``guix.el'' is: @command{guix package -i guix}. If you do this, there | |
57 | is no need to read further. | |
58 | ||
59 | For the manual installation, you need to add the following code into | |
ff4455e6 | 60 | your init file (@pxref{Init File,,, emacs, The GNU Emacs Manual}): |
457f60fa AK |
61 | |
62 | @example | |
a72f18a5 | 63 | (add-to-list 'load-path "/path/to/directory-with-guix.el") |
ff4455e6 | 64 | (require 'guix-autoloads nil t) |
457f60fa AK |
65 | @end example |
66 | ||
a72f18a5 AK |
67 | So the only thing you need to figure out is where the directory with |
68 | elisp files for Guix is placed. It depends on how you installed Guix: | |
69 | ||
70 | @itemize | |
71 | @item | |
72 | If it was installed by a package manager of your distribution or by a | |
73 | usual @code{./configure && make && make install} command sequence, then | |
74 | elisp files are placed in a standard directory with Emacs packages | |
75 | (usually it is @file{/usr/share/emacs/site-lisp/}), which is already in | |
6667af6a AK |
76 | @code{load-path}, so there is no need to add that directory there. Note |
77 | that if you don't update this installation periodically, you may get an | |
78 | outdated Emacs code which does not work with the current Guile code of | |
79 | Guix. | |
a72f18a5 AK |
80 | |
81 | @item | |
82 | If you used a binary installation method (@pxref{Binary Installation}), | |
83 | then Guix is installed somewhere in the store, so the elisp files are | |
84 | placed in @file{/gnu/store/@dots{}-guix-0.8.2/share/emacs/site-lisp/} or | |
85 | alike. However it is not recommended to refer directly to a store | |
6667af6a AK |
86 | directory, as it may be garbage-collected one day. So a better choice |
87 | would be to install Guix using Guix itself with @command{guix package -i | |
88 | guix}. | |
a72f18a5 AK |
89 | |
90 | @item | |
91 | If you did not install Guix at all and prefer a hacking way | |
92 | (@pxref{Running Guix Before It Is Installed}), along with augmenting | |
93 | @code{load-path} you need to set @code{guix-load-path} variable to the | |
94 | same directory, so your final configuration will look like this: | |
457f60fa AK |
95 | |
96 | @example | |
a72f18a5 AK |
97 | (let ((dir "/path/to/your-guix-git-tree/emacs")) |
98 | (add-to-list 'load-path dir) | |
99 | (setq guix-load-path dir)) | |
ff4455e6 | 100 | (require 'guix-autoloads nil t) |
457f60fa | 101 | @end example |
a72f18a5 | 102 | @end itemize |
457f60fa | 103 | |
c554de89 AK |
104 | |
105 | @node Emacs Package Management | |
106 | @section Package Management | |
457f60fa AK |
107 | |
108 | Once ``guix.el'' has been successfully configured, you should be able to | |
c554de89 AK |
109 | use a visual interface for routine package management tasks, pretty much |
110 | like the @command{guix package} command (@pxref{Invoking guix package}). | |
111 | Specifically, it makes it easy to: | |
112 | ||
113 | @itemize | |
114 | @item browse and display packages and generations; | |
115 | @item search, install, upgrade and remove packages; | |
116 | @item display packages from previous generations; | |
117 | @item do some other useful things. | |
118 | @end itemize | |
457f60fa AK |
119 | |
120 | @menu | |
bd53d327 AK |
121 | * Commands: Emacs Commands. @kbd{M-x guix-@dots{}} |
122 | * General information: Emacs General info. Common for both interfaces. | |
123 | * ``List'' buffer: Emacs List buffer. List-like interface. | |
124 | * ``Info'' buffer: Emacs Info buffer. Help-like interface. | |
c554de89 | 125 | * Configuration: Emacs Configuration. Configuring the interface. |
457f60fa AK |
126 | @end menu |
127 | ||
bd53d327 | 128 | @node Emacs Commands |
c554de89 | 129 | @subsection Commands |
457f60fa | 130 | |
23459fa5 AK |
131 | All commands for displaying packages and generations use the current |
132 | profile, which can be changed with | |
133 | @kbd{M-x@tie{}guix-set-current-profile}. Alternatively, if you call any | |
134 | of these commands with prefix argument (@kbd{C-u}), you will be prompted | |
135 | for a profile just for that command. | |
136 | ||
137 | Commands for displaying packages: | |
457f60fa AK |
138 | |
139 | @table @kbd | |
23459fa5 | 140 | |
457f60fa AK |
141 | @item M-x guix-all-available-packages |
142 | @itemx M-x guix-newest-available-packages | |
143 | Display all/newest available packages. | |
144 | ||
145 | @item M-x guix-installed-packages | |
cfb1c62a AK |
146 | @itemx M-x guix-installed-user-packages |
147 | @itemx M-x guix-installed-system-packages | |
148 | Display installed packages. As described above, @kbd{M-x | |
149 | guix-installed-packages} uses an arbitrary profile that you can specify, | |
150 | while the other commands display packages installed in 2 special | |
151 | profiles: @file{~/.guix-profile} and @file{/run/current-system/profile} | |
152 | (only on GuixSD). | |
457f60fa AK |
153 | |
154 | @item M-x guix-obsolete-packages | |
23459fa5 AK |
155 | Display obsolete packages (the packages that are installed in a profile |
156 | but cannot be found among available packages). | |
457f60fa | 157 | |
e119ba90 | 158 | @item M-x guix-packages-by-name |
457f60fa AK |
159 | Display package(s) with the specified name. |
160 | ||
83aab70b AK |
161 | @item M-x guix-packages-by-license |
162 | Display package(s) with the specified license. | |
163 | ||
b4ea535a AK |
164 | @item M-x guix-packages-by-location |
165 | Display package(s) located in the specified file. These files usually | |
166 | have the following form: @file{gnu/packages/emacs.scm}, but don't type | |
167 | them manually! Press @key{TAB} to complete the file name. | |
168 | ||
f8476e17 AK |
169 | @item M-x guix-package-from-file |
170 | Display package that the code within the specified file evaluates to. | |
171 | @xref{Invoking guix package, @code{--install-from-file}}, for an example | |
172 | of what such a file may look like. | |
173 | ||
457f60fa AK |
174 | @item M-x guix-search-by-regexp |
175 | Search for packages by a specified regexp. By default ``name'', | |
176 | ``synopsis'' and ``description'' of the packages will be searched. This | |
c80ce104 | 177 | can be changed by modifying @code{guix-package-search-params} variable. |
457f60fa | 178 | |
27a2e483 AK |
179 | @item M-x guix-search-by-name |
180 | Search for packages with names matching a specified regexp. This | |
181 | command is the same as @code{guix-search-by-regexp}, except only a | |
182 | package ``name'' is searched. | |
183 | ||
457f60fa AK |
184 | @end table |
185 | ||
23459fa5 AK |
186 | By default, these commands display each output on a separate line. If |
187 | you prefer to see a list of packages---i.e., a list with a package per | |
188 | line, use the following setting: | |
a54a237b AK |
189 | |
190 | @example | |
191 | (setq guix-package-list-type 'package) | |
192 | @end example | |
193 | ||
23459fa5 AK |
194 | Commands for displaying generations: |
195 | ||
196 | @table @kbd | |
197 | ||
198 | @item M-x guix-generations | |
199 | List all the generations. | |
200 | ||
201 | @item M-x guix-last-generations | |
202 | List the @var{N} last generations. You will be prompted for the number | |
203 | of generations. | |
204 | ||
205 | @item M-x guix-generations-by-time | |
206 | List generations matching time period. You will be prompted for the | |
207 | period using Org mode time prompt based on Emacs calendar (@pxref{The | |
773bab64 | 208 | date/time prompt,,, org, The Org Manual}). |
23459fa5 AK |
209 | |
210 | @end table | |
457f60fa | 211 | |
67cedc4b AK |
212 | Analogously on GuixSD you can also display system generations: |
213 | ||
214 | @table @kbd | |
215 | @item M-x guix-system-generations | |
216 | @item M-x guix-last-system-generations | |
217 | @item M-x guix-system-generations-by-time | |
218 | @end table | |
219 | ||
2d7bf949 AK |
220 | You can also invoke the @command{guix pull} command (@pxref{Invoking |
221 | guix pull}) from Emacs using: | |
222 | ||
223 | @table @kbd | |
224 | @item M-x guix-pull | |
225 | With @kbd{C-u}, make it verbose. | |
226 | @end table | |
227 | ||
228 | Once @command{guix pull} has succeeded, the Guix REPL is restared. This | |
229 | allows you to keep using the Emacs interface with the updated Guix. | |
230 | ||
7c1b1ae2 | 231 | |
bd53d327 | 232 | @node Emacs General info |
c554de89 | 233 | @subsection General information |
457f60fa AK |
234 | |
235 | The following keys are available for both ``list'' and ``info'' types of | |
236 | buffers: | |
237 | ||
238 | @table @kbd | |
239 | @item l | |
240 | @itemx r | |
241 | Go backward/forward by the history of the displayed results (this | |
242 | history is similar to the history of the Emacs @code{help-mode} or | |
243 | @code{Info-mode}). | |
244 | ||
245 | @item g | |
246 | Revert current buffer: update information about the displayed | |
247 | packages/generations and redisplay it. | |
248 | ||
249 | @item R | |
250 | Redisplay current buffer (without updating information). | |
251 | ||
5a727cdf AK |
252 | @item M |
253 | Apply manifest to the current profile or to a specified profile, if | |
254 | prefix argument is used. This has the same meaning as @code{--manifest} | |
255 | option (@pxref{Invoking guix package}). | |
256 | ||
457f60fa | 257 | @item C-c C-z |
96856613 LC |
258 | @cindex REPL |
259 | @cindex read-eval-print loop | |
457f60fa AK |
260 | Go to the Guix REPL (@pxref{The REPL,,, geiser, Geiser User Manual}). |
261 | ||
262 | @item h | |
263 | @itemx ? | |
264 | Describe current mode to see all available bindings. | |
265 | ||
266 | @end table | |
267 | ||
268 | @emph{Hint:} If you need several ``list'' or ``info'' buffers, you can | |
269 | simlpy @kbd{M-x clone-buffer} them, and each buffer will have its own | |
270 | history. | |
271 | ||
272 | @emph{Warning:} Name/version pairs cannot be used to identify packages | |
273 | (because a name is not necessarily unique), so ``guix.el'' uses special | |
274 | identifiers that live only during a guile session, so if the Guix REPL | |
275 | was restarted, you may want to revert ``list'' buffer (by pressing | |
276 | @kbd{g}). | |
277 | ||
bd53d327 | 278 | @node Emacs List buffer |
c554de89 | 279 | @subsection ``List'' buffer |
457f60fa AK |
280 | |
281 | An interface of a ``list'' buffer is similar to the interface provided | |
773bab64 | 282 | by ``package.el'' (@pxref{Package Menu,,, emacs, The GNU Emacs Manual}). |
457f60fa AK |
283 | |
284 | Default key bindings available for both ``package-list'' and | |
285 | ``generation-list'' buffers: | |
286 | ||
287 | @table @kbd | |
288 | @item m | |
578b98da | 289 | Mark the current entry (with prefix, mark all entries). |
457f60fa | 290 | @item u |
91cc37a1 | 291 | Unmark the current entry (with prefix, unmark all entries). |
457f60fa AK |
292 | @item @key{DEL} |
293 | Unmark backward. | |
457f60fa AK |
294 | @item S |
295 | Sort entries by a specified column. | |
296 | @end table | |
297 | ||
298 | A ``package-list'' buffer additionally provides the following bindings: | |
299 | ||
300 | @table @kbd | |
301 | @item @key{RET} | |
302 | Describe marked packages (display available information in a | |
303 | ``package-info'' buffer). | |
304 | @item i | |
a54a237b | 305 | Mark the current package for installation. |
457f60fa | 306 | @item d |
a54a237b | 307 | Mark the current package for deletion. |
91cc37a1 | 308 | @item U |
a54a237b | 309 | Mark the current package for upgrading. |
457f60fa | 310 | @item ^ |
91cc37a1 | 311 | Mark all obsolete packages for upgrading. |
6248e326 AK |
312 | @item e |
313 | Edit the definition of the curent package (go to its location). This is | |
314 | similar to @command{guix edit} command (@pxref{Invoking guix edit}), but | |
315 | for opening a package recipe in the current Emacs instance. | |
457f60fa | 316 | @item x |
a54a237b | 317 | Execute actions on the marked packages. |
5c8994d9 AK |
318 | @item B |
319 | Display latest builds of the current package (@pxref{Emacs Hydra}). | |
457f60fa AK |
320 | @end table |
321 | ||
322 | A ``generation-list'' buffer additionally provides the following | |
323 | bindings: | |
324 | ||
325 | @table @kbd | |
326 | @item @key{RET} | |
327 | List packages installed in the current generation. | |
328 | @item i | |
329 | Describe marked generations (display available information in a | |
330 | ``generation-info'' buffer). | |
af874238 AK |
331 | @item s |
332 | Switch profile to the current generation. | |
cb6a5c71 AK |
333 | @item d |
334 | Mark the current generation for deletion (with prefix, mark all | |
335 | generations). | |
336 | @item x | |
337 | Execute actions on the marked generations---i.e., delete generations. | |
d38bd08c AK |
338 | @item e |
339 | Run Ediff (@pxref{Top,,, ediff, The Ediff Manual}) on package outputs | |
340 | installed in the 2 marked generations. With prefix argument, run Ediff | |
341 | on manifests of the marked generations. | |
342 | @item D | |
343 | @itemx = | |
344 | Run Diff (@pxref{Diff Mode,,, emacs, The GNU Emacs Manual}) on package | |
345 | outputs installed in the 2 marked generations. With prefix argument, | |
346 | run Diff on manifests of the marked generations. | |
347 | @item + | |
348 | List package outputs added to the latest marked generation comparing | |
349 | with another marked generation. | |
350 | @item - | |
351 | List package outputs removed from the latest marked generation comparing | |
352 | with another marked generation. | |
457f60fa AK |
353 | @end table |
354 | ||
bd53d327 | 355 | @node Emacs Info buffer |
c554de89 | 356 | @subsection ``Info'' buffer |
457f60fa AK |
357 | |
358 | The interface of an ``info'' buffer is similar to the interface of | |
773bab64 | 359 | @code{help-mode} (@pxref{Help Mode,,, emacs, The GNU Emacs Manual}). |
457f60fa AK |
360 | |
361 | ``Info'' buffer contains some buttons (as usual you may use @key{TAB} / | |
362 | @kbd{S-@key{TAB}} to move between buttons---@pxref{Mouse References,,, | |
773bab64 | 363 | emacs, The GNU Emacs Manual}) which can be used to: |
457f60fa AK |
364 | |
365 | @itemize @bullet | |
366 | @item (in a ``package-info'' buffer) | |
367 | ||
368 | @itemize @minus | |
369 | @item install/remove a package; | |
370 | @item jump to a package location; | |
371 | @item browse home page of a package; | |
cefb7aea | 372 | @item browse license URL; |
457f60fa AK |
373 | @item describe packages from ``Inputs'' fields. |
374 | @end itemize | |
375 | ||
376 | @item (in a ``generation-info'' buffer) | |
377 | ||
378 | @itemize @minus | |
379 | @item remove a generation; | |
af874238 | 380 | @item switch to a generation; |
457f60fa AK |
381 | @item list packages installed in a generation; |
382 | @item jump to a generation directory. | |
383 | @end itemize | |
384 | ||
385 | @end itemize | |
386 | ||
56149217 AK |
387 | It is also possible to copy a button label (a link to an URL or a file) |
388 | by pressing @kbd{c} on a button. | |
389 | ||
457f60fa | 390 | |
bd53d327 | 391 | @node Emacs Configuration |
457f60fa AK |
392 | @subsection Configuration |
393 | ||
394 | There are many variables you can modify to change the appearance or | |
395 | behavior of Emacs user interface. Some of these variables are described | |
396 | in this section. Also you can use Custom Interface (@pxref{Easy | |
773bab64 AK |
397 | Customization,,, emacs, The GNU Emacs Manual}) to explore/set variables |
398 | (not all) and faces. | |
457f60fa AK |
399 | |
400 | @menu | |
bd53d327 AK |
401 | * Guile and Build Options: Emacs Build Options. Specifying how packages are built. |
402 | * Buffer Names: Emacs Buffer Names. Names of Guix buffers. | |
403 | * Keymaps: Emacs Keymaps. Configuring key bindings. | |
404 | * Appearance: Emacs Appearance. Settings for visual appearance. | |
457f60fa AK |
405 | @end menu |
406 | ||
bd53d327 | 407 | @node Emacs Build Options |
457f60fa AK |
408 | @subsubsection Guile and Build Options |
409 | ||
410 | @table @code | |
411 | @item guix-guile-program | |
412 | If you have some special needs for starting a Guile process, you may set | |
413 | this variable, for example: | |
414 | ||
415 | @example | |
416 | (setq guix-guile-program '("/bin/guile" "--no-auto-compile")) | |
417 | @end example | |
418 | ||
419 | @item guix-use-substitutes | |
420 | Has the same meaning as @code{--no-substitutes} option (@pxref{Invoking | |
421 | guix build}). | |
422 | ||
423 | @item guix-dry-run | |
424 | Has the same meaning as @code{--dry-run} option (@pxref{Invoking guix | |
425 | build}). | |
426 | ||
427 | @end table | |
428 | ||
bd53d327 | 429 | @node Emacs Buffer Names |
a54a237b AK |
430 | @subsubsection Buffer Names |
431 | ||
432 | Default names of ``guix.el'' buffers (``*Guix@tie{}@dots{}*'') may be | |
433 | changed with the following variables: | |
434 | ||
435 | @table @code | |
436 | @item guix-package-list-buffer-name | |
437 | @item guix-output-list-buffer-name | |
438 | @item guix-generation-list-buffer-name | |
439 | @item guix-package-info-buffer-name | |
440 | @item guix-output-info-buffer-name | |
441 | @item guix-generation-info-buffer-name | |
442 | @item guix-repl-buffer-name | |
443 | @item guix-internal-repl-buffer-name | |
a54a237b AK |
444 | @end table |
445 | ||
23459fa5 AK |
446 | By default, the name of a profile is also displayed in a ``list'' or |
447 | ``info'' buffer name. To change this behavior, use | |
8bff0c79 | 448 | @code{guix-ui-buffer-name-function} variable. |
23459fa5 AK |
449 | |
450 | For example, if you want to display all types of results in a single | |
a54a237b AK |
451 | buffer (in such case you will probably use a history (@kbd{l}/@kbd{r}) |
452 | extensively), you may do it like this: | |
453 | ||
454 | @example | |
455 | (let ((name "Guix Universal")) | |
456 | (setq | |
457 | guix-package-list-buffer-name name | |
458 | guix-output-list-buffer-name name | |
459 | guix-generation-list-buffer-name name | |
460 | guix-package-info-buffer-name name | |
461 | guix-output-info-buffer-name name | |
8bff0c79 | 462 | guix-generation-info-buffer-name name)) |
a54a237b AK |
463 | @end example |
464 | ||
bd53d327 | 465 | @node Emacs Keymaps |
457f60fa AK |
466 | @subsubsection Keymaps |
467 | ||
468 | If you want to change default key bindings, use the following keymaps | |
773bab64 | 469 | (@pxref{Init Rebinding,,, emacs, The GNU Emacs Manual}): |
457f60fa AK |
470 | |
471 | @table @code | |
e40b3c33 AK |
472 | @item guix-buffer-map |
473 | Parent keymap with general keys for any buffer type. | |
474 | ||
475 | @item guix-ui-map | |
476 | Parent keymap with general keys for buffers used for Guix package | |
477 | management (for packages, outputs and generations). | |
74cc6737 | 478 | |
457f60fa AK |
479 | @item guix-list-mode-map |
480 | Parent keymap with general keys for ``list'' buffers. | |
481 | ||
482 | @item guix-package-list-mode-map | |
483 | Keymap with specific keys for ``package-list'' buffers. | |
484 | ||
a54a237b AK |
485 | @item guix-output-list-mode-map |
486 | Keymap with specific keys for ``output-list'' buffers. | |
487 | ||
457f60fa AK |
488 | @item guix-generation-list-mode-map |
489 | Keymap with specific keys for ``generation-list'' buffers. | |
490 | ||
491 | @item guix-info-mode-map | |
492 | Parent keymap with general keys for ``info'' buffers. | |
493 | ||
494 | @item guix-package-info-mode-map | |
495 | Keymap with specific keys for ``package-info'' buffers. | |
496 | ||
a54a237b AK |
497 | @item guix-output-info-mode-map |
498 | Keymap with specific keys for ``output-info'' buffers. | |
499 | ||
457f60fa AK |
500 | @item guix-generation-info-mode-map |
501 | Keymap with specific keys for ``generation-info'' buffers. | |
502 | ||
56149217 AK |
503 | @item guix-info-button-map |
504 | Keymap with keys available when a point is placed on a button. | |
505 | ||
457f60fa AK |
506 | @end table |
507 | ||
bd53d327 | 508 | @node Emacs Appearance |
457f60fa AK |
509 | @subsubsection Appearance |
510 | ||
511 | You can change almost any aspect of ``list'' / ``info'' buffers using | |
cf910cef AK |
512 | the following variables (@dfn{ENTRY-TYPE} means @code{package}, |
513 | @code{output} or @code{generation}): | |
457f60fa AK |
514 | |
515 | @table @code | |
cf910cef | 516 | @item guix-ENTRY-TYPE-list-format |
574f6727 | 517 | @itemx guix-ENTRY-TYPE-list-titles |
457f60fa AK |
518 | Specify the columns, their names, what and how is displayed in ``list'' |
519 | buffers. | |
520 | ||
9193fb7c | 521 | @item guix-ENTRY-TYPE-info-format |
574f6727 | 522 | @itemx guix-ENTRY-TYPE-info-titles |
2c7ed388 | 523 | @itemx guix-info-ignore-empty-values |
457f60fa AK |
524 | @itemx guix-info-param-title-format |
525 | @itemx guix-info-multiline-prefix | |
526 | @itemx guix-info-indent | |
2c7ed388 | 527 | @itemx guix-info-fill |
457f60fa AK |
528 | @itemx guix-info-delimiter |
529 | Various settings for ``info'' buffers. | |
530 | ||
531 | @end table | |
9a130e19 AK |
532 | |
533 | ||
687c9bc0 AK |
534 | @node Emacs Licenses |
535 | @section Licenses | |
536 | ||
537 | If you want to browse the URL of a particular license, or to look at a | |
538 | list of licenses, you may use the following commands: | |
539 | ||
540 | @table @kbd | |
541 | ||
542 | @item M-x guix-browse-license-url | |
543 | Choose a license from a completion list to browse its URL using | |
544 | @code{browse-url} function (@pxref{Browse-URL,,, emacs, The GNU Emacs | |
545 | Manual}). | |
546 | ||
547 | @item M-x guix-licenses | |
548 | Display a list of available licenses. You can press @kbd{@key{RET}} | |
549 | there to display packages with this license in the same way as @kbd{M-x | |
550 | guix-packages-by-license} would do (@pxref{Emacs Commands}). | |
551 | ||
8472b2fd AK |
552 | @item M-x guix-find-license-definition |
553 | Open @file{@dots{}/guix/licenses.scm} and move to the specified license. | |
554 | ||
687c9bc0 AK |
555 | @end table |
556 | ||
557 | ||
b5e3cbbb AK |
558 | @node Emacs Package Locations |
559 | @section Package Source Locations | |
560 | ||
561 | As you know, package definitions are placed in Guile files, also known | |
562 | as @dfn{package locations}. The following commands should help you not | |
563 | get lost in these locations: | |
564 | ||
565 | @table @kbd | |
566 | ||
b4b9975d AK |
567 | @item M-x guix-locations |
568 | Display a list of package locations. You can press @key{RET} there to | |
569 | display packages placed in the current location in the same way as | |
570 | @kbd{M-x guix-packages-by-location} would do (@pxref{Emacs Commands}). | |
571 | Note that when the point is on a location button, @key{RET} will open | |
572 | this location file. | |
573 | ||
b5e3cbbb AK |
574 | @item M-x guix-find-location |
575 | Open the given package definition source file (press @key{TAB} to choose | |
576 | a location from a completion list). | |
577 | ||
578 | @item M-x guix-edit | |
579 | Find location of a specified package. This is an Emacs analog of | |
580 | @command{guix edit} command (@pxref{Invoking guix edit}). As with | |
581 | @kbd{M-x guix-packages-by-name}, you can press @key{TAB} to complete a | |
582 | package name. | |
583 | ||
584 | @end table | |
585 | ||
586 | If you are contributing to Guix, you may find it useful for @kbd{M-x | |
587 | guix-find-location} and @kbd{M-x guix-edit} to open locations from your | |
588 | Git checkout. This can be done by setting @code{guix-directory} | |
589 | variable. For example, after this: | |
590 | ||
591 | @example | |
592 | (setq guix-directory "~/src/guix") | |
593 | @end example | |
594 | ||
595 | @kbd{M-x guix-edit guix} opens | |
596 | @file{~/src/guix/gnu/packages/package-management.scm} file. | |
597 | ||
598 | Also you can use @kbd{C-u} prefix argument to specify a directory just | |
599 | for the current @kbd{M-x guix-find-location} or @kbd{M-x guix-edit} | |
600 | command. | |
601 | ||
602 | ||
9b0afb0d AK |
603 | @node Emacs Popup Interface |
604 | @section Popup Interface | |
605 | ||
606 | If you ever used Magit, you know what ``popup interface'' is | |
607 | (@pxref{Top,,, magit-popup, Magit-Popup User Manual}). Even if you are | |
608 | not acquainted with Magit, there should be no worries as it is very | |
609 | intuitive. | |
610 | ||
611 | So @kbd{M-x@tie{}guix} command provides a top-level popup interface for | |
612 | all available guix commands. When you select an option, you'll be | |
613 | prompted for a value in the minibuffer. Many values have completions, | |
614 | so don't hesitate to press @key{TAB} key. Multiple values (for example, | |
615 | packages or lint checkers) should be separated by commas. | |
616 | ||
617 | After specifying all options and switches for a command, you may choose | |
618 | one of the available actions. The following default actions are | |
619 | available for all commands: | |
620 | ||
621 | @itemize | |
622 | ||
623 | @item | |
624 | Run the command in the Guix REPL. It is faster than running | |
625 | @code{guix@tie{}@dots{}} command directly in shell, as there is no | |
626 | need to run another guile process and to load required modules there. | |
627 | ||
628 | @item | |
629 | Run the command in a shell buffer. You can set | |
630 | @code{guix-run-in-shell-function} variable to fine tune the shell buffer | |
631 | you want to use. | |
632 | ||
633 | @item | |
634 | Add the command line to the kill ring (@pxref{Kill Ring,,, emacs, The | |
635 | GNU Emacs Manual}). | |
636 | ||
637 | @end itemize | |
638 | ||
710fa231 | 639 | Several commands (@command{guix graph}, @command{guix system shepherd-graph} |
5e2b761e AK |
640 | and @command{guix system extension-graph}) also have a ``View graph'' |
641 | action, which allows you to view a generated graph using @command{dot} | |
642 | command (specified by @code{guix-dot-program} variable). By default a | |
643 | PNG file will be saved in @file{/tmp} directory and will be opened | |
644 | directly in Emacs. This behavior may be changed with the following | |
645 | variables: | |
646 | ||
647 | @table @code | |
648 | ||
649 | @item guix-find-file-function | |
650 | Function used to open a generated graph. If you want to open a graph in | |
651 | an external program, you can do it by modifying this variable---for | |
652 | example, you can use a functionality provided by the Org Mode | |
653 | (@pxref{Top,,, org, The Org Manual}): | |
654 | ||
655 | @example | |
656 | (setq guix-find-file-function 'org-open-file) | |
657 | (add-to-list 'org-file-apps '("\\.png\\'" . "sxiv %s")) | |
658 | @end example | |
659 | ||
660 | @item guix-dot-default-arguments | |
661 | Command line arguments to run @command{dot} command. If you change an | |
662 | output format (for example, into @code{-Tpdf}), you also need to change | |
663 | the next variable. | |
664 | ||
665 | @item guix-dot-file-name-function | |
666 | Function used to define a name of the generated graph file. Default | |
667 | name is @file{/tmp/guix-emacs-graph-XXXXXX.png}. | |
668 | ||
669 | @end table | |
670 | ||
671 | So, for example, if you want to generate and open a PDF file in your | |
672 | Emacs, you may change the settings like this: | |
673 | ||
674 | @example | |
675 | (defun my-guix-pdf-graph () | |
676 | "/tmp/my-current-guix-graph.pdf") | |
677 | ||
678 | (setq guix-dot-default-arguments '("-Tpdf") | |
679 | guix-dot-file-name-function 'my-guix-pdf-graph) | |
680 | @end example | |
681 | ||
9b0afb0d | 682 | |
9a130e19 | 683 | @node Emacs Prettify |
c554de89 | 684 | @section Guix Prettify Mode |
9a130e19 | 685 | |
c554de89 AK |
686 | GNU@tie{}Guix also comes with ``guix-prettify.el''. It provides a minor |
687 | mode for abbreviating store file names by replacing hash sequences of | |
688 | symbols with ``@dots{}'': | |
9a130e19 AK |
689 | |
690 | @example | |
691 | /gnu/store/72f54nfp6g1hz873w8z3gfcah0h4nl9p-foo-0.1 | |
692 | @result{} /gnu/store/…-foo-0.1 | |
693 | @end example | |
694 | ||
695 | Once you set up ``guix.el'' (@pxref{Emacs Initial Setup}), the following | |
696 | commands become available: | |
697 | ||
698 | @table @kbd | |
699 | ||
700 | @item M-x guix-prettify-mode | |
701 | Enable/disable prettifying for the current buffer. | |
702 | ||
703 | @item M-x global-guix-prettify-mode | |
704 | Enable/disable prettifying globally. | |
705 | ||
706 | @end table | |
707 | ||
708 | To automatically enable @code{guix-prettify-mode} globally on Emacs | |
709 | start, add the following line to your init file: | |
710 | ||
711 | @example | |
712 | (global-guix-prettify-mode) | |
713 | @end example | |
714 | ||
715 | If you want to enable it only for specific major modes, add it to the | |
716 | mode hooks (@pxref{Hooks,,, emacs, The GNU Emacs Manual}), for example: | |
717 | ||
718 | @example | |
719 | (add-hook 'shell-mode-hook 'guix-prettify-mode) | |
720 | (add-hook 'dired-mode-hook 'guix-prettify-mode) | |
721 | @end example | |
00a8dae2 AK |
722 | |
723 | ||
34850cd5 AK |
724 | @node Emacs Build Log |
725 | @section Build Log Mode | |
726 | ||
727 | GNU@tie{}Guix provides major and minor modes for highlighting build | |
728 | logs. So when you have a file with a package build output---for | |
729 | example, a file returned by @command{guix build --log-file @dots{}} | |
730 | command (@pxref{Invoking guix build}), you may call @kbd{M-x | |
731 | guix-build-log-mode} command in the buffer with this file. This major | |
732 | mode highlights some lines specific to build output and provides the | |
733 | following key bindings: | |
734 | ||
735 | @table @kbd | |
736 | ||
737 | @item M-n | |
738 | Move to the next build phase. | |
739 | ||
740 | @item M-p | |
741 | Move to the previous build phase. | |
742 | ||
eda1cc8b AK |
743 | @item @key{TAB} |
744 | Toggle (show/hide) the body of the current build phase. | |
745 | ||
746 | @item S-@key{TAB} | |
747 | Toggle (show/hide) the bodies of all build phases. | |
748 | ||
34850cd5 AK |
749 | @end table |
750 | ||
751 | There is also @kbd{M-x guix-build-log-minor-mode} which also provides | |
f4044b58 AK |
752 | the same highlighting and the same key bindings as the major mode, but |
753 | prefixed with @kbd{C-c}. By default, this minor mode is enabled in | |
754 | shell buffers (@pxref{Interactive Shell,,, emacs, The GNU Emacs | |
755 | Manual}). If you don't like it, set | |
756 | @code{guix-build-log-minor-mode-activate} to nil. | |
34850cd5 AK |
757 | |
758 | ||
00a8dae2 | 759 | @node Emacs Completions |
c554de89 | 760 | @section Shell Completions |
00a8dae2 AK |
761 | |
762 | Another feature that becomes available after configuring Emacs interface | |
763 | (@pxref{Emacs Initial Setup}) is completing of @command{guix} | |
764 | subcommands, options, packages and other things in @code{shell} | |
765 | (@pxref{Interactive Shell,,, emacs, The GNU Emacs Manual}) and | |
766 | @code{eshell} (@pxref{Top,,, eshell, Eshell: The Emacs Shell}). | |
767 | ||
768 | It works the same way as other completions do. Just press @key{TAB} | |
769 | when your intuition tells you. | |
770 | ||
771 | And here are some examples, where pressing @key{TAB} may complete | |
772 | something: | |
773 | ||
774 | @itemize @w{} | |
775 | ||
776 | @item @code{guix pa}@key{TAB} | |
777 | @item @code{guix package -}@key{TAB} | |
778 | @item @code{guix package --}@key{TAB} | |
779 | @item @code{guix package -i gei}@key{TAB} | |
780 | @item @code{guix build -L/tm}@key{TAB} | |
781 | @item @code{guix build --sy}@key{TAB} | |
782 | @item @code{guix build --system=i}@key{TAB} | |
783 | @item @code{guix system rec}@key{TAB} | |
784 | @item @code{guix lint --checkers=sy}@key{TAB} | |
785 | @item @code{guix lint --checkers=synopsis,des}@key{TAB} | |
786 | ||
787 | @end itemize | |
187f80c6 AK |
788 | |
789 | ||
790 | @node Emacs Development | |
791 | @section Development | |
792 | ||
793 | By default, when you open a Scheme file, @code{guix-devel-mode} will be | |
794 | activated (if you don't want it, set @code{guix-devel-activate-mode} to | |
795 | nil). This minor mode provides the following key bindings: | |
796 | ||
797 | @table @kbd | |
798 | ||
799 | @item C-c . k | |
800 | Copy the name of the current Guile module into kill ring | |
801 | (@code{guix-devel-copy-module-as-kill}). | |
802 | ||
803 | @item C-c . u | |
804 | Use the current Guile module. Often after opening a Scheme file, you | |
805 | want to use a module it defines, so you switch to the Geiser REPL and | |
806 | write @code{,use (some module)} there. You may just use this command | |
807 | instead (@code{guix-devel-use-module}). | |
808 | ||
1a6c4c2f AK |
809 | @item C-c . b |
810 | Build a package defined by the current variable definition. The | |
811 | building process is run in the current Geiser REPL. If you modified the | |
812 | current package definition, don't forget to reevaluate it before calling | |
813 | this command---for example, with @kbd{C-M-x} (@pxref{To eval or not to | |
814 | eval,,, geiser, Geiser User Manual}) | |
815 | (@code{guix-devel-build-package-definition}). | |
816 | ||
ad8b83bd AK |
817 | @item C-c . s |
818 | Build a source derivation of the package defined by the current variable | |
819 | definition. This command has the same meaning as @code{guix build -S} | |
820 | shell command (@pxref{Invoking guix build}) | |
821 | (@code{guix-devel-build-package-source}). | |
822 | ||
b94ef11a AK |
823 | @item C-c . l |
824 | Lint (check) a package defined by the current variable definition | |
825 | (@pxref{Invoking guix lint}) (@code{guix-devel-lint-package}). | |
826 | ||
187f80c6 | 827 | @end table |
1a6c4c2f AK |
828 | |
829 | Unluckily, there is a limitation related to long-running REPL commands. | |
830 | When there is a running process in a Geiser REPL, you are not supposed | |
831 | to evaluate anything in a scheme buffer, because this will ``freeze'' | |
832 | the REPL: it will stop producing any output (however, the evaluating | |
833 | process will continue---you will just not see any progress anymore). Be | |
834 | aware: even moving the point in a scheme buffer may ``break'' the REPL | |
835 | if Autodoc (@pxref{Autodoc and friends,,, geiser, Geiser User Manual}) | |
836 | is enabled (which is the default). | |
837 | ||
838 | So you have to postpone editing your scheme buffers until the running | |
839 | evaluation will be finished in the REPL. | |
840 | ||
841 | Alternatively, to avoid this limitation, you may just run another Geiser | |
842 | REPL, and while something is being evaluated in the previous REPL, you | |
843 | can continue editing a scheme file with the help of the current one. | |
32950fc8 AK |
844 | |
845 | ||
846 | @node Emacs Hydra | |
847 | @section Hydra | |
848 | ||
849 | The continuous integration server at @code{hydra.gnu.org} builds all | |
850 | the distribution packages on the supported architectures and serves | |
851 | them as substitutes (@pxref{Substitutes}). Continuous integration is | |
852 | currently orchestrated by @uref{https://nixos.org/hydra/, Hydra}. | |
853 | ||
854 | This section describes an Emacs interface to query Hydra to know the | |
855 | build status of specific packages, discover recent and ongoing builds, | |
856 | view build logs, and so on. This interface is mostly the same as the | |
857 | ``list''/``info'' interface for displaying packages and generations | |
858 | (@pxref{Emacs Package Management}). | |
859 | ||
860 | The following commands are available: | |
861 | ||
862 | @table @kbd | |
863 | ||
864 | @item M-x guix-hydra-latest-builds | |
865 | Display latest failed or successful builds (you will be prompted for a | |
866 | number of builds). With @kbd{C-u}, you will also be prompted for other | |
867 | parameters (project, jobset, job and system). | |
868 | ||
869 | @item M-x guix-hydra-queued-builds | |
870 | Display scheduled or currently running builds (you will be prompted for | |
871 | a number of builds). | |
872 | ||
873 | @item M-x guix-hydra-jobsets | |
874 | Display available jobsets (you will be prompted for a project). | |
875 | ||
876 | @end table | |
877 | ||
878 | In a list of builds you can press @kbd{L} key to display a build log of | |
879 | the current build. Also both a list of builds and a list of jobsets | |
880 | provide @kbd{B} key to display latest builds of the current job or | |
881 | jobset (don't forget about @kbd{C-u}). |