Emacs-Guix Reference Manual

Table of Contents

Next:   [Contents][Index]

Emacs-Guix

This document describes Emacs-Guix, the Emacs interface for the GNU Guix package manager.

Copyright © 2014-2019, 2021 Alex Kost
Copyright © 2018 Oleg Pykhalov

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is available at http://www.gnu.org/licenses/fdl.html.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

Emacs-Guix (also known as “guix.el”) provides various interfaces and tools related to the GNU Guix package manager.

Call M-x guix if you prefer to dive in right away (see Popup Interface).

In short, Emacs-Guix provides the following features:


Next: , Previous: , Up: Top   [Contents][Index]

2 Installation

There are several ways1 to install Emacs-Guix:

For the first 2 options, you are all set, so you can skip this chapter. If you want to use Emacs-Guix from a git checkout, read further.


Next: , Up: Installation   [Contents][Index]

2.1 Requirements

Emacs-Guix depends on the following packages:

To sum up, most likely, you’ll need all the above dependencies except maybe magit-popup, edit-indirect and build-farm.


Previous: , Up: Installation   [Contents][Index]

2.2 Using from Git

You can use Emacs-Guix directly from a git checkout without any installation.

At first, you need to clone the repository and to run autogen.sh script (it’s just a wrapper for autoreconf command). If you don’t have all dependencies installed, you may use guix.scm file to make an environment to build Emacs-Guix (see Invoking guix environment in The GNU Guix Reference Manual):

$ git clone https://notabug.org/alezost/emacs-guix.git
$ cd guix.el
$ guix environment --pure --load=guix.scm
$ ./autogen.sh

Now configure and make it (this will compile all Emacs-Lisp and Scheme files, and will generate guix-autoloads.el file):

$ ./configure
$ make

Now all you need, is to add elisp directory to the Emacs load-path and to load the generated autoloads. This can be done by adding the following code into your Emacs init file (see Init File in The GNU Emacs Manual):

(add-to-list 'load-path "/path/to/emacs-guix/elisp")
(require 'guix-autoloads nil t)

Now, if you start Emacs, all M-x guix-… commands should become available.


Up: Using from Git   [Contents][Index]

2.2.1 Using the Manual from Git

After “make”-ing, the info manual is ready to use. You can run it, for example, with C-u C-h i command (the file is doc/emacs-guix.info). However it is not convenient. You may want to have this manual in the top info directory along with the other manuals. To make it possible, you need to do the following 2 steps:

Once the above 2 steps are done, C-h i should display the Emacs-Guix entry. Also you can use M-x guix-info command to run the manual (see Help).


Next: , Previous: , Up: Top   [Contents][Index]

3 Packages

Emacs-Guix provides a visual interface for packages where you can perform routine package management tasks, pretty much like the guix package command (see Invoking guix package in The GNU Guix Reference Manual).


Next: , Up: Packages   [Contents][Index]

3.1 Package Commands

There are multiple commands to display a list of Guix packages. You can either perform some actions in such “package-list” buffer, or “describe” package(s) in “package-info” buffer using RET.

The following commands use the current profile, which can be changed globally with M-x guix-set-current-profile (see Profile Commands). Alternatively, if you call any of the following commands with a prefix argument (C-u), you will be prompted for a profile just for that command.

M-x guix-all-packages

Display all available packages.

M-x guix-installed-packages
M-x guix-installed-user-packages
M-x guix-installed-system-packages

Display installed packages. As explained 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 Guix System).

M-x guix-obsolete-packages

Display obsolete or unknown packages (the packages that are installed in a profile but cannot be found among the available packages).

M-x guix-superseded-packages

Display packages that are superseded by the other packages.

M-x guix-hidden-packages

Display packages that are hidden from user interfaces (usually because they are for internal use only).

M-x guix-dependent-packages

Display packages that depend on the specified package(s). This command is analogous to guix refresh --list-dependent shell command (see Invoking guix refresh in The GNU Guix Reference Manual). You’ll be prompted for a package name (or multiple names, separated by commas) and a dependency type (it should be either “all” or “direct”).

M-x guix-packages-by-name

Display package(s) with the specified name.

M-x guix-packages-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-packages-by-name-regexp

Search for packages with names matching a specified regexp. This command is the same as guix-packages-by-regexp, except only a package “name” is searched.

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 in The GNU Guix Reference Manual, for an example of what such a file may look like.

M-x guix-packages-from-system-config-file

Display packages from the specified file with operating-system declaration (see Using the Configuration System in The GNU Guix Reference Manual).

By default, these commands display each package 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)

