Re: Real-world example for channels?

[Chris Marusich <cmmarusich@gmail.com>]

[-- 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 --]