@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.
+* 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
+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 GNU Emacs Manual}):
+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 GNU Emacs
-Manual}):
+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.
+
+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}).
-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, The GNU Emacs Lisp
-Reference 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.
+* 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:
@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
@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}).
@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
@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
@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
@subsection Configuration
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.
@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
@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