[PATCH 0/3] doc: Reorder "Channels" section

  • Done
  • quality assurance status badge
Details
2 participants
  • Ludovic Courtès
  • zimoun
Owner
unassigned
Submitted by
zimoun
Severity
normal
Z
Z
zimoun wrote on 18 Sep 2020 03:37
(address . guix-patches@gnu.org)(name . zimoun)(address . zimon.toutoune@gmail.com)
20200918013744.3448-1-zimon.toutoune@gmail.com
Dear,

As discussed here [1], the Channels is modified to satisfy a more logical
order, at least mine. :-)

The patch 0003 can be hard to review. Basically, I have moved the sections:

5.6 Invoking @command{guix pull}
5.7 Channels
5.7.1 Specifying Additional Channels
5.7.2 Using a Custom Guix Channel
5.7.3 Replicating Guix
5.7.4 Channel Authentication
5.7.5 Primary URL
5.7.6 Writing custom channels
5.7.7 Package Modules in a Sub-directory
5.7.8 Declaring Channel Dependencies
5.7.9 Specifying Channel Authorizations
5.7.10 Writing Channel News
5.8 Invoking @command{guix time-machine}

And I did some minor tweaks trying to have user vs developer of channels. Say
that from 5.7.1 to 5.7.5, the channel are collection of "variants". Then it
becomes "your own channel".

I added these words which deserve a better wording, I guess.

Toggle snippet (5 lines)
Last, as a channel author, you may want to run an authenticated channel
(@pxref{Channel Authentication}), then @pxref{Specifying Channel
Authorizations} for details.

At the end of the section "Writing custom channels".

And after some thinking, I find better to have "guix pull" and time-machine
visible from Package Management section:


Well, that is a start. :-)



All the best,
simon

zimoun (3):
doc: Update the master menu.
doc: Add the "Channels" section menu.
doc: Reorder the "Channels" section.

doc/guix.texi | 353 +++++++++++++++++++++++++++++---------------------
1 file changed, 202 insertions(+), 151 deletions(-)


base-commit: 679d5e6b3dcac4ee1f419c04b3719fead0bd9ee5
--
2.28.0
Z
Z
zimoun wrote on 18 Sep 2020 03:45
[PATCH 1/3] doc: Update the master menu.
(address . 43482@debbugs.gnu.org)(name . zimoun)(address . zimon.toutoune@gmail.com)
20200918014502.6081-1-zimon.toutoune@gmail.com
* doc/guix.texi: Update the master menu.
---
doc/guix.texi | 13 ++++++++++---
1 file changed, 10 insertions(+), 3 deletions(-)

