Bad Documentation Series: 6.1 Specifying Additional Channels

  • Open
  • quality assurance status badge
Details
3 participants
  • Marek Pa?nikowski
  • Maxime Devos
  • Tobias Geerinckx-Rice
Owner
unassigned
Submitted by
Marek Pa?nikowski
Severity
normal
M
M
Marek Pa?nikowski wrote on 4 Apr 2022 18:21
(address . bug-guix@gnu.org)
47274732e10dfe517a608d869117cb0253e2623b.camel@marekpasnikowski.name
Dear Guix Developers

I love the Guix's vision of system management.
Thank you for your hard work to implement it.

It pains me greatly to see the documentation be completely useless.
It gives descriptions of Guix programs,
but almost nothing usable for configuration files.

I am considering filing a bug report for each inadequate chapter.
Please reply whether this is welcome.
My aim is to rewrite the documentation in a way usable to someone,
who has never used Guix before.

I decided to prioritize channel documentation,
because this is my current blocker.
My goal is to keep a local mirror of the guix repository,
with my personal changes and additions.
Following is the list of the documentation problems.

1. (channel (introduction -)) is not mentioned at all.

2. What ==is== the channel introduction?
Which commit am I supposed to use?
How do I find the PGP fingerprint?

3. How do I declare a local repository?

4. How do I declare a channel within the config.scm file?

Respectfully,
Guix Noob
Marek Pasnikowski
M
M
Maxime Devos wrote on 4 Apr 2022 19:53
c2423083dbff213b43b53a8d3eca846c8598cd48.camel@telenet.be
Marek Pa?nikowski schreef op ma 04-04-2022 om 18:21 [+0200]:
Toggle quote (2 lines)
> 3. How do I declare a local repository?

The same way as an external repository. Just replace the "https://..."
of the repo at savannah with
"file://home/user/location/of/git/repository". But yes, this could be
documented ...

Greetings,
Maxime.
-----BEGIN PGP SIGNATURE-----

iI0EABYKADUWIQTB8z7iDFKP233XAR9J4+4iGRcl7gUCYkswhBccbWF4aW1lZGV2
b3NAdGVsZW5ldC5iZQAKCRBJ4+4iGRcl7pxuAQCPTLS62oy5LBnpFtwPZSYHvf+I
YV8f6kDx6Z5ETyOlPwD+OOhtI+tqRzSvasfGH1kQFk9p+FXJndEZyxtpgjldTwk=
=PFtT
-----END PGP SIGNATURE-----


M
M
Maxime Devos wrote on 4 Apr 2022 19:55
6f356f2c29491340288b447470af0035be64463e.camel@telenet.be
Marek Pa?nikowski schreef op ma 04-04-2022 om 18:21 [+0200]:
Toggle quote (2 lines)
> 4. How do I declare a channel within the config.scm file?

