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
@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
@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,
open store connection.
@end deffn
-@deffn {Monadic Procedure} text-file @var{name} @var{text}
+@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.
+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}] @
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.
@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.
+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
* 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
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/guix-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
* 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
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
@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