diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 277 |
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 |