Guix and its package collection are updated by running
(see Invoking guix pull). By default
guix pull downloads and
deploys Guix itself from the official GNU Guix repository. This can be
customized by defining channels in the
~/.config/guix/channels.scm file. A channel specifies a URL and branch
of a Git repository to be deployed, and
guix pull can be instructed
to pull from one or more channels. In other words, channels can be used to
customize and to extend Guix, as we will see below.
The channel called
guix specifies where Guix itself—its command-line
tools as well as its package collection—should be downloaded. For instance,
suppose you want to update from your own copy of the Guix repository at
example.org, and specifically the
super-hacks branch, you can
~/.config/guix/channels.scm this specification:
;; Tell 'guix pull' to use my own repo. (list (channel (name 'guix) (url "https://example.org/my-guix.git") (branch "super-hacks")))
From there on,
guix pull will fetch code from the
branch of the repository at
You can also specify additional channels to pull from. Let’s say you have a bunch of custom package variants or personal packages that you think would make little sense to contribute to the Guix project, but would like to have these packages transparently available to you at the command line. You would first write modules containing those package definitions (see Package Modules), maintain them in a Git repository, and then you and anyone else can use it as an additional channel to get packages from. Neat, no?
Warning: Before you, dear user, shout—“woow this is soooo coool!”—and publish your personal channel to the world, we would like to share a few words of caution:
- Before publishing a channel, please consider contributing your package definitions to Guix proper (see Contributing). Guix as a project is open to free software of all sorts, and packages in Guix proper are readily available to all Guix users and benefit from the project’s quality assurance process.
- When you maintain package definitions outside Guix, we, Guix developers, consider that the compatibility burden is on you. Remember that package modules and package definitions are just Scheme code that uses various programming interfaces (APIs). We want to remain free to change these APIs to keep improving Guix, possibly in ways that break your channel. We never change APIs gratuitously, but we will not commit to freezing APIs either.
- Corollary: if you’re using an external channel and that channel breaks, please report the issue to the channel authors, not to the Guix project.
You’ve been warned! Having said this, we believe external channels are a practical way to exert your freedom to augment Guix’ package collection and to share your improvements, which are basic tenets of free software. Please email us at firstname.lastname@example.org if you’d like to discuss this.
To use a channel, write
~/.config/guix/channels.scm to instruct
guix pull to pull from it in addition to the default Guix
;; Add my personal packages to those Guix provides. (cons (channel (name 'my-personal-packages) (url "https://example.org/personal-packages.git")) %default-channels)
Note that the snippet above is (as always!) Scheme code; we use
add a channel the list of channels that the variable
is bound to (see
cons and lists in GNU Guile Reference
Manual). With this file in place,
guix pull builds not only Guix
but also the package modules from your own repository. The result in
~/.config/guix/current is the union of Guix with your own package
$ guix pull --list-generations … Generation 19 Aug 27 2018 16:20:48 guix d894ab8 repository URL: https://git.savannah.gnu.org/git/guix.git branch: master commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300 my-personal-packages dd3df5e repository URL: https://example.org/personal-packages.git branch: master commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb 11 new packages: my-gimp, my-emacs-with-cool-features, … 4 packages upgraded: email@example.com, …
The output of
guix pull above shows that Generation 19 includes
both Guix and packages from the
my-personal-packages channel. Among
the new and upgraded packages that are listed, some like
my-emacs-with-cool-features might come from
my-personal-packages, while others come from the Guix default channel.
To create a channel, create a Git repository containing your own package
modules and make it available. The repository can contain anything, but a
useful channel will contain Guile modules that export packages. Once you
start using a channel, Guix will behave as if the root directory of that
channel’s Git repository has been added to the Guile load path (see Load
Paths in GNU Guile Reference Manual). For example, if your channel
contains a file at my-packages/my-tools.scm that defines a Guile
module, then the module will be available under the name
my-tools), and you will be able to use it like any other module
(see Modules in GNU Guile Reference Manual).
Channel authors may decide to augment a package collection provided by other channels. They can declare their channel to be dependent on other channels in a meta-data file .guix-channel, which is to be placed in the root of the channel repository.
The meta-data file should contain a simple S-expression like this:
(channel (version 0) (dependencies (channel (name some-collection) (url "https://example.org/first-collection.git")) (channel (name some-other-collection) (url "https://example.org/second-collection.git") (branch "testing"))))
In the above example this channel is declared to depend on two other channels, which will both be fetched automatically. The modules provided by the channel will be compiled in an environment where the modules of all these declared channels are available.
For the sake of reliability and maintainability, you should avoid dependencies on channels that you don’t control, and you should aim to keep the number of dependencies to a minimum.
As a channel author, you may want to keep your channel modules in a sub-directory. If your modules are in the sub-directory guix, you must add a meta-data file .guix-channel that contains:
(channel (version 0) (directory "guix"))
guix pull --list-generations output above shows precisely which
commits were used to build this instance of Guix. We can thus replicate it,
say, on another machine, by providing a channel specification in
~/.config/guix/channels.scm that is “pinned” to these commits:
;; Deploy specific commits of my channels of interest. (list (channel (name 'guix) (url "https://git.savannah.gnu.org/git/guix.git") (commit "d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300")) (channel (name 'my-personal-packages) (url "https://example.org/personal-packages.git") (branch "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))
guix describe --format=channels command can even generate this
list of channels directly (see Invoking guix describe).
At this point the two machines run the exact same Guix, with access to
the exact same packages. The output of
guix build gimp on
one machine will be exactly the same, bit for bit, as the output of the same
command on the other machine. It also means both machines have access to all
the source code of Guix and, transitively, to all the source code of every
package it defines.
This gives you super powers, allowing you to track the provenance of binary artifacts with very fine grain, and to reproduce software environments at will—some sort of “meta reproducibility” capabilities, if you will. See Inferiors, for another way to take advantage of these super powers.