Emacs Interface
===============

GNU Guix comes with a visual user interface for GNU Emacs, known as ``guix.el''.  It can be used for routine package management tasks, pretty much like the guix package command (see Invoking guix package).  Specifically, ``guix.el'' 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.

Initial Setup
-------------

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.

When it is done, add the following into your init file (see Init File (The GNU Emacs Manual)):

     (require 'guix-init nil t)

However there is a chance that load-path of your Emacs does not contain a directory with ``guix.el'' (usually it is /usr/share/emacs/site-lisp/).  In that case you need to add it before requiring (see Lisp Libraries (The GNU Emacs Manual)):

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

By default, along with autoloading (see Autoload (The GNU Emacs Lisp Reference Manual)) the main interactive commands for ``guix.el'' (see Emacs Commands), requiring guix-init will also autoload commands for the Emacs packages installed in your user profile.

To disable automatic loading of installed Emacs packages, set guix-package-enable-at-startup variable to nil before requiring guix-init.  This variable has the same meaning for Emacs packages installed with Guix, as package-enable-at-startup for the built-in Emacs package system (see Package Installation (The GNU Emacs Manual)).

You can activate Emacs packages installed in your profile whenever you want using M-x guix-emacs-load-autoloads.

Usage
-----

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.

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
     Display all installed packages.

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-search-by-name
     Display package(s) with the specified name.

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

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

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 restared.  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).

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 simlpy 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.

M
     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.

x
     Execute actions on the marked packages.

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;

       - 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
     Has the same meaning as --no-substitutes option (see Invoking guix build).

guix-dry-run
     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-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
        guix-buffer-name-function        #'guix-buffer-name-simple))

Keymaps
.......

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

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:

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

guix-info-displayed-params
guix-info-insert-methods
guix-info-ignore-empty-vals
guix-info-param-title-format
guix-info-multiline-prefix
guix-info-indent
guix-info-fill-column
guix-info-delimiter
     Various settings for ``info'' buffers.

Guix Prettify Mode
------------------

Along with ``guix.el'', GNU Guix 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)