1680 lines
53 KiB
Plaintext
1680 lines
53 KiB
Plaintext
\input texinfo
|
|
|
|
@setfilename emacs-guix.info
|
|
@documentencoding UTF-8
|
|
@settitle Emacs-Guix Reference Manual
|
|
|
|
@copying
|
|
This document describes Emacs-Guix, the Emacs interface for the
|
|
@uref{https://www.gnu.org/software/guix/, GNU Guix} package manager.
|
|
|
|
@quotation
|
|
Copyright @copyright{} 2014-2018 Alex Kost@*
|
|
Copyright @copyright{} 2018 Oleg Pykhalov
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3
|
|
or any later version published by the Free Software Foundation;
|
|
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
|
|
A copy of the license is available at
|
|
@url{http://www.gnu.org/licenses/fdl.html}.
|
|
|
|
@end quotation
|
|
@end copying
|
|
|
|
@dircategory Emacs
|
|
@direntry
|
|
* Emacs-Guix: (Emacs-Guix). Emacs interface for GNU Guix
|
|
@end direntry
|
|
|
|
@titlepage
|
|
@title Emacs-Guix User Manual
|
|
@author Alex Kost
|
|
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
|
|
@insertcopying
|
|
@end titlepage
|
|
|
|
@contents
|
|
|
|
@c ----------------------------------------------------------------
|
|
@node Top
|
|
@top Emacs-Guix
|
|
|
|
@insertcopying
|
|
|
|
@menu
|
|
* Introduction:: Quick overview.
|
|
* Installation:: Installing Emacs-Guix.
|
|
* Packages:: Interface for packages.
|
|
* Profiles and Generations:: Interface for profiles and their generations.
|
|
* System:: Interface for @code{operating-system} and services.
|
|
* Package Licenses:: Interface for licenses of packages.
|
|
* Popup Interface:: Magit-like interface for guix commands.
|
|
* Prettify Mode:: Abbreviating @file{/gnu/store/@dots{}} file names.
|
|
* Prettify Variables:: Split and indent Shell variables.
|
|
* Build Log Mode:: Highlighting Guix build logs.
|
|
* Completions:: Completing @command{guix} shell command.
|
|
* Development:: Highlighting and tools for Guix code.
|
|
* Hydra:: Interface for the Guix build farm.
|
|
* List/Info Interface:: Describing ``list''/''info'' buffers.
|
|
* Configuration:: Configuring Emacs-Guix.
|
|
* Miscellaneous Commands:: @kbd{M-x guix-@dots{}} uncovered by other sections.
|
|
* Help:: Help commands.
|
|
|
|
Indexes
|
|
* Concept Index:: Concepts.
|
|
* Command Index:: Commands and functions.
|
|
* Variable Index:: Variables.
|
|
@end menu
|
|
|
|
@c ----------------------------------------------------------------
|
|
@node Introduction
|
|
@chapter Introduction
|
|
|
|
Emacs-Guix (also known as ``guix.el'') provides various interfaces and
|
|
tools related to the GNU Guix package manager.
|
|
|
|
@findex guix-about
|
|
Call @kbd{M-x guix-about} to see a splash screen similar to
|
|
@kbd{M-x@tie{}about-emacs}.
|
|
|
|
Call @kbd{M-x guix-help} to get a summary of all the available
|
|
commands (@pxref{Help}).
|
|
|
|
In short, Emacs-Guix provides the following features:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Interfaces for:
|
|
|
|
@itemize @minus
|
|
@item profiles (@pxref{Profiles})
|
|
@item profile generations (@pxref{Generations})
|
|
@item packages (@pxref{Packages})
|
|
@item package locations (@pxref{Package Locations})
|
|
@item package licenses (@pxref{Package Licenses})
|
|
@item @code{operating-system} declaration (@pxref{System From File})
|
|
@item services (@pxref{Services})
|
|
@item service locations (@pxref{Service Locations})
|
|
@item @uref{https://hydra.gnu.org, Hydra build farm} (@pxref{Hydra})
|
|
@end itemize
|
|
|
|
@item
|
|
Magit-like popup interface for all guix shell commands
|
|
(@pxref{Popup Interface}).
|
|
|
|
@item
|
|
Modes to view logs of package builds (@pxref{Build Log Mode}).
|
|
|
|
@item
|
|
Minor mode to ``prettify'' store file names (@pxref{Prettify Mode}).
|
|
|
|
@item
|
|
Shell completions for all guix commands and options
|
|
(@pxref{Completions}).
|
|
|
|
@item
|
|
Minor mode with additional functionality for @code{scheme-mode} to
|
|
work with Guix Scheme files (@pxref{Development}).
|
|
@end itemize
|
|
|
|
@c ----------------------------------------------------------------
|
|
@node Installation
|
|
@chapter Installation
|
|
|
|
@cindex installation
|
|
There are several ways@footnote{It is not recommended to mix several
|
|
installations (in particular, installations from Guix and MELPA), as
|
|
it may lead to incompatibilities in the source (@code{.scm}) and
|
|
compiled (@code{.go}) Guile files.} to install Emacs-Guix:
|
|
|
|
@itemize
|
|
@item Installing using GNU Guix
|
|
@example
|
|
$ guix package -i emacs-guix
|
|
@end example
|
|
|
|
@item Installing from @uref{http://melpa.org/, MELPA}
|
|
|
|
@item Using from a git checkout
|
|
@end itemize
|
|
|
|
For the first 2 options, you are all set, so you can skip this
|
|
chapter. If you want to use Emacs-Guix from a git checkout, read
|
|
further.
|
|
|
|
@menu
|
|
* Requirements:: Required and optional dependencies.
|
|
* Using from Git:: Using without installation.
|
|
@end menu
|
|
|
|
@node Requirements
|
|
@section Requirements
|
|
|
|
Emacs-Guix depends on the following packages:
|
|
|
|
@itemize
|
|
|
|
@item
|
|
@uref{http://www.gnu.org/software/emacs/, GNU Emacs}, version 24.3 or
|
|
later.
|
|
|
|
@item
|
|
@uref{http://www.gnu.org/software/guix/, GNU Guix}, version 0.11.0 or
|
|
later. You need it for the most features of Emacs-Guix, but not for
|
|
all: Guix is not needed if you want to look at log files (@pxref{Build
|
|
Log Mode}), to ``prettify'' store file names (@pxref{Prettify Mode}),
|
|
or to receive some info from Hydra (@pxref{Hydra}).
|
|
|
|
@item
|
|
@uref{http://nongnu.org/geiser/, Geiser}, version 0.8 or later. It is
|
|
used to communicate with the Guix daemon, and to receive various info
|
|
from the Guix Guile code. So without Geiser, you can use the same
|
|
features as without Guix.
|
|
|
|
@item
|
|
@uref{https://github.com/magnars/dash.el, dash library}, version
|
|
2.11.0 or later.
|
|
|
|
@item
|
|
@uref{https://github.com/alezost/bui.el, BUI library}, version 1.1.0
|
|
or later. It is used to define various ``list''/``info'' interfaces
|
|
(to display packages, generations, licenses, etc.).
|
|
|
|
@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 required only for @kbd{M-x@tie{}guix} command (@pxref{Popup
|
|
Interface}).
|
|
|
|
@item
|
|
@uref{https://github.com/Fanael/edit-indirect, edit-indirect library},
|
|
version 0.1.4 or later. It is used only to edit synopsis/description
|
|
in @code{guix-devel-mode} (@pxref{Development}).
|
|
|
|
@end itemize
|
|
|
|
To sum up, most likely, you'll need all the above dependencies except
|
|
maybe @code{magit-popup} and @code{edit-indirect}.
|
|
|
|
@node Using from Git
|
|
@section Using from Git
|
|
|
|
You can use Emacs-Guix directly from a git checkout without any
|
|
installation.
|
|
|
|
At first, you need to clone the repository and to run
|
|
@code{autogen.sh} script (it's just a wrapper for @code{autoreconf}
|
|
command). If you don't have all dependencies installed, you may use
|
|
@file{guix.scm} file to make an environment to build Emacs-Guix
|
|
(@pxref{Invoking guix environment,,, guix, The GNU Guix Reference
|
|
Manual}):
|
|
|
|
@example
|
|
$ git clone https://github.com/alezost/guix.el.git
|
|
$ cd guix.el
|
|
$ guix environment --pure --load=guix.scm
|
|
$ ./autogen.sh
|
|
@end example
|
|
|
|
Now configure and make it (this will compile all Emacs-Lisp and Scheme
|
|
files, and will generate @file{guix-autoloads.el} file):
|
|
|
|
@example
|
|
$ ./configure
|
|
$ make
|
|
@end example
|
|
|
|
Now all you need, is to add @file{elisp} directory to the Emacs
|
|
@code{load-path} and to load the generated autoloads. This can be
|
|
done by adding the following code into your Emacs init file
|
|
(@pxref{Init File,,, emacs, The GNU Emacs Manual}):
|
|
|
|
@example
|
|
(add-to-list 'load-path "/path/to/emacs-guix/elisp")
|
|
(require 'guix-autoloads nil t)
|
|
@end example
|
|
|
|
Now, if you start Emacs, all @kbd{M-x guix-@dots{}} commands should
|
|
become available.
|
|
|
|
@node Using the Manual from Git
|
|
@subsection Using the Manual from Git
|
|
|
|
After ``make''-ing, the info manual is ready to use. You can run it,
|
|
for example, with @kbd{C-u C-h i} command (the file is
|
|
@file{doc/emacs-guix.info}). However it is not convenient. You may
|
|
want to have this manual in the top info directory along with the
|
|
other manuals. To make it possible, you need to do the following 2
|
|
steps:
|
|
|
|
@itemize
|
|
|
|
@item
|
|
At first, you need to add the doc directory to your Info path. One
|
|
way to do it is to extend INFOPATH environment variable:
|
|
|
|
@example
|
|
export INFOPATH="/path/to/emacs-guix/doc$@{INFOPATH:+:@}$INFOPATH"
|
|
@end example
|
|
|
|
Alternatively, you can adjust Info path inside Emacs, like this:
|
|
|
|
@example
|
|
(with-eval-after-load 'info
|
|
(info-initialize)
|
|
(add-to-list 'Info-directory-list "/path/to/emacs-guix/doc"))
|
|
@end example
|
|
|
|
@item
|
|
And secondly, the doc directory should contain @file{dir} file
|
|
(@pxref{Directory File,,, texinfo, The GNU Texinfo Manual}). It can
|
|
be generated simply by running the following command:
|
|
|
|
@example
|
|
make doc/dir
|
|
@end example
|
|
|
|
@end itemize
|
|
|
|
Once the above 2 steps are done, @kbd{C-h i} should display the
|
|
Emacs-Guix entry. Also you can use @kbd{M-x guix-info} command to run
|
|
the manual (@pxref{Help}).
|
|
|
|
@c ----------------------------------------------------------------
|
|
@node Packages
|
|
@chapter Packages
|
|
|
|
@cindex packages
|
|
Emacs-Guix provides a visual interface for packages where you can
|
|
perform routine package management tasks, pretty much like the
|
|
@command{guix package} command (@pxref{Invoking guix package,,, guix,
|
|
The GNU Guix Reference Manual}).
|
|
|
|
@menu
|
|
* Package Commands:: @kbd{M-x guix-@dots{}} to show packages.
|
|
* Package Keys:: Key bindings in package ``list'' and ``info'' buffers.
|
|
* Package Locations:: Interface for locations of packages.
|
|
* More Package Commands:: Other @kbd{M-x guix-@dots{}} related to packages.
|
|
@end menu
|
|
|
|
@node Package Commands
|
|
@section Package Commands
|
|
|
|
There are multiple commands to display a list of Guix packages. You
|
|
can either perform some actions in such ``package-list'' buffer, or
|
|
``describe'' package(s) in ``package-info'' buffer using
|
|
@kbd{@key{RET}}.
|
|
|
|
@findex guix-set-current-profile
|
|
The following commands use the current profile, which can be changed
|
|
globally with @kbd{M-x@tie{}guix-set-current-profile} (@pxref{Profile
|
|
Commands}). Alternatively, if you call any of the following commands
|
|
with a prefix argument (@kbd{C-u}), you will be prompted for a profile
|
|
just for that command.
|
|
|
|
@table @kbd
|
|
|
|
@findex guix-all-packages
|
|
@item M-x guix-all-packages
|
|
@findex guix-newest-packages
|
|
@itemx M-x guix-newest-packages
|
|
Display all/newest available packages.
|
|
|
|
@findex guix-installed-packages
|
|
@item M-x guix-installed-packages
|
|
@findex guix-installed-user-packages
|
|
@itemx M-x guix-installed-user-packages
|
|
@findex guix-installed-system-packages
|
|
@itemx M-x guix-installed-system-packages
|
|
Display installed packages. As explained above, @kbd{M-x
|
|
guix-installed-packages} uses an arbitrary profile that you can specify,
|
|
while the other commands display packages installed in 2 special
|
|
profiles: @file{~/.guix-profile} and @file{/run/current-system/profile}
|
|
(only on GuixSD).
|
|
|
|
@findex guix-obsolete-packages
|
|
@item M-x guix-obsolete-packages
|
|
Display obsolete or unknown packages (the packages that are installed
|
|
in a profile but cannot be found among the available packages).
|
|
|
|
@findex guix-superseded-packages
|
|
@item M-x guix-superseded-packages
|
|
Display packages that are superseded by the other packages.
|
|
|
|
@findex guix-dependent-packages
|
|
@item M-x guix-dependent-packages
|
|
Display packages that depend on the specified package(s). This
|
|
command is analogous to @code{guix refresh --list-dependent} shell
|
|
command (@pxref{Invoking guix refresh,,, guix, The GNU Guix Reference
|
|
Manual}). You'll be prompted for a package name (or multiple names,
|
|
separated by commas) and a dependency type (it should be either
|
|
``all'' or ``direct'').
|
|
|
|
@findex guix-packages-by-name
|
|
@item M-x guix-packages-by-name
|
|
Display package(s) with the specified name.
|
|
|
|
@findex guix-packages-by-license
|
|
@item M-x guix-packages-by-license
|
|
Display package(s) with the specified license.
|
|
|
|
@findex guix-packages-by-location
|
|
@item M-x guix-packages-by-location
|
|
Display package(s) located in the specified file. These files usually
|
|
have the following form: @file{gnu/packages/emacs.scm}, but don't type
|
|
them manually! Press @kbd{@key{TAB}} to complete the file name.
|
|
|
|
@findex guix-package-from-file
|
|
@item M-x guix-package-from-file
|
|
Display package that the code within the specified file evaluates to.
|
|
@xref{Invoking guix package, @code{--install-from-file},, guix, The
|
|
GNU Guix Reference Manual}, for an example of what such a file may
|
|
look like.
|
|
|
|
@findex guix-packages-from-system-config-file
|
|
@item M-x guix-packages-from-system-config-file
|
|
Display packages from the specified file with @code{operating-system}
|
|
declaration (@pxref{Using the Configuration System,,, guix, The GNU
|
|
Guix Reference Manual}).
|
|
|
|
@findex guix-search-by-regexp
|
|
@vindex guix-package-search-params
|
|
@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.
|
|
|
|
@findex guix-search-by-name
|
|
@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
|
|
|
|
@vindex guix-package-list-type
|
|
By default, these commands display each package @strong{output} on a
|
|
separate line. If you prefer to see a list of packages---i.e., a list
|
|
with a @strong{package} per line, use the following setting:
|
|
|
|
@example
|
|
(setq guix-package-list-type 'package)
|
|
@end example
|
|
|
|
@node Package Keys
|
|
@section Package Keys
|
|
|
|
@subsection List Buffer
|
|
|
|
Along with the general ``list'' keys (@pxref{List buffer}), a
|
|
``package-list'' buffer additionally provides the following key
|
|
bindings:
|
|
|
|
@table @kbd
|
|
@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 (with prefix, mark all
|
|
installed packages for upgrading).
|
|
@item x
|
|
Execute actions on the marked packages.
|
|
@item e
|
|
Edit the definition of the current package (go to its location). This
|
|
is similar to @command{guix edit} command (@pxref{Invoking guix
|
|
edit,,, guix, The GNU Guix Reference Manual}), but for opening a
|
|
package recipe in the current Emacs instance.
|
|
@item G
|
|
@cindex graph
|
|
Show graph for the current package (@pxref{Graph Configuration}).
|
|
@item z
|
|
Show package size (@pxref{Invoking guix size,,, guix, The GNU Guix
|
|
Reference Manual}).
|
|
@item L
|
|
Lint the current package (@pxref{Invoking guix lint,,, guix, The GNU
|
|
Guix Reference Manual}). With prefix argument, you'll be prompted for
|
|
checker names.
|
|
@item B
|
|
Display latest builds of the current package (@pxref{Hydra}).
|
|
@end table
|
|
|
|
@subsection Info Buffer
|
|
|
|
Similarly, ``package-info'' buffer provides the following key bindings:
|
|
|
|
@table @kbd
|
|
@item i
|
|
Install the current package.
|
|
@item d
|
|
Delete the current package.
|
|
@item U
|
|
Upgrade the current package.
|
|
@item e
|
|
Go to the package definition.
|
|
@item G
|
|
Show package graph.
|
|
@item z
|
|
Show package size.
|
|
@item L
|
|
Lint the package.
|
|
@end table
|
|
|
|
@node Package Locations
|
|
@section Package Locations
|
|
|
|
@cindex package locations
|
|
As you know, package definitions are placed in Guile files. The
|
|
following commands should help you not get lost in these @dfn{package
|
|
locations}:
|
|
|
|
@table @kbd
|
|
|
|
@findex guix-package-locations
|
|
@item M-x guix-package-locations
|
|
Display a list of files with package definitions. You can press @kbd{P}
|
|
or @kbd{@key{RET}} there to display packages placed in the current file in
|
|
the same way as @kbd{M-x@tie{}guix-packages-by-location} would do
|
|
(@pxref{Package Commands}). Note that when the point is on a location
|
|
button, @kbd{@key{RET}} will open this location file.
|
|
|
|
@findex guix-find-package-location-file
|
|
@item M-x guix-find-package-location-file
|
|
Open a file with package definitions (press @kbd{@key{TAB}} to choose a
|
|
file from the completion list).
|
|
|
|
@findex guix-find-package-definition
|
|
@item M-x guix-find-package-definition
|
|
@findex guix-edit
|
|
@itemx M-x guix-edit
|
|
Find location of a specified package. This is an Emacs analog of
|
|
@command{guix edit} command (@pxref{Invoking guix edit,,, guix, The
|
|
GNU Guix Reference Manual}). As with
|
|
@kbd{M-x@tie{}guix-packages-by-name}, you can press @kbd{@key{TAB}} to
|
|
complete a package name.
|
|
|
|
@end table
|
|
|
|
@vindex guix-read-package-name-function
|
|
By default, when you should specify a package name (for example, after
|
|
@kbd{M-x guix-edit}), you will be prompted for it in the minibuffer,
|
|
but you can configure Emacs-Guix to use a package name at the current
|
|
point position (unless @kbd{C-u} is used):
|
|
|
|
@example
|
|
(setq guix-read-package-name-function 'guix-read-package-name-at-point)
|
|
@end example
|
|
|
|
@node More Package Commands
|
|
@section More Package Commands
|
|
|
|
And some more commands related to packages:
|
|
|
|
@table @kbd
|
|
|
|
@findex guix-number-of-packages
|
|
@item M-x guix-number-of-packages
|
|
This command just displays a message (in the minibuffer) with the
|
|
number of available packages. Along with the default Guix packages,
|
|
this number includes the packages from @code{GUIX_PACKAGE_PATH}
|
|
environment variable (@pxref{Package Modules,,, guix, The GNU Guix
|
|
Reference Manual}).
|
|
|
|
@cindex graph
|
|
@findex guix-package-graph
|
|
@item M-x guix-package-graph
|
|
Show a package graph. You'll be prompted for a package name, graph
|
|
backend and graph node type (everything can be completed with
|
|
@kbd{@key{TAB}} key). @xref{Graph Configuration}, if you want to set
|
|
an external graph viewer.
|
|
|
|
@findex guix-package-size
|
|
@item M-x guix-package-size
|
|
Show a package size (@pxref{Invoking guix size,,, guix, The GNU Guix
|
|
Reference Manual}). You'll be prompted for a package name and a size
|
|
type (it should be either ``text'' or ``image'').
|
|
|
|
@findex guix-package-lint
|
|
@item M-x guix-package-lint
|
|
Lint a package (@pxref{Invoking guix lint,,, guix, The GNU Guix
|
|
Reference Manual}). You'll be prompted for a package name. With
|
|
prefix argument, you'll be also prompted for checker names.
|
|
|
|
@end table
|
|
|
|
@c ----------------------------------------------------------------
|
|
@node Profiles and Generations
|
|
@chapter Profiles and Generations
|
|
|
|
As you know, packages are installed in @dfn{profiles}. The default
|
|
user profile is @file{~/.guix-profile} (actually it is a symlink to
|
|
the real profile) but you can also install packages to non-standard
|
|
profiles (using @code{guix package --profile=@dots{}}).
|
|
|
|
Profiles have @dfn{generations}. They appear whenever you perform any
|
|
profile action (installing/removing packages). These generations are
|
|
just symlinks to the previous versions of profile, so you can easily
|
|
roll-back to any previous generation.
|
|
|
|
As you may guess, Emacs-Guix provides an interface for profiles and
|
|
their generations, where you can look at the packages from the old
|
|
generations, switch to any generation, delete generations, etc.
|
|
|
|
@menu
|
|
* Profiles:: Interface for profiles.
|
|
* Generations:: Interface for generations.
|
|
@end menu
|
|
|
|
@node Profiles
|
|
@section Profiles
|
|
|
|
@cindex profiles
|
|
If you manage multiple Guix profiles, this section is for you.
|
|
@kbd{M-x guix-profiles} is the entry point to display profiles. There
|
|
you can look at the profile generations, installed packages and more.
|
|
Read further for details.
|
|
|
|
@menu
|
|
* Profile Commands:: @kbd{M-x guix-profiles} and friends.
|
|
* Profile Keys:: Key bindings in profile ``list'' buffer.
|
|
@end menu
|
|
|
|
@node Profile Commands
|
|
@subsection Profile Commands
|
|
|
|
@table @kbd
|
|
|
|
@findex guix-profiles
|
|
@vindex guix-profiles
|
|
@item M-x guix-profiles
|
|
Show a list of available Guix profiles. By default, it displays only
|
|
the default user profile and system profile (only on GuixSD). But if
|
|
you use multiple profiles, you can add them to this list by setting
|
|
@code{guix-profiles} variable, for example, like this:
|
|
|
|
@example
|
|
(with-eval-after-load 'guix-ui-profile
|
|
(setq guix-profiles
|
|
(append '("/path/to/my-profile1"
|
|
"/path/to/my-profile2")
|
|
guix-profiles)))
|
|
@end example
|
|
|
|
The ``profile-list'' buffer provides some keys to work with profiles
|
|
(@pxref{Profile Keys}), but also there are the following standalone
|
|
profile commands that can be called outside this buffer.
|
|
|
|
@vindex guix-current-profile
|
|
@findex guix-set-current-profile
|
|
@item M-x guix-set-current-profile
|
|
Set the current profile (@code{guix-current-profile} variable) to the
|
|
specified one. The current profile is used by the package commands
|
|
(@pxref{Package Commands}) to check what package is installed in this
|
|
profile, and by generation commands (@pxref{Generation Commands}).
|
|
|
|
@findex guix-apply-manifest
|
|
@item M-x guix-apply-manifest
|
|
Apply a manifest file to the current profile or a specified profile,
|
|
if the prefix argument is used. This has the same meaning as
|
|
@code{--manifest} option (@pxref{Invoking guix package,,, guix, The
|
|
GNU Guix Reference Manual}).
|
|
|
|
@end table
|
|
|
|
@node Profile Keys
|
|
@subsection Profile Keys
|
|
|
|
Along with the general ``list'' keys (@pxref{List buffer}), a
|
|
``profile-list'' buffer (displayed by @kbd{M-x guix-profiles})
|
|
additionally provides the following bindings:
|
|
|
|
@table @kbd
|
|
@item P
|
|
Display packages installed in profile at point.
|
|
@item G
|
|
Display generations of profile at point.
|
|
@item E
|
|
Display ``search paths'' environment variables for the marked
|
|
profiles, or the current profile if nothing is marked. This command
|
|
is analogous to @code{guix package --search-paths} shell command
|
|
(@pxref{Invoking guix package,,, guix, The GNU Guix Reference
|
|
Manual}).
|
|
@item c
|
|
Make profile at point the current profile for the package commands
|
|
(@pxref{Packages}).
|
|
@item M
|
|
Apply manifest from a specified file to the profile at point.
|
|
@end table
|
|
|
|
@node Generations
|
|
@section Generations
|
|
|
|
@cindex generations
|
|
Each Guix profile may have multiple generations and Emacs-Guix allows
|
|
you to display these generations, to switch to a particular
|
|
generation, to look at the packages installed in it and to compare 2
|
|
generations.
|
|
|
|
@menu
|
|
* Generation Commands:: @kbd{M-x guix-@dots{}} to show profile generations.
|
|
* Generation Keys:: Key bindings in generation ``list'' buffer.
|
|
@end menu
|
|
|
|
@node Generation Commands
|
|
@subsection Generation Commands
|
|
|
|
As with commands for displaying packages (@pxref{Package Commands}),
|
|
commands for displaying generations also use the current profile and
|
|
can be called with a prefix argument.
|
|
|
|
@table @kbd
|
|
|
|
@findex guix-generations
|
|
@item M-x guix-generations
|
|
List all the generations.
|
|
|
|
@findex guix-last-generations
|
|
@item M-x guix-last-generations
|
|
List the @var{N} last generations. You will be prompted for the number
|
|
of generations.
|
|
|
|
@findex guix-generations-by-time
|
|
@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
|
|
|
|
If you use GuixSD, you may also look at the system generations using
|
|
the similar commands (@pxref{System Commands}).
|
|
|
|
@node Generation Keys
|
|
@subsection Generation Keys
|
|
|
|
Along with the general ``list'' keys (@pxref{List buffer}), a
|
|
``generation-list'' buffer additionally provides the following
|
|
bindings:
|
|
|
|
@table @kbd
|
|
@item P
|
|
Display packages installed in the current generation.
|
|
@item E
|
|
Display ``search paths'' environment variables for the marked
|
|
generations. This command is similar to the one for a list of
|
|
profiles (@pxref{Profiles}).
|
|
@item c
|
|
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 =
|
|
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
|
|
|
|
@c ----------------------------------------------------------------
|
|
@node System
|
|
@chapter System
|
|
|
|
This chapter describes Emacs-Guix features related to GuixSD, in
|
|
particular:
|
|
|
|
@itemize
|
|
@item interface for system configuration file;
|
|
@item interface for system services;
|
|
@item commands to display system profile and generations.
|
|
@end itemize
|
|
|
|
@menu
|
|
* System From File:: Interface for @code{operating-system} declaration.
|
|
* Services:: Interface for system services.
|
|
* System Commands:: Other @kbd{M-x guix-@dots{}} related to system.
|
|
@end menu
|
|
|
|
@node System From File
|
|
@section System From File
|
|
|
|
@cindex system
|
|
Your system configuration file (for GuixSD) contains
|
|
@code{operating-system} declaration (@pxref{operating-system
|
|
Reference,,, guix, The GNU Guix Reference Manual}).
|
|
|
|
And Emacs-Guix provides an interface for this @code{operating-system},
|
|
where you can look at the packages, services, initrd modules that this
|
|
system will install and some other stuff.
|
|
|
|
@table @kbd
|
|
|
|
@findex guix-system-from-file
|
|
@item guix-system-from-file
|
|
Find your system configuration file and look at the system it
|
|
provides.
|
|
|
|
@end table
|
|
|
|
@node Services
|
|
@section Services
|
|
|
|
@cindex services
|
|
If you use GuixSD, you may have a wish to become more familiar with
|
|
the system services (@pxref{Services,,, guix, The GNU Guix Reference
|
|
Manual}). Emacs-Guix provides several commands to display these
|
|
services.
|
|
|
|
@menu
|
|
* Service Commands:: @kbd{M-x guix-@dots{}} to show services.
|
|
* Service Locations:: Interface for locations of services.
|
|
@end menu
|
|
|
|
@node Service Commands
|
|
@subsection Service Commands
|
|
|
|
The interface for services is very similar to the interface for
|
|
packages (@pxref{Packages}). The following commands allows you to
|
|
look at the GuixSD services.
|
|
|
|
@table @kbd
|
|
|
|
@findex guix-all-services
|
|
@item M-x guix-all-services
|
|
Display all available services.
|
|
|
|
@findex guix-default-services
|
|
@item M-x guix-default-services
|
|
Display services from @code{%base-services} (@pxref{Base Services,,,
|
|
guix, The GNU Guix Reference Manual}) or @code{%desktop-services}
|
|
(@pxref{Desktop Services,,, guix, The GNU Guix Reference Manual}).
|
|
You will be prompted in the minibuffer for the variable name
|
|
(completions available).
|
|
|
|
@findex guix-services-by-name
|
|
@item M-x guix-services-by-name
|
|
Display service(s) with the specified name.
|
|
|
|
@findex guix-services-by-regexp
|
|
@vindex guix-service-search-params
|
|
@item M-x guix-services-by-regexp
|
|
Search for services by a specified regexp. By default, ``name'' and
|
|
``description'' of the services will be searched. This can be changed
|
|
by modifying @code{guix-service-search-params} variable.
|
|
|
|
@findex guix-services-by-location
|
|
@item M-x guix-services-by-location
|
|
Display service(s) located in the specified file.
|
|
|
|
@findex guix-services-from-system-config-file
|
|
@item M-x guix-services-from-system-config-file
|
|
Display services from the specified file with @code{operating-system}
|
|
declaration.
|
|
|
|
@end table
|
|
|
|
@node Service Locations
|
|
@subsection Service Locations
|
|
|
|
@cindex service Locations
|
|
Similarly to the package locations (@pxref{Package Locations}), you
|
|
may look at the service locations:
|
|
|
|
@table @kbd
|
|
|
|
@findex guix-service-locations
|
|
@item M-x guix-service-locations
|
|
Display a list of files with service locations. Press @kbd{@key{RET}}
|
|
there to display services placed in the current location.
|
|
|
|
@findex guix-find-service-location-file
|
|
@item M-x guix-find-service-location-file
|
|
Open a file with service definitions (press @kbd{@key{TAB}} to choose
|
|
the file from a completion list).
|
|
|
|
@findex guix-find-service-definition
|
|
@item M-x guix-find-service-definition
|
|
Go to the service location---i.e., open a file with the specified
|
|
service and move the point to its definition.
|
|
|
|
@end table
|
|
|
|
@node System Commands
|
|
@section System Commands
|
|
|
|
Along with the commands for services and @code{operating-system},
|
|
there are commands to look at the system profile
|
|
(@file{/var/guix/profiles/system}), its generations and packages
|
|
installed in it.
|
|
|
|
@table @kbd
|
|
|
|
@findex guix-system-profile
|
|
@item M-x guix-system-profile
|
|
Display ``info'' interface for the system profile.
|
|
|
|
@findex guix-system-generations
|
|
@item M-x guix-system-generations
|
|
@findex guix-last-system-generations
|
|
@itemx M-x guix-last-system-generations
|
|
@findex guix-system-generations-by-time
|
|
@itemx M-x guix-system-generations-by-time
|
|
Display generations of the system profile. These commands have the
|
|
same meaning as the usual generation commands (@pxref{Generation
|
|
Commands}).
|
|
|
|
@findex guix-installed-system-packages
|
|
@item M-x guix-installed-system-packages
|
|
Display packages installed in the system profile.
|
|
|
|
@findex guix-packages-from-system-config-file
|
|
@item M-x guix-packages-from-system-config-file
|
|
@findex guix-services-from-system-config-file
|
|
@item M-x guix-services-from-system-config-file
|
|
Display packages/services from the specified system configuration
|
|
file. You can also look at these packages/services from the
|
|
``system-info'' interface (@pxref{System From File}).
|
|
|
|
@end table
|
|
|
|
@c ----------------------------------------------------------------
|
|
@node Package Licenses
|
|
@chapter Package Licenses
|
|
|
|
@cindex package licenses
|
|
If you want to browse the URL of a particular license, or to look at a
|
|
list of licenses, you may use the following commands:
|
|
|
|
@table @kbd
|
|
|
|
@findex guix-browse-license-url
|
|
@item M-x guix-browse-license-url
|
|
Choose a license from a completion list to browse its URL using
|
|
@code{browse-url} function (@pxref{Browse-URL,,, emacs, The GNU Emacs
|
|
Manual}).
|
|
|
|
@findex guix-licenses
|
|
@item M-x guix-licenses
|
|
Display a list of available licenses. You can press @kbd{P} key
|
|
there to display packages with this license in the same way as
|
|
@kbd{M-x@tie{}guix-packages-by-license} would do (@pxref{Package
|
|
Commands}).
|
|
|
|
@findex guix-find-license-location-file
|
|
@item M-x guix-find-license-location-file
|
|
Open @file{@dots{}/guix/licenses.scm} file.
|
|
|
|
@findex guix-find-license-definition
|
|
@item M-x guix-find-license-definition
|
|
Open @file{@dots{}/guix/licenses.scm} and move to the specified license.
|
|
|
|
@end table
|
|
|
|
@c ----------------------------------------------------------------
|
|
@node Popup Interface
|
|
@chapter 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.
|
|
|
|
@findex guix
|
|
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 @kbd{@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
|
|
@vindex guix-run-in-shell-function
|
|
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
|
|
|
|
@cindex graph
|
|
Several commands (@command{guix graph}, @command{guix system
|
|
shepherd-graph} and @command{guix system extension-graph}) also have a
|
|
``View graph'' action, which allows you to view a generated graph
|
|
(@pxref{Graph Configuration}).
|
|
|
|
@c ----------------------------------------------------------------
|
|
@node Prettify Mode
|
|
@chapter Guix Prettify Mode
|
|
|
|
Emacs-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
|
|
|
|
@table @kbd
|
|
|
|
@findex guix-prettify-mode
|
|
@item M-x guix-prettify-mode
|
|
Enable/disable prettifying for the current buffer.
|
|
|
|
@findex global-guix-prettify-mode
|
|
@item M-x global-guix-prettify-mode
|
|
Enable/disable prettifying globally.
|
|
|
|
@end table
|
|
|
|
If you wish to enable @code{global-guix-prettify-mode} automatically
|
|
on Emacs start, you may do it by adding the following line to your
|
|
Emacs init file:
|
|
|
|
@example
|
|
(add-hook 'after-init-hook '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
|
|
|
|
@c ----------------------------------------------------------------
|
|
@node Prettify Variables
|
|
@chapter Guix Environment Variables Mode
|
|
|
|
Emacs-Guix provides a major mode based on @code{sh-mode} for
|
|
prettifying @file{environment-variables} and @file{profile} files. It
|
|
will split all exported variables and separate them with a newline.
|
|
All @file{/tmp/guix-build-*-*.drv-*/environment-variables} and
|
|
@file{/etc/profile} will be prettified by default.
|
|
|
|
@vindex guix-env-var-enable-formatting
|
|
If you want to disable this prettifying, set
|
|
@code{guix-env-var-enable-formatting} variable to nil.
|
|
|
|
You could also directly use @code{guix-env-var-prettify-buffer} to
|
|
prettify the current buffer without changing its major mode and
|
|
@code{guix-env-var-prettify-variable} to prettify a variable at
|
|
current line.
|
|
|
|
@table @kbd
|
|
|
|
@findex guix-env-var-mode
|
|
@item M-x guix-env-var-mode
|
|
Enable/disable prettifying for the current buffer.
|
|
|
|
@findex guix-env-var-prettify-buffer
|
|
@item M-x guix-env-var-prettify-buffer
|
|
Prettify current buffer without switching to @code{guix-env-var-mode}.
|
|
|
|
@findex guix-env-var-prettify-variable
|
|
@item M-x guix-env-var-prettify-variable
|
|
Prettify variable assignment at current line.
|
|
|
|
@end table
|
|
|
|
@c ----------------------------------------------------------------
|
|
@node Build Log Mode
|
|
@chapter Build Log Mode
|
|
|
|
@cindex build log
|
|
@findex guix-build-log-mode
|
|
Emacs-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,,, guix, The GNU Guix Reference Manual}),
|
|
you may call @kbd{M-x@tie{}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
|
|
|
|
@findex guix-build-log-minor-mode
|
|
There is also @kbd{M-x@tie{}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}. You may find this minor mode
|
|
useful for shell buffers (@pxref{Interactive Shell,,, emacs, The GNU
|
|
Emacs Manual}). It can be enabled there like this:
|
|
|
|
@example
|
|
(add-hook 'shell-mode-hook 'guix-build-log-minor-mode)
|
|
@end example
|
|
|
|
@c ----------------------------------------------------------------
|
|
@node Completions
|
|
@chapter Shell Completions
|
|
|
|
@cindex shell
|
|
@cindex completions
|
|
Another available feature is completing @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}) buffers.
|
|
|
|
It works the same way as other completions do. Just press
|
|
@kbd{@key{TAB}} when your intuition tells you.
|
|
|
|
And here are some examples, where pressing @kbd{@key{TAB}} may
|
|
complete something:
|
|
|
|
@itemize @w{}
|
|
|
|
@item @code{guix pa}@kbd{@key{TAB}}
|
|
@item @code{guix package -}@kbd{@key{TAB}}
|
|
@item @code{guix package --}@kbd{@key{TAB}}
|
|
@item @code{guix package -i gei}@kbd{@key{TAB}}
|
|
@item @code{guix build -L/tm}@kbd{@key{TAB}}
|
|
@item @code{guix build --sy}@kbd{@key{TAB}}
|
|
@item @code{guix build --system=i}@kbd{@key{TAB}}
|
|
@item @code{guix system rec}@kbd{@key{TAB}}
|
|
@item @code{guix lint --checkers=sy}@kbd{@key{TAB}}
|
|
@item @code{guix lint --checkers=synopsis,des}@kbd{@key{TAB}}
|
|
@item @code{guix graph --backend=}@kbd{@key{TAB}}
|
|
|
|
@end itemize
|
|
|
|
@c ----------------------------------------------------------------
|
|
@node Development
|
|
@chapter Development
|
|
|
|
@findex guix-devel-mode
|
|
If you often work with Guix package files, you may want to see some
|
|
highlighting and to have some indentation rules specific for Guix
|
|
keywords. There is a minor mode to help
|
|
you---@kbd{M-x@tie{}guix-devel-mode}. It can be enabled in Scheme
|
|
buffers like this:
|
|
|
|
@example
|
|
(add-hook 'scheme-mode-hook 'guix-devel-mode)
|
|
@end example
|
|
|
|
Along with highlighting and indentation, 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,,, guix, The GNU
|
|
Guix Reference Manual}) (@code{guix-devel-build-package-source}).
|
|
|
|
@item C-c . d
|
|
Download a source of the package defined by the current variable
|
|
definition. This command is the same as running @code{guix download}
|
|
shell command on the package source (@pxref{Invoking guix download,,,
|
|
guix, The GNU Guix Reference Manual})
|
|
(@code{guix-devel-download-package-source}).
|
|
|
|
@item C-c . l
|
|
Lint (check) a package defined by the current variable definition
|
|
(@pxref{Invoking guix lint,,, guix, The GNU Guix Reference Manual})
|
|
(@code{guix-devel-lint-package}).
|
|
|
|
@item C-c . '
|
|
Edit @code{description} or @code{synopsis} of the current package in
|
|
@code{texinfo-mode} (@code{guix-devel-code-block-edit}).
|
|
|
|
@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.
|
|
|
|
@cindex ffap
|
|
To find a patch file at point with @kbd{M-x ffap} command, you may use:
|
|
|
|
@example
|
|
(add-to-list 'ffap-alist '("\\.patch" . guix-devel-ffap-patch))
|
|
@end example
|
|
|
|
@c ----------------------------------------------------------------
|
|
@node Hydra
|
|
@chapter Hydra
|
|
|
|
@cindex 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,,, guix, The GNU Guix
|
|
Reference Manual}). 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
|
|
(@pxref{Packages}), generations (@pxref{Generations}) and other
|
|
things.
|
|
|
|
The following commands are available:
|
|
|
|
@table @kbd
|
|
|
|
@findex guix-hydra-latest-builds
|
|
@vindex guix-hydra-number-of-builds
|
|
@item M-x guix-hydra-latest-builds
|
|
Display the latest failed or successful builds. With @kbd{C-u}, you
|
|
will be prompted for the number of builds and other parameters
|
|
(project, jobset, job and system). If you want to change the default
|
|
number of builds, set @code{guix-hydra-number-of-builds} variable.
|
|
|
|
@findex guix-hydra-queued-builds
|
|
@item M-x guix-hydra-queued-builds
|
|
Display scheduled or currently running builds.
|
|
|
|
@findex guix-hydra-jobsets
|
|
@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}).
|
|
|
|
@c ----------------------------------------------------------------
|
|
@node List/Info Interface
|
|
@chapter List/Info Interface
|
|
|
|
As you probably already know, there are multiple commands that display
|
|
various lists (of packages, licenses, etc.). This is so-called
|
|
``list'' interface. Also you can get the same data displayed in
|
|
``info'' interface. This chapter describes these interfaces.
|
|
|
|
@menu
|
|
* List/Info Keys:: Common keys for both interfaces.
|
|
* ``List'' buffer: List buffer. List-like interface.
|
|
* ``Info'' buffer: Info buffer. Help-like interface.
|
|
@end menu
|
|
|
|
@node List/Info Keys
|
|
@section List/Info Keys
|
|
|
|
The following keys are available for both ``list'' and ``info''
|
|
interfaces:
|
|
|
|
@table @kbd
|
|
@item h
|
|
Show ``hint'' (a message with available key bindings).
|
|
|
|
@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 (receive it again) the currently
|
|
displayed data and redisplay it.
|
|
|
|
@item R
|
|
Redisplay current buffer (without updating the data).
|
|
|
|
@item ?
|
|
Describe current mode.
|
|
|
|
@end table
|
|
|
|
Also some buffers provide the following keys:
|
|
|
|
@table @kbd
|
|
|
|
@item M
|
|
Apply manifest file to the current profile (@pxref{Miscellaneous
|
|
Commands, @code{guix-apply-manifest}}).
|
|
|
|
@item C-c C-z
|
|
@cindex Guix REPL
|
|
Go to the Guix REPL (@pxref{The REPL,,, geiser, Geiser User Manual}).
|
|
|
|
@end table
|
|
|
|
@emph{Hint:} If you need several ``list'' or ``info'' buffers, you can
|
|
simply @kbd{M-x@tie{}clone-buffer} them, and each buffer will have its
|
|
own history.
|
|
|
|
@node List buffer
|
|
@section ``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}).
|
|
|
|
And here are the default key bindings (some of them may be rebound
|
|
to more specific commands):
|
|
|
|
@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 @key{RET}
|
|
@itemx i
|
|
Display ``info'' interface for the marked entries (or the current
|
|
entry if nothing is marked).
|
|
@item s
|
|
Sort entries by column specified by the prefix argument (counting from
|
|
0).
|
|
@end table
|
|
|
|
@node Info buffer
|
|
@section ``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}),
|
|
or rather @code{Custom-mode} (@pxref{Easy Customization,,, emacs, The
|
|
GNU Emacs Manual}), as it is full of various buttons that can be used
|
|
to open files, browse URLs, do some actions (like installing/removing
|
|
packages), etc.
|
|
|
|
@cindex buttons
|
|
As always, you may use @kbd{@key{TAB}} / @kbd{S-@key{TAB}} to move
|
|
between buttons and @kbd{@key{RET}} to press a button, or you can just
|
|
use mouse (@pxref{Mouse References,,, emacs, The GNU Emacs Manual}).
|
|
|
|
Finally, you can copy any button label (a link to an URL or a file) by
|
|
pressing @kbd{c} on a button.
|
|
|
|
@c ----------------------------------------------------------------
|
|
@node Configuration
|
|
@chapter Configuration
|
|
|
|
@cindex customization group
|
|
There are many variables you can modify to change the appearance or
|
|
behavior of Emacs-Guix. 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 and faces---@kbd{M-x@tie{}customize-group @key{RET} guix}.
|
|
|
|
@vindex guix-ENTRY-TYPE-BUFFER-TYPE-format
|
|
If you wish to change the appearance of ``list'' / ``info'' buffers,
|
|
look at @code{guix-ENTRY-TYPE-BUFFER-TYPE-format} variables
|
|
(@dfn{ENTRY-TYPE} can be @code{package}, @code{output},
|
|
@code{profile}, @code{generation} @code{system-generation},
|
|
@code{license}, @code{location}, @code{hydra-build},
|
|
@code{hydra-jobset}; @dfn{BUFFER-TYPE} is either @code{list} or
|
|
@code{info}).
|
|
|
|
@menu
|
|
* Graph Configuration:: Set external viewer for graphs, etc.
|
|
* Guile and Build Options:: Settings for Guix REPL, Guile, etc.
|
|
* Buffer Names:: Names of Guix buffers.
|
|
* Keymaps:: Configuring key bindings.
|
|
* Miscellaneous Configuration:: Other configuration variables.
|
|
@end menu
|
|
|
|
@node Graph Configuration
|
|
@section Graph Configuration
|
|
|
|
@cindex graph
|
|
Some commands may display a graph image. Currently Guix provides 2
|
|
graph backends (@pxref{Invoking guix graph,,, guix, The GNU Guix
|
|
Reference Manual}):
|
|
|
|
@table @code
|
|
@item d3js
|
|
Such graph will be displayed in your browser using @code{browse-url}
|
|
function (@pxref{Browse-URL,,, emacs, The GNU Emacs Manual}).
|
|
@item graphviz
|
|
Such graph will be displayed inside Emacs by default, but this can be
|
|
configured @dots{}
|
|
@end table
|
|
|
|
@vindex guix-find-file-function
|
|
@dots{} Graphs are opened using @code{guix-find-file-function}, so if
|
|
you want to use an external viewer, you need to set this variable.
|
|
Probably the easiest way to set an external viewer is to use a
|
|
functionality provided by the Org Mode. For example, if you want to
|
|
open the generated graphs (PNG files) with @code{sxiv} image viewer,
|
|
you can do it like this:
|
|
|
|
@example
|
|
(setq guix-find-file-function 'org-open-file)
|
|
(add-to-list 'org-file-apps '("\\.png\\'" . "sxiv %s"))
|
|
@end example
|
|
|
|
Now some deeper details and configuration options.
|
|
|
|
@vindex guix-dot-program
|
|
@vindex guix-dot-default-arguments
|
|
@vindex guix-dot-file-name-function
|
|
The @code{graphviz} graph is converted into an image file using
|
|
@command{dot} command specified by @code{guix-dot-program} and
|
|
@code{guix-dot-default-arguments} variables. By default, a PNG file is
|
|
generated and saved as @file{/tmp/emacs-guix-XXXXXX/graph-XXXXXX.png}.
|
|
If you want to change an output format (for example, into PDF), you also
|
|
need to change @code{guix-dot-file-name-function} (to make @code{.pdf}
|
|
extension of the output file). This can be done 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 Guile and Build Options
|
|
@section Guile and Build Options
|
|
|
|
@table @code
|
|
|
|
@vindex guix-guile-program
|
|
@item guix-guile-program
|
|
If you have some special needs for starting a Guile process, you may
|
|
set this variable. For example, if you use Guix via
|
|
@file{pre-inst-env} script (@pxref{Running Guix Before It Is
|
|
Installed,,, guix, The GNU Guix Reference Manual}), you may customize
|
|
this variable like this:
|
|
|
|
@example
|
|
(setq guix-guile-program
|
|
'("/path/to/guix/pre-inst-env" "guile" "--no-auto-compile"))
|
|
@end example
|
|
|
|
Note: @code{--no-auto-compile} flag is recommended as auto-compilation
|
|
of a ``dirty'' tree may take a very long time and may even lead to
|
|
unpredictable errors.
|
|
|
|
@vindex guix-use-substitutes
|
|
@item guix-use-substitutes
|
|
Has the same meaning as @code{--no-substitutes} option
|
|
(@pxref{Invoking guix build,,, guix, The GNU Guix Reference
|
|
Manual})---i.e., when non-nil, substitutes are enabled.
|
|
|
|
@vindex guix-dry-run
|
|
@item guix-dry-run
|
|
Has the same meaning as @code{--dry-run} option (@pxref{Invoking guix
|
|
build,,, guix, The GNU Guix Reference Manual})---i.e., when non-nil,
|
|
do not build the derivations.
|
|
|
|
@cindex Guix REPL
|
|
@vindex guix-repl-use-server
|
|
@item guix-repl-use-server
|
|
By default, along with the main Guix REPL, an additional (internal)
|
|
REPL is started. This allows you to display packages, generations and
|
|
to receive other info from the Scheme side, while there is some active
|
|
process in the main Guix REPL (e.g., while downloading or building
|
|
packages). If you don't want to have the second REPL, set this
|
|
variable to nil.
|
|
|
|
@vindex guix-repl-use-latest
|
|
@item guix-repl-use-latest
|
|
Set this variable to nil, if you don't want to use the latest Guix
|
|
code received with @code{guix pull} command (@pxref{Invoking guix
|
|
pull,,, guix, The GNU Guix Reference Manual}).
|
|
|
|
@end table
|
|
|
|
@node Buffer Names
|
|
@section Buffer Names
|
|
|
|
Default names of various Emacs-Guix buffers (``*Guix@tie{}@dots{}*'')
|
|
may be changed with the following variables:
|
|
|
|
@table @code
|
|
|
|
@vindex guix-ENTRY-TYPE-BUFFER-TYPE-buffer-name
|
|
@item guix-ENTRY-TYPE-BUFFER-TYPE-buffer-name
|
|
@xref{Configuration}, for the meaning of @code{ENTRY-TYPE} and
|
|
@code{BUFFER-TYPE}.
|
|
|
|
@vindex guix-ui-buffer-name-function
|
|
@item guix-ui-buffer-name-function
|
|
By default, many Guix buffers contain profile name (e.g., @code{*Guix
|
|
Packages: <profile>*}). This variable allows you to control how this
|
|
profile name is displayed. If you want to remove profile name from
|
|
the buffer names, you can do it like this:
|
|
|
|
@example
|
|
(setq guix-ui-buffer-name-function 'guix-ui-buffer-name-simple)
|
|
@end example
|
|
|
|
@vindex guix-repl-buffer-name
|
|
@item guix-repl-buffer-name
|
|
|
|
@vindex guix-internal-repl-buffer-name
|
|
@item guix-internal-repl-buffer-name
|
|
|
|
@vindex guix-search-paths-buffer-name
|
|
@item guix-search-paths-buffer-name
|
|
|
|
@vindex guix-help-buffer-name
|
|
@item guix-help-buffer-name
|
|
|
|
@vindex guix-about-buffer-name
|
|
@item guix-about-buffer-name
|
|
|
|
@end table
|
|
|
|
@node Keymaps
|
|
@section Keymaps
|
|
|
|
If you want to change default key bindings, look at the following
|
|
keymaps (@pxref{Init Rebinding,,, emacs, The GNU Emacs Manual}):
|
|
|
|
@table @code
|
|
|
|
@vindex guix-ui-map
|
|
@item guix-ui-map
|
|
Parent keymap with general keys for buffers used for Guix package
|
|
management.
|
|
|
|
@vindex guix-ENTRY-TYPE-BUFFER-TYPE-mode-map
|
|
@item guix-ENTRY-TYPE-BUFFER-TYPE-mode-map
|
|
@xref{Configuration}, for the meaning of @code{ENTRY-TYPE} and
|
|
@code{BUFFER-TYPE}.
|
|
|
|
@vindex guix-build-log-common-map
|
|
@item guix-build-log-common-map
|
|
|
|
@vindex guix-build-log-mode-map
|
|
@item guix-build-log-mode-map
|
|
|
|
@vindex guix-build-log-minor-mode-map
|
|
@item guix-build-log-minor-mode-map
|
|
|
|
@vindex guix-devel-keys-map
|
|
@item guix-devel-keys-map
|
|
|
|
@vindex guix-devel-mode-map
|
|
@item guix-devel-mode-map
|
|
|
|
@end table
|
|
|
|
@node Miscellaneous Configuration
|
|
@section Miscellaneous Configuration
|
|
|
|
@table @code
|
|
|
|
@vindex guix-support-dired
|
|
@item guix-support-dired
|
|
Some Emacs-Guix commands (for example, @kbd{M-x guix-hash} or @kbd{M-x
|
|
guix-package-from-file}) may or may not support @code{dired-mode}
|
|
(@pxref{Dired,,, emacs, The GNU Emacs Manual}). By default, whenever
|
|
you run them in a Dired buffer, they will use the file name at
|
|
point---i.e., you will not be prompted for it. If you wish to disable
|
|
this feature, set @code{guix-support-dired} variable to nil.
|
|
|
|
@end table
|
|
|
|
@c ----------------------------------------------------------------
|
|
@node Miscellaneous Commands
|
|
@chapter Miscellaneous Commands
|
|
|
|
And some more commands that were not covered by the other chapters.
|
|
|
|
@table @kbd
|
|
|
|
@findex guix-report-bug
|
|
@item M-x guix-report-bug
|
|
Open a mail buffer to report a bug for GNU Guix similarly to
|
|
@kbd{M-x@tie{}report-emacs-bug} command.
|
|
|
|
@findex guix-pull
|
|
@item M-x guix-pull
|
|
It is the same as @command{guix pull} shell command (@pxref{Invoking
|
|
guix pull,,, guix, The GNU Guix Reference Manual}). With @kbd{C-u},
|
|
make it verbose.
|
|
|
|
@cindex Guix REPL
|
|
Once @command{guix pull} has succeeded, the Guix REPL is
|
|
restarted@footnote{Note that name/version pairs cannot be used to
|
|
identify packages (because a name is not necessarily unique), so
|
|
Emacs-Guix 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}).}. This allows you to keep
|
|
using the Emacs interface with the updated Guix code.
|
|
|
|
@findex guix-hash
|
|
@item M-x guix-hash
|
|
Compute and copy to the kill ring (@pxref{Yanking,,, emacs, The GNU
|
|
Emacs Manual}) the SHA256 hash of a file (@pxref{Invoking guix hash,,,
|
|
guix, The GNU Guix Reference Manual}). With @kbd{C-u}, prompt for a
|
|
hash format.
|
|
|
|
If you call this command on a directory, its hash will be calculated
|
|
recursively without version-controlled files (so you can use this hash
|
|
in a package recipe).
|
|
|
|
@end table
|
|
|
|
@c ----------------------------------------------------------------
|
|
@node Help
|
|
@chapter Help
|
|
|
|
So many commands, so many buffers! This chapter describes few more
|
|
commands that should help you not to get lost.
|
|
|
|
@table @kbd
|
|
|
|
@findex guix-help
|
|
@item M-x guix-help
|
|
Display a buffer with the summary of the available Emacs-Guix
|
|
commands. Buttons in this buffer allow you to run commands and to
|
|
look at their docstrings and manual entries.
|
|
|
|
@findex guix-info
|
|
@item M-x guix-info
|
|
Show this Emacs-Guix info manual. With prefix argument, show the Guix
|
|
info manual.
|
|
|
|
@findex guix-switch-to-buffer
|
|
@item M-x guix-switch-to-buffer
|
|
Switch to one of the Emacs-Guix buffers. This is like a usual
|
|
@code{switch-to-buffer} (bound to @kbd{C-x b} by default), except it
|
|
completes only Guix buffers names. If you are going to use this
|
|
command, it is probably better to bind it to some key, for example:
|
|
|
|
@example
|
|
(global-set-key (kbd "C-x B") 'guix-switch-to-buffer)
|
|
@end example
|
|
|
|
@findex guix-extended-command
|
|
@item M-x guix-extended-command
|
|
Run Emacs-Guix command. This is like @kbd{M-x} (@pxref{M-x,,, emacs,
|
|
The GNU Emacs Manual}), except it completes only Guix command names.
|
|
And again, this is not a very useful command unless it is bound to
|
|
some key, for example:
|
|
|
|
@example
|
|
(global-set-key (kbd "M-X") 'guix-extended-command)
|
|
@end example
|
|
|
|
@end table
|
|
|
|
@c ----------------------------------------------------------------
|
|
@node Concept Index
|
|
@unnumbered Concept Index
|
|
@printindex cp
|
|
|
|
@node Command Index
|
|
@unnumbered Command Index
|
|
@printindex fn
|
|
|
|
@node Variable Index
|
|
@unnumbered Variable Index
|
|
@printindex vr
|
|
|
|
@bye
|