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 Emacs Editor)):

     (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 Emacs Editor)):

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

Do not worry about the efficiency of that require thing.  It will not load the whole ``guix.el'' package, it will just autoload the main interactive commands (see Autoload (Emacs Lisp)).

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

You may use the following commands to display packages and generations:

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

M-x guix-installed-packages
     Display all packages installed in the current profile.

M-x guix-obsolete-packages
     Display obsolete packages (the packages that are installed in the current 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.

M-x guix-generations
     List generations for the current profile.  With numeric prefix, show so many last generations.

It is possible to change the currently used profile with M-x guix-set-current-profile.  This has the same effect as specifying --profile option for guix package (see Invoking guix package).

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

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.

DEL
     Unmark backward.

U
     Unmark all entries.

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 a package for installation (with prefix, prompt for output(s) to install).

d
     Mark a package for deletion.

^
     Mark a package for upgrading.

x
     Execute actions on 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).

``Info'' buffer
...............

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

``Info'' buffer contains some buttons (as usual you may use TAB / S-TAB to move between buttons---see Mouse References (The Emacs Editor)) 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;

       - list packages installed in a generation;

       - jump to a generation directory.

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

Keymaps
.......

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

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-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-generation-info-mode-map
     Keymap with specific keys for ``generation-info'' buffers.

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.