* 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
instead, you want to install the complete GNU operating system,
@pxref{System Installation}.
-The build procedure for Guix is the same as for other GNU software, and
-is not covered here. Please see the files @file{README} and
-@file{INSTALL} in the Guix source tree for additional details.
-
@menu
+* 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.
@end menu
+@node Binary Installation
+@section Binary Installation
+
+This section describes how to install Guix on an arbitrary system from a
+self-contained tarball providing binaries for Guix and for all its
+dependencies. This is often quicker than installing from source, which
+is described in the next sections. The only requirement is to have
+GNU@tie{}tar and Xz.
+
+Installing goes along these lines:
+
+@enumerate
+@item
+Download the binary tarball from
+@code{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
+kernel Linux, and so on.
+
+@item
+As @code{root}, run:
+
+@example
+# cd /
+# tar xf guix-binary-@value{VERSION}.@var{system}.tar.xz
+@end example
+
+This creates @file{/gnu/store} (@pxref{The Store}), @file{/var/guix},
+and @file{/root/.guix-profile}. @file{/root/.guix-profile} is a
+ready-to-use profile for @code{root} where Guix is installed.
+
+Do @emph{not} unpack the tarball on a working Guix system since that
+would overwrite its own essential files.
+
+@item
+Set up the daemon as explained below (@pxref{Setting Up the Daemon}), and
+run it:
+
+@example
+# /root/.guix-profile/bin/guix-daemon --build-users-group=guix-builder
+@end example
+
+@item
+Make the @command{guix} command available to other users on the machine,
+for instance with:
+
+@example
+# mkdir -p /usr/local/bin
+# cd /usr/local/bin
+# ln -s /root/.guix-profile/bin/guix
+@end example
+@end enumerate
+
+And that's it!
+
+The @code{guix} package must remain available in @code{root}'s
+profile, or it would become subject to garbage collection---in which
+case you would find yourself badly handicapped by the lack of the
+@command{guix} command.
+
+The tarball in question can be (re)produced simply by running the
+following command in the Guix source tree:
+
+@example
+make guix-binary.@var{system}.tar.xz
+@end example
+
+
@node Requirements
@section Requirements
+This section lists requirements when building Guix from source. The
+build procedure for Guix is the same as for other GNU software, and is
+not covered here. Please see the files @file{README} and @file{INSTALL}
+in the Guix source tree for additional details.
+
GNU Guix depends on the following packages:
@itemize
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:
Each @var{package} may specify either a simple package name, such as
@code{guile}, or a package name followed by a hyphen and version number,
-such as @code{guile-1.8.8}. If no version number is specified, the
+such as @code{guile-1.8.8} or simply @code{guile-1.8} (in the latter
+case, the newest version prefixed by @code{1.8} is selected.)
+
+If no version number is specified, the
newest available version will be selected. In addition, @var{package}
may contain a colon, followed by the name of one of the outputs of the
package, as in @code{gcc:doc} or @code{binutils-2.22:lib}
@itemx -u [@var{regexp} @dots{}]
Upgrade all the installed packages. If one or more @var{regexp}s are
specified, upgrade only installed packages whose name matches a
-@var{regexp}.
+@var{regexp}. Also see the @code{--do-not-upgrade} option below.
Note that this upgrades package to the latest version of packages found
in the distribution currently installed. To update your distribution,
you should regularly run @command{guix pull} (@pxref{Invoking guix
pull}).
+@item --do-not-upgrade[=@var{regexp} @dots{}]
+When used together with the @code{--upgrade} option, do @emph{not}
+upgrade any packages whose name matches a @var{regexp}. For example, to
+upgrade all packages in the current profile except those containing the
+substring ``emacs'':
+
+@example
+$ guix package --upgrade . --do-not-upgrade emacs
+@end example
+
@item --roll-back
Roll back to the previous @dfn{generation} of the profile---i.e., undo
the last transaction.
@item --search=@var{regexp}
@itemx -s @var{regexp}
-List the available packages whose synopsis or description matches
+List the available packages whose name, synopsis, or description matches
@var{regexp}. Print all the meta-data of matching packages in
@code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
GNU recutils manual}).
@item --list-available[=@var{regexp}]
@itemx -A [@var{regexp}]
-List packages currently available in the software distribution
+List packages currently available in the distribution for this system
(@pxref{GNU Distribution}). When @var{regexp} is specified, list only
installed packages whose name matches @var{regexp}.
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
@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,
#~(begin
(mkdir #$output)
(chdir #$output)
- (symlink (string-append #$coreutils "/bin/ls")
+ (symlink (string-append #$coreutils "/bin/ls")
"list-files")))
@end example
* 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
@example
guix import nix ~/path/to/nixpkgs libreoffice
@end example
+
+@item hackage
+@cindex hackage
+Import meta-data from Haskell community's central package archive
+@uref{https://hackage.haskell.org/, Hackage}. Information is taken from
+Cabal files and includes all the relevant information, including package
+dependencies.
+
+Specific command-line options are:
+
+@table @code
+@item --no-test-dependencies
+@itemx -t
+Do not include dependencies only required to run the test suite.
+@end table
+
+The command below imports meta-data for the latest version of the
+@code{HTTP} Haskell package without including test dependencies:
+
+@example
+guix import hackage -t HTTP
+@end example
+
+A specific package version may optionally be specified by following the
+package name by a hyphen and a version number as in the following example:
+
+@example
+guix import hackage mtl-2.1.3.1
+@end example
+
+Currently only indentation structured Cabal files are supported.
@end table
The structure of the @command{guix import} code is modular. It would be
names, as in this example:
@example
-guix refresh -u emacs idutils
+guix refresh -u emacs idutils gcc-4.8.4
@end example
@noindent
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
(comment "Bob's sister")
(home-directory "/home/alice"))))
(packages (cons emacs %base-packages))
- (services (cons (lsh-service #:port 2222 #:root-login? #t
- #:initialize? #t)
+ (services (cons (lsh-service #:port 2222 #:root-login? #t)
%base-services)))
@end lisp
@defvr {Scheme Variable} %base-file-systems
These are essential file systems that are required on normal systems,
-such as @var{%devtmpfs-file-system} (see below.) Operating system
-declarations should always contain at least these.
+such as @var{%devtmpfs-file-system} and @var{%immutable-store} (see
+below.) Operating system declarations should always contain at least
+these.
@end defvr
@defvr {Scheme Variable} %devtmpfs-file-system
@code{shm_open},, libc, The GNU C Library Reference Manual}).
@end defvr
+@defvr {Scheme Variable} %immutable-store
+This file system performs a read-only ``bind mount'' of
+@file{/gnu/store}, making it read-only for all the users including
+@code{root}. This prevents against accidental modification by software
+running as @code{root} or by system administrators.
+
+The daemon itself is still able to write to the store: it remounts it
+read-write in its own ``name space.''
+@end defvr
+
@defvr {Scheme Variable} %binary-format-file-system
The @code{binfmt_misc} file system, which allows handling of arbitrary
executable file types to be delegated to user space. This requires the
@node User Accounts
@subsection User Accounts
-User accounts are specified with the @code{user-account} form:
+User accounts and groups are entirely managed through the
+@code{operating-system} declaration. They are specified with the
+@code{user-account} and @code{user-group} forms:
@example
(user-account
(home-directory "/home/alice"))
@end example
+When booting or upon completion of @command{guix system reconfigure},
+the system ensures that only the user accounts and groups specified in
+the @code{operating-system} declaration exist, and with the specified
+properties. Thus, account or group creations or modifications made by
+directly invoking commands such as @command{useradd} are lost upon
+reconfiguration or reboot. This ensures that the system remains exactly
+as declared.
+
@deftp {Data Type} user-account
Objects of this type represent user accounts. The following members may
be specified:
@item @code{password} (default: @code{#f})
You would normally leave this field to @code{#f}, initialize user
passwords as @code{root} with the @command{passwd} command, and then let
-users change it with @command{passwd}.
+users change it with @command{passwd}. Passwords set with
+@command{passwd} are of course preserved across reboot and
+reconfiguration.
If you @emph{do} want to have a preset password for an account, then
this field must contain the encrypted password, as a string.
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.
+name service switch (NSS) modules needed by nscd. @xref{Name Service
+Switch}, for an example.
@end deffn
@defvr {Scheme Variable} %nscd-default-configuration
[#: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.
passed to @command{lircd}.
@end deffn
+@code{(gnu services upower)} provides a power-management daemon:
+
+@deffn {Monadic Procedure} upower-service [#:upower @var{upower}] @
+ [#:watts-up-pro? #f] @
+ [#:poll-batteries? #t] @
+ [#:ignore-lid? #f] @
+ [#:use-percentage-for-policy? #f] @
+ [#:percentage-low 10] @
+ [#:percentage-critical 3] @
+ [#:percentage-action 2] @
+ [#:time-low 1200] @
+ [#:time-critical 300] @
+ [#:time-action 120] @
+ [#:critical-power-action 'hybrid-sleep]
+Return a service that runs @uref{http://upower.freedesktop.org/,
+@command{upowerd}}, a system-wide monitor for power consumption and battery
+levels, with the given configuration settings. It implements the
+@code{org.freedesktop.UPower} D-Bus interface, and is notably used by
+GNOME.
+@end deffn
+
+@code{(gnu services colord)} provides a color management service:
+
+@deffn {Monadic Procedure} colord-service [#:colord @var{colord}]
+Return a service that runs @command{colord}, a system service with a D-Bus
+interface to manage the color profiles of input and output devices such as
+screens and scanners. It is notably used by the GNOME Color Manager graphical
+tool. See @uref{http://www.freedesktop.org/software/colord/, the colord web
+site} for more information.
+@end deffn
+
@node Setuid Programs
@subsection Setuid Programs
@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/>.
+@cindex nss-mdns
+@cindex .local, host name lookup
As an example, the declaration below configures the NSS to use the
-@code{nss-mdns} back-end for host name lookups:
+@uref{http://0pointer.de/lennart/projects/nss-mdns/, @code{nss-mdns}
+back-end}, which supports host name lookups over multicast DNS (mDNS)
+for host names ending in @code{.local}:
@example
(name-service-switch
(name "mdns")))))
@end example
+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}
+shared library (@pxref{Base Services, @code{nscd-service}}). Since the
+@code{nscd} service is part of @var{%base-services}, you may want to
+customize it by adding this snippet in the operating system
+configuration file:
+
+@example
+(use-modules (guix) (gnu))
+
+(define %my-base-services
+ ;; Replace the default nscd service with one that knows
+ ;; about nss-mdns.
+ (map (lambda (mservice)
+ ;; "Bind" the MSERVICE monadic value to inspect it.
+ (mlet %store-monad ((service mservice))
+ (if (member 'nscd (service-provision service))
+ (nscd-service (nscd-configuration)
+ #:name-services (list nss-mdns))
+ mservice)))
+ %base-services))
+@end example
+
+@noindent
+@dots{} and then refer to @var{%my-base-services} instead of
+@var{%base-services} in the @code{operating-system} declaration.
+
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
@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