Next: , Previous: , Up: Packages   [Contents][Index]

3.2 Package Keys

3.2.1 List Buffer

Along with the general “list” keys (see List buffer), a “package-list” buffer additionally provides the following key bindings:

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 (with prefix, mark all installed packages for upgrading).

x

Execute actions on the marked packages.

e

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

G

Show graph for the current package (see Graph Configuration).

z

Show package size (see Invoking guix size in The GNU Guix Reference Manual).

L

Lint the current package (see Invoking guix lint in The GNU Guix Reference Manual). With prefix argument, you’ll be prompted for checker names.

B

Display latest builds (from the Guix build farm) of the current package.

3.2.2 Info Buffer

Similarly, “package-info” buffer provides the following key bindings:

i

Install the current package.

d

Delete the current package.

U

Upgrade the current package.

e

Go to the package definition.

G

Show package graph.

z

Show package size.

L

Lint the package.


Next: , Previous: , Up: Packages   [Contents][Index]

3.3 Package Locations

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

M-x guix-package-locations

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

M-x guix-find-package-location-file

Open a file with package definitions (press TAB to choose a file from the completion list).

M-x guix-find-package-definition
M-x guix-edit

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

By default, when you should specify a package name (for example, after M-x guix-edit), you will be prompted for it in the minibuffer, but you can configure Emacs-Guix to use a package name at the current point position (unless C-u is used):

(setq guix-read-package-name-function 'guix-read-package-name-at-point)

Next: , Previous: , Up: Packages   [Contents][Index]

3.4 Lint Checkers

The following commands provides functionality similar to guix lint shell command (see Invoking guix lint in The GNU Guix Reference Manual).

M-x guix-lint-checkers

Display a list of available lint checkers. You can press L there to lint the packages you will be prompted for with the marked checkers.

M-x guix-package-lint

Lint packages. You will be prompted for comma separated package names. With prefix argument, you will also be prompted for checker names.


Previous: , Up: Packages   [Contents][Index]

3.5 More Package Commands

And some more commands related to packages:

M-x guix-number-of-packages

This command just displays a message (in the minibuffer) with the number of available packages. Along with the default Guix packages, this number includes the packages from GUIX_PACKAGE_PATH environment variable (see Package Modules in The GNU Guix Reference Manual).

M-x guix-package-graph

Show a package graph. You’ll be prompted for a package name, graph backend and graph node type (everything can be completed with TAB key). See Graph Configuration, if you want to set an external graph viewer.

M-x guix-package-size

Show a package size (see Invoking guix size in The GNU Guix Reference Manual). You’ll be prompted for a package name and a size type (it should be either “text” or “image”).


Next: , Previous: , Up: Top   [Contents][Index]

4 Profiles and Generations

As you know, packages are installed in profiles. The default user profile is ~/.guix-profile (actually it is a symlink to the real profile) but you can also install packages to non-standard profiles (using guix package --profile=…).

Profiles have generations. They appear whenever you perform any profile action (installing/removing packages). These generations are just symlinks to the previous versions of profile, so you can easily roll-back to any previous generation.

As you may guess, Emacs-Guix provides an interface for profiles and their generations, where you can look at the packages from the old generations, switch to any generation, delete generations, etc.


Next: , Up: Profiles and Generations   [Contents][Index]

4.1 Profiles

If you manage multiple Guix profiles, this section is for you. M-x guix-profiles is the entry point to display profiles. There you can look at the profile generations, installed packages and more. Read further for details.


Next: , Up: Profiles   [Contents][Index]

4.1.1 Profile Commands

M-x guix-profiles

Show a list of available Guix profiles. By default, it displays:

~/.guix-profile

the default user profile

~/.config/guix/current

profile, populated by guix pull

/var/guix/profiles/system

system profile (only on Guix System)

GUIX_PROFILE

(only if this environment variable is set and this profile is not the same as one of the above)

and other profiles shown by guix package --list-profiles shell command. If it is not enough for you, you can add even more profiles to this list by setting guix-profiles variable, for example, like this:

(with-eval-after-load 'guix-ui-profile
  (setq guix-profiles
        (append '("/path/to/my-profile1"
                  "/path/to/my-profile2")
                (guix-all-profiles))))

