@copying
Copyright @copyright{} 2012, 2013, 2014, 2015 Ludovic Courtès@*
Copyright @copyright{} 2013, 2014 Andreas Enge@*
-Copyright @copyright{} 2013 Nikita Karetnikov
+Copyright @copyright{} 2013 Nikita Karetnikov@*
+Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
Installation
+* Binary Installation:: Getting Guix running in no time!
* 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.
+* Running Guix Before It Is Installed:: Hacker tricks.
Setting Up the Daemon
* The Store Monad:: Purely functional interface to the store.
* G-Expressions:: Manipulating build expressions.
+Defining Packages
+
+* package Reference:: The package data type.
+* origin Reference:: The origin data type.
+
Utilities
* Invoking guix build:: Building packages from the command line.
* Locales:: Language and cultural convention settings.
* Services:: Specifying system services.
* Setuid Programs:: Programs running with root privileges.
+* X.509 Certificates:: Authenticating HTTPS servers.
* Name Service Switch:: Configuring libc's name service switch.
* Initial RAM Disk:: Linux-Libre bootstrapping.
* GRUB Configuration:: Configuring the boot loader.
* Base Services:: Essential system services.
* Networking Services:: Network setup, SSH daemon, etc.
* X Window:: Graphical display.
+* Desktop Services:: D-Bus and desktop services.
+* Database Services:: SQL databases.
* Various Services:: Other services.
Packaging Guidelines
upgrade, and remove packages, as well as a Scheme programming interface.
@cindex Guix System Distribution
-@cindex GSD
+@cindex GuixSD
Last but not least, Guix is used to build a distribution of the GNU
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
+System Distribution, or GNU@tie{}GuixSD, takes advantage of the core
+properties of Guix at the system level. With GuixSD, 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}.
* Running the Test Suite:: Testing Guix.
* Setting Up the Daemon:: Preparing the build daemon's environment.
* Invoking guix-daemon:: Running the build daemon.
+* Running Guix Before It Is Installed:: Hacker tricks.
@end menu
@node Binary Installation
@enumerate
@item
Download the binary tarball from
-@code{ftp://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz}@footnote{As
+@indicateurl{ftp://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz}@footnote{As
usual, make sure to download the associated @file{.sig} file and to
verify the authenticity of the tarball against it!}, where @var{system}
is @code{x86_64-linux} for an @code{x86_64} machine already running the
would overwrite its own essential files.
@item
-Create the group and user accounts for build users as explained below
-(@pxref{Build Environment Setup}), and run the daemon:
+Run the daemon:
@example
-# /root/.guix-profile/bin/guix-daemon --build-users-group=guix-builder
+# /root/.guix-profile/bin/guix-daemon --build-users-group=guixbuild
@end example
@item
@example
# mkdir -p /usr/local/bin
# cd /usr/local/bin
-# ln -s /root/.guix-profile/bin/guix
+# ln -s /var/guix/profiles/per-user/root/guix-profile/bin/guix
@end example
@item
GNU Guix depends on the following packages:
@itemize
-@item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.0.5 or later;
+@item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.0.7 or later;
@item @url{http://gnupg.org/, GNU libgcrypt};
+@item @url{http://www.gnu.org/software/make/, GNU Make}.
@end itemize
The following dependencies are optional:
following packages are also needed:
@itemize
-@item @url{http://sqlite.org, SQLite 3}
-@item @url{http://www.bzip.org, libbz2}
-@item @url{http://gcc.gnu.org, GCC's g++}
+@item @url{http://sqlite.org, SQLite 3};
+@item @url{http://www.bzip.org, libbz2};
+@item @url{http://gcc.gnu.org, GCC's g++}, with support for the
+C++11 standard.
@end itemize
When a working installation of @url{http://nixos.org/nix/, the Nix package
@c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
@c for why `-G' is needed.
@example
-# groupadd --system guix-builder
-# for i in `seq 1 10`;
+# groupadd --system guixbuild
+# for i in `seq -w 1 10`;
do
- useradd -g guix-builder -G guix-builder \
- -d /var/empty -s `which nologin` \
- -c "Guix build user $i" --system \
- guix-builder$i;
+ useradd -g guixbuild -G guixbuild \
+ -d /var/empty -s `which nologin` \
+ -c "Guix build user $i" --system \
+ guixbuilder$i;
done
@end example
The @code{guix-daemon} program may then be run as @code{root} with:
@example
-# guix-daemon --build-users-group=guix-builder
+# guix-daemon --build-users-group=guixbuild
@end example
@cindex chroot
@noindent
This way, the daemon starts build processes in a chroot, under one of
-the @code{guix-builder} users. On GNU/Linux, by default, the chroot
+the @code{guixbuilder} users. On GNU/Linux, by default, the chroot
environment contains nothing but:
@c Keep this list in sync with libstore/build.cc! -----------------------
a writable @file{/tmp} directory.
@end itemize
-If you are installing Guix as an unprivileged user, it is still
-possible to run @command{guix-daemon}. However, build processes will
-not be isolated from one another, and not from the rest of the system.
-Thus, build processes may interfere with each other, and may access
-programs, libraries, and other files available on the system---making it
-much harder to view them as @emph{pure} functions.
+If you are installing Guix as an unprivileged user, it is still possible
+to run @command{guix-daemon} provided you pass @code{--disable-chroot}.
+However, build processes will not be isolated from one another, and not
+from the rest of the system. Thus, build processes may interfere with
+each other, and may access programs, libraries, and other files
+available on the system---making it much harder to view them as
+@emph{pure} functions.
@node Daemon Offload Setup
is normally run as @code{root} like this:
@example
-# guix-daemon --build-users-group=guix-builder
+# guix-daemon --build-users-group=guixbuild
@end example
@noindent
@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}
+source URLs. When this option is omitted, @indicateurl{http://hydra.gnu.org}
is used.
This means that substitutes may be downloaded from @var{urls}, as long
Disable chroot builds.
Using this option is not recommended since, again, it would allow build
-processes to gain access to undeclared dependencies.
+processes to gain access to undeclared dependencies. It is necessary,
+though, when @command{guix-daemon} is running under an unprivileged user
+account.
@item --disable-log-compression
Disable compression of the build logs.
daemons on the same machine.
@end table
+@node Running Guix Before It Is Installed
+@section Running Guix Before It Is Installed
+
+If you are hacking Guix itself---which is a good idea!---you will find
+it useful to test the changes made in your local source tree checkout
+without actually installing them.
+
+To that end, all the command-line tools can be used even if you have not
+run @command{make install}. To do that, prefix each command with
+@command{./pre-inst-env} (the @file{pre-inst-env} script lives in the
+top build tree of Guix), as in:
+
+@example
+$ sudo ./pre-inst-env guix-daemon --build-users-group=guixbuild
+$ ./pre-inst-env guix build hello
+@end example
+
+@noindent
+Similarly, for a Guile session using the Guix modules:
+
+@example
+$ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
+@end example
+
+The @command{pre-inst-env} script sets up all the environment variables
+necessary to support this, including @code{PATH} and
+@code{GUILE_LOAD_PATH}.
+
+If you are hacking Guix from Emacs using the wonderful Geiser
+(@pxref{Introduction,,, geiser, Geiser User Manual}), make sure to
+augment Guile's load path so that it finds source files from your
+checkout:
+
+@lisp
+;; Assuming the Guix checkout is in ~/src/guix.
+(add-to-list 'geiser-guile-load-path "~/src/guix")
+@end lisp
+
@c *********************************************************************
@node Package Management
Primarily, @var{options} specifies the operations to be performed during
the transaction. Upon completion, a new profile is created, but
-previous generations of the profile remain available, should the user
+previous @dfn{generations} of the profile remain available, should the user
want to roll back.
For example, to remove @code{lua} and install @code{guile} and
guix package -r lua -i guile guile-cairo
@end example
+@command{guix package} also supports a @dfn{declarative approach}
+whereby the user specifies the exact set of packages to be available and
+passes it @i{via} the @option{--manifest} option
+(@pxref{profile-manifest, @option{--manifest}}).
+
For each user, a symlink to the user's default profile is automatically
created in @file{$HOME/.guix-profile}. This symlink always points to the
current generation of the user's default profile. Thus, users can add
@cindex propagated inputs
Sometimes packages have @dfn{propagated inputs}: these are dependencies
-that automatically get installed along with the required package.
+that automatically get installed along with the required package
+(@pxref{package-propagated-inputs, @code{propagated-inputs} in
+@code{package} objects}, for information about propagated inputs in
+package definitions).
+@anchor{package-cmd-propagated-inputs}
An example is the GNU MPC library: its C header files refer to those of
the GNU MPFR library, which in turn refer to those of the GMP library.
Thus, when installing MPC, the MPFR and GMP libraries also get installed
$ guix package --upgrade . --do-not-upgrade emacs
@end example
+@item @anchor{profile-manifest}--manifest=@var{file}
+@itemx -m @var{file}
+@cindex profile declaration
+@cindex profile manifest
+Create a new generation of the profile from the manifest object
+returned by the Scheme code in @var{file}.
+
+This allows you to @emph{declare} the profile's contents rather than
+constructing it through a sequence of @code{--install} and similar
+commands. The advantage is that @var{file} can be put under version
+control, copied to different machines to reproduce the same profile, and
+so on.
+
+@c FIXME: Add reference to (guix profile) documentation when available.
+@var{file} must return a @dfn{manifest} object, which is roughly a list
+of packages:
+
+@findex packages->manifest
+@example
+(use-package-modules guile emacs)
+
+(packages->manifest
+ (list emacs
+ guile-2.0
+ ;; Use a specific package output.
+ (list guile-2.0 "debug")))
+@end example
+
@item --roll-back
Roll back to the previous @dfn{generation} of the profile---i.e., undo
the last transaction.
not make a zeroth generation, so if a specified generation does not
exist, the current generation will not be changed.
-@item --search-paths
+@item --search-paths[=@var{kind}]
@cindex search paths
Report environment variable definitions, in Bash syntax, that may be
needed in order to use the set of installed packages. These environment
suggest setting these variables to @code{@var{profile}/include} and
@code{@var{profile}/lib}, respectively.
+The typical use case is to define these environment variables in the
+shell:
+
+@example
+$ eval `guix package --search-paths`
+@end example
+
+@var{kind} may be one of @code{exact}, @code{prefix}, or @code{suffix},
+meaning that the returned environment variable definitions will either
+be exact settings, or prefixes or suffixes of the current value of these
+variables. When omitted, @var{kind} defaults to @code{exact}.
+
@item --profile=@var{profile}
@itemx -p @var{profile}
Use @var{profile} instead of the user's default profile.
weaknesses. While using @code{hydra.gnu.org} substitutes can be
convenient, we encourage users to also build on their own, or even run
their own build farm, such that @code{hydra.gnu.org} is less of an
-interesting target.
+interesting target. One way to help is by publishing the software you
+build using @command{guix publish} so that others have one more choice
+of server to download substitutes from (@pxref{Invoking guix publish}).
Guix has the foundations to maximize build reproducibility
(@pxref{Features}). In most cases, independent builds of a given
arguments. This fails if some of the files are not in the store, or if
they are still live.
+@item --optimize
+@cindex deduplication
+Optimize the store by hard-linking identical files---this is
+@dfn{deduplication}.
+
+The daemon performs deduplication after each successful build or archive
+import, unless it was started with @code{--disable-deduplication}
+(@pxref{Invoking guix-daemon, @code{--disable-deduplication}}). Thus,
+this option is primarily useful when the daemon was running with
+@code{--disable-deduplication}.
+
@item --list-dead
Show the list of dead files and directories still present in the
store---i.e., files and directories no longer reachable from any root.
@itemize
@item
-The @code{source} field of the package is an @code{<origin>} object.
+The @code{source} field of the package is an @code{<origin>} object
+(@pxref{origin Reference}, for the complete reference).
Here, the @code{url-fetch} method from @code{(guix download)} is used,
meaning that the source is a file to be downloaded over FTP or HTTP.
unavailable to the build process, possibly leading to a build failure.
@end itemize
+@xref{package Reference}, for a full description of possible fields.
+
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
Configure and Build System}).
@end deffn
+@menu
+* package Reference :: The package data type.
+* origin Reference:: The origin data type.
+@end menu
+
+
+@node package Reference
+@subsection @code{package} Reference
+
+This section summarizes all the options available in @code{package}
+declarations (@pxref{Defining Packages}).
+
+@deftp {Data Type} package
+This is the data type representing a package recipe.
+
+@table @asis
+@item @code{name}
+The name of the package, as a string.
+
+@item @code{version}
+The version of the package, as a string.
+
+@item @code{source}
+An origin object telling how the source code for the package should be
+acquired (@pxref{origin Reference}).
+
+@item @code{build-system}
+The build system that should be used to build the package (@pxref{Build
+Systems}).
+
+@item @code{arguments} (default: @code{'()})
+The arguments that should be passed to the build system. This is a
+list, typically containing sequential keyword-value pairs.
+
+@item @code{inputs} (default: @code{'()})
+Package or derivation inputs to the build. This is a list of lists,
+where each list has the name of the input (a string) as its first
+element, a package or derivation object as its second element, and
+optionally the name of the output of the package or derivation that
+should be used, which defaults to @code{"out"}.
+
+@item @anchor{package-propagated-inputs}@code{propagated-inputs} (default: @code{'()})
+@cindex propagated inputs
+This field is like @code{inputs}, but the specified packages will be
+force-installed alongside the package they belong to
+(@pxref{package-cmd-propagated-inputs, @command{guix package}}, for
+information on how @command{guix package} deals with propagated inputs.)
+
+For example this is necessary when a library needs headers of another
+library to compile, or needs another shared library to be linked
+alongside itself when a program wants to link to it.
+
+@item @code{native-inputs} (default: @code{'()})
+This field is like @code{inputs}, but in case of a cross-compilation it
+will be ensured that packages for the architecture of the build machine
+are present, such that executables from them can be used during the
+build.
+
+This is typically where you would list tools needed at build time but
+not at run time, such as Autoconf, Automake, pkg-config, Gettext, or
+Bison. @command{guix lint} can report likely mistakes in this area
+(@pxref{Invoking guix lint}).
+
+@item @code{self-native-input?} (default: @code{#f})
+This is a Boolean field telling whether the package should use itself as
+a native input when cross-compiling.
+
+@item @code{outputs} (default: @code{'("out")})
+The list of output names of the package. @xref{Packages with Multiple
+Outputs}, for typical uses of additional outputs.
+
+@item @code{native-search-paths} (default: @code{'()})
+@itemx @code{search-paths} (default: @code{'()})
+A list of @code{search-path-specification} objects describing
+search-path environment variables honored by the package.
+
+@item @code{replacement} (default: @code{#f})
+This must either @code{#f} or a package object that will be used as a
+@dfn{replacement} for this package. @xref{Security Updates, grafts},
+for details.
+
+@item @code{synopsis}
+A one-line description of the package.
+
+@item @code{description}
+A more elaborate description of the package.
+
+@item @code{license}
+The license of the package; a value from @code{(guix licenses)}.
+
+@item @code{home-page}
+The URL to the home-page of the package, as a string.
+
+@item @code{supported-systems} (default: @var{%supported-systems})
+The list of systems supported by the package, as strings of the form
+@code{architecture-kernel}, for example @code{"x86_64-linux"}.
+
+@item @code{maintainers} (default: @code{'()})
+The list of maintainers of the package, as @code{maintainer} objects.
+
+@item @code{location} (default: source location of the @code{package} form)
+The source location of the package. It's useful to override this when
+inheriting from another package, in which case this field is not
+automatically corrected.
+@end table
+@end deftp
+
+
+@node origin Reference
+@subsection @code{origin} Reference
+
+This section summarizes all the options available in @code{origin}
+declarations (@pxref{Defining Packages}).
+
+@deftp {Data Type} origin
+This is the data type representing a source code origin.
+
+@table @asis
+@item @code{uri}
+An object containing the URI of the source. The object type depends on
+the @code{method} (see below). For example, when using the
+@var{url-fetch} method of @code{(guix download)}, the valid @code{uri}
+values are: a URL represented as a string, or a list thereof.
+
+@item @code{method}
+A procedure that will handle the URI.
+
+Examples include:
+
+@table @asis
+@item @var{url-fetch} from @code{(guix download)}
+download a file the HTTP, HTTPS, or FTP URL specified in the
+@code{uri} field;
+
+@item @var{git-fetch} from @code{(guix git-download)}
+clone the Git version control repository, and check out the revision
+specified in the @code{uri} field as a @code{git-reference} object; a
+@code{git-reference} looks like this:
+
+@example
+(git-reference
+ (url "git://git.debian.org/git/pkg-shadow/shadow")
+ (commit "v4.1.5.1"))
+@end example
+@end table
+
+@item @code{sha256}
+A bytevector containing the SHA-256 hash of the source. Typically the
+@code{base32} form is used here to generate the bytevector from a
+base-32 string.
+
+@item @code{file-name} (default: @code{#f})
+The file name under which the source code should be saved. When this is
+@code{#f}, a sensible default value will be used in most cases. In case
+the source is fetched from a URL, the file name from the URL will be
+used. For version control checkouts, it's recommended to provide the
+file name explicitly because the default is not very descriptive.
+
+@item @code{patches} (default: @code{'()})
+A list of file names containing patches to be applied to the source.
+
+@item @code{snippet} (default: @code{#f})
+A quoted piece of code that will be run in the source directory to make
+any modifications, which is sometimes more convenient than a patch.
+
+@item @code{patch-flags} (default: @code{'("-p1")})
+A list of command-line flags that should be passed to the @code{patch}
+command.
+
+@item @code{patch-inputs} (default: @code{#f})
+Input packages or derivations to the patching process. When this is
+@code{#f}, the usual set of inputs necessary for patching are provided,
+such as GNU@tie{}Patch.
+
+@item @code{modules} (default: @code{'()})
+A list of Guile modules that should be loaded during the patching
+process and while running the code in the @code{snippet} field.
+
+@item @code{imported-modules} (default: @code{'()})
+The list of Guile modules to import in the patch derivation, for use by
+the @code{snippet}.
+
+@item @code{patch-guile} (default: @code{#f})
+The Guile package that should be used in the patching process. When
+this is @code{#f}, a sensible default is used.
+@end table
+@end deftp
+
@node Build Systems
@section Build Systems
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}.
+parameter which defaults to @code{ghc}.
@end defvr
Lastly, for packages that do not need anything as sophisticated, a
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
+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.)
+into gexps. For example, a useful type of high-level object that can be
+inserted in a gexp is ``file-like objects'', which make it easy to
+add files to the store and refer to them in
+derivations and such (see @code{local-file} and @code{plain-file}
+below.)
To illustrate the idea, here is an example of a gexp:
The other arguments are as for @code{derivation} (@pxref{Derivations}).
@end deffn
+@cindex file-like objects
+The @code{local-file} and @code{plain-file} procedures below return
+@dfn{file-like objects}. That is, when unquoted in a G-expression,
+these objects lead to a file in the store. Consider this G-expression:
+
+@example
+#~(system* (string-append #$glibc "/sbin/nscd") "-f"
+ #$(local-file "/tmp/my-nscd.conf"))
+@end example
+
+The effect here is to ``intern'' @file{/tmp/my-nscd.conf} by copying it
+to the store. Once expanded, for instance @i{via}
+@code{gexp->derivation}, the G-expression refers to that copy under
+@file{/gnu/store}; thus, modifying or removing the file in @file{/tmp}
+does not have any effect on what the G-expression does.
+@code{plain-file} can be used similarly; it differs in that the file
+content is directly passed as a string.
+
@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
procedure (@pxref{The Store Monad, @code{interned-file}}).
@end deffn
+@deffn {Scheme Procedure} plain-file @var{name} @var{content}
+Return an object representing a text file called @var{name} with the given
+@var{content} (a string) to be added to the store.
+
+This is the declarative counterpart of @code{text-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.
@item -E @var{command}
Execute @var{command} in the new environment.
+@item --ad-hoc
+Include all specified packages in the resulting environment, as if an
+@i{ad hoc} package were defined with them as inputs. This option is
+useful for quickly creating an environment without having to write a
+package expression to contain the desired inputs.
+
+For instance, the command:
+
+@example
+guix environment --ad-hoc guile guile-sdl -E guile
+@end example
+
+runs @command{guile} in an environment where Guile and Guile-SDL are
+available.
+
@item --pure
Unset existing environment variables when building the new environment.
This has the effect of creating an environment in which search paths
@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.
+their store with others, which can then use it as a substitute server
+(@pxref{Substitutes}).
+
+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 compatible with Hydra, the software behind
+the @code{hydra.gnu.org} build farm.
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.
+readable by the system administrator, it must be started as root; the
+@code{--user} option makes it drop root privileges early on.
The general syntax is:
@itemx -p @var{port}
Listen for HTTP requests on @var{port}.
+@item --listen=@var{host}
+Listen on the network interface for @var{host}. The default is to
+accept connections from any interface.
+
+@item --user=@var{user}
+@itemx -u @var{user}
+Change privileges to @var{user} as soon as possible---i.e., once the
+server socket is open and the signing key has been read.
+
@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).
+Reference Manual}) on @var{port} (37146 by default). This is used
+primarily for debugging a running @command{guix publish} server.
@end table
@c *********************************************************************
@chapter GNU Distribution
@cindex Guix System Distribution
-@cindex GSD
+@cindex GuixSD
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
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 the Guix
-System Distribution, or GNU@tie{}GSD.
+System Distribution, or GuixSD.
The distribution provides core GNU packages such as GNU libc, GCC, and
Binutils, as well as many GNU and non-GNU applications. The complete
@end table
-GSD itself is currently only available on @code{i686} and @code{x86_64}.
+GuixSD itself is currently only available on @code{i686} and @code{x86_64}.
@noindent
For information on porting to other architectures or kernels,
@subsection Limitations
-As of version @value{VERSION}, the Guix System Distribution (GSD) is
+As of version @value{VERSION}, the Guix System Distribution (GuixSD) 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 the GSD without fear, of course. In the meantime, you can
+to the GuixSD 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}).
(@pxref{Services}).
@item
-On the order of 1,200 packages are available, which means that you may
+On the order of 1,900 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
-@code{ftp://alpha.gnu.org/gnu/guix/gsd-usb-install-@value{VERSION}.@var{system}.xz},
+@indicateurl{ftp://alpha.gnu.org/gnu/guix/guixsd-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 gsd-usb-install-@value{VERSION}.@var{system}.xz
+xz -d guixsd-usb-install-@value{VERSION}.@var{system}.xz
@end example
@item
copy the image with:
@example
-dd if=gsd-usb-install-@value{VERSION}.x86_64 of=/dev/sdX
+dd if=guixsd-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 eno1} (to get an
-automatically assigned IP address from the wired network interface
-controller@footnote{
+Configure the network, by running @command{ifconfig eno1 up && dhclient
+eno1} (to get an automatically assigned IP address from the wired
+network interface 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
It is better to store that file on the target root file system, say, as
@file{/mnt/etc/config.scm}.
-A minimal operating system configuration, with just the bare minimum and
-only a root account would look like this (on the installation system,
-this example is available as @file{/etc/configuration-template.scm}):
-
-@example
-@include os-config.texi
-@end example
-
-@noindent
-For more information on @code{operating-system} declarations,
-@pxref{Using the Configuration System}.
+@xref{Using the Configuration System}, for examples of operating system
+configurations. These examples are available under
+@file{/etc/configuration} in the installation image, so you can copy
+them and use them as a starting point for your own configuration.
-Once that is done, the new system must be initialized (remember that the
-target root file system is mounted under @file{/mnt}):
+Once you are done preparing the configuration file, the new system must
+be initialized (remember that the target root file system is mounted
+under @file{/mnt}):
@example
guix system init /mnt/etc/config.scm /mnt
* Locales:: Language and cultural convention settings.
* Services:: Specifying system services.
* Setuid Programs:: Programs running with root privileges.
+* X.509 Certificates:: Authenticating HTTPS servers.
* Name Service Switch:: Configuring libc's name service switch.
* Initial RAM Disk:: Linux-Libre bootstrapping.
* GRUB Configuration:: Configuring the boot loader.
@findex operating-system
@lisp
-(use-modules (gnu) ; for 'user-account', '%base-services', etc.
- (gnu packages emacs) ; for 'emacs'
- (gnu services ssh)) ; for 'lsh-service'
-
-(operating-system
- (host-name "komputilo")
- (timezone "Europe/Paris")
- (locale "fr_FR.utf8")
- (bootloader (grub-configuration
- (device "/dev/sda")))
- (file-systems (cons (file-system
- (device "/dev/sda1") ; or partition label
- (mount-point "/")
- (type "ext3"))
- %base-file-systems))
- (users (list (user-account
- (name "alice")
- (group "users")
- (comment "Bob's sister")
- (home-directory "/home/alice"))))
- (packages (cons emacs %base-packages))
- (services (cons (lsh-service #:port 2222 #:root-login? #t)
- %base-services)))
+@include os-config-bare-bones.texi
@end lisp
This example should be self-describing. Some of the fields defined
Reference}, for details about the available @code{operating-system}
fields.
+The configuration for a typical ``desktop'' usage, with the X11 display
+server, a desktop environment, network management, an SSH server, and
+more, would look like this:
+
+@lisp
+@include os-config-desktop.texi
+@end lisp
+
+@xref{Desktop Services}, for the exact list of services provided by
+@var{%desktop-services}. @xref{X.509 Certificates}, for background
+information about the @code{nss-certs} package that is used here.
+
Assuming the above snippet is stored in the @file{my-system-config.scm}
file, the @command{guix system reconfigure my-system-config.scm} command
instantiates that configuration, and makes it the default GRUB boot
@table @asis
@item @code{kernel} (default: @var{linux-libre})
-The package object of the operating system to use@footnote{Currently
+The package object of the operating system kernel to use@footnote{Currently
only the Linux-libre kernel is supported. In the future, it will be
possible to use the GNU@tie{}Hurd.}.
(@pxref{Memory Concepts,,, libc, The GNU C Library Reference Manual}).
For example, @code{'("/dev/sda3")}.
-@item @code{users} (default: @code{'()})
+@item @code{users} (default: @code{%base-user-accounts})
@itemx @code{groups} (default: @var{%base-groups})
List of user accounts and groups. @xref{User Accounts}.
@item @code{sudoers} (default: @var{%sudoers-specification})
@cindex sudoers
-The contents of the @file{/etc/sudoers} file as a string.
+The contents of the @file{/etc/sudoers} file as a file-like object
+(@pxref{G-Expressions, @code{local-file} and @code{plain-file}}).
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
specific devices such as ``audio'', ``disk'', and ``cdrom''.
@end defvr
+@defvr {Scheme Variable} %base-user-accounts
+This is the list of basic system accounts that programs may expect to
+find on a GNU/Linux system, such as the ``nobody'' account.
+
+Note that the ``root'' account is not included here. It is a
+special-case and is automatically added whether or not it is specified.
+@end defvr
+
@node Locales
@subsection Locales
browsers, from accessing Facebook.
@end defvr
+The @code{(gnu services avahi)} provides the following definition.
+
+@deffn {Monadic Procedure} avahi-service [#:avahi @var{avahi}] @
+ [#:host-name #f] [#:publish? #t] [#:ipv4? #t] @
+ [#:ipv6? #t] [#:wide-area? #f] @
+ [#:domains-to-browse '()]
+Return a service that runs @command{avahi-daemon}, a system-wide
+mDNS/DNS-SD responder that allows for service discovery and
+"zero-configuration" host name lookups (see @uref{http://avahi.org/}).
+
+If @var{host-name} is different from @code{#f}, use that as the host name to
+publish for this machine; otherwise, use the machine's actual host name.
+
+When @var{publish?} is true, publishing of host names and services is allowed;
+in particular, avahi-daemon will publish the machine's host name and IP
+address via mDNS on the local network.
+
+When @var{wide-area?} is true, DNS-SD over unicast DNS is enabled.
+
+Boolean values @var{ipv4?} and @var{ipv6?} determine whether to use IPv4/IPv6
+sockets.
+@end deffn
+
+
@node X Window
@subsubsection X Window
turn starts the X display server with @var{startx}, a command as returned by
@code{xorg-start-command}.
+@cindex X session
+
+SLiM automatically looks for session types described by the @file{.desktop}
+files in @file{/run/current-system/profile/share/xsessions} and allows users
+to choose a session from the log-in screen using @kbd{F1}. Packages such as
+@var{xfce}, @var{sawfish}, and @var{ratpoison} provide @file{.desktop} files;
+adding them to the system-wide set of packages automatically makes them
+available at the log-in screen.
+
+In addition, @file{~/.xsession} files are honored. When available,
+@file{~/.xsession} must be an executable that starts a window manager
+and/or other X clients.
+
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}.
@end defvr
@deffn {Monadic Procedure} xorg-start-command [#:guile] @
- [#:drivers '()] [#:resolutions '()] [#:xorg-server @var{xorg-server}]
+ [#:configuration-file #f] [#: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.
+from @var{xorg-server}. @var{configuration-file} is the server configuration
+file or a derivation that builds it; when omitted, the result of
+@code{xorg-configuration-file} is used.
+
+Usually the X server is started by a login manager.
+@end deffn
+
+@deffn {Monadic Procedure} xorg-configuration-file @
+ [#:drivers '()] [#:resolutions '()] [#:extra-config '()]
+Return a configuration file for the Xorg server containing search paths for
+all the common drivers.
@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")}.
+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))}.
+
+Last, @var{extra-config} is a list of strings or objects appended to the
+@code{text-file*} argument list. It is used to pass extra text to be added
+verbatim to the configuration file.
@end deffn
@node Desktop Services
machine running a graphical display server, possibly with graphical user
interfaces, etc.
+To simplify things, the module defines a variable containing the set of
+services that users typically expect on a machine with a graphical
+environment and networking:
+
+@defvr {Scheme Variable} %desktop-services
+This is a list of services that builds upon @var{%base-services} and
+adds or adjust services for a typical ``desktop'' setup.
+
+In particular, it adds a graphical login manager (@pxref{X Window,
+@code{slim-service}}), a network management tool (@pxref{Networking
+Services, @code{wicd-service}}), energy and color management services,
+an NTP client and an SSH server (@pxref{Networking Services}), the Avahi
+daemon, and has the name service switch service configured to be able to
+use @code{nss-mdns} (@pxref{Name Service Switch, mDNS}).
+@end defvr
+
+The @var{%desktop-services} variable can be used as the @code{services}
+field of an @code{operating-system} declaration (@pxref{operating-system
+Reference, @code{services}}).
+
+The actual service definitions provided by @code{(gnu services desktop)}
+are described below.
+
@deffn {Monadic Procedure} dbus-service @var{services} @
[#:dbus @var{dbus}]
Return a service that runs the ``system bus'', using @var{dbus}, with
files in this directory refer to the ``real'' binaries, which are in the
store.
+@node X.509 Certificates
+@subsection X.509 Certificates
+
+@cindex HTTPS, certificates
+@cindex X.509 certificates
+@cindex TLS
+Web servers available over HTTPS (that is, HTTP over the transport-layer
+security mechanism, TLS) send client programs an @dfn{X.509 certificate}
+that the client can then use to @emph{authenticate} the server. To do
+that, clients verify that the server's certificate is signed by a
+so-called @dfn{certificate authority} (CA). But to verify the CA's
+signature, clients must have first acquired the CA's certificate.
+
+Web browsers such as GNU@tie{}IceCat include their own set of CA
+certificates, such that they are able to verify CA signatures
+out-of-the-box.
+
+However, most other programs that can talk HTTPS---@command{wget},
+@command{git}, @command{w3m}, etc.---need to be told where CA
+certificates can be found.
+
+@cindex @code{nss-certs}
+In GuixSD, this is done by adding a package that provides certificates
+to the @code{packages} field of the @code{operating-system} declaration
+(@pxref{operating-system Reference}). GuixSD includes one such package,
+@code{nss-certs}, which is a set of CA certificates provided as part of
+Mozilla's Network Security Services.
+
+Note that it is @emph{not} part of @var{%base-packages}, so you need to
+explicitly add it. The @file{/etc/ssl/certs} directory, which is where
+most applications and libraries look for certificates by default, points
+to the certificates installed globally.
+
+Unprivileged users can also install their own certificate package in
+their profile. A number of environment variables need to be defined so
+that applications and libraries know where to find them. Namely, the
+OpenSSL library honors the @code{SSL_CERT_DIR} and @code{SSL_CERT_FILE}
+variables. Some applications add their own environment variables; for
+instance, the Git version control system honors the certificate bundle
+pointed to by the @code{GIT_SSL_CAINFO} environment variable.
+
+
@node Name Service Switch
@subsection Name Service Switch
(name "mdns")))))
@end example
+Don't worry: the @code{%mdns-host-lookup-nss} variable (see below)
+contains this configuration, so you won't have to type it if all you
+want is to have @code{.local} host lookup working.
+
Note that, in this case, in addition to setting the
@code{name-service-switch} of the @code{operating-system} declaration,
@code{nscd-service} must be told where to find the @code{nss-mdns}
@noindent
@dots{} and then refer to @var{%my-base-services} instead of
@var{%base-services} in the @code{operating-system} declaration.
+Lastly, this relies on the availability of the Avahi service
+(@pxref{Networking Services, @code{avahi-service}}).
+
+For convenience, the following variables provide typical NSS
+configurations.
+
+@defvr {Scheme Variable} %default-nss
+This is the default name service switch configuration, a
+@code{name-service-switch} object.
+@end defvr
+
+@defvr {Scheme Variable} %mdns-host-lookup-nss
+This is the name service switch configuration with support for host name
+lookup over multicast DNS (mDNS) for host names ending in @code{.local}.
+@end defvr
The reference for name service switch configuration is given below. It
is a direct mapping of the C library's configuration file format, so
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
@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 GSD. For instance:
+installations of GuixSD. For instance:
@example
guix system init my-os-config.scm /mnt
of the given @var{size}. @var{size} may be a number of bytes, or it may
include a unit as a suffix (@pxref{Block size, size specifications,,
coreutils, GNU Coreutils}).
+
+@item --on-error=@var{strategy}
+Apply @var{strategy} when an error occurs when reading @var{file}.
+@var{strategy} may be one of the following:
+
+@table @code
+@item nothing-special
+Report the error concisely and exit. This is the default strategy.
+
+@item backtrace
+Likewise, but also display a backtrace.
+
+@item debug
+Report the error and enter Guile's debugger. From there, you can run
+commands such as @code{,bt} to get a backtrace, @code{,locals} to
+display local variable values, and more generally inspect the program's
+state. @xref{Debug Commands,,, guile, GNU Guile Reference Manual}, for
+a list of available debugging commands.
+@end table
@end table
Note that all the actions above, except @code{build} and @code{init},
@cindex package module search path
Users can store package definitions in modules with different
names---e.g., @code{(my-packages emacs)}@footnote{Note that the file
-name and module name must match. @xref{Modules and the File System,,,
-guile, GNU Guile Reference Manual}, for details.} These package definitions
+name and module name must match. For instance, the @code{(my-packages
+emacs)} module must be stored in a @file{my-packages/emacs.scm} file
+relative to the load path specified with @option{--load-path} or
+@code{GUIX_PACKAGE_PATH}. @xref{Modules and the File System,,,
+guile, GNU Guile Reference Manual}, for details.}. 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{-e} option so that they know where to find the package. Better
+yet, they can 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
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{Invoking guix build}). For example, assuming the new package is
-called @code{gnew}, you may run this command from the Guix build tree:
+called @code{gnew}, you may run this command from the Guix build tree
+(@pxref{Running Guix Before It Is Installed}):
@example
./pre-inst-env guix build gnew --keep-failed
HCoop / jackhill / guix / guix.git / blobdiff