* emacs/guix-ui-package.el (guix-search-by-name): New command. * doc/emacs.texi (Emacs Commands): Document it.
798 lines
25 KiB
Plaintext
798 lines
25 KiB
Plaintext
@node Emacs Interface
|
|
@chapter Emacs Interface
|
|
|
|
@cindex Emacs
|
|
GNU Guix comes with several useful modules (known as ``guix.el'') for
|
|
GNU@tie{}Emacs which are intended to make an Emacs user interaction with
|
|
Guix convenient and fun.
|
|
|
|
@menu
|
|
* Initial Setup: Emacs Initial Setup. Preparing @file{~/.emacs}.
|
|
* Package Management: Emacs Package Management. Managing packages and generations.
|
|
* Popup Interface: Emacs Popup Interface. Magit-like interface for guix commands.
|
|
* Prettify Mode: Emacs Prettify. Abbreviating @file{/gnu/store/@dots{}} file names.
|
|
* Build Log Mode: Emacs Build Log. Highlighting Guix build logs.
|
|
* Completions: Emacs Completions. Completing @command{guix} shell command.
|
|
* Development: Emacs Development. Tools for Guix developers.
|
|
* Hydra: Emacs Hydra. Interface for Guix build farm.
|
|
@end menu
|
|
|
|
|
|
@node Emacs Initial Setup
|
|
@section Initial Setup
|
|
|
|
On the Guix System Distribution (@pxref{GNU Distribution}), ``guix.el''
|
|
is ready to use, provided Guix is installed system-wide, which is the
|
|
case by default. So if that is what you're using, you can happily skip
|
|
this section and read about the fun stuff.
|
|
|
|
If you're not yet a happy user of GuixSD, a little bit of setup is needed.
|
|
To be able to use ``guix.el'', you need to install the following
|
|
packages:
|
|
|
|
@itemize
|
|
@item
|
|
@uref{http://www.gnu.org/software/emacs/, GNU Emacs}, version 24.3 or
|
|
later;
|
|
|
|
@item
|
|
@uref{http://nongnu.org/geiser/, Geiser}, version 0.3 or later: it is
|
|
used for interacting with the Guile process.
|
|
|
|
@item
|
|
@uref{https://github.com/magit/magit/, magit-popup library}. You
|
|
already have this library if you use Magit 2.1.0 or later. This library
|
|
is an optional dependency---it is required only for @kbd{M-x@tie{}guix}
|
|
command (@pxref{Emacs Popup Interface}).
|
|
|
|
@end itemize
|
|
|
|
When it is done ``guix.el'' may be configured by requiring a special
|
|
@code{guix-init} file---i.e., by adding the following code into your
|
|
init file (@pxref{Init File,,, emacs, The GNU Emacs Manual}):
|
|
|
|
@example
|
|
(add-to-list 'load-path "/path/to/directory-with-guix.el")
|
|
(require 'guix-init nil t)
|
|
@end example
|
|
|
|
So the only thing you need to figure out is where the directory with
|
|
elisp files for Guix is placed. It depends on how you installed Guix:
|
|
|
|
@itemize
|
|
@item
|
|
If it was installed by a package manager of your distribution or by a
|
|
usual @code{./configure && make && make install} command sequence, then
|
|
elisp files are placed in a standard directory with Emacs packages
|
|
(usually it is @file{/usr/share/emacs/site-lisp/}), which is already in
|
|
@code{load-path}, so there is no need to add that directory there.
|
|
|
|
@item
|
|
If you used a binary installation method (@pxref{Binary Installation}),
|
|
then Guix is installed somewhere in the store, so the elisp files are
|
|
placed in @file{/gnu/store/@dots{}-guix-0.8.2/share/emacs/site-lisp/} or
|
|
alike. However it is not recommended to refer directly to a store
|
|
directory. Instead you can install Guix using Guix itself with
|
|
@command{guix package -i guix} command (@pxref{Invoking guix package})
|
|
and add @file{~/.guix-profile/share/emacs/site-lisp/} directory to
|
|
@code{load-path} variable.
|
|
|
|
@item
|
|
If you did not install Guix at all and prefer a hacking way
|
|
(@pxref{Running Guix Before It Is Installed}), along with augmenting
|
|
@code{load-path} you need to set @code{guix-load-path} variable to the
|
|
same directory, so your final configuration will look like this:
|
|
|
|
@example
|
|
(let ((dir "/path/to/your-guix-git-tree/emacs"))
|
|
(add-to-list 'load-path dir)
|
|
(setq guix-load-path dir))
|
|
(require 'guix-init nil t)
|
|
@end example
|
|
@end itemize
|
|
|
|
By default, along with autoloading (@pxref{Autoload,,, elisp, The GNU
|
|
Emacs Lisp Reference Manual}) the main interactive commands for
|
|
``guix.el'' (@pxref{Emacs Commands}), requiring @code{guix-init} will
|
|
also autoload commands for the Emacs packages installed in your user
|
|
profile.
|
|
|
|
To disable automatic loading of installed Emacs packages, set
|
|
@code{guix-package-enable-at-startup} variable to @code{nil} before
|
|
requiring @code{guix-init}. This variable has the same meaning for
|
|
Emacs packages installed with Guix, as @code{package-enable-at-startup}
|
|
for the built-in Emacs package system (@pxref{Package Installation,,,
|
|
emacs, The GNU Emacs Manual}).
|
|
|
|
You can activate Emacs packages installed in your profile whenever you
|
|
want using @kbd{M-x@tie{}guix-emacs-load-autoloads}.
|
|
|
|
|
|
@node Emacs Package Management
|
|
@section Package Management
|
|
|
|
Once ``guix.el'' has been successfully configured, you should be able to
|
|
use a visual interface for routine package management tasks, pretty much
|
|
like the @command{guix package} command (@pxref{Invoking guix package}).
|
|
Specifically, it makes it easy to:
|
|
|
|
@itemize
|
|
@item browse and display packages and generations;
|
|
@item search, install, upgrade and remove packages;
|
|
@item display packages from previous generations;
|
|
@item do some other useful things.
|
|
@end itemize
|
|
|
|
@menu
|
|
* Commands: Emacs Commands. @kbd{M-x guix-@dots{}}
|
|
* General information: Emacs General info. Common for both interfaces.
|
|
* ``List'' buffer: Emacs List buffer. List-like interface.
|
|
* ``Info'' buffer: Emacs Info buffer. Help-like interface.
|
|
* Configuration: Emacs Configuration. Configuring the interface.
|
|
@end menu
|
|
|
|
@node Emacs Commands
|
|
@subsection Commands
|
|
|
|
All commands for displaying packages and generations use the current
|
|
profile, which can be changed with
|
|
@kbd{M-x@tie{}guix-set-current-profile}. Alternatively, if you call any
|
|
of these commands with prefix argument (@kbd{C-u}), you will be prompted
|
|
for a profile just for that command.
|
|
|
|
Commands for displaying packages:
|
|
|
|
@table @kbd
|
|
|
|
@item M-x guix-all-available-packages
|
|
@itemx M-x guix-newest-available-packages
|
|
Display all/newest available packages.
|
|
|
|
@item M-x guix-installed-packages
|
|
Display all installed packages.
|
|
|
|
@item M-x guix-obsolete-packages
|
|
Display obsolete packages (the packages that are installed in a profile
|
|
but cannot be found among available packages).
|
|
|
|
@item M-x guix-packages-by-name
|
|
Display package(s) with the specified name.
|
|
|
|
@item M-x guix-search-by-regexp
|
|
Search for packages by a specified regexp. By default ``name'',
|
|
``synopsis'' and ``description'' of the packages will be searched. This
|
|
can be changed by modifying @code{guix-package-search-params} variable.
|
|
|
|
@item M-x guix-search-by-name
|
|
Search for packages with names matching a specified regexp. This
|
|
command is the same as @code{guix-search-by-regexp}, except only a
|
|
package ``name'' is searched.
|
|
|
|
@end table
|
|
|
|
By default, these commands display each output on a separate line. If
|
|
you prefer to see a list of packages---i.e., a list with a package per
|
|
line, use the following setting:
|
|
|
|
@example
|
|
(setq guix-package-list-type 'package)
|
|
@end example
|
|
|
|
Commands for displaying generations:
|
|
|
|
@table @kbd
|
|
|
|
@item M-x guix-generations
|
|
List all the generations.
|
|
|
|
@item M-x guix-last-generations
|
|
List the @var{N} last generations. You will be prompted for the number
|
|
of generations.
|
|
|
|
@item M-x guix-generations-by-time
|
|
List generations matching time period. You will be prompted for the
|
|
period using Org mode time prompt based on Emacs calendar (@pxref{The
|
|
date/time prompt,,, org, The Org Manual}).
|
|
|
|
@end table
|
|
|
|
Analogously on GuixSD you can also display system generations:
|
|
|
|
@table @kbd
|
|
@item M-x guix-system-generations
|
|
@item M-x guix-last-system-generations
|
|
@item M-x guix-system-generations-by-time
|
|
@end table
|
|
|
|
You can also invoke the @command{guix pull} command (@pxref{Invoking
|
|
guix pull}) from Emacs using:
|
|
|
|
@table @kbd
|
|
@item M-x guix-pull
|
|
With @kbd{C-u}, make it verbose.
|
|
@end table
|
|
|
|
Once @command{guix pull} has succeeded, the Guix REPL is restared. This
|
|
allows you to keep using the Emacs interface with the updated Guix.
|
|
|
|
@node Emacs General info
|
|
@subsection General information
|
|
|
|
The following keys are available for both ``list'' and ``info'' types of
|
|
buffers:
|
|
|
|
@table @kbd
|
|
@item l
|
|
@itemx r
|
|
Go backward/forward by the history of the displayed results (this
|
|
history is similar to the history of the Emacs @code{help-mode} or
|
|
@code{Info-mode}).
|
|
|
|
@item g
|
|
Revert current buffer: update information about the displayed
|
|
packages/generations and redisplay it.
|
|
|
|
@item R
|
|
Redisplay current buffer (without updating information).
|
|
|
|
@item M
|
|
Apply manifest to the current profile or to a specified profile, if
|
|
prefix argument is used. This has the same meaning as @code{--manifest}
|
|
option (@pxref{Invoking guix package}).
|
|
|
|
@item C-c C-z
|
|
@cindex REPL
|
|
@cindex read-eval-print loop
|
|
Go to the Guix REPL (@pxref{The REPL,,, geiser, Geiser User Manual}).
|
|
|
|
@item h
|
|
@itemx ?
|
|
Describe current mode to see all available bindings.
|
|
|
|
@end table
|
|
|
|
@emph{Hint:} If you need several ``list'' or ``info'' buffers, you can
|
|
simlpy @kbd{M-x clone-buffer} them, and each buffer will have its own
|
|
history.
|
|
|
|
@emph{Warning:} Name/version pairs cannot be used to identify packages
|
|
(because a name is not necessarily unique), so ``guix.el'' uses special
|
|
identifiers that live only during a guile session, so if the Guix REPL
|
|
was restarted, you may want to revert ``list'' buffer (by pressing
|
|
@kbd{g}).
|
|
|
|
@node Emacs List buffer
|
|
@subsection ``List'' buffer
|
|
|
|
An interface of a ``list'' buffer is similar to the interface provided
|
|
by ``package.el'' (@pxref{Package Menu,,, emacs, The GNU Emacs Manual}).
|
|
|
|
Default key bindings available for both ``package-list'' and
|
|
``generation-list'' buffers:
|
|
|
|
@table @kbd
|
|
@item m
|
|
Mark the current entry (with prefix, mark all entries).
|
|
@item u
|
|
Unmark the current entry (with prefix, unmark all entries).
|
|
@item @key{DEL}
|
|
Unmark backward.
|
|
@item S
|
|
Sort entries by a specified column.
|
|
@end table
|
|
|
|
A ``package-list'' buffer additionally provides the following bindings:
|
|
|
|
@table @kbd
|
|
@item @key{RET}
|
|
Describe marked packages (display available information in a
|
|
``package-info'' buffer).
|
|
@item i
|
|
Mark the current package for installation.
|
|
@item d
|
|
Mark the current package for deletion.
|
|
@item U
|
|
Mark the current package for upgrading.
|
|
@item ^
|
|
Mark all obsolete packages for upgrading.
|
|
@item e
|
|
Edit the definition of the curent package (go to its location). This is
|
|
similar to @command{guix edit} command (@pxref{Invoking guix edit}), but
|
|
for opening a package recipe in the current Emacs instance.
|
|
@item x
|
|
Execute actions on the marked packages.
|
|
@item B
|
|
Display latest builds of the current package (@pxref{Emacs Hydra}).
|
|
@end table
|
|
|
|
A ``generation-list'' buffer additionally provides the following
|
|
bindings:
|
|
|
|
@table @kbd
|
|
@item @key{RET}
|
|
List packages installed in the current generation.
|
|
@item i
|
|
Describe marked generations (display available information in a
|
|
``generation-info'' buffer).
|
|
@item s
|
|
Switch profile to the current generation.
|
|
@item d
|
|
Mark the current generation for deletion (with prefix, mark all
|
|
generations).
|
|
@item x
|
|
Execute actions on the marked generations---i.e., delete generations.
|
|
@item e
|
|
Run Ediff (@pxref{Top,,, ediff, The Ediff Manual}) on package outputs
|
|
installed in the 2 marked generations. With prefix argument, run Ediff
|
|
on manifests of the marked generations.
|
|
@item D
|
|
@itemx =
|
|
Run Diff (@pxref{Diff Mode,,, emacs, The GNU Emacs Manual}) on package
|
|
outputs installed in the 2 marked generations. With prefix argument,
|
|
run Diff on manifests of the marked generations.
|
|
@item +
|
|
List package outputs added to the latest marked generation comparing
|
|
with another marked generation.
|
|
@item -
|
|
List package outputs removed from the latest marked generation comparing
|
|
with another marked generation.
|
|
@end table
|
|
|
|
@node Emacs Info buffer
|
|
@subsection ``Info'' buffer
|
|
|
|
The interface of an ``info'' buffer is similar to the interface of
|
|
@code{help-mode} (@pxref{Help Mode,,, emacs, The GNU Emacs Manual}).
|
|
|
|
``Info'' buffer contains some buttons (as usual you may use @key{TAB} /
|
|
@kbd{S-@key{TAB}} to move between buttons---@pxref{Mouse References,,,
|
|
emacs, The GNU Emacs Manual}) which can be used to:
|
|
|
|
@itemize @bullet
|
|
@item (in a ``package-info'' buffer)
|
|
|
|
@itemize @minus
|
|
@item install/remove a package;
|
|
@item jump to a package location;
|
|
@item browse home page of a package;
|
|
@item describe packages from ``Inputs'' fields.
|
|
@end itemize
|
|
|
|
@item (in a ``generation-info'' buffer)
|
|
|
|
@itemize @minus
|
|
@item remove a generation;
|
|
@item switch to a generation;
|
|
@item list packages installed in a generation;
|
|
@item jump to a generation directory.
|
|
@end itemize
|
|
|
|
@end itemize
|
|
|
|
It is also possible to copy a button label (a link to an URL or a file)
|
|
by pressing @kbd{c} on a button.
|
|
|
|
|
|
@node Emacs Configuration
|
|
@subsection Configuration
|
|
|
|
There are many variables you can modify to change the appearance or
|
|
behavior of Emacs user interface. Some of these variables are described
|
|
in this section. Also you can use Custom Interface (@pxref{Easy
|
|
Customization,,, emacs, The GNU Emacs Manual}) to explore/set variables
|
|
(not all) and faces.
|
|
|
|
@menu
|
|
* Guile and Build Options: Emacs Build Options. Specifying how packages are built.
|
|
* Buffer Names: Emacs Buffer Names. Names of Guix buffers.
|
|
* Keymaps: Emacs Keymaps. Configuring key bindings.
|
|
* Appearance: Emacs Appearance. Settings for visual appearance.
|
|
@end menu
|
|
|
|
@node Emacs Build Options
|
|
@subsubsection Guile and Build Options
|
|
|
|
@table @code
|
|
@item guix-guile-program
|
|
If you have some special needs for starting a Guile process, you may set
|
|
this variable, for example:
|
|
|
|
@example
|
|
(setq guix-guile-program '("/bin/guile" "--no-auto-compile"))
|
|
@end example
|
|
|
|
@item guix-use-substitutes
|
|
Has the same meaning as @code{--no-substitutes} option (@pxref{Invoking
|
|
guix build}).
|
|
|
|
@item guix-dry-run
|
|
Has the same meaning as @code{--dry-run} option (@pxref{Invoking guix
|
|
build}).
|
|
|
|
@end table
|
|
|
|
@node Emacs Buffer Names
|
|
@subsubsection Buffer Names
|
|
|
|
Default names of ``guix.el'' buffers (``*Guix@tie{}@dots{}*'') may be
|
|
changed with the following variables:
|
|
|
|
@table @code
|
|
@item guix-package-list-buffer-name
|
|
@item guix-output-list-buffer-name
|
|
@item guix-generation-list-buffer-name
|
|
@item guix-package-info-buffer-name
|
|
@item guix-output-info-buffer-name
|
|
@item guix-generation-info-buffer-name
|
|
@item guix-repl-buffer-name
|
|
@item guix-internal-repl-buffer-name
|
|
@end table
|
|
|
|
By default, the name of a profile is also displayed in a ``list'' or
|
|
``info'' buffer name. To change this behavior, use
|
|
@code{guix-ui-buffer-name-function} variable.
|
|
|
|
For example, if you want to display all types of results in a single
|
|
buffer (in such case you will probably use a history (@kbd{l}/@kbd{r})
|
|
extensively), you may do it like this:
|
|
|
|
@example
|
|
(let ((name "Guix Universal"))
|
|
(setq
|
|
guix-package-list-buffer-name name
|
|
guix-output-list-buffer-name name
|
|
guix-generation-list-buffer-name name
|
|
guix-package-info-buffer-name name
|
|
guix-output-info-buffer-name name
|
|
guix-generation-info-buffer-name name))
|
|
@end example
|
|
|
|
@node Emacs Keymaps
|
|
@subsubsection Keymaps
|
|
|
|
If you want to change default key bindings, use the following keymaps
|
|
(@pxref{Init Rebinding,,, emacs, The GNU Emacs Manual}):
|
|
|
|
@table @code
|
|
@item guix-buffer-map
|
|
Parent keymap with general keys for any buffer type.
|
|
|
|
@item guix-ui-map
|
|
Parent keymap with general keys for buffers used for Guix package
|
|
management (for packages, outputs and generations).
|
|
|
|
@item guix-list-mode-map
|
|
Parent keymap with general keys for ``list'' buffers.
|
|
|
|
@item guix-package-list-mode-map
|
|
Keymap with specific keys for ``package-list'' buffers.
|
|
|
|
@item guix-output-list-mode-map
|
|
Keymap with specific keys for ``output-list'' buffers.
|
|
|
|
@item guix-generation-list-mode-map
|
|
Keymap with specific keys for ``generation-list'' buffers.
|
|
|
|
@item guix-info-mode-map
|
|
Parent keymap with general keys for ``info'' buffers.
|
|
|
|
@item guix-package-info-mode-map
|
|
Keymap with specific keys for ``package-info'' buffers.
|
|
|
|
@item guix-output-info-mode-map
|
|
Keymap with specific keys for ``output-info'' buffers.
|
|
|
|
@item guix-generation-info-mode-map
|
|
Keymap with specific keys for ``generation-info'' buffers.
|
|
|
|
@item guix-info-button-map
|
|
Keymap with keys available when a point is placed on a button.
|
|
|
|
@end table
|
|
|
|
@node Emacs Appearance
|
|
@subsubsection Appearance
|
|
|
|
You can change almost any aspect of ``list'' / ``info'' buffers using
|
|
the following variables (@dfn{ENTRY-TYPE} means @code{package},
|
|
@code{output} or @code{generation}):
|
|
|
|
@table @code
|
|
@item guix-ENTRY-TYPE-list-format
|
|
@itemx guix-ENTRY-TYPE-list-titles
|
|
Specify the columns, their names, what and how is displayed in ``list''
|
|
buffers.
|
|
|
|
@item guix-ENTRY-TYPE-info-format
|
|
@itemx guix-ENTRY-TYPE-info-titles
|
|
@itemx guix-info-ignore-empty-values
|
|
@itemx guix-info-param-title-format
|
|
@itemx guix-info-multiline-prefix
|
|
@itemx guix-info-indent
|
|
@itemx guix-info-fill
|
|
@itemx guix-info-delimiter
|
|
Various settings for ``info'' buffers.
|
|
|
|
@end table
|
|
|
|
|
|
@node Emacs Popup Interface
|
|
@section Popup Interface
|
|
|
|
If you ever used Magit, you know what ``popup interface'' is
|
|
(@pxref{Top,,, magit-popup, Magit-Popup User Manual}). Even if you are
|
|
not acquainted with Magit, there should be no worries as it is very
|
|
intuitive.
|
|
|
|
So @kbd{M-x@tie{}guix} command provides a top-level popup interface for
|
|
all available guix commands. When you select an option, you'll be
|
|
prompted for a value in the minibuffer. Many values have completions,
|
|
so don't hesitate to press @key{TAB} key. Multiple values (for example,
|
|
packages or lint checkers) should be separated by commas.
|
|
|
|
After specifying all options and switches for a command, you may choose
|
|
one of the available actions. The following default actions are
|
|
available for all commands:
|
|
|
|
@itemize
|
|
|
|
@item
|
|
Run the command in the Guix REPL. It is faster than running
|
|
@code{guix@tie{}@dots{}} command directly in shell, as there is no
|
|
need to run another guile process and to load required modules there.
|
|
|
|
@item
|
|
Run the command in a shell buffer. You can set
|
|
@code{guix-run-in-shell-function} variable to fine tune the shell buffer
|
|
you want to use.
|
|
|
|
@item
|
|
Add the command line to the kill ring (@pxref{Kill Ring,,, emacs, The
|
|
GNU Emacs Manual}).
|
|
|
|
@end itemize
|
|
|
|
Several commands (@command{guix graph}, @command{guix system dmd-graph}
|
|
and @command{guix system extension-graph}) also have a ``View graph''
|
|
action, which allows you to view a generated graph using @command{dot}
|
|
command (specified by @code{guix-dot-program} variable). By default a
|
|
PNG file will be saved in @file{/tmp} directory and will be opened
|
|
directly in Emacs. This behavior may be changed with the following
|
|
variables:
|
|
|
|
@table @code
|
|
|
|
@item guix-find-file-function
|
|
Function used to open a generated graph. If you want to open a graph in
|
|
an external program, you can do it by modifying this variable---for
|
|
example, you can use a functionality provided by the Org Mode
|
|
(@pxref{Top,,, org, The Org Manual}):
|
|
|
|
@example
|
|
(setq guix-find-file-function 'org-open-file)
|
|
(add-to-list 'org-file-apps '("\\.png\\'" . "sxiv %s"))
|
|
@end example
|
|
|
|
@item guix-dot-default-arguments
|
|
Command line arguments to run @command{dot} command. If you change an
|
|
output format (for example, into @code{-Tpdf}), you also need to change
|
|
the next variable.
|
|
|
|
@item guix-dot-file-name-function
|
|
Function used to define a name of the generated graph file. Default
|
|
name is @file{/tmp/guix-emacs-graph-XXXXXX.png}.
|
|
|
|
@end table
|
|
|
|
So, for example, if you want to generate and open a PDF file in your
|
|
Emacs, you may change the settings like this:
|
|
|
|
@example
|
|
(defun my-guix-pdf-graph ()
|
|
"/tmp/my-current-guix-graph.pdf")
|
|
|
|
(setq guix-dot-default-arguments '("-Tpdf")
|
|
guix-dot-file-name-function 'my-guix-pdf-graph)
|
|
@end example
|
|
|
|
|
|
@node Emacs Prettify
|
|
@section Guix Prettify Mode
|
|
|
|
GNU@tie{}Guix also comes with ``guix-prettify.el''. It provides a minor
|
|
mode for abbreviating store file names by replacing hash sequences of
|
|
symbols with ``@dots{}'':
|
|
|
|
@example
|
|
/gnu/store/72f54nfp6g1hz873w8z3gfcah0h4nl9p-foo-0.1
|
|
@result{} /gnu/store/…-foo-0.1
|
|
@end example
|
|
|
|
Once you set up ``guix.el'' (@pxref{Emacs Initial Setup}), the following
|
|
commands become available:
|
|
|
|
@table @kbd
|
|
|
|
@item M-x guix-prettify-mode
|
|
Enable/disable prettifying for the current buffer.
|
|
|
|
@item M-x global-guix-prettify-mode
|
|
Enable/disable prettifying globally.
|
|
|
|
@end table
|
|
|
|
To automatically enable @code{guix-prettify-mode} globally on Emacs
|
|
start, add the following line to your init file:
|
|
|
|
@example
|
|
(global-guix-prettify-mode)
|
|
@end example
|
|
|
|
If you want to enable it only for specific major modes, add it to the
|
|
mode hooks (@pxref{Hooks,,, emacs, The GNU Emacs Manual}), for example:
|
|
|
|
@example
|
|
(add-hook 'shell-mode-hook 'guix-prettify-mode)
|
|
(add-hook 'dired-mode-hook 'guix-prettify-mode)
|
|
@end example
|
|
|
|
|
|
@node Emacs Build Log
|
|
@section Build Log Mode
|
|
|
|
GNU@tie{}Guix provides major and minor modes for highlighting build
|
|
logs. So when you have a file with a package build output---for
|
|
example, a file returned by @command{guix build --log-file @dots{}}
|
|
command (@pxref{Invoking guix build}), you may call @kbd{M-x
|
|
guix-build-log-mode} command in the buffer with this file. This major
|
|
mode highlights some lines specific to build output and provides the
|
|
following key bindings:
|
|
|
|
@table @kbd
|
|
|
|
@item M-n
|
|
Move to the next build phase.
|
|
|
|
@item M-p
|
|
Move to the previous build phase.
|
|
|
|
@item @key{TAB}
|
|
Toggle (show/hide) the body of the current build phase.
|
|
|
|
@item S-@key{TAB}
|
|
Toggle (show/hide) the bodies of all build phases.
|
|
|
|
@end table
|
|
|
|
There is also @kbd{M-x guix-build-log-minor-mode} which also provides
|
|
the same highlighting and the same key bindings as the major mode, but
|
|
prefixed with @kbd{C-c}. By default, this minor mode is enabled in
|
|
shell buffers (@pxref{Interactive Shell,,, emacs, The GNU Emacs
|
|
Manual}). If you don't like it, set
|
|
@code{guix-build-log-minor-mode-activate} to nil.
|
|
|
|
|
|
@node Emacs Completions
|
|
@section Shell Completions
|
|
|
|
Another feature that becomes available after configuring Emacs interface
|
|
(@pxref{Emacs Initial Setup}) is completing of @command{guix}
|
|
subcommands, options, packages and other things in @code{shell}
|
|
(@pxref{Interactive Shell,,, emacs, The GNU Emacs Manual}) and
|
|
@code{eshell} (@pxref{Top,,, eshell, Eshell: The Emacs Shell}).
|
|
|
|
It works the same way as other completions do. Just press @key{TAB}
|
|
when your intuition tells you.
|
|
|
|
And here are some examples, where pressing @key{TAB} may complete
|
|
something:
|
|
|
|
@itemize @w{}
|
|
|
|
@item @code{guix pa}@key{TAB}
|
|
@item @code{guix package -}@key{TAB}
|
|
@item @code{guix package --}@key{TAB}
|
|
@item @code{guix package -i gei}@key{TAB}
|
|
@item @code{guix build -L/tm}@key{TAB}
|
|
@item @code{guix build --sy}@key{TAB}
|
|
@item @code{guix build --system=i}@key{TAB}
|
|
@item @code{guix system rec}@key{TAB}
|
|
@item @code{guix lint --checkers=sy}@key{TAB}
|
|
@item @code{guix lint --checkers=synopsis,des}@key{TAB}
|
|
|
|
@end itemize
|
|
|
|
|
|
@node Emacs Development
|
|
@section Development
|
|
|
|
By default, when you open a Scheme file, @code{guix-devel-mode} will be
|
|
activated (if you don't want it, set @code{guix-devel-activate-mode} to
|
|
nil). This minor mode provides the following key bindings:
|
|
|
|
@table @kbd
|
|
|
|
@item C-c . k
|
|
Copy the name of the current Guile module into kill ring
|
|
(@code{guix-devel-copy-module-as-kill}).
|
|
|
|
@item C-c . u
|
|
Use the current Guile module. Often after opening a Scheme file, you
|
|
want to use a module it defines, so you switch to the Geiser REPL and
|
|
write @code{,use (some module)} there. You may just use this command
|
|
instead (@code{guix-devel-use-module}).
|
|
|
|
@item C-c . b
|
|
Build a package defined by the current variable definition. The
|
|
building process is run in the current Geiser REPL. If you modified the
|
|
current package definition, don't forget to reevaluate it before calling
|
|
this command---for example, with @kbd{C-M-x} (@pxref{To eval or not to
|
|
eval,,, geiser, Geiser User Manual})
|
|
(@code{guix-devel-build-package-definition}).
|
|
|
|
@item C-c . s
|
|
Build a source derivation of the package defined by the current variable
|
|
definition. This command has the same meaning as @code{guix build -S}
|
|
shell command (@pxref{Invoking guix build})
|
|
(@code{guix-devel-build-package-source}).
|
|
|
|
@item C-c . l
|
|
Lint (check) a package defined by the current variable definition
|
|
(@pxref{Invoking guix lint}) (@code{guix-devel-lint-package}).
|
|
|
|
@end table
|
|
|
|
Unluckily, there is a limitation related to long-running REPL commands.
|
|
When there is a running process in a Geiser REPL, you are not supposed
|
|
to evaluate anything in a scheme buffer, because this will ``freeze''
|
|
the REPL: it will stop producing any output (however, the evaluating
|
|
process will continue---you will just not see any progress anymore). Be
|
|
aware: even moving the point in a scheme buffer may ``break'' the REPL
|
|
if Autodoc (@pxref{Autodoc and friends,,, geiser, Geiser User Manual})
|
|
is enabled (which is the default).
|
|
|
|
So you have to postpone editing your scheme buffers until the running
|
|
evaluation will be finished in the REPL.
|
|
|
|
Alternatively, to avoid this limitation, you may just run another Geiser
|
|
REPL, and while something is being evaluated in the previous REPL, you
|
|
can continue editing a scheme file with the help of the current one.
|
|
|
|
|
|
@node Emacs Hydra
|
|
@section Hydra
|
|
|
|
The continuous integration server at @code{hydra.gnu.org} builds all
|
|
the distribution packages on the supported architectures and serves
|
|
them as substitutes (@pxref{Substitutes}). Continuous integration is
|
|
currently orchestrated by @uref{https://nixos.org/hydra/, Hydra}.
|
|
|
|
This section describes an Emacs interface to query Hydra to know the
|
|
build status of specific packages, discover recent and ongoing builds,
|
|
view build logs, and so on. This interface is mostly the same as the
|
|
``list''/``info'' interface for displaying packages and generations
|
|
(@pxref{Emacs Package Management}).
|
|
|
|
The following commands are available:
|
|
|
|
@table @kbd
|
|
|
|
@item M-x guix-hydra-latest-builds
|
|
Display latest failed or successful builds (you will be prompted for a
|
|
number of builds). With @kbd{C-u}, you will also be prompted for other
|
|
parameters (project, jobset, job and system).
|
|
|
|
@item M-x guix-hydra-queued-builds
|
|
Display scheduled or currently running builds (you will be prompted for
|
|
a number of builds).
|
|
|
|
@item M-x guix-hydra-jobsets
|
|
Display available jobsets (you will be prompted for a project).
|
|
|
|
@end table
|
|
|
|
In a list of builds you can press @kbd{L} key to display a build log of
|
|
the current build. Also both a list of builds and a list of jobsets
|
|
provide @kbd{B} key to display latest builds of the current job or
|
|
jobset (don't forget about @kbd{C-u}).
|