Managing the operating system configuration.
@end direntry
+@dircategory Software development
+@direntry
+* guix environment: (guix)Invoking guix environment
+ Building development environments with Guix.
+@end direntry
+
@titlepage
@title GNU Guix Reference Manual
@subtitle Using the GNU Guix Functional Package Manager
* GNU Free Documentation License:: The license of this manual.
* Concept Index:: Concepts.
* Programming Index:: Data types, functions, and variables.
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Installation
+
+* Requirements:: Software needed to build and run Guix.
+* Setting Up the Daemon:: Preparing the build daemon's environment.
+* Invoking guix-daemon:: Running the build daemon.
+
+Setting Up the Daemon
+
+* Build Environment Setup:: Preparing the isolated build environment.
+* Daemon Offload Setup:: Offloading builds to remote machines.
+
+Package Management
+
+* Features:: How Guix will make your life brighter.
+* Invoking guix package:: Package installation, removal, etc.
+* Emacs Interface:: Package management from Emacs.
+* Substitutes:: Downloading pre-built binaries.
+* 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.
+* Invoking guix archive:: Exporting and importing store files.
+
+Programming Interface
+
+* Defining Packages:: Defining new packages.
+* Build Systems:: Specifying how packages are built.
+* The Store:: Manipulating the package store.
+* Derivations:: Low-level interface to package derivations.
+* The Store Monad:: Purely functional interface to the store.
+* G-Expressions:: Manipulating build expressions.
+
+Utilities
+
+* Invoking guix build:: Building packages from the command line.
+* Invoking guix download:: Downloading a file and printing its hash.
+* Invoking guix hash:: Computing the cryptographic hash of a file.
+* Invoking guix import:: Importing package definitions.
+* Invoking guix refresh:: Updating package definitions.
+* Invoking guix lint:: Finding errors in package definitions.
+* Invoking guix environment:: Setting up development environments.
+
+GNU Distribution
+
+* System Installation:: Installing the whole operating system.
+* System Configuration:: Configuring a GNU system.
+* Installing Debugging Files:: Feeding the debugger.
+* Security Updates:: Deploying security fixes quickly.
+* Package Modules:: Packages from the programmer's viewpoint.
+* Packaging Guidelines:: Growing the distribution.
+* Bootstrapping:: GNU/Linux built from scratch.
+* Porting:: Targeting another platform or kernel.
+
+System Configuration
+
+* Using the Configuration System:: Customizing your GNU system.
+* operating-system Reference:: Detail of operating-system declarations.
+* File Systems:: Configuring file system mounts.
+* Mapped Devices:: Block device extra processing.
+* User Accounts:: Specifying user accounts.
+* Locales:: Language and cultural convention settings.
+* Services:: Specifying system services.
+* Setuid Programs:: Programs running with root privileges.
+* Initial RAM Disk:: Linux-Libre bootstrapping.
+* GRUB Configuration:: Configuring the boot loader.
+* Invoking guix system:: Instantiating a system configuration.
+* Defining Services:: Adding new service definitions.
+
+Services
+
+* Base Services:: Essential system services.
+* Networking Services:: Network setup, SSH daemon, etc.
+* X Window:: Graphical display.
+
+Packaging Guidelines
+
+* Software Freedom:: What may go into the distribution.
+* Package Naming:: What's in a name?
+* Version Numbers:: When the name is not enough.
+* Python Modules:: Taming the snake.
+* Perl Modules:: Little pearls.
+* Fonts:: Fond of fonts.
+
+@end detailmenu
@end menu
@c *********************************************************************
@itemize
@item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.0.5 or later;
-@item @url{http://gnupg.org/, GNU libgcrypt}
+@item @url{http://gnupg.org/, GNU libgcrypt};
+@end itemize
+
+The following dependencies are optional:
+
+@itemize
+@item
+Installing
+@url{http://savannah.nongnu.org/projects/guile-json/, Guile-JSON} will
+allow you to use the @command{guix import pypi} command (@pxref{Invoking
+guix import}). It is of
+interest primarily for developers and not for casual users.
+@item
+Installing @uref{http://gnutls.org/, GnuTLS-Guile} will
+allow you to access @code{https} URLs with the @command{guix download}
+command (@pxref{Invoking guix download}) and the @command{guix import
+pypi} command. This is primarily of interest to developers.
+@xref{Guile Preparations, how to install the GnuTLS bindings for Guile,,
+gnutls-guile, GnuTLS-Guile}.
@end itemize
Unless @code{--disable-daemon} was passed to @command{configure}, the
shows a fixed list of build machines, one could imagine, say, using
DNS-SD to return a list of potential build machines discovered in the
local network (@pxref{Introduction, Guile-Avahi,, guile-avahi, Using
-Avahi in Guile Scheme Programs}).
+Avahi in Guile Scheme Programs}). The @code{build-machine} data type is
+detailed below.
-The compulsory fields for a @code{build-machine} declaration are:
+@deftp {Data Type} build-machine
+This data type represents build machines the daemon may offload builds
+to. The important fields are:
@table @code
The remote machine's host name.
@item system
-The remote machine's system type.
+The remote machine's system type---e.g., @code{"x86_64-linux"}.
@item user
The user account to use when connecting to the remote machine over SSH.
@end table
-@noindent
A number of optional fields may be specified:
@table @code
name, and they will be scheduled on matching build machines.
@end table
+@end deftp
The @code{guix} command must be in the search path on the build
machines, since offloading works by invoking the @code{guix archive} and
@end example
@noindent
-For details on how to set it up, @ref{Setting Up the Daemon}.
+For details on how to set it up, @pxref{Setting Up the Daemon}.
@cindex chroot
@cindex container, build environment
explicitly enable substitution @i{via} the @code{set-build-options}
remote procedure call (@pxref{The Store}).
+@item --substitute-urls=@var{urls}
+Consider @var{urls} the default whitespace-separated list of substitute
+source URLs. When this option is omitted, @code{http://hydra.gnu.org}
+is used.
+
+This means that substitutes may be downloaded from @var{urls}, as long
+as they are signed by a trusted signature (@pxref{Substitutes}).
+
@cindex build hook
@item --no-build-hook
Do not use the @dfn{build hook}.
@item --max-jobs=@var{n}
@itemx -M @var{n}
Allow at most @var{n} build jobs in parallel. The default value is
-@code{1}.
+@code{1}. Setting it to @code{0} means that no builds will be performed
+locally; instead, the daemon will offload builds (@pxref{Daemon Offload
+Setup}), or simply fail.
@item --debug
Produce debugging output.
features.
This chapter describes the main features of Guix, as well as the package
-management tools it provides.
+management tools it provides. Two user interfaces are provided for
+routine package management tasks: a command-line interface
+(@pxref{Invoking guix package, @code{guix package}}), and a visual user
+interface in Emacs (@pxref{Emacs Interface}).
@menu
* Features:: How Guix will make your life brighter.
When using Guix, each package ends up in the @dfn{package store}, in its
own directory---something that resembles
-@file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string.
+@file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string
+(note that Guix comes with an Emacs extension to shorten those file
+names, @pxref{Emacs Prettify}.)
Instead of referring to these directories, users have their own
@dfn{profile}, which points to the packages that they actually want to
otherwise, it builds the package from source, locally
(@pxref{Substitutes}).
+Control over the build environment is a feature that is also useful for
+developers. The @command{guix environment} command allows developers of
+a package to quickly set up the right development environment for their
+package, without having to manually install the package's dependencies
+in their profile (@pxref{Invoking guix environment}).
+
@node Invoking guix package
@section Invoking @command{guix package}
been rolled back to overwrites previous future generations. Thus, the
history of a profile's generations is always linear.
+@item --switch-generation=@var{pattern}
+@itemx -S @var{pattern}
+Switch to a particular generation defined by @var{pattern}.
+
+@var{pattern} may be either a generation number or a number prefixed
+with ``+'' or ``-''. The latter means: move forward/backward by a
+specified number of generations. For example, if you want to return to
+the latest generation after @code{--roll-back}, use
+@code{--switch-generation=+1}.
+
+The difference between @code{--roll-back} and
+@code{--switch-generation=-1} is that @code{--switch-generation} will
+not make a zeroth generation, so if a specified generation does not
+exist, the current generation will not be changed.
+
@item --search-paths
@cindex search paths
Report environment variable definitions, in Bash syntax, that may be
The @code{hydra.gnu.org} server is a front-end to a build farm that
builds packages from the GNU distribution continuously for some
-architectures, and makes them available as substitutes.
+architectures, and makes them available as substitutes. This is the
+default source of substitutes; it can be overridden by passing
+@command{guix-daemon} the @code{--substitute-urls} option
+(@pxref{Invoking guix-daemon}).
@cindex security
@cindex digital signatures
When @var{min} is given, stop once @var{min} bytes have been collected.
@var{min} may be a number of bytes, or it may include a unit as a
-suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes.
+suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes
+(@pxref{Block size, size specifications,, coreutils, GNU Coreutils}).
When @var{min} is omitted, collect all the garbage.
#:use-module (guix build-system gnu)
#:use-module (guix licenses))
-(define hello
+(define-public hello
(package
(name "hello")
(version "2.8")
@code{(guix packages)} module; for instance, @code{(package-name hello)}
returns---surprise!---@code{"hello"}.
+With luck, you may be able to import part or all of the definition of
+the package you are interested in from another repository, using the
+@code{guix import} command (@pxref{Invoking guix import}).
+
In the example above, @var{hello} is defined into a module of its own,
@code{(gnu packages hello)}. Technically, this is not strictly
necessary, but it is convenient to do so: all the packages defined in
unavailable to the build process, possibly leading to a build failure.
@end itemize
-Once a package definition is in place@footnote{Simple package
-definitions like the one above may be automatically converted from the
-Nixpkgs distribution using the @command{guix import} command.}, the
+Once a package definition is in place, the
package may actually be built using the @code{guix build} command-line
tool (@pxref{Invoking guix build}). @xref{Packaging Guidelines}, for
more information on how to test package definitions, and
@ref{Invoking guix lint}, for information on how to check a definition
for style conformance.
-
Eventually, updating the package definition to a new upstream version
can be partly automated by the @command{guix refresh} command
(@pxref{Invoking guix refresh}).
create and manipulate them is provided by the @code{(guix build-system)}
module, and actual build systems are exported by specific modules.
+@cindex bag (low-level package representation)
+Under the hood, build systems first compile package objects to
+@dfn{bags}. A @dfn{bag} is like a package, but with less
+ornamentation---in other words, a bag is a lower-level representation of
+a package, which includes all the inputs of that package, including some
+that were implicitly added by the build system. This intermediate
+representation is then compiled to a derivation (@pxref{Derivations}).
+
Build systems accept an optional list of @dfn{arguments}. In package
definitions, these are passed @i{via} the @code{arguments} field
(@pxref{Defining Packages}). They are typically keyword arguments
It automatically adds the @code{cmake} package to the set of inputs.
Which package is used can be specified with the @code{#:cmake}
parameter.
+
+The @code{#:configure-flags} parameter is taken as a list of flags
+passed to the @command{cmake} command. The @code{#:build-type}
+parameter specifies in abstract terms the flags passed to the compiler;
+it defaults to @code{"RelWithDebInfo"} (short for ``release mode with
+debugging information''), which roughly means that code is compiled with
+@code{-O2 -g}, as is the case for Autoconf-based packages by default.
+@end defvr
+
+@defvr {Scheme Variable} glib-or-gtk-build-system
+This variable is exported by @code{(guix build-system glib-or-gtk)}. It
+is intended for use with packages making use of GLib or GTK+.
+
+This build system adds the following two phases to the ones defined by
+@var{gnu-build-system}:
+
+@table @code
+@item glib-or-gtk-wrap
+The phase @code{glib-or-gtk-wrap} ensures that programs found under
+@file{bin/} are able to find GLib's ``schemas'' and
+@uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, GTK+
+modules}. This is achieved by wrapping the programs in launch scripts
+that appropriately set the @code{XDG_DATA_DIRS} and @code{GTK_PATH}
+environment variables.
+
+@item glib-or-gtk-compile-schemas
+The phase @code{glib-or-gtk-compile-schemas} makes sure that all GLib's
+@uref{https://developer.gnome.org/gio/stable/glib-compile-schemas.html,
+GSettings schemas} are compiled. Compilation is performed by the
+@command{glib-compile-schemas} program. It is provided by the package
+@code{glib:bin} which is automatically imported by the build system.
+The @code{glib} package providing @command{glib-compile-schemas} can be
+specified with the @code{#:glib} parameter.
+@end table
+
+Both phases are executed after the @code{install} phase.
@end defvr
@defvr {Scheme Variable} python-build-system
Which Perl package is used can be specified with @code{#:perl}.
@end defvr
+@defvr {Scheme Variable} ruby-build-system
+This variable is exported by @code{(guix build-system ruby)}. It
+implements the RubyGems build procedure used by Ruby packages, which
+involves running @code{gem build} followed by @code{gem install}.
+
+Which Ruby package is used can be specified with the @code{#:ruby}
+parameter.
+@end defvr
Lastly, for packages that do not need anything as sophisticated, a
``trivial'' build system is provided. It is trivial in the sense that
(@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
@end deffn
+@deffn {Scheme System} mbegin @var{monad} @var{mexp} ...
+Bind @var{mexp} and the following monadic expressions in sequence,
+returning the result of the last expression.
+
+This is akin to @code{mlet}, except that the return values of the
+monadic expressions are ignored. In that sense, it is analogous to
+@code{begin}, but applied to monadic expressions.
+@end deffn
+
The interface to the store monad provided by @code{(guix monads)} is as
follows.
[#:system (%current-system)] [#:target #f] [#:inputs '()] @
[#:hash #f] [#:hash-algo #f] @
[#:recursive? #f] [#:env-vars '()] [#:modules '()] @
+ [#:module-path @var{%load-path}] @
[#:references-graphs #f] [#:local-build? #f] @
[#:guile-for-build #f]
Return a derivation @var{name} that runs @var{exp} (a gexp) with
referred to by @var{exp}.
Make @var{modules} available in the evaluation context of @var{EXP};
-@var{MODULES} is a list of names of Guile modules from the current
-search path to be copied in the store, compiled, and made available in
+@var{MODULES} is a list of names of Guile modules searched in
+@var{MODULE-PATH} to be copied in the store, compiled, and made available in
the load path during the execution of @var{exp}---e.g., @code{((guix
build utils) (guix build gnu-build-system))}.
* Invoking guix build:: Building packages from the command line.
* Invoking guix download:: Downloading a file and printing its hash.
* Invoking guix hash:: Computing the cryptographic hash of a file.
+* Invoking guix import:: Importing package definitions.
* Invoking guix refresh:: Updating package definitions.
* Invoking guix lint:: Finding errors in package definitions.
+* Invoking guix environment:: Setting up development environments.
@end menu
@node Invoking guix build
guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz
@end example
+@item --no-grafts
+Do not ``graft'' packages. In practice, this means that package updates
+available as grafts are not applied. @xref{Security Updates}, for more
+information on grafts.
@item --derivations
@itemx -d
@table @code
+@item --load-path=@var{directory}
+@itemx -L @var{directory}
+Add @var{directory} to the front of the package module search path
+(@pxref{Package Modules}).
+
+This allows users to define their own packages and make them visible to
+the command-line tools.
+
@item --keep-failed
@itemx -K
Keep the build tree of failed builds. Thus, if a build fail, its build
Allow the use of up to @var{n} CPU cores for the build. The special
value @code{0} means to use as many CPU cores as available.
+@item --max-jobs=@var{n}
+@itemx -M @var{n}
+Allow at most @var{n} build jobs in parallel. @xref{Invoking
+guix-daemon, @code{--max-jobs}}, for details about this option and the
+equivalent @command{guix-daemon} option.
+
@end table
Behind the scenes, @command{guix build} is essentially an interface to
package definitions. In particular, it supports @code{mirror://} URIs.
@code{https} URIs (HTTP over TLS) are supported @emph{provided} the
Guile bindings for GnuTLS are available in the user's environment; when
-they are not available, an error is raised.
+they are not available, an error is raised. @xref{Guile Preparations,
+how to install the GnuTLS bindings for Guile,, gnutls-guile,
+GnuTLS-Guile}, for more information.
The following option is available:
@item --format=@var{fmt}
@itemx -f @var{fmt}
Write the hash in the format specified by @var{fmt}. For more
-information on the valid values for @var{fmt}, @ref{Invoking guix hash}.
+information on the valid values for @var{fmt}, @pxref{Invoking guix hash}.
@end table
@node Invoking guix hash
@end table
+@node Invoking guix import
+@section Invoking @command{guix import}
+
+@cindex importing packages
+@cindex package import
+@cindex package conversion
+The @command{guix import} command is useful for people willing to add a
+package to the distribution but who'd rather do as little work as
+possible to get there---a legitimate demand. The command knows of a few
+repositories from which it can ``import'' package meta-data. The result
+is a package definition, or a template thereof, in the format we know
+(@pxref{Defining Packages}).
+
+The general syntax is:
+
+@example
+guix import @var{importer} @var{options}@dots{}
+@end example
+
+@var{importer} specifies the source from which to import package
+meta-data, and @var{options} specifies a package identifier and other
+options specific to @var{importer}. Currently, the available
+``importers'' are:
+
+@table @code
+@item gnu
+Import meta-data for the given GNU package. This provides a template
+for the latest version of that GNU package, including the hash of its
+source tarball, and its canonical synopsis and description.
+
+Additional information such as the package's dependencies and its
+license needs to be figured out manually.
+
+For example, the following command returns a package definition for
+GNU@tie{}Hello:
+
+@example
+guix import gnu hello
+@end example
+
+Specific command-line options are:
+
+@table @code
+@item --key-download=@var{policy}
+As for @code{guix refresh}, specify the policy to handle missing OpenPGP
+keys when verifying the package's signature. @xref{Invoking guix
+refresh, @code{--key-download}}.
+@end table
+
+@item pypi
+@cindex pypi
+Import meta-data from the @uref{https://pypi.python.org/, Python Package
+Index}@footnote{This functionality requires Guile-JSON to be installed.
+@xref{Requirements}.}. Information is taken from the JSON-formatted
+description available at @code{pypi.python.org} and usually includes all
+the relevant information, including package dependencies.
+
+The command below imports meta-data for the @code{itsdangerous} Python
+package:
+
+@example
+guix import pypi itsdangerous
+@end example
+
+@item nix
+Import meta-data from a local copy of the source of the
+@uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This
+relies on the @command{nix-instantiate} command of
+@uref{http://nixos.org/nix/, Nix}.}. Package definitions in Nixpkgs are
+typically written in a mixture of Nix-language and Bash code. This
+command only imports the high-level package structure that is written in
+the Nix language. It normally includes all the basic fields of a
+package definition.
+
+When importing a GNU package, the synopsis and descriptions are replaced
+by their canonical upstream variant.
+
+As an example, the command below imports the package definition of
+LibreOffice (more precisely, it imports the definition of the package
+bound to the @code{libreoffice} top-level attribute):
+
+@example
+guix import nix ~/path/to/nixpkgs libreoffice
+@end example
+@end table
+
+The structure of the @command{guix import} code is modular. It would be
+useful to have more importers for other package formats, and your help
+is welcome here (@pxref{Contributing}).
+
@node Invoking guix refresh
@section Invoking @command{guix refresh}
@item --update
@itemx -u
Update distribution source files (package recipes) in place.
-@ref{Defining Packages}, for more information on package definitions.
+@xref{Defining Packages}, for more information on package definitions.
@item --select=[@var{subset}]
@itemx -s @var{subset}
@table @code
-@item --key-server=@var{host}
-Use @var{host} as the OpenPGP key server when importing a public key.
-
@item --gpg=@var{command}
Use @var{command} as the GnuPG 2.x command. @var{command} is searched
for in @code{$PATH}.
+@item --key-download=@var{policy}
+Handle missing OpenPGP keys according to @var{policy}, which may be one
+of:
+
+@table @code
+@item always
+Always download missing OpenPGP keys from the key server, and add them
+to the user's GnuPG keyring.
+
+@item never
+Never try to download missing OpenPGP keys. Instead just bail out.
+
+@item interactive
+When a package signed with an unknown OpenPGP key is encountered, ask
+the user whether to download it or not. This is the default behavior.
+@end table
+
+@item --key-server=@var{host}
+Use @var{host} as the OpenPGP key server when importing a public key.
+
@end table
@node Invoking guix lint
@table @code
+@item --checkers
+@itemx -c
+Only enable the checkers specified in a comma-separated list using the
+names returned by @code{--list-checkers}.
+
@item --list-checkers
@itemx -l
List and describe all the available checkers that will be run on packages
@end table
+@node Invoking guix environment
+@section Invoking @command{guix environment}
+
+@cindex reproducible build environments
+The purpose of @command{guix environment} is to assist hackers in
+creating reproducible development environments without polluting their
+package profile. The @command{guix environment} tool takes one or more
+packages, builds all of the necessary inputs, and creates a shell
+environment to use them.
+
+The general syntax is:
+
+@example
+guix environment @var{options} @var{package}@dots{}
+@end example
+
+The following examples spawns a new shell that is capable of building
+the GNU Guile source code:
+
+@example
+guix environment guile
+@end example
+
+If the specified packages are not built yet, @command{guix environment}
+automatically builds them. The new shell's environment is an augmented
+version of the environment that @command{guix environment} was run in.
+It contains the necessary search paths for building the given package
+added to the existing environment variables. To create a ``pure''
+environment in which the original environment variables have been unset,
+use the @code{--pure} option.
+
+Additionally, more than one package may be specified, in which case the
+union of the inputs for the given packages are used. For example, the
+command below spawns a shell where all of the dependencies of both Guile
+and Emacs are available:
+
+@example
+guix environment guile emacs
+@end example
+
+Sometimes an interactive shell session is not desired. The
+@code{--exec} option can be used to specify the command to run instead.
+
+@example
+guix environment guile --exec=make
+@end example
+
+The following options are available:
+
+@table @code
+@item --expression=@var{expr}
+@itemx -e @var{expr}
+Create an environment for the package that @var{expr} evaluates to.
+
+@item --load=@var{file}
+@itemx -l @var{file}
+Create an environment for the package that the code within @var{file}
+evaluates to.
+
+@item --exec=@var{command}
+@item -E @var{command}
+Execute @var{command} in the new environment.
+
+@item --pure
+Unset existing environment variables when building the new environment.
+This has the effect of creating an environment in which search paths
+only contain package inputs.
+
+@item --search-paths
+Display the environment variable definitions that make up the
+environment.
+@end table
+
+It also supports all of the common build options that @command{guix
+build} supports (@pxref{Invoking guix build, common build options}).
+
@c *********************************************************************
@node GNU Distribution
@chapter GNU Distribution
* System Installation:: Installing the whole operating system.
* System Configuration:: Configuring a GNU system.
* Installing Debugging Files:: Feeding the debugger.
+* Security Updates:: Deploying security fixes quickly.
* Package Modules:: Packages from the programmer's viewpoint.
* Packaging Guidelines:: Growing the distribution.
* Bootstrapping:: GNU/Linux built from scratch.
@end menu
Building this distribution is a cooperative effort, and you are invited
-to join! @ref{Contributing}, for information about how you can help.
+to join! @xref{Contributing}, for information about how you can help.
@node System Installation
@section System Installation
@command{mkfs.ext4} and related commands.
The installation image includes Parted (@pxref{Overview,,, parted, GNU
-Parted User Manual}), @command{fdisk}, and e2fsprogs, the suite of tools
-to manipulate ext2/ext3/ext4 file systems.
+Parted User Manual}), @command{fdisk}, Cryptsetup/LUKS for disk
+encryption, and e2fsprogs, the suite of tools to manipulate
+ext2/ext3/ext4 file systems.
@item
Once that is done, mount the target root partition under @file{/mnt}.
@menu
* Using the Configuration System:: Customizing your GNU system.
+* operating-system Reference:: Detail of operating-system declarations.
* File Systems:: Configuring file system mounts.
* Mapped Devices:: Block device extra processing.
* User Accounts:: Specifying user accounts.
+* Locales:: Language and cultural convention settings.
* Services:: Specifying system services.
* Setuid Programs:: Programs running with root privileges.
* Initial RAM Disk:: Linux-Libre bootstrapping.
+* GRUB Configuration:: Configuring the boot loader.
* Invoking guix system:: Instantiating a system configuration.
* Defining Services:: Adding new service definitions.
@end menu
(operating-system
(host-name "komputilo")
(timezone "Europe/Paris")
- (locale "fr_FR.UTF-8")
+ (locale "fr_FR.utf8")
(bootloader (grub-configuration
(device "/dev/sda")))
(file-systems (cons (file-system
%base-file-systems))
(users (list (user-account
(name "alice")
- (password "")
(uid 1000) (group 100)
(comment "Bob's sister")
(home-directory "/home/alice"))))
(packages (cons emacs %base-packages))
- (services (cons (lsh-service #:port 2222 #:allow-root-login? #t)
+ (services (cons (lsh-service #:port 2222 #:root-login? #t)
%base-services)))
@end lisp
(@pxref{Invoking lshd,,, lsh, GNU lsh Manual}). Under the hood,
@code{lsh-service} arranges so that @code{lshd} is started with the
right command-line options, possibly with supporting configuration files
-generated as needed (@pxref{Defining Services}).
+generated as needed (@pxref{Defining Services}). @xref{operating-system
+Reference}, for details about the available @code{operating-system}
+fields.
Assuming the above snippet is stored in the @file{my-system-config.scm}
file, the @command{guix system reconfigure my-system-config.scm} command
instantiate @var{os}.
@end deffn
+@node operating-system Reference
+@subsection @code{operating-system} Reference
+
+This section summarizes all the options available in
+@code{operating-system} declarations (@pxref{Using the Configuration
+System}).
+
+@deftp {Data Type} operating-system
+This is the data type representing an operating system configuration.
+By that, we mean all the global system configuration, not per-user
+configuration (@pxref{Using the Configuration System}).
+
+@table @asis
+@item @code{kernel} (default: @var{linux-libre})
+The package object of the operating system to use@footnote{Currently
+only the Linux-libre kernel is supported. In the future, it will be
+possible to use the GNU@tie{}Hurd.}.
+
+@item @code{bootloader}
+The system bootloader configuration object. @xref{GRUB Configuration}.
+
+@item @code{initrd} (default: @code{base-initrd})
+A two-argument monadic procedure that returns an initial RAM disk for
+the Linux kernel. @xref{Initial RAM Disk}.
+
+@item @code{firmware} (default: @var{%base-firmware})
+@cindex firmware
+List of firmware packages loadable by the operating system kernel.
+
+The default includes firmware needed for Atheros-based WiFi devices
+(Linux-libre module @code{ath9k}.)
+
+@item @code{host-name}
+The host name.
+
+@item @code{hosts-file}
+@cindex hosts file
+A zero-argument monadic procedure that returns a text file for use as
+@file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C Library
+Reference Manual}). The default is to produce a file with entries for
+@code{localhost} and @var{host-name}.
+
+@item @code{mapped-devices} (default: @code{'()})
+A list of mapped devices. @xref{Mapped Devices}.
+
+@item @code{file-systems}
+A list of file systems. @xref{File Systems}.
+
+@item @code{swap-devices} (default: @code{'()})
+@cindex swap devices
+A list of strings identifying devices to be used for ``swap space''
+(@pxref{Memory Concepts,,, libc, The GNU C Library Reference Manual}).
+For example, @code{'("/dev/sda3")}.
+
+@item @code{users} (default: @code{'()})
+@itemx @code{groups} (default: @var{%base-groups})
+List of user accounts and groups. @xref{User Accounts}.
+
+@item @code{skeletons} (default: @code{(default-skeletons)})
+A monadic list of pairs of target file name and files. These are the
+files that will be used as skeletons as new accounts are created.
+
+For instance, a valid value may look like this:
+
+@example
+(mlet %store-monad ((bashrc (text-file "bashrc" "\
+ export PATH=$HOME/.guix-profile/bin")))
+ (return `((".bashrc" ,bashrc))))
+@end example
+
+@item @code{issue} (default: @var{%default-issue})
+A string denoting the contents of the @file{/etc/issue} file, which is
+what displayed when users log in on a text console.
+
+@item @code{packages} (default: @var{%base-packages})
+The set of packages installed in the global profile, which is accessible
+at @file{/run/current-system/profile}.
+
+The default set includes core utilities, but it is good practice to
+install non-core utilities in user profiles (@pxref{Invoking guix
+package}).
+
+@item @code{timezone}
+A timezone identifying string---e.g., @code{"Europe/Paris"}.
+
+@item @code{locale} (default: @code{"en_US.utf8"})
+The name of the default locale (@pxref{Locale Names,,, libc, The GNU C
+Library Reference Manual}). @xref{Locales}, for more information.
+
+@item @code{locale-definitions} (default: @var{%default-locale-definitions})
+The list of locale definitions to be compiled and that may be used at
+run time. @xref{Locales}.
+
+@item @code{services} (default: @var{%base-services})
+A list of monadic values denoting system services. @xref{Services}.
+
+@item @code{pam-services} (default: @code{(base-pam-services)})
+@cindex PAM
+@cindex pluggable authentication modules
+Linux @dfn{pluggable authentication module} (PAM) services.
+@c FIXME: Add xref to PAM services section.
+
+@item @code{setuid-programs} (default: @var{%setuid-programs})
+List of string-valued G-expressions denoting setuid programs.
+@xref{Setuid Programs}.
+
+@item @code{sudoers} (default: @var{%sudoers-specification})
+@cindex sudoers
+The contents of the @file{/etc/sudoers} file as a string.
+
+This file specifies which users can use the @command{sudo} command, what
+they are allowed to do, and what privileges they may gain. The default
+is that only @code{root} and members of the @code{wheel} group may use
+@code{sudo}.
+
+@end table
+@end deftp
+
@node File Systems
@subsection File Systems
graphical login managers do not list them.
@item @code{password} (default: @code{#f})
-Unless @code{#f}, this is the password to be used for the account.
+You would normally leave this field to @code{#f}, initialize user
+passwords as @code{root} with the @command{passwd} command, and then let
+users change it with @command{passwd}.
+
+If you @emph{do} want to have a preset password for an account, then
+this field must contain the encrypted password, as a string.
+@xref{crypt,,, libc, The GNU C Library Reference Manual}, for more information
+on password encryption, and @ref{Encryption,,, guile, GNU Guile Reference
+Manual}, for information on Guile's @code{crypt} procedure.
@end table
@end deftp
specific devices such as ``audio'', ``disk'', and ``cdrom''.
@end defvr
+@node Locales
+@subsection Locales
+
+@cindex locale
+A @dfn{locale} defines cultural conventions for a particular language
+and region of the world (@pxref{Locales,,, libc, The GNU C Library
+Reference Manual}). Each locale has a name that typically has the form
+@code{@var{language}_@var{territory}.@var{charset}}---e.g.,
+@code{fr_LU.utf8} designates the locale for the French language, with
+cultural conventions from Luxembourg, and using the UTF-8 encoding.
+
+@cindex locale definition
+Usually, you will want to specify the default locale for the machine
+using the @code{locale} field of the @code{operating-system} declaration
+(@pxref{operating-system Reference, @code{locale}}).
+
+That locale must be among the @dfn{locale definitions} that are known to
+the system---and these are specified in the @code{locale-definitions}
+slot of @code{operating-system}. The default value includes locale
+definition for some widely used locales, but not for all the available
+locales, in order to save space.
+
+If the locale specified in the @code{locale} field is not among the
+definitions listed in @code{locale-definitions}, @command{guix system}
+raises an error. In that case, you should add the locale definition to
+the @code{locale-definitions} field. For instance, to add the North
+Frisian locale for Germany, the value of that field may be:
+
+@example
+(cons (locale-definition
+ (name "fy_DE.utf8") (source "fy_DE"))
+ %default-locale-definitions)
+@end example
+
+Likewise, to save space, one might want @code{locale-definitions} to
+list only the locales that are actually used, as in:
+
+@example
+(list (locale-definition
+ (name "ja_JP.eucjp") (source "ja_JP")
+ (charset "EUC-JP")))
+@end example
+
+The @code{locale-definition} form is provided by the @code{(gnu system
+locale)} module. Details are given below.
+
+@deftp {Data Type} locale-definition
+This is the data type of a locale definition.
+
+@table @asis
+
+@item @code{name}
+The name of the locale. @xref{Locale Names,,, libc, The GNU C Library
+Reference Manual}, for more information on locale names.
+
+@item @code{source}
+The name of the source for that locale. This is typically the
+@code{@var{language}_@var{territory}} part of the locale name.
+
+@item @code{charset} (default: @code{"UTF-8"})
+The ``character set'' or ``code set'' for that locale,
+@uref{http://www.iana.org/assignments/character-sets, as defined by
+IANA}.
+
+@end table
+@end deftp
+
+@defvr {Scheme Variable} %default-locale-definitions
+An arbitrary list of commonly used locales, used as the default value of
+the @code{locale-definitions} field of @code{operating-system}
+declarations.
+@end defvr
@node Services
@subsection Services
this:
@example
-(cons* (avahi-service) (lshd-service) %base-services)
+(cons* (avahi-service) (lsh-service) %base-services)
@end example
@end defvr
@node Networking Services
@subsubsection Networking Services
-The @code{(gnu system networking)} module provides services to configure
+The @code{(gnu services networking)} module provides services to configure
the network interface.
@cindex DHCP, networking service
gateway.
@end deffn
+@deffn {Monadic Procedure} ntp-service [#:ntp @var{ntp}] @
+ [#:name-service @var{%ntp-servers}]
+Return a service that runs the daemon from @var{ntp}, the
+@uref{http://www.ntp.org, Network Time Protocol package}. The daemon will
+keep the system clock synchronized with that of @var{servers}.
+@end deffn
+
+@defvr {Scheme Variable} %ntp-servers
+List of host names used as the default NTP servers.
+@end defvr
+
@deffn {Monadic Procedure} tor-service [#:tor tor]
Return a service to run the @uref{https://torproject.org,Tor} daemon.
policy) as the @code{tor} unprivileged user.
@end deffn
-In addition, @code{(gnu system ssh)} provides the following service.
+@deffn {Monadic Procedure} bitlbee-service [#:bitlbee bitlbee] @
+ [#:interface "127.0.0.1"] [#:port 6667] @
+ [#:extra-settings ""]
+Return a service that runs @url{http://bitlbee.org,BitlBee}, a daemon that
+acts as a gateway between IRC and chat networks.
+
+The daemon will listen to the interface corresponding to the IP address
+specified in @var{interface}, on @var{port}. @code{127.0.0.1} means that only
+local clients can connect, whereas @code{0.0.0.0} means that connections can
+come from any networking interface.
+
+In addition, @var{extra-settings} specifies a string to append to the
+configuration file.
+@end deffn
+
+Furthermore, @code{(gnu services ssh)} provides the following service.
@deffn {Monadic Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @
[#:interfaces '()] [#:port-number 22] @
upon service activation if they do not exist yet. This may take long and
require interaction.
+When @var{initialize?} is false, it is up to the user to initialize the
+randomness generator (@pxref{lsh-make-seed,,, lsh, LSH Manual}), and to create
+a key pair with the private key stored in file @var{host-key} (@pxref{lshd
+basics,,, lsh, LSH Manual}).
+
When @var{interfaces} is empty, lshd listens for connections on all the
network interfaces; otherwise, @var{interfaces} must be a list of host names
or addresses.
-@var{allow-empty-passwords?} specifies whether to accepts log-ins with empty
-passwords, and @var{root-login?} specifies whether to accepts log-ins as
+@var{allow-empty-passwords?} specifies whether to accept log-ins with empty
+passwords, and @var{root-login?} specifies whether to accept log-ins as
root.
The other options should be self-descriptive.
@end deffn
+@defvr {Scheme Variable} %facebook-host-aliases
+This variable contains a string for use in @file{/etc/hosts}
+(@pxref{Host Names,,, libc, The GNU C Library Reference Manual}). Each
+line contains a entry that maps a known server name of the Facebook
+on-line service---e.g., @code{www.facebook.com}---to the local
+host---@code{127.0.0.1} or its IPv6 equivalent, @code{::1}.
+
+This variable is typically used in the @code{hosts-file} field of an
+@code{operating-system} declaration (@pxref{operating-system Reference,
+@file{/etc/hosts}}):
+
+@example
+(use-modules (gnu) (guix))
+
+(operating-system
+ (host-name "mymachine")
+ ;; ...
+ (hosts-file
+ ;; Create a /etc/hosts file with aliases for "localhost"
+ ;; and "mymachine", as well as for Facebook servers.
+ (text-file "hosts"
+ (string-append (local-host-aliases host-name)
+ %facebook-host-aliases))))
+@end example
+
+This mechanism can prevent programs running locally, such as Web
+browsers, from accessing Facebook.
+@end defvr
+
@node X Window
@subsubsection X Window
started by the @dfn{login manager}, currently SLiM.
@deffn {Monadic Procedure} slim-service [#:allow-empty-passwords? #f] @
- [#:auto-login? #f] [#:default-user ""] [#:startx]
+ [#:auto-login? #f] [#:default-user ""] [#:startx] @
+ [#:theme @var{%default-slim-theme}] @
+ [#:theme-name @var{%default-slim-theme-name}]
Return a service that spawns the SLiM graphical login manager, which in
turn starts the X display server with @var{startx}, a command as returned by
@code{xorg-start-command}.
When @var{allow-empty-passwords?} is true, allow logins with an empty
password. When @var{auto-login?} is true, log in automatically as
@var{default-user}.
+
+If @var{theme} is @code{#f}, the use the default log-in theme; otherwise
+@var{theme} must be a gexp denoting the name of a directory containing the
+theme to use. In that case, @var{theme-name} specifies the name of the
+theme.
@end deffn
+@defvr {Scheme Variable} %default-theme
+@defvrx {Scheme Variable} %default-theme-name
+The G-Expression denoting the default SLiM theme and its name.
+@end defvr
+
+@deffn {Monadic Procedure} xorg-start-command [#:guile] @
+ [#:drivers '()] [#:resolutions '()] [#:xorg-server @var{xorg-server}]
+Return a derivation that builds a @var{guile} script to start the X server
+from @var{xorg-server}. Usually the X server is started by a login manager.
+
+@var{drivers} must be either the empty list, in which case Xorg chooses a
+graphics driver automatically, or a list of driver names that will be tried in
+this order---e.g., @code{("modesetting" "vesa")}.
+
+Likewise, when @var{resolutions} is the empty list, Xorg chooses an
+appropriate screen resolution; otherwise, it must be a list of
+resolutions---e.g., @code{((1024 768) (640 480))}.
+@end deffn
@node Setuid Programs
@subsection Setuid Programs
initrd.
@end deffn
+@node GRUB Configuration
+@subsection GRUB Configuration
+
+@cindex GRUB
+@cindex boot loader
+
+The operating system uses GNU@tie{}GRUB as its boot loader
+(@pxref{Overview, overview of GRUB,, grub, GNU GRUB Manual}). It is
+configured using @code{grub-configuration} declarations. This data type
+is exported by the @code{(gnu system grub)} module, and described below.
+
+@deftp {Data Type} grub-configuration
+The type of a GRUB configuration declaration.
+
+@table @asis
+
+@item @code{device}
+This is a string denoting the boot device. It must be a device name
+understood by the @command{grub-install} command, such as
+@code{/dev/sda} or @code{(hd0)} (@pxref{Invoking grub-install,,, grub,
+GNU GRUB Manual}).
+
+@item @code{menu-entries} (default: @code{()})
+A possibly empty list of @code{menu-entry} objects (see below), denoting
+entries to appear in the GRUB boot menu, in addition to the current
+system entry and the entry pointing to previous system generations.
+
+@item @code{default-entry} (default: @code{0})
+The index of the default boot menu entry. Index 0 is for the current
+system's entry.
+
+@item @code{timeout} (default: @code{5})
+The number of seconds to wait for keyboard input before booting. Set to
+0 to boot immediately, and to -1 to wait indefinitely.
+
+@item @code{theme} (default: @var{%default-theme})
+The @code{grub-theme} object describing the theme to use.
+@end table
+
+@end deftp
+
+Should you want to list additional boot menu entries @i{via} the
+@code{menu-entries} field above, you will need to create them with the
+@code{menu-entry} form:
+
+@deftp {Data Type} menu-entry
+The type of an entry in the GRUB boot menu.
+
+@table @asis
+
+@item @code{label}
+The label to show in the menu---e.g., @code{"GNU System"}.
+
+@item @code{linux}
+The Linux kernel to boot.
+
+@item @code{linux-arguments} (default: @code{()})
+The list of extra Linux kernel command-line arguments---e.g.,
+@code{("console=ttyS0")}.
+
+@item @code{initrd}
+A G-Expression or string denoting the file name of the initial RAM disk
+to use (@pxref{G-Expressions}).
+
+@end table
+@end deftp
+
+@c FIXME: Write documentation once it's stable.
+Themes are created using the @code{grub-theme} form, which is not
+documented yet.
+
+@defvr {Scheme Variable} %default-theme
+This is the default GRUB theme used by the operating system, with a
+fancy background image displaying the GNU and Guix logos.
+@end defvr
+
+
@node Invoking guix system
@subsection Invoking @code{guix system}
entries for older configurations to a submenu---unless
@option{--no-grub} is passed.
+@c The paragraph below refers to the problem discussed at
+@c <http://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>.
+It is highly recommended to run @command{guix pull} once before you run
+@command{guix system reconfigure} for the first time (@pxref{Invoking
+guix pull}). Failing to do that you would see an older version of Guix
+once @command{reconfigure} has completed.
+
@item build
Build the operating system's derivation, which includes all the
configuration files and programs needed to boot and run the system.
@item vm
@cindex virtual machine
+@cindex VM
Build a virtual machine that contain the operating system declared in
@var{file}, and return a script to run that virtual machine (VM).
+Arguments given to the script are passed as is to QEMU.
The VM shares its store with the host system.
+Additional file systems can be shared between the host and the VM using
+the @code{--share} and @code{--expose} command-line options: the former
+specifies a directory to be shared with write access, while the latter
+provides read-only access to the shared directory.
+
+The example below creates a VM in which the user's home directory is
+accessible read-only, and where the @file{/exchange} directory is a
+read-write mapping of the host's @file{$HOME/tmp}:
+
+@example
+guix system vm my-config.scm \
+ --expose=$HOME --share=$HOME/tmp=/exchange
+@end example
+
+On GNU/Linux, the default is to boot directly to the kernel; this has
+the advantage of requiring only a very tiny root disk image since the
+host's store can then be mounted.
+
+The @code{--full-boot} option forces a complete boot sequence, starting
+with the bootloader. This requires more disk space since a root image
+containing at least the kernel, initrd, and bootloader data files must
+be created. The @code{--image-size} option can be used to specify the
+image's size.
+
@item vm-image
@itemx disk-image
Return a virtual machine or disk image of the operating system declared
@item --image-size=@var{size}
For the @code{vm-image} and @code{disk-image} actions, create an image
of the given @var{size}. @var{size} may be a number of bytes, or it may
-include a unit as a suffix, such as @code{MiB} for mebibytes and
-@code{GB} for gigabytes.
+include a unit as a suffix (@pxref{Block size, size specifications,,
+coreutils, GNU Coreutils}).
@end table
Note that all the actions above, except @code{build} and @code{init},
@command{guix package --list-available} (@pxref{Invoking guix package}).
+@node Security Updates
+@section Security Updates
+
+@quotation Note
+As of version @value{VERSION}, the feature described in this section is
+experimental.
+@end quotation
+
+@cindex security updates
+Occasionally, important security vulnerabilities are discovered in core
+software packages and must be patched. Guix follows a functional
+package management discipline (@pxref{Introduction}), which implies
+that, when a package is changed, @emph{every package that depends on it}
+must be rebuilt. This can significantly slow down the deployment of
+fixes in core packages such as libc or Bash, since basically the whole
+distribution would need to be rebuilt. Using pre-built binaries helps
+(@pxref{Substitutes}), but deployment may still take more time than
+desired.
+
+@cindex grafts
+To address that, Guix implements @dfn{grafts}, a mechanism that allows
+for fast deployment of critical updates without the costs associated
+with a whole-distribution rebuild. The idea is to rebuild only the
+package that needs to be patched, and then to ``graft'' it onto packages
+explicitly installed by the user and that were previously referring to
+the original package. The cost of grafting is typically very low, and
+order of magnitudes lower than a full rebuild of the dependency chain.
+
+@cindex replacements of packages, for grafts
+For instance, suppose a security update needs to be applied to Bash.
+Guix developers will provide a package definition for the ``fixed''
+Bash, say @var{bash-fixed}, in the usual way (@pxref{Defining
+Packages}). Then, the original package definition is augmented with a
+@code{replacement} field pointing to the package containing the bug fix:
+
+@example
+(define bash
+ (package
+ (name "bash")
+ ;; @dots{}
+ (replacement bash-fixed)))
+@end example
+
+From there on, any package depending directly or indirectly on Bash that
+is installed will automatically be ``rewritten'' to refer to
+@var{bash-fixed} instead of @var{bash}. This grafting process takes
+time proportional to the size of the package, but expect less than a
+minute for an ``average'' package on a recent machine.
+
+Currently, the graft and the package it replaces (@var{bash-fixed} and
+@var{bash} in the example above) must have the exact same @code{name}
+and @code{version} fields. This restriction mostly comes from the fact
+that grafting works by patching files, including binary files, directly.
+Other restrictions may apply: for instance, when adding a graft to a
+package providing a shared library, the original shared library and its
+replacement must have the same @code{SONAME} and be binary-compatible.
+
+
@node Package Modules
@section Package Modules
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 special: it is
+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)}. In that case, commands such
-as @command{guix package} and @command{guix build} have to be used with
-the @code{-e} option so that they know where to find the package.
+names---e.g., @code{(my-packages emacs)}. These package definitions
+will not be visible by default. Thus, users can invoke commands such as
+@command{guix package} and @command{guix build} have to be used with the
+@code{-e} option so that they know where to find the package, or use the
+@code{-L} option of these commands to make those modules visible
+(@pxref{Invoking guix build, @code{--load-path}}), or define the
+@code{GUIX_PACKAGE_PATH} environment variable. This environment
+variable makes it easy to extend or customize the distribution and is
+honored by all the user interfaces.
+
+@defvr {Environment Variable} GUIX_PACKAGE_PATH
+This is a colon-separated list of directories to search for package
+modules. Directories listed in this variable take precedence over the
+distribution's own modules.
+@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,
-@ref{Bootstrapping}.
+@pxref{Bootstrapping}.
@node Packaging Guidelines
@section Packaging Guidelines
and export that variable from a module (@pxref{Package Modules}).
However, in-depth Scheme knowledge is @emph{not} a prerequisite for
creating packages. For more information on package definitions,
-@ref{Defining Packages}.
+@pxref{Defining Packages}.
Once a package definition is in place, stored in a file in the Guix
source tree, it can be tested using the @command{guix build} command
(@pxref{Contributing}). Well, if you need help, we will be happy to
help you too. Once the patch is committed in the Guix repository, the
new package automatically gets built on the supported platforms by
-@url{http://hydra.gnu.org/gnu/master, our continuous integration
+@url{http://hydra.gnu.org/jobset/gnu/master, our continuous integration
system}.
@cindex substituter
* Version Numbers:: When the name is not enough.
* Python Modules:: Taming the snake.
* Perl Modules:: Little pearls.
+* Fonts:: Fond of fonts.
@end menu
@node Software Freedom
SDL_net as @code{sdl-net}.
We do not add @code{lib} prefixes for library packages, unless these are
-already part of the official project name. But see @pxref{Python
+already part of the official project name. But @pxref{Python
Modules} and @ref{Perl Modules} for special rules concerning modules for
the Python and Perl languages.
+Font package names are handled differently, @pxref{Fonts}.
+
@node Version Numbers
@subsection Version Numbers
prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}.
+@node Fonts
+@subsection Fonts
+
+For fonts that are in general not installed by a user for typesetting
+purposes, or that are distributed as part of a larger software package,
+we rely on the general packaging rules for software; for instance, this
+applies to the fonts delivered as part of the X.Org system or fonts that
+are part of TeX Live.
+
+To make it easier for a user to search for fonts, names for other packages
+containing only fonts are constructed as follows, independently of the
+upstream package name.
+
+The name of a package containing only one font family starts with
+@code{font-}; it is followed by the foundry name and a dash @code{-}
+if the foundry is known, and the font family name, in which spaces are
+replaced by dashes (and as usual, all upper case letters are transformed
+to lower case).
+For example, the Gentium font family by SIL is packaged under the name
+@code{font-sil-gentium}.
+
+For a package containing several font families, the name of the collection
+is used in the place of the font family name.
+For instance, the Liberation fonts consist of three families,
+Liberation Sans, Liberation Serif and Liberation Mono.
+These could be packaged separately under the names
+@code{font-liberation-sans} and so on; but as they are distributed together
+under a common name, we prefer to package them together as
+@code{font-liberation}.
+
+In the case where several formats of the same font family or font collection
+are packaged separately, a short form of the format, prepended by a dash,
+is added to the package name. We use @code{-ttf} for TrueType fonts,
+@code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1
+fonts.
+
+
@node Bootstrapping
@section Bootstrapping
@chapter Acknowledgments
Guix is based on the Nix package manager, which was designed and
-implemented by Eelco Dolstra. Nix pioneered functional package
+implemented by Eelco Dolstra, with contributions from other people (see
+the @file{nix/AUTHORS} file in Guix.) Nix pioneered functional package
management, and promoted unprecedented features, such as transactional
package upgrades and rollbacks, per-user profiles, and referentially
transparent build processes. Without this work, Guix would not exist.
The Nix-based software distributions, Nixpkgs and NixOS, have also been
an inspiration for Guix.
+GNU@tie{}Guix itself is a collective work with contributions from a
+number of people. See the @file{AUTHORS} file in Guix for more
+information on these fine people. The @file{THANKS} file lists people
+who have helped by reporting bugs, taking care of the infrastructure,
+providing artwork and themes, making suggestions, and more---thank you!
+
+
@c *********************************************************************
@node GNU Free Documentation License
@appendix GNU Free Documentation License
HCoop / jackhill / guix / guix.git / blobdiff