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-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.
* Package Management::  Managing packages and profile generations.
* Package Licenses::    Interface for licenses of packages.
* Package Locations::   Interface for locations of package source files.
* Popup Interface::     Magit-like interface for guix commands.
* Prettify Mode::       Abbreviating @file{/gnu/store/@dots{}} file names.
* 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 licenses (@pxref{Package Licenses})
@item package locations (@pxref{Package 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 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} with @kbd{C-c '} key binding
(@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 Package Management
@chapter Package Management

Emacs-Guix provides a visual interface for routine package management
tasks, pretty much like the @command{guix package} command
(@pxref{Invoking guix package,,, guix, The GNU Guix Reference
Manual}).  Specifically, it makes it easy to:

@itemize
@item browse and display packages and generations;
@item search, install, upgrade and remove packages;
@item display packages from previous generations;
@item do some other useful things.
@end itemize

@menu
* Packages::                    Interface for packages.
* Profiles::                    Interface for profiles.
* Generations::                 Interface for profile generations.
@end menu

@node Packages
@section Packages

@cindex packages
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) with @kbd{@key{RET}} and do what you need in
``info'' buffer.

@menu
* Package Commands::    @kbd{M-x guix-@dots{}} to show packages.
* Package Keys::        Key bindings in ``package-list'' buffer.
* More Package Commands:: Other @kbd{M-x guix-@dots{}} related to packages.
@end menu

@node Package Commands
@subsection Package Commands

@vindex guix-current-profile
@findex guix-set-current-profile
All commands for displaying packages use the current profile
(@code{guix-current-profile} variable), which can be changed with
@kbd{M-x@tie{}guix-set-current-profile}.  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-available-packages
@item M-x guix-all-available-packages
@findex guix-newest-available-packages
@itemx M-x guix-newest-available-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-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
@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
@subsection Package Keys

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

@subsubsection 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 More Package Commands
@subsection More Package Commands

And some more commands related to packages:

@table @kbd

@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

@node Profiles
@section Profiles

@cindex profiles
@findex guix-profiles
@vindex guix-profiles
You can keep track of your Guix profiles with @kbd{M-x guix-profiles}
command.  By default, it displays only @file{~/.guix-profile} and a
system profile (on GuixSD).  But if you manage multiple profiles, you
can add them 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

Along with the general ``list'' keys (@pxref{List buffer}), a
``profile-list'' buffer 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}).
@end table

@findex guix-apply-manifest
Finally, you can use @kbd{M-x guix-apply-manifest} to apply a manifest
file to the current profile or to a specified profile, if prefix
argument is used.  This has the same meaning as @code{--manifest}
option (@pxref{Invoking guix package,,, guix, The GNU Guix Reference
Manual}).

@node Generations
@section Generations

@cindex generations
Each Guix profile may have 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 generations.

@menu
* Generation Commands::    @kbd{M-x guix-@dots{}} to show 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 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

Analogously, on GuixSD you can also display system generations:

@table @kbd
@findex guix-system-generations
@item M-x guix-system-generations
@findex guix-last-system-generations
@item M-x guix-last-system-generations
@findex guix-system-generations-by-time
@item M-x guix-system-generations-by-time
@end table

@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 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-definition
@item M-x guix-find-license-definition
Open @file{@dots{}/guix/licenses.scm} and move to the specified license.

@end table

@c ----------------------------------------------------------------
@node Package Locations
@chapter Package Locations

@cindex package locations
As you know, package definitions are placed in Guile files, also known
as @dfn{package locations}.  The following commands should help you not
get lost in these locations:

@table @kbd

@findex guix-locations
@item M-x guix-locations
Display a list of package locations.  You can press @kbd{P} or
@kbd{@key{RET}} there to display packages placed in the current
location 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-location
@item M-x guix-find-location
Open the given package definition source file (press @kbd{@key{TAB}}
to choose a location from a completion list).

@findex guix-edit
@item 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-directory
If you are contributing to Guix, you may find it useful for
@kbd{M-x@tie{}guix-find-location} and @kbd{M-x@tie{}guix-edit} to open
locations from your Git checkout.  This can be done by setting
@code{guix-directory} variable.  For example, after this:

@example
(setq guix-directory "~/src/guix")
@end example

@kbd{M-x guix-edit guix} opens
@file{~/src/guix/gnu/packages/package-management.scm} file.

Also you can use @kbd{C-u} prefix argument to specify a directory just
for the current @kbd{M-x@tie{}guix-find-location} or
@kbd{M-x@tie{}guix-edit} command.

@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

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

@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 and generations
(@pxref{Package Management}).

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

@c ----------------------------------------------------------------
@node Miscellaneous Commands
@chapter Miscellaneous Commands

And some more commands that were not covered by the other chapters.

@table @kbd

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

@vindex guix-hash-support-dired
Finally, this command supports @code{dired-mode} (@pxref{Dired,,,
emacs, The GNU Emacs Manual}): whenever you run @kbd{M-x guix-hash} in
a Dired buffer, a hash of the current file will be calculated---i.e.,
you will not be prompted for a file name.  If you wish to disable this
feature, set @code{guix-hash-support-dired} variable to nil.

@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