From unknown Thu Aug 14 21:55:19 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#43482 <43482@debbugs.gnu.org> To: bug#43482 <43482@debbugs.gnu.org> Subject: Status: [PATCH 0/3] doc: Reorder "Channels" section Reply-To: bug#43482 <43482@debbugs.gnu.org> Date: Fri, 15 Aug 2025 04:55:19 +0000 retitle 43482 [PATCH 0/3] doc: Reorder "Channels" section reassign 43482 guix-patches submitter 43482 zimoun severity 43482 normal tag 43482 patch thanks From debbugs-submit-bounces@debbugs.gnu.org Thu Sep 17 21:37:59 2020 Received: (at submit) by debbugs.gnu.org; 18 Sep 2020 01:37:59 +0000 Received: from localhost ([127.0.0.1]:40172 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kJ5Lb-0002va-Ee for submit@debbugs.gnu.org; Thu, 17 Sep 2020 21:37:59 -0400 Received: from lists.gnu.org ([209.51.188.17]:39820) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kJ5La-0002vU-IA for submit@debbugs.gnu.org; Thu, 17 Sep 2020 21:37:58 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:54846) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kJ5La-0002uN-Bh for guix-patches@gnu.org; Thu, 17 Sep 2020 21:37:58 -0400 Received: from mail-wr1-x42a.google.com ([2a00:1450:4864:20::42a]:43414) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kJ5LY-0003pz-8q for guix-patches@gnu.org; Thu, 17 Sep 2020 21:37:57 -0400 Received: by mail-wr1-x42a.google.com with SMTP id k15so3913732wrn.10 for ; Thu, 17 Sep 2020 18:37:55 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; bh=lci0a7cs8oQWU9Z2KkpdL1d2WlCgqI8z9/8X6rDnlY4=; b=WPQe+1bs0WaDv0U05Rrp55aiHiF+rkPJBylN7lG3HruybYHXmXg30thXvFSuZgGSLJ t4FDoSdjmjNCQSWEQd2bemObr7xNPxjV9vAdawGMoF2/Nihuzx06wET8T5fZS8Yr7MOI euUIAe07X3mdtSP31BBPpXLJNpmUVrh8rk2+XQ14cKBFIl1d8yKSPsxaBmUEN2p4+45D cbFiJFgc/71WSvQi43M440+XVY65lYB7aHw+fZeWMcmJWgaU78O/08EDbbpIGW7PKSVO 6+G3YnjfDYwLZNaJr//Ie8Z2J+tWy9SiHgdz8rUlxB1OpG3tg40DQ6hYtqm14BEW0Bmp Joog== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; bh=lci0a7cs8oQWU9Z2KkpdL1d2WlCgqI8z9/8X6rDnlY4=; b=Ret3zbB9lCOxJxo3xrWgxrG+V1aWa/9UM+Syb6VvwveDpemAegBPUyXDv4g3yBLJdN fPenmvU2INdSOV/jJM95wPOL0SM30DxWceC15qUog0/qwe5xDnKhsnbD95rRlN/bUflJ PLzvJdxDEz0gR9M+fhLdqZZyM+Z4GoULjjQcqZGR9ZcAr+NnbtCbhOKMJ57Zxgq2k6dp fF9GuPPPyexYgkMl9VFGCotM4RSdQH6BNLsoq7LiOVhFHkBi0StDIg/rRyyQmfI/27id eKmjDJppy3H7V3100a/Xpx1fNNm4RaYuXZ0G6WKIwNo/GTcU4ZCpm5DfojdDepBR3Od2 sg0A== X-Gm-Message-State: AOAM5339f3i/rb7T7nGdAa31Gc/lIE4fXB5cTmUF7VLh9XyNh2KxDXqA 140gxoyh0tuk5hI6Icc5rNdrZXvE0tQ= X-Google-Smtp-Source: ABdhPJy+jfwlSryrquGndq7wUsJCrEp6hP2jtVnQ8L0BwjxcEfLqssFTJUMPTxzndVVPfl4vIABozw== X-Received: by 2002:a5d:4d8a:: with SMTP id b10mr34596219wru.82.1600393073923; Thu, 17 Sep 2020 18:37:53 -0700 (PDT) Received: from lili.univ-paris-diderot.fr ([88.126.110.68]) by smtp.gmail.com with ESMTPSA id c4sm2065763wrp.85.2020.09.17.18.37.52 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 17 Sep 2020 18:37:53 -0700 (PDT) From: zimoun To: guix-patches@gnu.org Subject: [PATCH 0/3] doc: Reorder "Channels" section Date: Fri, 18 Sep 2020 03:37:44 +0200 Message-Id: <20200918013744.3448-1-zimon.toutoune@gmail.com> X-Mailer: git-send-email 2.28.0 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Received-SPF: pass client-ip=2a00:1450:4864:20::42a; envelope-from=zimon.toutoune@gmail.com; helo=mail-wr1-x42a.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-Spam-Score: 0.7 (/) X-Debbugs-Envelope-To: submit Cc: zimoun 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 (--) Dear, As discussed here [1], the Channels is modified to satisfy a more logical order, at least mine. :-) The patch 0003 can be hard to review. Basically, I have moved the sections: 5.6 Invoking @command{guix pull} 5.7 Channels 5.7.1 Specifying Additional Channels 5.7.2 Using a Custom Guix Channel 5.7.3 Replicating Guix 5.7.4 Channel Authentication 5.7.5 Primary URL 5.7.6 Writing custom channels 5.7.7 Package Modules in a Sub-directory 5.7.8 Declaring Channel Dependencies 5.7.9 Specifying Channel Authorizations 5.7.10 Writing Channel News 5.8 Invoking @command{guix time-machine} And I did some minor tweaks trying to have user vs developer of channels. Say that from 5.7.1 to 5.7.5, the channel are collection of "variants". Then it becomes "your own channel". I added these words which deserve a better wording, I guess. --8<---------------cut here---------------start------------->8--- Last, as a channel author, you may want to run an authenticated channel (@pxref{Channel Authentication}), then @pxref{Specifying Channel Authorizations} for details. --8<---------------cut here---------------end--------------->8--- At the end of the section "Writing custom channels". And after some thinking, I find better to have "guix pull" and time-machine visible from Package Management section: . Well, that is a start. :-) [1] https://lists.gnu.org/archive/html/guix-devel/2020-09/msg00153.html All the best, simon zimoun (3): doc: Update the master menu. doc: Add the "Channels" section menu. doc: Reorder the "Channels" section. doc/guix.texi | 353 +++++++++++++++++++++++++++++--------------------- 1 file changed, 202 insertions(+), 151 deletions(-) base-commit: 679d5e6b3dcac4ee1f419c04b3719fead0bd9ee5 -- 2.28.0 From debbugs-submit-bounces@debbugs.gnu.org Thu Sep 17 21:45:17 2020 Received: (at 43482) by debbugs.gnu.org; 18 Sep 2020 01:45:17 +0000 Received: from localhost ([127.0.0.1]:40179 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kJ5Sf-00036w-92 for submit@debbugs.gnu.org; Thu, 17 Sep 2020 21:45:17 -0400 Received: from mail-wm1-f48.google.com ([209.85.128.48]:55100) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kJ5Sd-00036c-GP for 43482@debbugs.gnu.org; Thu, 17 Sep 2020 21:45:15 -0400 Received: by mail-wm1-f48.google.com with SMTP id s13so3723707wmh.4 for <43482@debbugs.gnu.org>; Thu, 17 Sep 2020 18:45:15 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; bh=lKWZYqGSn/p0QY50K3+SuUI2P93JgKeiFZFyQRDNXRA=; b=m7kw7BT8KA+Qq9APsTfciu7uJG2m/jVZc9sQQauj8dW1V21o2OiHvFWLbojB0OEtVF zCsGQo9WDOSzTkMAGwTQYwdij/RR9F7MftEhew3UzLuGQoFQt4UkzmKampK3KqkDMNl6 +Mu3IWCyA5dBceRaegaQ8ORpgP6ILLhVg4VtO+LTX4vyvgV2Wzj38ahekqLvse0xbO8t VxBDrcs1uD3LUUaqWUm1myINUNT5l8Czus4nvR6/uPyF6OLHg9kvju0KcALrLFTARxvv YMsa/Gru+lVFcUzCMeDqVjKkQ07N7sGiHPgc2aZ+s/OKdgEPdLfm4JXbdxtMi/UUC4nn 53fA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; bh=lKWZYqGSn/p0QY50K3+SuUI2P93JgKeiFZFyQRDNXRA=; b=V+Noc1kZzBOi3vZDH5uEPmK2Hc1u/xtmtcFyshApm7EwC8KKJ3/+F8mRG2a31WUujq /XJg2YYFrGJ/NzqnOZlw431wYeOdgZS9YaElFxtf0Y8QaB7m0VMluwCo7RGNw/PWUPQ5 +seKevWj8lRhtbWgRpBjbimN65I/bftxrh5eu7hlF6HkMjPOPuuiNjFE8vb5rTp/ubGD TwnFjF4QPVmr+YnYDgigJkDLh8aeEBpwv7Z3/UAqf2TBJPOYdSQ5LQjd47np3wbxoT56 6MWlfLUOajfYKcSuzQOmXrPebIY2/Howel61D6fmPIJuCC53cgHH1u+SXE5EAQfs2lB2 +H+Q== X-Gm-Message-State: AOAM533EXkU+Floh74ECtRzF/IaR6j1fQWW9xIML7PU5Ck+SR3nN5ilx QdCo+ixWT/RWWgbVcpb54glItd+RIjo= X-Google-Smtp-Source: ABdhPJzYj4Ct+jggwfraN28LOvUQhizve+Feta2mnXko2gIS5SR9HYpcrcRVTc1JmuMQs2mNK8hi1g== X-Received: by 2002:a05:600c:230f:: with SMTP id 15mr12857768wmo.186.1600393509341; Thu, 17 Sep 2020 18:45:09 -0700 (PDT) Received: from lili.univ-paris-diderot.fr ([88.126.110.68]) by smtp.gmail.com with ESMTPSA id q15sm2144919wrr.8.2020.09.17.18.45.08 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 17 Sep 2020 18:45:08 -0700 (PDT) From: zimoun To: 43482@debbugs.gnu.org Subject: [PATCH 1/3] doc: Update the master menu. Date: Fri, 18 Sep 2020 03:45:00 +0200 Message-Id: <20200918014502.6081-1-zimon.toutoune@gmail.com> X-Mailer: git-send-email 2.28.0 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 43482 Cc: zimoun 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: -1.0 (-) * doc/guix.texi: Update the master menu. --- doc/guix.texi | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/doc/guix.texi b/doc/guix.texi index 88128a4b3a..5a1f2e3bc3 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -178,6 +178,7 @@ Installation * Setting Up the Daemon:: Preparing the build daemon's environment. * Invoking guix-daemon:: Running the build daemon. * Application Setup:: Application-specific setup. +* Upgrading Guix:: Upgrading Guix and its build daemon. Setting Up the Daemon @@ -197,8 +198,6 @@ System Installation * Installing Guix in a VM:: Guix System playground. * Building the Installation Image:: How this comes to be. -Getting Started - Manual Installation * Keyboard Layout and Networking and Partitioning:: Initial setup. @@ -232,6 +231,7 @@ Development * Invoking guix environment:: Setting up development environments. * Invoking guix pack:: Creating software bundles. * The GCC toolchain:: Working with languages supported by GCC. +* Invoking guix git authenticate:: Authenticating Git repositories. Programming Interface @@ -300,6 +300,7 @@ Services * Scheduled Job Execution:: The mcron service. * Log Rotation:: The rottlog service. * Networking Services:: Network setup, SSH daemon, etc. +* Unattended Upgrades:: Automated system upgrades. * X Window:: Graphical display. * Printing Services:: Local and remote printer support. * Desktop Services:: D-Bus and desktop services. @@ -310,6 +311,7 @@ Services * Telephony Services:: Telephony services. * Monitoring Services:: Monitoring services. * Kerberos Services:: Kerberos services. +* LDAP Services:: LDAP services. * Web Services:: Web servers. * Certificate Services:: TLS certificates via Let's Encrypt. * DNS Services:: DNS daemons. @@ -324,7 +326,7 @@ Services * PAM Mount Service:: Service to mount volumes when logging in. * Guix Services:: Services relating specifically to Guix. * Linux Services:: Services tied to the Linux kernel. -* Hurd Services:: Services specific to a Hurd System. +* Hurd Services:: Services specific for a Hurd System. * Miscellaneous Services:: Other services. Defining Services @@ -334,6 +336,11 @@ Defining Services * Service Reference:: API reference. * Shepherd Services:: A particular type of service. +Bootstrapping + +* Reduced Binary Seed Bootstrap:: A Bootstrap worthy of GNU. +* Preparing to Use the Bootstrap Binaries:: Building that what matters most. + @end detailmenu @end menu -- 2.28.0 From debbugs-submit-bounces@debbugs.gnu.org Thu Sep 17 21:45:18 2020 Received: (at 43482) by debbugs.gnu.org; 18 Sep 2020 01:45:18 +0000 Received: from localhost ([127.0.0.1]:40181 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kJ5Sf-00036y-LV for submit@debbugs.gnu.org; Thu, 17 Sep 2020 21:45:18 -0400 Received: from mail-wm1-f46.google.com ([209.85.128.46]:50976) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kJ5Se-00036e-8P for 43482@debbugs.gnu.org; Thu, 17 Sep 2020 21:45:16 -0400 Received: by mail-wm1-f46.google.com with SMTP id e17so3733662wme.0 for <43482@debbugs.gnu.org>; Thu, 17 Sep 2020 18:45:16 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=Q0Kcw/1ioIETOFFX8GR8DtbvqjsEYe8NDJlFGi69hKA=; b=YvnHN6VtnSXAdEgeJOnlILs8E50iEJKW9ZUrZjherZ14S2XroZNrNHJPp/kf8rbvne 3z3TUox5unVBHWGPUtB66WLHPFDZObg9uj7CKaArSdqYIo4FS4UBeNzRjFgb6Gc/+Qmf DwmidQ/O3IDO13uWcjM3Waw6W/FJzZTZGdppJmVSFhdgjGIgeXZgsTaOKPokK8TAkGxs 74tDy1WvGvAAy6bNStRVUE4LMmi/YSZZo9kYvsMFpvp4jfQNkJsHOk3ay7oFruzqIAxs TehwFIWeAXoKzLwW1ntZjgLkTYvCt8HN5mziOdjoR8j5xFibZSFl/TekqwceLk3K7EZI v22g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=Q0Kcw/1ioIETOFFX8GR8DtbvqjsEYe8NDJlFGi69hKA=; b=iExt6M7ossut82fcYetAkOhqTSnQNs4/tRYkeARCr36uBSLCaDcrW7Rv0zOHQkGqrA Ls3J6gPQ1hI1CWymlnFr/5HABxmN0DwjZa1HTPp7oY7Pe2pyS7IcX1JtRwF0XMJKJzTJ l2VejAPGksZDZOxC2779o78aexPvgWypMRVUXs8EzwzmQCTjRVX+Wo04BF12hP57Iaqd k4oJcF/ta5dzUj5CuQ8FD5PXQtREwpkEKO5dKdj/Fmv8fz0iG+Xrg+23xz5/cX7V1q0p pr6h8pbW4nUeKtmzql7KZWR7WqMPVQgP67FCQTTQvHYKNxTmQAa2x5xRisKO29+IhLYI nxsA== X-Gm-Message-State: AOAM530Ft36xSd2i0oW82PCOQyR+escyO2IXqVSkhKFZdnEnMcb95GJ4 TjnGq236AJRpF53SdfrHu45eH2VEHjw= X-Google-Smtp-Source: ABdhPJzTxIaOufMv7F9OYmiebk3vFp+Pcj0hhmGhz4A5XV16RvdxqYbwL19iAxHObSpe0Gf6fePStQ== X-Received: by 2002:a1c:40c6:: with SMTP id n189mr12680009wma.48.1600393510261; Thu, 17 Sep 2020 18:45:10 -0700 (PDT) Received: from lili.univ-paris-diderot.fr ([88.126.110.68]) by smtp.gmail.com with ESMTPSA id q15sm2144919wrr.8.2020.09.17.18.45.09 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 17 Sep 2020 18:45:09 -0700 (PDT) From: zimoun To: 43482@debbugs.gnu.org Subject: [PATCH 2/3] doc: Add the "Channels" section menu. Date: Fri, 18 Sep 2020 03:45:01 +0200 Message-Id: <20200918014502.6081-2-zimon.toutoune@gmail.com> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20200918014502.6081-1-zimon.toutoune@gmail.com> References: <20200918014502.6081-1-zimon.toutoune@gmail.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 43482 Cc: zimoun 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: -1.0 (-) * doc/guix.texi (Channels): Add the section menu. --- doc/guix.texi | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/doc/guix.texi b/doc/guix.texi index 5a1f2e3bc3..f30faf257a 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -226,6 +226,18 @@ Substitutes * Substitution Failure:: What happens when substitution fails. * On Trusting Binaries:: How can you trust that binary blob? +Channels + +* Channel Authentication:: How Guix verifies what it fetches. +* Using a Custom Guix Channel:: Using a customized Guix. +* Specifying Additional Channels:: Extending the package collection. +* Declaring Channel Dependencies:: Declaring channel dependencies. +* Package Modules in a Sub-directory:: Package Modules in a Sub-directory. +* Specifying Channel Authorizations:: Specifying Channel Authorizations. +* Primary URL:: Distinguishing mirror to original. +* Writing Channel News:: Communicating information to channel's users. +* Replicating Guix:: Running the @emph{exact same} Guix. + Development * Invoking guix environment:: Setting up development environments. @@ -4206,6 +4218,19 @@ to pull from one or more channels. In other words, channels can be used to @emph{customize} and to @emph{extend} Guix, as we will see below. Before that, some security considerations. +@menu +* Channel Authentication:: How Guix verifies what it fetches. +* Using a Custom Guix Channel:: Using a customized Guix. +* Specifying Additional Channels:: Extending the package collection. +* Declaring Channel Dependencies:: Declaring channel dependencies. +* Package Modules in a Sub-directory:: Package Modules in a Sub-directory. +* Specifying Channel Authorizations:: Specifying Channel Authorizations. +* Primary URL:: Distinguishing mirror to original. +* Writing Channel News:: Communicating information to channel's users. +* Replicating Guix:: Running the @emph{exact same} Guix. +@end menu + +@node Channel Authentication @subsection Channel Authentication @anchor{channel-authentication} @@ -4245,6 +4270,7 @@ introduction from a trusted source since that is the root of your trust. If you're curious about the authentication mechanics, read on! +@node Using a Custom Guix Channel @subsection Using a Custom Guix Channel The channel called @code{guix} specifies where Guix itself---its command-line @@ -4265,6 +4291,7 @@ write in @code{~/.config/guix/channels.scm} this specification: From there on, @command{guix pull} will fetch code from the @code{super-hacks} branch of the repository at @code{example.org}. +@node Specifying Additional Channels @subsection Specifying Additional Channels @cindex extending the package collection (channels) @@ -4373,6 +4400,7 @@ my-tools)}, and you will be able to use it like any other module @cindex dependencies, channels @cindex meta-data, channels +@node Declaring Channel Dependencies @subsection Declaring Channel Dependencies Channel authors may decide to augment a package collection provided by other @@ -4413,6 +4441,7 @@ on channels that you don't control, and you should aim to keep the number of dependencies to a minimum. @cindex subdirectory, channels +@node Package Modules in a Sub-directory @subsection Package Modules in a Sub-directory As a channel author, you may want to keep your channel modules in a @@ -4426,6 +4455,7 @@ add a meta-data file @file{.guix-channel} that contains: @end lisp @cindex channel authorizations +@node Specifying Channel Authorizations @subsection Specifying Channel Authorizations @anchor{channel-authorizations} @@ -4526,6 +4556,7 @@ are considered authentic if and only if they are signed by a key present in the @file{.guix-authorizations} file of @emph{both} branches. @cindex primary URL, channels +@node Primary URL @subsection Primary URL Channel authors can indicate the primary URL of their channel's Git @@ -4548,6 +4579,7 @@ the official @code{guix} channel, for which @command{guix pull} ensures the code it fetches is authentic. @cindex news, for channels +@node Writing Channel News @subsection Writing Channel News Channel authors may occasionally want to communicate to their users @@ -4615,6 +4647,7 @@ xgettext -o news.po -l scheme -ken etc/news.txt To sum up, yes, you could use your channel as a blog. But beware, this is @emph{not quite} what your users might expect. +@node Replicating Guix @subsection Replicating Guix @cindex pinning, channels -- 2.28.0 From debbugs-submit-bounces@debbugs.gnu.org Thu Sep 17 21:45:23 2020 Received: (at 43482) by debbugs.gnu.org; 18 Sep 2020 01:45:23 +0000 Received: from localhost ([127.0.0.1]:40184 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kJ5Sk-00037M-5I for submit@debbugs.gnu.org; Thu, 17 Sep 2020 21:45:23 -0400 Received: from mail-wm1-f48.google.com ([209.85.128.48]:36087) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kJ5Sf-00036h-U9 for 43482@debbugs.gnu.org; Thu, 17 Sep 2020 21:45:19 -0400 Received: by mail-wm1-f48.google.com with SMTP id z9so3909818wmk.1 for <43482@debbugs.gnu.org>; Thu, 17 Sep 2020 18:45:17 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=xgGPcSMr+SVy0zGHHD+8A5Be4P4r5ka8lxmvLC6gOJ0=; b=N798lsukEdQKIQgVSierJX0iLxcEdIGIScaZsDbNc2yvMgw41DwNawmPUmGm9TdG87 jTGrbcePLRdLFnDYJpSN5iZRwp+opGc4iiyY40RoYL26LZ4tL6i3UdyRiUiT/w702b0s 3RSLon39Mcz3nWDbvr6DsA2FTLuQ+etH2xjPctIJGiT4kL+l8vV9hA9FhSE3JXG/5vTD h9dpQzD44w6EyUSE+uWh5TxmeT5iC49dvnF/1JCDVxJ+KUkX/LXwN6XEuwpveSsK3Vym ehADqU1rGoiq8Q62FVSXc1AQtgGv0lty+Bw8bJ6+zU0LSPxiOMvZ1eEh1M+Q7hgoJ0BT LN+A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=xgGPcSMr+SVy0zGHHD+8A5Be4P4r5ka8lxmvLC6gOJ0=; b=JtNKfcG1B5DxAHNj3ervpiprSOU+014tZCwo78mC/bg0vo4LYHOakyBNHRv1+xnoQE OC+EApq/FXsKZYZYyHz/LBPB9GJ7tFXPWT51fm97R99qbA1T2zKUyY52G7oiB/x5zxna jTjpLi1vQuXKP4JMrnTWEN60tGE4uhvPPVVsmyumMhlErlXSh/Qp27ixmNAGHfJd5Z00 bnTF3Z8hCswl3BV8ijEHcbL+K9RAjBldNPAVqMz8XpYDC8IOOh2vnbkl0L4FqZZVJU99 1mLYq/5YRe5JRyuQPYeHGayUf6dfFK96JUudYPJxXlhlGIDb5/MnzE1N74sMOoELS1L/ 7QQA== X-Gm-Message-State: AOAM533VrtMP2ELV2Svu9aFPjAnwnSzXkVg9k3cwBOhifR8gv2vfJdvl 54WAeoMqWPpYSSb+NURovX9S8+DONqY= X-Google-Smtp-Source: ABdhPJyORp/yU+fEN9j67fB7dXKD7Kf0T5fkPeIVdF+ST2NQA4Hdg7NRHZMjBMcfhCjolmk2Ti1w0w== X-Received: by 2002:a1c:7911:: with SMTP id l17mr12699909wme.179.1600393511243; Thu, 17 Sep 2020 18:45:11 -0700 (PDT) Received: from lili.univ-paris-diderot.fr ([88.126.110.68]) by smtp.gmail.com with ESMTPSA id q15sm2144919wrr.8.2020.09.17.18.45.10 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 17 Sep 2020 18:45:10 -0700 (PDT) From: zimoun To: 43482@debbugs.gnu.org Subject: [PATCH 3/3] doc: Reorder the "Channels" section. Date: Fri, 18 Sep 2020 03:45:02 +0200 Message-Id: <20200918014502.6081-3-zimon.toutoune@gmail.com> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20200918014502.6081-1-zimon.toutoune@gmail.com> References: <20200918014502.6081-1-zimon.toutoune@gmail.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 43482 Cc: zimoun 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: -1.0 (-) * doc/guix.texi (Channels): Reorder the section. Minor tweaks to keep uniformity. Update the master menu. --- doc/guix.texi | 342 ++++++++++++++++++++++++++------------------------ 1 file changed, 177 insertions(+), 165 deletions(-) diff --git a/doc/guix.texi b/doc/guix.texi index f30faf257a..015c8c9736 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -228,15 +228,16 @@ Substitutes Channels +* Specifying Additional Channels:: Extending the package collection. +* Using a Custom Guix Channel:: Using a customized Guix. +* Replicating Guix:: Running the @emph{exact same} Guix. * Channel Authentication:: How Guix verifies what it fetches. -* Using a Custom Guix Channel:: Using a customized Guix. -* Specifying Additional Channels:: Extending the package collection. -* Declaring Channel Dependencies:: Declaring channel dependencies. -* Package Modules in a Sub-directory:: Package Modules in a Sub-directory. -* Specifying Channel Authorizations:: Specifying Channel Authorizations. * Primary URL:: Distinguishing mirror to original. +* Writing custom channels:: How to setup your own channel. +* Package Modules in a Sub-directory:: Specifying the channel's package modules location. +* Declaring Channel Dependencies:: How to depend on other channels. +* Specifying Channel Authorizations:: Defining channel authors authorizations. * Writing Channel News:: Communicating information to channel's users. -* Replicating Guix:: Running the @emph{exact same} Guix. Development @@ -4216,20 +4217,135 @@ customized by defining @dfn{channels} in the of a Git repository to be deployed, and @command{guix pull} can be instructed to pull from one or more channels. In other words, channels can be used to @emph{customize} and to @emph{extend} Guix, as we will see below. -Before that, some security considerations. +Guix is able to take into account security concerns and deal with authenticated +updates. @menu +* Specifying Additional Channels:: Extending the package collection. +* Using a Custom Guix Channel:: Using a customized Guix. +* Replicating Guix:: Running the @emph{exact same} Guix. * Channel Authentication:: How Guix verifies what it fetches. -* Using a Custom Guix Channel:: Using a customized Guix. -* Specifying Additional Channels:: Extending the package collection. -* Declaring Channel Dependencies:: Declaring channel dependencies. -* Package Modules in a Sub-directory:: Package Modules in a Sub-directory. -* Specifying Channel Authorizations:: Specifying Channel Authorizations. * Primary URL:: Distinguishing mirror to original. +* Writing custom channels:: How to setup your own channel. +* Package Modules in a Sub-directory:: Specifying the channel's package modules location. +* Declaring Channel Dependencies:: How to depend on other channels. +* Specifying Channel Authorizations:: Defining channel authors authorizations. * Writing Channel News:: Communicating information to channel's users. -* Replicating Guix:: Running the @emph{exact same} Guix. @end menu +@node Specifying Additional Channels +@subsection 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 the default Guix channel(s): + +@vindex %default-channels +@lisp +;; Add variant packages to those Guix provides. +(cons (channel + (name 'variant-packages) + (url "https://example.org/variant-packages.git")) + %default-channels) +@end lisp + +@noindent +Note that the snippet above is (as always!)@: Scheme code; we use @code{cons} to +add a channel 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 your own repository. The result in +@file{~/.config/guix/current} is the union of Guix with your own 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-packages dd3df5e + repository URL: https://example.org/variant-packages.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 from the @code{variant-personal-packages} 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-packages}, while others come from the Guix default channel. + +@node Using a Custom Guix Channel +@subsection Using a Custom Guix Channel + +The channel called @code{guix} specifies where Guix itself---its command-line +tools as well as its package collection---should be downloaded. For instance, +suppose you want to update from another copy of the Guix repository at +@code{example.org}, and specifically the @code{super-hacks} branch, you can +write in @code{~/.config/guix/channels.scm} this specification: + +@lisp +;; Tell 'guix pull' to use another repo. +(list (channel + (name 'guix) + (url "https://example.org/another-guix.git") + (branch "super-hacks"))) +@end lisp + +@noindent +From there on, @command{guix pull} will fetch code from the @code{super-hacks} +branch of the repository at @code{example.org}. The authentication concern is +addressed below ((@pxref{Channel Authentication}). + +@node Replicating Guix +@subsection Replicating Guix + +@cindex pinning, channels +@cindex replicating Guix +@cindex reproducibility, of Guix +The @command{guix pull --list-generations} output above shows precisely which +commits were used to build this instance of Guix. We can thus replicate it, +say, on another machine, by providing a channel specification in +@file{~/.config/guix/channels.scm} that is ``pinned'' to these commits: + +@lisp +;; Deploy specific commits of my channels of interest. +(list (channel + (name 'guix) + (url "https://git.savannah.gnu.org/git/guix.git") + (commit "6298c3ffd9654d3231a6f25390b056483e8f407c")) + (channel + (name 'variant-packages) + (url "https://example.org/variant-packages.git") + (commit "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb"))) +@end lisp + +The @command{guix describe --format=channels} command can even generate this +list of channels directly (@pxref{Invoking guix describe}). The resulting +file can be used with the -C options of @command{guix pull} +(@pxref{Invoking guix pull}) or @command{guix time-machine} +(@pxref{Invoking guix time-machine}). + +At this point the two machines run the @emph{exact same Guix}, with access to +the @emph{exact same packages}. The output of @command{guix build gimp} on +one machine will be exactly the same, bit for bit, as the output of the same +command on the other machine. It also means both machines have access to all +the source code of Guix and, transitively, to all the source code of every +package it defines. + +This gives you super powers, allowing you to track the provenance of binary +artifacts with very fine grain, and to reproduce software environments at +will---some sort of ``meta reproducibility'' capabilities, if you will. +@xref{Inferiors}, for another way to take advantage of these super powers. + @node Channel Authentication @subsection Channel Authentication @@ -4248,8 +4364,8 @@ along these lines: @lisp (channel - (name 'my-channel) - (url "https://example.org/my-channel.git") + (name 'some-channel) + (url "https://example.org/some-channel.git") (introduction (make-channel-introduction "6f0d8cc0d88abb59c324b2990bfee2876016bb86" @@ -4270,40 +4386,41 @@ introduction from a trusted source since that is the root of your trust. If you're curious about the authentication mechanics, read on! -@node Using a Custom Guix Channel -@subsection Using a Custom Guix Channel +@cindex primary URL, channels +@node Primary URL +@subsection Primary URL -The channel called @code{guix} specifies where Guix itself---its command-line -tools as well as its package collection---should be downloaded. For instance, -suppose you want to update from your own copy of the Guix repository at -@code{example.org}, and specifically the @code{super-hacks} branch, you can -write in @code{~/.config/guix/channels.scm} this specification: +Channel authors can indicate the primary URL of their channel's Git +repository in the @file{.guix-channel} file, like so: @lisp -;; Tell 'guix pull' to use my own repo. -(list (channel - (name 'guix) - (url "https://example.org/my-guix.git") - (branch "super-hacks"))) +(channel + (version 0) + (url "https://example.org/guix.git")) @end lisp -@noindent -From there on, @command{guix pull} will fetch code from the @code{super-hacks} -branch of the repository at @code{example.org}. +This allows @command{guix pull} to determine whether it is pulling code +from a mirror of the channel; when that is the case, it warns the user +that the mirror might be stale and displays the primary URL. That way, +users cannot be tricked into fetching code from a stale mirror that does +not receive security updates. -@node Specifying Additional Channels -@subsection Specifying Additional Channels +This feature only makes sense for authenticated repositories, such as +the official @code{guix} channel, for which @command{guix pull} ensures +the code it fetches is authentic. -@cindex extending the package collection (channels) @cindex personal packages (channels) @cindex channels, for personal packages -You can also specify @emph{additional channels} to pull from. 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? +@node Writing custom channels +@subsection Writing custom channels + +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? @c What follows stems from discussions at @c as well as @@ -4342,51 +4459,6 @@ 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 -To use a channel, write @code{~/.config/guix/channels.scm} to instruct -@command{guix pull} to pull from it @emph{in addition} to the default Guix -channel(s): - -@vindex %default-channels -@lisp -;; Add my personal packages to those Guix provides. -(cons (channel - (name 'my-personal-packages) - (url "https://example.org/personal-packages.git")) - %default-channels) -@end lisp - -@noindent -Note that the snippet above is (as always!)@: Scheme code; we use @code{cons} to -add a channel 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 your own repository. The result in -@file{~/.config/guix/current} is the union of Guix with your own 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 - my-personal-packages dd3df5e - repository URL: https://example.org/personal-packages.git - branch: master - commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb - 11 new packages: my-gimp, my-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 from the @code{my-personal-packages} channel. Among -the new and upgraded packages that are listed, some like @code{my-gimp} and -@code{my-emacs-with-cool-features} might come from -@code{my-personal-packages}, while others come from the Guix default channel. - 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 @@ -4398,6 +4470,24 @@ 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}). +Last, as a channel author, you may want to run an authenticated channel +(@pxref{Channel Authentication}), then @pxref{Specifying Channel +Authorizations} for details. + +@cindex subdirectory, channels +@node Package Modules in a Sub-directory +@subsection Package Modules in a Sub-directory + +As a channel author, you may want to keep your channel modules in a +sub-directory. If your modules are in the sub-directory @file{guix}, you must +add a meta-data file @file{.guix-channel} that contains: + +@lisp +(channel + (version 0) + (directory "guix")) +@end lisp + @cindex dependencies, channels @cindex meta-data, channels @node Declaring Channel Dependencies @@ -4415,7 +4505,7 @@ The meta-data file should contain a simple S-expression like this: (version 0) (dependencies (channel - (name some-collection) + (name 'some-collection) (url "https://example.org/first-collection.git") ;; The 'introduction' bit below is optional: you would @@ -4426,7 +4516,7 @@ The meta-data file should contain a simple S-expression like this: (commit "a8883b58dc82e167c96506cf05095f37c2c2c6cd") (signer "CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5")))) (channel - (name some-other-collection) + (name 'some-other-collection) (url "https://example.org/second-collection.git") (branch "testing")))) @end lisp @@ -4440,20 +4530,6 @@ For the sake of reliability and maintainability, you should avoid dependencies on channels that you don't control, and you should aim to keep the number of dependencies to a minimum. -@cindex subdirectory, channels -@node Package Modules in a Sub-directory -@subsection Package Modules in a Sub-directory - -As a channel author, you may want to keep your channel modules in a -sub-directory. If your modules are in the sub-directory @file{guix}, you must -add a meta-data file @file{.guix-channel} that contains: - -@lisp -(channel - (version 0) - (directory "guix")) -@end lisp - @cindex channel authorizations @node Specifying Channel Authorizations @subsection Specifying Channel Authorizations @@ -4555,29 +4631,6 @@ authentication! Pay attention to merges in particular: merge commits are considered authentic if and only if they are signed by a key present in the @file{.guix-authorizations} file of @emph{both} branches. -@cindex primary URL, channels -@node Primary URL -@subsection Primary URL - -Channel authors can indicate the primary URL of their channel's Git -repository in the @file{.guix-channel} file, like so: - -@lisp -(channel - (version 0) - (url "https://example.org/guix.git")) -@end lisp - -This allows @command{guix pull} to determine whether it is pulling code -from a mirror of the channel; when that is the case, it warns the user -that the mirror might be stale and displays the primary URL. That way, -users cannot be tricked into fetching code from a stale mirror that does -not receive security updates. - -This feature only makes sense for authenticated repositories, such as -the official @code{guix} channel, for which @command{guix pull} ensures -the code it fetches is authentic. - @cindex news, for channels @node Writing Channel News @subsection Writing Channel News @@ -4647,47 +4700,6 @@ xgettext -o news.po -l scheme -ken etc/news.txt To sum up, yes, you could use your channel as a blog. But beware, this is @emph{not quite} what your users might expect. -@node Replicating Guix -@subsection Replicating Guix - -@cindex pinning, channels -@cindex replicating Guix -@cindex reproducibility, of Guix -The @command{guix pull --list-generations} output above shows precisely which -commits were used to build this instance of Guix. We can thus replicate it, -say, on another machine, by providing a channel specification in -@file{~/.config/guix/channels.scm} that is ``pinned'' to these commits: - -@lisp -;; Deploy specific commits of my channels of interest. -(list (channel - (name 'guix) - (url "https://git.savannah.gnu.org/git/guix.git") - (commit "6298c3ffd9654d3231a6f25390b056483e8f407c")) - (channel - (name 'my-personal-packages) - (url "https://example.org/personal-packages.git") - (commit "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb"))) -@end lisp - -The @command{guix describe --format=channels} command can even generate this -list of channels directly (@pxref{Invoking guix describe}). The resulting -file can be used with the -C options of @command{guix pull} -(@pxref{Invoking guix pull}) or @command{guix time-machine} -(@pxref{Invoking guix time-machine}). - -At this point the two machines run the @emph{exact same Guix}, with access to -the @emph{exact same packages}. The output of @command{guix build gimp} on -one machine will be exactly the same, bit for bit, as the output of the same -command on the other machine. It also means both machines have access to all -the source code of Guix and, transitively, to all the source code of every -package it defines. - -This gives you super powers, allowing you to track the provenance of binary -artifacts with very fine grain, and to reproduce software environments at -will---some sort of ``meta reproducibility'' capabilities, if you will. -@xref{Inferiors}, for another way to take advantage of these super powers. - @node Invoking guix time-machine @section Invoking @command{guix time-machine} -- 2.28.0 From debbugs-submit-bounces@debbugs.gnu.org Thu Sep 24 10:51:19 2020 Received: (at 43482) by debbugs.gnu.org; 24 Sep 2020 14:51:19 +0000 Received: from localhost ([127.0.0.1]:41222 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kLSad-0002gF-6g for submit@debbugs.gnu.org; Thu, 24 Sep 2020 10:51:19 -0400 Received: from eggs.gnu.org ([209.51.188.92]:58480) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kLSab-0002g3-4z for 43482@debbugs.gnu.org; Thu, 24 Sep 2020 10:51:17 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:34304) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kLSaV-0007Lw-QB; Thu, 24 Sep 2020 10:51:11 -0400 Received: from [2a01:e0a:1d:7270:af76:b9b:ca24:c465] (port=57410 helo=ribbon) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1kLSaV-0006oB-9M; Thu, 24 Sep 2020 10:51:11 -0400 From: =?utf-8?Q?Ludovic_Court=C3=A8s?= To: zimoun Subject: Re: [bug#43482] [PATCH 1/3] doc: Update the master menu. References: <20200918013744.3448-1-zimon.toutoune@gmail.com> <20200918014502.6081-1-zimon.toutoune@gmail.com> Date: Thu, 24 Sep 2020 16:51:09 +0200 In-Reply-To: <20200918014502.6081-1-zimon.toutoune@gmail.com> (zimoun's message of "Fri, 18 Sep 2020 03:45:00 +0200") Message-ID: <87k0wj8bz6.fsf@gnu.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 43482 Cc: 43482@debbugs.gnu.org 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 (---) Hi, zimoun skribis: > * doc/guix.texi: Update the master menu. LGTM! How come it got this much out of sync? How did you update it? IME the Emacs thingie gets confused when some but not all the top-level nodes are in separate files. Thanks, Ludo=E2=80=99. From debbugs-submit-bounces@debbugs.gnu.org Thu Sep 24 10:52:26 2020 Received: (at 43482) by debbugs.gnu.org; 24 Sep 2020 14:52:26 +0000 Received: from localhost ([127.0.0.1]:41226 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kLSbi-0002hy-G0 for submit@debbugs.gnu.org; Thu, 24 Sep 2020 10:52:26 -0400 Received: from eggs.gnu.org ([209.51.188.92]:58758) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kLSbh-0002hl-MZ for 43482@debbugs.gnu.org; Thu, 24 Sep 2020 10:52:25 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:34318) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kLSbc-0007Qp-CB; Thu, 24 Sep 2020 10:52:20 -0400 Received: from [2a01:e0a:1d:7270:af76:b9b:ca24:c465] (port=57412 helo=ribbon) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1kLSbb-0006rf-UZ; Thu, 24 Sep 2020 10:52:20 -0400 From: =?utf-8?Q?Ludovic_Court=C3=A8s?= To: zimoun Subject: Re: [bug#43482] [PATCH 2/3] doc: Add the "Channels" section menu. References: <20200918014502.6081-1-zimon.toutoune@gmail.com> <20200918014502.6081-2-zimon.toutoune@gmail.com> Date: Thu, 24 Sep 2020 16:52:18 +0200 In-Reply-To: <20200918014502.6081-2-zimon.toutoune@gmail.com> (zimoun's message of "Fri, 18 Sep 2020 03:45:01 +0200") Message-ID: <87ft778bx9.fsf@gnu.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 43482 Cc: 43482@debbugs.gnu.org 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 (---) zimoun skribis: > * doc/guix.texi (Channels): Add the section menu. [...] > +@node Channel Authentication > @subsection Channel Authentication What I had in mind was also to move everything one level higher: @section becomes @chapter, @subsection becomes @section, etc. WDYT? From debbugs-submit-bounces@debbugs.gnu.org Thu Sep 24 10:59:56 2020 Received: (at 43482) by debbugs.gnu.org; 24 Sep 2020 14:59:56 +0000 Received: from localhost ([127.0.0.1]:41235 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kLSiy-0002s1-El for submit@debbugs.gnu.org; Thu, 24 Sep 2020 10:59:56 -0400 Received: from eggs.gnu.org ([209.51.188.92]:60798) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kLSiw-0002ro-KT for 43482@debbugs.gnu.org; Thu, 24 Sep 2020 10:59:54 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:34446) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kLSir-00006Q-8e; Thu, 24 Sep 2020 10:59:49 -0400 Received: from [2a01:e0a:1d:7270:af76:b9b:ca24:c465] (port=57414 helo=ribbon) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1kLSij-0008Ap-EI; Thu, 24 Sep 2020 10:59:44 -0400 From: =?utf-8?Q?Ludovic_Court=C3=A8s?= To: zimoun Subject: Re: [bug#43482] [PATCH 3/3] doc: Reorder the "Channels" section. References: <20200918014502.6081-1-zimon.toutoune@gmail.com> <20200918014502.6081-3-zimon.toutoune@gmail.com> Date: Thu, 24 Sep 2020 16:59:39 +0200 In-Reply-To: <20200918014502.6081-3-zimon.toutoune@gmail.com> (zimoun's message of "Fri, 18 Sep 2020 03:45:02 +0200") Message-ID: <874knn8bl0.fsf@gnu.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 43482 Cc: 43482@debbugs.gnu.org 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 (---) zimoun skribis: > * doc/guix.texi (Channels): Reorder the section. > Minor tweaks to keep uniformity. > Update the master menu. It would be nice if you could better describe what=E2=80=99s moved where si= nce looking at the diff doesn=E2=80=99t help understand it. > +@node Writing custom channels > +@subsection Writing custom channels Should be =E2=80=9CWriting Custom Channels=E2=80=9D. Maybe =E2=80=9CCreating a Channel=E2=80=9D is more to the point actually? > 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 > @@ -4398,6 +4470,24 @@ module, then the module will be available under th= e 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}). >=20=20 > +Last, as a channel author, you may want to run an authenticated channel > +(@pxref{Channel Authentication}), then @pxref{Specifying Channel > +Authorizations} for details. Maybe something like: 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. (Note: @pxref cannot be used in the middle of a sentence like you did above. I always end up re-reading the Texinfo manual to find which cross-reference command to use in which context=E2=80=A6) Could you send updated patches? Thanks! Ludo=E2=80=99. From debbugs-submit-bounces@debbugs.gnu.org Thu Sep 24 11:05:57 2020 Received: (at 43482) by debbugs.gnu.org; 24 Sep 2020 15:05:57 +0000 Received: from localhost ([127.0.0.1]:41249 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kLSon-00059a-5J for submit@debbugs.gnu.org; Thu, 24 Sep 2020 11:05:57 -0400 Received: from mail-qv1-f65.google.com ([209.85.219.65]:33543) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kLSok-00059K-BN for 43482@debbugs.gnu.org; Thu, 24 Sep 2020 11:05:55 -0400 Received: by mail-qv1-f65.google.com with SMTP id cy2so2069404qvb.0 for <43482@debbugs.gnu.org>; Thu, 24 Sep 2020 08:05:54 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc:content-transfer-encoding; bh=vEcLbMJvQ8Jr6piG1s9VPxgWZeig1aWZJ+sTHCTj6UU=; b=IxVAM/nqF1JlGbJcy9xNs6BGg0EvYEFPtSMiI4afsXWiJA6ZAId4FEYfXez5x3kF/M 9nDL8DlUBcaWzFTYEQmcUFfUgT2oVO7LvTANDF2eGSPEXnZcXnTpiLMDsSQhFdKMZTPK OnZ491po9hYba2ppuy7zeLDG9LHLSw4RBsMDFpdG6ZCg/0Hc75SaaLgMjbc5Fd6zk7fQ ZNx9I2NUkBdbLW6rNnHC+DFYiMgrwQMNv3enuluwsyWN/lLxYdeWmnW1PyXm3yT5at03 TdkiBzFnBRiSBhPgo/zLQIVdN1NrNWt8ci8HpUBiQs1IUgeZvQkgUSECbOhU54L1i1HU XjJg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc:content-transfer-encoding; bh=vEcLbMJvQ8Jr6piG1s9VPxgWZeig1aWZJ+sTHCTj6UU=; b=SKDjMpHmas51mioREIMN6yG7yM4CFyrClMe+2sCzSvpFaJAc84t2i5TyqWHlJP+l1W nyZl05NNbde+G/kPpMii6xX7NKr3IVkaURD55g/IL/DLUhI9TF7UyuOOj3essDcEa2UI 5etBK2jm3LbciJaEXKy5Gh0jR/ggpHFIl3sdFJ6P1cnTGVdQTQbMidAvQHbOQ6wGycnu O50SvDMdFDYXqQv7jOEgvT6a1SeqyPNRasQCxPHDT4nom7SR1aI9KGQm/R+zSTBwMFWm raqCWsNc4tm2kVlOLE39Cgrf598muNeAdnsbTCunUOVYVISZ1eHMVg5VYH5oA1f5wsHO 6Ytw== X-Gm-Message-State: AOAM530CksHcnpcROCLPqWdk8o3vsWk+3wsJxaogEjw3gmX/eQNNSqD1 Hkxagh7ELVofbVCS7OY5OEvUVOUmGpZ1eLHEq5Y= X-Google-Smtp-Source: ABdhPJzfnFec+NKgin1ALuwmBLCtKxi4Lk55cqTAaZneVFxQWpYuhCkNnSgrV79lmb92TJHRDY5mlO+czSruWgR9oZs= X-Received: by 2002:a05:6214:1767:: with SMTP id et7mr5552398qvb.43.1600959948792; Thu, 24 Sep 2020 08:05:48 -0700 (PDT) MIME-Version: 1.0 References: <20200918014502.6081-1-zimon.toutoune@gmail.com> <20200918014502.6081-2-zimon.toutoune@gmail.com> <87ft778bx9.fsf@gnu.org> In-Reply-To: <87ft778bx9.fsf@gnu.org> From: zimoun Date: Thu, 24 Sep 2020 17:05:24 +0200 Message-ID: Subject: Re: [bug#43482] [PATCH 2/3] doc: Add the "Channels" section menu. To: =?UTF-8?Q?Ludovic_Court=C3=A8s?= Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 43482 Cc: 43482@debbugs.gnu.org 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: -1.0 (-) On Thu, 24 Sep 2020 at 16:52, Ludovic Court=C3=A8s wrote: > > +@node Channel Authentication > > @subsection Channel Authentication > > What I had in mind was also to move everything one level higher: > @section becomes @chapter, @subsection becomes @section, etc. I had that in mind too. After I did the change (subsection->section, etc.), then I was not convinced, so I just added the '@node'. Concretely, I do not have a strong opinion. Let's rebase with this big move. :-) However, moving "guix pull" and "guix time-machine" to this section does not appear to me "logical" and should stay under Package management. Especially with the "one level higher" move. WDYT? Cheers, simon From debbugs-submit-bounces@debbugs.gnu.org Thu Sep 24 11:13:23 2020 Received: (at 43482) by debbugs.gnu.org; 24 Sep 2020 15:13:23 +0000 Received: from localhost ([127.0.0.1]:41266 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kLSvy-0005Kv-RQ for submit@debbugs.gnu.org; Thu, 24 Sep 2020 11:13:23 -0400 Received: from mail-qk1-f195.google.com ([209.85.222.195]:37818) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kLSvv-0005Kh-Jf for 43482@debbugs.gnu.org; Thu, 24 Sep 2020 11:13:21 -0400 Received: by mail-qk1-f195.google.com with SMTP id 16so3581537qkf.4 for <43482@debbugs.gnu.org>; Thu, 24 Sep 2020 08:13:19 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc:content-transfer-encoding; bh=1IIr1FT71wg2RWDyEnp8O9zBr4ZdmvUj78aMamXyT90=; b=LnVmdkhzqIQn8qLDYRnO1DKmiMHEvDd4vpZQVpRjIr3LEbY6X67pmqwlPMUwjvPgN9 PDmK7XioyZ035lxlhEwH/iffEFziovFwFore+6q2cEU2TtVyWy2PWEgoXF2k3taWFBk2 aH3f7Kc9tbNC/cWqesOq05GmV3cth96h7JsUPIRE/r7Ys7l7mq6jP9zY/cnq6D7gPbcl KjMrBn8HKH+E8UAdZCZtg61XaMNmnq2wmt1KGO2iBBKb6X3cgO9v7RNPBv7gQ7RX28wL 9ld/y0a5I5/HIuFPjlKvQNQl5lOHYwtghUW8w8zzRZcm4Ku1ueS8wElbJE6/poymBznL DJag== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc:content-transfer-encoding; bh=1IIr1FT71wg2RWDyEnp8O9zBr4ZdmvUj78aMamXyT90=; b=h3CXM7S8+/3Rv4o6mxpOGu0EA40GEswHXchd+YzJZmaZqAXaip4RSd/dKuzTOaTci1 2Thc0d/mC8FNh6B1zE72qWKxGNDNhpveOG88E+QGscvD1wiAxjGFFMmotWSXWhRcdrKQ LNAXIcMnqUM9IFtyz9vjn5mR4H3ZErEja6TgIpqCELEyXmDarjUhhfpA2JGy1aFfXboS RpgULRStAUg6XIRM+12ehhlQah/U/fRVmrErUig+7jV2wcqzC5weuh9f1rh0FUO6VMeW 73of9sYEFE2ZRtIXT4ZVWfVYoCPooC+nj0ElwX4/tRcrOsvz2PiASrtnHKut9d+u6T8t 6KAQ== X-Gm-Message-State: AOAM532vaSokkLB+zxkkdIGGbBSSZVIb2zz19gDOja8q2MAySFTxq1j4 4OMRfSo5dyN4hbRP1QZSfZVY+NTReRTbVgoDmbo= X-Google-Smtp-Source: ABdhPJwBpTPdq2PzeeaPA3VQhbJTm8cshBNAaNc7MU94BloMuhTI29U9FYtN2PMHq3FU+k2OlH/nl1n/7LWipOqi1Hk= X-Received: by 2002:a05:620a:a09:: with SMTP id i9mr89557qka.201.1600960393852; Thu, 24 Sep 2020 08:13:13 -0700 (PDT) MIME-Version: 1.0 References: <20200918014502.6081-1-zimon.toutoune@gmail.com> <20200918014502.6081-3-zimon.toutoune@gmail.com> <874knn8bl0.fsf@gnu.org> In-Reply-To: <874knn8bl0.fsf@gnu.org> From: zimoun Date: Thu, 24 Sep 2020 17:13:02 +0200 Message-ID: Subject: Re: [bug#43482] [PATCH 3/3] doc: Reorder the "Channels" section. To: =?UTF-8?Q?Ludovic_Court=C3=A8s?= Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 43482 Cc: 43482@debbugs.gnu.org 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: -1.0 (-) Hi, Thank you for the review. On Thu, 24 Sep 2020 at 16:59, Ludovic Court=C3=A8s wrote: > > * doc/guix.texi (Channels): Reorder the section. > > Minor tweaks to keep uniformity. > > Update the master menu. > > It would be nice if you could better describe what=E2=80=99s moved where = since > looking at the diff doesn=E2=80=99t help understand it. I will try to do my best. :-) > > +@node Writing custom channels > > +@subsection Writing custom channels > > Should be =E2=80=9CWriting Custom Channels=E2=80=9D. > > Maybe =E2=80=9CCreating a Channel=E2=80=9D is more to the point actually? Ok. > > +Last, as a channel author, you may want to run an authenticated channe= l > > +(@pxref{Channel Authentication}), then @pxref{Specifying Channel > > +Authorizations} for details. > > Maybe something like: > > 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. Ok. > (Note: @pxref cannot be used in the middle of a sentence like you did > above. I always end up re-reading the Texinfo manual to find which > cross-reference command to use in which context=E2=80=A6) Thanks for the explanations. > Could you send updated patches? Ok. Cheers, simon From debbugs-submit-bounces@debbugs.gnu.org Thu Sep 24 11:29:18 2020 Received: (at 43482) by debbugs.gnu.org; 24 Sep 2020 15:29:18 +0000 Received: from localhost ([127.0.0.1]:41327 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kLTBO-0005md-Hn for submit@debbugs.gnu.org; Thu, 24 Sep 2020 11:29:18 -0400 Received: from mail-qt1-f194.google.com ([209.85.160.194]:36686) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kLTBN-0005mP-29 for 43482@debbugs.gnu.org; Thu, 24 Sep 2020 11:29:17 -0400 Received: by mail-qt1-f194.google.com with SMTP id n10so3282246qtv.3 for <43482@debbugs.gnu.org>; Thu, 24 Sep 2020 08:29:17 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc:content-transfer-encoding; bh=mqIb4qhqYc/SpszfPbS9+hBddWVkaOHDrwtgWW5eWvs=; b=LAWB1E0JkqGcEbadj4AFEn1PrE72HuPDwyFUXkPTSNzRA8F8XpDm6YvF5Gl+US90DX 2zpG6cVNDGTO6Ji3Vhhgvd2+7EGvX6Y2LsYRetevDiwijWnrnWdMlqp96pXfiYX9I6af +hCAUhqWST3U5IJFGKksvGCS+xUanqmSszLPNRos7FRn6Eia0JKL4ZufW//Eu1HvZmE5 lLTv5P9uJzASolOk2dNPLjxlEIizRebsK3MlxFcV7eenEJrEdFEz39HG/JlJF30flBPg 62uBknS9yE/jQL7zeqY6HvONqitk481ligAJcGziVzSAiDWH94jXm/vThE6cQbvZjUtU BjUQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc:content-transfer-encoding; bh=mqIb4qhqYc/SpszfPbS9+hBddWVkaOHDrwtgWW5eWvs=; b=EsOaK60d+rhOia4Tsch/9+nP/VhGGcr8Ah8hFL23cpke+puunAEMfqpEv8L2X48bDn SrrpOSe8915NBEtCQczSjfNVfwNisXTq0qRAzUp+jAtLLlUa0V2li5I4wdAd23PaUL2T NcbhPjPkxt7bI03iuWBP5vffBSMm3xX6U8KXpKS7TFC0ngDK01zHa1BcBeBSCimXqdG/ Mlc01JSIPZMPxgVKkLOMLstlKrT4M3HHUQTt5GBYzGraSkTrgOjeytiKGfkItins7kHb +SqFA45G5iXnXT3XWdDs50HVo0MPVZSoa6smKZvA3E73buXYLbKwDnfPw+Frt97RvutG Apjg== X-Gm-Message-State: AOAM533OewAiVUQ0Z4rBmo9lgjmXs49ompWZuy1tusnzRaSAn+1NwIJx nsIIb0r5/0N6nYnlPd+N/brsnCyVCyK90GEIWJM= X-Google-Smtp-Source: ABdhPJwiAIfQJ6lCU92u/MR/mE5/le8dWKsreTLhJ6l+hIE3NDfvONHicg6pdTwsajR3C9yxB39V0G4WOLg1En+zTNw= X-Received: by 2002:ac8:fec:: with SMTP id f41mr120918qtk.186.1600961351442; Thu, 24 Sep 2020 08:29:11 -0700 (PDT) MIME-Version: 1.0 References: <20200918013744.3448-1-zimon.toutoune@gmail.com> <20200918014502.6081-1-zimon.toutoune@gmail.com> <87k0wj8bz6.fsf@gnu.org> In-Reply-To: <87k0wj8bz6.fsf@gnu.org> From: zimoun Date: Thu, 24 Sep 2020 17:28:57 +0200 Message-ID: Subject: Re: [bug#43482] [PATCH 1/3] doc: Update the master menu. To: =?UTF-8?Q?Ludovic_Court=C3=A8s?= Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 43482 Cc: 43482@debbugs.gnu.org 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: -1.0 (-) On Thu, 24 Sep 2020 at 16:51, Ludovic Court=C3=A8s wrote: > How come it got this much out of sync? How did you update it? IME the > Emacs thingie gets confused when some but not all the top-level nodes > are in separate files. I do not remember exactly how. Well, I have used the 'menu-bar' since I never remember the TexInfo keys. Then, I tried 'texinfo-master-menu' and 'texinfo-every-node-update' and 'texinfo-all-menus-update' and manually checked with Magit the diff. For example, this commit b460ba7992 adds one node but does not update the master menu; the TeXInfo workflow is a bit tedious and the mistake always happens somehow. Cheers, simon From debbugs-submit-bounces@debbugs.gnu.org Fri Sep 25 05:20:26 2020 Received: (at 43482) by debbugs.gnu.org; 25 Sep 2020 09:20:26 +0000 Received: from localhost ([127.0.0.1]:42636 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kLjty-0006Sy-5j for submit@debbugs.gnu.org; Fri, 25 Sep 2020 05:20:26 -0400 Received: from eggs.gnu.org ([209.51.188.92]:51548) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kLjtv-0006Sl-PM for 43482@debbugs.gnu.org; Fri, 25 Sep 2020 05:20:24 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:51457) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kLjtq-0000JO-Hg; Fri, 25 Sep 2020 05:20:18 -0400 Received: from [2a01:e0a:1d:7270:af76:b9b:ca24:c465] (port=60702 helo=ribbon) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1kLjtp-0007N3-QM; Fri, 25 Sep 2020 05:20:18 -0400 From: =?utf-8?Q?Ludovic_Court=C3=A8s?= To: zimoun Subject: Re: [bug#43482] [PATCH 2/3] doc: Add the "Channels" section menu. References: <20200918014502.6081-1-zimon.toutoune@gmail.com> <20200918014502.6081-2-zimon.toutoune@gmail.com> <87ft778bx9.fsf@gnu.org> X-URL: http://www.fdn.fr/~lcourtes/ X-Revolutionary-Date: 4 =?utf-8?Q?Vend=C3=A9miaire?= an 229 de la =?utf-8?Q?R=C3=A9volution?= X-PGP-Key-ID: 0x090B11993D9AEBB5 X-PGP-Key: http://www.fdn.fr/~lcourtes/ludovic.asc X-PGP-Fingerprint: 3CE4 6455 8A84 FDC6 9DB4 0CFB 090B 1199 3D9A EBB5 X-OS: x86_64-pc-linux-gnu Date: Fri, 25 Sep 2020 11:20:15 +0200 In-Reply-To: (zimoun's message of "Thu, 24 Sep 2020 17:05:24 +0200") Message-ID: <871riq43hs.fsf@gnu.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 43482 Cc: 43482@debbugs.gnu.org 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 (---) Hi, zimoun skribis: > On Thu, 24 Sep 2020 at 16:52, Ludovic Court=C3=A8s wrote: > >> > +@node Channel Authentication >> > @subsection Channel Authentication >> >> What I had in mind was also to move everything one level higher: >> @section becomes @chapter, @subsection becomes @section, etc. > > I had that in mind too. After I did the change (subsection->section, > etc.), then I was not convinced, so I just added the '@node'. I think moving one level higher can help. More generally, I think it=E2=80= =99s a bad sign when a manual as few chapters and many subsubsubsections; it makes it harder to see what the main topics are. It=E2=80=99s a problem we= have here (the Guile manual is worse in that respect :-)). > However, moving "guix pull" and "guix time-machine" to this section > does not appear to me "logical" and should stay under Package > management. Especially with the "one level higher" move. WDYT? We=E2=80=99ll see that later. :-) Thanks, Ludo=E2=80=99. From debbugs-submit-bounces@debbugs.gnu.org Fri Sep 25 16:01:16 2020 Received: (at 43482) by debbugs.gnu.org; 25 Sep 2020 20:01:16 +0000 Received: from localhost ([127.0.0.1]:45400 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kLtu8-0008NH-3H for submit@debbugs.gnu.org; Fri, 25 Sep 2020 16:01:16 -0400 Received: from mail-wm1-f45.google.com ([209.85.128.45]:55555) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kLtu5-0008N0-V6 for 43482@debbugs.gnu.org; Fri, 25 Sep 2020 16:01:14 -0400 Received: by mail-wm1-f45.google.com with SMTP id d4so238598wmd.5 for <43482@debbugs.gnu.org>; Fri, 25 Sep 2020 13:01:13 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; bh=F0j3Rzs4NN+0cszqe0lPHZm589eJtgkFz6qXSBODV2k=; b=Zx7qzrNXGneZY9P9YZTG8S+W33sRjQ7CpXS1ps7VvbtBAPn1h+MIQYW4viugo1InNp 7Jmhj+7zM/MHxeLaZ8AGoXeerEb4RSzHZZTEEVE6cz2aEsDKblBbThryyCz+QTYR9X/l JZtT7Q58+uhIPnB4WDoYgLnaXGVKjsK7DkkHbgHpyJQnMN8itnNlvBzbJdlzIJeNurnx cJRkN1hgjhGxZxbnUZJd0nxLChL6OJEfuR8wcmXl8rBicU1OA16o3L4CmMFFIE5d/Sz8 FkIgpRJEHs3MrNXhPOYZYviAP6q34l5Iz1d3Qc3OfpbTIRVnbhQxPCR5hb/U+O7ue/dT 9Q7w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; bh=F0j3Rzs4NN+0cszqe0lPHZm589eJtgkFz6qXSBODV2k=; b=NjJIB9+9XBOAAnO8FL18v7UIqBqzsAUmsYlrRSKZPdpzZUFeuPJfeR5E/sbpMnkFXp dCfdmgfOfK4/6IRJtBR6OvtxNyY+aiac9ak9d6vCdI42xVcgo6q1H7heQbo8CWmWAUTw KNVly/HtIzmUCMPFGkIjmC2Qxd+mCnkgVh/KKZpaNT9a/QBsBNd3S4tAHlCJcoidy7UC r+RLmwHsSlpFNH0YWW6Wt2MPIGwWgZeUy2oukTIVn71qEDyxLTfGq4a6oFi+jmUhtHmL adIIg/i6kld1spQlISGwpSP94gtQg9OQYieDtUcoklu8+/U+xESer8liyYbPeScqdZN+ IT8g== X-Gm-Message-State: AOAM533NW+muoPYeRewMuoQMfQ6cRER4KvhKXTbd+AdTwOybXAL1gaCv JUgPlNNHrFEmXqNA/naVBUvMmpNJOX5sTw== X-Google-Smtp-Source: ABdhPJwsn4/ZwsftJ0dxjQ+zhmmTrybv2pVWbuKuYsr1pEqVXBIAo5lQg05dL7TaqRez8MHMMR10XA== X-Received: by 2002:a1c:81c9:: with SMTP id c192mr242402wmd.2.1601064067817; Fri, 25 Sep 2020 13:01:07 -0700 (PDT) Received: from pfiuh02.univ-paris-diderot.fr ([193.48.40.241]) by smtp.gmail.com with ESMTPSA id 76sm99652wma.42.2020.09.25.13.01.06 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 25 Sep 2020 13:01:07 -0700 (PDT) From: zimoun To: 43482@debbugs.gnu.org Subject: [PATCH v2 1/2] doc: Update the master menu. Date: Fri, 25 Sep 2020 22:00:54 +0200 Message-Id: <20200925200055.8908-1-zimon.toutoune@gmail.com> X-Mailer: git-send-email 2.28.0 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 43482 Cc: ludo@gnu.org, zimoun 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: -1.0 (-) * doc/guix.texi: Update the master menu. --- doc/guix.texi | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/doc/guix.texi b/doc/guix.texi index a66ab82b31..bc72373d80 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -179,6 +179,7 @@ Installation * Setting Up the Daemon:: Preparing the build daemon's environment. * Invoking guix-daemon:: Running the build daemon. * Application Setup:: Application-specific setup. +* Upgrading Guix:: Upgrading Guix and its build daemon. Setting Up the Daemon @@ -198,8 +199,6 @@ System Installation * Installing Guix in a VM:: Guix System playground. * Building the Installation Image:: How this comes to be. -Getting Started - Manual Installation * Keyboard Layout and Networking and Partitioning:: Initial setup. @@ -233,6 +232,7 @@ Development * Invoking guix environment:: Setting up development environments. * Invoking guix pack:: Creating software bundles. * The GCC toolchain:: Working with languages supported by GCC. +* Invoking guix git authenticate:: Authenticating Git repositories. Programming Interface @@ -301,6 +301,7 @@ Services * Scheduled Job Execution:: The mcron service. * Log Rotation:: The rottlog service. * Networking Services:: Network setup, SSH daemon, etc. +* Unattended Upgrades:: Automated system upgrades. * X Window:: Graphical display. * Printing Services:: Local and remote printer support. * Desktop Services:: D-Bus and desktop services. @@ -311,6 +312,7 @@ Services * Telephony Services:: Telephony services. * Monitoring Services:: Monitoring services. * Kerberos Services:: Kerberos services. +* LDAP Services:: LDAP services. * Web Services:: Web servers. * Certificate Services:: TLS certificates via Let's Encrypt. * DNS Services:: DNS daemons. @@ -325,7 +327,7 @@ Services * PAM Mount Service:: Service to mount volumes when logging in. * Guix Services:: Services relating specifically to Guix. * Linux Services:: Services tied to the Linux kernel. -* Hurd Services:: Services specific to a Hurd System. +* Hurd Services:: Services specific for a Hurd System. * Miscellaneous Services:: Other services. Defining Services @@ -335,6 +337,11 @@ Defining Services * Service Reference:: API reference. * Shepherd Services:: A particular type of service. +Bootstrapping + +* Reduced Binary Seed Bootstrap:: A Bootstrap worthy of GNU. +* Preparing to Use the Bootstrap Binaries:: Building that what matters most. + @end detailmenu @end menu base-commit: 3e5ed76df5ba12be22c6360abd83f328c3613ae0 -- 2.28.0 From debbugs-submit-bounces@debbugs.gnu.org Fri Sep 25 16:01:27 2020 Received: (at 43482) by debbugs.gnu.org; 25 Sep 2020 20:01:27 +0000 Received: from localhost ([127.0.0.1]:45403 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kLtuG-0008Nb-CD for submit@debbugs.gnu.org; Fri, 25 Sep 2020 16:01:27 -0400 Received: from mail-wm1-f48.google.com ([209.85.128.48]:40599) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kLtuB-0008N9-Iz for 43482@debbugs.gnu.org; Fri, 25 Sep 2020 16:01:23 -0400 Received: by mail-wm1-f48.google.com with SMTP id k18so277886wmj.5 for <43482@debbugs.gnu.org>; Fri, 25 Sep 2020 13:01:19 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=RrjMBZlD5jPiBnSf5m7+qtjdzL7crKMXiAbfq1U32Sk=; b=uV45qR07lzPQNizwGDVsDbR4Lz17+tly5Y2hkiYrwL6BYx8DJJYmOXIZjAdskS1jAj yp7J3K/s55WxtY1V1azUWmaMdtTVkIJTKt3+KdugoKF00U1yZTjVZEJuikNm7sGA415O ey1xBMvtRxGCdMHUfHKOWM767UJ7KHf8/oFAGZ/alluM5OLcQBANDFjsTFoVk3yr8iGT Z5WFE9KTeTHe+X4a/sXpk4bU6RHpizXzK0sdr7DXJUHh0hYq95qPuMKnDahPGsRLfIw9 zYx1n87PLFpxFsVDqwZrNOL2kYfWk8VkRjJ2UKDjuxb0NbMDgWuIarKnHq3KLKuQikv5 uXRA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=RrjMBZlD5jPiBnSf5m7+qtjdzL7crKMXiAbfq1U32Sk=; b=FpajVEgcY8r8+T8fmEvt8HJVQ6tFrjwXdwWcp/ijYvoCpbnxL6choHt6mHZEXuP/23 PyfQlihaJeTHHrHuUtyhXAt0x6LAsooJ/csOqHPZD+ywLeqKdoP1SgbMNlyTbOidNQ2V 9+00OQTVJkNiVjUEHH9iJg2JWjWKhXP7N+xeqfj3H9+SH/fFi6BQMAAdrjq26YmxB2d1 xAmI1aKm5CyHrwiUsQM0OOOSaj3cx6ZjK5F/vJAlizyN3nnlWUM20uELtBvoWX5p6wCV LPioxntXQ5UPMDTKojupaSB9fiJbT8aoMTXYVxIkMOzg8ebt9dQsmak+VwS12gNo5VpJ nsvQ== X-Gm-Message-State: AOAM533wwbLgxds84d3v9D0LDPQnjYDU63WG0OsenKdIvKJbxXrP0zB+ OKKBImrfoa0LnpVft/TaLyNHHr6lups95g== X-Google-Smtp-Source: ABdhPJx0xEXvE/fT42MrObB0riHA0rKh3CmObZdz5SSK4lfwr36OXAyruYVJqzb7Sz+qUd5N/EgA2A== X-Received: by 2002:a1c:e1d6:: with SMTP id y205mr239619wmg.92.1601064069542; Fri, 25 Sep 2020 13:01:09 -0700 (PDT) Received: from pfiuh02.univ-paris-diderot.fr ([193.48.40.241]) by smtp.gmail.com with ESMTPSA id 76sm99652wma.42.2020.09.25.13.01.07 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 25 Sep 2020 13:01:08 -0700 (PDT) From: zimoun To: 43482@debbugs.gnu.org Subject: [PATCH v2 2/2] doc: Promote "Channels" as chapter and reorder. Date: Fri, 25 Sep 2020 22:00:55 +0200 Message-Id: <20200925200055.8908-2-zimon.toutoune@gmail.com> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20200925200055.8908-1-zimon.toutoune@gmail.com> References: <20200925200055.8908-1-zimon.toutoune@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 43482 Cc: ludo@gnu.org, zimoun 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: -1.0 (-) The sectioning becomes: 1. Specifying Additional Channels (was 3.) 2. Using a Custom Guix Channel (was 2.) 3. Replicating Guix (was 9.) 4. Channel Authentication (was 1.) 5. Primary URL (was 7.) 6. Creating a Channel (reworded) 7. Package Modules in a Sub-directory (was 5.) 8. Declaring Channel Dependencies (was 4.) 9. Specifying Channel Authorizations (was 6.) 10. Writing Channel News (was 8.) * doc/guix.texi (Channels): Move section to chapter. Reorder the chapter. Minor tweaks to keep uniformity. Update the master menu. --- doc/guix.texi | 1587 +++++++++++++++++++++++++------------------------ 1 file changed, 817 insertions(+), 770 deletions(-) diff --git a/doc/guix.texi b/doc/guix.texi index bc72373d80..ef10785316 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -147,6 +147,7 @@ Project}. * System Installation:: Installing the whole operating system. * Getting Started:: Your first steps. * Package Management:: Package installation, upgrade, etc. +* Channels:: Customizing the package collection. * Development:: Guix-aided software development. * Programming Interface:: Using Guix in Scheme. * Utilities:: Package management commands. @@ -212,7 +213,6 @@ Package Management * Packages with Multiple Outputs:: Single source package, multiple outputs. * Invoking guix gc:: Running the garbage collector. * Invoking guix pull:: Fetching the latest Guix and distribution. -* Channels:: Customizing the package collection. * Invoking guix time-machine:: Running an older revision of Guix. * Inferiors:: Interacting with another revision of Guix. * Invoking guix describe:: Display information about your Guix revision. @@ -227,6 +227,19 @@ Substitutes * Substitution Failure:: What happens when substitution fails. * On Trusting Binaries:: How can you trust that binary blob? +Channels + +* Specifying Additional Channels:: Extending the package collection. +* Using a Custom Guix Channel:: Using a customized Guix. +* Replicating Guix:: Running the @emph{exact same} Guix. +* Channel Authentication:: How Guix verifies what it fetches. +* Primary URL:: Distinguishing mirror to original. +* Creating a Channel:: How to write your custom channel. +* Package Modules in a Sub-directory:: Specifying the channel's package modules location. +* Declaring Channel Dependencies:: How to depend on other channels. +* Specifying Channel Authorizations:: Defining channel authors authorizations. +* Writing Channel News:: Communicating information to channel's users. + Development * Invoking guix environment:: Setting up development environments. @@ -2812,7 +2825,6 @@ guix install emacs-guix * Packages with Multiple Outputs:: Single source package, multiple outputs. * Invoking guix gc:: Running the garbage collector. * Invoking guix pull:: Fetching the latest Guix and distribution. -* Channels:: Customizing the package collection. * Invoking guix time-machine:: Running an older revision of Guix. * Inferiors:: Interacting with another revision of Guix. * Invoking guix describe:: Display information about your Guix revision. @@ -4189,937 +4201,972 @@ information. In addition, @command{guix pull} supports all the common build options (@pxref{Common Build Options}). -@node Channels -@section Channels - -@cindex channels -@cindex @file{channels.scm}, configuration file -@cindex configuration file for channels -@cindex @command{guix pull}, configuration file -@cindex configuration of @command{guix pull} -Guix and its package collection are updated by running @command{guix pull} -(@pxref{Invoking guix pull}). By default @command{guix pull} downloads and -deploys Guix itself from the official GNU@tie{}Guix repository. This can be -customized by defining @dfn{channels} in the -@file{~/.config/guix/channels.scm} file. A channel specifies a URL and branch -of a Git repository to be deployed, and @command{guix pull} can be instructed -to pull from one or more channels. In other words, channels can be used -to @emph{customize} and to @emph{extend} Guix, as we will see below. -Before that, some security considerations. +@node Invoking guix time-machine +@section Invoking @command{guix time-machine} -@subsection Channel Authentication +@cindex @command{guix time-machine} +@cindex pinning, channels +@cindex replicating Guix +@cindex reproducibility, of Guix -@anchor{channel-authentication} -@cindex authentication, of channel code -The @command{guix pull} and @command{guix time-machine} commands -@dfn{authenticate} the code retrieved from channels: they make sure each -commit that is fetched is signed by an authorized developer. The goal -is to protect from unauthorized modifications to the channel that would -lead users to run malicious code. +The @command{guix time-machine} command provides access to other +revisions of Guix, for example to install older versions of packages, +or to reproduce a computation in an identical environment. The revision +of Guix to be used is defined by a commit or by a channel +description file created by @command{guix describe} +(@pxref{Invoking guix describe}). -As a user, you must provide a @dfn{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: +The general syntax is: -@lisp -(channel - (name 'my-channel) - (url "https://example.org/my-channel.git") - (introduction - (make-channel-introduction - "6f0d8cc0d88abb59c324b2990bfee2876016bb86" - (openpgp-fingerprint - "CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5")))) -@end lisp +@example +guix time-machine @var{options}@dots{} -- @var{command} @var {arg}@dots{} +@end example -The specification above shows the name and URL of the channel. The call -to @code{make-channel-introduction} above specifies that authentication -of this channel starts at commit @code{6f0d8cc@dots{}}, which is signed -by the OpenPGP key with fingerprint @code{CABB A931@dots{}}. +where @var{command} and @var{arg}@dots{} are passed unmodified to the +@command{guix} command of the specified revision. The @var{options} that define +this revision are the same as for @command{guix pull} (@pxref{Invoking guix pull}): -For the main channel, called @code{guix}, you automatically get that -information from your Guix installation. For other channels, include -the channel introduction provided by the channel authors in your -@file{channels.scm} file. Make sure you retrieve the channel -introduction from a trusted source since that is the root of your trust. +@table @code +@item --url=@var{url} +@itemx --commit=@var{commit} +@itemx --branch=@var{branch} +Use the @code{guix} channel from the specified @var{url}, at the +given @var{commit} (a valid Git commit ID represented as a hexadecimal +string), or @var{branch}. -If you're curious about the authentication mechanics, read on! +@item --channels=@var{file} +@itemx -C @var{file} +Read the list of channels from @var{file}. @var{file} must contain +Scheme code that evaluates to a list of channel objects. +@xref{Channels} for more information. +@end table -@subsection Using a Custom Guix Channel +As for @command{guix pull}, the absence of any options means that the +the latest commit on the master branch will be used. The command -The channel called @code{guix} specifies where Guix itself---its command-line -tools as well as its package collection---should be downloaded. For instance, -suppose you want to update from your own copy of the Guix repository at -@code{example.org}, and specifically the @code{super-hacks} branch, you can -write in @code{~/.config/guix/channels.scm} this specification: +@example +guix time-machine -- build hello +@end example -@lisp -;; Tell 'guix pull' to use my own repo. -(list (channel - (name 'guix) - (url "https://example.org/my-guix.git") - (branch "super-hacks"))) -@end lisp +will thus build the package @code{hello} as defined in the master branch, +which is in general a newer revision of Guix than you have installed. +Time travel works in both directions! -@noindent -From there on, @command{guix pull} will fetch code from the @code{super-hacks} -branch of the repository at @code{example.org}. +Note that @command{guix time-machine} can trigger builds of channels and +their dependencies, and these are controlled by the standard build +options (@pxref{Common Build Options}). -@subsection Specifying Additional Channels +@node Inferiors +@section Inferiors -@cindex extending the package collection (channels) -@cindex personal packages (channels) -@cindex channels, for personal packages -You can also specify @emph{additional channels} to pull from. 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? +@c TODO: Remove this once we're more confident about API stability. +@quotation Note +The functionality described here is a ``technology preview'' as of version +@value{VERSION}. As such, the interface is subject to change. +@end quotation -@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: +@cindex inferiors +@cindex composition of Guix revisions +Sometimes you might need to mix packages from the revision of Guix you're +currently running with packages available in a different revision of Guix. +Guix @dfn{inferiors} allow you to achieve that by composing different Guix +revisions in arbitrary ways. -@itemize -@item -Before publishing a channel, please consider contributing your package -definitions to Guix proper (@pxref{Contributing}). Guix as a project is open -to free software of all sorts, and packages in Guix proper are readily -available to all Guix users and benefit from the project's quality assurance -process. +@cindex inferior packages +Technically, an ``inferior'' is essentially a separate Guix process connected +to your main Guix process through a REPL (@pxref{Invoking guix repl}). The +@code{(guix inferior)} module allows you to create inferiors and to +communicate with them. It also provides a high-level interface to browse and +manipulate the packages that an inferior provides---@dfn{inferior packages}. -@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. +When combined with channels (@pxref{Channels}), inferiors provide a simple way +to interact with a separate revision of Guix. For example, let's assume you +want to install in your profile the current @code{guile} package, along with +the @code{guile-json} as it existed in an older revision of Guix---perhaps +because the newer @code{guile-json} has an incompatible API and you want to +run your code against the old API@. To do that, you could write a manifest for +use by @code{guix package --manifest} (@pxref{Invoking guix package}); in that +manifest, you would create an inferior for that old Guix revision you care +about, and you would look up the @code{guile-json} package in the inferior: -@item -Corollary: if you're using an external channel and that channel breaks, please -@emph{report the issue to the channel authors}, not to the Guix project. -@end itemize +@lisp +(use-modules (guix inferior) (guix channels) + (srfi srfi-1)) ;for 'first' -You've been warned! Having said this, we believe external channels are a -practical way to exert your freedom to augment Guix' package collection and to -share your improvements, which are basic tenets of -@uref{https://www.gnu.org/philosophy/free-sw.html, free software}. Please -email us at @email{guix-devel@@gnu.org} if you'd like to discuss this. -@end quotation +(define channels + ;; This is the old revision from which we want to + ;; extract guile-json. + (list (channel + (name 'guix) + (url "https://git.savannah.gnu.org/git/guix.git") + (commit + "65956ad3526ba09e1f7a40722c96c6ef7c0936fe")))) -To use a channel, write @code{~/.config/guix/channels.scm} to instruct -@command{guix pull} to pull from it @emph{in addition} to the default Guix -channel(s): +(define inferior + ;; An inferior representing the above revision. + (inferior-for-channels channels)) -@vindex %default-channels -@lisp -;; Add my personal packages to those Guix provides. -(cons (channel - (name 'my-personal-packages) - (url "https://example.org/personal-packages.git")) - %default-channels) +;; Now create a manifest with the current "guile" package +;; and the old "guile-json" package. +(packages->manifest + (list (first (lookup-inferior-packages inferior "guile-json")) + (specification->package "guile"))) @end lisp -@noindent -Note that the snippet above is (as always!)@: Scheme code; we use @code{cons} to -add a channel 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 your own repository. The result in -@file{~/.config/guix/current} is the union of Guix with your own package -modules: +On its first run, @command{guix package --manifest} might have to build the +channel you specified before it can create the inferior; subsequent runs will +be much faster because the Guix revision will be cached. -@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 - my-personal-packages dd3df5e - repository URL: https://example.org/personal-packages.git - branch: master - commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb - 11 new packages: my-gimp, my-emacs-with-cool-features, @dots{} - 4 packages upgraded: emacs-racket-mode@@0.0.2-2.1b78827, @dots{} -@end example +The @code{(guix inferior)} module provides the following procedures to open an +inferior: -@noindent -The output of @command{guix pull} above shows that Generation@tie{}19 includes -both Guix and packages from the @code{my-personal-packages} channel. Among -the new and upgraded packages that are listed, some like @code{my-gimp} and -@code{my-emacs-with-cool-features} might come from -@code{my-personal-packages}, while others come from the Guix default channel. +@deffn {Scheme Procedure} inferior-for-channels @var{channels} @ + [#:cache-directory] [#:ttl] +Return an inferior for @var{channels}, a list of channels. Use the cache at +@var{cache-directory}, where entries can be reclaimed after @var{ttl} seconds. +This procedure opens a new connection to the build daemon. -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 side effect, this procedure may build or substitute binaries for +@var{channels}, which can take time. +@end deffn -@cindex dependencies, channels -@cindex meta-data, channels -@subsection Declaring Channel Dependencies +@deffn {Scheme Procedure} open-inferior @var{directory} @ + [#:command "bin/guix"] +Open the inferior Guix in @var{directory}, running +@code{@var{directory}/@var{command} repl} or equivalent. Return @code{#f} if +the inferior could not be launched. +@end deffn -Channel authors may decide to augment a package collection provided by other -channels. They can declare their channel to be dependent on other channels in -a meta-data file @file{.guix-channel}, which is to be placed in the root of -the channel repository. +@cindex inferior packages +The procedures listed below allow you to obtain and manipulate inferior +packages. -The meta-data file should contain a simple S-expression like this: +@deffn {Scheme Procedure} inferior-packages @var{inferior} +Return the list of packages known to @var{inferior}. +@end deffn -@lisp -(channel - (version 0) - (dependencies - (channel - (name some-collection) - (url "https://example.org/first-collection.git") - - ;; The 'introduction' bit below is optional: you would - ;; provide it for dependencies that can be authenticated. - (introduction - (channel-introduction - (version 0) - (commit "a8883b58dc82e167c96506cf05095f37c2c2c6cd") - (signer "CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5")))) - (channel - (name some-other-collection) - (url "https://example.org/second-collection.git") - (branch "testing")))) -@end lisp +@deffn {Scheme Procedure} lookup-inferior-packages @var{inferior} @var{name} @ + [@var{version}] +Return the sorted list of inferior packages matching @var{name} in +@var{inferior}, with highest version numbers first. If @var{version} is true, +return only packages with a version number prefixed by @var{version}. +@end deffn -In the above example this channel is declared to depend on two other channels, -which will both be fetched automatically. The modules provided by the channel -will be compiled in an environment where the modules of all these declared -channels are available. +@deffn {Scheme Procedure} inferior-package? @var{obj} +Return true if @var{obj} is an inferior package. +@end deffn -For the sake of reliability and maintainability, you should avoid dependencies -on channels that you don't control, and you should aim to keep the number of -dependencies to a minimum. +@deffn {Scheme Procedure} inferior-package-name @var{package} +@deffnx {Scheme Procedure} inferior-package-version @var{package} +@deffnx {Scheme Procedure} inferior-package-synopsis @var{package} +@deffnx {Scheme Procedure} inferior-package-description @var{package} +@deffnx {Scheme Procedure} inferior-package-home-page @var{package} +@deffnx {Scheme Procedure} inferior-package-location @var{package} +@deffnx {Scheme Procedure} inferior-package-inputs @var{package} +@deffnx {Scheme Procedure} inferior-package-native-inputs @var{package} +@deffnx {Scheme Procedure} inferior-package-propagated-inputs @var{package} +@deffnx {Scheme Procedure} inferior-package-transitive-propagated-inputs @var{package} +@deffnx {Scheme Procedure} inferior-package-native-search-paths @var{package} +@deffnx {Scheme Procedure} inferior-package-transitive-native-search-paths @var{package} +@deffnx {Scheme Procedure} inferior-package-search-paths @var{package} +These procedures are the counterpart of package record accessors +(@pxref{package Reference}). Most of them work by querying the inferior +@var{package} comes from, so the inferior must still be live when you call +these procedures. +@end deffn -@cindex subdirectory, channels -@subsection Package Modules in a Sub-directory +Inferior packages can be used transparently like any other package or +file-like object in G-expressions (@pxref{G-Expressions}). They are also +transparently handled by the @code{packages->manifest} procedure, which is +commonly use in manifests (@pxref{Invoking guix package, the +@option{--manifest} option of @command{guix package}}). Thus you can insert +an inferior package pretty much anywhere you would insert a regular package: +in manifests, in the @code{packages} field of your @code{operating-system} +declaration, and so on. -As a channel author, you may want to keep your channel modules in a -sub-directory. If your modules are in the sub-directory @file{guix}, you must -add a meta-data file @file{.guix-channel} that contains: +@node Invoking guix describe +@section Invoking @command{guix describe} -@lisp -(channel - (version 0) - (directory "guix")) -@end lisp +@cindex reproducibility +@cindex replicating Guix +Often you may want to answer questions like: ``Which revision of Guix am I +using?'' or ``Which channels am I using?'' This is useful information in many +situations: if you want to @emph{replicate} an environment on a different +machine or user account, if you want to report a bug or to determine what +change in the channels you are using caused it, or if you want to record your +system state for reproducibility purposes. The @command{guix describe} +command answers these questions. -@cindex channel authorizations -@subsection Specifying Channel Authorizations +When run from a @command{guix pull}ed @command{guix}, @command{guix describe} +displays the channel(s) that it was built from, including their repository URL +and commit IDs (@pxref{Channels}): -@anchor{channel-authorizations} -As we saw above, Guix ensures the source code it pulls from channels -comes from authorized developers. As a channel author, you need to -specify the list of authorized developers in the -@file{.guix-authorizations} file in the channel's Git repository. The -authentication rule is simple: each commit must be signed by a key -listed in the @file{.guix-authorizations} file of its parent -commit(s)@footnote{Git commits form a @dfn{directed acyclic graph} -(DAG). Each commit can have zero or more parents; ``regular'' commits -have one parent and merge commits have two parent commits. Read -@uref{https://eagain.net/articles/git-for-computer-scientists/, @i{Git -for Computer Scientists}} for a great overview.} The -@file{.guix-authorizations} file looks like this: +@example +$ guix describe +Generation 10 Sep 03 2018 17:32:44 (current) + guix e0fa68c + repository URL: https://git.savannah.gnu.org/git/guix.git + branch: master + commit: e0fa68c7718fffd33d81af415279d6ddb518f727 +@end example -@lisp -;; Example '.guix-authorizations' file. +If you're familiar with the Git version control system, this is similar in +spirit to @command{git describe}; the output is also similar to that of +@command{guix pull --list-generations}, but limited to the current generation +(@pxref{Invoking guix pull, the @option{--list-generations} option}). Because +the Git commit ID shown above unambiguously refers to a snapshot of Guix, this +information is all it takes to describe the revision of Guix you're using, and +also to replicate it. -(authorizations - (version 0) ;current file format version +To make it easier to replicate Guix, @command{guix describe} can also be asked +to return a list of channels instead of the human-readable description above: - (("AD17 A21E F8AE D8F1 CC02 DBD9 F8AE D8F1 765C 61E3" - (name "alice")) - ("2A39 3FFF 68F4 EF7A 3D29 12AF 68F4 EF7A 22FB B2D5" - (name "bob")) - ("CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5" - (name "charlie")))) -@end lisp +@example +$ guix describe -f channels +(list (channel + (name 'guix) + (url "https://git.savannah.gnu.org/git/guix.git") + (commit + "e0fa68c7718fffd33d81af415279d6ddb518f727") + (introduction + (make-channel-introduction + "9edb3f66fd807b096b48283debdcddccfea34bad" + (openpgp-fingerprint + "BBB0 2DDF 2CEA F6A8 0D1D E643 A2A0 6DF2 A33A 54FA"))))) +@end example -Each fingerprint is followed by optional key/value pairs, as in the -example above. Currently these key/value pairs are ignored. +@noindent +You can save this to a file and feed it to @command{guix pull -C} on some +other machine or at a later point in time, which will instantiate @emph{this +exact Guix revision} (@pxref{Invoking guix pull, the @option{-C} option}). +From there on, since you're able to deploy the same revision of Guix, you can +just as well @emph{replicate a complete software environment}. We humbly +think that this is @emph{awesome}, and we hope you'll like it too! -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 -@file{.guix-authorizations}? And how do we fork existing channels? +The details of the options supported by @command{guix describe} are as +follows: -@cindex channel introduction -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 @command{guix pull} or @command{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. +@table @code +@item --format=@var{format} +@itemx -f @var{format} +Produce output in the specified @var{format}, one of: -Additionally, your channel must provide all the OpenPGP keys that were -ever mentioned in @file{.guix-authorizations}, stored as @file{.key} -files, which can be either binary or ``ASCII-armored''. By default, -those @file{.key} files are searched for in the branch named -@code{keyring} but you can specify a different branch name in -@code{.guix-channel} like so: +@table @code +@item human +produce human-readable output; +@item channels +produce a list of channel specifications that can be passed to @command{guix +pull -C} or installed as @file{~/.config/guix/channels.scm} (@pxref{Invoking +guix pull}); +@item channels-sans-intro +like @code{channels}, but omit the @code{introduction} field; use it to +produce a channel specification suitable for Guix version 1.1.0 or +earlier---the @code{introduction} field has to do with channel +authentication (@pxref{Channels, Channel Authentication}) and is not +supported by these older versions; +@item json +@cindex JSON +produce a list of channel specifications in JSON format; +@item recutils +produce a list of channel specifications in Recutils format. +@end table -@lisp -(channel - (version 0) - (keyring-reference "my-keyring-branch")) -@end lisp +@item --list-formats +Display available formats for @option{--format} option. -To summarize, as the author of a channel, there are three things you have -to do to allow users to authenticate your code: +@item --profile=@var{profile} +@itemx -p @var{profile} +Display information about @var{profile}. +@end table -@enumerate -@item -Export the OpenPGP keys of past and present committers with @command{gpg ---export} and store them in @file{.key} files, by default in a branch -named @code{keyring} (we recommend making it an @dfn{orphan branch}). +@node Invoking guix archive +@section Invoking @command{guix archive} -@item -Introduce an initial @file{.guix-authorizations} in the channel's -repository. Do that in a signed commit (@pxref{Commit Access}, for -information on how to sign Git commits.) +@cindex @command{guix archive} +@cindex archive +The @command{guix archive} command allows users to @dfn{export} files +from the store into a single archive, and to later @dfn{import} them on +a machine that runs Guix. +In particular, it allows store files to be transferred from one machine +to the store on another machine. -@item -Advertise the channel introduction, for instance on your channel's web -page. The channel introduction, as we saw above, is the commit/key -pair---i.e., the commit that introduced @file{.guix-authorizations}, and -the fingerprint of the OpenPGP used to sign it. -@end enumerate +@quotation Note +If you're looking for a way to produce archives in a format suitable for +tools other than Guix, @pxref{Invoking guix pack}. +@end quotation -Before pushing to your public Git repository, you can run @command{guix -git-authenticate} to verify that you did sign all the commits you are -about to push with an authorized key: +@cindex exporting store items +To export store files as an archive to standard output, run: @example -guix git authenticate @var{commit} @var{signer} +guix archive --export @var{options} @var{specifications}... @end example -@noindent -where @var{commit} and @var{signer} are your channel introduction. -@xref{Invoking guix git authenticate}, for details. +@var{specifications} may be either store file names or package +specifications, as for @command{guix package} (@pxref{Invoking guix +package}). For instance, the following command creates an archive +containing the @code{gui} output of the @code{git} package and the main +output of @code{emacs}: -Publishing a signed channel requires discipline: any mistake, such as an -unsigned commit or a commit signed by an unauthorized key, will prevent -users from pulling from your channel---well, that's the whole point of -authentication! Pay attention to merges in particular: merge commits -are considered authentic if and only if they are signed by a key present -in the @file{.guix-authorizations} file of @emph{both} branches. +@example +guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar +@end example -@cindex primary URL, channels -@subsection Primary URL +If the specified packages are not built yet, @command{guix archive} +automatically builds them. The build process may be controlled with the +common build options (@pxref{Common Build Options}). -Channel authors can indicate the primary URL of their channel's Git -repository in the @file{.guix-channel} file, like so: - -@lisp -(channel - (version 0) - (url "https://example.org/guix.git")) -@end lisp - -This allows @command{guix pull} to determine whether it is pulling code -from a mirror of the channel; when that is the case, it warns the user -that the mirror might be stale and displays the primary URL. That way, -users cannot be tricked into fetching code from a stale mirror that does -not receive security updates. +To transfer the @code{emacs} package to a machine connected over SSH, +one would run: -This feature only makes sense for authenticated repositories, such as -the official @code{guix} channel, for which @command{guix pull} ensures -the code it fetches is authentic. +@example +guix archive --export -r emacs | ssh the-machine guix archive --import +@end example -@cindex news, for channels -@subsection Writing Channel News +@noindent +Similarly, a complete user profile may be transferred from one machine +to another like this: -Channel authors may occasionally want to communicate to their users -information about important changes in the channel. You'd send them all -an email, but that's not convenient. +@example +guix archive --export -r $(readlink -f ~/.guix-profile) | \ + ssh the-machine guix archive --import +@end example -Instead, channels can provide a @dfn{news file}; when the channel users -run @command{guix pull}, that news file is automatically read and -@command{guix pull --news} can display the announcements that correspond -to the new commits that have been pulled, if any. +@noindent +However, note that, in both examples, all of @code{emacs} and the +profile as well as all of their dependencies are transferred (due to +@option{-r}), regardless of what is already available in the store on +the target machine. The @option{--missing} option can help figure out +which items are missing from the target store. The @command{guix copy} +command simplifies and optimizes this whole process, so this is probably +what you should use in this case (@pxref{Invoking guix copy}). -To do that, channel authors must first declare the name of the news file -in their @file{.guix-channel} file: +@cindex nar, archive format +@cindex normalized archive (nar) +@cindex nar bundle, archive format +Each store item is written in the @dfn{normalized archive} or @dfn{nar} +format (described below), and the output of @command{guix archive +--export} (and input of @command{guix archive --import}) is a @dfn{nar +bundle}. -@lisp -(channel - (version 0) - (news-file "etc/news.txt")) -@end lisp +The nar format is +comparable in spirit to `tar', but with differences +that make it more appropriate for our purposes. First, rather than +recording all Unix metadata for each file, the nar format only mentions +the file type (regular, directory, or symbolic link); Unix permissions +and owner/group are dismissed. Second, the order in which directory +entries are stored always follows the order of file names according to +the C locale collation order. This makes archive production fully +deterministic. -The news file itself, @file{etc/news.txt} in this example, must look -something like this: +That nar bundle format is essentially the concatenation of zero or more +nars along with metadata for each store item it contains: its file name, +references, corresponding derivation, and a digital signature. -@lisp -(channel-news - (version 0) - (entry (tag "the-bug-fix") - (title (en "Fixed terrible bug") - (fr "Oh la la")) - (body (en "@@emph@{Good news@}! It's fixed!") - (eo "Certe ĝi pli bone funkcias nun!"))) - (entry (commit "bdcabe815cd28144a2d2b4bc3c5057b051fa9906") - (title (en "Added a great package") - (ca "Què vol dir guix?")) - (body (en "Don't miss the @@code@{hello@} package!")))) -@end lisp +When exporting, the daemon digitally signs the contents of the archive, +and that digital signature is appended. When importing, the daemon +verifies the signature and rejects the import in case of an invalid +signature or if the signing key is not authorized. +@c FIXME: Add xref to daemon doc about signatures. -While the news file is using the Scheme syntax, avoid naming it with a -@file{.scm} extension or else it will get picked up when building the -channel and yield an error since it is not a valid module. -Alternatively, you can move the channel module to a subdirectory and -store the news file in another directory. +The main options are: -The file consists of a list of @dfn{news entries}. Each entry is -associated with a commit or tag: it describes changes made in this -commit, possibly in preceding commits as well. Users see entries only -the first time they obtain the commit the entry refers to. +@table @code +@item --export +Export the specified store files or packages (see below). Write the +resulting archive to the standard output. -The @code{title} field should be a one-line summary while @code{body} -can be arbitrarily long, and both can contain Texinfo markup -(@pxref{Overview,,, texinfo, GNU Texinfo}). Both the title and body are -a list of language tag/message tuples, which allows @command{guix pull} -to display news in the language that corresponds to the user's locale. +Dependencies are @emph{not} included in the output, unless +@option{--recursive} is passed. -If you want to translate news using a gettext-based workflow, you can -extract translatable strings with @command{xgettext} (@pxref{xgettext -Invocation,,, gettext, GNU Gettext Utilities}). For example, assuming -you write news entries in English first, the command below creates a PO -file containing the strings to translate: +@item -r +@itemx --recursive +When combined with @option{--export}, this instructs @command{guix archive} +to include dependencies of the given items in the archive. Thus, the +resulting archive is self-contained: it contains the closure of the +exported store items. -@example -xgettext -o news.po -l scheme -ken etc/news.txt -@end example +@item --import +Read an archive from the standard input, and import the files listed +therein into the store. Abort if the archive has an invalid digital +signature, or if it is signed by a public key not among the authorized +keys (see @option{--authorize} below). -To sum up, yes, you could use your channel as a blog. But beware, this -is @emph{not quite} what your users might expect. +@item --missing +Read a list of store file names from the standard input, one per line, +and write on the standard output the subset of these files missing from +the store. -@subsection Replicating Guix +@item --generate-key[=@var{parameters}] +@cindex signing, archives +Generate a new key pair for the daemon. This is a prerequisite before +archives can be exported with @option{--export}. Note that this +operation usually takes time, because it needs to gather enough entropy +to generate the key pair. -@cindex pinning, channels -@cindex replicating Guix -@cindex reproducibility, of Guix -The @command{guix pull --list-generations} output above shows precisely which -commits were used to build this instance of Guix. We can thus replicate it, -say, on another machine, by providing a channel specification in -@file{~/.config/guix/channels.scm} that is ``pinned'' to these commits: +The generated key pair is typically stored under @file{/etc/guix}, in +@file{signing-key.pub} (public key) and @file{signing-key.sec} (private +key, which must be kept secret). When @var{parameters} is omitted, +an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt +versions before 1.6.0, it is a 4096-bit RSA key. +Alternatively, @var{parameters} can specify +@code{genkey} parameters suitable for Libgcrypt (@pxref{General +public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The +Libgcrypt Reference Manual}). -@lisp -;; Deploy specific commits of my channels of interest. -(list (channel - (name 'guix) - (url "https://git.savannah.gnu.org/git/guix.git") - (commit "6298c3ffd9654d3231a6f25390b056483e8f407c")) - (channel - (name 'my-personal-packages) - (url "https://example.org/personal-packages.git") - (commit "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb"))) -@end lisp +@item --authorize +@cindex authorizing, archives +Authorize imports signed by the public key passed on standard input. +The public key must be in ``s-expression advanced format''---i.e., the +same format as the @file{signing-key.pub} file. -The @command{guix describe --format=channels} command can even generate this -list of channels directly (@pxref{Invoking guix describe}). The resulting -file can be used with the -C options of @command{guix pull} -(@pxref{Invoking guix pull}) or @command{guix time-machine} -(@pxref{Invoking guix time-machine}). +The list of authorized keys is kept in the human-editable file +@file{/etc/guix/acl}. The file contains +@url{https://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format +s-expressions''} and is structured as an access-control list in the +@url{https://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure +(SPKI)}. -At this point the two machines run the @emph{exact same Guix}, with access to -the @emph{exact same packages}. The output of @command{guix build gimp} on -one machine will be exactly the same, bit for bit, as the output of the same -command on the other machine. It also means both machines have access to all -the source code of Guix and, transitively, to all the source code of every -package it defines. +@item --extract=@var{directory} +@itemx -x @var{directory} +Read a single-item archive as served by substitute servers +(@pxref{Substitutes}) and extract it to @var{directory}. This is a +low-level operation needed in only very narrow use cases; see below. -This gives you super powers, allowing you to track the provenance of binary -artifacts with very fine grain, and to reproduce software environments at -will---some sort of ``meta reproducibility'' capabilities, if you will. -@xref{Inferiors}, for another way to take advantage of these super powers. +For example, the following command extracts the substitute for Emacs +served by @code{@value{SUBSTITUTE-SERVER}} to @file{/tmp/emacs}: -@node Invoking guix time-machine -@section Invoking @command{guix time-machine} +@example +$ wget -O - \ + https://@value{SUBSTITUTE-SERVER}/nar/gzip/@dots{}-emacs-24.5 \ + | gunzip | guix archive -x /tmp/emacs +@end example -@cindex @command{guix time-machine} -@cindex pinning, channels -@cindex replicating Guix -@cindex reproducibility, of Guix +Single-item archives are different from multiple-item archives produced +by @command{guix archive --export}; they contain a single store item, +and they do @emph{not} embed a signature. Thus this operation does +@emph{no} signature verification and its output should be considered +unsafe. -The @command{guix time-machine} command provides access to other -revisions of Guix, for example to install older versions of packages, -or to reproduce a computation in an identical environment. The revision -of Guix to be used is defined by a commit or by a channel -description file created by @command{guix describe} -(@pxref{Invoking guix describe}). +The primary purpose of this operation is to facilitate inspection of +archive contents coming from possibly untrusted substitute servers +(@pxref{Invoking guix challenge}). -The general syntax is: +@item --list +@itemx -t +Read a single-item archive as served by substitute servers +(@pxref{Substitutes}) and print the list of files it contains, as in +this example: @example -guix time-machine @var{options}@dots{} -- @var{command} @var {arg}@dots{} +$ wget -O - \ + https://@value{SUBSTITUTE-SERVER}/nar/lzip/@dots{}-emacs-26.3 \ + | lzip -d | guix archive -t @end example -where @var{command} and @var{arg}@dots{} are passed unmodified to the -@command{guix} command of the specified revision. The @var{options} that define -this revision are the same as for @command{guix pull} (@pxref{Invoking guix pull}): - -@table @code -@item --url=@var{url} -@itemx --commit=@var{commit} -@itemx --branch=@var{branch} -Use the @code{guix} channel from the specified @var{url}, at the -given @var{commit} (a valid Git commit ID represented as a hexadecimal -string), or @var{branch}. - -@item --channels=@var{file} -@itemx -C @var{file} -Read the list of channels from @var{file}. @var{file} must contain -Scheme code that evaluates to a list of channel objects. -@xref{Channels} for more information. @end table -As for @command{guix pull}, the absence of any options means that the -the latest commit on the master branch will be used. The command +@c ********************************************************************* +@node Channels +@chapter Channels + +@cindex channels +@cindex @file{channels.scm}, configuration file +@cindex configuration file for channels +@cindex @command{guix pull}, configuration file +@cindex configuration of @command{guix pull} +Guix and its package collection are updated by running @command{guix pull} +(@pxref{Invoking guix pull}). By default @command{guix pull} downloads and +deploys Guix itself from the official GNU@tie{}Guix repository. This can be +customized by defining @dfn{channels} in the +@file{~/.config/guix/channels.scm} file. A channel specifies a URL and branch +of a Git repository to be deployed, and @command{guix pull} can be instructed +to pull from one or more channels. In other words, channels can be used +to @emph{customize} and to @emph{extend} Guix, as we will see below. +Guix is able to take into account security concerns and deal with authenticated +updates. + +@menu +* Specifying Additional Channels:: Extending the package collection. +* Using a Custom Guix Channel:: Using a customized Guix. +* Replicating Guix:: Running the @emph{exact same} Guix. +* Channel Authentication:: How Guix verifies what it fetches. +* Primary URL:: Distinguishing mirror to original. +* Creating a Channel:: How to write your custom channel. +* Package Modules in a Sub-directory:: Specifying the channel's package modules location. +* Declaring Channel Dependencies:: How to depend on other channels. +* Specifying Channel Authorizations:: Defining channel authors authorizations. +* Writing Channel News:: Communicating information to channel's users. +@end menu + +@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 the default Guix channel(s): + +@vindex %default-channels +@lisp +;; Add variant packages to those Guix provides. +(cons (channel + (name 'variant-packages) + (url "https://example.org/variant-packages.git")) + %default-channels) +@end lisp + +@noindent +Note that the snippet above is (as always!)@: Scheme code; we use @code{cons} to +add a channel 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 your own repository. The result in +@file{~/.config/guix/current} is the union of Guix with your own package +modules: @example -guix time-machine -- build hello +$ 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-packages dd3df5e + repository URL: https://example.org/variant-packages.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 -will thus build the package @code{hello} as defined in the master branch, -which is in general a newer revision of Guix than you have installed. -Time travel works in both directions! +@noindent +The output of @command{guix pull} above shows that Generation@tie{}19 includes +both Guix and packages from the @code{variant-personal-packages} 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-packages}, while others come from the Guix default channel. -Note that @command{guix time-machine} can trigger builds of channels and -their dependencies, and these are controlled by the standard build -options (@pxref{Common Build Options}). +@node Using a Custom Guix Channel +@section Using a Custom Guix Channel -@node Inferiors -@section Inferiors +The channel called @code{guix} specifies where Guix itself---its command-line +tools as well as its package collection---should be downloaded. For instance, +suppose you want to update from another copy of the Guix repository at +@code{example.org}, and specifically the @code{super-hacks} branch, you can +write in @code{~/.config/guix/channels.scm} this specification: -@c TODO: Remove this once we're more confident about API stability. -@quotation Note -The functionality described here is a ``technology preview'' as of version -@value{VERSION}. As such, the interface is subject to change. -@end quotation +@lisp +;; Tell 'guix pull' to use another repo. +(list (channel + (name 'guix) + (url "https://example.org/another-guix.git") + (branch "super-hacks"))) +@end lisp -@cindex inferiors -@cindex composition of Guix revisions -Sometimes you might need to mix packages from the revision of Guix you're -currently running with packages available in a different revision of Guix. -Guix @dfn{inferiors} allow you to achieve that by composing different Guix -revisions in arbitrary ways. +@noindent +From there on, @command{guix pull} will fetch code from the @code{super-hacks} +branch of the repository at @code{example.org}. The authentication concern is +addressed below ((@pxref{Channel Authentication}). -@cindex inferior packages -Technically, an ``inferior'' is essentially a separate Guix process connected -to your main Guix process through a REPL (@pxref{Invoking guix repl}). The -@code{(guix inferior)} module allows you to create inferiors and to -communicate with them. It also provides a high-level interface to browse and -manipulate the packages that an inferior provides---@dfn{inferior packages}. +@node Replicating Guix +@section Replicating Guix -When combined with channels (@pxref{Channels}), inferiors provide a simple way -to interact with a separate revision of Guix. For example, let's assume you -want to install in your profile the current @code{guile} package, along with -the @code{guile-json} as it existed in an older revision of Guix---perhaps -because the newer @code{guile-json} has an incompatible API and you want to -run your code against the old API@. To do that, you could write a manifest for -use by @code{guix package --manifest} (@pxref{Invoking guix package}); in that -manifest, you would create an inferior for that old Guix revision you care -about, and you would look up the @code{guile-json} package in the inferior: +@cindex pinning, channels +@cindex replicating Guix +@cindex reproducibility, of Guix +The @command{guix pull --list-generations} output above shows precisely which +commits were used to build this instance of Guix. We can thus replicate it, +say, on another machine, by providing a channel specification in +@file{~/.config/guix/channels.scm} that is ``pinned'' to these commits: @lisp -(use-modules (guix inferior) (guix channels) - (srfi srfi-1)) ;for 'first' +;; Deploy specific commits of my channels of interest. +(list (channel + (name 'guix) + (url "https://git.savannah.gnu.org/git/guix.git") + (commit "6298c3ffd9654d3231a6f25390b056483e8f407c")) + (channel + (name 'variant-packages) + (url "https://example.org/variant-packages.git") + (commit "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb"))) +@end lisp -(define channels - ;; This is the old revision from which we want to - ;; extract guile-json. - (list (channel - (name 'guix) - (url "https://git.savannah.gnu.org/git/guix.git") - (commit - "65956ad3526ba09e1f7a40722c96c6ef7c0936fe")))) +The @command{guix describe --format=channels} command can even generate this +list of channels directly (@pxref{Invoking guix describe}). The resulting +file can be used with the -C options of @command{guix pull} +(@pxref{Invoking guix pull}) or @command{guix time-machine} +(@pxref{Invoking guix time-machine}). -(define inferior - ;; An inferior representing the above revision. - (inferior-for-channels channels)) +At this point the two machines run the @emph{exact same Guix}, with access to +the @emph{exact same packages}. The output of @command{guix build gimp} on +one machine will be exactly the same, bit for bit, as the output of the same +command on the other machine. It also means both machines have access to all +the source code of Guix and, transitively, to all the source code of every +package it defines. -;; Now create a manifest with the current "guile" package -;; and the old "guile-json" package. -(packages->manifest - (list (first (lookup-inferior-packages inferior "guile-json")) - (specification->package "guile"))) +This gives you super powers, allowing you to track the provenance of binary +artifacts with very fine grain, and to reproduce software environments at +will---some sort of ``meta reproducibility'' capabilities, if you will. +@xref{Inferiors}, for another way to take advantage of these super powers. + +@node Channel Authentication +@section Channel Authentication + +@anchor{channel-authentication} +@cindex authentication, of channel code +The @command{guix pull} and @command{guix time-machine} commands +@dfn{authenticate} the code retrieved from channels: they make sure each +commit that is fetched is signed by an authorized developer. The goal +is to protect from unauthorized modifications to the channel that would +lead users to run malicious code. + +As a user, you must provide a @dfn{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: + +@lisp +(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")))) @end lisp -On its first run, @command{guix package --manifest} might have to build the -channel you specified before it can create the inferior; subsequent runs will -be much faster because the Guix revision will be cached. +The specification above shows the name and URL of the channel. The call +to @code{make-channel-introduction} above specifies that authentication +of this channel starts at commit @code{6f0d8cc@dots{}}, which is signed +by the OpenPGP key with fingerprint @code{CABB A931@dots{}}. -The @code{(guix inferior)} module provides the following procedures to open an -inferior: +For the main channel, called @code{guix}, you automatically get that +information from your Guix installation. For other channels, include +the channel introduction provided by the channel authors in your +@file{channels.scm} file. Make sure you retrieve the channel +introduction from a trusted source since that is the root of your trust. -@deffn {Scheme Procedure} inferior-for-channels @var{channels} @ - [#:cache-directory] [#:ttl] -Return an inferior for @var{channels}, a list of channels. Use the cache at -@var{cache-directory}, where entries can be reclaimed after @var{ttl} seconds. -This procedure opens a new connection to the build daemon. +If you're curious about the authentication mechanics, read on! -As a side effect, this procedure may build or substitute binaries for -@var{channels}, which can take time. -@end deffn +@cindex primary URL, channels +@node Primary URL +@section Primary URL -@deffn {Scheme Procedure} open-inferior @var{directory} @ - [#:command "bin/guix"] -Open the inferior Guix in @var{directory}, running -@code{@var{directory}/@var{command} repl} or equivalent. Return @code{#f} if -the inferior could not be launched. -@end deffn +Channel authors can indicate the primary URL of their channel's Git +repository in the @file{.guix-channel} file, like so: -@cindex inferior packages -The procedures listed below allow you to obtain and manipulate inferior -packages. +@lisp +(channel + (version 0) + (url "https://example.org/guix.git")) +@end lisp -@deffn {Scheme Procedure} inferior-packages @var{inferior} -Return the list of packages known to @var{inferior}. -@end deffn +This allows @command{guix pull} to determine whether it is pulling code +from a mirror of the channel; when that is the case, it warns the user +that the mirror might be stale and displays the primary URL. That way, +users cannot be tricked into fetching code from a stale mirror that does +not receive security updates. -@deffn {Scheme Procedure} lookup-inferior-packages @var{inferior} @var{name} @ - [@var{version}] -Return the sorted list of inferior packages matching @var{name} in -@var{inferior}, with highest version numbers first. If @var{version} is true, -return only packages with a version number prefixed by @var{version}. -@end deffn +This feature only makes sense for authenticated repositories, such as +the official @code{guix} channel, for which @command{guix pull} ensures +the code it fetches is authentic. -@deffn {Scheme Procedure} inferior-package? @var{obj} -Return true if @var{obj} is an inferior package. -@end deffn +@cindex personal packages (channels) +@cindex channels, for personal packages +@node Creating a Channel +@section Creating a Channel -@deffn {Scheme Procedure} inferior-package-name @var{package} -@deffnx {Scheme Procedure} inferior-package-version @var{package} -@deffnx {Scheme Procedure} inferior-package-synopsis @var{package} -@deffnx {Scheme Procedure} inferior-package-description @var{package} -@deffnx {Scheme Procedure} inferior-package-home-page @var{package} -@deffnx {Scheme Procedure} inferior-package-location @var{package} -@deffnx {Scheme Procedure} inferior-package-inputs @var{package} -@deffnx {Scheme Procedure} inferior-package-native-inputs @var{package} -@deffnx {Scheme Procedure} inferior-package-propagated-inputs @var{package} -@deffnx {Scheme Procedure} inferior-package-transitive-propagated-inputs @var{package} -@deffnx {Scheme Procedure} inferior-package-native-search-paths @var{package} -@deffnx {Scheme Procedure} inferior-package-transitive-native-search-paths @var{package} -@deffnx {Scheme Procedure} inferior-package-search-paths @var{package} -These procedures are the counterpart of package record accessors -(@pxref{package Reference}). Most of them work by querying the inferior -@var{package} comes from, so the inferior must still be live when you call -these procedures. -@end deffn +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? -Inferior packages can be used transparently like any other package or -file-like object in G-expressions (@pxref{G-Expressions}). They are also -transparently handled by the @code{packages->manifest} procedure, which is -commonly use in manifests (@pxref{Invoking guix package, the -@option{--manifest} option of @command{guix package}}). Thus you can insert -an inferior package pretty much anywhere you would insert a regular package: -in manifests, in the @code{packages} field of your @code{operating-system} -declaration, and so on. +@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: -@node Invoking guix describe -@section Invoking @command{guix describe} +@itemize +@item +Before publishing a channel, please consider contributing your package +definitions to Guix proper (@pxref{Contributing}). Guix as a project is open +to free software of all sorts, and packages in Guix proper are readily +available to all Guix users and benefit from the project's quality assurance +process. -@cindex reproducibility -@cindex replicating Guix -Often you may want to answer questions like: ``Which revision of Guix am I -using?'' or ``Which channels am I using?'' This is useful information in many -situations: if you want to @emph{replicate} an environment on a different -machine or user account, if you want to report a bug or to determine what -change in the channels you are using caused it, or if you want to record your -system state for reproducibility purposes. The @command{guix describe} -command answers these questions. +@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. -When run from a @command{guix pull}ed @command{guix}, @command{guix describe} -displays the channel(s) that it was built from, including their repository URL -and commit IDs (@pxref{Channels}): +@item +Corollary: if you're using an external channel and that channel breaks, please +@emph{report the issue to the channel authors}, not to the Guix project. +@end itemize -@example -$ guix describe -Generation 10 Sep 03 2018 17:32:44 (current) - guix e0fa68c - repository URL: https://git.savannah.gnu.org/git/guix.git - branch: master - commit: e0fa68c7718fffd33d81af415279d6ddb518f727 -@end example +You've been warned! Having said this, we believe external channels are a +practical way to exert your freedom to augment Guix' package collection and to +share your improvements, which are basic tenets of +@uref{https://www.gnu.org/philosophy/free-sw.html, free software}. Please +email us at @email{guix-devel@@gnu.org} if you'd like to discuss this. +@end quotation -If you're familiar with the Git version control system, this is similar in -spirit to @command{git describe}; the output is also similar to that of -@command{guix pull --list-generations}, but limited to the current generation -(@pxref{Invoking guix pull, the @option{--list-generations} option}). Because -the Git commit ID shown above unambiguously refers to a snapshot of Guix, this -information is all it takes to describe the revision of Guix you're using, and -also to replicate it. +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 make it easier to replicate Guix, @command{guix describe} can also be asked -to return a list of channels instead of the human-readable description above: +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. -@example -$ guix describe -f channels -(list (channel - (name 'guix) - (url "https://git.savannah.gnu.org/git/guix.git") - (commit - "e0fa68c7718fffd33d81af415279d6ddb518f727") - (introduction - (make-channel-introduction - "9edb3f66fd807b096b48283debdcddccfea34bad" - (openpgp-fingerprint - "BBB0 2DDF 2CEA F6A8 0D1D E643 A2A0 6DF2 A33A 54FA"))))) -@end example -@noindent -You can save this to a file and feed it to @command{guix pull -C} on some -other machine or at a later point in time, which will instantiate @emph{this -exact Guix revision} (@pxref{Invoking guix pull, the @option{-C} option}). -From there on, since you're able to deploy the same revision of Guix, you can -just as well @emph{replicate a complete software environment}. We humbly -think that this is @emph{awesome}, and we hope you'll like it too! +@cindex subdirectory, channels +@node Package Modules in a Sub-directory +@section Package Modules in a Sub-directory -The details of the options supported by @command{guix describe} are as -follows: +As a channel author, you may want to keep your channel modules in a +sub-directory. If your modules are in the sub-directory @file{guix}, you must +add a meta-data file @file{.guix-channel} that contains: -@table @code -@item --format=@var{format} -@itemx -f @var{format} -Produce output in the specified @var{format}, one of: +@lisp +(channel + (version 0) + (directory "guix")) +@end lisp -@table @code -@item human -produce human-readable output; -@item channels -produce a list of channel specifications that can be passed to @command{guix -pull -C} or installed as @file{~/.config/guix/channels.scm} (@pxref{Invoking -guix pull}); -@item channels-sans-intro -like @code{channels}, but omit the @code{introduction} field; use it to -produce a channel specification suitable for Guix version 1.1.0 or -earlier---the @code{introduction} field has to do with channel -authentication (@pxref{Channels, Channel Authentication}) and is not -supported by these older versions; -@item json -@cindex JSON -produce a list of channel specifications in JSON format; -@item recutils -produce a list of channel specifications in Recutils format. -@end table +@cindex dependencies, channels +@cindex meta-data, channels +@node Declaring Channel Dependencies +@section Declaring Channel Dependencies -@item --list-formats -Display available formats for @option{--format} option. +Channel authors may decide to augment a package collection provided by other +channels. They can declare their channel to be dependent on other channels in +a meta-data file @file{.guix-channel}, which is to be placed in the root of +the channel repository. -@item --profile=@var{profile} -@itemx -p @var{profile} -Display information about @var{profile}. -@end table +The meta-data file should contain a simple S-expression like this: -@node Invoking guix archive -@section Invoking @command{guix archive} +@lisp +(channel + (version 0) + (dependencies + (channel + (name 'some-collection) + (url "https://example.org/first-collection.git") -@cindex @command{guix archive} -@cindex archive -The @command{guix archive} command allows users to @dfn{export} files -from the store into a single archive, and to later @dfn{import} them on -a machine that runs Guix. -In particular, it allows store files to be transferred from one machine -to the store on another machine. + ;; The 'introduction' bit below is optional: you would + ;; provide it for dependencies that can be authenticated. + (introduction + (channel-introduction + (version 0) + (commit "a8883b58dc82e167c96506cf05095f37c2c2c6cd") + (signer "CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5")))) + (channel + (name 'some-other-collection) + (url "https://example.org/second-collection.git") + (branch "testing")))) +@end lisp -@quotation Note -If you're looking for a way to produce archives in a format suitable for -tools other than Guix, @pxref{Invoking guix pack}. -@end quotation +In the above example this channel is declared to depend on two other channels, +which will both be fetched automatically. The modules provided by the channel +will be compiled in an environment where the modules of all these declared +channels are available. -@cindex exporting store items -To export store files as an archive to standard output, run: +For the sake of reliability and maintainability, you should avoid dependencies +on channels that you don't control, and you should aim to keep the number of +dependencies to a minimum. -@example -guix archive --export @var{options} @var{specifications}... -@end example +@cindex channel authorizations +@node Specifying Channel Authorizations +@section Specifying Channel Authorizations -@var{specifications} may be either store file names or package -specifications, as for @command{guix package} (@pxref{Invoking guix -package}). For instance, the following command creates an archive -containing the @code{gui} output of the @code{git} package and the main -output of @code{emacs}: +@anchor{channel-authorizations} +As we saw above, Guix ensures the source code it pulls from channels +comes from authorized developers. As a channel author, you need to +specify the list of authorized developers in the +@file{.guix-authorizations} file in the channel's Git repository. The +authentication rule is simple: each commit must be signed by a key +listed in the @file{.guix-authorizations} file of its parent +commit(s)@footnote{Git commits form a @dfn{directed acyclic graph} +(DAG). Each commit can have zero or more parents; ``regular'' commits +have one parent and merge commits have two parent commits. Read +@uref{https://eagain.net/articles/git-for-computer-scientists/, @i{Git +for Computer Scientists}} for a great overview.} The +@file{.guix-authorizations} file looks like this: -@example -guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar -@end example +@lisp +;; Example '.guix-authorizations' file. -If the specified packages are not built yet, @command{guix archive} -automatically builds them. The build process may be controlled with the -common build options (@pxref{Common Build Options}). +(authorizations + (version 0) ;current file format version -To transfer the @code{emacs} package to a machine connected over SSH, -one would run: + (("AD17 A21E F8AE D8F1 CC02 DBD9 F8AE D8F1 765C 61E3" + (name "alice")) + ("2A39 3FFF 68F4 EF7A 3D29 12AF 68F4 EF7A 22FB B2D5" + (name "bob")) + ("CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5" + (name "charlie")))) +@end lisp -@example -guix archive --export -r emacs | ssh the-machine guix archive --import -@end example +Each fingerprint is followed by optional key/value pairs, as in the +example above. Currently these key/value pairs are ignored. -@noindent -Similarly, a complete user profile may be transferred from one machine -to another like this: +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 +@file{.guix-authorizations}? And how do we fork existing channels? -@example -guix archive --export -r $(readlink -f ~/.guix-profile) | \ - ssh the-machine guix archive --import -@end example +@cindex channel introduction +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 @command{guix pull} or @command{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. -@noindent -However, note that, in both examples, all of @code{emacs} and the -profile as well as all of their dependencies are transferred (due to -@option{-r}), regardless of what is already available in the store on -the target machine. The @option{--missing} option can help figure out -which items are missing from the target store. The @command{guix copy} -command simplifies and optimizes this whole process, so this is probably -what you should use in this case (@pxref{Invoking guix copy}). +Additionally, your channel must provide all the OpenPGP keys that were +ever mentioned in @file{.guix-authorizations}, stored as @file{.key} +files, which can be either binary or ``ASCII-armored''. By default, +those @file{.key} files are searched for in the branch named +@code{keyring} but you can specify a different branch name in +@code{.guix-channel} like so: -@cindex nar, archive format -@cindex normalized archive (nar) -@cindex nar bundle, archive format -Each store item is written in the @dfn{normalized archive} or @dfn{nar} -format (described below), and the output of @command{guix archive ---export} (and input of @command{guix archive --import}) is a @dfn{nar -bundle}. +@lisp +(channel + (version 0) + (keyring-reference "my-keyring-branch")) +@end lisp -The nar format is -comparable in spirit to `tar', but with differences -that make it more appropriate for our purposes. First, rather than -recording all Unix metadata for each file, the nar format only mentions -the file type (regular, directory, or symbolic link); Unix permissions -and owner/group are dismissed. Second, the order in which directory -entries are stored always follows the order of file names according to -the C locale collation order. This makes archive production fully -deterministic. +To summarize, as the author of a channel, there are three things you have +to do to allow users to authenticate your code: -That nar bundle format is essentially the concatenation of zero or more -nars along with metadata for each store item it contains: its file name, -references, corresponding derivation, and a digital signature. +@enumerate +@item +Export the OpenPGP keys of past and present committers with @command{gpg +--export} and store them in @file{.key} files, by default in a branch +named @code{keyring} (we recommend making it an @dfn{orphan branch}). -When exporting, the daemon digitally signs the contents of the archive, -and that digital signature is appended. When importing, the daemon -verifies the signature and rejects the import in case of an invalid -signature or if the signing key is not authorized. -@c FIXME: Add xref to daemon doc about signatures. +@item +Introduce an initial @file{.guix-authorizations} in the channel's +repository. Do that in a signed commit (@pxref{Commit Access}, for +information on how to sign Git commits.) -The main options are: +@item +Advertise the channel introduction, for instance on your channel's web +page. The channel introduction, as we saw above, is the commit/key +pair---i.e., the commit that introduced @file{.guix-authorizations}, and +the fingerprint of the OpenPGP used to sign it. +@end enumerate -@table @code -@item --export -Export the specified store files or packages (see below). Write the -resulting archive to the standard output. +Before pushing to your public Git repository, you can run @command{guix +git-authenticate} to verify that you did sign all the commits you are +about to push with an authorized key: -Dependencies are @emph{not} included in the output, unless -@option{--recursive} is passed. +@example +guix git authenticate @var{commit} @var{signer} +@end example -@item -r -@itemx --recursive -When combined with @option{--export}, this instructs @command{guix archive} -to include dependencies of the given items in the archive. Thus, the -resulting archive is self-contained: it contains the closure of the -exported store items. +@noindent +where @var{commit} and @var{signer} are your channel introduction. +@xref{Invoking guix git authenticate}, for details. -@item --import -Read an archive from the standard input, and import the files listed -therein into the store. Abort if the archive has an invalid digital -signature, or if it is signed by a public key not among the authorized -keys (see @option{--authorize} below). +Publishing a signed channel requires discipline: any mistake, such as an +unsigned commit or a commit signed by an unauthorized key, will prevent +users from pulling from your channel---well, that's the whole point of +authentication! Pay attention to merges in particular: merge commits +are considered authentic if and only if they are signed by a key present +in the @file{.guix-authorizations} file of @emph{both} branches. -@item --missing -Read a list of store file names from the standard input, one per line, -and write on the standard output the subset of these files missing from -the store. +@cindex news, for channels +@node Writing Channel News +@section Writing Channel News -@item --generate-key[=@var{parameters}] -@cindex signing, archives -Generate a new key pair for the daemon. This is a prerequisite before -archives can be exported with @option{--export}. Note that this -operation usually takes time, because it needs to gather enough entropy -to generate the key pair. +Channel authors may occasionally want to communicate to their users +information about important changes in the channel. You'd send them all +an email, but that's not convenient. -The generated key pair is typically stored under @file{/etc/guix}, in -@file{signing-key.pub} (public key) and @file{signing-key.sec} (private -key, which must be kept secret). When @var{parameters} is omitted, -an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt -versions before 1.6.0, it is a 4096-bit RSA key. -Alternatively, @var{parameters} can specify -@code{genkey} parameters suitable for Libgcrypt (@pxref{General -public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The -Libgcrypt Reference Manual}). +Instead, channels can provide a @dfn{news file}; when the channel users +run @command{guix pull}, that news file is automatically read and +@command{guix pull --news} can display the announcements that correspond +to the new commits that have been pulled, if any. -@item --authorize -@cindex authorizing, archives -Authorize imports signed by the public key passed on standard input. -The public key must be in ``s-expression advanced format''---i.e., the -same format as the @file{signing-key.pub} file. +To do that, channel authors must first declare the name of the news file +in their @file{.guix-channel} file: -The list of authorized keys is kept in the human-editable file -@file{/etc/guix/acl}. The file contains -@url{https://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format -s-expressions''} and is structured as an access-control list in the -@url{https://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure -(SPKI)}. +@lisp +(channel + (version 0) + (news-file "etc/news.txt")) +@end lisp -@item --extract=@var{directory} -@itemx -x @var{directory} -Read a single-item archive as served by substitute servers -(@pxref{Substitutes}) and extract it to @var{directory}. This is a -low-level operation needed in only very narrow use cases; see below. +The news file itself, @file{etc/news.txt} in this example, must look +something like this: -For example, the following command extracts the substitute for Emacs -served by @code{@value{SUBSTITUTE-SERVER}} to @file{/tmp/emacs}: +@lisp +(channel-news + (version 0) + (entry (tag "the-bug-fix") + (title (en "Fixed terrible bug") + (fr "Oh la la")) + (body (en "@@emph@{Good news@}! It's fixed!") + (eo "Certe ĝi pli bone funkcias nun!"))) + (entry (commit "bdcabe815cd28144a2d2b4bc3c5057b051fa9906") + (title (en "Added a great package") + (ca "Què vol dir guix?")) + (body (en "Don't miss the @@code@{hello@} package!")))) +@end lisp -@example -$ wget -O - \ - https://@value{SUBSTITUTE-SERVER}/nar/gzip/@dots{}-emacs-24.5 \ - | gunzip | guix archive -x /tmp/emacs -@end example +While the news file is using the Scheme syntax, avoid naming it with a +@file{.scm} extension or else it will get picked up when building the +channel and yield an error since it is not a valid module. +Alternatively, you can move the channel module to a subdirectory and +store the news file in another directory. -Single-item archives are different from multiple-item archives produced -by @command{guix archive --export}; they contain a single store item, -and they do @emph{not} embed a signature. Thus this operation does -@emph{no} signature verification and its output should be considered -unsafe. +The file consists of a list of @dfn{news entries}. Each entry is +associated with a commit or tag: it describes changes made in this +commit, possibly in preceding commits as well. Users see entries only +the first time they obtain the commit the entry refers to. -The primary purpose of this operation is to facilitate inspection of -archive contents coming from possibly untrusted substitute servers -(@pxref{Invoking guix challenge}). +The @code{title} field should be a one-line summary while @code{body} +can be arbitrarily long, and both can contain Texinfo markup +(@pxref{Overview,,, texinfo, GNU Texinfo}). Both the title and body are +a list of language tag/message tuples, which allows @command{guix pull} +to display news in the language that corresponds to the user's locale. -@item --list -@itemx -t -Read a single-item archive as served by substitute servers -(@pxref{Substitutes}) and print the list of files it contains, as in -this example: +If you want to translate news using a gettext-based workflow, you can +extract translatable strings with @command{xgettext} (@pxref{xgettext +Invocation,,, gettext, GNU Gettext Utilities}). For example, assuming +you write news entries in English first, the command below creates a PO +file containing the strings to translate: @example -$ wget -O - \ - https://@value{SUBSTITUTE-SERVER}/nar/lzip/@dots{}-emacs-26.3 \ - | lzip -d | guix archive -t +xgettext -o news.po -l scheme -ken etc/news.txt @end example -@end table +To sum up, yes, you could use your channel as a blog. But beware, this +is @emph{not quite} what your users might expect. @c ********************************************************************* -- 2.28.0 From debbugs-submit-bounces@debbugs.gnu.org Sun Sep 27 16:38:25 2020 Received: (at 43482-done) by debbugs.gnu.org; 27 Sep 2020 20:38:25 +0000 Received: from localhost ([127.0.0.1]:50523 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kMdRB-0003hu-1W for submit@debbugs.gnu.org; Sun, 27 Sep 2020 16:38:25 -0400 Received: from eggs.gnu.org ([209.51.188.92]:38880) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kMdR7-0003hT-07 for 43482-done@debbugs.gnu.org; Sun, 27 Sep 2020 16:38:21 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:57043) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kMdR1-0006C4-Mn; Sun, 27 Sep 2020 16:38:15 -0400 Received: from [2a01:e0a:1d:7270:af76:b9b:ca24:c465] (port=43732 helo=ribbon) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1kMdR0-0003ap-BI; Sun, 27 Sep 2020 16:38:14 -0400 From: =?utf-8?Q?Ludovic_Court=C3=A8s?= To: zimoun Subject: Re: [bug#43482] [PATCH v2 1/2] doc: Update the master menu. References: <20200918013744.3448-1-zimon.toutoune@gmail.com> <20200925200055.8908-1-zimon.toutoune@gmail.com> Date: Sun, 27 Sep 2020 22:38:12 +0200 In-Reply-To: <20200925200055.8908-1-zimon.toutoune@gmail.com> (zimoun's message of "Fri, 25 Sep 2020 22:00:54 +0200") Message-ID: <871rinez0r.fsf@gnu.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 43482-done Cc: 43482-done@debbugs.gnu.org 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 (---) Hi, zimoun skribis: > * doc/guix.texi: Update the master menu. [...] > The sectioning becomes: > > 1. Specifying Additional Channels (was 3.) > 2. Using a Custom Guix Channel (was 2.) > 3. Replicating Guix (was 9.) > 4. Channel Authentication (was 1.) > 5. Primary URL (was 7.) > 6. Creating a Channel (reworded) > 7. Package Modules in a Sub-directory (was 5.) > 8. Declaring Channel Dependencies (was 4.) > 9. Specifying Channel Authorizations (was 6.) > 10. Writing Channel News (was 8.) > > * doc/guix.texi (Channels): Move section to chapter. > Reorder the chapter. > Minor tweaks to keep uniformity. > Update the master menu. Applied, thanks! Ludo=E2=80=99. From unknown Thu Aug 14 21:55:19 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Mon, 26 Oct 2020 11:24:09 +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