Real-world example for channels?

Real-world example for channels?

[Hartmut Goebel]

Hi,

I'm looking for some real-world examples for channels.

After reading
<https://www.gnu.org/software/guix/manual/en/html_node/Channels.html>
I'm confused:

  * AFAIU Section 3.7.1 shows an example for pulling *whole* guix from a
    different location. So this needs to be a complete guix-clone
    (optionally including my own package modules).
  * Section 3.7.2 describes how to add "a Git repository containing [my]
    own package modules".
      o What files or scm-packages is this git-repo expected to include?
        What's the file-layout? Is there a suggested naming-convention?
        How to #use-module these packages?
      o What happens if files conflict? Which repo will take precedence?

I suggest adding a short example to the manual. To avoid any conflict
with the warinign in sec. 3.7.2 this could be some "personal dotfiles"
package.

Side-note: IMHO 3.7.1 should not be the first section, since this is not
the case most user will want to use.

Thanks in advance for answering

-- 
Regards
Hartmut Goebel

| Hartmut Goebel          | h.goebel@crazy-compilers.com               |
| www.crazy-compilers.com | compilers which you thought are impossible |

Re: Real-world example for channels?

[Ricardo Wurmus]

Hi Hartmut,

> I'm looking for some real-world examples for channels.

Here’s an example:

    https://github.com/BIMSBbioinfo/guix-bimsb

> After reading
> <https://www.gnu.org/software/guix/manual/en/html_node/Channels.html>
> I'm confused:
>
>   * AFAIU Section 3.7.1 shows an example for pulling *whole* guix from a
>     different location. So this needs to be a complete guix-clone
>     (optionally including my own package modules).

Correct.

>   * Section 3.7.2 describes how to add "a Git repository containing [my]
>     own package modules".
>       o What files or scm-packages is this git-repo expected to include?
>         What's the file-layout? Is there a suggested naming-convention?
>         How to #use-module these packages?

No files are expected to be included.  You only include files that you
want to offer.  There is no prescribed file layout, nor is there any
naming convention.

You #:use-module these modules like any other module.

If the repository contains a file “foo.scm” which starts with
“(define-module (foo) …)”, then you can “#:use-module (foo)” after the
repository has been added as a channel.

I suggest putting modules in separate namespaces.  All modules provided
by “guix-bimsb”, for example, are in the “bimsb” namespace.

--
Ricardo

Re: Real-world example for channels?

[Efraim Flashner]

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

On Sat, Jan 26, 2019 at 11:16:31PM +0100, Hartmut Goebel wrote:
> Hi,
> 
> I'm looking for some real-world examples for channels.
> 

Here's the contents of my ~/.config/guix/channels.scm

(cons* (channel
         (name 'chromium)
         (url "https://gitlab.com/mbakke/guix-chromium.git")
         (branch "master"))
       (channel
         (name 'ietf)
         (url "https://gitlab.com/efraim/guix-ietf.git")
         (branch "master"))
       %default-channels)

-- 
Efraim Flashner   <efraim@flashner.co.il>   אפרים פלשנר
GPG key = A28B F40C 3E55 1372 662D  14F7 41AA E7DC CA3D 8351
Confidentiality cannot be guaranteed on emails sent or received unencrypted

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Real-world example for channels?

[Chris Marusich]

[-- Attachment #1.1: Type: text/plain, Size: 1194 bytes --]

Ricardo Wurmus <rekado@elephly.net> writes:

> No files are expected to be included.  You only include files that you
> want to offer.  There is no prescribed file layout, nor is there any
> naming convention.
>
> You #:use-module these modules like any other module.
>
> If the repository contains a file “foo.scm” which starts with
> “(define-module (foo) …)”, then you can “#:use-module (foo)” after the
> repository has been added as a channel.
>
> I suggest putting modules in separate namespaces.  All modules provided
> by “guix-bimsb”, for example, are in the “bimsb” namespace.

I agree with Hartmut.  I also found this confusing.  I've attached a
patch to try clarifying it.  What do you think?

If the Guix manual had told me that the repository's root directory will
basically be added to the Guile load path, I would have understood the
expected file structure immediately.  The Guile manual clearly describes
the requirements for making modules available via the load path.

Maybe the existing text was clear enough for some.  I read it but still
wasn't sure exactly how Guix expected me to lay out my channel's files.

-- 
Chris

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.2: 0001-doc-Clarify-channel-file-structure.patch --]
[-- Type: text/x-patch, Size: 2012 bytes --]

From d382cbddd11e86bd9b69f271782d2dccba180a05 Mon Sep 17 00:00:00 2001
From: Chris Marusich <cmmarusich@gmail.com>
Date: Sun, 27 Jan 2019 16:29:30 -0800
Subject: [PATCH] doc: Clarify channel file structure.

Suggested by Hartmut Goebel <h.goebel@crazy-compilers.com>.

* doc/guix.texi (Channels): Clarify how a channel author should structure the
files in their channel's Git repository.
---
 doc/guix.texi | 18 ++++++++++++++----
 1 file changed, 14 insertions(+), 4 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 22fc03b8f..5499ebf5b 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -3691,10 +3691,20 @@ 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
 
-Once you have a Git repository containing your own package modules, you can
-write @code{~/.config/guix/channels.scm} to instruct @command{guix pull} to
-pull from your personal channel @emph{in addition} to the default Guix
-channel(s):
+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}).
+
+To use a channel, you can write @code{~/.config/guix/channels.scm} to instruct
+@command{guix pull} to pull from your personal channel @emph{in addition} to
+the default Guix channel(s):
 
 @vindex %default-channels
 @lisp
-- 
2.20.1


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

Re: Real-world example for channels?

[Chris Marusich]

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

Hartmut Goebel <h.goebel@crazy-compilers.com> writes:

>       o What happens if files conflict? Which repo will take precedence?

I think the short answer is: for now, don't do that.

There was some discussion here about conflicts:

https://lists.gnu.org/archive/html/guix-devel/2018-10/msg00384.html

We basically agreed that for now, we should error out if there is a
conflict, but I don't know if that code has been implemented yet.

-- 
Chris

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

Re: Real-world example for channels?

[Konrad Hinsen]

Hi Chris,

> I agree with Hartmut.  I also found this confusing.  I've attached a
> patch to try clarifying it.  What do you think?

Thanks for the clarification. I was also confused about this, to the 
point of never actually setting up my own channel.

Konrad.

Re: Real-world example for channels?

[Ludovic Courtès]

Hi Chris,

Chris Marusich <cmmarusich@gmail.com> skribis:

> From d382cbddd11e86bd9b69f271782d2dccba180a05 Mon Sep 17 00:00:00 2001
> From: Chris Marusich <cmmarusich@gmail.com>
> Date: Sun, 27 Jan 2019 16:29:30 -0800
> Subject: [PATCH] doc: Clarify channel file structure.
>
> Suggested by Hartmut Goebel <h.goebel@crazy-compilers.com>.
>
> * doc/guix.texi (Channels): Clarify how a channel author should structure the
> files in their channel's Git repository.
> ---
>  doc/guix.texi | 18 ++++++++++++++----
>  1 file changed, 14 insertions(+), 4 deletions(-)
>
> diff --git a/doc/guix.texi b/doc/guix.texi
> index 22fc03b8f..5499ebf5b 100644
> --- a/doc/guix.texi
> +++ b/doc/guix.texi
> @@ -3691,10 +3691,20 @@ 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
>  
> -Once you have a Git repository containing your own package modules, you can
> -write @code{~/.config/guix/channels.scm} to instruct @command{guix pull} to
> -pull from your personal channel @emph{in addition} to the default Guix
> -channel(s):
> +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}).
> +
> +To use a channel, you can write @code{~/.config/guix/channels.scm} to instruct
> +@command{guix pull} to pull from your personal channel @emph{in addition} to
> +the default Guix channel(s):

I’d perhaps move the “To create a channel” paragraph after the “To use a
channel” paragraph, but otherwise LGTM.

Thanks for taking the time to improve the manual!

Ludo’.

Re: Real-world example for channels?

[Chris Marusich]

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

Hi Ludo,

I've pushed this as b0a372637f683eae35802af93d67711c3a18e480.

Thank you everyone for the feedback!  And thank you to Hartmut for
calling out the problem!

-- 
Chris

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]