What do you mean with ‘the config.scm file’ here? The operating system
configuration file, which is conventionally named configuration.scm or
config.scm but in principle can be named anything? The
~/.config/guix/current/channels.scm file? The Guix Home configuration
(if any)? The manifest used for the user profile (if any, using "guix
install" and friends is also an option)?

Greetings,
Maxime.
-----BEGIN PGP SIGNATURE-----

iI0EABYKADUWIQTB8z7iDFKP233XAR9J4+4iGRcl7gUCYksxHBccbWF4aW1lZGV2
b3NAdGVsZW5ldC5iZQAKCRBJ4+4iGRcl7syQAQCT3fYZiDsb77dpX58S4OzMP5Kr
rDzDSSd9QP5sQpgtCQEAhwmvuy27ZnyqtQ5KrSAucy4dXQOlAM1fzB/LgDhTzgo=
=aenL
-----END PGP SIGNATURE-----


M
M
Maxime Devos wrote on 4 Apr 2022 19:58
30e17f9f3d997eba9acd79ea87f94c231f9a7e5a.camel@telenet.be
Marek Pa?nikowski schreef op ma 04-04-2022 om 18:21 [+0200]:
Toggle quote (2 lines)
> 1. (channel (introduction -)) is not mentioned at all.

It isn't in (guix)Specifying Aditional Channels, because its optional
(albeit nice to have for security). It is documented in the next few
sections.
-----BEGIN PGP SIGNATURE-----

iI0EABYKADUWIQTB8z7iDFKP233XAR9J4+4iGRcl7gUCYksxyxccbWF4aW1lZGV2
b3NAdGVsZW5ldC5iZQAKCRBJ4+4iGRcl7ikiAQDNNJL/CeicaNo/k/uzcEetTcG1
jWRAOK3p9qIbQThjxgEA25c9FfH1cSMsCGbTvnMeZHNZM02eUgqiCQDxwJgLkQk=
=GtVs
-----END PGP SIGNATURE-----


M
M
Maxime Devos wrote on 4 Apr 2022 20:02
bd612c3e13fe517218d9913057e0d8ccaa01731c.camel@telenet.be
Marek Pa?nikowski schreef op ma 04-04-2022 om 18:21 [+0200]:

Toggle quote (2 lines)
> How do I find the PGP fingerprint?

(guix)Channel Authentication
The specification above shows the name and URL of the channel. The
call to ‘make-channel-introduction’ above specifies that authentication
of this channel starts at commit ‘6f0d8cc...’, which is signed by the
OpenPGP key with fingerprint ‘CABB A931...’.

The PGP fingerprint is the PGP fingerprint that is used to sign the
commit. You can find it in the PGP application you used to create your
PGP key.

Greetings,
Maxime.
-----BEGIN PGP SIGNATURE-----

iI0EABYKADUWIQTB8z7iDFKP233XAR9J4+4iGRcl7gUCYksynxccbWF4aW1lZGV2
b3NAdGVsZW5ldC5iZQAKCRBJ4+4iGRcl7uvLAP9A+aCCynixU/eeiJ55fQw93lQW
HfTX1drWPE2Im/i6CwD9ERAWJZWqlU6l3Y4tFaJxLnr3BFcNn/85CKTu7XiDyww=
=IfT0
-----END PGP SIGNATURE-----


M
M
Maxime Devos wrote on 4 Apr 2022 20:08
6cd9ef48a3e204b7ad7fe57f56847ee3df0d68d2.camel@telenet.be
Marek Pa?nikowski schreef op ma 04-04-2022 om 18:21 [+0200]:
Toggle quote (2 lines)
> 2. What ==is== the channel introduction?

From (guix)Channel Authentication:

As a user, you must provide a “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:

(channel
(name 'some-channel)
(introduction
(make-channel-introduction
"6f0d8cc0d88abb59c324b2990bfee2876016bb86"
(openpgp-fingerprint
"CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5"))))

It's the (make-channel-introduction [...]) thing. It's just a bunch of
information that Guix can use to authenticate the first commit of the
channel. Also see ...

Toggle quote (2 lines)
> Which commit am I supposed to use?

The first commit that adds (or in your case, modifies) the .guix-
authorization file. From (guix)Specifying Channel Authorizations:

This authentication rule creates a chicken-and-egg issue: how do we
authenticate the first commit? Related to that: how do we deal with
channels whose repository history contains unsigned commits and lack
‘.guix-authorizations’? And how do we fork existing channels?

Channel introductions answer these questions by describing the first
commit of a channel that should be authenticated. The first time a
channel is fetched with ‘guix pull’ or ‘guix time-machine’, the command
looks up the introductory commit and verifies that it is signed by the
specified OpenPGP key. From then on, it authenticates commits
according to the rule above. Authentication fails if the target commit
is neither a descendant nor an ancestor of the introductory commit.

Greetings,
Maxime.
-----BEGIN PGP SIGNATURE-----

iI0EABYKADUWIQTB8z7iDFKP233XAR9J4+4iGRcl7gUCYks0LhccbWF4aW1lZGV2
b3NAdGVsZW5ldC5iZQAKCRBJ4+4iGRcl7sBtAQDD4DZb11QoKxOZNCyoLLM+cRMv
NhHdw8cxMPxgxCeExQEAvzElsNEsijUMMGQdgp+Km3k4e/A1eZviqEs51ui77w8=
=IMip
-----END PGP SIGNATURE-----


M
M
Maxime Devos wrote on 4 Apr 2022 20:13
f88ca99a09fac09b2aa39328e1001778a3d5f830.camel@telenet.be
Maxime Devos schreef op ma 04-04-2022 om 19:53 [+0200]:
Toggle quote (10 lines)
> Marek Pa?nikowski schreef op ma 04-04-2022 om 18:21 [+0200]:
> > 3. How do I declare a local repository?
>
> The same way as an external repository.  Just replace the
> "https://..."
> of the repo at savannah with
> "file://home/user/location/of/git/repository".  But yes, this could
> be
> documented ...

Or simpler: "/home/user/location/of/..." might work too ...
-----BEGIN PGP SIGNATURE-----

iI0EABYKADUWIQTB8z7iDFKP233XAR9J4+4iGRcl7gUCYks1QBccbWF4aW1lZGV2
b3NAdGVsZW5ldC5iZQAKCRBJ4+4iGRcl7nIWAP4gmLOGcEAz+nZeIFfFtL8uEwKx
oK9S5xuGiKX88U1fEAD8DQArPaMgBOYBFdDGRV+1ba6rO69YaNT3cZQaNDpmeQY=
=Nlo6
-----END PGP SIGNATURE-----


M
M
Marek Pa?nikowski wrote on 4 Apr 2022 20:43
Bad Documentation Series: 6.1 Specifying Additional Channels
(address . 54711@debbugs.gnu.org)
4b4fb5fcf67ee63c9899f43e9653b1cfd689dd26.camel@marekpasnikowski.name
Thank you for the quick reply.

Those are my conclusions:

1. If I clone someone else's channel, do not bother with the
introduction.

2. If I create my own channel from scratch,
then I have to authorize it with my key.
Thus I know the commit and the key fingerprint.

3. For a local repository, use (url "file://") or (url "/path").

Is any of these wrong?

Regarding point 4.: I meant both /etc/config.scm and
~/src/guix-config/home-configuration.scm .
My understanding is that it should be possible to define private
(user specific) channels.
I could be wrong here.
I do not like the ~/.config/guix/channels.scm file,
because it lives outside of the home configuration.
I would rather have it generated from the home config file.
M
M
Maxime Devos wrote on 4 Apr 2022 21:47
2e3b78a8e94fb13bcf98ff8336a239b2e47040c3.camel@telenet.be
Marek Pa?nikowski schreef op ma 04-04-2022 om 20:43 [+0200]:
Toggle quote (8 lines)
> Regarding point 4.: I meant both /etc/config.scm and
> ~/src/guix-config/home-configuration.scm .
> My understanding is that it should be possible to define private
> (user specific) channels.
> I could be wrong here.
> I do not like the ~/.config/guix/channels.scm file,
> because it lives outside of the home configuration.

FWIW, you can create a symlink from ~/.config/guix/channels.scm to
~/src/guix-config/channels.scm and modify ~/src/guix-
config/channels.scm. That way, the configuration files live together,
which might be close enough for your purposes.

Toggle quote (2 lines)
> I would rather have it generated from the home config file.

You can define user-specific channels, in ~/.config/guix/channels.scm.
I suppose it might be technically possible to write a home
configuration that puts a file in ~/.config/guix/channels.scm and/or
runs the equivalent of "guix pull".

However, that's too late. What you want is the home or system to be
reconfigured with a certain guix+channels Y mentioned in the home or
system configuration. But when you run "guix system reconfigure", that
reconfiguration is performed with guix X. While after the
reconfiguration, the guix is updated, the reconfiguration uses the old
guix.

Greetings,
Maxime.
-----BEGIN PGP SIGNATURE-----

iI0EABYKADUWIQTB8z7iDFKP233XAR9J4+4iGRcl7gUCYktLUhccbWF4aW1lZGV2
b3NAdGVsZW5ldC5iZQAKCRBJ4+4iGRcl7hLOAP9WQhzTvNV8IF2LyOQbuTKoMHo1
cQXDsjRfKlEuiyfC6AD9Gf2gp4egB54n2OZnsLhvBj8jXpGRVwRU9akR1lg+uAM=
=XEBb
-----END PGP SIGNATURE-----


M
M
Maxime Devos wrote on 4 Apr 2022 21:51
edd8257298b584aa231b29fafb46ce5431c06ba6.camel@telenet.be
Marek Pa?nikowski schreef op ma 04-04-2022 om 20:43 [+0200]:
Toggle quote (3 lines)
> 1. If I clone someone else's channel, do not bother with the
> introduction.

If with ‘clone’ you mean a ‘local git checkout+modifications’ here, and
its a local clone, then probably yes --- if some attacker can replace
the contents of your local repository, that's not something in Guix'
threat model ...

Now, if you choose to publish your modified version of someone's
channel to other people, then the other people might appreciate to have
introductions and .guix-authorization set-up.

Greetings,
Maxime.
-----BEGIN PGP SIGNATURE-----

iI0EABYKADUWIQTB8z7iDFKP233XAR9J4+4iGRcl7gUCYktMXRccbWF4aW1lZGV2
b3NAdGVsZW5ldC5iZQAKCRBJ4+4iGRcl7sPCAQD2eW0g1kEYDxP94exRNIVuvVK3
Njdq1qzJeNIY+SjuUQD/eFDIbRpvhGWlBZ+b21tOCvR2jFGm0reOOCHe6ShBKgY=
=+a2P
-----END PGP SIGNATURE-----


M
M
Maxime Devos wrote on 4 Apr 2022 21:52
a329f832f421c227519dbade014b33cc179a2e4d.camel@telenet.be
Marek Pa?nikowski schreef op ma 04-04-2022 om 20:43 [+0200]:
Toggle quote (2 lines)
> 3. For a local repository, use (url "file://") or (url "/path").

Yes, that should work.

Greetings,
Maxime.
-----BEGIN PGP SIGNATURE-----

iI0EABYKADUWIQTB8z7iDFKP233XAR9J4+4iGRcl7gUCYktMixccbWF4aW1lZGV2
b3NAdGVsZW5ldC5iZQAKCRBJ4+4iGRcl7vG6AQCZyebHFzFIum95jvXWLHABRpiO
Bb+7U4NtxHvH0Oc1mAEA6DryBojKHYBVD9ddOsax9Ageg5bXD7torW2BVUgxngo=
=/Fvi
-----END PGP SIGNATURE-----


M
M
Maxime Devos wrote on 4 Apr 2022 21:54
ae30f1b5875a0de5697ad9b9da89c665ba8dd510.camel@telenet.be
Marek Pa?nikowski schreef op ma 04-04-2022 om 20:43 [+0200]:
Toggle quote (4 lines)
> 2. If I create my own channel from scratch,
> then I have to authorize it with my key.
> Thus I know the commit and the key fingerprint.

You don't have to do any authorization -- you can skip .guix-
authorization and channel introductions. However, by skipping this,
you lose some nice security properties, so I cannot recommend this if
the channel is published over the Internet or something for other
people. But if it's purely local, then skipping it is probably fine.

Greetings,
Maxime.
-----BEGIN PGP SIGNATURE-----

iI0EABYKADUWIQTB8z7iDFKP233XAR9J4+4iGRcl7gUCYktM8BccbWF4aW1lZGV2
b3NAdGVsZW5ldC5iZQAKCRBJ4+4iGRcl7hZOAP92wtxCLY5LO7V2iugmLS6TqDIY
M3VDKsKwKMJKnF7IJAEAxEYFWKKJsDj8KQmUIv3nZhIh2m11dijFbWHA2HW83gw=
=1qEy
-----END PGP SIGNATURE-----


M
M
Marek Pa?nikowski wrote on 10 Apr 2022 14:55
Bad Documentation Series: 6.1 Specifying Additional Channels
(address . 54711@debbugs.gnu.org)
155cb35e7d71ee1a73496ba47dbab6d8a121c0d6.camel@marekpasnikowski.name
In light of the above replies and my own experiences, I propose the
following to be the text of the chapter. Formatted in CommonMark.

## 6.1 Specifying Additional Channels

You can specify _additional channels_ to pull from. To use a channel,
write `~/.config/guix/channels.scm` to instruct `guix pull` to pull
from it _in addition to_ or _instead of_ the default Guix channel:

```
;; Use the literal default.
%default-channels
```

```
;; Add a channel to the default.
(cons
(channel
(name 'additional-channel)
%default-channels)
```

```
;; Replace Guix repository with a local copy.
(list
(channel
(name 'guix)
(url "/home/user/src/guix")))
```

Note that the snippets above are (as always!) Scheme code; we use
`cons` to add a channel to the list of channels that the variable
`%default-channels` is bound to (see [`cons` and lists](link target) in
GNU Guile Reference Manual). With this file in place, `guix pull`
builds not only Guix, but also the package modules from the added
repositories. The result in `~/.config/guix/current` is the union of
Guix with the added package modules:

```
$ guix pull --list generations
... Example output ...
```

The output of `guix pull` above shows that Generation 19 includes both
Guix and packages from the `additional-channel` channel. Among the new
and upgraded packages that are listed, some like `variant-gimp` and
`variant-emacs-with-cool-features` might come from `additional-
channel`, while others come from the Guix default channel.

Don't forget, that the channels can have more options specified, such
as authentication. Read the following chapters to learn more about the
options.

***

PS: (url "file://path/to/local/repository") was not accepted by Guix
during my experiments this week. Should I report is as a separate bug?
T
T
Tobias Geerinckx-Rice wrote on 10 Apr 2022 15:33
Re: bug#54711: Bad Documentation Seri es: 6.1 Specifying Additional Channels
00423B2C-F1DE-48F2-AFD4-3AD2BE12A105@tobias.gr
Hi Marek,

On 10 April 2022 12:55:09 UTC, "Marek Pa?nikowski" <mail@marekpasnikowski.name> wrote:
Toggle quote (2 lines)
>In light of the above replies [...] in CommonMark.

Thanks! Please try to submit Texinfo going forward. It doesn't need to be perfect but it will be so much closer to something we can merge.

You'll learn something, *and* save Maxime (or someone else) the tedious chore of translating markdown back to markup. :-)

Toggle quote (2 lines)
>PS: (url "file://path/to/local/repository")

Hm, I haven't tried relative file names myself. For robustness, I suggest using absolute ones instead, e.g., file:///home/marek/path/to/local/repository.

N.B., file:// might be optional, but the leading / is not.

If that still doesn't work, paste the error you get.



Kind regards,

T G-R

Sent on the go. Excuse or enjoy my brevity.
T
T
Tobias Geerinckx-Rice wrote on 10 Apr 2022 15:54
24DF226B-A9CE-448B-BD13-1CEA60864E28@tobias.gr
Toggle quote (2 lines)
> PS: (url "file://path/to/local/repository")

Actually, 'path' is a hostname here, so I guess it *must not* work even as a relative file name.

Whether Guix/Guile follows standards that well, or correctly errors out for an incorrect reason, I don't know.


Kind regards,

T G-R

Sent on the go. Excuse or enjoy my brevity.
M
M
Marek Pa?nikowski wrote on 10 Apr 2022 18:27
Bad Documentation Series: 6.1 Specifying Additional Channels
(address . 54711@debbugs.gnu.org)
f18913073b304777cd3ac4b8b57b99e63aef9fd9.camel@marekpasnikowski.name
```
@node Specifying Additional Channels
@section 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} or
@emph{instead of} the default Guix channel:

@vindex %default-channels
@lisp
;; Use the literal default.
%default-channels

;; Add a channel to the default.
(cons
(channel
(name 'variant-channel)
%default-channels)

;; Replace Guix repository with a local copy.
(list
(channel
(name 'guix)
(url "file:///home/user/src/guix")))
@end lisp

@noindent
Note that the snippets above are (as always!)@: Scheme code; we use
@code{cons} to add a channel to 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 the added repositories. The result in
@file{~/.config/guix/current} is the union of Guix with the added
package modules:

@example
$ guix pull --list-generations
@dots{}
Generation 19 Aug 27 2018 16:20:48
guix d894ab8
branch: master
commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300
variant-channel dd3df5e
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 the @code{variant-channel} 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-channel}, while others come from the Guix
default channel.

@noindent
Don't forget, that the chanels can have more options specified, such as
authentication. Read the following pages to learn more about the
options.
```

I just checked, and the `file:///` prefix was accepted by Guix.I was
not aware of the "prefix thing". This is one of many assumptions which
trip up unprepared readers.
?
Your comment

Commenting via the web interface is currently disabled.

To comment on this conversation send an email to 54711@debbugs.gnu.org

To respond to this issue using the mumi CLI, first switch to it
mumi current 54711
Then, you may apply the latest patchset in this issue (with sign off)
mumi am -- -s
Or, compose a reply to this issue
mumi compose
Or, send patches to this issue
mumi send-email *.patch