The “profile-list” buffer provides some keys to work with profiles (see Profile Keys), but also there are the following standalone profile commands that can be called outside this buffer.

M-x guix-set-current-profile

Set the current profile (guix-current-profile variable) to the specified one. The current profile is used by the package commands (see Package Commands) to check what package is installed in this profile, and by generation commands (see Generation Commands).

M-x guix-apply-manifest

Apply a manifest file to the current profile or a specified profile, if the prefix argument is used. This has the same meaning as --manifest option (see Invoking guix package in The GNU Guix Reference Manual).


Previous: , Up: Profiles   [Contents][Index]

4.1.2 Profile Keys

Along with the general “list” keys (see List buffer), a “profile-list” buffer (displayed by M-x guix-profiles) additionally provides the following bindings:

P

Display packages installed in profile at point.

G

Display generations of profile at point.

E

Display “search paths” environment variables for the marked profiles, or the current profile if nothing is marked. This command is analogous to guix package --search-paths shell command (see Invoking guix package in The GNU Guix Reference Manual).

c

Make profile at point the current profile for the package commands (see Packages).

M

Apply manifest from a specified file to the profile at point.


Previous: , Up: Profiles and Generations   [Contents][Index]

4.2 Generations

Each Guix profile may have multiple generations and Emacs-Guix allows you to display these generations, to switch to a particular generation, to look at the packages installed in it and to compare 2 generations.


Next: , Up: Generations   [Contents][Index]

4.2.1 Generation Commands

As with commands for displaying packages (see Package Commands), commands for displaying generations also use the current profile and can be called with a prefix argument.

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 in The Org Manual).

If you use Guix System, you may also look at the system generations using the similar commands (see System Commands).


Previous: , Up: Generations   [Contents][Index]

4.2.2 Generation Keys

Along with the general “list” keys (see List buffer), a “generation-list” buffer additionally provides the following bindings:

P

Display packages installed in the current generation.

E

Display “search paths” environment variables for the marked generations. This command is similar to the one for a list of profiles (see Profiles).

c

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.

=

Run Diff (see Diff Mode in 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.


Next: , Previous: , Up: Top   [Contents][Index]

5 System

This chapter describes Emacs-Guix features related to Guix System, in particular:


Next: , Up: System   [Contents][Index]

5.1 System From File

Your system configuration file (for Guix System) contains operating-system declaration (see operating-system Reference in The GNU Guix Reference Manual).

And Emacs-Guix provides an interface for this operating-system, where you can look at the packages, services, initrd modules that this system will install and some other stuff.

guix-system-from-file

Find your system configuration file and look at the system it provides.


Next: , Previous: , Up: System   [Contents][Index]

5.2 Services

If you use Guix System, you may have a wish to become more familiar with the system services (see Services in The GNU Guix Reference Manual). Emacs-Guix provides several commands to display these services.


Next: , Up: Services   [Contents][Index]

5.2.1 Service Commands

The interface for services is very similar to the interface for packages (see Packages). The following commands allows you to look at the Guix System services.

M-x guix-all-services

Display all available services.

M-x guix-default-services

Display services from %base-services (see Base Services in The GNU Guix Reference Manual) or %desktop-services (see Desktop Services in The GNU Guix Reference Manual). You will be prompted in the minibuffer for the variable name (completions available).

M-x guix-services-by-name

Display service(s) with the specified name.

M-x guix-services-by-regexp

Search for services by a specified regexp. By default, “name” and “description” of the services will be searched. This can be changed by modifying guix-service-search-params variable.

M-x guix-services-by-location

Display service(s) located in the specified file.

M-x guix-services-from-system-config-file

Display services from the specified file with operating-system declaration.


Previous: , Up: Services   [Contents][Index]

5.2.2 Service Locations

Similarly to the package locations (see Package Locations), you may look at the service locations:

M-x guix-service-locations

Display a list of files with service locations. Press RET there to display services placed in the current location.

M-x guix-find-service-location-file

Open a file with service definitions (press TAB to choose the file from a completion list).

M-x guix-find-service-definition

Go to the service location—i.e., open a file with the specified service and move the point to its definition.


Previous: , Up: System   [Contents][Index]

5.3 System Commands

Along with the commands for services and operating-system, there are commands to look at the system profile (/var/guix/profiles/system), its generations and packages installed in it.

M-x guix-system-profile

Display “info” interface for the system profile.

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

Display generations of the system profile. These commands have the same meaning as the usual generation commands (see Generation Commands).

M-x guix-installed-system-packages

Display packages installed in the system profile.

M-x guix-packages-from-system-config-file
M-x guix-services-from-system-config-file

Display packages/services from the specified system configuration file. You can also look at these packages/services from the “system-info” interface (see System From File).


Next: , Previous: , Up: Top   [Contents][Index]

6 Store Items

Your /gnu/store is full of items, and Emacs-Guix provides several commands that allow you to look at these items closely. Most of these commands are analogous to guix gc shell commands with the according options (--referrers, --derivers, etc.) (see Invoking guix gc in The GNU Guix Reference Manual).


Next: , Up: Store Items   [Contents][Index]

6.1 Store Item Commands

M-x guix-store-item

Display some info on the specified store file.

M-x guix-store-item-referrers

Display referrers of the specified store file.

M-x guix-store-item-references

Display references of the specified store file.

M-x guix-store-item-requisites

Display requisites of the specified store file.

M-x guix-store-item-derivers

Display derivers of the specified store file.

M-x guix-store-failures

Display store items corresponding to cached build failures.

M-x guix-store-live-items

Display live store items. Note that this and the next commands may take a long time if your store is big.

M-x guix-store-dead-items

Display dead store items.


Previous: , Up: Store Items   [Contents][Index]

6.2 Store Item Keys

Along with the general “list” keys (see List buffer), a “store-item-list” buffer additionally provides the following key bindings:

e

Go to the current store item.

d

Mark the current store item for deletion (with prefix, mark all store items).

x

Execute operation on the marked store items—i.e., attempt to delete them. This is similar to guix gc --delete ….

z

Show minibuffer message with total size of the marked store items.

D

Show derivers of the current (or marked) store item(s).

R

Show requisites of the current (or marked) store item(s).

f

Show referrers of the current (or marked) store item(s).

F

Show references of the current (or marked) store item(s).


Next: , Previous: , Up: Top   [Contents][Index]

7 Package 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 in The GNU Emacs Manual).

