From debbugs-submit-bounces@debbugs.gnu.org Thu Sep 17 21:45:23 2020 Received: (at 43482) by debbugs.gnu.org; 18 Sep 2020 01:45:23 +0000 Received: from localhost ([127.0.0.1]:40184 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kJ5Sk-00037M-5I for submit@debbugs.gnu.org; Thu, 17 Sep 2020 21:45:23 -0400 Received: from mail-wm1-f48.google.com ([209.85.128.48]:36087) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kJ5Sf-00036h-U9 for 43482@debbugs.gnu.org; Thu, 17 Sep 2020 21:45:19 -0400 Received: by mail-wm1-f48.google.com with SMTP id z9so3909818wmk.1 for <43482@debbugs.gnu.org>; Thu, 17 Sep 2020 18:45:17 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=xgGPcSMr+SVy0zGHHD+8A5Be4P4r5ka8lxmvLC6gOJ0=; b=N798lsukEdQKIQgVSierJX0iLxcEdIGIScaZsDbNc2yvMgw41DwNawmPUmGm9TdG87 jTGrbcePLRdLFnDYJpSN5iZRwp+opGc4iiyY40RoYL26LZ4tL6i3UdyRiUiT/w702b0s 3RSLon39Mcz3nWDbvr6DsA2FTLuQ+etH2xjPctIJGiT4kL+l8vV9hA9FhSE3JXG/5vTD h9dpQzD44w6EyUSE+uWh5TxmeT5iC49dvnF/1JCDVxJ+KUkX/LXwN6XEuwpveSsK3Vym ehADqU1rGoiq8Q62FVSXc1AQtgGv0lty+Bw8bJ6+zU0LSPxiOMvZ1eEh1M+Q7hgoJ0BT LN+A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=xgGPcSMr+SVy0zGHHD+8A5Be4P4r5ka8lxmvLC6gOJ0=; b=JtNKfcG1B5DxAHNj3ervpiprSOU+014tZCwo78mC/bg0vo4LYHOakyBNHRv1+xnoQE OC+EApq/FXsKZYZYyHz/LBPB9GJ7tFXPWT51fm97R99qbA1T2zKUyY52G7oiB/x5zxna jTjpLi1vQuXKP4JMrnTWEN60tGE4uhvPPVVsmyumMhlErlXSh/Qp27ixmNAGHfJd5Z00 bnTF3Z8hCswl3BV8ijEHcbL+K9RAjBldNPAVqMz8XpYDC8IOOh2vnbkl0L4FqZZVJU99 1mLYq/5YRe5JRyuQPYeHGayUf6dfFK96JUudYPJxXlhlGIDb5/MnzE1N74sMOoELS1L/ 7QQA== X-Gm-Message-State: AOAM533VrtMP2ELV2Svu9aFPjAnwnSzXkVg9k3cwBOhifR8gv2vfJdvl 54WAeoMqWPpYSSb+NURovX9S8+DONqY= X-Google-Smtp-Source: ABdhPJyORp/yU+fEN9j67fB7dXKD7Kf0T5fkPeIVdF+ST2NQA4Hdg7NRHZMjBMcfhCjolmk2Ti1w0w== X-Received: by 2002:a1c:7911:: with SMTP id l17mr12699909wme.179.1600393511243; Thu, 17 Sep 2020 18:45:11 -0700 (PDT) Received: from lili.univ-paris-diderot.fr ([88.126.110.68]) by smtp.gmail.com with ESMTPSA id q15sm2144919wrr.8.2020.09.17.18.45.10 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 17 Sep 2020 18:45:10 -0700 (PDT) From: zimoun To: 43482@debbugs.gnu.org Subject: [PATCH 3/3] doc: Reorder the "Channels" section. Date: Fri, 18 Sep 2020 03:45:02 +0200 Message-Id: <20200918014502.6081-3-zimon.toutoune@gmail.com> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20200918014502.6081-1-zimon.toutoune@gmail.com> References: <20200918014502.6081-1-zimon.toutoune@gmail.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 43482 Cc: zimoun X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) * doc/guix.texi (Channels): Reorder the section. Minor tweaks to keep uniformity. Update the master menu. --- doc/guix.texi | 342 ++++++++++++++++++++++++++------------------------ 1 file changed, 177 insertions(+), 165 deletions(-) diff --git a/doc/guix.texi b/doc/guix.texi index f30faf257a..015c8c9736 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -228,15 +228,16 @@ Substitutes Channels +* Specifying Additional Channels:: Extending the package collection. +* Using a Custom Guix Channel:: Using a customized Guix. +* Replicating Guix:: Running the @emph{exact same} Guix. * Channel Authentication:: How Guix verifies what it fetches. -* Using a Custom Guix Channel:: Using a customized Guix. -* Specifying Additional Channels:: Extending the package collection. -* Declaring Channel Dependencies:: Declaring channel dependencies. -* Package Modules in a Sub-directory:: Package Modules in a Sub-directory. -* Specifying Channel Authorizations:: Specifying Channel Authorizations. * Primary URL:: Distinguishing mirror to original. +* Writing custom channels:: How to setup your own channel. +* Package Modules in a Sub-directory:: Specifying the channel's package modules location. +* Declaring Channel Dependencies:: How to depend on other channels. +* Specifying Channel Authorizations:: Defining channel authors authorizations. * Writing Channel News:: Communicating information to channel's users. -* Replicating Guix:: Running the @emph{exact same} Guix. Development @@ -4216,20 +4217,135 @@ customized by defining @dfn{channels} in the 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. -Before that, some security considerations. +Guix is able to take into account security concerns and deal with authenticated +updates. @menu +* Specifying Additional Channels:: Extending the package collection. +* Using a Custom Guix Channel:: Using a customized Guix. +* Replicating Guix:: Running the @emph{exact same} Guix. * Channel Authentication:: How Guix verifies what it fetches. -* Using a Custom Guix Channel:: Using a customized Guix. -* Specifying Additional Channels:: Extending the package collection. -* Declaring Channel Dependencies:: Declaring channel dependencies. -* Package Modules in a Sub-directory:: Package Modules in a Sub-directory. -* Specifying Channel Authorizations:: Specifying Channel Authorizations. * Primary URL:: Distinguishing mirror to original. +* Writing custom channels:: How to setup your own channel. +* Package Modules in a Sub-directory:: Specifying the channel's package modules location. +* Declaring Channel Dependencies:: How to depend on other channels. +* Specifying Channel Authorizations:: Defining channel authors authorizations. * Writing Channel News:: Communicating information to channel's users. -* Replicating Guix:: Running the @emph{exact same} Guix. @end menu +@node Specifying Additional Channels +@subsection Specifying Additional Channels + +@cindex extending the package collection (channels) +@cindex variant packages (channels) +You can specify @emph{additional channels} to pull from. To use a channel, write +@code{~/.config/guix/channels.scm} to instruct @command{guix pull} to pull from it +@emph{in addition} to the default Guix channel(s): + +@vindex %default-channels +@lisp +;; Add variant packages to those Guix provides. +(cons (channel + (name 'variant-packages) + (url "https://example.org/variant-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 + variant-packages dd3df5e + repository URL: https://example.org/variant-packages.git + branch: master + commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb + 11 new packages: variant-gimp, variant-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{variant-personal-packages} channel. Among +the new and upgraded packages that are listed, some like @code{variant-gimp} and +@code{variant-emacs-with-cool-features} might come from +@code{variant-packages}, while others come from the Guix default channel. + +@node Using a Custom Guix Channel +@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 another 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 another repo. +(list (channel + (name 'guix) + (url "https://example.org/another-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}. The authentication concern is +addressed below ((@pxref{Channel Authentication}). + +@node Replicating Guix +@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 "6298c3ffd9654d3231a6f25390b056483e8f407c")) + (channel + (name 'variant-packages) + (url "https://example.org/variant-packages.git") + (commit "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb"))) +@end lisp + +The @command{guix describe --format=channels} command can even generate this +list of channels directly (@pxref{Invoking guix describe}). The resulting +file can be used with the -C options of @command{guix pull} +(@pxref{Invoking guix pull}) or @command{guix time-machine} +(@pxref{Invoking guix time-machine}). + +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. +@xref{Inferiors}, for another way to take advantage of these super powers. + @node Channel Authentication @subsection Channel Authentication @@ -4248,8 +4364,8 @@ along these lines: @lisp (channel - (name 'my-channel) - (url "https://example.org/my-channel.git") + (name 'some-channel) + (url "https://example.org/some-channel.git") (introduction (make-channel-introduction "6f0d8cc0d88abb59c324b2990bfee2876016bb86" @@ -4270,40 +4386,41 @@ introduction from a trusted source since that is the root of your trust. If you're curious about the authentication mechanics, read on! -@node Using a Custom Guix Channel -@subsection Using a Custom Guix Channel +@cindex primary URL, channels +@node Primary URL +@subsection Primary URL -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: +Channel authors can indicate the primary URL of their channel's Git +repository in the @file{.guix-channel} file, like so: @lisp -;; Tell 'guix pull' to use my own repo. -(list (channel - (name 'guix) - (url "https://example.org/my-guix.git") - (branch "super-hacks"))) +(channel + (version 0) + (url "https://example.org/guix.git")) @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}. +This allows @command{guix pull} to determine whether it is pulling code +from a mirror of the channel; when that is the case, it warns the user +that the mirror might be stale and displays the primary URL. That way, +users cannot be tricked into fetching code from a stale mirror that does +not receive security updates. -@node Specifying Additional Channels -@subsection Specifying Additional Channels +This feature only makes sense for authenticated repositories, such as +the official @code{guix} channel, for which @command{guix pull} ensures +the code it fetches is authentic. -@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? +@node Writing custom channels +@subsection Writing custom channels + +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 as well as @@ -4342,51 +4459,6 @@ share your improvements, which are basic tenets of email us at @email{guix-devel@@gnu.org} if you'd like to discuss this. @end quotation -To use a channel, write @code{~/.config/guix/channels.scm} to instruct -@command{guix pull} to pull from it @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. - 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 @@ -4398,6 +4470,24 @@ module, then the module will be available under the name @code{(my-packages my-tools)}, and you will be able to use it like any other module (@pxref{Modules,,, guile, GNU Guile Reference Manual}). +Last, as a channel author, you may want to run an authenticated channel +(@pxref{Channel Authentication}), then @pxref{Specifying Channel +Authorizations} for details. + +@cindex subdirectory, channels +@node Package Modules in a Sub-directory +@subsection Package Modules in a Sub-directory + +As a channel author, you may want to keep your channel modules in a +sub-directory. If your modules are in the sub-directory @file{guix}, you must +add a meta-data file @file{.guix-channel} that contains: + +@lisp +(channel + (version 0) + (directory "guix")) +@end lisp + @cindex dependencies, channels @cindex meta-data, channels @node Declaring Channel Dependencies @@ -4415,7 +4505,7 @@ The meta-data file should contain a simple S-expression like this: (version 0) (dependencies (channel - (name some-collection) + (name 'some-collection) (url "https://example.org/first-collection.git") ;; The 'introduction' bit below is optional: you would @@ -4426,7 +4516,7 @@ The meta-data file should contain a simple S-expression like this: (commit "a8883b58dc82e167c96506cf05095f37c2c2c6cd") (signer "CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5")))) (channel - (name some-other-collection) + (name 'some-other-collection) (url "https://example.org/second-collection.git") (branch "testing")))) @end lisp @@ -4440,20 +4530,6 @@ 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. -@cindex subdirectory, channels -@node Package Modules in a Sub-directory -@subsection Package Modules in a Sub-directory - -As a channel author, you may want to keep your channel modules in a -sub-directory. If your modules are in the sub-directory @file{guix}, you must -add a meta-data file @file{.guix-channel} that contains: - -@lisp -(channel - (version 0) - (directory "guix")) -@end lisp - @cindex channel authorizations @node Specifying Channel Authorizations @subsection Specifying Channel Authorizations @@ -4555,29 +4631,6 @@ authentication! Pay attention to merges in particular: merge commits are considered authentic if and only if they are signed by a key present in the @file{.guix-authorizations} file of @emph{both} branches. -@cindex primary URL, channels -@node Primary URL -@subsection Primary URL - -Channel authors can indicate the primary URL of their channel's Git -repository in the @file{.guix-channel} file, like so: - -@lisp -(channel - (version 0) - (url "https://example.org/guix.git")) -@end lisp - -This allows @command{guix pull} to determine whether it is pulling code -from a mirror of the channel; when that is the case, it warns the user -that the mirror might be stale and displays the primary URL. That way, -users cannot be tricked into fetching code from a stale mirror that does -not receive security updates. - -This feature only makes sense for authenticated repositories, such as -the official @code{guix} channel, for which @command{guix pull} ensures -the code it fetches is authentic. - @cindex news, for channels @node Writing Channel News @subsection Writing Channel News @@ -4647,47 +4700,6 @@ xgettext -o news.po -l scheme -ken etc/news.txt To sum up, yes, you could use your channel as a blog. But beware, this is @emph{not quite} what your users might expect. -@node Replicating Guix -@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 "6298c3ffd9654d3231a6f25390b056483e8f407c")) - (channel - (name 'my-personal-packages) - (url "https://example.org/personal-packages.git") - (commit "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb"))) -@end lisp - -The @command{guix describe --format=channels} command can even generate this -list of channels directly (@pxref{Invoking guix describe}). The resulting -file can be used with the -C options of @command{guix pull} -(@pxref{Invoking guix pull}) or @command{guix time-machine} -(@pxref{Invoking guix time-machine}). - -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. -@xref{Inferiors}, for another way to take advantage of these super powers. - @node Invoking guix time-machine @section Invoking @command{guix time-machine} -- 2.28.0