489 lines
14 KiB
Plaintext
489 lines
14 KiB
Plaintext
@node Emacs Interface
|
|
@section Emacs Interface
|
|
|
|
@cindex Emacs
|
|
GNU Guix comes with a visual user interface for GNU@tie{}Emacs, known
|
|
as ``guix.el''. It can be used for routine package management tasks,
|
|
pretty much like the @command{guix package} command (@pxref{Invoking
|
|
guix package}). Specifically, ``guix.el'' 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
|
|
* Initial Setup: Emacs Initial Setup. Preparing @file{~/.emacs}.
|
|
* Usage: Emacs Usage. Using the interface.
|
|
* Configuration: Emacs Configuration. Configuring the interface.
|
|
* Prettify Mode: Emacs Prettify. Abbreviating @file{/gnu/store/@dots{}} file names.
|
|
@end menu
|
|
|
|
@node Emacs Initial Setup
|
|
@subsection 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 GSD, 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.
|
|
|
|
@end itemize
|
|
|
|
When it is done, add the following into your init file (@pxref{Init
|
|
File,,, emacs, The GNU Emacs Manual}):
|
|
|
|
@example
|
|
(require 'guix-init nil t)
|
|
@end example
|
|
|
|
However there is a chance that @code{load-path} of your Emacs does not
|
|
contain a directory with ``guix.el'' (usually it is
|
|
@file{/usr/share/emacs/site-lisp/}). In that case you need to add it
|
|
before requiring (@pxref{Lisp Libraries,,, emacs, The GNU Emacs
|
|
Manual}):
|
|
|
|
@example
|
|
(add-to-list 'load-path "/path/to/directory-with-guix.el")
|
|
(require 'guix-init)
|
|
@end example
|
|
|
|
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 Usage
|
|
@subsection Usage
|
|
|
|
Once ``guix.el'' has been successfully configured, you should be able to
|
|
use commands for displaying packages and generations. This information
|
|
can be displayed in a ``list'' or ``info'' buffer.
|
|
|
|
@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.
|
|
@end menu
|
|
|
|
@node Emacs Commands
|
|
@subsubsection 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-search-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-search-params} variable.
|
|
|
|
@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
|
|
|
|
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
|
|
@subsubsection 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 C-c C-z
|
|
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
|
|
@subsubsection ``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.
|
|
@item M
|
|
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 x
|
|
Execute actions on the marked packages.
|
|
@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
|
|
@subsubsection ``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-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
|
|
guix-buffer-name-function #'guix-buffer-name-simple))
|
|
@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-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:
|
|
|
|
@table @code
|
|
@item guix-list-column-format
|
|
@itemx guix-list-column-titles
|
|
@itemx guix-list-column-value-methods
|
|
Specify the columns, their names, what and how is displayed in ``list''
|
|
buffers.
|
|
|
|
@item guix-info-displayed-params
|
|
@itemx guix-info-insert-methods
|
|
@itemx guix-info-ignore-empty-vals
|
|
@itemx guix-info-param-title-format
|
|
@itemx guix-info-multiline-prefix
|
|
@itemx guix-info-indent
|
|
@itemx guix-info-fill-column
|
|
@itemx guix-info-delimiter
|
|
Various settings for ``info'' buffers.
|
|
|
|
@end table
|
|
|
|
|
|
@node Emacs Prettify
|
|
@subsection Guix Prettify Mode
|
|
|
|
Along with ``guix.el'', GNU@tie{}Guix 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
|