M-x guix-licenses

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

M-x guix-find-license-location-file

Open …/guix/licenses.scm file.

M-x guix-find-license-definition

Open …/guix/licenses.scm and move to the specified license.


Next: , Previous: , Up: Top   [Contents][Index]

8 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 almost all the available Emacs-Guix commands. It has 2 advantages comparing with calling M-x guix-… commands directly:

If you use M-x guix often, you may wish to bind it to some easy accessible key combination, for example, to super-g:

(global-set-key (kbd "s-g") 'guix)

Up: Popup Interface   [Contents][Index]

8.1 Guix Popup Interface

There is one rather special sub-popup in M-x guix. It is bind to c by default, and you can call it separately with M-x guix-command. It is a popup interface for guix … shell commands. It is probably not very useful, as it provides all the options and flags for all the shell actions and subcommands, so it may be confusing to see them all at once. Nevertheless, a description of this thing follows.

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:

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 (see Graph Configuration).


Next: , Previous: , Up: Top   [Contents][Index]

9 Guix Prettify Mode

Emacs-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
M-x guix-prettify-mode

Enable/disable prettifying for the current buffer.

M-x global-guix-prettify-mode

Enable/disable prettifying globally.

If you wish to enable global-guix-prettify-mode automatically on Emacs start, you may do it by adding the following line to your Emacs init file:

(add-hook 'after-init-hook 'global-guix-prettify-mode)

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

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

Next: , Previous: , Up: Top   [Contents][Index]

10 Guix Environment Variables Mode

Emacs-Guix provides a major mode based on sh-mode for prettifying environment-variables and profile files. It will split all exported variables and separate them with a newline. All /tmp/guix-build-*-*.drv-*/environment-variables and /etc/profile will be prettified by default.

If you want to disable this prettifying, set guix-env-var-enable-formatting variable to nil.

You could also directly use guix-env-var-prettify-buffer to prettify the current buffer without changing its major mode and guix-env-var-prettify-variable to prettify a variable at current line.

M-x guix-env-var-mode

Enable/disable prettifying for the current buffer.

M-x guix-env-var-prettify-buffer

Prettify current buffer without switching to guix-env-var-mode.

M-x guix-env-var-prettify-variable

Prettify variable assignment at current line.


Next: , Previous: , Up: Top   [Contents][Index]

11 Build Log Mode

Emacs-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 in The GNU Guix Reference Manual), 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. You may find this minor mode useful for shell buffers (see Interactive Shell in The GNU Emacs Manual). It can be enabled there like this:

(add-hook 'shell-mode-hook 'guix-build-log-minor-mode)

Next: , Previous: , Up: Top   [Contents][Index]

12 Shell Completions

Another available feature is completing guix subcommands, options, packages and other things in shell (see Interactive Shell in The GNU Emacs Manual) and eshell (see Eshell: The Emacs Shell) buffers.

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:


Next: , Previous: , Up: Top   [Contents][Index]

13 Development

If you often work with Guix package files, you may want to see some highlighting and to have some indentation rules specific for Guix keywords. There is a minor mode to help you—M-x guix-devel-mode. It can be enabled in Scheme buffers like this:

(add-hook 'scheme-mode-hook 'guix-devel-mode)

Along with highlighting and indentation, 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 in 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 in The GNU Guix Reference Manual) (guix-devel-build-package-source).

C-c . d

Download a source of the package defined by the current variable definition. This command is the same as running guix download shell command on the package source (see Invoking guix download in The GNU Guix Reference Manual) (guix-devel-download-package-source).

C-c . l

Lint (check) a package defined by the current variable definition (see Invoking guix lint in The GNU Guix Reference Manual) (guix-devel-lint-package).

C-c . '

Edit description or synopsis of the current package in texinfo-mode (guix-devel-code-block-edit).

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

To find a patch file at point with M-x ffap command, you may use:

(add-to-list 'ffap-alist '("\\.patch" . guix-devel-ffap-patch))

Next: , Previous: , Up: Top   [Contents][Index]

14 List/Info Interface

As you probably already know, there are multiple commands that display various lists (of packages, licenses, etc.). This is so-called “list” interface. Also you can get the same data displayed in “info” interface. This chapter describes these interfaces.


Next: , Up: List/Info Interface   [Contents][Index]

14.1 List/Info Keys

The following keys are available for both “list” and “info” interfaces:

h

Show “hint” (a message with available key bindings).

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 (receive it again) the currently displayed data and redisplay it.

R

Redisplay current buffer (without updating the data).

?

Describe current mode.

Also some buffers provide the following keys:

M

Apply manifest file to the current profile (see guix-apply-manifest).

C-c C-z

Go to the Guix REPL (see The REPL in Geiser User Manual).

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.


Next: , Previous: , Up: List/Info Interface   [Contents][Index]

14.2 “List” buffer

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

And here are the default key bindings (some of them may be rebound to more specific commands):

m

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

u

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

DEL

Unmark backward.

RET
i

Display “info” interface for the marked entries (or the current entry if nothing is marked).

s

Sort entries by column specified by the prefix argument (counting from 0).


Previous: , Up: List/Info Interface   [Contents][Index]

14.3 “Info” buffer

The interface of an “info” buffer is similar to the interface of help-mode (see Help Mode in The GNU Emacs Manual), or rather Custom-mode (see Easy Customization in The GNU Emacs Manual), as it is full of various buttons that can be used to open files, browse URLs, do some actions (like installing/removing packages), etc.

As always, you may use TAB / S-TAB to move between buttons and RET to press a button, or you can just use mouse (see Mouse References in The GNU Emacs Manual).

Finally, you can copy any button label (a link to an URL or a file) by pressing c on a button.


Next: , Previous: , Up: Top   [Contents][Index]

15 Configuration

There are many variables you can modify to change the appearance or behavior of Emacs-Guix. Some of these variables are described in this section. Also you can use Custom Interface (see Easy Customization in The GNU Emacs Manual) to explore/set variables and faces—M-x customize-group RET guix.


Next: , Up: Configuration   [Contents][Index]

15.1 Graph Configuration

Some commands may display a graph image. Currently Guix provides 2 graph backends (see Invoking guix graph in The GNU Guix Reference Manual):

d3js

Such graph will be displayed in your browser using browse-url function (see Browse-URL in The GNU Emacs Manual).

graphviz

Such graph will be displayed inside Emacs by default, but this can be configured …

… Graphs are opened using guix-find-file-function, so if you want to use an external viewer, you need to set this variable. Probably the easiest way to set an external viewer is to use a functionality provided by the Org Mode. For example, if you want to open the generated graphs (PNG files) with sxiv image viewer, you can do it like this:

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

