@node Emacs Interface
-@section Emacs Interface
+@chapter Emacs Interface
-@cindex emacs
-GNU Guix comes with a visual user interface for GNU@tie{}Emacs, known
-as ``guix.el''. It can be used for routine package management tasks,
-pretty much like the @command{guix package} command (@pxref{Invoking
-guix package}). Specifically, ``guix.el'' makes it easy to:
-
-@itemize
-@item browse and display packages and generations;
-@item search, install, upgrade and remove packages;
-@item display packages from previous generations;
-@item do some other useful things.
-@end itemize
+@cindex Emacs
+GNU Guix comes with several useful modules (known as ``guix.el'') for
+GNU@tie{}Emacs which are intended to make an Emacs user interaction with
+Guix convenient and fun.
@menu
-* Initial Setup: emacs Initial Setup. Preparing @file{~/.emacs}.
-* Usage: emacs Usage. Using the interface.
-* Configuration: emacs Configuration. Configuring the interface.
+* 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
-@node emacs Initial Setup
-@subsection Initial Setup
+@node Emacs Initial Setup
+@section Initial Setup
+
+On the Guix System Distribution (@pxref{GNU Distribution}), ``guix.el''
+is ready to use, provided Guix is installed system-wide, which is the
+case by default. So if that is what you're using, you can happily skip
+this section and read about the fun stuff.
+
+If you're not yet a happy user of GuixSD, a little bit of setup is needed.
To be able to use ``guix.el'', you need to install the following
packages:
@uref{http://nongnu.org/geiser/, Geiser}, version 0.3 or later: it is
used for interacting with the Guile process.
+@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 an optional dependency---it is required only for @kbd{M-x@tie{}guix}
+command (@pxref{Emacs Popup Interface}).
+
@end itemize
-When it is done, add the following into your init file (@pxref{Init
-File,,, emacs, The Emacs Editor}):
+When it is done ``guix.el'' may be configured by requiring a special
+@code{guix-init} file---i.e., by adding the following code into your
+init file (@pxref{Init File,,, emacs, The GNU Emacs Manual}):
@example
+(add-to-list 'load-path "/path/to/directory-with-guix.el")
(require 'guix-init nil t)
@end example
-However there is a chance that @code{load-path} of your Emacs does not
-contain a directory with ``guix.el'' (usually it is
-@file{/usr/share/emacs/site-lisp/}). In that case you need to add it
-before requiring (@pxref{Lisp Libraries,,, emacs, The Emacs Editor}):
+So the only thing you need to figure out is where the directory with
+elisp files for Guix is placed. It depends on how you installed Guix:
+
+@itemize
+@item
+If it was installed by a package manager of your distribution or by a
+usual @code{./configure && make && make install} command sequence, then
+elisp files are placed in a standard directory with Emacs packages
+(usually it is @file{/usr/share/emacs/site-lisp/}), which is already in
+@code{load-path}, so there is no need to add that directory there.
+
+@item
+If you used a binary installation method (@pxref{Binary Installation}),
+then Guix is installed somewhere in the store, so the elisp files are
+placed in @file{/gnu/store/@dots{}-guix-0.8.2/share/emacs/site-lisp/} or
+alike. However it is not recommended to refer directly to a store
+directory. Instead you can install Guix using Guix itself with
+@command{guix package -i guix} command (@pxref{Invoking guix package})
+and add @file{~/.guix-profile/share/emacs/site-lisp/} directory to
+@code{load-path} variable.
+
+@item
+If you did not install Guix at all and prefer a hacking way
+(@pxref{Running Guix Before It Is Installed}), along with augmenting
+@code{load-path} you need to set @code{guix-load-path} variable to the
+same directory, so your final configuration will look like this:
@example
-(add-to-list 'load-path "/path/to/directory-with-guix.el")
-(require 'guix-init)
+(let ((dir "/path/to/your-guix-git-tree/emacs"))
+ (add-to-list 'load-path dir)
+ (setq guix-load-path dir))
+(require 'guix-init nil t)
@end example
+@end itemize
+
+By default, along with autoloading (@pxref{Autoload,,, elisp, The GNU
+Emacs Lisp Reference Manual}) the main interactive commands for
+``guix.el'' (@pxref{Emacs Commands}), requiring @code{guix-init} will
+also autoload commands for the Emacs packages installed in your user
+profile.
-Do not worry about the efficiency of that @code{require} thing. It will
-not load the whole ``guix.el'' package, it will just autoload the main
-interactive commands (@pxref{Autoload,,, elisp, Emacs Lisp}).
+To disable automatic loading of installed Emacs packages, set
+@code{guix-package-enable-at-startup} variable to @code{nil} before
+requiring @code{guix-init}. This variable has the same meaning for
+Emacs packages installed with Guix, as @code{package-enable-at-startup}
+for the built-in Emacs package system (@pxref{Package Installation,,,
+emacs, The GNU Emacs Manual}).
+You can activate Emacs packages installed in your profile whenever you
+want using @kbd{M-x@tie{}guix-emacs-autoload-packages}.
-@node emacs Usage
-@subsection Usage
+
+@node Emacs Package Management
+@section Package Management
Once ``guix.el'' has been successfully configured, you should be able to
-use commands for displaying packages and generations. This information
-can be displayed in a ``list'' or ``info'' buffer.
+use a visual interface for routine package management tasks, pretty much
+like the @command{guix package} command (@pxref{Invoking guix package}).
+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
-* Commands: emacs Commands. @kbd{M-x guix-@dots{}}
-* General information: emacs General info. Common for both interfaces.
-* ``List'' buffer: emacs List buffer. List-like interface.
-* ``Info'' buffer: emacs Info buffer. Help-like interface.
+* Commands: Emacs Commands. @kbd{M-x guix-@dots{}}
+* General information: Emacs General info. Common for both interfaces.
+* ``List'' buffer: Emacs List buffer. List-like interface.
+* ``Info'' buffer: Emacs Info buffer. Help-like interface.
+* Configuration: Emacs Configuration. Configuring the interface.
@end menu
-@node emacs Commands
-@subsubsection Commands
+@node Emacs Commands
+@subsection Commands
+
+All commands for displaying packages and generations use the current
+profile, which can be changed with
+@kbd{M-x@tie{}guix-set-current-profile}. Alternatively, if you call any
+of these commands with prefix argument (@kbd{C-u}), you will be prompted
+for a profile just for that command.
-You may use the following commands to display packages and generations:
+Commands for displaying packages:
@table @kbd
+
@item M-x guix-all-available-packages
@itemx M-x guix-newest-available-packages
Display all/newest available packages.
@item M-x guix-installed-packages
-Display all packages installed in the current profile.
+@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 the
-current profile but cannot be found among available 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-generations
-List generations for the current profile. With numeric prefix, show so
-many last generations.
+@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
-By default commands for displaying packages display each output on a
-separate line. If you prefer to see a list of packages (i.e.@: a list
-with a package per line), use the following setting:
+By default, these commands display each output on a separate line. If
+you prefer to see a list of packages---i.e., a list with a package per
+line, use the following setting:
@example
(setq guix-package-list-type 'package)
@end example
-It is possible to change the currently used profile with
-@kbd{M-x@tie{}guix-set-current-profile}. This has the same effect as
-specifying @code{--profile} option for @command{guix package}
-(@pxref{Invoking guix package}).
+Commands for displaying generations:
+
+@table @kbd
+
+@item M-x guix-generations
+List all the generations.
-@node emacs General info
-@subsubsection General information
+@item M-x guix-last-generations
+List the @var{N} last generations. You will be prompted for the number
+of generations.
+
+@item M-x guix-generations-by-time
+List generations matching time period. You will be prompted for the
+period using Org mode time prompt based on Emacs calendar (@pxref{The
+date/time prompt,,, org, The Org Manual}).
+
+@end table
+
+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:
+
+@table @kbd
+@item M-x guix-pull
+With @kbd{C-u}, make it verbose.
+@end table
+
+Once @command{guix pull} has succeeded, the Guix REPL is restared. This
+allows you to keep using the Emacs interface with the updated Guix.
+
+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
The following keys are available for both ``list'' and ``info'' types of
buffers:
@item R
Redisplay current buffer (without updating information).
+@item M
+Apply manifest 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}).
+
@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
was restarted, you may want to revert ``list'' buffer (by pressing
@kbd{g}).
-@node emacs List buffer
-@subsubsection ``List'' buffer
+@node Emacs List buffer
+@subsection ``List'' buffer
An interface of a ``list'' buffer is similar to the interface provided
-by ``package.el'' (@pxref{Package Menu,,, emacs, The Emacs Editor}).
+by ``package.el'' (@pxref{Package Menu,,, emacs, The GNU Emacs Manual}).
Default key bindings available for both ``package-list'' and
``generation-list'' buffers:
@table @kbd
@item m
-Mark the current entry.
-@item M
-Mark all entries.
+Mark the current entry (with prefix, mark all entries).
@item u
Unmark the current entry (with prefix, unmark all entries).
@item @key{DEL}
Mark the current package for upgrading.
@item ^
Mark all obsolete packages for upgrading.
+@item e
+Edit the definition of the curent package (go to its location). This is
+similar to @command{guix edit} command (@pxref{Invoking guix edit}), but
+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 i
Describe marked generations (display available information in a
``generation-info'' buffer).
+@item s
+Switch profile to the current generation.
+@item d
+Mark the current generation for deletion (with prefix, mark all
+generations).
+@item x
+Execute actions on the marked generations---i.e., delete generations.
+@item e
+Run Ediff (@pxref{Top,,, ediff, The Ediff Manual}) on package outputs
+installed in the 2 marked generations. With prefix argument, run Ediff
+on manifests of the marked generations.
+@item D
+@itemx =
+Run Diff (@pxref{Diff Mode,,, emacs, The GNU Emacs Manual}) on package
+outputs installed in the 2 marked generations. With prefix argument,
+run Diff on manifests of the marked generations.
+@item +
+List package outputs added to the latest marked generation comparing
+with another marked generation.
+@item -
+List package outputs removed from the latest marked generation comparing
+with another marked generation.
@end table
-@node emacs Info buffer
-@subsubsection ``Info'' buffer
+@node Emacs Info buffer
+@subsection ``Info'' buffer
The interface of an ``info'' buffer is similar to the interface of
-@code{help-mode} (@pxref{Help Mode,,, emacs, The Emacs Editor}).
+@code{help-mode} (@pxref{Help Mode,,, emacs, The GNU Emacs Manual}).
``Info'' buffer contains some buttons (as usual you may use @key{TAB} /
@kbd{S-@key{TAB}} to move between buttons---@pxref{Mouse References,,,
-emacs, The Emacs Editor}) which can be used to:
+emacs, The GNU Emacs Manual}) which can be used to:
@itemize @bullet
@item (in a ``package-info'' buffer)
@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
@itemize @minus
@item remove a generation;
+@item switch to a generation;
@item list packages installed in a generation;
@item jump to a generation directory.
@end itemize
@end itemize
+It is also possible to copy a button label (a link to an URL or a file)
+by pressing @kbd{c} on a button.
+
-@node emacs Configuration
+@node Emacs Configuration
@subsection Configuration
There are many variables you can modify to change the appearance or
behavior of Emacs user interface. Some of these variables are described
in this section. Also you can use Custom Interface (@pxref{Easy
-Customization,,, emacs, The Emacs Editor}) to explore/set variables (not
-all) and faces.
+Customization,,, emacs, The GNU Emacs Manual}) to explore/set variables
+(not all) and faces.
@menu
-* Guile and Build Options: emacs Build Options. Specifying how packages are built.
-* Buffer Names: emacs Buffer Names. Names of Guix buffers.
-* Keymaps: emacs Keymaps. Configuring key bindings.
-* Appearance: emacs Appearance. Settings for visual appearance.
+* Guile and Build Options: Emacs Build Options. Specifying how packages are built.
+* Buffer Names: Emacs Buffer Names. Names of Guix buffers.
+* Keymaps: Emacs Keymaps. Configuring key bindings.
+* Appearance: Emacs Appearance. Settings for visual appearance.
@end menu
-@node emacs Build Options
+@node Emacs Build Options
@subsubsection Guile and Build Options
@table @code
@end table
-@node emacs Buffer Names
+@node Emacs Buffer Names
@subsubsection Buffer Names
Default names of ``guix.el'' buffers (``*Guix@tie{}@dots{}*'') may be
@item guix-generation-info-buffer-name
@item guix-repl-buffer-name
@item guix-internal-repl-buffer-name
-@item guix-temp-buffer-name
@end table
-For example if you want to display all types of results in a single
+By default, the name of a profile is also displayed in a ``list'' or
+``info'' buffer name. To change this behavior, use
+@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})
extensively), you may do it like this:
guix-generation-info-buffer-name name))
@end example
-@node emacs Keymaps
+@node Emacs Keymaps
@subsubsection Keymaps
If you want to change default key bindings, use the following keymaps
-(@pxref{Init Rebinding,,, emacs, The Emacs Editor}):
+(@pxref{Init Rebinding,,, emacs, The GNU Emacs Manual}):
@table @code
+@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.
@item guix-generation-info-mode-map
Keymap with specific keys for ``generation-info'' buffers.
+@item guix-info-button-map
+Keymap with keys available when a point is placed on a button.
+
@end table
-@node emacs Appearance
+@node Emacs Appearance
@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
+
+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.
+
+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 @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
+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
+
+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
+
+GNU@tie{}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
+
+Once you set up ``guix.el'' (@pxref{Emacs Initial Setup}), the following
+commands become available:
+
+@table @kbd
+
+@item M-x guix-prettify-mode
+Enable/disable prettifying for the current buffer.
+
+@item M-x global-guix-prettify-mode
+Enable/disable prettifying globally.
+
+@end table
+
+To automatically enable @code{guix-prettify-mode} globally on Emacs
+start, add the following line to your init file:
+
+@example
+(global-guix-prettify-mode)
+@end example
+
+If you want to enable it only for specific major modes, add it to the
+mode hooks (@pxref{Hooks,,, emacs, The GNU Emacs Manual}), for example:
+
+@example
+(add-hook 'shell-mode-hook 'guix-prettify-mode)
+(add-hook 'dired-mode-hook 'guix-prettify-mode)
+@end example
+
+
+@node Emacs Build Log
+@section Build Log Mode
+
+GNU@tie{}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}), you may call @kbd{M-x
+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
+
+There is also @kbd{M-x 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}. 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
+@section Shell Completions
+
+Another feature that becomes available after configuring Emacs interface
+(@pxref{Emacs Initial Setup}) is completing of @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}).
+
+It works the same way as other completions do. Just press @key{TAB}
+when your intuition tells you.
+
+And here are some examples, where pressing @key{TAB} may complete
+something:
+
+@itemize @w{}
+
+@item @code{guix pa}@key{TAB}
+@item @code{guix package -}@key{TAB}
+@item @code{guix package --}@key{TAB}
+@item @code{guix package -i gei}@key{TAB}
+@item @code{guix build -L/tm}@key{TAB}
+@item @code{guix build --sy}@key{TAB}
+@item @code{guix build --system=i}@key{TAB}
+@item @code{guix system rec}@key{TAB}
+@item @code{guix lint --checkers=sy}@key{TAB}
+@item @code{guix lint --checkers=synopsis,des}@key{TAB}
+
+@end itemize
+
+
+@node Emacs Development
+@section Development
+
+By default, when you open a Scheme file, @code{guix-devel-mode} will be
+activated (if you don't want it, set @code{guix-devel-activate-mode} to
+nil). 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})
+(@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}).
+
+@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.
+
+
+@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}).
HCoop / jackhill / guix / guix.git / blobdiff