futurile/guix-play
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: Move "Package Modules" under "Programming Interface".

Browse Source 
* doc/guix.texi (Package Modules): Move to...
(Programming Interface): ... here.  Turn into a section.
This commit is contained in:
Ludovic Courtès 2019-01-21 11:35:52 +01:00
parent afe7408e19
commit ce6236f419
No known key found for this signature in database
GPG Key ID: 090B11993D9AEBB5
1 changed files with 64 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

128
doc/guix.texi
View File

@ -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{<package>} 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{<package>} 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