Now some deeper details and configuration options.

The graphviz graph is converted into an image file using dot command specified by guix-dot-program and guix-dot-default-arguments variables. By default, a PNG file is generated and saved as /tmp/emacs-guix-XXXXXX/graph-XXXXXX.png. If you want to change an output format (for example, into PDF), you also need to change guix-dot-file-name-function (to make .pdf extension of the output file). This can be done 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)

Next: , Previous: , Up: Configuration   [Contents][Index]

15.2 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, by default, Guile is started with --no-auto-compile flag (because auto-compilation may take a very long time), so if you just want guile without any flags, you may just use:

(setq guix-guile-program "guile")
guix-load-path
guix-load-compiled-path

Directory or a list of directories prepended to Guile’s %load-path and %load-compiled-path (see Load Paths in The GNU Guile Reference Manual).

If you use Guix from a git checkout (see Running Guix Before It Is Installed in The GNU Guix Reference Manual), you may want Emacs-Guix to use the same guix from git. All you need is to point Emacs-Guix to this checkout:

(setq guix-load-path "/path/to/guix-git-dir")

Note that setting guix-load-compiled-path is not needed when Scheme (.scm) and compiled (.go) files are placed in the same directories.

guix-use-substitutes

Has the same meaning as --no-substitutes option (see Invoking guix build in The GNU Guix Reference Manual)—i.e., when non-nil, substitutes are enabled.

guix-dry-run

Has the same meaning as --dry-run option (see Invoking guix build in The GNU Guix Reference Manual)—i.e., when non-nil, do not build the derivations.

guix-repl-use-server

By default, along with the main Guix REPL, an additional (internal) REPL is started. This allows you to display packages, generations and to receive other info from the Scheme side, while there is some active process in the main Guix REPL (e.g., while downloading or building packages). If you don’t want to have the second REPL, set this variable to nil.

guix-repl-use-latest

Set this variable to nil, if you don’t want to use the latest Guix code received with guix pull command (see Invoking guix pull in The GNU Guix Reference Manual).


Next: , Previous: , Up: Configuration   [Contents][Index]

15.3 List/Info Configuration

If you wish to change the appearance of various “list” and “info” buffers (see List/Info Interface), you may look at guix-ENTRY-TYPE-BUFFER-TYPE-… variables. Here, BUFFER-TYPE is either list or info, and ENTRY-TYPE is one of the following:

package
package-location
output
profile
generation
system
system-generation
service
service-location
license

The main variable of them is guix-ENTRY-TYPE-BUFFER-TYPE-format: it defines what parameters, in what order and in what way are displayed. You are welcome to play with these “format” variables and to explore the other ones.


Next: , Previous: , Up: Configuration   [Contents][Index]

15.4 Buffer Names

Default names of various Emacs-Guix buffers (“*Guix …*”) may be changed with the following variables:

guix-ENTRY-TYPE-BUFFER-TYPE-buffer-name

See List/Info Configuration, for the meaning of ENTRY-TYPE and BUFFER-TYPE.

guix-ui-buffer-name-function

By default, many Guix buffers contain profile name (e.g., *Guix Packages: <profile>*). This variable allows you to control how this profile name is displayed. If you want to remove profile name from the buffer names, you can do it like this:

