doc: cookbook: Remove outdated section about GUIX_PACKAGE_PATH.

The section insisted on GUIX_PACKAGE_PATH, mentioned version 0.16, and
didn't say much about channels, which made it look obsolete.

* doc/guix-cookbook.texi (GUIX_PACKAGE_PATH): Remove section.
(Guix channels): Rename to...
(Channels): ... this.  Merge most of the explanations previously in the
GUIX_PACKAGE_PATH section.  Say more about channels and add
cross-references.
This commit is contained in:
Ludovic Courtès 2023-05-06 18:01:16 +02:00
parent 4dbe29a76a
commit 86bf0c5a3f
No known key found for this signature in database
GPG key ID: 090B11993D9AEBB5

View file

@ -628,30 +628,25 @@ The @code{use-modules} expression tells which of the modules we need in the file
Modules are a collection of values and procedures. They are commonly called Modules are a collection of values and procedures. They are commonly called
``libraries'' or ``packages'' in other programming languages. ``libraries'' or ``packages'' in other programming languages.
@node @samp{GUIX_PACKAGE_PATH} @node Channels
@subsubsection @samp{GUIX_PACKAGE_PATH} @subsubsection Channels
@emph{Note: Starting from Guix 0.16, the more flexible Guix @dfn{channels} are the @cindex channel
preferred way and supersede @samp{GUIX_PACKAGE_PATH}. See next section.} Guix and its package collection can be extended through @dfn{channels}.
A channel is a Git repository, public or not, containing @file{.scm}
files that provide packages (@pxref{Defining Packages,,, guix, GNU Guix
Reference Manual}) or services (@pxref{Defining Services,,, guix, GNU
Guix Reference Manual}).
It can be tedious to specify the file from the command line instead of simply How would you go about creating a channel? First, create a directory
calling @code{guix package --install my-hello} as you would do with the official that will contain your @file{.scm} files, say @file{~/my-channel}:
packages.
Guix makes it possible to streamline the process by adding as many ``package
declaration directories'' as you want.
Create a directory, say @file{~/guix-packages} and add it to the @samp{GUIX_PACKAGE_PATH}
environment variable:
@example @example
$ mkdir ~/guix-packages mkdir ~/my-channel
$ export GUIX_PACKAGE_PATH=~/guix-packages
@end example @end example
To add several directories, separate them with a colon (@code{:}). Suppose you want to add the @samp{my-hello} package we saw previously;
it first needs some adjustments:
Our previous @samp{my-hello} needs some adjustments though:
@lisp @lisp
(define-module (my-hello) (define-module (my-hello)
@ -692,9 +687,9 @@ package. If you want to use @code{define-public} in this use-case nonetheless,
sure the file ends with an evaluation of @code{my-hello}: sure the file ends with an evaluation of @code{my-hello}:
@lisp @lisp
; ... ;; ...
(define-public my-hello (define-public my-hello
; ... ;; ...
) )
my-hello my-hello
@ -702,22 +697,50 @@ my-hello
This last example is not very typical. This last example is not very typical.
Now @samp{my-hello} should be part of the package collection like all other official Now how do you make that package visible to @command{guix} commands so
packages. You can verify this with: you can test your packages? You need to add the directory to the search
path using the @option{-L} command-line option, as in these examples:
@example @example
$ guix package --show=my-hello guix show -L ~/my-channel my-hello
guix build -L ~/my-channel my-hello
@end example @end example
@node Guix channels The final step is to turn @file{~/my-channel} into an actual channel,
@subsubsection Guix channels making your package collection seamlessly available @i{via} any
@command{guix} command. To do that, you first need to make it a Git
repository:
Guix 0.16 features channels, which is very similar to @samp{GUIX_PACKAGE_PATH} but @example
provides better integration and provenance tracking. Channels are not cd ~/my-channel
necessarily local, they can be maintained as a public Git repository for git init
instance. Of course, several channels can be used at the same time. git add my-hello.scm
git commit -m "First commit of my channel."
@end example
@xref{Channels,,, guix, GNU Guix Reference Manual} for setup details. And that's it, you have a channel! From there on, you can add this
channel to your channel configuration in
@file{~/.config/guix/channels.scm} (@pxref{Specifying Additional
Channels,,, guix, GNU Guix Reference Manual}); assuming you keep your
channel local for now, the @file{channels.scm} would look something like
this:
@lisp
(append (list (channel
(name 'my-channel)
(url (string-append "file://" (getenv "HOME")
"/my-channel"))))
%default-channels)
@end lisp
Next time you run @command{guix pull}, your channel will be picked up
and the packages it defines will be readily available to all the
@command{guix} commands, even if you do not pass @option{-L}. The
@command{guix describe} command will show that Guix is, indeed, using
both the @code{my-channel} and the @code{guix} channels.
@xref{Creating a Channel,,, guix, GNU Guix Reference Manual}, for
details.
@node Direct checkout hacking @node Direct checkout hacking
@subsubsection Direct checkout hacking @subsubsection Direct checkout hacking