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. | |
457f60fa AK |
21 | @end menu |
22 | ||
bd53d327 | 23 | @node Emacs Initial Setup |
457f60fa AK |
24 | @subsection Initial Setup |
25 | ||
26 | To be able to use ``guix.el'', you need to install the following | |
27 | packages: | |
28 | ||
29 | @itemize | |
30 | @item | |
31 | @uref{http://www.gnu.org/software/emacs/, GNU Emacs}, version 24.3 or | |
32 | later; | |
33 | ||
34 | @item | |
35 | @uref{http://nongnu.org/geiser/, Geiser}, version 0.3 or later: it is | |
36 | used for interacting with the Guile process. | |
37 | ||
38 | @end itemize | |
39 | ||
40 | When it is done, add the following into your init file (@pxref{Init | |
41 | File,,, emacs, The Emacs Editor}): | |
42 | ||
43 | @example | |
44 | (require 'guix-init nil t) | |
45 | @end example | |
46 | ||
47 | However there is a chance that @code{load-path} of your Emacs does not | |
48 | contain a directory with ``guix.el'' (usually it is | |
49 | @file{/usr/share/emacs/site-lisp/}). In that case you need to add it | |
50 | before requiring (@pxref{Lisp Libraries,,, emacs, The Emacs Editor}): | |
51 | ||
52 | @example | |
53 | (add-to-list 'load-path "/path/to/directory-with-guix.el") | |
54 | (require 'guix-init) | |
55 | @end example | |
56 | ||
57 | Do not worry about the efficiency of that @code{require} thing. It will | |
58 | not load the whole ``guix.el'' package, it will just autoload the main | |
59 | interactive commands (@pxref{Autoload,,, elisp, Emacs Lisp}). | |
60 | ||
61 | ||
bd53d327 | 62 | @node Emacs Usage |
457f60fa AK |
63 | @subsection Usage |
64 | ||
65 | Once ``guix.el'' has been successfully configured, you should be able to | |
66 | use commands for displaying packages and generations. This information | |
67 | can be displayed in a ``list'' or ``info'' buffer. | |
68 | ||
69 | @menu | |
bd53d327 AK |
70 | * Commands: Emacs Commands. @kbd{M-x guix-@dots{}} |
71 | * General information: Emacs General info. Common for both interfaces. | |
72 | * ``List'' buffer: Emacs List buffer. List-like interface. | |
73 | * ``Info'' buffer: Emacs Info buffer. Help-like interface. | |
457f60fa AK |
74 | @end menu |
75 | ||
bd53d327 | 76 | @node Emacs Commands |
457f60fa AK |
77 | @subsubsection Commands |
78 | ||
23459fa5 AK |
79 | All commands for displaying packages and generations use the current |
80 | profile, which can be changed with | |
81 | @kbd{M-x@tie{}guix-set-current-profile}. Alternatively, if you call any | |
82 | of these commands with prefix argument (@kbd{C-u}), you will be prompted | |
83 | for a profile just for that command. | |
84 | ||
85 | Commands for displaying packages: | |
457f60fa AK |
86 | |
87 | @table @kbd | |
23459fa5 | 88 | |
457f60fa AK |
89 | @item M-x guix-all-available-packages |
90 | @itemx M-x guix-newest-available-packages | |
91 | Display all/newest available packages. | |
92 | ||
93 | @item M-x guix-installed-packages | |
23459fa5 | 94 | Display all installed packages. |
457f60fa AK |
95 | |
96 | @item M-x guix-obsolete-packages | |
23459fa5 AK |
97 | Display obsolete packages (the packages that are installed in a profile |
98 | but cannot be found among available packages). | |
457f60fa AK |
99 | |
100 | @item M-x guix-search-by-name | |
101 | Display package(s) with the specified name. | |
102 | ||
103 | @item M-x guix-search-by-regexp | |
104 | Search for packages by a specified regexp. By default ``name'', | |
105 | ``synopsis'' and ``description'' of the packages will be searched. This | |
106 | can be changed by modifying @code{guix-search-params} variable. | |
107 | ||
457f60fa AK |
108 | @end table |
109 | ||
23459fa5 AK |
110 | By default, these commands display each output on a separate line. If |
111 | you prefer to see a list of packages---i.e., a list with a package per | |
112 | line, use the following setting: | |
a54a237b AK |
113 | |
114 | @example | |
115 | (setq guix-package-list-type 'package) | |
116 | @end example | |
117 | ||
23459fa5 AK |
118 | Commands for displaying generations: |
119 | ||
120 | @table @kbd | |
121 | ||
122 | @item M-x guix-generations | |
123 | List all the generations. | |
124 | ||
125 | @item M-x guix-last-generations | |
126 | List the @var{N} last generations. You will be prompted for the number | |
127 | of generations. | |
128 | ||
129 | @item M-x guix-generations-by-time | |
130 | List generations matching time period. You will be prompted for the | |
131 | period using Org mode time prompt based on Emacs calendar (@pxref{The | |
132 | date/time prompt,,, org, Org Mode Manual}). | |
133 | ||
134 | @end table | |
457f60fa | 135 | |
2d7bf949 AK |
136 | You can also invoke the @command{guix pull} command (@pxref{Invoking |
137 | guix pull}) from Emacs using: | |
138 | ||
139 | @table @kbd | |
140 | @item M-x guix-pull | |
141 | With @kbd{C-u}, make it verbose. | |
142 | @end table | |
143 | ||
144 | Once @command{guix pull} has succeeded, the Guix REPL is restared. This | |
145 | allows you to keep using the Emacs interface with the updated Guix. | |
146 | ||
bd53d327 | 147 | @node Emacs General info |
457f60fa AK |
148 | @subsubsection General information |
149 | ||
150 | The following keys are available for both ``list'' and ``info'' types of | |
151 | buffers: | |
152 | ||
153 | @table @kbd | |
154 | @item l | |
155 | @itemx r | |
156 | Go backward/forward by the history of the displayed results (this | |
157 | history is similar to the history of the Emacs @code{help-mode} or | |
158 | @code{Info-mode}). | |
159 | ||
160 | @item g | |
161 | Revert current buffer: update information about the displayed | |
162 | packages/generations and redisplay it. | |
163 | ||
164 | @item R | |
165 | Redisplay current buffer (without updating information). | |
166 | ||
167 | @item C-c C-z | |
168 | Go to the Guix REPL (@pxref{The REPL,,, geiser, Geiser User Manual}). | |
169 | ||
170 | @item h | |
171 | @itemx ? | |
172 | Describe current mode to see all available bindings. | |
173 | ||
174 | @end table | |
175 | ||
176 | @emph{Hint:} If you need several ``list'' or ``info'' buffers, you can | |
177 | simlpy @kbd{M-x clone-buffer} them, and each buffer will have its own | |
178 | history. | |
179 | ||
180 | @emph{Warning:} Name/version pairs cannot be used to identify packages | |
181 | (because a name is not necessarily unique), so ``guix.el'' uses special | |
182 | identifiers that live only during a guile session, so if the Guix REPL | |
183 | was restarted, you may want to revert ``list'' buffer (by pressing | |
184 | @kbd{g}). | |
185 | ||
bd53d327 | 186 | @node Emacs List buffer |
457f60fa AK |
187 | @subsubsection ``List'' buffer |
188 | ||
189 | An interface of a ``list'' buffer is similar to the interface provided | |
190 | by ``package.el'' (@pxref{Package Menu,,, emacs, The Emacs Editor}). | |
191 | ||
192 | Default key bindings available for both ``package-list'' and | |
193 | ``generation-list'' buffers: | |
194 | ||
195 | @table @kbd | |
196 | @item m | |
197 | Mark the current entry. | |
198 | @item M | |
199 | Mark all entries. | |
200 | @item u | |
91cc37a1 | 201 | Unmark the current entry (with prefix, unmark all entries). |
457f60fa AK |
202 | @item @key{DEL} |
203 | Unmark backward. | |
457f60fa AK |
204 | @item S |
205 | Sort entries by a specified column. | |
206 | @end table | |
207 | ||
208 | A ``package-list'' buffer additionally provides the following bindings: | |
209 | ||
210 | @table @kbd | |
211 | @item @key{RET} | |
212 | Describe marked packages (display available information in a | |
213 | ``package-info'' buffer). | |
214 | @item i | |
a54a237b | 215 | Mark the current package for installation. |
457f60fa | 216 | @item d |
a54a237b | 217 | Mark the current package for deletion. |
91cc37a1 | 218 | @item U |
a54a237b | 219 | Mark the current package for upgrading. |
457f60fa | 220 | @item ^ |
91cc37a1 | 221 | Mark all obsolete packages for upgrading. |
457f60fa | 222 | @item x |
a54a237b | 223 | Execute actions on the marked packages. |
457f60fa AK |
224 | @end table |
225 | ||
226 | A ``generation-list'' buffer additionally provides the following | |
227 | bindings: | |
228 | ||
229 | @table @kbd | |
230 | @item @key{RET} | |
231 | List packages installed in the current generation. | |
232 | @item i | |
233 | Describe marked generations (display available information in a | |
234 | ``generation-info'' buffer). | |
af874238 AK |
235 | @item s |
236 | Switch profile to the current generation. | |
cb6a5c71 AK |
237 | @item d |
238 | Mark the current generation for deletion (with prefix, mark all | |
239 | generations). | |
240 | @item x | |
241 | Execute actions on the marked generations---i.e., delete generations. | |
d38bd08c AK |
242 | @item e |
243 | Run Ediff (@pxref{Top,,, ediff, The Ediff Manual}) on package outputs | |
244 | installed in the 2 marked generations. With prefix argument, run Ediff | |
245 | on manifests of the marked generations. | |
246 | @item D | |
247 | @itemx = | |
248 | Run Diff (@pxref{Diff Mode,,, emacs, The GNU Emacs Manual}) on package | |
249 | outputs installed in the 2 marked generations. With prefix argument, | |
250 | run Diff on manifests of the marked generations. | |
251 | @item + | |
252 | List package outputs added to the latest marked generation comparing | |
253 | with another marked generation. | |
254 | @item - | |
255 | List package outputs removed from the latest marked generation comparing | |
256 | with another marked generation. | |
457f60fa AK |
257 | @end table |
258 | ||
bd53d327 | 259 | @node Emacs Info buffer |
457f60fa AK |
260 | @subsubsection ``Info'' buffer |
261 | ||
262 | The interface of an ``info'' buffer is similar to the interface of | |
263 | @code{help-mode} (@pxref{Help Mode,,, emacs, The Emacs Editor}). | |
264 | ||
265 | ``Info'' buffer contains some buttons (as usual you may use @key{TAB} / | |
266 | @kbd{S-@key{TAB}} to move between buttons---@pxref{Mouse References,,, | |
267 | emacs, The Emacs Editor}) which can be used to: | |
268 | ||
269 | @itemize @bullet | |
270 | @item (in a ``package-info'' buffer) | |
271 | ||
272 | @itemize @minus | |
273 | @item install/remove a package; | |
274 | @item jump to a package location; | |
275 | @item browse home page of a package; | |
276 | @item describe packages from ``Inputs'' fields. | |
277 | @end itemize | |
278 | ||
279 | @item (in a ``generation-info'' buffer) | |
280 | ||
281 | @itemize @minus | |
282 | @item remove a generation; | |
af874238 | 283 | @item switch to a generation; |
457f60fa AK |
284 | @item list packages installed in a generation; |
285 | @item jump to a generation directory. | |
286 | @end itemize | |
287 | ||
288 | @end itemize | |
289 | ||
290 | ||
bd53d327 | 291 | @node Emacs Configuration |
457f60fa AK |
292 | @subsection Configuration |
293 | ||
294 | There are many variables you can modify to change the appearance or | |
295 | behavior of Emacs user interface. Some of these variables are described | |
296 | in this section. Also you can use Custom Interface (@pxref{Easy | |
297 | Customization,,, emacs, The Emacs Editor}) to explore/set variables (not | |
298 | all) and faces. | |
299 | ||
300 | @menu | |
bd53d327 AK |
301 | * Guile and Build Options: Emacs Build Options. Specifying how packages are built. |
302 | * Buffer Names: Emacs Buffer Names. Names of Guix buffers. | |
303 | * Keymaps: Emacs Keymaps. Configuring key bindings. | |
304 | * Appearance: Emacs Appearance. Settings for visual appearance. | |
457f60fa AK |
305 | @end menu |
306 | ||
bd53d327 | 307 | @node Emacs Build Options |
457f60fa AK |
308 | @subsubsection Guile and Build Options |
309 | ||
310 | @table @code | |
311 | @item guix-guile-program | |
312 | If you have some special needs for starting a Guile process, you may set | |
313 | this variable, for example: | |
314 | ||
315 | @example | |
316 | (setq guix-guile-program '("/bin/guile" "--no-auto-compile")) | |
317 | @end example | |
318 | ||
319 | @item guix-use-substitutes | |
320 | Has the same meaning as @code{--no-substitutes} option (@pxref{Invoking | |
321 | guix build}). | |
322 | ||
323 | @item guix-dry-run | |
324 | Has the same meaning as @code{--dry-run} option (@pxref{Invoking guix | |
325 | build}). | |
326 | ||
327 | @end table | |
328 | ||
bd53d327 | 329 | @node Emacs Buffer Names |
a54a237b AK |
330 | @subsubsection Buffer Names |
331 | ||
332 | Default names of ``guix.el'' buffers (``*Guix@tie{}@dots{}*'') may be | |
333 | changed with the following variables: | |
334 | ||
335 | @table @code | |
336 | @item guix-package-list-buffer-name | |
337 | @item guix-output-list-buffer-name | |
338 | @item guix-generation-list-buffer-name | |
339 | @item guix-package-info-buffer-name | |
340 | @item guix-output-info-buffer-name | |
341 | @item guix-generation-info-buffer-name | |
342 | @item guix-repl-buffer-name | |
343 | @item guix-internal-repl-buffer-name | |
a54a237b AK |
344 | @end table |
345 | ||
23459fa5 AK |
346 | By default, the name of a profile is also displayed in a ``list'' or |
347 | ``info'' buffer name. To change this behavior, use | |
348 | @code{guix-buffer-name-function} variable. | |
349 | ||
350 | For example, if you want to display all types of results in a single | |
a54a237b AK |
351 | buffer (in such case you will probably use a history (@kbd{l}/@kbd{r}) |
352 | extensively), you may do it like this: | |
353 | ||
354 | @example | |
355 | (let ((name "Guix Universal")) | |
356 | (setq | |
357 | guix-package-list-buffer-name name | |
358 | guix-output-list-buffer-name name | |
359 | guix-generation-list-buffer-name name | |
360 | guix-package-info-buffer-name name | |
361 | guix-output-info-buffer-name name | |
23459fa5 AK |
362 | guix-generation-info-buffer-name name |
363 | guix-buffer-name-function #'guix-buffer-name-simple)) | |
a54a237b AK |
364 | @end example |
365 | ||
bd53d327 | 366 | @node Emacs Keymaps |
457f60fa AK |
367 | @subsubsection Keymaps |
368 | ||
369 | If you want to change default key bindings, use the following keymaps | |
370 | (@pxref{Init Rebinding,,, emacs, The Emacs Editor}): | |
371 | ||
372 | @table @code | |
373 | @item guix-list-mode-map | |
374 | Parent keymap with general keys for ``list'' buffers. | |
375 | ||
376 | @item guix-package-list-mode-map | |
377 | Keymap with specific keys for ``package-list'' buffers. | |
378 | ||
a54a237b AK |
379 | @item guix-output-list-mode-map |
380 | Keymap with specific keys for ``output-list'' buffers. | |
381 | ||
457f60fa AK |
382 | @item guix-generation-list-mode-map |
383 | Keymap with specific keys for ``generation-list'' buffers. | |
384 | ||
385 | @item guix-info-mode-map | |
386 | Parent keymap with general keys for ``info'' buffers. | |
387 | ||
388 | @item guix-package-info-mode-map | |
389 | Keymap with specific keys for ``package-info'' buffers. | |
390 | ||
a54a237b AK |
391 | @item guix-output-info-mode-map |
392 | Keymap with specific keys for ``output-info'' buffers. | |
393 | ||
457f60fa AK |
394 | @item guix-generation-info-mode-map |
395 | Keymap with specific keys for ``generation-info'' buffers. | |
396 | ||
397 | @end table | |
398 | ||
bd53d327 | 399 | @node Emacs Appearance |
457f60fa AK |
400 | @subsubsection Appearance |
401 | ||
402 | You can change almost any aspect of ``list'' / ``info'' buffers using | |
403 | the following variables: | |
404 | ||
405 | @table @code | |
406 | @item guix-list-column-format | |
407 | @itemx guix-list-column-titles | |
408 | @itemx guix-list-column-value-methods | |
409 | Specify the columns, their names, what and how is displayed in ``list'' | |
410 | buffers. | |
411 | ||
412 | @item guix-info-displayed-params | |
413 | @itemx guix-info-insert-methods | |
414 | @itemx guix-info-ignore-empty-vals | |
415 | @itemx guix-info-param-title-format | |
416 | @itemx guix-info-multiline-prefix | |
417 | @itemx guix-info-indent | |
418 | @itemx guix-info-fill-column | |
419 | @itemx guix-info-delimiter | |
420 | Various settings for ``info'' buffers. | |
421 | ||
422 | @end table |