summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2018-08-27 18:05:49 +0200
committerLudovic Courtès <ludo@gnu.org>2018-09-02 16:51:40 +0200
commit0d39a3b98948314e135566b9315717695a9035ea (patch)
tree26531e76ed2af0c4db34ae25f100ed73b4525c63 /doc
parentfe634eaf93ba40862acdf62d7f197c6f19f0651c (diff)
Add (guix channels) and use it in (guix scripts pull).
* guix/channels.scm: New file. * Makefile.am (MODULES): Add it. * guix/scripts/pull.scm: Use it. (%default-options): Remove 'repository-url' and 'ref'. (show-help, %options): Add '--channels'. (%self-build-file, %pull-version, build-from-source) (whole-package-for-legacy, derivation->manifest-entry): Remove. These now exist in a similar form in (guix channels). (build-and-install): Change 'source' to 'instances'. Remove #:url, #:branch, and #:commit. Rewrite using 'channel-instances->manifest'. (channel-list): New procedure. (guix-pull): Parameterize %REPOSITORY-CACHE-DIRECTORY. Call 'honor-lets-encrypt-certificates!' unconditionally. Load ~/.config/guix/channels.scm. Rewrite to use (guix channels). [use-le-certs?]: Remove. * po/guix/POTFILES.in: Add (guix channels). * doc/guix.texi (Invoking guix pull): Group the description of '--url', '--commit', and '--branch'. Remove mention of 'GUIX_PULL_URL'. Add references to "Channels". Document '--channels'. (Channels): New node. (Defining Packages): Link to "Channels" instead of "Package Modules". (Invoking guix edit): Link to "Package Modules" instead of "Defining Packages". (Package Modules): Document both GUIX_PACKAGE_PATH and channels.
Diffstat (limited to 'doc')
-rw-r--r--doc/guix.texi277
1 files changed, 231 insertions, 46 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index 8611059791..ad82c67932 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -146,17 +146,18 @@ Package Management
* Packages with Multiple Outputs:: Single source package, multiple outputs.
* Invoking guix gc:: Running the garbage collector.
* Invoking guix pull:: Fetching the latest Guix and distribution.
+* Channels:: Customizing the package collection.
* Invoking guix pack:: Creating software bundles.
* Invoking guix archive:: Exporting and importing store files.
Substitutes
-* Official Substitute Server:: One particular source of substitutes.
-* Substitute Server Authorization:: How to enable or disable substitutes.
-* Substitute Authentication:: How Guix verifies substitutes.
-* Proxy Settings:: How to get substitutes via proxy.
-* Substitution Failure:: What happens when substitution fails.
-* On Trusting Binaries:: How can you trust that binary blob?
+* Official Substitute Server:: One particular source of substitutes.
+* Substitute Server Authorization:: How to enable or disable substitutes.
+* Substitute Authentication:: How Guix verifies substitutes.
+* Proxy Settings:: How to get substitutes via proxy.
+* Substitution Failure:: What happens when substitution fails.
+* On Trusting Binaries:: How can you trust that binary blob?
Programming Interface
@@ -202,7 +203,7 @@ GNU Distribution
* System Installation:: Installing the whole operating system.
* System Configuration:: Configuring the operating system.
-* Documentation:: Browsing software user manuals.
+* Documentation:: Browsing software user manuals.
* Installing Debugging Files:: Feeding the debugger.
* Security Updates:: Deploying security fixes quickly.
* Package Modules:: Packages from the programmer's viewpoint.
@@ -264,7 +265,7 @@ Services
* Audio Services:: The MPD.
* Virtualization Services:: Virtualization services.
* Version Control Services:: Providing remote access to Git repositories.
-* Game Services:: Game servers.
+* Game Services:: Game servers.
* Miscellaneous Services:: Other services.
Defining Services
@@ -1694,6 +1695,7 @@ guix package -i emacs-guix
* Packages with Multiple Outputs:: Single source package, multiple outputs.
* Invoking guix gc:: Running the garbage collector.
* Invoking guix pull:: Fetching the latest Guix and distribution.
+* Channels:: Customizing the package collection.
* Invoking guix pack:: Creating software bundles.
* Invoking guix archive:: Exporting and importing store files.
@end menu
@@ -2276,12 +2278,12 @@ pre-built package binaries, but source tarballs, for instance, which
also result from derivation builds, can be available as substitutes.
@menu
-* Official Substitute Server:: One particular source of substitutes.
-* Substitute Server Authorization:: How to enable or disable substitutes.
-* Substitute Authentication:: How Guix verifies substitutes.
-* Proxy Settings:: How to get substitutes via proxy.
-* Substitution Failure:: What happens when substitution fails.
-* On Trusting Binaries:: How can you trust that binary blob?
+* Official Substitute Server:: One particular source of substitutes.
+* Substitute Server Authorization:: How to enable or disable substitutes.
+* Substitute Authentication:: How Guix verifies substitutes.
+* Proxy Settings:: How to get substitutes via proxy.
+* Substitution Failure:: What happens when substitution fails.
+* On Trusting Binaries:: How can you trust that binary blob?
@end menu
@node Official Substitute Server
@@ -2746,7 +2748,8 @@ the distribution currently available on your local machine. To update
that distribution, along with the Guix tools, you must run @command{guix
pull}: the command downloads the latest Guix source code and package
descriptions, and deploys it. Source code is downloaded from a
-@uref{https://git-scm.com, Git} repository.
+@uref{https://git-scm.com, Git} repository, by default the official
+GNU@tie{}Guix repository, though this can be customized.
On completion, @command{guix package} will use packages and package
versions from this just-retrieved copy of Guix. Not only that, but all
@@ -2821,20 +2824,23 @@ but it supports the following options:
Produce verbose output, writing build logs to the standard error output.
@item --url=@var{url}
-Download Guix from the Git repository at @var{url}.
-
-@vindex GUIX_PULL_URL
-By default, the source is taken from its canonical Git repository at
-@code{gnu.org}, for the stable branch of Guix. To use a different source,
-set the @code{GUIX_PULL_URL} environment variable.
-
-@item --commit=@var{commit}
-Deploy @var{commit}, a valid Git commit ID represented as a hexadecimal
-string.
-
-@item --branch=@var{branch}
-Deploy the tip of @var{branch}, the name of a Git branch available on
-the repository at @var{url}.
+@itemx --commit=@var{commit}
+@itemx --branch=@var{branch}
+Download code from the specified @var{url}, at the given @var{commit} (a valid
+Git commit ID represented as a hexadecimal string), or @var{branch}.
+
+@cindex @file{channels.scm}, configuration file
+@cindex configuration file for channels
+These options are provided for convenience, but you can also specify your
+configuration in the @file{~/.config/guix/channels.scm} file or using the
+@option{--channels} option (see below).
+
+@item --channels=@var{file}
+@itemx -C @var{file}
+Read the list of channels from @var{file} instead of
+@file{~/.config/guix/channels.scm}. @var{file} must contain Scheme code that
+evaluates to a list of channel objects. @xref{Channels}, for more
+information.
@item --list-generations[=@var{pattern}]
@itemx -l [@var{pattern}]
@@ -2848,9 +2854,180 @@ Use the bootstrap Guile to build the latest Guix. This option is only
useful to Guix developers.
@end table
+The @dfn{channel} mechanism allows you to instruct @command{guix pull} which
+repository and branch to pull from, as well as @emph{additional} repositories
+containing package modules that should be deployed. @xref{Channels}, for more
+information.
+
In addition, @command{guix pull} supports all the common build options
(@pxref{Common Build Options}).
+@node Channels
+@section Channels
+
+@cindex channels
+@cindex @file{channels.scm}, configuration file
+@cindex configuration file for channels
+@cindex @command{guix pull}, configuration file
+@cindex configuration of @command{guix pull}
+Guix and its package collection are updated by running @command{guix pull}
+(@pxref{Invoking guix pull}). By default @command{guix pull} downloads and
+deploys Guix itself from the official GNU@tie{}Guix repository. This can be
+customized by defining @dfn{channels} in the
+@file{~/.config/guix/channels.scm} file. A channel specifies a URL and branch
+of a Git repository to be deployed, and @command{guix pull} can be instructed
+to pull from one or more channels. In other words, channels can be used to
+@emph{customize} and to @emph{extend} Guix, as we will see below.
+
+@subsection Using a Custom Guix Channel
+
+The channel called @code{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
+@code{example.org}, and specifically the @code{super-hacks} branch, you can
+write in @code{~/.config/guix/channels.scm} this specification:
+
+@lisp
+;; Tell 'guix pull' to use my own repo.
+(list (channel
+ (name 'guix)
+ (url "https://example.org/my-guix.git")
+ (branch "super-hacks")))
+@end lisp
+
+@noindent
+From there on, @command{guix pull} will fetch code from the @code{super-hacks}
+branch of the repository at @code{example.org}.
+
+@subsection Specifying Additional Channels
+
+@cindex extending the package collection (channels)
+@cindex personal packages (channels)
+@cindex channels, for personal packages
+You can also specify @emph{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 (@pxref{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?
+
+@c What follows stems from discussions at
+@c <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> as well as
+@c earlier discussions on guix-devel@gnu.org.
+@quotation Warning
+Before you, dear user, shout---``woow this is @emph{soooo coool}!''---and
+publish your personal channel to the world, we would like to share a few words
+of caution:
+
+@itemize
+@item
+Before publishing a channel, please consider contributing your package
+definitions to Guix proper (@pxref{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.
+
+@item
+When you maintain package definitions outside Guix, we, Guix developers,
+consider that @emph{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 @emph{not} commit to freezing APIs
+either.
+
+@item
+Corollary: if you're using an external channel and that channel breaks, please
+@emph{report the issue to the channel authors}, not to the Guix project.
+@end itemize
+
+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
+@uref{https://www.gnu.org/philosophy/free-sw.html, free software}. Please
+email us at @email{guix-devel@@gnu.org} if you'd like to discuss this.
+@end quotation
+
+Once you have a Git repository containing your own package modules, you can
+write @code{~/.config/guix/channels.scm} to instruct @command{guix pull} to
+pull from your personal channel @emph{in addition} to the default Guix
+channel(s):
+
+@vindex %default-channels
+@lisp
+;; Add my personal packages to those Guix provides.
+(cons (channel
+ (name 'my-personal-packages)
+ (url "https://example.org/personal-packages.git"))
+ %default-channels)
+@end lisp
+
+@noindent
+Note that the snippet above is (as always!) Scheme code; we use @code{cons} to
+add a channel the list of channels that the variable @code{%default-channels}
+is bound to (@pxref{Pairs, @code{cons} and lists,, guile, GNU Guile Reference
+Manual}). With this file in place, @command{guix pull} builds not only Guix
+but also the package modules from your own repository. The result in
+@file{~/.config/guix/current} is the union of Guix with your own package
+modules:
+
+@example
+$ guix pull --list-generations
+@dots{}
+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, @dots{}
+ 4 packages upgraded: emacs-racket-mode@@0.0.2-2.1b78827, @dots{}
+@end example
+
+@noindent
+The output of @command{guix pull} above shows that Generation@tie{}19 includes
+both Guix and packages from the @code{my-personal-packages} channel. Among
+the new and upgraded packages that are listed, some like @code{my-gimp} and
+@code{my-emacs-with-cool-features} might come from
+@code{my-personal-packages}, while others come from the Guix default channel.
+
+@subsection Replicating Guix
+
+@cindex pinning, channels
+@cindex replicating Guix
+@cindex reproducibility, of Guix
+The @command{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
+@file{~/.config/guix/channels.scm} that is ``pinned'' to these commits:
+
+@lisp
+;; 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")))
+@end lisp
+
+At this point the two machines run the @emph{exact same Guix}, with access to
+the @emph{exact same packages}. The output of @command{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.
+
@node Invoking guix pack
@section Invoking @command{guix pack}
@@ -3431,9 +3608,9 @@ more information on how to test package definitions, and
@ref{Invoking guix lint}, for information on how to check a definition
for style conformance.
@vindex GUIX_PACKAGE_PATH
-Lastly, @pxref{Package Modules}, for information
+Lastly, @pxref{Channels}, for information
on how to extend the distribution by adding your own package definitions
-to @code{GUIX_PACKAGE_PATH}.
+in a ``channel''.
Finally, updating the package definition to a new upstream version
can be partly automated by the @command{guix refresh} command
@@ -6255,8 +6432,8 @@ and that of Vim.
If you are using a Guix Git checkout (@pxref{Building from Git}), or
have created your own packages on @code{GUIX_PACKAGE_PATH}
-(@pxref{Defining Packages}), you will be able to edit the package
-recipes. Otherwise, you will be able to examine the read-only recipes
+(@pxref{Package Modules}), you will be able to edit the package
+recipes. In other cases, you will be able to examine the read-only recipes
for packages currently in the store.
@@ -8376,7 +8553,7 @@ For information on porting to other architectures or kernels,
@menu
* System Installation:: Installing the whole operating system.
* System Configuration:: Configuring the operating system.
-* Documentation:: Browsing software user manuals.
+* Documentation:: Browsing software user manuals.
* Installing Debugging Files:: Feeding the debugger.
* Security Updates:: Deploying security fixes quickly.
* Package Modules:: Packages from the programmer's viewpoint.
@@ -8415,7 +8592,7 @@ available.
@menu
* Limitations:: What you can expect.
* Hardware Considerations:: Supported hardware.
-* USB Stick and DVD Installation:: Preparing the installation medium.
+* USB Stick and DVD Installation:: Preparing the installation medium.
* Preparing for Installation:: Networking, partitioning, etc.
* Proceeding with the Installation:: The real thing.
* Installing GuixSD in a VM:: GuixSD playground.
@@ -10096,7 +10273,7 @@ declaration.
* Audio Services:: The MPD.
* Virtualization Services:: Virtualization services.
* Version Control Services:: Providing remote access to Git repositories.
-* Game Services:: Game servers.
+* Game Services:: Game servers.
* Miscellaneous Services:: Other services.
@end menu
@@ -22641,16 +22818,24 @@ name and module name must match. For instance, the @code{(my-packages
emacs)} module must be stored in a @file{my-packages/emacs.scm} file
relative to the load path specified with @option{--load-path} or
@code{GUIX_PACKAGE_PATH}. @xref{Modules and the File System,,,
-guile, GNU Guile Reference Manual}, for details.}. These package definitions
-will not be visible by default. Users can invoke commands such as
-@command{guix package} and @command{guix build} with the
-@code{-e} option so that they know where to find the package. Better
-yet, they can use the
-@code{-L} option of these commands to make those modules visible
-(@pxref{Invoking guix build, @code{--load-path}}), or define the
-@code{GUIX_PACKAGE_PATH} environment variable. This environment
-variable makes it easy to extend or customize the distribution and is
-honored by all the user interfaces.
+guile, GNU Guile Reference Manual}, for details.}. There are two ways to make
+these package definitions visible to the user interfaces:
+
+@enumerate
+@item
+By adding the directory containing your package modules to the search path
+with the @code{-L} flag of @command{guix package} and other commands
+(@pxref{Common Build Options}), or by setting the @code{GUIX_PACKAGE_PATH}
+environment variable described below.
+
+@item
+By defining a @dfn{channel} and configuring @command{guix pull} so that it
+pulls from it. A channel is essentially a Git repository containing package
+modules. @xref{Channels}, for more information on how to define and use
+channels.
+@end enumerate
+
+@code{GUIX_PACKAGE_PATH} works similarly to other search path variables:
@defvr {Environment Variable} GUIX_PACKAGE_PATH
This is a colon-separated list of directories to search for additional