bug#54711: Bad Documentation Series: 6.1 Specifying Additional Channels

bug#54711: Bad Documentation Series: 6.1 Specifying Additional Channels

[Marek Paśnikowski]

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

bug#54711: Bad Documentation Series: 6.1 Specifying Additional Channels

[Maxime Devos]

[-- Attachment #1: Type: text/plain, Size: 322 bytes --]

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 ...

Greetings,
Maxime.

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 260 bytes --]

bug#54711: Bad Documentation Series: 6.1 Specifying Additional Channels

[Maxime Devos]

[-- Attachment #1: Type: text/plain, Size: 541 bytes --]

Marek Paśnikowski schreef op ma 04-04-2022 om 18:21 [+0200]:
> 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.

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 260 bytes --]

bug#54711: Bad Documentation Series: 6.1 Specifying Additional Channels

[Maxime Devos]

[-- Attachment #1: Type: text/plain, Size: 276 bytes --]

Marek Paśnikowski schreef op ma 04-04-2022 om 18:21 [+0200]:
> 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.

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 260 bytes --]

bug#54711: Bad Documentation Series: 6.1 Specifying Additional Channels

[Maxime Devos]

[-- Attachment #1: Type: text/plain, Size: 590 bytes --]

Marek Paśnikowski schreef op ma 04-04-2022 om 18:21 [+0200]:

> 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.



[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 260 bytes --]

bug#54711: Bad Documentation Series: 6.1 Specifying Additional Channels

[Maxime Devos]

[-- Attachment #1: Type: text/plain, Size: 1842 bytes --]

Marek Paśnikowski schreef op ma 04-04-2022 om 18:21 [+0200]:
> 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)
       (url "https://example.org/some-channel.git")
       (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 ...

> 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.

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 260 bytes --]

bug#54711: Bad Documentation Series: 6.1 Specifying Additional Channels

[Maxime Devos]

[-- Attachment #1: Type: text/plain, Size: 441 bytes --]

Maxime Devos schreef op ma 04-04-2022 om 19:53 [+0200]:
> 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 ...

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 260 bytes --]

bug#54711: Bad Documentation Series: 6.1 Specifying Additional Channels

[Marek Paśnikowski]

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.

bug#54711: Bad Documentation Series: 6.1 Specifying Additional Channels

[Maxime Devos]

[-- Attachment #1: Type: text/plain, Size: 1326 bytes --]

Marek Paśnikowski schreef op ma 04-04-2022 om 20:43 [+0200]:
> 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.

> 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.

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 260 bytes --]

bug#54711: Bad Documentation Series: 6.1 Specifying Additional Channels

[Maxime Devos]

[-- Attachment #1: Type: text/plain, Size: 597 bytes --]

Marek Paśnikowski schreef op ma 04-04-2022 om 20:43 [+0200]:
> 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.

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 260 bytes --]

bug#54711: Bad Documentation Series: 6.1 Specifying Additional Channels

[Maxime Devos]

[-- Attachment #1: Type: text/plain, Size: 181 bytes --]

Marek Paśnikowski schreef op ma 04-04-2022 om 20:43 [+0200]:
> 3. For a local repository, use (url "file://") or (url "/path").

Yes, that should work.

Greetings,
Maxime.

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 260 bytes --]

bug#54711: Bad Documentation Series: 6.1 Specifying Additional Channels

[Maxime Devos]

[-- Attachment #1: Type: text/plain, Size: 572 bytes --]

Marek Paśnikowski schreef op ma 04-04-2022 om 20:43 [+0200]:
> 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.

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 260 bytes --]

bug#54711: Bad Documentation Series: 6.1 Specifying Additional Channels

[Marek Paśnikowski]

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)
    (url "https://example.org/additional-channel.git"))
  %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?

bug#54711: Bad Documentation Series: 6.1 Specifying Additional Channels

[Tobias Geerinckx-Rice via Bug reports for GNU Guix]

Hi Marek,

On 10 April 2022 12:55:09 UTC, "Marek Paśnikowski" <mail@marekpasnikowski.name> wrote:
>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.  :-)

>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.

bug#54711: Bad Documentation Series: 6.1 Specifying Additional Channels

[Tobias Geerinckx-Rice via Bug reports for GNU Guix]

> 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.

bug#54711: Bad Documentation Series: 6.1 Specifying Additional Channels

[Marek Paśnikowski]

```
@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)
    (url "https://example.org/variant-channel.git"))
  %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
    repository URL: https://git.savannah.gnu.org/git/guix.git
    branch: master
    commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300
  variant-channel dd3df5e
    repository URL: https://example.org/variant-channel.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 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.