Toggle diff (68 lines)
diff --git a/doc/guix.texi b/doc/guix.texi
index 88128a4b3a..5a1f2e3bc3 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -178,6 +178,7 @@ Installation
* Setting Up the Daemon:: Preparing the build daemon's environment.
* Invoking guix-daemon:: Running the build daemon.
* Application Setup:: Application-specific setup.
+* Upgrading Guix:: Upgrading Guix and its build daemon.
Setting Up the Daemon
@@ -197,8 +198,6 @@ System Installation
* Installing Guix in a VM:: Guix System playground.
* Building the Installation Image:: How this comes to be.
-Getting Started
-
Manual Installation
* Keyboard Layout and Networking and Partitioning:: Initial setup.
@@ -232,6 +231,7 @@ Development
* Invoking guix environment:: Setting up development environments.
* Invoking guix pack:: Creating software bundles.
* The GCC toolchain:: Working with languages supported by GCC.
+* Invoking guix git authenticate:: Authenticating Git repositories.
Programming Interface
@@ -300,6 +300,7 @@ Services
* Scheduled Job Execution:: The mcron service.
* Log Rotation:: The rottlog service.
* Networking Services:: Network setup, SSH daemon, etc.
+* Unattended Upgrades:: Automated system upgrades.
* X Window:: Graphical display.
* Printing Services:: Local and remote printer support.
* Desktop Services:: D-Bus and desktop services.
@@ -310,6 +311,7 @@ Services
* Telephony Services:: Telephony services.
* Monitoring Services:: Monitoring services.
* Kerberos Services:: Kerberos services.
+* LDAP Services:: LDAP services.
* Web Services:: Web servers.
* Certificate Services:: TLS certificates via Let's Encrypt.
* DNS Services:: DNS daemons.
@@ -324,7 +326,7 @@ Services
* PAM Mount Service:: Service to mount volumes when logging in.
* Guix Services:: Services relating specifically to Guix.
* Linux Services:: Services tied to the Linux kernel.
-* Hurd Services:: Services specific to a Hurd System.
+* Hurd Services:: Services specific for a Hurd System.
* Miscellaneous Services:: Other services.
Defining Services
@@ -334,6 +336,11 @@ Defining Services
* Service Reference:: API reference.
* Shepherd Services:: A particular type of service.
+Bootstrapping
+
+* Reduced Binary Seed Bootstrap:: A Bootstrap worthy of GNU.
+* Preparing to Use the Bootstrap Binaries:: Building that what matters most.
+
@end detailmenu
@end menu
--
2.28.0
Z
Z
zimoun wrote on 18 Sep 2020 03:45
[PATCH 2/3] doc: Add the "Channels" section menu.
(address . 43482@debbugs.gnu.org)(name . zimoun)(address . zimon.toutoune@gmail.com)
20200918014502.6081-2-zimon.toutoune@gmail.com
* doc/guix.texi (Channels): Add the section menu.
---
doc/guix.texi | 33 +++++++++++++++++++++++++++++++++
1 file changed, 33 insertions(+)

Toggle diff (109 lines)
diff --git a/doc/guix.texi b/doc/guix.texi
index 5a1f2e3bc3..f30faf257a 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -226,6 +226,18 @@ Substitutes
* Substitution Failure:: What happens when substitution fails.
* On Trusting Binaries:: How can you trust that binary blob?
+Channels
+
+* 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 Channel News:: Communicating information to channel's users.
+* Replicating Guix:: Running the @emph{exact same} Guix.
+
Development
* Invoking guix environment:: Setting up development environments.
@@ -4206,6 +4218,19 @@ 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.
+@menu
+* 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 Channel News:: Communicating information to channel's users.
+* Replicating Guix:: Running the @emph{exact same} Guix.
+@end menu
+
+@node Channel Authentication
@subsection Channel Authentication
@anchor{channel-authentication}
@@ -4245,6 +4270,7 @@ 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
The channel called @code{guix} specifies where Guix itself---its command-line
@@ -4265,6 +4291,7 @@ write in @code{~/.config/guix/channels.scm} this specification:
From there on, @command{guix pull} will fetch code from the @code{super-hacks}
branch of the repository at @code{example.org}.
+@node Specifying Additional Channels
@subsection Specifying Additional Channels
@cindex extending the package collection (channels)
@@ -4373,6 +4400,7 @@ my-tools)}, and you will be able to use it like any other module
@cindex dependencies, channels
@cindex meta-data, channels
+@node Declaring Channel Dependencies
@subsection Declaring Channel Dependencies
Channel authors may decide to augment a package collection provided by other
@@ -4413,6 +4441,7 @@ 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
@@ -4426,6 +4455,7 @@ add a meta-data file @file{.guix-channel} that contains:
@end lisp
@cindex channel authorizations
+@node Specifying Channel Authorizations
@subsection Specifying Channel Authorizations
@anchor{channel-authorizations}
@@ -4526,6 +4556,7 @@ 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
@@ -4548,6 +4579,7 @@ 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
Channel authors may occasionally want to communicate to their users
@@ -4615,6 +4647,7 @@ 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
--
2.28.0
Z
Z
zimoun wrote on 18 Sep 2020 03:45
[PATCH 3/3] doc: Reorder the "Channels" section.
(address . 43482@debbugs.gnu.org)(name . zimoun)(address . zimon.toutoune@gmail.com)
20200918014502.6081-3-zimon.toutoune@gmail.com
* 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(-)

Toggle diff (444 lines)
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 <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> 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
L
L
Ludovic Courtès wrote on 24 Sep 2020 16:51
Re: [bug#43482] [PATCH 1/3] doc: Update the master menu.
(name . zimoun)(address . zimon.toutoune@gmail.com)(address . 43482@debbugs.gnu.org)
87k0wj8bz6.fsf@gnu.org
Hi,

zimoun <zimon.toutoune@gmail.com> skribis:

Toggle quote (2 lines)
> * doc/guix.texi: Update the master menu.

LGTM!

How come it got this much out of sync? How did you update it? IME the
Emacs thingie gets confused when some but not all the top-level nodes
are in separate files.

Thanks,
Ludo’.
L
L
Ludovic Courtès wrote on 24 Sep 2020 16:52
Re: [bug#43482] [PATCH 2/3] doc: Add the "Channels" section menu.
(name . zimoun)(address . zimon.toutoune@gmail.com)(address . 43482@debbugs.gnu.org)
87ft778bx9.fsf@gnu.org
zimoun <zimon.toutoune@gmail.com> skribis:

Toggle quote (2 lines)
> * doc/guix.texi (Channels): Add the section menu.

[...]

Toggle quote (3 lines)
> +@node Channel Authentication
> @subsection Channel Authentication

What I had in mind was also to move everything one level higher:
@section becomes @chapter, @subsection becomes @section, etc.

WDYT?
L
L
Ludovic Courtès wrote on 24 Sep 2020 16:59
Re: [bug#43482] [PATCH 3/3] doc: Reorder the "Channels" section.
(name . zimoun)(address . zimon.toutoune@gmail.com)(address . 43482@debbugs.gnu.org)
874knn8bl0.fsf@gnu.org
zimoun <zimon.toutoune@gmail.com> skribis:

Toggle quote (4 lines)
> * doc/guix.texi (Channels): Reorder the section.
> Minor tweaks to keep uniformity.
> Update the master menu.

It would be nice if you could better describe what’s moved where since
looking at the diff doesn’t help understand it.

Toggle quote (3 lines)
> +@node Writing custom channels
> +@subsection Writing custom channels

Should be “Writing Custom Channels”.

Maybe “Creating a Channel” is more to the point actually?

Toggle quote (11 lines)
> 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.

Maybe something like:

As a channel author, consider bundling authentication material with
your channel so that users can authenticate it. @xref{Channel
Authentication}, and @ref{Specifying Channel Authorizations}, for
info on how to do it.

(Note: @pxref cannot be used in the middle of a sentence like you did
above. I always end up re-reading the Texinfo manual to find which
cross-reference command to use in which context…)

Could you send updated patches?

Thanks!

Ludo’.
Z
Z
zimoun wrote on 24 Sep 2020 17:05
Re: [bug#43482] [PATCH 2/3] doc: Add the "Channels" section menu.
(name . Ludovic Courtès)(address . ludo@gnu.org)(address . 43482@debbugs.gnu.org)
CAJ3okZ0+xJniG=Hp0tDoBaJDF77O+bgJKf49KuST7qr8F+Y+UQ@mail.gmail.com
On Thu, 24 Sep 2020 at 16:52, Ludovic Courtès <ludo@gnu.org> wrote:

Toggle quote (6 lines)
> > +@node Channel Authentication
> > @subsection Channel Authentication
>
> What I had in mind was also to move everything one level higher:
> @section becomes @chapter, @subsection becomes @section, etc.

I had that in mind too. After I did the change (subsection->section,
etc.), then I was not convinced, so I just added the '@node'.
Concretely, I do not have a strong opinion. Let's rebase with this
big move. :-)

However, moving "guix pull" and "guix time-machine" to this section
does not appear to me "logical" and should stay under Package
management. Especially with the "one level higher" move. WDYT?

Cheers,
simon
Z
Z
zimoun wrote on 24 Sep 2020 17:13
Re: [bug#43482] [PATCH 3/3] doc: Reorder the "Channels" section.
(name . Ludovic Courtès)(address . ludo@gnu.org)(address . 43482@debbugs.gnu.org)
CAJ3okZ0wC9S0-rgKuvuCgqSwshHs0XM7nHkTcrf8OiHbwU1ocw@mail.gmail.com
Hi,

Thank you for the review.

On Thu, 24 Sep 2020 at 16:59, Ludovic Courtès <ludo@gnu.org> wrote:

Toggle quote (7 lines)
> > * doc/guix.texi (Channels): Reorder the section.
> > Minor tweaks to keep uniformity.
> > Update the master menu.
>
> It would be nice if you could better describe what’s moved where since
> looking at the diff doesn’t help understand it.

I will try to do my best. :-)


Toggle quote (7 lines)
> > +@node Writing custom channels
> > +@subsection Writing custom channels
>
> Should be “Writing Custom Channels”.
>
> Maybe “Creating a Channel” is more to the point actually?

Ok.


Toggle quote (11 lines)
> > +Last, as a channel author, you may want to run an authenticated channel
> > +(@pxref{Channel Authentication}), then @pxref{Specifying Channel
> > +Authorizations} for details.
>
> Maybe something like:
>
> As a channel author, consider bundling authentication material with
> your channel so that users can authenticate it. @xref{Channel
> Authentication}, and @ref{Specifying Channel Authorizations}, for
> info on how to do it.

Ok.

Toggle quote (4 lines)
> (Note: @pxref cannot be used in the middle of a sentence like you did
> above. I always end up re-reading the Texinfo manual to find which
> cross-reference command to use in which context…)

Thanks for the explanations.


Toggle quote (2 lines)
> Could you send updated patches?

Ok.


Cheers,
simon
Z
Z
zimoun wrote on 24 Sep 2020 17:28
Re: [bug#43482] [PATCH 1/3] doc: Update the master menu.
(name . Ludovic Courtès)(address . ludo@gnu.org)(address . 43482@debbugs.gnu.org)
CAJ3okZ37twEXmpC5a3prY78J+3bboTy3iBvZgGHe7Y6wob-2GQ@mail.gmail.com
On Thu, 24 Sep 2020 at 16:51, Ludovic Courtès <ludo@gnu.org> wrote:

Toggle quote (4 lines)
> How come it got this much out of sync? How did you update it? IME the
> Emacs thingie gets confused when some but not all the top-level nodes
> are in separate files.

I do not remember exactly how. Well, I have used the 'menu-bar' since
I never remember the TexInfo keys.
Then, I tried 'texinfo-master-menu' and 'texinfo-every-node-update'
and 'texinfo-all-menus-update' and manually checked with Magit the
diff.

For example, this commit b460ba7992 adds one node but does not update
the master menu; the TeXInfo workflow is a bit tedious and the mistake
always happens somehow.

Cheers,
simon
L
L
Ludovic Courtès wrote on 25 Sep 2020 11:20
Re: [bug#43482] [PATCH 2/3] doc: Add the "Channels" section menu.
(name . zimoun)(address . zimon.toutoune@gmail.com)(address . 43482@debbugs.gnu.org)
871riq43hs.fsf@gnu.org
Hi,

zimoun <zimon.toutoune@gmail.com> skribis:

Toggle quote (11 lines)
> On Thu, 24 Sep 2020 at 16:52, Ludovic Courtès <ludo@gnu.org> wrote:
>
>> > +@node Channel Authentication
>> > @subsection Channel Authentication
>>
>> What I had in mind was also to move everything one level higher:
>> @section becomes @chapter, @subsection becomes @section, etc.
>
> I had that in mind too. After I did the change (subsection->section,
> etc.), then I was not convinced, so I just added the '@node'.

I think moving one level higher can help. More generally, I think it’s
a bad sign when a manual as few chapters and many subsubsubsections; it
makes it harder to see what the main topics are. It’s a problem we have
here (the Guile manual is worse in that respect :-)).

Toggle quote (4 lines)
> However, moving "guix pull" and "guix time-machine" to this section
> does not appear to me "logical" and should stay under Package
> management. Especially with the "one level higher" move. WDYT?

We’ll see that later. :-)

Thanks,
Ludo’.
Z
Z
zimoun wrote on 25 Sep 2020 22:00
[PATCH v2 1/2] doc: Update the master menu.
(address . 43482@debbugs.gnu.org)
20200925200055.8908-1-zimon.toutoune@gmail.com
* doc/guix.texi: Update the master menu.
---
doc/guix.texi | 13 ++++++++++---
1 file changed, 10 insertions(+), 3 deletions(-)

Toggle diff (70 lines)
diff --git a/doc/guix.texi b/doc/guix.texi
index a66ab82b31..bc72373d80 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -179,6 +179,7 @@ Installation
* Setting Up the Daemon:: Preparing the build daemon's environment.
* Invoking guix-daemon:: Running the build daemon.
* Application Setup:: Application-specific setup.
+* Upgrading Guix:: Upgrading Guix and its build daemon.
Setting Up the Daemon
@@ -198,8 +199,6 @@ System Installation
* Installing Guix in a VM:: Guix System playground.
* Building the Installation Image:: How this comes to be.
-Getting Started
-
Manual Installation
* Keyboard Layout and Networking and Partitioning:: Initial setup.
@@ -233,6 +232,7 @@ Development
* Invoking guix environment:: Setting up development environments.
* Invoking guix pack:: Creating software bundles.
* The GCC toolchain:: Working with languages supported by GCC.
+* Invoking guix git authenticate:: Authenticating Git repositories.
Programming Interface
@@ -301,6 +301,7 @@ Services
* Scheduled Job Execution:: The mcron service.
* Log Rotation:: The rottlog service.
* Networking Services:: Network setup, SSH daemon, etc.
+* Unattended Upgrades:: Automated system upgrades.
* X Window:: Graphical display.
* Printing Services:: Local and remote printer support.
* Desktop Services:: D-Bus and desktop services.
@@ -311,6 +312,7 @@ Services
* Telephony Services:: Telephony services.
* Monitoring Services:: Monitoring services.
* Kerberos Services:: Kerberos services.
+* LDAP Services:: LDAP services.
* Web Services:: Web servers.
* Certificate Services:: TLS certificates via Let's Encrypt.
* DNS Services:: DNS daemons.
@@ -325,7 +327,7 @@ Services
* PAM Mount Service:: Service to mount volumes when logging in.
* Guix Services:: Services relating specifically to Guix.
* Linux Services:: Services tied to the Linux kernel.
-* Hurd Services:: Services specific to a Hurd System.
+* Hurd Services:: Services specific for a Hurd System.
* Miscellaneous Services:: Other services.
Defining Services
@@ -335,6 +337,11 @@ Defining Services
* Service Reference:: API reference.
* Shepherd Services:: A particular type of service.
+Bootstrapping
+
+* Reduced Binary Seed Bootstrap:: A Bootstrap worthy of GNU.
+* Preparing to Use the Bootstrap Binaries:: Building that what matters most.
+
@end detailmenu
@end menu

base-commit: 3e5ed76df5ba12be22c6360abd83f328c3613ae0
--
2.28.0
Z
Z
zimoun wrote on 25 Sep 2020 22:00
[PATCH v2 2/2] doc: Promote "Channels" as chapter and reorder.
(address . 43482@debbugs.gnu.org)
20200925200055.8908-2-zimon.toutoune@gmail.com
The sectioning becomes:

1. Specifying Additional Channels (was 3.)
2. Using a Custom Guix Channel (was 2.)
3. Replicating Guix (was 9.)
4. Channel Authentication (was 1.)
5. Primary URL (was 7.)
6. Creating a Channel (reworded)
7. Package Modules in a Sub-directory (was 5.)
8. Declaring Channel Dependencies (was 4.)
9. Specifying Channel Authorizations (was 6.)
10. Writing Channel News (was 8.)

* doc/guix.texi (Channels): Move section to chapter.
Reorder the chapter.
Minor tweaks to keep uniformity.
Update the master menu.
---
doc/guix.texi | 1587 +++++++++++++++++++++++++------------------------
1 file changed, 817 insertions(+), 770 deletions(-)

Toggle diff (408 lines)
diff --git a/doc/guix.texi b/doc/guix.texi
index bc72373d80..ef10785316 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -147,6 +147,7 @@ Project}.
* System Installation:: Installing the whole operating system.
* Getting Started:: Your first steps.
* Package Management:: Package installation, upgrade, etc.
+* Channels:: Customizing the package collection.
* Development:: Guix-aided software development.
* Programming Interface:: Using Guix in Scheme.
* Utilities:: Package management commands.
@@ -212,7 +213,6 @@ 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 time-machine:: Running an older revision of Guix.
* Inferiors:: Interacting with another revision of Guix.
* Invoking guix describe:: Display information about your Guix revision.
@@ -227,6 +227,19 @@ Substitutes
* Substitution Failure:: What happens when substitution fails.
* On Trusting Binaries:: How can you trust that binary blob?
+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.
+* Primary URL:: Distinguishing mirror to original.
+* Creating a Channel:: How to write your custom 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.
+
Development
* Invoking guix environment:: Setting up development environments.
@@ -2812,7 +2825,6 @@ guix install 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 time-machine:: Running an older revision of Guix.
* Inferiors:: Interacting with another revision of Guix.
* Invoking guix describe:: Display information about your Guix revision.
@@ -4189,937 +4201,972 @@ 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.
-Before that, some security considerations.
+@node Invoking guix time-machine
+@section Invoking @command{guix time-machine}
-@subsection Channel Authentication
+@cindex @command{guix time-machine}
+@cindex pinning, channels
+@cindex replicating Guix
+@cindex reproducibility, of Guix
-@anchor{channel-authentication}
-@cindex authentication, of channel code
-The @command{guix pull} and @command{guix time-machine} commands
-@dfn{authenticate} the code retrieved from channels: they make sure each
-commit that is fetched is signed by an authorized developer. The goal
-is to protect from unauthorized modifications to the channel that would
-lead users to run malicious code.
+The @command{guix time-machine} command provides access to other
+revisions of Guix, for example to install older versions of packages,
+or to reproduce a computation in an identical environment. The revision
+of Guix to be used is defined by a commit or by a channel
+description file created by @command{guix describe}
+(@pxref{Invoking guix describe}).
-As a user, you must provide a @dfn{channel introduction} in your
-channels file so that Guix knows how to authenticate its first commit.
-A channel specification, including its introduction, looks something
-along these lines:
+The general syntax is:
-@lisp
-(channel
- (name 'my-channel)
- (url "https://example.org/my-channel.git")
- (introduction
- (make-channel-introduction
- "6f0d8cc0d88abb59c324b2990bfee2876016bb86"
- (openpgp-fingerprint
- "CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5"))))
-@end lisp
+@example
+guix time-machine @var{options}@dots{} -- @var{command} @var {arg}@dots{}
+@end example
-The specification above shows the name and URL of the channel. The call
-to @code{make-channel-introduction} above specifies that authentication
-of this channel starts at commit @code{6f0d8cc@dots{}}, which is signed
-by the OpenPGP key with fingerprint @code{CABB A931@dots{}}.
+where @var{command} and @var{arg}@dots{} are passed unmodified to the
+@command{guix} command of the specified revision. The @var{options} that define
+this revision are the same as for @command{guix pull} (@pxref{Invoking guix pull}):
-For the main channel, called @code{guix}, you automatically get that
-information from your Guix installation. For other channels, include
-the channel introduction provided by the channel authors in your
-@file{channels.scm} file. Make sure you retrieve the channel
-introduction from a trusted source since that is the root of your trust.
+@table @code
+@item --url=@var{url}
+@itemx --commit=@var{commit}
+@itemx --branch=@var{branch}
+Use the @code{guix} channel from the specified @var{url}, at the
+given @var{commit} (a valid Git commit ID represented as a hexadecimal
+string), or @var{branch}.
-If you're curious about the authentication mechanics, read on!
+@item --channels=@var{file}
+@itemx -C @var{file}
+Read the list of channels from @var{file}. @var{file} must contain
+Scheme code that evaluates to a list of channel objects.
+@xref{Channels} for more information.
+@end table
-@subsection Using a Custom Guix Channel
+As for @command{guix pull}, the absence of any options means that the
+the latest commit on the master branch will be used. The command
-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:
+@example
+guix time-machine -- build hello
+@end example
-@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
+will thus build the package @code{hello} as defined in the master branch,
+which is in general a newer revision of Guix than you have installed.
+Time travel works in both directions!
-@noindent
-From there on, @command{guix pull} will fetch code from the @code{super-hacks}
-branch of the repository at @code{example.org}.
+Note that @command{guix time-machine} can trigger builds of channels and
+their dependencies, and these are controlled by the standard build
+options (@pxref{Common Build Options}).
-@subsection Specifying Additional Channels
+@node Inferiors
+@section Inferiors
-@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 TODO: Remove this once we're more confident about API stability.
+@quotation Note
+The functionality described here is a ``technology preview'' as of version
+@value{VERSION}. As such, the interface is subject to change.
+@end quotation
-@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:
+@cindex inferiors
+@cindex composition of Guix revisions
+Sometimes you might need to mix packages from the revision of Guix you're
+currently running with packages available in a different revision of Guix.
+Guix @dfn{inferiors} allow you to achieve that by composing different Guix
+revisions in arbitrary ways.
-@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.
+@cindex inferior packages
+Technically, an ``inferior'' is essentially a separate Guix process connected
+to your main Guix process through a REPL (@pxref{Invoking guix repl}). The
+@code{(guix inferior)} module allows you to create inferiors and to
+communicate with them. It also provides a high-level interface to browse and
+manipulate the packages that an inferior provides---@dfn{inferior packages}.
-@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.
+When combined with channels (@pxref{Channels}), inferiors provide a simple way
+to interact with a separate revision of Guix. For example, let's assume you
+want to install in your profile the current @code{guile} package, along with
+the @code{guile-json} as it existed in an older revision of Guix---perhaps
+because the newer @code{guile-json} has an incompatible API and you want to
+run your code against the old API@. To do that, you could write a manifest for
+use by @code{guix package --manifest} (@pxref{Invoking guix package}); in that
+manifest, you would create an inferior for that old Guix revision you care
+about, and you would look up the @code{guile-json} package in the inferior:
-@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
+@lisp
+(use-modules (guix inferior) (guix channels)
+ (srfi srfi-1)) ;for 'first'
-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
+(define channels
+ ;; This is the old revision from which we want to
+ ;; extract guile-json.
+ (list (channel
+ (name 'guix)
+ (url "https://git.savannah.gnu.org/git/guix.git")
+ (commit
+ "65956ad3526ba09e1f7a40722c96c6ef7c0936fe"))))
-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):
+(define inferior
+ ;; An inferior representing the above revision.
+ (inferior-for-channels channels))
-@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)
+;; Now create a manifest with the current "guile" package
+;; and the old "guile-json" package.
+(packages->manifest
+ (list (first (lookup-inferior-packages inferior "guile-json"))
+ (specification->package "guile")))
@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:
+On its first run, @command{guix package --manifest} might have to build the
+channel you specified before it can create the inferior; subsequent runs will
+be much faster because the Guix revision will be cached.
-@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
+The @code{(guix inferior)} module provides the following procedures to open an
+inferior:
-@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.
+@deffn {Scheme Procedure} inferior-for-channels @var{channels} @
+ [#:cache-directory] [#:ttl]
+Return an inferior for @var{channels}, a list of channels. Use the cache at
+@var{cache-directory}, where entries can be reclaimed after @var{ttl} seconds.
+This procedure opens a new connection to the build daemon.
-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 (@pxref{Load
-Paths,,, guile, GNU Guile Reference Manual}). For example, if your channel
-contains a file at @file{my-packages/my-tools.scm} that defines a Guile
-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}).
+As a side effect, this procedure may build or substitute binaries for
+@var{channels}, which can take time.
+@end deffn
-@cindex dependencies, channels
-@cindex meta-data, channels
-@subsection Declaring Channel Dependencies
+@deffn {Scheme Procedure} open-inferior @var{directory} @
+ [#:command "bin/guix"]
+Open the inferior Guix in @var{directory}, running
+@code{@var{directory}/@var{command} repl} or equivalent. Return @code{#f} if
+the inferior could not be launched.
+@end deffn
-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 @file{.guix-channel}, which is to be placed in the root of
-the channel repository.
+@cindex inferior packages
+The procedures listed below allow you to obtain and manipulate inferior
+packages.
-The meta-data file should contain a simple S-expression like this:
+@deffn {Scheme Procedure} inferior-packages @var{inferior}
+Return the list of packages known to @var{inferior}.
+@end deffn
-@lisp
-(channel
- (version 0)
- (dependencies
- (channel
- (name some-collection)
- (url "https://example.org/first-collection.git")
-
- ;; The 'introduction' bit below is optional: you would
- ;; provide it for dependencies that can be authenticated.
- (introduction
- (channel-introduction
- (version 0)
- (commit "a8883b58dc82e167c96506cf05095f37c2c2c6cd")
- (signer "CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5"))))
- (channel
- (name some-other-collection)
- (url "https://example.org/second-collection.git")
- (branch "testing"))))
-@end lisp
+@deffn {Scheme Procedure} lookup-inferior-packages @var{inferior} @var{name} @
+ [@var{version}]
+Return the sorted list of inferior packages matching @var{name} in
+@var{inferior}, with highest version numbers first. If @var{version} is true,
+return only packages with a version number prefixed by @var{version}.
+@end deffn
-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.
+@deffn {Scheme Procedure} inferior-package? @var{obj}
+Return true if @var{obj} is an inferior package.
+@end deffn
-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.
+@deffn {Scheme Procedure} inferior-package-name @var{package}
+@deffnx {Scheme Procedure} inferior-package-version @var{package}
+@deffnx {Scheme Procedure} inferior-package-synopsis @var{package}
+@deffnx {Scheme Procedure} inferior-package-description @var{package}
+@deffnx {Scheme Procedure} inferior-package-home-page @var{package}
+@deffnx {Scheme Procedure} inferior-package-location @var{package}
+@deffnx {Scheme Procedure} inferior-package-inputs @var{package}
+@deffnx {Scheme Procedure} inferior-package-native-inputs @var{package}
+@deffnx {Scheme Procedure} inferior-package-propagat
This message was truncated. Download the full message here.
L
L
Ludovic Courtès wrote on 27 Sep 2020 22:38
Re: [bug#43482] [PATCH v2 1/2] doc: Update the master menu.
(name . zimoun)(address . zimon.toutoune@gmail.com)(address . 43482-done@debbugs.gnu.org)
871rinez0r.fsf@gnu.org
Hi,

zimoun <zimon.toutoune@gmail.com> skribis:

Toggle quote (2 lines)
> * doc/guix.texi: Update the master menu.

[...]

Toggle quote (18 lines)
> The sectioning becomes:
>
> 1. Specifying Additional Channels (was 3.)
> 2. Using a Custom Guix Channel (was 2.)
> 3. Replicating Guix (was 9.)
> 4. Channel Authentication (was 1.)
> 5. Primary URL (was 7.)
> 6. Creating a Channel (reworded)
> 7. Package Modules in a Sub-directory (was 5.)
> 8. Declaring Channel Dependencies (was 4.)
> 9. Specifying Channel Authorizations (was 6.)
> 10. Writing Channel News (was 8.)
>
> * doc/guix.texi (Channels): Move section to chapter.
> Reorder the chapter.
> Minor tweaks to keep uniformity.
> Update the master menu.

Applied, thanks!

Ludo’.
Closed
?