From patchwork Mon Jan 21 11:02:38 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: =?utf-8?q?Ludovic_Court=C3=A8s?= X-Patchwork-Id: 777 Return-Path: X-Original-To: patchwork@mira.cbaines.net Delivered-To: patchwork@mira.cbaines.net Received: by mira.cbaines.net (Postfix, from userid 113) id 58E6016A47; Mon, 21 Jan 2019 11:04:14 +0000 (GMT) X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on mira.cbaines.net X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00 autolearn=ham autolearn_force=no version=3.4.0 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mira.cbaines.net (Postfix) with ESMTP id D426216A40 for ; Mon, 21 Jan 2019 11:04:13 +0000 (GMT) Received: from localhost ([127.0.0.1]:51809 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1glXNF-0002Aw-Gf for patchwork@mira.cbaines.net; Mon, 21 Jan 2019 06:04:13 -0500 Received: from eggs.gnu.org ([209.51.188.92]:44838) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1glXN9-000290-W7 for guix-patches@gnu.org; Mon, 21 Jan 2019 06:04:10 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1glXN6-0003Iz-WD for guix-patches@gnu.org; Mon, 21 Jan 2019 06:04:06 -0500 Received: from debbugs.gnu.org ([209.51.188.43]:40204) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1glXN5-0003Ha-2A for guix-patches@gnu.org; Mon, 21 Jan 2019 06:04:04 -0500 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1glXN4-00087A-T0 for guix-patches@gnu.org; Mon, 21 Jan 2019 06:04:02 -0500 X-Loop: help-debbugs@gnu.org Subject: [bug#34156] [PATCH 4/4] doc: Move "Package Modules" under "Programming Interface". Resent-From: Ludovic =?utf-8?q?Court=C3=A8s?= Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Mon, 21 Jan 2019 11:04:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 34156 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 34156@debbugs.gnu.org Received: via spool by 34156-submit@debbugs.gnu.org id=B34156.154806858631112 (code B ref 34156); Mon, 21 Jan 2019 11:04:02 +0000 Received: (at 34156) by debbugs.gnu.org; 21 Jan 2019 11:03:06 +0000 Received: from localhost ([127.0.0.1]:39482 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1glXM9-00085h-FR for submit@debbugs.gnu.org; Mon, 21 Jan 2019 06:03:05 -0500 Received: from hera.aquilenet.fr ([185.233.100.1]:53342) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1glXM1-00084l-4L for 34156@debbugs.gnu.org; Mon, 21 Jan 2019 06:02:59 -0500 Received: from localhost (localhost [127.0.0.1]) by hera.aquilenet.fr (Postfix) with ESMTP id 90B74A4; Mon, 21 Jan 2019 12:02:56 +0100 (CET) X-Virus-Scanned: Debian amavisd-new at aquilenet.fr Received: from hera.aquilenet.fr ([127.0.0.1]) by localhost (hera.aquilenet.fr [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id jQ9hC-3MVjlx; Mon, 21 Jan 2019 12:02:55 +0100 (CET) Received: from gnu.org (unknown [IPv6:2001:660:6102:320:e120:2c8f:8909:cdfe]) by hera.aquilenet.fr (Postfix) with ESMTPSA id BB121400D; Mon, 21 Jan 2019 12:02:44 +0100 (CET) From: Ludovic =?utf-8?q?Court=C3=A8s?= Date: Mon, 21 Jan 2019 12:02:38 +0100 Message-Id: <20190121110238.15225-4-ludo@gnu.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190121110238.15225-1-ludo@gnu.org> References: <20190121110238.15225-1-ludo@gnu.org> MIME-Version: 1.0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org Sender: "Guix-patches" X-getmail-retrieved-from-mailbox: Patches * doc/guix.texi (Package Modules): Move to... (Programming Interface): ... here. Turn into a section. --- doc/guix.texi | 128 +++++++++++++++++++++++++------------------------- 1 file changed, 64 insertions(+), 64 deletions(-) diff --git a/doc/guix.texi b/doc/guix.texi index add06ec8af..251fd9b8ec 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -125,7 +125,6 @@ Project}. * Documentation:: Browsing software user manuals. * Installing Debugging Files:: Feeding the debugger. * Security Updates:: Deploying security fixes quickly. -* Package Modules:: Packages from the programmer's viewpoint. * Bootstrapping:: GNU/Linux built from scratch. * Porting:: Targeting another platform or kernel. * Contributing:: Your help needed! @@ -188,6 +187,7 @@ Substitutes Programming Interface +* Package Modules:: Packages from the programmer's viewpoint. * Defining Packages:: Defining new packages. * Build Systems:: Specifying how packages are built. * The Store:: Manipulating the package store. @@ -4437,6 +4437,7 @@ This chapter describes all these APIs in turn, starting from high-level package definitions. @menu +* Package Modules:: Packages from the programmer's viewpoint. * Defining Packages:: Defining new packages. * Build Systems:: Specifying how packages are built. * The Store:: Manipulating the package store. @@ -4446,6 +4447,68 @@ package definitions. * Invoking guix repl:: Fiddling with Guix interactively. @end menu +@node Package Modules +@section Package Modules + +From a programming viewpoint, the package definitions of the +GNU distribution are provided by Guile modules in the @code{(gnu packages +@dots{})} name space@footnote{Note that packages under the @code{(gnu +packages @dots{})} module name space are not necessarily ``GNU +packages''. This module naming scheme follows the usual Guile module +naming convention: @code{gnu} means that these modules are distributed +as part of the GNU system, and @code{packages} identifies modules that +define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile +Reference Manual}). For instance, the @code{(gnu packages emacs)} +module exports a variable named @code{emacs}, which is bound to a +@code{} object (@pxref{Defining Packages}). + +The @code{(gnu packages @dots{})} module name space is +automatically scanned for packages by the command-line tools. For +instance, when running @code{guix package -i emacs}, all the @code{(gnu +packages @dots{})} modules are scanned until one that exports a package +object whose name is @code{emacs} is found. This package search +facility is implemented in the @code{(gnu packages)} module. + +@cindex customization, of packages +@cindex package module search path +Users can store package definitions in modules with different +names---e.g., @code{(my-packages emacs)}@footnote{Note that the file +name and module name must match. For instance, the @code{(my-packages +emacs)} module must be stored in a @file{my-packages/emacs.scm} file +relative to the load path specified with @option{--load-path} or +@code{GUIX_PACKAGE_PATH}. @xref{Modules and the File System,,, +guile, GNU Guile Reference Manual}, for details.}. There are two ways to make +these package definitions visible to the user interfaces: + +@enumerate +@item +By adding the directory containing your package modules to the search path +with the @code{-L} flag of @command{guix package} and other commands +(@pxref{Common Build Options}), or by setting the @code{GUIX_PACKAGE_PATH} +environment variable described below. + +@item +By defining a @dfn{channel} and configuring @command{guix pull} so that it +pulls from it. A channel is essentially a Git repository containing package +modules. @xref{Channels}, for more information on how to define and use +channels. +@end enumerate + +@code{GUIX_PACKAGE_PATH} works similarly to other search path variables: + +@defvr {Environment Variable} GUIX_PACKAGE_PATH +This is a colon-separated list of directories to search for additional +package modules. Directories listed in this variable take precedence +over the own modules of the distribution. +@end defvr + +The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}: +each package is built based solely on other packages in the +distribution. The root of this dependency graph is a small set of +@dfn{bootstrap binaries}, provided by the @code{(gnu packages +bootstrap)} module. For more information on bootstrapping, +@pxref{Bootstrapping}. + @node Defining Packages @section Defining Packages @@ -24106,69 +24169,6 @@ lsof | grep /gnu/store/.*bash @end example -@node Package Modules -@chapter Package Modules - -From a programming viewpoint, the package definitions of the -GNU distribution are provided by Guile modules in the @code{(gnu packages -@dots{})} name space@footnote{Note that packages under the @code{(gnu -packages @dots{})} module name space are not necessarily ``GNU -packages''. This module naming scheme follows the usual Guile module -naming convention: @code{gnu} means that these modules are distributed -as part of the GNU system, and @code{packages} identifies modules that -define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile -Reference Manual}). For instance, the @code{(gnu packages emacs)} -module exports a variable named @code{emacs}, which is bound to a -@code{} object (@pxref{Defining Packages}). - -The @code{(gnu packages @dots{})} module name space is -automatically scanned for packages by the command-line tools. For -instance, when running @code{guix package -i emacs}, all the @code{(gnu -packages @dots{})} modules are scanned until one that exports a package -object whose name is @code{emacs} is found. This package search -facility is implemented in the @code{(gnu packages)} module. - -@cindex customization, of packages -@cindex package module search path -Users can store package definitions in modules with different -names---e.g., @code{(my-packages emacs)}@footnote{Note that the file -name and module name must match. For instance, the @code{(my-packages -emacs)} module must be stored in a @file{my-packages/emacs.scm} file -relative to the load path specified with @option{--load-path} or -@code{GUIX_PACKAGE_PATH}. @xref{Modules and the File System,,, -guile, GNU Guile Reference Manual}, for details.}. There are two ways to make -these package definitions visible to the user interfaces: - -@enumerate -@item -By adding the directory containing your package modules to the search path -with the @code{-L} flag of @command{guix package} and other commands -(@pxref{Common Build Options}), or by setting the @code{GUIX_PACKAGE_PATH} -environment variable described below. - -@item -By defining a @dfn{channel} and configuring @command{guix pull} so that it -pulls from it. A channel is essentially a Git repository containing package -modules. @xref{Channels}, for more information on how to define and use -channels. -@end enumerate - -@code{GUIX_PACKAGE_PATH} works similarly to other search path variables: - -@defvr {Environment Variable} GUIX_PACKAGE_PATH -This is a colon-separated list of directories to search for additional -package modules. Directories listed in this variable take precedence -over the own modules of the distribution. -@end defvr - -The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}: -each package is built based solely on other packages in the -distribution. The root of this dependency graph is a small set of -@dfn{bootstrap binaries}, provided by the @code{(gnu packages -bootstrap)} module. For more information on bootstrapping, -@pxref{Bootstrapping}. - - @node Bootstrapping @chapter Bootstrapping