emacs-guix/doc/emacs-guix.texi

\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-2019, 2021 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.
* Store Items::         Interface for store items.
* Package Licenses::    Interface for licenses of packages.
* Popup Interface::     Magit-like interface for Emacs-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.
* 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.

Call @kbd{M-x guix} if you prefer to dive in right away (@pxref{Popup
Interface}).

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 store items (@pxref{Store Items})
@end itemize

@item
Magit-like popup interface for all Emacs-Guix @kbd{M-x} commands and
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}) or to ``prettify'' store file names (@pxref{Prettify Mode}).

@item
@uref{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version
0.1.0 or later.  It is needed only for @kbd{M-x@tie{}guix-hash}
command (@pxref{Miscellaneous Commands}).

@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://gitlab.com/alezost-emacs/bui, BUI library}, version
1.2.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-popup, 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}).

@item
@uref{https://gitlab.com/alezost-emacs/build-farm, Emacs-Build-Farm},
version 0.2.1 or later.  Emacs-Guix provides some integration features
for this package (if it is installed), for example, @kbd{B} key in a
list of packages (@pxref{Package Keys}).

@end itemize

To sum up, most likely, you'll need all the above dependencies except
maybe @code{magit-popup}, @code{edit-indirect} and @code{build-farm}.

@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://notabug.org/alezost/emacs-guix.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.
* Lint Checkers::       Interface for package lint checkers.
* 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
Display all 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 Guix System).

@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-hidden-packages
@item M-x guix-hidden-packages
Display packages that are hidden from user interfaces (usually because
they are for internal use only).

@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-regexp
@vindex guix-package-search-params
@item M-x guix-packages-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-packages-by-name-regexp
@item M-x guix-packages-by-name-regexp
Search for packages with names matching a specified regexp.  This
command is the same as @code{guix-packages-by-regexp}, except only a
package ``name'' is searched.

@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}).

@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 (from the Guix build farm) of the current
package.
@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 Lint Checkers
@section Lint Checkers

The following commands provides functionality similar to @code{guix
lint} shell command (@pxref{Invoking guix lint,,, guix, The GNU Guix
Reference Manual}).

@table @kbd

@findex guix-lint-checkers
@item M-x guix-lint-checkers
Display a list of available lint checkers.  You can press @kbd{L}
there to lint the packages you will be prompted for with the marked
checkers.

@findex guix-package-lint
@item M-x guix-package-lint
Lint packages.  You will be prompted for comma separated package
names.  With prefix argument, you will also be prompted for checker
names.

@end table

@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'').

@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:

@table @file

@item ~/.guix-profile
the default user profile

@item ~/.config/guix/current
profile, populated by @code{guix pull}

@item /var/guix/profiles/system
system profile (only on Guix System)

@item @env{GUIX_PROFILE}
(only if this environment variable is set and this profile is not the
same as one of the above)

@end table

and other profiles shown by @code{guix package --list-profiles} shell
command.  If it is not enough for you, you can add even more profiles
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-all-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 Guix System, 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 Guix System, 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 Guix System) 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 Guix System, 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 Guix System 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 Store Items
@chapter Store Items

@cindex store items
Your @file{/gnu/store} is full of items, and Emacs-Guix provides
several commands that allow you to look at these items closely.  Most
of these commands are analogous to @code{guix gc} shell commands with
the according options (@code{--referrers}, @code{--derivers}, etc.)
(@pxref{Invoking guix gc,,, guix, The GNU Guix Reference Manual}).

@menu
* Store Item Commands:: @kbd{M-x guix-@dots{}} to show store items.
* Store Item Keys::     Key bindings in store item ``list'' buffer.
@end menu

@node Store Item Commands
@section Store Item Commands

@table @kbd

@findex guix-store-item
@item M-x guix-store-item
Display some info on the specified store file.

@findex guix-store-item-referrers
@item M-x guix-store-item-referrers
Display referrers of the specified store file.

@findex guix-store-item-references
@item M-x guix-store-item-references
Display references of the specified store file.

@findex guix-store-item-requisites
@item M-x guix-store-item-requisites
Display requisites of the specified store file.

@findex guix-store-item-derivers
@item M-x guix-store-item-derivers
Display derivers of the specified store file.

@findex guix-store-failures
@item M-x guix-store-failures
Display store items corresponding to cached build failures.

@findex guix-store-live-items
@item M-x guix-store-live-items
Display live store items.  Note that this and the next commands may
take a long time if your store is big.

@findex guix-store-dead-items
@item M-x guix-store-dead-items
Display dead store items.

@end table

@node Store Item Keys
@section Store Item Keys

Along with the general ``list'' keys (@pxref{List buffer}), a
``store-item-list'' buffer additionally provides the following key
bindings:

@table @kbd
@item e
Go to the current store item.
@item d
Mark the current store item for deletion (with prefix, mark all store
items).
@item x
Execute operation on the marked store items---i.e., attempt to delete
them.  This is similar to @code{guix gc --delete @dots{}}.
@item z
Show minibuffer message with total size of the marked store items.
@item D
Show derivers of the current (or marked) store item(s).
@item R
Show requisites of the current (or marked) store item(s).
@item f
Show referrers of the current (or marked) store item(s).
@item F
Show references of the current (or marked) store item(s).
@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 almost all the available Emacs-Guix commands.  It has 2 advantages
comparing with calling @kbd{M-x@tie{}guix-@dots{}} commands directly:

@itemize

@item
There is no need to remember the names of Emacs-Guix commands, as you
can always find them in @kbd{M-x@tie{}guix} and its sub-popups.

@item
It is faster (well, if you know what you are going to call), as it may
serve as a shortcut.  For example, instead of calling
@kbd{M-x@tie{}guix-packages-by-name}, you can press:
@kbd{M-x@tie{}guix@tie{}p@tie{}n}.

@end itemize

If you use @kbd{M-x@tie{}guix} often, you may wish to bind it to some
easy accessible key combination, for example, to @kbd{@key{super}-g}:

@example
(global-set-key (kbd "s-g") 'guix)
@end example

@node Guix Popup Interface
@section Guix Popup Interface

@findex guix-command
There is one rather special sub-popup in @kbd{M-x@tie{}guix}.  It is
bind to @kbd{c} by default, and you can call it separately with
@kbd{M-x@tie{}guix-command}.  It is a popup interface for
@code{guix@tie{}@dots{}}  shell commands.  It is probably not very
useful, as it provides all the options and flags for all the shell
actions and subcommands, so it may be confusing to see them all at
once.  Nevertheless, a description of this thing follows.

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 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}.

@menu
* Graph Configuration::         Set external viewer for graphs, etc.
* Guile and Build Options::     Settings for Guix REPL, Guile, etc.
* List/Info Configuration::     Variables for various interfaces.
* 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, by default, Guile is started with
@code{--no-auto-compile} flag (because auto-compilation may take a
very long time), so if you just want @code{guile} without any flags,
you may just use:

@example
(setq guix-guile-program "guile")
@end example

@vindex guix-load-path
@vindex guix-load-compiled-path
@item guix-load-path
@itemx guix-load-compiled-path
Directory or a list of directories prepended to Guile's
@code{%load-path} and @code{%load-compiled-path} (@pxref{Load Paths,,,
guile, The GNU Guile Reference Manual}).

If you use Guix from a git checkout (@pxref{Running Guix Before It Is
Installed,,, guix, The GNU Guix Reference Manual}), you may want
Emacs-Guix to use the same guix from git.  All you need is to point
Emacs-Guix to this checkout:

@example
(setq guix-load-path "/path/to/guix-git-dir")
@end example

Note that setting @code{guix-load-compiled-path} is not needed when
Scheme (@code{.scm}) and compiled (@code{.go}) files are placed in the
same directories.

@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 List/Info Configuration
@section List/Info Configuration

If you wish to change the appearance of various ``list'' and ``info''
buffers (@pxref{List/Info Interface}), you may look at
@code{guix-ENTRY-TYPE-BUFFER-TYPE-@dots{}} variables.  Here,
@dfn{BUFFER-TYPE} is either @code{list} or @code{info}, and
@dfn{ENTRY-TYPE} is one of the following:

@table @code
@item package
@item package-location
@item output
@item profile
@item generation
@item system
@item system-generation
@item service
@item service-location
@item license
@end table

@vindex guix-ENTRY-TYPE-BUFFER-TYPE-format
The main variable of them is
@code{guix-ENTRY-TYPE-BUFFER-TYPE-format}: it defines what parameters,
in what order and in what way are displayed.  You are welcome to play
with these ``format'' variables and to explore the other ones.

@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{List/Info 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{List/Info 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.

@vindex guix-file-size-string-function
@item guix-file-size-string-function
You may meet a string with file size in several places, in particular,
in interface for store items (@pxref{Store Items}).  By default, this
string looks like this: @samp{96.5k (98765 bytes)}.  You can modify
this format by using your own function, for example:

@example
(defun my-guix-file-size-string (size)
  (file-size-human-readable size 'si))

(setq guix-file-size-string-function 'my-guix-file-size-string)
@end example

@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-set-emacs-environment
@item M-x guix-set-emacs-environment
Set current Emacs environment according to a specified profile.  Note
that there is no way to restore the original environment (you have to
restart Emacs if you wish to do it).

@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