Commit | Line | Data |
---|---|---|
457f60fa AK |
1 | @node Emacs Interface |
2 | @section Emacs Interface | |
3 | ||
4 | @cindex emacs | |
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 | |
18 | * Initial Setup: emacs Initial Setup. Preparing @file{~/.emacs}. | |
19 | * Usage: emacs Usage. Using the interface. | |
20 | * Configuration: emacs Configuration. Configuring the interface. | |
21 | @end menu | |
22 | ||
23 | @node emacs Initial Setup | |
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 | ||
62 | @node emacs Usage | |
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 | |
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. | |
74 | @end menu | |
75 | ||
76 | @node emacs Commands | |
77 | @subsubsection Commands | |
78 | ||
79 | You may use the following commands to display packages and generations: | |
80 | ||
81 | @table @kbd | |
82 | @item M-x guix-all-available-packages | |
83 | @itemx M-x guix-newest-available-packages | |
84 | Display all/newest available packages. | |
85 | ||
86 | @item M-x guix-installed-packages | |
87 | Display all packages installed in the current profile. | |
88 | ||
89 | @item M-x guix-obsolete-packages | |
90 | Display obsolete packages (the packages that are installed in the | |
91 | current profile but cannot be found among available packages). | |
92 | ||
93 | @item M-x guix-search-by-name | |
94 | Display package(s) with the specified name. | |
95 | ||
96 | @item M-x guix-search-by-regexp | |
97 | Search for packages by a specified regexp. By default ``name'', | |
98 | ``synopsis'' and ``description'' of the packages will be searched. This | |
99 | can be changed by modifying @code{guix-search-params} variable. | |
100 | ||
101 | @item M-x guix-generations | |
102 | List generations for the current profile. With numeric prefix, show so | |
103 | many last generations. | |
104 | ||
105 | @end table | |
106 | ||
107 | It is possible to change the currently used profile with | |
108 | @kbd{M-x@tie{}guix-set-current-profile}. This has the same effect as | |
109 | specifying @code{--profile} option for @command{guix package} | |
110 | (@pxref{Invoking guix package}). | |
111 | ||
112 | @node emacs General info | |
113 | @subsubsection General information | |
114 | ||
115 | The following keys are available for both ``list'' and ``info'' types of | |
116 | buffers: | |
117 | ||
118 | @table @kbd | |
119 | @item l | |
120 | @itemx r | |
121 | Go backward/forward by the history of the displayed results (this | |
122 | history is similar to the history of the Emacs @code{help-mode} or | |
123 | @code{Info-mode}). | |
124 | ||
125 | @item g | |
126 | Revert current buffer: update information about the displayed | |
127 | packages/generations and redisplay it. | |
128 | ||
129 | @item R | |
130 | Redisplay current buffer (without updating information). | |
131 | ||
132 | @item C-c C-z | |
133 | Go to the Guix REPL (@pxref{The REPL,,, geiser, Geiser User Manual}). | |
134 | ||
135 | @item h | |
136 | @itemx ? | |
137 | Describe current mode to see all available bindings. | |
138 | ||
139 | @end table | |
140 | ||
141 | @emph{Hint:} If you need several ``list'' or ``info'' buffers, you can | |
142 | simlpy @kbd{M-x clone-buffer} them, and each buffer will have its own | |
143 | history. | |
144 | ||
145 | @emph{Warning:} Name/version pairs cannot be used to identify packages | |
146 | (because a name is not necessarily unique), so ``guix.el'' uses special | |
147 | identifiers that live only during a guile session, so if the Guix REPL | |
148 | was restarted, you may want to revert ``list'' buffer (by pressing | |
149 | @kbd{g}). | |
150 | ||
151 | @node emacs List buffer | |
152 | @subsubsection ``List'' buffer | |
153 | ||
154 | An interface of a ``list'' buffer is similar to the interface provided | |
155 | by ``package.el'' (@pxref{Package Menu,,, emacs, The Emacs Editor}). | |
156 | ||
157 | Default key bindings available for both ``package-list'' and | |
158 | ``generation-list'' buffers: | |
159 | ||
160 | @table @kbd | |
161 | @item m | |
162 | Mark the current entry. | |
163 | @item M | |
164 | Mark all entries. | |
165 | @item u | |
166 | Unmark the current entry. | |
167 | @item @key{DEL} | |
168 | Unmark backward. | |
169 | @item U | |
170 | Unmark all entries. | |
171 | @item S | |
172 | Sort entries by a specified column. | |
173 | @end table | |
174 | ||
175 | A ``package-list'' buffer additionally provides the following bindings: | |
176 | ||
177 | @table @kbd | |
178 | @item @key{RET} | |
179 | Describe marked packages (display available information in a | |
180 | ``package-info'' buffer). | |
181 | @item i | |
182 | Mark a package for installation (with prefix, prompt for output(s) to | |
183 | install). | |
184 | @item d | |
185 | Mark a package for deletion. | |
186 | @item ^ | |
187 | Mark a package for upgrading. | |
188 | @item x | |
189 | Execute actions on marked packages. | |
190 | @end table | |
191 | ||
192 | A ``generation-list'' buffer additionally provides the following | |
193 | bindings: | |
194 | ||
195 | @table @kbd | |
196 | @item @key{RET} | |
197 | List packages installed in the current generation. | |
198 | @item i | |
199 | Describe marked generations (display available information in a | |
200 | ``generation-info'' buffer). | |
201 | @end table | |
202 | ||
203 | @node emacs Info buffer | |
204 | @subsubsection ``Info'' buffer | |
205 | ||
206 | The interface of an ``info'' buffer is similar to the interface of | |
207 | @code{help-mode} (@pxref{Help Mode,,, emacs, The Emacs Editor}). | |
208 | ||
209 | ``Info'' buffer contains some buttons (as usual you may use @key{TAB} / | |
210 | @kbd{S-@key{TAB}} to move between buttons---@pxref{Mouse References,,, | |
211 | emacs, The Emacs Editor}) which can be used to: | |
212 | ||
213 | @itemize @bullet | |
214 | @item (in a ``package-info'' buffer) | |
215 | ||
216 | @itemize @minus | |
217 | @item install/remove a package; | |
218 | @item jump to a package location; | |
219 | @item browse home page of a package; | |
220 | @item describe packages from ``Inputs'' fields. | |
221 | @end itemize | |
222 | ||
223 | @item (in a ``generation-info'' buffer) | |
224 | ||
225 | @itemize @minus | |
226 | @item remove a generation; | |
227 | @item list packages installed in a generation; | |
228 | @item jump to a generation directory. | |
229 | @end itemize | |
230 | ||
231 | @end itemize | |
232 | ||
233 | ||
234 | @node emacs Configuration | |
235 | @subsection Configuration | |
236 | ||
237 | There are many variables you can modify to change the appearance or | |
238 | behavior of Emacs user interface. Some of these variables are described | |
239 | in this section. Also you can use Custom Interface (@pxref{Easy | |
240 | Customization,,, emacs, The Emacs Editor}) to explore/set variables (not | |
241 | all) and faces. | |
242 | ||
243 | @menu | |
244 | * Guile and Build Options: emacs Build Options. Specifying how packages are built. | |
245 | * Keymaps: emacs Keymaps. Configuring key bindings. | |
246 | * Appearance: emacs Appearance. Settings for visual appearance. | |
247 | @end menu | |
248 | ||
249 | @node emacs Build Options | |
250 | @subsubsection Guile and Build Options | |
251 | ||
252 | @table @code | |
253 | @item guix-guile-program | |
254 | If you have some special needs for starting a Guile process, you may set | |
255 | this variable, for example: | |
256 | ||
257 | @example | |
258 | (setq guix-guile-program '("/bin/guile" "--no-auto-compile")) | |
259 | @end example | |
260 | ||
261 | @item guix-use-substitutes | |
262 | Has the same meaning as @code{--no-substitutes} option (@pxref{Invoking | |
263 | guix build}). | |
264 | ||
265 | @item guix-dry-run | |
266 | Has the same meaning as @code{--dry-run} option (@pxref{Invoking guix | |
267 | build}). | |
268 | ||
269 | @end table | |
270 | ||
271 | @node emacs Keymaps | |
272 | @subsubsection Keymaps | |
273 | ||
274 | If you want to change default key bindings, use the following keymaps | |
275 | (@pxref{Init Rebinding,,, emacs, The Emacs Editor}): | |
276 | ||
277 | @table @code | |
278 | @item guix-list-mode-map | |
279 | Parent keymap with general keys for ``list'' buffers. | |
280 | ||
281 | @item guix-package-list-mode-map | |
282 | Keymap with specific keys for ``package-list'' buffers. | |
283 | ||
284 | @item guix-generation-list-mode-map | |
285 | Keymap with specific keys for ``generation-list'' buffers. | |
286 | ||
287 | @item guix-info-mode-map | |
288 | Parent keymap with general keys for ``info'' buffers. | |
289 | ||
290 | @item guix-package-info-mode-map | |
291 | Keymap with specific keys for ``package-info'' buffers. | |
292 | ||
293 | @item guix-generation-info-mode-map | |
294 | Keymap with specific keys for ``generation-info'' buffers. | |
295 | ||
296 | @end table | |
297 | ||
298 | @node emacs Appearance | |
299 | @subsubsection Appearance | |
300 | ||
301 | You can change almost any aspect of ``list'' / ``info'' buffers using | |
302 | the following variables: | |
303 | ||
304 | @table @code | |
305 | @item guix-list-column-format | |
306 | @itemx guix-list-column-titles | |
307 | @itemx guix-list-column-value-methods | |
308 | Specify the columns, their names, what and how is displayed in ``list'' | |
309 | buffers. | |
310 | ||
311 | @item guix-info-displayed-params | |
312 | @itemx guix-info-insert-methods | |
313 | @itemx guix-info-ignore-empty-vals | |
314 | @itemx guix-info-param-title-format | |
315 | @itemx guix-info-multiline-prefix | |
316 | @itemx guix-info-indent | |
317 | @itemx guix-info-fill-column | |
318 | @itemx guix-info-delimiter | |
319 | Various settings for ``info'' buffers. | |
320 | ||
321 | @end table |