Emacs Interface
***************

GNU Guix comes with several useful modules (known as ``guix.el'') for GNU Emacs which are intended to make an Emacs user interaction with Guix convenient and fun.

Initial Setup
=============

On the Guix System Distribution (see 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:

  * GNU Emacs (http://www.gnu.org/software/emacs/), version 24.3 or later;

  * Geiser (http://nongnu.org/geiser/), version 0.3 or later: it is used for interacting with the Guile process.

  * magit-popup library (https://github.com/magit/magit/).  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 M-x guix command (see Emacs Popup Interface).

When it is done, ``guix.el'' may be configured by requiring guix-autoloads file.  If you install Guix in your user profile, this auto-loading is done automatically by our Emacs package (see Application Setup), so a universal recipe for configuring ``guix.el'' is: guix package -i guix.  If you do this, there is no need to read further.

For the manual installation, you need to add the following code into your init file (see Init File (The GNU Emacs Manual)):

     (add-to-list 'load-path "/path/to/directory-with-guix.el")
     (require 'guix-autoloads nil t)

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:

  * If it was installed by a package manager of your distribution or by a usual ./configure && make && make install command sequence, then elisp files are placed in a standard directory with Emacs packages (usually it is /usr/share/emacs/site-lisp/), which is already in load-path, so there is no need to add that directory there.  Note that if you don't update this installation periodically, you may get an outdated Emacs code which does not work with the current Guile code of Guix.

  * If you used a binary installation method (see Binary Installation), then Guix is installed somewhere in the store, so the elisp files are placed in /gnu/store/...-guix-0.8.2/share/emacs/site-lisp/ or alike.  However it is not recommended to refer directly to a store directory, as it may be garbage-collected one day.  So a better choice would be to install Guix using Guix itself with guix package -i guix.

  * If you did not install Guix at all and prefer a hacking way (see Running Guix Before It Is Installed), along with augmenting load-path you need to set guix-load-path variable to the same directory, so your final configuration will look like this:

          (let ((dir "/path/to/your-guix-git-tree/emacs"))
            (add-to-list 'load-path dir)
            (setq guix-load-path dir))
          (require 'guix-autoloads nil t)

Package Management
==================

Once ``guix.el'' has been successfully configured, you should be able to use a visual interface for routine package management tasks, pretty much like the guix package command (see Invoking guix package). Specifically, it makes it easy to:

  * browse and display packages and generations;

  * search, install, upgrade and remove packages;

  * display packages from previous generations;

  * do some other useful things.

Commands
--------

All commands for displaying packages and generations use the current profile, which can be changed with M-x guix-set-current-profile.  Alternatively, if you call any of these commands with prefix argument (C-u), you will be prompted for a profile just for that command.

Commands for displaying packages:

M-x guix-all-available-packages
M-x guix-newest-available-packages
     Display all/newest available packages.

M-x guix-installed-packages
M-x guix-installed-user-packages
M-x guix-installed-system-packages
     Display installed packages.  As described above, M-x guix-installed-packages uses an arbitrary profile that you can specify, while the other commands display packages installed in 2 special profiles: ~/.guix-profile and /run/current-system/profile (only on GuixSD).

M-x guix-obsolete-packages
     Display obsolete packages (the packages that are installed in a profile but cannot be found among available packages).

M-x guix-packages-by-name
     Display package(s) with the specified name.

M-x guix-packages-by-license
     Display package(s) with the specified license.

M-x guix-packages-by-location
     Display package(s) located in the specified file.  These files usually have the following form: gnu/packages/emacs.scm, but don't type them manually!  Press TAB to complete the file name.

M-x guix-package-from-file
     Display package that the code within the specified file evaluates to. See --install-from-file, for an example of what such a file may look like.

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 guix-package-search-params variable.

M-x guix-search-by-name
     Search for packages with names matching a specified regexp.  This command is the same as guix-search-by-regexp, except only a package ``name'' is searched.

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:

     (setq guix-package-list-type 'package)

Commands for displaying generations:

M-x guix-generations
     List all the generations.

M-x guix-last-generations
     List the N last generations.  You will be prompted for the number of generations.

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 (see The date/time prompt (The Org Manual)).

Analogously on GuixSD you can also display system generations:

M-x guix-system-generations

M-x guix-last-system-generations

M-x guix-system-generations-by-time

You can also invoke the guix pull command (see Invoking guix pull) from Emacs using:

M-x guix-pull
     With C-u, make it verbose.

Once guix pull has succeeded, the Guix REPL is restarted.  This allows you to keep using the Emacs interface with the updated Guix.

General information
-------------------

The following keys are available for both ``list'' and ``info'' types of buffers:

l
r
     Go backward/forward by the history of the displayed results (this history is similar to the history of the Emacs help-mode or Info-mode).

g
     Revert current buffer: update information about the displayed packages/generations and redisplay it.

R
     Redisplay current buffer (without updating information).

M
     Apply manifest to the current profile or to a specified profile, if prefix argument is used.  This has the same meaning as --manifest option (see Invoking guix package).

C-c C-z
     Go to the Guix REPL (see The REPL (Geiser User Manual)).

h
?
     Describe current mode to see all available bindings.

Hint: If you need several ``list'' or ``info'' buffers, you can simply M-x clone-buffer them, and each buffer will have its own history.

Warning: Name/version pairs cannot be used to identify packages (because a name is not necessarily unique), so ``guix.el'' 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 g).

``List'' buffer
---------------

An interface of a ``list'' buffer is similar to the interface provided by ``package.el'' (see Package Menu (The GNU Emacs Manual)).

Default key bindings available for both ``package-list'' and ``generation-list'' buffers:

m
     Mark the current entry (with prefix, mark all entries).

u
     Unmark the current entry (with prefix, unmark all entries).

DEL
     Unmark backward.

S
     Sort entries by a specified column.

A ``package-list'' buffer additionally provides the following bindings:

RET
     Describe marked packages (display available information in a ``package-info'' buffer).

i
     Mark the current package for installation.

d
     Mark the current package for deletion.

U
     Mark the current package for upgrading.

^
     Mark all obsolete packages for upgrading.

e
     Edit the definition of the current package (go to its location).  This is similar to guix edit command (see Invoking guix edit), but for opening a package recipe in the current Emacs instance.

x
     Execute actions on the marked packages.

B
     Display latest builds of the current package (see Emacs Hydra).

A ``generation-list'' buffer additionally provides the following bindings:

RET
     List packages installed in the current generation.

i
     Describe marked generations (display available information in a ``generation-info'' buffer).

s
     Switch profile to the current generation.

d
     Mark the current generation for deletion (with prefix, mark all generations).

x
     Execute actions on the marked generations---i.e., delete generations.

e
     Run Ediff (see The Ediff Manual) on package outputs installed in the 2 marked generations.  With prefix argument, run Ediff on manifests of the marked generations.

D
=
     Run Diff (see Diff Mode (The GNU Emacs Manual)) on package outputs installed in the 2 marked generations.  With prefix argument, run Diff on manifests of the marked generations.

+
     List package outputs added to the latest marked generation comparing with another marked generation.

-
     List package outputs removed from the latest marked generation comparing with another marked generation.

``Info'' buffer
---------------

The interface of an ``info'' buffer is similar to the interface of help-mode (see Help Mode (The GNU Emacs Manual)).

``Info'' buffer contains some buttons (as usual you may use TAB / S-TAB to move between buttons---see Mouse References (The GNU Emacs Manual)) which can be used to:

  * (in a ``package-info'' buffer)

       - install/remove a package;

       - jump to a package location;

       - browse home page of a package;

       - browse license URL;

       - describe packages from ``Inputs'' fields.

  * (in a ``generation-info'' buffer)

       - remove a generation;

       - switch to a generation;

       - list packages installed in a generation;

       - jump to a generation directory.

It is also possible to copy a button label (a link to an URL or a file) by pressing c on a button.

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 (see Easy Customization (The GNU Emacs Manual)) to explore/set variables (not all) and faces.

Guile and Build Options
.......................

guix-guile-program
     If you have some special needs for starting a Guile process, you may set this variable, for example:

          (setq guix-guile-program '("/bin/guile" "--no-auto-compile"))

guix-use-substitutes
     If nil, has the same meaning as --no-substitutes option (see Invoking guix build).

guix-dry-run
     If non-nil, has the same meaning as --dry-run option (see Invoking guix build).

Buffer Names
............

Default names of ``guix.el'' buffers (``*Guix ...*'') may be changed with the following variables:

guix-package-list-buffer-name

guix-output-list-buffer-name

guix-generation-list-buffer-name

guix-package-info-buffer-name

guix-output-info-buffer-name

guix-generation-info-buffer-name

guix-repl-buffer-name

guix-internal-repl-buffer-name

By default, the name of a profile is also displayed in a ``list'' or ``info'' buffer name.  To change this behavior, use 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 (l/r) extensively), you may do it like this:

     (let ((name "Guix Universal"))
       (setq
        guix-package-list-buffer-name    name
        guix-output-list-buffer-name     name
        guix-generation-list-buffer-name name
        guix-package-info-buffer-name    name
        guix-output-info-buffer-name     name
        guix-generation-info-buffer-name name))

Keymaps
.......

If you want to change default key bindings, use the following keymaps (see Init Rebinding (The GNU Emacs Manual)):

guix-buffer-map
     Parent keymap with general keys for any buffer type.

guix-ui-map
     Parent keymap with general keys for buffers used for Guix package management (for packages, outputs and generations).

guix-list-mode-map
     Parent keymap with general keys for ``list'' buffers.

guix-package-list-mode-map
     Keymap with specific keys for ``package-list'' buffers.

guix-output-list-mode-map
     Keymap with specific keys for ``output-list'' buffers.

guix-generation-list-mode-map
     Keymap with specific keys for ``generation-list'' buffers.

guix-info-mode-map
     Parent keymap with general keys for ``info'' buffers.

guix-package-info-mode-map
     Keymap with specific keys for ``package-info'' buffers.

guix-output-info-mode-map
     Keymap with specific keys for ``output-info'' buffers.

guix-generation-info-mode-map
     Keymap with specific keys for ``generation-info'' buffers.

guix-info-button-map
     Keymap with keys available when a point is placed on a button.

Appearance
..........

You can change almost any aspect of ``list'' / ``info'' buffers using the following variables (ENTRY-TYPE means package, output or generation):

guix-ENTRY-TYPE-list-format
guix-ENTRY-TYPE-list-titles
     Specify the columns, their names, what and how is displayed in ``list'' buffers.

guix-ENTRY-TYPE-info-format
guix-ENTRY-TYPE-info-titles
guix-info-ignore-empty-values
guix-info-param-title-format
guix-info-multiline-prefix
guix-info-indent
guix-info-fill
guix-info-delimiter
     Various settings for ``info'' buffers.

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:

M-x guix-browse-license-url
     Choose a license from a completion list to browse its URL using browse-url function (see Browse-URL (The GNU Emacs Manual)).

M-x guix-licenses
     Display a list of available licenses.  You can press RET there to display packages with this license in the same way as M-x guix-packages-by-license would do (see Emacs Commands).

M-x guix-find-license-definition
     Open .../guix/licenses.scm and move to the specified license.

Package Source Locations
========================

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

M-x guix-locations
     Display a list of package locations.  You can press RET there to display packages placed in the current location in the same way as M-x guix-packages-by-location would do (see Emacs Commands). Note that when the point is on a location button, RET will open this location file.

M-x guix-find-location
     Open the given package definition source file (press TAB to choose a location from a completion list).

M-x guix-edit
     Find location of a specified package.  This is an Emacs analog of guix edit command (see Invoking guix edit).  As with M-x guix-packages-by-name, you can press TAB to complete a package name.

If you are contributing to Guix, you may find it useful for M-x guix-find-location and M-x guix-edit to open locations from your Git checkout.  This can be done by setting guix-directory variable.  For example, after this:

     (setq guix-directory "~/src/guix")

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

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

Popup Interface
===============

If you ever used Magit, you know what ``popup interface'' is (see Magit-Popup User Manual).  Even if you are not acquainted with Magit, there should be no worries as it is very intuitive.

So M-x 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 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:

  * Run the command in the Guix REPL.  It is faster than running guix ... command directly in shell, as there is no need to run another guile process and to load required modules there.

  * Run the command in a shell buffer.  You can set guix-run-in-shell-function variable to fine tune the shell buffer you want to use.

  * Add the command line to the kill ring (see Kill Ring (The GNU Emacs Manual)).

Several commands (guix graph, guix system shepherd-graph and guix system extension-graph) also have a ``View graph'' action, which allows you to view a generated graph using dot command (specified by guix-dot-program variable).  By default a PNG file will be saved in /tmp directory and will be opened directly in Emacs.  This behavior may be changed with the following variables:

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 (see The Org Manual):

          (setq guix-find-file-function 'org-open-file)
          (add-to-list 'org-file-apps '("\\.png\\'" . "sxiv %s"))

guix-dot-default-arguments
     Command line arguments to run dot command.  If you change an output format (for example, into -Tpdf), you also need to change the next variable.

guix-dot-file-name-function
     Function used to define a name of the generated graph file.  Default name is /tmp/guix-emacs-graph-XXXXXX.png.

So, for example, if you want to generate and open a PDF file in your Emacs, you may change the settings like this:

     (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)

Guix Prettify Mode
==================

GNU Guix also comes with ``guix-prettify.el''.  It provides a minor mode for abbreviating store file names by replacing hash sequences of symbols with ``...'':

     /gnu/store/72f54nfp6g1hz873w8z3gfcah0h4nl9p-foo-0.1
     => /gnu/store/…-foo-0.1

Once you set up ``guix.el'' (see Emacs Initial Setup), the following commands become available:

M-x guix-prettify-mode
     Enable/disable prettifying for the current buffer.

M-x global-guix-prettify-mode
     Enable/disable prettifying globally.

To automatically enable guix-prettify-mode globally on Emacs start, add the following line to your init file:

     (global-guix-prettify-mode)

If you want to enable it only for specific major modes, add it to the mode hooks (see Hooks (The GNU Emacs Manual)), for example:

     (add-hook 'shell-mode-hook 'guix-prettify-mode)
     (add-hook 'dired-mode-hook 'guix-prettify-mode)

Build Log Mode
==============

GNU 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 guix build --log-file ... command (see Invoking guix build), you may call 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:

M-n
     Move to the next build phase.

M-p
     Move to the previous build phase.

TAB
     Toggle (show/hide) the body of the current build phase.

S-TAB
     Toggle (show/hide) the bodies of all build phases.

There is also 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 C-c.  By default, this minor mode is enabled in shell buffers (see Interactive Shell (The GNU Emacs Manual)).  If you don't like it, set guix-build-log-minor-mode-activate to nil.

Shell Completions
=================

Another feature that becomes available after configuring Emacs interface (see Emacs Initial Setup) is completing of guix subcommands, options, packages and other things in shell (see Interactive Shell (The GNU Emacs Manual)) and eshell (see Eshell: The Emacs Shell).

It works the same way as other completions do.  Just press TAB when your intuition tells you.

And here are some examples, where pressing TAB may complete something:

  guix paTAB

  guix package -TAB

  guix package --TAB

  guix package -i geiTAB

  guix build -L/tmTAB

  guix build --syTAB

  guix build --system=iTAB

  guix system recTAB

  guix lint --checkers=syTAB

  guix lint --checkers=synopsis,desTAB

Development
===========

By default, when you open a Scheme file, guix-devel-mode will be activated (if you don't want it, set guix-devel-activate-mode to nil).  This minor mode provides the following key bindings:

C-c . k
     Copy the name of the current Guile module into kill ring (guix-devel-copy-module-as-kill).

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 ,use (some module) there.  You may just use this command instead (guix-devel-use-module).

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 C-M-x (see To eval or not to eval (Geiser User Manual)) (guix-devel-build-package-definition).

C-c . s
     Build a source derivation of the package defined by the current variable definition.  This command has the same meaning as guix build -S shell command (see Invoking guix build) (guix-devel-build-package-source).

C-c . l
     Lint (check) a package defined by the current variable definition (see Invoking guix lint) (guix-devel-lint-package).

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 (see Autodoc and friends (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.

Hydra
=====

The continuous integration server at hydra.gnu.org builds all the distribution packages on the supported architectures and serves them as substitutes (see Substitutes).  Continuous integration is currently orchestrated by Hydra (https://nixos.org/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 (see Emacs Package Management).

The following commands are available:

M-x guix-hydra-latest-builds
     Display latest failed or successful builds (you will be prompted for a number of builds).  With C-u, you will also be prompted for other parameters (project, jobset, job and system).

M-x guix-hydra-queued-builds
     Display scheduled or currently running builds (you will be prompted for a number of builds).

M-x guix-hydra-jobsets
     Display available jobsets (you will be prompted for a project).

In a list of builds you can press L key to display a build log of the current build.  Also both a list of builds and a list of jobsets provide B key to display latest builds of the current job or jobset (don't forget about C-u).