@menu
* Initial Setup: Emacs Initial Setup. Preparing @file{~/.emacs}.
* Package Management: Emacs Package Management. Managing packages and generations.
+* Licenses: Emacs Licenses. Interface for licenses of Guix packages.
* Popup Interface: Emacs Popup Interface. Magit-like interface for guix commands.
* Prettify Mode: Emacs Prettify. Abbreviating @file{/gnu/store/@dots{}} file names.
* Build Log Mode: Emacs Build Log. Highlighting Guix build logs.
* Completions: Emacs Completions. Completing @command{guix} shell command.
* Development: Emacs Development. Tools for Guix developers.
+* Hydra: Emacs Hydra. Interface for Guix build farm.
@end menu
emacs, The GNU Emacs Manual}).
You can activate Emacs packages installed in your profile whenever you
-want using @kbd{M-x@tie{}guix-emacs-load-autoloads}.
+want using @kbd{M-x@tie{}guix-emacs-autoload-packages}.
@node Emacs Package Management
Display all/newest available packages.
@item M-x guix-installed-packages
-Display all installed packages.
+@itemx M-x guix-installed-user-packages
+@itemx M-x guix-installed-system-packages
+Display installed packages. As described 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).
@item M-x guix-obsolete-packages
Display obsolete packages (the packages that are installed in a profile
but cannot be found among available packages).
-@item M-x guix-search-by-name
+@item M-x guix-packages-by-name
Display package(s) with the specified name.
+@item M-x guix-packages-by-license
+Display package(s) with the specified license.
+
@item M-x guix-search-by-regexp
Search for packages by a specified regexp. By default ``name'',
``synopsis'' and ``description'' of the packages will be searched. This
-can be changed by modifying @code{guix-search-params} variable.
+can be changed by modifying @code{guix-package-search-params} variable.
+
+@item M-x guix-search-by-name
+Search for packages with names matching a specified regexp. This
+command is the same as @code{guix-search-by-regexp}, except only a
+package ``name'' is searched.
@end table
@end table
+Analogously on GuixSD you can also display system generations:
+
+@table @kbd
+@item M-x guix-system-generations
+@item M-x guix-last-system-generations
+@item M-x guix-system-generations-by-time
+@end table
+
You can also invoke the @command{guix pull} command (@pxref{Invoking
guix pull}) from Emacs using:
Once @command{guix pull} has succeeded, the Guix REPL is restared. This
allows you to keep using the Emacs interface with the updated Guix.
+Finally, there is an Emacs variant of @command{guix edit} command
+(@pxref{Invoking guix edit}):
+
+@table @kbd
+@item M-x guix-edit
+As with @kbd{M-x guix-packages-by-name}, you can press @key{TAB} to
+complete a package name.
+@end table
+
+If you are contributing to Guix, you may find it useful for @kbd{M-x
+guix-edit} to open package files from your git directory. 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 guix-edit} command.
+
+
@node Emacs General info
@subsection General information
option (@pxref{Invoking guix package}).
@item C-c C-z
+@cindex REPL
+@cindex read-eval-print loop
Go to the Guix REPL (@pxref{The REPL,,, geiser, Geiser User Manual}).
@item h
for opening a package recipe in the current Emacs instance.
@item x
Execute actions on the marked packages.
+@item B
+Display latest builds of the current package (@pxref{Emacs Hydra}).
@end table
A ``generation-list'' buffer additionally provides the following
@item install/remove a package;
@item jump to a package location;
@item browse home page of a package;
+@item browse license URL;
@item describe packages from ``Inputs'' fields.
@end itemize
By default, the name of a profile is also displayed in a ``list'' or
``info'' buffer name. To change this behavior, use
-@code{guix-buffer-name-function} variable.
+@code{guix-ui-buffer-name-function} variable.
For example, if you want to display all types of results in a single
buffer (in such case you will probably use a history (@kbd{l}/@kbd{r})
guix-generation-list-buffer-name name
guix-package-info-buffer-name name
guix-output-info-buffer-name name
- guix-generation-info-buffer-name name
- guix-buffer-name-function #'guix-buffer-name-simple))
+ guix-generation-info-buffer-name name))
@end example
@node Emacs Keymaps
(@pxref{Init Rebinding,,, emacs, The GNU Emacs Manual}):
@table @code
-@item guix-root-map
-Parent keymap with general keys for all guix modes.
+@item guix-buffer-map
+Parent keymap with general keys for any buffer type.
+
+@item guix-ui-map
+Parent keymap with general keys for buffers used for Guix package
+management (for packages, outputs and generations).
@item guix-list-mode-map
Parent keymap with general keys for ``list'' buffers.
@subsubsection Appearance
You can change almost any aspect of ``list'' / ``info'' buffers using
-the following variables:
+the following variables (@dfn{ENTRY-TYPE} means @code{package},
+@code{output} or @code{generation}):
@table @code
-@item guix-list-column-format
-@itemx guix-list-column-titles
-@itemx guix-list-column-value-methods
+@item guix-ENTRY-TYPE-list-format
+@itemx guix-ENTRY-TYPE-list-titles
Specify the columns, their names, what and how is displayed in ``list''
buffers.
-@item guix-info-displayed-params
-@itemx guix-info-insert-methods
-@itemx guix-info-ignore-empty-vals
+@item guix-ENTRY-TYPE-info-format
+@itemx guix-ENTRY-TYPE-info-titles
+@itemx guix-info-ignore-empty-values
@itemx guix-info-param-title-format
@itemx guix-info-multiline-prefix
@itemx guix-info-indent
-@itemx guix-info-fill-column
+@itemx guix-info-fill
@itemx guix-info-delimiter
Various settings for ``info'' buffers.
@end table
+@node Emacs Licenses
+@section 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
+
+@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}).
+
+@item M-x guix-licenses
+Display a list of available licenses. You can press @kbd{@key{RET}}
+there to display packages with this license in the same way as @kbd{M-x
+guix-packages-by-license} would do (@pxref{Emacs Commands}).
+
+@end table
+
+
@node Emacs Popup Interface
@section Popup Interface
@end itemize
+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 using @command{dot}
+command (specified by @code{guix-dot-program} variable). By default a
+PNG file will be saved in @file{/tmp} directory and will be opened
+directly in Emacs. This behavior may be changed with the following
+variables:
+
+@table @code
+
+@item guix-find-file-function
+Function used to open a generated graph. If you want to open a graph in
+an external program, you can do it by modifying this variable---for
+example, you can use a functionality provided by the Org Mode
+(@pxref{Top,,, org, The Org Manual}):
+
+@example
+(setq guix-find-file-function 'org-open-file)
+(add-to-list 'org-file-apps '("\\.png\\'" . "sxiv %s"))
+@end example
+
+@item guix-dot-default-arguments
+Command line arguments to run @command{dot} command. If you change an
+output format (for example, into @code{-Tpdf}), you also need to change
+the next variable.
+
+@item guix-dot-file-name-function
+Function used to define a name of the generated graph file. Default
+name is @file{/tmp/guix-emacs-graph-XXXXXX.png}.
+
+@end table
+
+So, for example, if you want to generate and open a PDF file in your
+Emacs, you may change the settings like this:
+
+@example
+(defun my-guix-pdf-graph ()
+ "/tmp/my-current-guix-graph.pdf")
+
+(setq guix-dot-default-arguments '("-Tpdf")
+ guix-dot-file-name-function 'my-guix-pdf-graph)
+@end example
+
@node Emacs Prettify
@section Guix Prettify Mode
@end table
There is also @kbd{M-x guix-build-log-minor-mode} which also provides
-the same highlighting (but not key bindings). And as it is a minor
-mode, it can be enabled in any buffer. For example, if you are building
-some package in a shell buffer (@pxref{Interactive Shell,,, emacs, The
-GNU Emacs Manual}), you may enable @command{guix-build-log-minor-mode}
-to make it more colorful. Guix build output is rather specific, so this
-new highlighting shouldn't conflict with the existing one.
+the same highlighting and the same key bindings as the major mode, but
+prefixed with @kbd{C-c}. By default, this minor mode is enabled in
+shell buffers (@pxref{Interactive Shell,,, emacs, The GNU Emacs
+Manual}). If you don't like it, set
+@code{guix-build-log-minor-mode-activate} to nil.
@node Emacs Completions
eval,,, geiser, Geiser User Manual})
(@code{guix-devel-build-package-definition}).
+@item C-c . s
+Build a source derivation of the package defined by the current variable
+definition. This command has the same meaning as @code{guix build -S}
+shell command (@pxref{Invoking guix build})
+(@code{guix-devel-build-package-source}).
+
@item C-c . l
Lint (check) a package defined by the current variable definition
(@pxref{Invoking guix lint}) (@code{guix-devel-lint-package}).
Alternatively, to avoid this limitation, you may just run another Geiser
REPL, and while something is being evaluated in the previous REPL, you
can continue editing a scheme file with the help of the current one.
+
+
+@node Emacs Hydra
+@section Hydra
+
+The continuous integration server at @code{hydra.gnu.org} builds all
+the distribution packages on the supported architectures and serves
+them as substitutes (@pxref{Substitutes}). Continuous integration is
+currently orchestrated by @uref{https://nixos.org/hydra/, Hydra}.
+
+This section describes an Emacs interface to query Hydra to know the
+build status of specific packages, discover recent and ongoing builds,
+view build logs, and so on. This interface is mostly the same as the
+``list''/``info'' interface for displaying packages and generations
+(@pxref{Emacs Package Management}).
+
+The following commands are available:
+
+@table @kbd
+
+@item M-x guix-hydra-latest-builds
+Display latest failed or successful builds (you will be prompted for a
+number of builds). With @kbd{C-u}, you will also be prompted for other
+parameters (project, jobset, job and system).
+
+@item M-x guix-hydra-queued-builds
+Display scheduled or currently running builds (you will be prompted for
+a number of builds).
+
+@item M-x guix-hydra-jobsets
+Display available jobsets (you will be prompted for a project).
+
+@end table
+
+In a list of builds you can press @kbd{L} key to display a build log of
+the current build. Also both a list of builds and a list of jobsets
+provide @kbd{B} key to display latest builds of the current job or
+jobset (don't forget about @kbd{C-u}).