summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorAlex Kost <alezost@gmail.com>2016-12-22 12:47:28 +0300
committerAlex Kost <alezost@gmail.com>2016-12-29 23:40:24 +0300
commitdeb6276dda81a69da38e842d269c5370a28fa5cf (patch)
tree93e63ad233b0cae6e40473b020be14911cbd7aee /doc
parent94a6f20bafc2bb7b11cbd150779999ffa738ec7b (diff)
Remove Emacs interface.
* emacs/guix-about.el: Remove file. * emacs/guix-backend.el: Likewise. * emacs/guix-base.el: Likewise. * emacs/guix-buffer.el: Likewise. * emacs/guix-build-log.el: Likewise. * emacs/guix-command.el: Likewise. * emacs/guix-config.el.in: Likewise. * emacs/guix-devel.el: Likewise. * emacs/guix-entry.el: Likewise. * emacs/guix-external.el: Likewise. * emacs/guix-geiser.el: Likewise. * emacs/guix-guile.el: Likewise. * emacs/guix-help-vars.el: Likewise. * emacs/guix-helper.scm.in: Likewise. * emacs/guix-history.el: Likewise. * emacs/guix-hydra-build.el: Likewise. * emacs/guix-hydra-jobset.el: Likewise. * emacs/guix-hydra.el: Likewise. * emacs/guix-info.el: Likewise. * emacs/guix-init.el: Likewise. * emacs/guix-license.el: Likewise. * emacs/guix-list.el: Likewise. * emacs/guix-location.el: Likewise. * emacs/guix-main.scm: Likewise. * emacs/guix-messages.el: Likewise. * emacs/guix-pcomplete.el: Likewise. * emacs/guix-popup.el: Likewise. * emacs/guix-prettify.el: Likewise. * emacs/guix-profiles.el: Likewise. * emacs/guix-read.el: Likewise. * emacs/guix-ui-generation.el: Likewise. * emacs/guix-ui-license.el: Likewise. * emacs/guix-ui-location.el: Likewise. * emacs/guix-ui-package.el: Likewise. * emacs/guix-ui-system-generation.el: Likewise. * emacs/guix-ui.el: Likewise. * emacs/guix-utils.el: Likewise. * emacs/local.mk: Likewise. * doc/emacs.texi: Likewise. * doc/guix.texi: Remove cross-references to Emacs nodes. (Package Management): Mention 'emacs-guix' package. * doc/contributing.texi (The Perfect Setup): Remove the reference. * doc/htmlxref.cnf: Add 'emacs-guix' URL. * Makefile.am: Remove Emacs stuff. * configure.ac: Likewise. * gnu/packages/package-management.scm (guix-0.12.0)[native-inputs]: Remove "emacs". [propagated-inputs]: Remove "geiser" and "emacs-magit-popup". Co-authored-by: Ludovic Courtès <ludo@gnu.org>
Diffstat (limited to 'doc')
-rw-r--r--doc/contributing.texi3
-rw-r--r--doc/emacs.texi881
-rw-r--r--doc/guix.texi51
-rw-r--r--doc/htmlxref.cnf2
4 files changed, 13 insertions, 924 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi
index de08f9b3510..24db9a89e6f 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -187,9 +187,6 @@ facilities to directly operate on the syntax tree, such as raising an
187s-expression or wrapping it, swallowing or rejecting the following 187s-expression or wrapping it, swallowing or rejecting the following
188s-expression, etc. 188s-expression, etc.
189 189
190GNU Guix also comes with a minor mode that provides some additional
191functionality for Scheme buffers (@pxref{Emacs Development}).
192
193 190
194@node Coding Style 191@node Coding Style
195@section Coding Style 192@section Coding Style
diff --git a/doc/emacs.texi b/doc/emacs.texi
deleted file mode 100644
index 1ffb9f636ed..00000000000
--- a/doc/emacs.texi
+++ /dev/null
@@ -1,881 +0,0 @@
1@node Emacs Interface
2@chapter Emacs Interface
3
4@cindex Emacs
5GNU Guix comes with several useful modules (known as ``guix.el'') for
6GNU@tie{}Emacs which are intended to make an Emacs user interaction with
7Guix convenient and fun.
8
9@menu
10* Initial Setup: Emacs Initial Setup. Preparing @file{~/.emacs}.
11* Package Management: Emacs Package Management. Managing packages and generations.
12* Licenses: Emacs Licenses. Interface for licenses of Guix packages.
13* Package Source Locations: Emacs Package Locations. Interface for package location files.
14* Popup Interface: Emacs Popup Interface. Magit-like interface for guix commands.
15* Prettify Mode: Emacs Prettify. Abbreviating @file{/gnu/store/@dots{}} file names.
16* Build Log Mode: Emacs Build Log. Highlighting Guix build logs.
17* Completions: Emacs Completions. Completing @command{guix} shell command.
18* Development: Emacs Development. Tools for Guix developers.
19* Hydra: Emacs Hydra. Interface for Guix build farm.
20@end menu
21
22
23@node Emacs Initial Setup
24@section Initial Setup
25
26On the Guix System Distribution (@pxref{GNU Distribution}), ``guix.el''
27is ready to use, provided Guix is installed system-wide, which is the
28case by default. So if that is what you're using, you can happily skip
29this section and read about the fun stuff.
30
31If you're not yet a happy user of GuixSD, a little bit of setup is needed.
32To be able to use ``guix.el'', you need to install the following
33packages:
34
35@itemize
36@item
37@uref{http://www.gnu.org/software/emacs/, GNU Emacs}, version 24.3 or
38later;
39
40@item
41@uref{http://nongnu.org/geiser/, Geiser}, version 0.3 or later: it is
42used for interacting with the Guile process.
43
44@item
45@uref{https://github.com/magit/magit/, magit-popup library}. You
46already have this library if you use Magit 2.1.0 or later. This library
47is an optional dependency---it is required only for @kbd{M-x@tie{}guix}
48command (@pxref{Emacs Popup Interface}).
49
50@end itemize
51
52When it is done, ``guix.el'' may be configured by requiring
53@code{guix-autoloads} file. If you install Guix in your user profile,
54this 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
57is no need to read further.
58
59For the manual installation, you need to add the following code into
60your init file (@pxref{Init File,,, emacs, The GNU Emacs Manual}):
61
62@example
63(add-to-list 'load-path "/path/to/directory-with-guix.el")
64(require 'guix-autoloads nil t)
65@end example
66
67So the only thing you need to figure out is where the directory with
68elisp files for Guix is placed. It depends on how you installed Guix:
69
70@itemize
71@item
72If it was installed by a package manager of your distribution or by a
73usual @code{./configure && make && make install} command sequence, then
74elisp files are placed in a standard directory with Emacs packages
75(usually it is @file{/usr/share/emacs/site-lisp/}), which is already in
76@code{load-path}, so there is no need to add that directory there. Note
77that if you don't update this installation periodically, you may get an
78outdated Emacs code which does not work with the current Guile code of
79Guix.
80
81@item
82If you used a binary installation method (@pxref{Binary Installation}),
83then Guix is installed somewhere in the store, so the elisp files are
84placed in @file{/gnu/store/@dots{}-guix-0.8.2/share/emacs/site-lisp/} or
85alike. However it is not recommended to refer directly to a store
86directory, as it may be garbage-collected one day. So a better choice
87would be to install Guix using Guix itself with @command{guix package -i
88guix}.
89
90@item
91If 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
94same directory, so your final configuration will look like this:
95
96@example
97(let ((dir "/path/to/your-guix-git-tree/emacs"))
98 (add-to-list 'load-path dir)
99 (setq guix-load-path dir))
100(require 'guix-autoloads nil t)
101@end example
102@end itemize
103
104
105@node Emacs Package Management
106@section Package Management
107
108Once ``guix.el'' has been successfully configured, you should be able to
109use a visual interface for routine package management tasks, pretty much
110like the @command{guix package} command (@pxref{Invoking guix package}).
111Specifically, 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
119
120@menu
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.
125* Configuration: Emacs Configuration. Configuring the interface.
126@end menu
127
128@node Emacs Commands
129@subsection Commands
130
131All commands for displaying packages and generations use the current
132profile, which can be changed with
133@kbd{M-x@tie{}guix-set-current-profile}. Alternatively, if you call any
134of these commands with prefix argument (@kbd{C-u}), you will be prompted
135for a profile just for that command.
136
137Commands for displaying packages:
138
139@table @kbd
140
141@item M-x guix-all-available-packages
142@itemx M-x guix-newest-available-packages
143Display all/newest available packages.
144
145@item M-x guix-installed-packages
146@itemx M-x guix-installed-user-packages
147@itemx M-x guix-installed-system-packages
148Display installed packages. As described above, @kbd{M-x
149guix-installed-packages} uses an arbitrary profile that you can specify,
150while the other commands display packages installed in 2 special
151profiles: @file{~/.guix-profile} and @file{/run/current-system/profile}
152(only on GuixSD).
153
154@item M-x guix-obsolete-packages
155Display obsolete packages (the packages that are installed in a profile
156but cannot be found among available packages).
157
158@item M-x guix-packages-by-name
159Display package(s) with the specified name.
160
161@item M-x guix-packages-by-license
162Display package(s) with the specified license.
163
164@item M-x guix-packages-by-location
165Display package(s) located in the specified file. These files usually
166have the following form: @file{gnu/packages/emacs.scm}, but don't type
167them manually! Press @key{TAB} to complete the file name.
168
169@item M-x guix-package-from-file
170Display package that the code within the specified file evaluates to.
171@xref{Invoking guix package, @code{--install-from-file}}, for an example
172of what such a file may look like.
173
174@item M-x guix-search-by-regexp
175Search for packages by a specified regexp. By default ``name'',
176``synopsis'' and ``description'' of the packages will be searched. This
177can be changed by modifying @code{guix-package-search-params} variable.
178
179@item M-x guix-search-by-name
180Search for packages with names matching a specified regexp. This
181command is the same as @code{guix-search-by-regexp}, except only a
182package ``name'' is searched.
183
184@end table
185
186By default, these commands display each output on a separate line. If
187you prefer to see a list of packages---i.e., a list with a package per
188line, use the following setting:
189
190@example
191(setq guix-package-list-type 'package)
192@end example
193
194Commands for displaying generations:
195
196@table @kbd
197
198@item M-x guix-generations
199List all the generations.
200
201@item M-x guix-last-generations
202List the @var{N} last generations. You will be prompted for the number
203of generations.
204
205@item M-x guix-generations-by-time
206List generations matching time period. You will be prompted for the
207period using Org mode time prompt based on Emacs calendar (@pxref{The
208date/time prompt,,, org, The Org Manual}).
209
210@end table
211
212Analogously 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
220You can also invoke the @command{guix pull} command (@pxref{Invoking
221guix pull}) from Emacs using:
222
223@table @kbd
224@item M-x guix-pull
225With @kbd{C-u}, make it verbose.
226@end table
227
228Once @command{guix pull} has succeeded, the Guix REPL is restarted. This
229allows you to keep using the Emacs interface with the updated Guix.
230
231
232@node Emacs General info
233@subsection General information
234
235The following keys are available for both ``list'' and ``info'' types of
236buffers:
237
238@table @kbd
239@item l
240@itemx r
241Go backward/forward by the history of the displayed results (this
242history is similar to the history of the Emacs @code{help-mode} or
243@code{Info-mode}).
244
245@item g
246Revert current buffer: update information about the displayed
247packages/generations and redisplay it.
248
249@item R
250Redisplay current buffer (without updating information).
251
252@item M
253Apply manifest to the current profile or to a specified profile, if
254prefix argument is used. This has the same meaning as @code{--manifest}
255option (@pxref{Invoking guix package}).
256
257@item C-c C-z
258@cindex REPL
259@cindex read-eval-print loop
260Go to the Guix REPL (@pxref{The REPL,,, geiser, Geiser User Manual}).
261
262@item h
263@itemx ?
264Describe 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
269simply @kbd{M-x clone-buffer} them, and each buffer will have its own
270history.
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
274identifiers that live only during a guile session, so if the Guix REPL
275was restarted, you may want to revert ``list'' buffer (by pressing
276@kbd{g}).
277
278@node Emacs List buffer
279@subsection ``List'' buffer
280
281An interface of a ``list'' buffer is similar to the interface provided
282by ``package.el'' (@pxref{Package Menu,,, emacs, The GNU Emacs Manual}).
283
284Default key bindings available for both ``package-list'' and
285``generation-list'' buffers:
286
287@table @kbd
288@item m
289Mark the current entry (with prefix, mark all entries).
290@item u
291Unmark the current entry (with prefix, unmark all entries).
292@item @key{DEL}
293Unmark backward.
294@item S
295Sort entries by a specified column.
296@end table
297
298A ``package-list'' buffer additionally provides the following bindings:
299
300@table @kbd
301@item @key{RET}
302Describe marked packages (display available information in a
303``package-info'' buffer).
304@item i
305Mark the current package for installation.
306@item d
307Mark the current package for deletion.
308@item U
309Mark the current package for upgrading.
310@item ^
311Mark all obsolete packages for upgrading.
312@item e
313Edit the definition of the current package (go to its location). This is
314similar to @command{guix edit} command (@pxref{Invoking guix edit}), but
315for opening a package recipe in the current Emacs instance.
316@item x
317Execute actions on the marked packages.
318@item B
319Display latest builds of the current package (@pxref{Emacs Hydra}).
320@end table
321
322A ``generation-list'' buffer additionally provides the following
323bindings:
324
325@table @kbd
326@item @key{RET}
327List packages installed in the current generation.
328@item i
329Describe marked generations (display available information in a
330``generation-info'' buffer).
331@item s
332Switch profile to the current generation.
333@item d
334Mark the current generation for deletion (with prefix, mark all
335generations).
336@item x
337Execute actions on the marked generations---i.e., delete generations.
338@item e
339Run Ediff (@pxref{Top,,, ediff, The Ediff Manual}) on package outputs
340installed in the 2 marked generations. With prefix argument, run Ediff
341on manifests of the marked generations.
342@item D
343@itemx =
344Run Diff (@pxref{Diff Mode,,, emacs, The GNU Emacs Manual}) on package
345outputs installed in the 2 marked generations. With prefix argument,
346run Diff on manifests of the marked generations.
347@item +
348List package outputs added to the latest marked generation comparing
349with another marked generation.
350@item -
351List package outputs removed from the latest marked generation comparing
352with another marked generation.
353@end table
354
355@node Emacs Info buffer
356@subsection ``Info'' buffer
357
358The interface of an ``info'' buffer is similar to the interface of
359@code{help-mode} (@pxref{Help Mode,,, emacs, The GNU Emacs Manual}).
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,,,
363emacs, The GNU Emacs Manual}) which can be used to:
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;
372@item browse license URL;
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;
380@item switch to a generation;
381@item list packages installed in a generation;
382@item jump to a generation directory.
383@end itemize
384
385@end itemize
386
387It is also possible to copy a button label (a link to an URL or a file)
388by pressing @kbd{c} on a button.
389
390
391@node Emacs Configuration
392@subsection Configuration
393
394There are many variables you can modify to change the appearance or
395behavior of Emacs user interface. Some of these variables are described
396in this section. Also you can use Custom Interface (@pxref{Easy
397Customization,,, emacs, The GNU Emacs Manual}) to explore/set variables
398(not all) and faces.
399
400@menu
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.
405@end menu
406
407@node Emacs Build Options
408@subsubsection Guile and Build Options
409
410@table @code
411@item guix-guile-program
412If you have some special needs for starting a Guile process, you may set
413this 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
420If nil, has the same meaning as @code{--no-substitutes} option
421(@pxref{Invoking guix build}).
422
423@item guix-dry-run
424If non-nil, has the same meaning as @code{--dry-run} option
425(@pxref{Invoking guix build}).
426
427@end table
428
429@node Emacs Buffer Names
430@subsubsection Buffer Names
431
432Default names of ``guix.el'' buffers (``*Guix@tie{}@dots{}*'') may be
433changed 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
444@end table
445
446By default, the name of a profile is also displayed in a ``list'' or
447``info'' buffer name. To change this behavior, use
448@code{guix-ui-buffer-name-function} variable.
449
450For example, if you want to display all types of results in a single
451buffer (in such case you will probably use a history (@kbd{l}/@kbd{r})
452extensively), 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
462 guix-generation-info-buffer-name name))
463@end example
464
465@node Emacs Keymaps
466@subsubsection Keymaps
467
468If you want to change default key bindings, use the following keymaps
469(@pxref{Init Rebinding,,, emacs, The GNU Emacs Manual}):
470
471@table @code
472@item guix-buffer-map
473Parent keymap with general keys for any buffer type.
474
475@item guix-ui-map
476Parent keymap with general keys for buffers used for Guix package
477management (for packages, outputs and generations).
478
479@item guix-list-mode-map
480Parent keymap with general keys for ``list'' buffers.
481
482@item guix-package-list-mode-map
483Keymap with specific keys for ``package-list'' buffers.
484
485@item guix-output-list-mode-map
486Keymap with specific keys for ``output-list'' buffers.
487
488@item guix-generation-list-mode-map
489Keymap with specific keys for ``generation-list'' buffers.
490
491@item guix-info-mode-map
492Parent keymap with general keys for ``info'' buffers.
493
494@item guix-package-info-mode-map
495Keymap with specific keys for ``package-info'' buffers.
496
497@item guix-output-info-mode-map
498Keymap with specific keys for ``output-info'' buffers.
499
500@item guix-generation-info-mode-map
501Keymap with specific keys for ``generation-info'' buffers.
502
503@item guix-info-button-map
504Keymap with keys available when a point is placed on a button.
505
506@end table
507
508@node Emacs Appearance
509@subsubsection Appearance
510
511You can change almost any aspect of ``list'' / ``info'' buffers using
512the following variables (@dfn{ENTRY-TYPE} means @code{package},
513@code{output} or @code{generation}):
514
515@table @code
516@item guix-ENTRY-TYPE-list-format
517@itemx guix-ENTRY-TYPE-list-titles
518Specify the columns, their names, what and how is displayed in ``list''
519buffers.
520
521@item guix-ENTRY-TYPE-info-format
522@itemx guix-ENTRY-TYPE-info-titles
523@itemx guix-info-ignore-empty-values
524@itemx guix-info-param-title-format
525@itemx guix-info-multiline-prefix
526@itemx guix-info-indent
527@itemx guix-info-fill
528@itemx guix-info-delimiter
529Various settings for ``info'' buffers.
530
531@end table
532
533
534@node Emacs Licenses
535@section Licenses
536
537If you want to browse the URL of a particular license, or to look at a
538list of licenses, you may use the following commands:
539
540@table @kbd
541
542@item M-x guix-browse-license-url
543Choose a license from a completion list to browse its URL using
544@code{browse-url} function (@pxref{Browse-URL,,, emacs, The GNU Emacs
545Manual}).
546
547@item M-x guix-licenses
548Display a list of available licenses. You can press @kbd{@key{RET}}
549there to display packages with this license in the same way as @kbd{M-x
550guix-packages-by-license} would do (@pxref{Emacs Commands}).
551
552@item M-x guix-find-license-definition
553Open @file{@dots{}/guix/licenses.scm} and move to the specified license.
554
555@end table
556
557
558@node Emacs Package Locations
559@section Package Source Locations
560
561As you know, package definitions are placed in Guile files, also known
562as @dfn{package locations}. The following commands should help you not
563get lost in these locations:
564
565@table @kbd
566
567@item M-x guix-locations
568Display a list of package locations. You can press @key{RET} there to
569display packages placed in the current location in the same way as
570@kbd{M-x guix-packages-by-location} would do (@pxref{Emacs Commands}).
571Note that when the point is on a location button, @key{RET} will open
572this location file.
573
574@item M-x guix-find-location
575Open the given package definition source file (press @key{TAB} to choose
576a location from a completion list).
577
578@item M-x guix-edit
579Find 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
582package name.
583
584@end table
585
586If you are contributing to Guix, you may find it useful for @kbd{M-x
587guix-find-location} and @kbd{M-x guix-edit} to open locations from your
588Git checkout. This can be done by setting @code{guix-directory}
589variable. 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
598Also you can use @kbd{C-u} prefix argument to specify a directory just
599for the current @kbd{M-x guix-find-location} or @kbd{M-x guix-edit}
600command.
601
602
603@node Emacs Popup Interface
604@section Popup Interface
605
606If you ever used Magit, you know what ``popup interface'' is
607(@pxref{Top,,, magit-popup, Magit-Popup User Manual}). Even if you are
608not acquainted with Magit, there should be no worries as it is very
609intuitive.
610
611So @kbd{M-x@tie{}guix} command provides a top-level popup interface for
612all available guix commands. When you select an option, you'll be
613prompted for a value in the minibuffer. Many values have completions,
614so don't hesitate to press @key{TAB} key. Multiple values (for example,
615packages or lint checkers) should be separated by commas.
616
617After specifying all options and switches for a command, you may choose
618one of the available actions. The following default actions are
619available for all commands:
620
621@itemize
622
623@item
624Run the command in the Guix REPL. It is faster than running
625@code{guix@tie{}@dots{}} command directly in shell, as there is no
626need to run another guile process and to load required modules there.
627
628@item
629Run the command in a shell buffer. You can set
630@code{guix-run-in-shell-function} variable to fine tune the shell buffer
631you want to use.
632
633@item
634Add the command line to the kill ring (@pxref{Kill Ring,,, emacs, The
635GNU Emacs Manual}).
636
637@end itemize
638
639Several commands (@command{guix graph}, @command{guix system shepherd-graph}
640and @command{guix system extension-graph}) also have a ``View graph''
641action, which allows you to view a generated graph using @command{dot}
642command (specified by @code{guix-dot-program} variable). By default a
643PNG file will be saved in @file{/tmp} directory and will be opened
644directly in Emacs. This behavior may be changed with the following
645variables:
646
647@table @code
648
649@item guix-find-file-function
650Function used to open a generated graph. If you want to open a graph in
651an external program, you can do it by modifying this variable---for
652example, 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
661Command line arguments to run @command{dot} command. If you change an
662output format (for example, into @code{-Tpdf}), you also need to change
663the next variable.
664
665@item guix-dot-file-name-function
666Function used to define a name of the generated graph file. Default
667name is @file{/tmp/guix-emacs-graph-XXXXXX.png}.
668
669@end table
670
671So, for example, if you want to generate and open a PDF file in your
672Emacs, 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
682
683@node Emacs Prettify
684@section Guix Prettify Mode
685
686GNU@tie{}Guix also comes with ``guix-prettify.el''. It provides a minor
687mode for abbreviating store file names by replacing hash sequences of
688symbols with ``@dots{}'':
689
690@example
691/gnu/store/72f54nfp6g1hz873w8z3gfcah0h4nl9p-foo-0.1
692@result{} /gnu/store/…-foo-0.1
693@end example
694
695Once you set up ``guix.el'' (@pxref{Emacs Initial Setup}), the following
696commands become available:
697
698@table @kbd
699
700@item M-x guix-prettify-mode
701Enable/disable prettifying for the current buffer.
702
703@item M-x global-guix-prettify-mode
704Enable/disable prettifying globally.
705
706@end table
707
708To automatically enable @code{guix-prettify-mode} globally on Emacs
709start, add the following line to your init file:
710
711@example
712(global-guix-prettify-mode)
713@end example
714
715If you want to enable it only for specific major modes, add it to the
716mode 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
722
723
724@node Emacs Build Log
725@section Build Log Mode
726
727GNU@tie{}Guix provides major and minor modes for highlighting build
728logs. So when you have a file with a package build output---for
729example, a file returned by @command{guix build --log-file @dots{}}
730command (@pxref{Invoking guix build}), you may call @kbd{M-x
731guix-build-log-mode} command in the buffer with this file. This major
732mode highlights some lines specific to build output and provides the
733following key bindings:
734
735@table @kbd
736
737@item M-n
738Move to the next build phase.
739
740@item M-p
741Move to the previous build phase.
742
743@item @key{TAB}
744Toggle (show/hide) the body of the current build phase.
745
746@item S-@key{TAB}
747Toggle (show/hide) the bodies of all build phases.
748
749@end table
750
751There is also @kbd{M-x guix-build-log-minor-mode} which also provides
752the same highlighting and the same key bindings as the major mode, but
753prefixed with @kbd{C-c}. By default, this minor mode is enabled in
754shell buffers (@pxref{Interactive Shell,,, emacs, The GNU Emacs
755Manual}). If you don't like it, set
756@code{guix-build-log-minor-mode-activate} to nil.
757
758
759@node Emacs Completions
760@section Shell Completions
761
762Another feature that becomes available after configuring Emacs interface
763(@pxref{Emacs Initial Setup}) is completing of @command{guix}
764subcommands, 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
768It works the same way as other completions do. Just press @key{TAB}
769when your intuition tells you.
770
771And here are some examples, where pressing @key{TAB} may complete
772something:
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
788
789
790@node Emacs Development
791@section Development
792
793By default, when you open a Scheme file, @code{guix-devel-mode} will be
794activated (if you don't want it, set @code{guix-devel-activate-mode} to
795nil). This minor mode provides the following key bindings:
796
797@table @kbd
798
799@item C-c . k
800Copy the name of the current Guile module into kill ring
801(@code{guix-devel-copy-module-as-kill}).
802
803@item C-c . u
804Use the current Guile module. Often after opening a Scheme file, you
805want to use a module it defines, so you switch to the Geiser REPL and
806write @code{,use (some module)} there. You may just use this command
807instead (@code{guix-devel-use-module}).
808
809@item C-c . b
810Build a package defined by the current variable definition. The
811building process is run in the current Geiser REPL. If you modified the
812current package definition, don't forget to reevaluate it before calling
813this command---for example, with @kbd{C-M-x} (@pxref{To eval or not to
814eval,,, geiser, Geiser User Manual})
815(@code{guix-devel-build-package-definition}).
816
817@item C-c . s
818Build a source derivation of the package defined by the current variable
819definition. This command has the same meaning as @code{guix build -S}
820shell command (@pxref{Invoking guix build})
821(@code{guix-devel-build-package-source}).
822
823@item C-c . l
824Lint (check) a package defined by the current variable definition
825(@pxref{Invoking guix lint}) (@code{guix-devel-lint-package}).
826
827@end table
828
829Unluckily, there is a limitation related to long-running REPL commands.
830When there is a running process in a Geiser REPL, you are not supposed
831to evaluate anything in a scheme buffer, because this will ``freeze''
832the REPL: it will stop producing any output (however, the evaluating
833process will continue---you will just not see any progress anymore). Be
834aware: even moving the point in a scheme buffer may ``break'' the REPL
835if Autodoc (@pxref{Autodoc and friends,,, geiser, Geiser User Manual})
836is enabled (which is the default).
837
838So you have to postpone editing your scheme buffers until the running
839evaluation will be finished in the REPL.
840
841Alternatively, to avoid this limitation, you may just run another Geiser
842REPL, and while something is being evaluated in the previous REPL, you
843can continue editing a scheme file with the help of the current one.
844
845
846@node Emacs Hydra
847@section Hydra
848
849The continuous integration server at @code{hydra.gnu.org} builds all
850the distribution packages on the supported architectures and serves
851them as substitutes (@pxref{Substitutes}). Continuous integration is
852currently orchestrated by @uref{https://nixos.org/hydra/, Hydra}.
853
854This section describes an Emacs interface to query Hydra to know the
855build status of specific packages, discover recent and ongoing builds,
856view 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
860The following commands are available:
861
862@table @kbd
863
864@item M-x guix-hydra-latest-builds
865Display latest failed or successful builds (you will be prompted for a
866number of builds). With @kbd{C-u}, you will also be prompted for other
867parameters (project, jobset, job and system).
868
869@item M-x guix-hydra-queued-builds
870Display scheduled or currently running builds (you will be prompted for
871a number of builds).
872
873@item M-x guix-hydra-jobsets
874Display available jobsets (you will be prompted for a project).
875
876@end table
877
878In a list of builds you can press @kbd{L} key to display a build log of
879the current build. Also both a list of builds and a list of jobsets
880provide @kbd{B} key to display latest builds of the current job or
881jobset (don't forget about @kbd{C-u}).
diff --git a/doc/guix.texi b/doc/guix.texi
index 69129d5835e..8756061a46e 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -54,12 +54,6 @@ Documentation License''.
54* guix environment: (guix)Invoking guix environment. Building development environments with Guix. 54* guix environment: (guix)Invoking guix environment. Building development environments with Guix.
55@end direntry 55@end direntry
56 56
57@dircategory Emacs
58@direntry
59* Guix user interface: (guix)Emacs Interface. Package management from the comfort of Emacs.
60@end direntry
61
62
63@titlepage 57@titlepage
64@title GNU Guix Reference Manual 58@title GNU Guix Reference Manual
65@subtitle Using the GNU Guix Functional Package Manager 59@subtitle Using the GNU Guix Functional Package Manager
@@ -86,7 +80,6 @@ package management tool written for the GNU system.
86* Introduction:: What is Guix about? 80* Introduction:: What is Guix about?
87* Installation:: Installing Guix. 81* Installation:: Installing Guix.
88* Package Management:: Package installation, upgrade, etc. 82* Package Management:: Package installation, upgrade, etc.
89* Emacs Interface:: Using Guix from Emacs.
90* Programming Interface:: Using Guix in Scheme. 83* Programming Interface:: Using Guix in Scheme.
91* Utilities:: Package management commands. 84* Utilities:: Package management commands.
92* GNU Distribution:: Software for your friendly GNU system. 85* GNU Distribution:: Software for your friendly GNU system.
@@ -124,19 +117,6 @@ Package Management
124* Invoking guix pull:: Fetching the latest Guix and distribution. 117* Invoking guix pull:: Fetching the latest Guix and distribution.
125* Invoking guix archive:: Exporting and importing store files. 118* Invoking guix archive:: Exporting and importing store files.
126 119
127Emacs Interface
128
129* Initial Setup: Emacs Initial Setup. Preparing @file{~/.emacs}.
130* Package Management: Emacs Package Management. Managing packages and generations.
131* Licenses: Emacs Licenses. Interface for licenses of Guix packages.
132* Package Source Locations: Emacs Package Locations. Interface for package location files.
133* Popup Interface: Emacs Popup Interface. Magit-like interface for guix commands.
134* Prettify Mode: Emacs Prettify. Abbreviating @file{/gnu/store/@dots{}} file names.
135* Build Log Mode: Emacs Build Log. Highlighting Guix build logs.
136* Completions: Emacs Completions. Completing @command{guix} shell command.
137* Development: Emacs Development. Tools for Guix developers.
138* Hydra: Emacs Hydra. Interface for Guix build farm.
139
140Programming Interface 120Programming Interface
141 121
142* Defining Packages:: Defining new packages. 122* Defining Packages:: Defining new packages.
@@ -278,8 +258,7 @@ assists with the creation and maintenance of software environments.
278@cindex user interfaces 258@cindex user interfaces
279Guix provides a command-line package management interface 259Guix provides a command-line package management interface
280(@pxref{Invoking guix package}), a set of command-line utilities 260(@pxref{Invoking guix package}), a set of command-line utilities
281(@pxref{Utilities}), a visual user interface in Emacs (@pxref{Emacs 261(@pxref{Utilities}), as well as Scheme programming interfaces
282Interface}), as well as Scheme programming interfaces
283(@pxref{Programming Interface}). 262(@pxref{Programming Interface}).
284@cindex build daemon 263@cindex build daemon
285Its @dfn{build daemon} is responsible for building packages on behalf of 264Its @dfn{build daemon} is responsible for building packages on behalf of
@@ -1414,10 +1393,14 @@ procedures or dependencies. Guix also goes beyond this obvious set of
1414features. 1393features.
1415 1394
1416This chapter describes the main features of Guix, as well as the package 1395This chapter describes the main features of Guix, as well as the package
1417management tools it provides. Two user interfaces are provided for 1396management tools it provides. Along with the command-line interface
1418routine package management tasks: A command-line interface described below 1397described below (@pxref{Invoking guix package, @code{guix package}}),
1419(@pxref{Invoking guix package, @code{guix package}}), as well as a visual user 1398you may also use Emacs Interface, after installing @code{emacs-guix}
1420interface in Emacs described in a subsequent chapter (@pxref{Emacs Interface}). 1399package (run @kbd{M-x guix-help} command to start with it):
1400
1401@example
1402guix package -i emacs-guix
1403@end example
1421 1404
1422@menu 1405@menu
1423* Features:: How Guix will make your life brighter. 1406* Features:: How Guix will make your life brighter.
@@ -1434,9 +1417,7 @@ interface in Emacs described in a subsequent chapter (@pxref{Emacs Interface}).
1434 1417
1435When using Guix, each package ends up in the @dfn{package store}, in its 1418When using Guix, each package ends up in the @dfn{package store}, in its
1436own directory---something that resembles 1419own directory---something that resembles
1437@file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string 1420@file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string.
1438(note that Guix comes with an Emacs extension to shorten those file
1439names, @pxref{Emacs Prettify}.)
1440 1421
1441Instead of referring to these directories, users have their own 1422Instead of referring to these directories, users have their own
1442@dfn{profile}, which points to the packages that they actually want to 1423@dfn{profile}, which points to the packages that they actually want to
@@ -1982,9 +1963,7 @@ also result from derivation builds, can be available as substitutes.
1982 1963
1983The @code{hydra.gnu.org} server is a front-end to a build farm that 1964The @code{hydra.gnu.org} server is a front-end to a build farm that
1984builds packages from the GNU distribution continuously for some 1965builds packages from the GNU distribution continuously for some
1985architectures, and makes them available as substitutes (@pxref{Emacs 1966architectures, and makes them available as substitutes. This is the
1986Hydra}, for information on how to query the continuous integration
1987server). This is the
1988default source of substitutes; it can be overridden by passing the 1967default source of substitutes; it can be overridden by passing the
1989@option{--substitute-urls} option either to @command{guix-daemon} 1968@option{--substitute-urls} option either to @command{guix-daemon}
1990(@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}}) 1969(@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}})
@@ -2510,9 +2489,6 @@ archive contents coming from possibly untrusted substitute servers.
2510@end table 2489@end table
2511 2490
2512@c ********************************************************************* 2491@c *********************************************************************
2513@include emacs.texi
2514
2515@c *********************************************************************
2516@node Programming Interface 2492@node Programming Interface
2517@chapter Programming Interface 2493@chapter Programming Interface
2518 2494
@@ -4923,11 +4899,6 @@ have created your own packages on @code{GUIX_PACKAGE_PATH}
4923recipes. Otherwise, you will be able to examine the read-only recipes 4899recipes. Otherwise, you will be able to examine the read-only recipes
4924for packages currently in the store. 4900for packages currently in the store.
4925 4901
4926If you are using Emacs, note that the Emacs user interface provides the
4927@kbd{M-x guix-edit} command and a similar functionality in the ``package
4928info'' and ``package list'' buffers created by the @kbd{M-x
4929guix-search-by-name} and similar commands (@pxref{Emacs Commands}).
4930
4931 4902
4932@node Invoking guix download 4903@node Invoking guix download
4933@section Invoking @command{guix download} 4904@section Invoking @command{guix download}
diff --git a/doc/htmlxref.cnf b/doc/htmlxref.cnf
index bd2eb5f1477..93e214fcc56 100644
--- a/doc/htmlxref.cnf
+++ b/doc/htmlxref.cnf
@@ -219,6 +219,8 @@ emacs node ${EMACS}/html_node/emacs/
219easejs mono ${GS}/easejs/manual/easejs.html 219easejs mono ${GS}/easejs/manual/easejs.html
220easejs node ${GS}/easejs/manual/ 220easejs node ${GS}/easejs/manual/
221 221
222emacs-guix mono https://notabug.org/alezost/emacs-guix
223
222emacs-muse node ${GS}/emacs-muse/manual/muse.html 224emacs-muse node ${GS}/emacs-muse/manual/muse.html
223emacs-muse node ${GS}/emacs-muse/manual/html_node/ 225emacs-muse node ${GS}/emacs-muse/manual/html_node/
224 226