From unknown Sun Aug 17 00:58:53 2025 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-Mailer: MIME-tools 5.509 (Entity 5.509) Content-Type: text/plain; charset=utf-8 From: bug#64040 <64040@debbugs.gnu.org> To: bug#64040 <64040@debbugs.gnu.org> Subject: Status: [PATCH] doc: Turn "Creating a Channel" into a step-by-step guide. Reply-To: bug#64040 <64040@debbugs.gnu.org> Date: Sun, 17 Aug 2025 07:58:53 +0000 retitle 64040 [PATCH] doc: Turn "Creating a Channel" into a step-by-step gu= ide. reassign 64040 guix-patches submitter 64040 Ludovic Court=C3=A8s severity 64040 normal tag 64040 patch thanks From debbugs-submit-bounces@debbugs.gnu.org Tue Jun 13 06:21:09 2023 Received: (at submit) by debbugs.gnu.org; 13 Jun 2023 10:21:09 +0000 Received: from localhost ([127.0.0.1]:41351 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1q919A-0005H5-St for submit@debbugs.gnu.org; Tue, 13 Jun 2023 06:21:09 -0400 Received: from lists.gnu.org ([209.51.188.17]:60898) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1q9196-0005Gu-6W for submit@debbugs.gnu.org; Tue, 13 Jun 2023 06:21:07 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1q9195-0001OE-LZ for guix-patches@gnu.org; Tue, 13 Jun 2023 06:21:03 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1q9192-0003vq-Pj; Tue, 13 Jun 2023 06:21:00 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:Date:Subject:To:From:in-reply-to: references; bh=Het7Jpcuv1HGOWUVimELPjFZc5V6Ah39p3cVEysbhC4=; b=keYjXg3EZpuBg3 /uyHAsceeUmoZJB7ijMDglOV7HPgSJ3IjSx1MjuBQINNdqVG+IhoePJfGwBcjy2InyOkxMGvghMyp MI7J/BFF5dyUo2YQupU+m/DgakM90II7Y2F+PbP/NUccQ5K6YWlo3cYNpWfpLwulJjAfv4cSq47f7 P8sQk3yettIOm3ZNXVhDvzyG6K1WLcKacxv6UTXmH5bYl9H1cTJd5+DBbOd6pchmclm7n9QUrLjrw S9JaxiBhrueGfJh4ucgyb+tG/uszhYTr1J7VeuEJlAX7sEkrt5OX44+unGVNwNO1UZuoYyaJ+Gg6M 1YADUVqJFyesOSSMRsEg==; Received: from [193.50.110.239] (helo=gnu.org) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1q9190-0001Mk-17; Tue, 13 Jun 2023 06:21:00 -0400 From: =?UTF-8?q?Ludovic=20Court=C3=A8s?= To: guix-patches@gnu.org Subject: [PATCH] doc: Turn "Creating a Channel" into a step-by-step guide. Date: Tue, 13 Jun 2023 12:20:41 +0200 Message-Id: <414c557c291ad6aa35841cc96cc8616900c8f960.1686651530.git.ludo@gnu.org> X-Mailer: git-send-email 2.40.1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: submit Cc: =?UTF-8?q?Ludovic=20Court=C3=A8s?= X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) From: Ludovic Courtès * doc/guix.texi (Creating a Channel): Rewrite as a step-by-step guide. Move warning below and shorten it. --- doc/guix.texi | 122 ++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 93 insertions(+), 29 deletions(-) Hi! This is an attempt to make “Creating a Channel” more concrete than it is, with clearly identified steps to follow and shell snippets. Feedback welcome! Ludo’. diff --git a/doc/guix.texi b/doc/guix.texi index 395fc25818..1134ac113f 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -5641,18 +5641,99 @@ Creating a Channel Let's say you have a bunch of custom package variants or personal packages that you think would make little sense to contribute to the Guix project, but would like to have these packages transparently available to you at the -command line. You would first write modules containing those package -definitions (@pxref{Package Modules}), maintain them in a Git repository, and -then you and anyone else can use it as an additional channel to get packages -from. Neat, no? +command line. By creating a @dfn{channel}, you can use and publish such +a package collection. This involves the following steps: + +@enumerate +@item +Channels live in a Git repository so the first step, when creating a +channel, is to create its repository: + +@example +mkdir my-channel +cd my-channel +git init +@end example + +@item +The next step is to create files containing package modules +(@pxref{Package Modules}), each of which will contain one or more +package definitions (@pxref{Defining Packages}). A channel can provide +things other than packages, such as build systems or services; we're +using packages as most common use case. + +For example, Alice might want to provide a module called @code{(alice +packages greetings)} that will provide her favorite ``hello world'' +implementations. To do that Alice will create a directory corresponding +to that module name. + +@example +mkdir -p alice/packages +$EDITOR alice/packages/greetings.scm +git add alice/packages/greetings.scm +@end example + +You can name your package modules however you like; the main constraint +to keep in mind is to avoid name clashes with other package collections, +which is why our hypothetical Alice wisely chose the @code{(alice +packages @dots{})} name space. + +Note that you can also place modules in a sub-directory of the +repository; @pxref{Package Modules in a Sub-directory}, for more info on +that. + +@item +With this first module in place, the next step is to test the packages +it provides. This can be done with @command{guix build}, which needs to +be fold to look for modules in the Git checkout. For example, assuming +@code{(alice packages greetings)} provides a package called +@code{hi-from-alice}, Alice will run this command from the Git checkout: + +@example +guix build -L. hi-from-alice +@end example + +@noindent +... where @code{-L.} adds the current directory to Guile's load path +(@pxref{Load Paths,,, guile, GNU Guile Reference Manual}). + +@item +It might take Alice a few iterations to obtain satisfying package +definitions. Eventually Alice will commit this file: + +@example +git commit +@end example + +As a channel author, consider bundling authentication material with your +channel so that users can authenticate it. @xref{Channel +Authentication}, and @ref{Specifying Channel Authorizations}, for info +on how to do it. + +@item +To use Alice's channel, anyone can now add it to their channel file +(@pxref{Specifying Additional Channels}) and run @command{guix pull} +(@pxref{Invoking guix pull}): + +@example +$EDITOR ~/.config/guix/channels.scm +guix pull +@end example + +Guix will now behave as if the root directory of that channel's Git +repository had been permanently added to the Guile load path. In this +example, @code{(alice packages greetings)} will automatically be found +by the @command{guix} command. +@end enumerate + +Voilà! @c What follows stems from discussions at @c as well as @c earlier discussions on guix-devel@gnu.org. @quotation Warning -Before you, dear user, shout---``woow this is @emph{soooo coool}!''---and -publish your personal channel to the world, we would like to share a few words -of caution: +Before you publish your channel, we would like to share a few words of +caution: @itemize @item @@ -5663,13 +5744,11 @@ Creating a Channel process. @item -When you maintain package definitions outside Guix, we, Guix developers, -consider that @emph{the compatibility burden is on you}. Remember that -package modules and package definitions are just Scheme code that uses various -programming interfaces (APIs). We want to remain free to change these APIs to -keep improving Guix, possibly in ways that break your channel. We never -change APIs gratuitously, but we will @emph{not} commit to freezing APIs -either. +Package modules and package definitions are Scheme code that uses +various programming interfaces (APIs). We, Guix developers, never +change APIs gratuitously, but we do @emph{not} commit to freezing APIs +either. When you maintain package definitions outside Guix, we consider +that @emph{the compatibility burden is on you}. @item Corollary: if you're using an external channel and that channel breaks, please @@ -5683,21 +5762,6 @@ Creating a Channel email us at @email{guix-devel@@gnu.org} if you'd like to discuss this. @end quotation -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}). - -As a channel author, consider bundling authentication material with your -channel so that users can authenticate it. @xref{Channel -Authentication}, and @ref{Specifying Channel Authorizations}, for info -on how to do it. @node Package Modules in a Sub-directory base-commit: 9504dd2c3eef0277369acc0944f87fb4546251b1 -- 2.40.1 From debbugs-submit-bounces@debbugs.gnu.org Sat Jun 24 10:25:00 2023 Received: (at control) by debbugs.gnu.org; 24 Jun 2023 14:25:00 +0000 Received: from localhost ([127.0.0.1]:41189 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qD4CC-0001Xm-Ew for submit@debbugs.gnu.org; Sat, 24 Jun 2023 10:25:00 -0400 Received: from mail2-relais-roc.national.inria.fr ([192.134.164.83]:5754) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qD4CA-0001XJ-Io for control@debbugs.gnu.org; Sat, 24 Jun 2023 10:24:58 -0400 Authentication-Results: mail2-relais-roc.national.inria.fr; dkim=none (message not signed) header.i=none; spf=SoftFail smtp.mailfrom=ludo@gnu.org; dmarc=fail (p=none dis=none) d=gnu.org X-IronPort-AV: E=Sophos;i="6.01,155,1684792800"; d="scan'208";a="114481572" Received: from 91-160-117-201.subs.proxad.net (HELO ribbon) ([91.160.117.201]) by mail2-relais-roc.national.inria.fr with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 24 Jun 2023 16:24:56 +0200 Date: Sat, 24 Jun 2023 16:24:53 +0200 Message-Id: <87ilbd0wga.fsf@gnu.org> To: control@debbugs.gnu.org From: =?utf-8?Q?Ludovic_Court=C3=A8s?= Subject: control message for bug #64040 MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -1.3 (-) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.3 (--) close 64040 quit From unknown Sun Aug 17 00:58:53 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Sun, 23 Jul 2023 11:24:08 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator