Installation
* Requirements:: Software needed to build and run Guix.
+* Running the Test Suite:: Testing Guix.
* Setting Up the Daemon:: Preparing the build daemon's environment.
* Invoking guix-daemon:: Running the build daemon.
* Invoking guix refresh:: Updating package definitions.
* Invoking guix lint:: Finding errors in package definitions.
* Invoking guix environment:: Setting up development environments.
+* Invoking guix publish:: Sharing substitutes.
GNU Distribution
* Locales:: Language and cultural convention settings.
* Services:: Specifying system services.
* Setuid Programs:: Programs running with root privileges.
+* Name Service Switch:: Configuring libc's name service switch.
* Initial RAM Disk:: Linux-Libre bootstrapping.
* GRUB Configuration:: Configuring the boot loader.
* Invoking guix system:: Instantiating a system configuration.
* Base Services:: Essential system services.
* Networking Services:: Network setup, SSH daemon, etc.
* X Window:: Graphical display.
+* Various Services:: Other services.
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.
+* 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
Guix has a command-line interface, which allows users to build, install,
upgrade, and remove packages, as well as a Scheme programming interface.
+@cindex Guix System Distribution
+@cindex GSD
Last but not least, Guix is used to build a distribution of the GNU
-system, with many GNU and non-GNU free software packages. @xref{GNU
-Distribution}.
+system, with many GNU and non-GNU free software packages. The Guix
+System Distribution, or GNU@tie{}GSD, takes advantage of the core
+properties of Guix at the system level. With GNU@tie{}GSD, users
+@emph{declare} all aspects of the operating system configuration, and
+Guix takes care of instantiating that configuration in a reproducible,
+stateless fashion. @xref{GNU Distribution}.
@c *********************************************************************
@node Installation
@menu
* Requirements:: Software needed to build and run Guix.
+* Running the Test Suite:: Testing Guix.
* Setting Up the Daemon:: Preparing the build daemon's environment.
* Invoking guix-daemon:: Running the build daemon.
@end menu
Note that @code{--disable-daemon} is not required if
your goal is to share the store with Nix.
+@node Running the Test Suite
+@section Running the Test Suite
+
+After a successful @command{configure} and @code{make} run, it is a good
+idea to run the test suite. It can help catch issues with the setup or
+environment, or bugs in Guix itself---and really, reporting test
+failures is a good way to help improve the software. To run the test
+suite, type:
+
+@example
+make check
+@end example
+
+Test cases can run in parallel: you can use the @code{-j} option of
+GNU@tie{}make to speed things up. The first run may take a few minutes
+on a recent machine; subsequent runs will be faster because the store
+that is created for test purposes will already have various things in
+cache.
+
+Upon failure, please email @email{bug-guix@@gnu.org} and attach the
+@file{test-suite.log} file. When @file{tests/@var{something}.scm}
+fails, please also attach the @file{@var{something}.log} file available
+in the top-level build directory. Please specify the Guix version being
+used as well as version numbers of the dependencies
+(@pxref{Requirements}) in your message.
+
@node Setting Up the Daemon
@section Setting Up the Daemon
daemon (@i{via} remote procedure calls) to instruct it what to do.
The following sections explain how to prepare the build daemon's
-environment.
+environment. Also @ref{Substitutes}, for information on how to allow
+the daemon to download pre-built binaries.
@menu
* Build Environment Setup:: Preparing the isolated build environment.
done
@end example
-The @file{/gnu/store} directory (or whichever was specified with the
-@code{--with-store-dir} option) must have ownership and permissions as
-follows:
-
-@example
-# chgrp guix-builder /gnu/store
-# chmod 1775 /gnu/store
-@end example
-
@noindent
The @code{guix-daemon} program may then be run as @code{root} with:
a separate mount name space, its own PID name space, network name space,
etc. This helps achieve reproducible builds (@pxref{Features}).
+When the daemon performs a build on behalf of the user, it creates a
+build directory under @file{/tmp} or under the directory specified by
+its @code{TMPDIR} environment variable; this directory is shared with
+the container for the duration of the build. Be aware that using a
+directory other than @file{/tmp} can affect build results---for example,
+with a longer directory name, a build process that uses Unix-domain
+sockets might hit the name length limitation for @code{sun_path}, which
+it would otherwise not hit.
+
+The build directory is automatically deleted upon completion, unless the
+build failed and the client specified @option{--keep-failed}
+(@pxref{Invoking guix build, @option{--keep-failed}}).
+
The following command-line options are supported:
@table @code
specified duration match. For instance, @code{--delete-generations=1m}
deletes generations that are more than one month old.
-If the current generation matches, it is deleted atomically---i.e., by
-switching to the previous available generation. Note that the zeroth
-generation is never deleted.
+If the current generation matches, it is @emph{not} deleted. Also, the
+zeroth generation is never deleted.
Note that deleting generations prevents roll-back to them.
Consequently, this command must be used with care.
@cindex garbage collector
Packages that are installed but not used may be @dfn{garbage-collected}.
The @command{guix gc} command allows users to explicitly run the garbage
-collector to reclaim space from the @file{/gnu/store} directory.
+collector to reclaim space from the @file{/gnu/store} directory. It is
+the @emph{only} way to remove files from @file{/gnu/store}---removing
+files or directories manually may break it beyond repair!
The garbage collector has a set of known @dfn{roots}: any file under
@file{/gnu/store} reachable from a root is considered @dfn{live} and
package to a machine connected over SSH, one would run:
@example
-guix archive --export emacs | ssh the-machine guix archive --import
+guix archive --export -r emacs | ssh the-machine guix archive --import
+@end example
+
+@noindent
+Similarly, a complete user profile may be transferred from one machine
+to another like this:
+
+@example
+guix archive --export -r $(readlink -f ~/.guix-profile) | \
+ ssh the-machine guix-archive --import
@end example
@noindent
-However, note that, in this example, all of @code{emacs} and its
-dependencies are transferred, regardless of what is already available in
-the target machine's store. The @code{--missing} option can help figure
-out which items are missing from the target's store.
+However, note that, in both examples, all of @code{emacs} and the
+profile as well as all of their dependencies are transferred (due to
+@code{-r}), regardless of what is already available in the target
+machine's store. The @code{--missing} option can help figure out which
+items are missing from the target's store.
Archives are stored in the ``Nix archive'' or ``Nar'' format, which is
comparable in spirit to `tar', but with a few noteworthy differences
Export the specified store files or packages (see below.) Write the
resulting archive to the standard output.
+Dependencies are @emph{not} included in the output, unless
+@code{--recursive} is passed.
+
+@item -r
+@itemx --recursive
+When combined with @code{--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.
+
@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
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, it
-is a 4096-bit RSA key. Alternately, @var{parameters} can specify
+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.
+Alternately, @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}).
@defvr {Scheme Variable} perl-build-system
This variable is exported by @code{(guix build-system perl)}. It
-implements the standard build procedure for Perl packages, which
-consists in running @code{perl Makefile.PL PREFIX=/gnu/store/@dots{}},
-followed by @code{make} and @code{make install}.
-
-The initial @code{perl Makefile.PL} invocation passes flags specified by
-the @code{#:make-maker-flags} parameter.
+implements the standard build procedure for Perl packages, which either
+consists in running @code{perl Build.PL --prefix=/gnu/store/@dots{}},
+followed by @code{Build} and @code{Build install}; or in running
+@code{perl Makefile.PL PREFIX=/gnu/store/@dots{}}, followed by
+@code{make} and @code{make install}; depending on which of
+@code{Build.PL} or @code{Makefile.PL} is present in the package
+distribution. Preference is given to the former if both @code{Build.PL}
+and @code{Makefile.PL} exist in the package distribution. This
+preference can be reversed by specifying @code{#t} for the
+@code{#:make-maker?} parameter.
+
+The initial @code{perl Makefile.PL} or @code{perl Build.PL} invocation
+passes flags specified by the @code{#:make-maker-flags} or
+@code{#:module-build-flags} parameter, respectively.
Which Perl package is used can be specified with @code{#:perl}.
@end defvr
parameter.
@end defvr
+@defvr {Scheme Variable} waf-build-system
+This variable is exported by @code{(guix build-system waf)}. It
+implements a build procedure around the @code{waf} script. The common
+phases---@code{configure}, @code{build}, and @code{install}---are
+implemented by passing their names as arguments to the @code{waf}
+script.
+
+The @code{waf} script is executed by the Python interpreter. Which
+Python package is used to run the script can be specified with the
+@code{#:python} parameter.
+@end defvr
+
+@defvr {Scheme Variable} haskell-build-system
+This variable is exported by @code{(guix build-system haskell)}. It
+implements the Cabal build procedure used by Haskell packages, which
+involves running @code{runhaskell Setup.hs configure
+--prefix=/gnu/store/@dots{}} and @code{runhaskell Setup.hs build}.
+Instead of installing the package by running @code{runhaskell Setup.hs
+install}, to avoid trying to register libraries in the read-only
+compiler store directory, the build system uses @code{runhaskell
+Setup.hs copy}, followed by @code{runhaskell Setup.hs register}. In
+addition, the build system generates the package documentation by
+running @code{runhaskell Setup.hs haddock}, unless @code{#:haddock? #f}
+is passed. Optional Haddock parameters can be passed with the help of
+the @code{#:haddock-flags} parameter. If the file @code{Setup.hs} is
+not found, the build system looks for @code{Setup.lhs} instead.
+
+Which Haskell compiler is used can be specified with the @code{#:haskell}
+parameter which defaults to @code{ghc}.
+@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
it provides basically no support: it does not pull any implicit inputs,
useful monad for our uses, the @dfn{store monad}. Monads are a
construct that allows two things: associating ``context'' with values
(in our case, the context is the store), and building sequences of
-computations (here computations includes accesses to the store.) Values
+computations (here computations include accesses to the store.) Values
in a monad---values that carry this additional context---are called
@dfn{monadic values}; procedures that return such values are called
@dfn{monadic procedures}.
Note that non-monadic values cannot be returned in the
@code{store-monad} REPL.
-The main syntactic forms to deal with monads in general are described
-below.
+The main syntactic forms to deal with monads in general are provided by
+the @code{(guix monads)} module and are described below.
@deffn {Scheme Syntax} with-monad @var{monad} @var{body} ...
Evaluate any @code{>>=} or @code{return} forms in @var{body} as being
@code{begin}, but applied to monadic expressions.
@end deffn
-The interface to the store monad provided by @code{(guix monads)} is as
-follows.
+@cindex state monad
+The @code{(guix monads)} module provides the @dfn{state monad}, which
+allows an additional value---the state---to be @emph{threaded} through
+monadic procedure calls.
-@defvr {Scheme Variable} %store-monad
-The store monad. Values in the store monad encapsulate accesses to the
-store. When its effect is needed, a value of the store monad must be
-``evaluated'' by passing it to the @code{run-with-store} procedure (see
-below.)
+@defvr {Scheme Variable} %state-monad
+The state monad. Procedures in the state monad can access and change
+the state that is threaded.
+
+Consider the example below. The @code{square} procedure returns a value
+in the state monad. It returns the square of its argument, but also
+increments the current state value:
+
+@example
+(define (square x)
+ (mlet %state-monad ((count (current-state)))
+ (mbegin %state-monad
+ (set-current-state (+ 1 count))
+ (return (* x x)))))
+
+(run-with-state (sequence %state-monad (map square (iota 3))) 0)
+@result{} (0 1 4)
+@result{} 3
+@end example
+
+When ``run'' through @var{%state-monad}, we obtain that additional state
+value, which is the number of @code{square} calls.
@end defvr
-@deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)]
-Run @var{mval}, a monadic value in the store monad, in @var{store}, an
-open store connection.
+@deffn {Monadic Procedure} current-state
+Return the current state as a monadic value.
@end deffn
-@deffn {Monadic Procedure} text-file @var{name} @var{text}
-Return as a monadic value the absolute file name in the store of the file
-containing @var{text}, a string.
+@deffn {Monadic Procedure} set-current-state @var{value}
+Set the current state to @var{value} and return the previous state as a
+monadic value.
@end deffn
-@deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
-Return as a monadic value a derivation that builds a text file
-containing all of @var{text}. @var{text} may list, in addition to
-strings, packages, derivations, and store file names; the resulting
-store file holds references to all these.
+@deffn {Monadic Procedure} state-push @var{value}
+Push @var{value} to the current state, which is assumed to be a list,
+and return the previous state as a monadic value.
+@end deffn
-This variant should be preferred over @code{text-file} anytime the file
-to create will reference items from the store. This is typically the
-case when building a configuration file that embeds store file names,
-like this:
+@deffn {Monadic Procedure} state-pop
+Pop a value from the current state and return it as a monadic value.
+The state is assumed to be a list.
+@end deffn
-@example
-(define (profile.sh)
- ;; Return the name of a shell script in the store that
- ;; initializes the 'PATH' environment variable.
- (text-file* "profile.sh"
- "export PATH=" coreutils "/bin:"
- grep "/bin:" sed "/bin\n"))
-@end example
+@deffn {Scheme Procedure} run-with-state @var{mval} [@var{state}]
+Run monadic value @var{mval} starting with @var{state} as the initial
+state. Return two values: the resulting value, and the resulting state.
+@end deffn
-In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file
-will references @var{coreutils}, @var{grep}, and @var{sed}, thereby
-preventing them from being garbage-collected during its lifetime.
+The main interface to the store monad, provided by the @code{(guix
+store)} module, is as follows.
+
+@defvr {Scheme Variable} %store-monad
+The store monad---an alias for @var{%state-monad}.
+
+Values in the store monad encapsulate accesses to the store. When its
+effect is needed, a value of the store monad must be ``evaluated'' by
+passing it to the @code{run-with-store} procedure (see below.)
+@end defvr
+
+@deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)]
+Run @var{mval}, a monadic value in the store monad, in @var{store}, an
+open store connection.
+@end deffn
+
+@deffn {Monadic Procedure} text-file @var{name} @var{text} [@var{references}]
+Return as a monadic value the absolute file name in the store of the file
+containing @var{text}, a string. @var{references} is a list of store items that the
+resulting text file refers to; it defaults to the empty list.
@end deffn
@deffn {Monadic Procedure} interned-file @var{file} [@var{name}] @
@end deffn
+The @code{(guix packages)} module exports the following package-related
+monadic procedures:
+
@deffn {Monadic Procedure} package-file @var{package} [@var{file}] @
[#:system (%current-system)] [#:target #f] @
[#:output "out"] Return as a monadic
processes.
@item
-When a package or derivation is unquoted inside a gexp, the result is as
-if its output file name had been introduced.
+When a high-level object such as a package or derivation is unquoted
+inside a gexp, the result is as if its output file name had been
+introduced.
@item
Gexps carry information about the packages or derivations they refer to,
processes that use them.
@end itemize
+Actually this mechanism is not limited to package and derivation
+objects; @dfn{compilers} able to ``lower'' other high-level objects to
+derivations can be defined, such that these objects can also be inserted
+into gexps. Another useful type of high-level object that can be
+inserted in a gexp is @dfn{local files}, which allows files from the
+local file system to be added to the store and referred to by
+derivations and such (see @code{local-file} below.)
+
To illustrate the idea, here is an example of a gexp:
@example
#~(begin
(mkdir #$output)
(chdir #$output)
- (symlink (string-append #$coreutils "/bin/ls")
+ (symlink (string-append #$coreutils "/bin/ls")
"list-files")))
@end example
@table @code
@item #$@var{obj}
@itemx (ungexp @var{obj})
-Introduce a reference to @var{obj}. @var{obj} may be a package or a
+Introduce a reference to @var{obj}. @var{obj} may have one of the
+supported types, for example a package or a
derivation, in which case the @code{ungexp} form is replaced by its
output file name---e.g., @code{"/gnu/store/@dots{}-coreutils-8.22}.
-If @var{obj} is a list, it is traversed and any package or derivation
-references are substituted similarly.
+If @var{obj} is a list, it is traversed and references to supported
+objects are substituted similarly.
If @var{obj} is another gexp, its contents are inserted and its
dependencies are added to those of the containing gexp.
If @var{obj} is another kind of object, it is inserted as is.
-@item #$@var{package-or-derivation}:@var{output}
-@itemx (ungexp @var{package-or-derivation} @var{output})
+@item #$@var{obj}:@var{output}
+@itemx (ungexp @var{obj} @var{output})
This is like the form above, but referring explicitly to the
-@var{output} of @var{package-or-derivation}---this is useful when
-@var{package-or-derivation} produces multiple outputs (@pxref{Packages
-with Multiple Outputs}).
+@var{output} of @var{obj}---this is useful when @var{obj} produces
+multiple outputs (@pxref{Packages with Multiple Outputs}).
@item #+@var{obj}
@itemx #+@var{obj}:output
information about monads.)
@deffn {Monadic Procedure} gexp->derivation @var{name} @var{exp} @
- [#:system (%current-system)] [#:target #f] [#:inputs '()] @
+ [#:system (%current-system)] [#:target #f] [#:graft? #t] @
[#: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]
+ [#:references-graphs #f] [#:allowed-references #f] @
+ [#:local-build? #f] [#:guile-for-build #f]
Return a derivation @var{name} that runs @var{exp} (a gexp) with
@var{guile-for-build} (a derivation) on @var{system}. When @var{target}
is true, it is used as the cross-compilation target triplet for packages
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 searched in
-@var{MODULE-PATH} to be copied in the store, compiled, and made available in
+Make @var{modules} available in the evaluation context of @var{exp};
+@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))}.
+@var{graft?} determines whether packages referred to by @var{exp} should be grafted when
+applicable.
+
When @var{references-graphs} is true, it must be a list of tuples of one of the
following forms:
@var{file-name} contains the reference graph of the corresponding item, in a simple
text format.
+@var{allowed-references} must be either @code{#f} or a list of output names and packages.
+In the latter case, the list denotes store items that the result is allowed to
+refer to. Any reference to another store item will lead to a build error.
+
The other arguments are as for @code{derivation} (@pxref{Derivations}).
@end deffn
+@deffn {Scheme Procedure} local-file @var{file} [@var{name}] @
+ [#:recursive? #t]
+Return an object representing local file @var{file} to add to the store; this
+object can be used in a gexp. @var{file} will be added to the store under @var{name}--by
+default the base name of @var{file}.
+
+When @var{recursive?} is true, the contents of @var{file} are added recursively; if @var{file}
+designates a flat file and @var{recursive?} is true, its contents are added, and its
+permission bits are kept.
+
+This is the declarative counterpart of the @code{interned-file} monadic
+procedure (@pxref{The Store Monad, @code{interned-file}}).
+@end deffn
+
@deffn {Monadic Procedure} gexp->script @var{name} @var{exp}
Return an executable script @var{name} that runs @var{exp} using
@var{guile} with @var{modules} in its search path.
or a subset thereof.
@end deffn
+@deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
+Return as a monadic value a derivation that builds a text file
+containing all of @var{text}. @var{text} may list, in addition to
+strings, objects of any type that can be used in a gexp: packages,
+derivations, local file objects, etc. The resulting store file holds
+references to all these.
+
+This variant should be preferred over @code{text-file} anytime the file
+to create will reference items from the store. This is typically the
+case when building a configuration file that embeds store file names,
+like this:
+
+@example
+(define (profile.sh)
+ ;; Return the name of a shell script in the store that
+ ;; initializes the 'PATH' environment variable.
+ (text-file* "profile.sh"
+ "export PATH=" coreutils "/bin:"
+ grep "/bin:" sed "/bin\n"))
+@end example
+
+In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file
+will references @var{coreutils}, @var{grep}, and @var{sed}, thereby
+preventing them from being garbage-collected during its lifetime.
+@end deffn
+
Of course, in addition to gexps embedded in ``host'' code, there are
also modules containing build tools. To make it clear that they are
meant to be used in the build stratum, these modules are kept in the
* Invoking guix refresh:: Updating package definitions.
* Invoking guix lint:: Finding errors in package definitions.
* Invoking guix environment:: Setting up development environments.
+* Invoking guix publish:: Sharing substitutes.
@end menu
@node Invoking guix build
Behind the scenes, @command{guix build} is essentially an interface to
the @code{package-derivation} procedure of the @code{(guix packages)}
module, and to the @code{build-derivations} procedure of the @code{(guix
-store)} module.
+derivations)} module.
In addition to options explicitly passed on the command line,
@command{guix build} and other @command{guix} commands that support
Import meta-data from @uref{https://www.metacpan.org/, MetaCPAN}.
Information is taken from the JSON-formatted meta-data provided through
@uref{https://api.metacpan.org/, MetaCPAN's API} and includes most
-relevant information. License information should be checked closely.
-Package dependencies are included but may in some cases needlessly
-include core Perl modules.
+relevant information, such as module dependencies. License information
+should be checked closely. If Perl is available in the store, then the
+@code{corelist} utility will be used to filter core modules out of the
+list of dependencies.
The command command below imports meta-data for the @code{Acme::Boolean}
Perl module:
@node Invoking guix lint
@section Invoking @command{guix lint}
The @command{guix lint} is meant to help package developers avoid common
-errors and use a consistent style. It runs a few checks on a given set of
-packages in order to find common mistakes in their definitions.
+errors and use a consistent style. It runs a number of checks on a
+given set of packages in order to find common mistakes in their
+definitions. Available @dfn{checkers} include (see
+@code{--list-checkers} for a complete list):
+
+@table @code
+@item synopsis
+@itemx description
+Validate certain typographical and stylistic rules about package
+descriptions and synopses.
+
+@item inputs-should-be-native
+Identify inputs that should most likely be native inputs.
+
+@item source
+@itemx home-page
+Probe @code{home-page} and @code{source} URLs and report those that are
+invalid.
+@end table
The general syntax is:
It also supports all of the common build options that @command{guix
build} supports (@pxref{Invoking guix build, common build options}).
+@node Invoking guix publish
+@section Invoking @command{guix publish}
+
+The purpose of @command{guix publish} is to enable users to easily share
+their store with others. When @command{guix publish} runs, it spawns an
+HTTP server which allows anyone with network access to obtain
+substitutes from it. This means that any machine running Guix can also
+act as if it were a build farm, since the HTTP interface is
+Hydra-compatible.
+
+For security, each substitute is signed, allowing recipients to check
+their authenticity and integrity (@pxref{Substitutes}). Because
+@command{guix publish} uses the system's signing key, which is only
+readable by the system administrator, it must run as root.
+
+The general syntax is:
+
+@example
+guix publish @var{options}@dots{}
+@end example
+
+Running @command{guix publish} without any additional arguments will
+spawn an HTTP server on port 8080:
+
+@example
+guix publish
+@end example
+
+Once a publishing server has been authorized (@pxref{Invoking guix
+archive}), the daemon may download substitutes from it:
+
+@example
+guix-daemon --substitute-urls=http://example.org:8080
+@end example
+
+The following options are available:
+
+@table @code
+@item --port=@var{port}
+@itemx -p @var{port}
+Listen for HTTP requests on @var{port}.
+
+@item --repl[=@var{port}]
+@itemx -r [@var{port}]
+Spawn a Guile REPL server (@pxref{REPL Servers,,, guile, GNU Guile
+Reference Manual}) on @var{port} (37146 by default).
+@end table
+
@c *********************************************************************
@node GNU Distribution
@chapter GNU Distribution
-@cindex Guixotic
-Guix comes with a distribution of free software@footnote{The term
-``free'' here refers to the
+@cindex Guix System Distribution
+@cindex GSD
+Guix comes with a distribution of the GNU system consisting entirely of
+free software@footnote{The term ``free'' here refers to the
@url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
-users of that software}.} that forms the basis of the GNU system. The
+users of that software}.}. The
distribution can be installed on its own (@pxref{System Installation}),
but it is also possible to install Guix as a package manager on top of
an installed GNU/Linux system (@pxref{Installation}). To distinguish
-between the two, we refer to the standalone distribution as
-``Guixotic''@footnote{``How am I going to pronounce that name?'', you
-may ask. Well, we would pronounce it like ``geeks-otic'', for
-consistency with Guix---which is quite different from the usual
-pronunciation of ``quixotic''.}.
+between the two, we refer to the standalone distribution as the Guix
+System Distribution, or GNU@tie{}GSD.
The distribution provides core GNU packages such as GNU libc, GCC, and
Binutils, as well as many GNU and non-GNU applications. The complete
tight integration of GNU components, and an emphasis on programs and
tools that help users exert that freedom.
-The GNU distribution is currently available on the following platforms:
+Packages are currently available on the following platforms:
@table @code
@item i686-linux
Intel 32-bit architecture (IA32), Linux-Libre kernel;
+@item armhf-linux
+ARMv7-A architecture with hard float, Thumb-2 and VFP3D16 coprocessor,
+using the EABI hard-float ABI, and Linux-Libre kernel.
+
@item mips64el-linux
little-endian 64-bit MIPS processors, specifically the Loongson series,
n32 application binary interface (ABI), and Linux-Libre kernel.
@end table
+GSD itself is currently only available on @code{i686} and @code{x86_64}.
+
@noindent
For information on porting to other architectures or kernels,
@xref{Porting}.
@node System Installation
@section System Installation
-@cindex Guixotic
-This section explains how to install the standalone distribution,
-code-named ``Guixotic'', on a machine. The Guix package manager can
+@cindex Guix System Distribution
+This section explains how to install the Guix System Distribution
+on a machine. The Guix package manager can
also be installed on top of a running GNU/Linux system,
@pxref{Installation}.
@subsection Limitations
-As of version @value{VERSION}, GNU@tie{}Guix and Guixotic are
-not production-ready. They may contain bugs and lack important
+As of version @value{VERSION}, the Guix System Distribution (GSD) is
+not production-ready. It may contain bugs and lack important
features. Thus, if you are looking for a stable production system that
respects your freedom as a computer user, a good solution at this point
is to consider @url{http://www.gnu.org/distros/free-distros.html, one of
more established GNU/Linux distributions}. We hope you can soon switch
-to Guixotic without fear, of course. In the meantime, you can
+to the GSD without fear, of course. In the meantime, you can
also keep using your distribution and try out the package manager on top
of it (@pxref{Installation}).
get a feel of what that means.)
@item
-The system does not yet provide graphical desktop environments such as
-GNOME and KDE.
+The system does not yet provide GNOME and KDE; it provides Xfce, though,
+if graphical desktop environments are your thing.
@item
Support for the Logical Volume Manager (LVM) is missing.
(@pxref{Services}).
@item
-On the order of 1,000 packages are available, which means that you may
+On the order of 1,200 packages are available, which means that you may
occasionally find that a useful package is missing.
@end itemize
@subsection USB Stick Installation
An installation image for USB sticks can be downloaded from
-@url{ftp://alpha.gnu.org/gnu/guix/gnu-usb-install-@value{VERSION}.@var{system}.xz},
+@code{ftp://alpha.gnu.org/gnu/guix/gsd-usb-install-@value{VERSION}.@var{system}.xz},
where @var{system} is one of:
@table @code
Decompress the image using the @command{xz} command:
@example
-xz -d gnu-usb-install-@value{VERSION}.@var{system}.xz
+xz -d gsd-usb-install-@value{VERSION}.@var{system}.xz
@end example
@item
copy the image with:
@example
-dd if=gnu-usb-install-@value{VERSION}.x86_64 of=/dev/sdX
+dd if=gsd-usb-install-@value{VERSION}.x86_64 of=/dev/sdX
@end example
Access to @file{/dev/sdX} usually requires root privileges.
@enumerate
@item
-Configure the network, by running @command{dhclient eth0} (to get an
+Configure the network, by running @command{dhclient eno1} (to get an
automatically assigned IP address from the wired network interface
-controller), or using the @command{ifconfig} command.
+controller@footnote{
+@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
+The name @code{eno1} is for the first on-board Ethernet controller. The
+interface name for an Ethernet controller that is in the first slot of
+the first PCI bus, for instance, would be @code{enp1s0}. Use
+@command{ifconfig -a} to list all the available network interfaces.}),
+or using the @command{ifconfig} command.
The system automatically loads drivers for your network interface
controllers.
system} command, specifically:
@example
-guix system disk-image --image-size=800MiB gnu/system/install.scm
+guix system disk-image --image-size=850MiB gnu/system/install.scm
@end example
@xref{Invoking guix system}, for more information. See
@section System Configuration
@cindex system configuration
-Guixotic supports a consistent whole-system configuration
+The Guix System Distribution supports a consistent whole-system configuration
mechanism. By that we mean that all aspects of the global system
configuration---such as the available system services, timezone and
locale settings, user accounts---are declared in a single place. Such
* Locales:: Language and cultural convention settings.
* Services:: Specifying system services.
* Setuid Programs:: Programs running with root privileges.
+* Name Service Switch:: Configuring libc's name service switch.
* Initial RAM Disk:: Linux-Libre bootstrapping.
* GRUB Configuration:: Configuring the boot loader.
* Invoking guix system:: Instantiating a system configuration.
The list of locale definitions to be compiled and that may be used at
run time. @xref{Locales}.
+@item @code{name-service-switch} (default: @var{%default-nss})
+Configuration of libc's name service switch (NSS)---a
+@code{<name-service-switch>} object. @xref{Name Service Switch}, for
+details.
+
@item @code{services} (default: @var{%base-services})
A list of monadic values denoting system services. @xref{Services}.
* Base Services:: Essential system services.
* Networking Services:: Network setup, SSH daemon, etc.
* X Window:: Graphical display.
+* Various Services:: Other services.
@end menu
@node Base Services
@cindex name service cache daemon
@cindex nscd
-@deffn {Monadic Procedure} nscd-service [@var{config}] [#:glibc glibc]
-Return a service that runs libc's name service cache daemon (nscd) with the
-given @var{config}---an @code{<nscd-configuration>} object.
+@deffn {Monadic Procedure} nscd-service [@var{config}] [#:glibc glibc] @
+ [#:name-services '()]
+Return a service that runs libc's name service cache daemon (nscd) with
+the given @var{config}---an @code{<nscd-configuration>} object.
+Optionally, @code{#:name-services} is a list of packages that provide
+name service switch (NSS) modules needed by nscd.
@end deffn
@defvr {Scheme Variable} %nscd-default-configuration
@end defvr
-@deffn {Monadic Procedure} syslog-service
-Return a service that runs @code{syslogd} with reasonable default
+@deffn {Monadic Procedure} syslog-service [#:config-file #f]
+Return a service that runs @code{syslogd}. If configuration file name
+@var{config-file} is not specified, use some reasonable default
settings.
@end deffn
@deffn {Monadic Procedure} guix-service [#:guix guix] @
[#:builder-group "guixbuild"] [#:build-accounts 10] @
- [#:authorize-hydra-key? #f] [#:use-substitutes? #t] @
+ [#:authorize-hydra-key? #t] [#:use-substitutes? #t] @
[#:extra-options '()]
Return a service that runs the build daemon from @var{guix}, and has
@var{build-accounts} user accounts available under @var{builder-group}.
gateway.
@end deffn
+@cindex wicd
+@deffn {Monadic Procedure} wicd-service [#:wicd @var{wicd}]
+Return a service that runs @url{https://launchpad.net/wicd,Wicd}, a
+network manager that aims to simplify wired and wireless networking.
+@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
Furthermore, @code{(gnu services ssh)} provides the following service.
@deffn {Monadic Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @
- [#:interfaces '()] [#:port-number 22] @
+ [#:daemonic? #t] [#:interfaces '()] [#:port-number 22] @
[#:allow-empty-passwords? #f] [#:root-login? #f] @
[#:syslog-output? #t] [#:x11-forwarding? #t] @
[#:tcp/ip-forwarding? #t] [#:password-authentication? #t] @
- [public-key-authentication? #t] [#:initialize? #f]
+ [#:public-key-authentication? #t] [#:initialize? #t]
Run the @command{lshd} program from @var{lsh} to listen on port @var{port-number}.
@var{host-key} must designate a file containing the host key, and readable
only by root.
+When @var{daemonic?} is true, @command{lshd} will detach from the
+controlling terminal and log its output to syslogd, unless one sets
+@var{syslog-output?} to false. Obviously, it also makes lsh-service
+depend on existence of syslogd service. When @var{pid-file?} is true,
+@command{lshd} writes its PID to the file called @var{pid-file}.
+
When @var{initialize?} is true, automatically create the seed and host key
upon service activation if they do not exist yet. This may take long and
require interaction.
resolutions---e.g., @code{((1024 768) (640 480))}.
@end deffn
+@node Various Services
+@subsubsection Various Services
+
+The @code{(gnu services lirc)} module provides the following service.
+
+@deffn {Monadic Procedure} lirc-service [#:lirc lirc] @
+ [#:device #f] [#:driver #f] [#:config-file #f] @
+ [#:extra-options '()]
+Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that
+decodes infrared signals from remote controls.
+
+Optionally, @var{device}, @var{driver} and @var{config-file}
+(configuration file name) may be specified. See @command{lircd} manual
+for details.
+
+Finally, @var{extra-options} is a list of additional command-line options
+passed to @command{lircd}.
+@end deffn
+
@node Setuid Programs
@subsection Setuid Programs
files in this directory refer to the ``real'' binaries, which are in the
store.
+@node Name Service Switch
+@subsection Name Service Switch
+
+@cindex name service switch
+@cindex NSS
+The @code{(gnu system nss)} module provides bindings to the
+configuration file of libc's @dfn{name service switch} or @dfn{NSS}
+(@pxref{NSS Configuration File,,, libc, The GNU C Library Reference
+Manual}). In a nutshell, the NSS is a mechanism that allows libc to be
+extended with new ``name'' lookup methods for system databases, which
+includes host names, service names, user accounts, and more (@pxref{Name
+Service Switch, System Databases and Name Service Switch,, libc, The GNU
+C Library Reference Manual}).
+
+The NSS configuration specifies, for each system database, which lookup
+method is to be used, and how the various methods are chained
+together---for instance, under which circumstances NSS should try the
+next method in the list. The NSS configuration is given in the
+@code{name-service-switch} field of @code{operating-system} declarations
+(@pxref{operating-system Reference, @code{name-service-switch}}).
+
+@c See <http://0pointer.de/lennart/projects/nss-mdns/>.
+As an example, the declaration below configures the NSS to use the
+@code{nss-mdns} back-end for host name lookups:
+
+@example
+(name-service-switch
+ (hosts (list %files ;first, check /etc/hosts
+
+ ;; If the above did not succeed, try
+ ;; with 'mdns_minimal'.
+ (name-service
+ (name "mdns_minimal")
+
+ ;; 'mdns_minimal' is authoritative for
+ ;; '.local'. When it returns "not found",
+ ;; no need to try the next methods.
+ (reaction (lookup-specification
+ (not-found => return))))
+
+ ;; Then fall back to DNS.
+ (name-service
+ (name "dns"))
+
+ ;; Finally, try with the "full" 'mdns'.
+ (name-service
+ (name "mdns")))))
+@end example
+
+The reference for name service switch configuration is given below. It
+is a direct mapping of the C library's configuration file format, so
+please refer to the C library manual for more information (@pxref{NSS
+Configuration File,,, libc, The GNU C Library Reference Manual}).
+Compared to libc's NSS configuration file format, it has the advantage
+not only of adding this warm parenthetic feel that we like, but also
+static checks: you'll know about syntax errors and typos as soon as you
+run @command{guix system}.
+
+@defvr {Scheme Variable} %default-nss
+This is the default name service switch configuration, a
+@code{name-service-switch} object.
+@end defvr
+
+@deftp {Data Type} name-service-switch
+
+This is the data type representation the configuration of libc's name
+service switch (NSS). Each field below represents one of the supported
+system databases.
+
+@table @code
+@item aliases
+@itemx ethers
+@itemx group
+@itemx gshadow
+@itemx hosts
+@itemx initgroups
+@itemx netgroup
+@itemx networks
+@itemx password
+@itemx public-key
+@itemx rpc
+@itemx services
+@itemx shadow
+The system databases handled by the NSS. Each of these fields must be a
+list of @code{<name-service>} objects (see below.)
+@end table
+@end deftp
+
+@deftp {Data Type} name-service
+
+This is the data type representing an actual name service and the
+associated lookup action.
+
+@table @code
+@item name
+A string denoting the name service (@pxref{Services in the NSS
+configuration,,, libc, The GNU C Library Reference Manual}).
+
+Note that name services listed here must be visible to nscd. This is
+achieved by passing the @code{#:name-services} argument to
+@code{nscd-service} the list of packages providing the needed name
+services (@pxref{Base Services, @code{nscd-service}}).
+
+@item reaction
+An action specified using the @code{lookup-specification} macro
+(@pxref{Actions in the NSS configuration,,, libc, The GNU C Library
+Reference Manual}). For example:
+
+@example
+(lookup-specification (unavailable => continue)
+ (success => return))
+@end example
+@end table
+@end deftp
@node Initial RAM Disk
@subsection Initial RAM Disk
@example
(initrd (lambda (file-systems . rest)
+ ;; Create a standard initrd that has modules "foo.ko"
+ ;; and "bar.ko", as well as their dependencies, in
+ ;; addition to the modules available by default.
(apply base-initrd file-systems
- #:extra-modules '("my.ko" "modules.ko")
+ #:extra-modules '("foo" "bar")
rest)))
@end example
@item init
Populate the given directory with all the files necessary to run the
operating system specified in @var{file}. This is useful for first-time
-installations of Guixotic. For instance:
+installations of GSD. For instance:
@example
guix system init my-os-config.scm /mnt
@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)}. These package definitions
+names---e.g., @code{(my-packages emacs)}@footnote{Note that the file
+name and module name must match. @xref{Modules and the File System,,,
+guile, GNU Guile Reference Manual}, for details.} 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
@menu
-* 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.
+* 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 menu
@node Software Freedom
HCoop / jackhill / guix / guix.git / blobdiff