(setq guix-ui-buffer-name-function 'guix-ui-buffer-name-simple)
guix-repl-buffer-name
guix-internal-repl-buffer-name
guix-search-paths-buffer-name
guix-help-buffer-name
guix-about-buffer-name

Next: , Previous: , Up: Configuration   [Contents][Index]

15.5 Keymaps

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

guix-ui-map

Parent keymap with general keys for buffers used for Guix package management.

guix-ENTRY-TYPE-BUFFER-TYPE-mode-map

See List/Info Configuration, for the meaning of ENTRY-TYPE and BUFFER-TYPE.

guix-build-log-common-map
guix-build-log-mode-map
guix-build-log-minor-mode-map
guix-devel-keys-map
guix-devel-mode-map

Previous: , Up: Configuration   [Contents][Index]

15.6 Miscellaneous Configuration

guix-support-dired

Some Emacs-Guix commands (for example, M-x guix-hash or M-x guix-package-from-file) may or may not support dired-mode (see Dired in The GNU Emacs Manual). By default, whenever you run them in a Dired buffer, they will use the file name at point—i.e., you will not be prompted for it. If you wish to disable this feature, set guix-support-dired variable to nil.

guix-file-size-string-function

You may meet a string with file size in several places, in particular, in interface for store items (see Store Items). By default, this string looks like this: ‘96.5k (98765 bytes)’. You can modify this format by using your own function, for example:

(defun my-guix-file-size-string (size)
  (file-size-human-readable size 'si))

(setq guix-file-size-string-function 'my-guix-file-size-string)

Next: , Previous: , Up: Top   [Contents][Index]

16 Miscellaneous Commands

And some more commands that were not covered by the other chapters.

M-x guix-report-bug

Open a mail buffer to report a bug for GNU Guix similarly to M-x report-emacs-bug command.

M-x guix-set-emacs-environment

Set current Emacs environment according to a specified profile. Note that there is no way to restore the original environment (you have to restart Emacs if you wish to do it).

M-x guix-pull

It is the same as guix pull shell command (see Invoking guix pull in The GNU Guix Reference Manual). With C-u, make it verbose.

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

M-x guix-hash

Compute and copy to the kill ring (see Yanking in The GNU Emacs Manual) the SHA256 hash of a file (see Invoking guix hash in The GNU Guix Reference Manual). With C-u, prompt for a hash format.

If you call this command on a directory, its hash will be calculated recursively without version-controlled files (so you can use this hash in a package recipe).


Next: , Previous: , Up: Top   [Contents][Index]

17 Help

So many commands, so many buffers! This chapter describes few more commands that should help you not to get lost.

M-x guix-help

Display a buffer with the summary of the available Emacs-Guix commands. Buttons in this buffer allow you to run commands and to look at their docstrings and manual entries.

M-x guix-info

Show this Emacs-Guix info manual. With prefix argument, show the Guix info manual.

M-x guix-switch-to-buffer

Switch to one of the Emacs-Guix buffers. This is like a usual switch-to-buffer (bound to C-x b by default), except it completes only Guix buffers names. If you are going to use this command, it is probably better to bind it to some key, for example:

(global-set-key (kbd "C-x B") 'guix-switch-to-buffer)
M-x guix-extended-command

Run Emacs-Guix command. This is like M-x (see M-x in The GNU Emacs Manual), except it completes only Guix command names. And again, this is not a very useful command unless it is bound to some key, for example:

(global-set-key (kbd "M-X") 'guix-extended-command)

Next: , Previous: , Up: Top   [Contents][Index]

Concept Index

Jump to:   B   C   F   G   I   P   S  
Index Entry  Section

B
build log: Build Log Mode
buttons: Info buffer

C
completions: Completions
customization group: Configuration

F
ffap: Development

G
generations: Generations
graph: Package Keys
graph: More Package Commands
graph: Guix Popup Interface
graph: Graph Configuration
Guix REPL: List/Info Keys
Guix REPL: Guile and Build Options
Guix REPL: Miscellaneous Commands

I
installation: Installation

P
package licenses: Package Licenses
package locations: Package Locations
packages: Packages
profiles: Profiles

S
service Locations: Service Locations
services: Services
shell: Completions
store items: Store Items
system: System From File

Jump to:   B   C   F   G   I   P   S  

Next: , Previous: , Up: Top   [Contents][Index]

Command Index

Jump to:   G  
Index Entry  Section

G
global-guix-prettify-mode: Prettify Mode
guix: Popup Interface
guix-all-packages: Package Commands
guix-all-services: Service Commands
guix-apply-manifest: Profile Commands
guix-browse-license-url: Package Licenses
guix-build-log-minor-mode: Build Log Mode
guix-build-log-mode: Build Log Mode
guix-command: Guix Popup Interface
guix-default-services: Service Commands
guix-dependent-packages: Package Commands
guix-devel-mode: Development
guix-edit: Package Locations
guix-env-var-mode: Prettify Variables
guix-env-var-prettify-buffer: Prettify Variables
guix-env-var-prettify-variable: Prettify Variables
guix-extended-command: Help
guix-find-license-definition: Package Licenses
guix-find-license-location-file: Package Licenses
guix-find-package-definition: Package Locations
guix-find-package-location-file: Package Locations
guix-find-service-definition: Service Locations
guix-find-service-location-file: Service Locations
guix-generations: Generation Commands
guix-generations-by-time: Generation Commands
guix-hash: Miscellaneous Commands
guix-help: Help
guix-hidden-packages: Package Commands
guix-info: Help
guix-installed-packages: Package Commands
guix-installed-system-packages: Package Commands
guix-installed-system-packages: System Commands
guix-installed-user-packages: Package Commands
guix-last-generations: Generation Commands
guix-last-system-generations: System Commands
guix-licenses: Package Licenses
guix-lint-checkers: Lint Checkers
guix-number-of-packages: More Package Commands
guix-obsolete-packages: Package Commands
guix-package-from-file: Package Commands
guix-package-graph: More Package Commands
guix-package-lint: Lint Checkers
guix-package-locations: Package Locations
guix-package-size: More Package Commands
guix-packages-by-license: Package Commands
guix-packages-by-location: Package Commands
guix-packages-by-name: Package Commands
guix-packages-by-name-regexp: Package Commands
guix-packages-by-regexp: Package Commands
guix-packages-from-system-config-file: Package Commands
guix-packages-from-system-config-file: System Commands
guix-prettify-mode: Prettify Mode
guix-profiles: Profile Commands
guix-pull: Miscellaneous Commands
guix-report-bug: Miscellaneous Commands
guix-service-locations: Service Locations
guix-services-by-location: Service Commands
guix-services-by-name: Service Commands
guix-services-by-regexp: Service Commands
guix-services-from-system-config-file: Service Commands
guix-services-from-system-config-file: System Commands
guix-set-current-profile: Package Commands
guix-set-current-profile: Profile Commands
guix-set-emacs-environment: Miscellaneous Commands
guix-store-dead-items: Store Item Commands
guix-store-failures: Store Item Commands
guix-store-item: Store Item Commands
guix-store-item-derivers: Store Item Commands
guix-store-item-references: Store Item Commands
guix-store-item-referrers: Store Item Commands
guix-store-item-requisites: Store Item Commands
guix-store-live-items: Store Item Commands
guix-superseded-packages: Package Commands
guix-switch-to-buffer: Help
guix-system-from-file: System From File
guix-system-generations: System Commands
guix-system-generations-by-time: System Commands
guix-system-profile: System Commands

Jump to:   G  

Previous: , Up: Top   [Contents][Index]

Variable Index

Jump to:   G  
Index Entry  Section

G
guix-about-buffer-name: Buffer Names
guix-build-log-common-map: Keymaps
guix-build-log-minor-mode-map: Keymaps
guix-build-log-mode-map: Keymaps
guix-current-profile: Profile Commands
guix-devel-keys-map: Keymaps
guix-devel-mode-map: Keymaps
guix-dot-default-arguments: Graph Configuration
guix-dot-file-name-function: Graph Configuration
guix-dot-program: Graph Configuration
guix-dry-run: Guile and Build Options
guix-ENTRY-TYPE-BUFFER-TYPE-buffer-name: Buffer Names
guix-ENTRY-TYPE-BUFFER-TYPE-format: List/Info Configuration
guix-ENTRY-TYPE-BUFFER-TYPE-mode-map: Keymaps
guix-env-var-enable-formatting: Prettify Variables
guix-file-size-string-function: Miscellaneous Configuration
guix-find-file-function: Graph Configuration
guix-guile-program: Guile and Build Options
guix-help-buffer-name: Buffer Names
guix-internal-repl-buffer-name: Buffer Names
guix-load-compiled-path: Guile and Build Options
guix-load-path: Guile and Build Options
guix-package-list-type: Package Commands
guix-package-search-params: Package Commands
guix-profiles: Profile Commands
guix-read-package-name-function: Package Locations
guix-repl-buffer-name: Buffer Names
guix-repl-use-latest: Guile and Build Options
guix-repl-use-server: Guile and Build Options
guix-run-in-shell-function: Guix Popup Interface
guix-search-paths-buffer-name: Buffer Names
guix-service-search-params: Service Commands
guix-support-dired: Miscellaneous Configuration
guix-ui-buffer-name-function: Buffer Names
guix-ui-map: Keymaps
guix-use-substitutes: Guile and Build Options

Jump to:   G  

Footnotes

(1)

It is not recommended to mix several installations (in particular, installations from Guix and MELPA), as it may lead to incompatibilities in the source (.scm) and compiled (.go) Guile files.

(2)

Note that name/version pairs cannot be used to identify packages (because a name is not necessarily unique), so Emacs-Guix 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).