@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
+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.
+* 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.
-* Completions: Emacs Completions. Completing @command{guix} shell command.
+* 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
+@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
@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 ``guix.el'' may be configured by requiring a special
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 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.
+* Configuration: Emacs Configuration. Configuring the interface.
@end menu
@node Emacs Commands
-@subsubsection Commands
+@subsection Commands
All commands for displaying packages and generations use the current
profile, which can be changed with
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
-@subsubsection General information
+@subsection General information
The following keys are available for both ``list'' and ``info'' types of
buffers:
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
@kbd{g}).
@node Emacs List buffer
-@subsubsection ``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 GNU Emacs Manual}).
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
@end table
@node Emacs Info buffer
-@subsubsection ``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 GNU Emacs Manual}).
@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-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
+
+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
-@subsection Guix Prettify Mode
+@section Guix Prettify Mode
-Along with ``guix.el'', GNU@tie{}Guix comes with ``guix-prettify.el''.
-It provides a minor mode for abbreviating store file names by replacing
-hash sequences of symbols with ``@dots{}'':
+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
@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
-@subsection Shell Completions
+@section Shell Completions
Another feature that becomes available after configuring Emacs interface
(@pxref{Emacs Initial Setup}) is completing of @command{guix}
@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