Copyright @copyright{} 2012, 2013, 2014, 2015, 2016 Ludovic Courtès@*
Copyright @copyright{} 2013, 2014, 2016 Andreas Enge@*
Copyright @copyright{} 2013 Nikita Karetnikov@*
-Copyright @copyright{} 2015 Mathieu Lirzin@*
+Copyright @copyright{} 2015, 2016 Mathieu Lirzin@*
Copyright @copyright{} 2014 Pierre-Antoine Rault@*
Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@*
Copyright @copyright{} 2015, 2016 Leo Famulari
+Copyright @copyright{} 2016 Ben Woodcroft
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
Documentation License''.
@end copying
-@dircategory Package management
+@dircategory System administration
@direntry
-* guix: (guix). Guix, the functional package manager.
-* guix package: (guix)Invoking guix package
- Managing packages with Guix.
-* guix build: (guix)Invoking guix build
- Building packages with Guix.
-* guix system: (guix)Invoking guix system
- Managing the operating system configuration.
+* Guix: (guix). Manage installed software and system configuration.
+* guix package: (guix)Invoking guix package. Installing, removing, and upgrading packages.
+* guix build: (guix)Invoking guix build. Building packages.
+* guix gc: (guix)Invoking guix gc. Reclaiming unused disk space.
+* guix pull: (guix)Invoking guix pull. Update the list of available packages.
+* guix system: (guix)Invoking guix system. Manage the operating system configuration.
@end direntry
@dircategory Software development
@direntry
-* guix environment: (guix)Invoking guix environment
- Building development environments with Guix.
+* guix environment: (guix)Invoking guix environment. Building development environments with Guix.
@end direntry
+@dircategory Emacs
+@direntry
+* Guix user interface: (guix)Emacs Interface. Package management from the comfort of Emacs.
+@end direntry
+
+
@titlepage
@title GNU Guix Reference Manual
@subtitle Using the GNU Guix Functional Package Manager
(@pxref{Build Environment Setup}).
@item
-Run the daemon:
+Run the daemon, and set it to automatically start on boot.
+
+If your host distro uses the systemd init system, this can be achieved
+with these commands:
@example
-# ~root/.guix-profile/bin/guix-daemon --build-users-group=guixbuild
+# cp ~root/.guix-profile/lib/systemd/system/guix-daemon.service \
+ /etc/systemd/system/
+# systemctl start guix-daemon && systemctl enable guix-daemon
+@end example
+
+If your host distro uses the Upstart init system:
+
+@example
+# cp ~root/.guix-profile/lib/upstart/system/guix-daemon.conf /etc/init/
+# start guix-daemon
@end example
-On hosts using the systemd init system, drop
-@file{~root/.guix-profile/lib/systemd/system/guix-daemon.service} in
-@file{/etc/systemd/system}.
+Otherwise, you can still start the daemon manually with:
-Likewise, on hosts using the Upstart init system, drop
-@file{~root/.guix-profile/lib/upstart/system/guix-daemon.conf} in
-@file{/etc/init}.
+@example
+# ~root/.guix-profile/bin/guix-daemon --build-users-group=guixbuild
+@end example
@item
Make the @command{guix} command available to other users on the machine,
@end example
@end enumerate
-And that's it! For additional tips and tricks, @pxref{Application
-Setup}.
+This completes root-level install of Guix. Each user will need to
+perform additional steps to make their Guix envionment ready for use,
+@pxref{Application Setup}.
+
+You can confirm that Guix is working by installing a sample package into
+the root profile:
+
+@example
+# guix package -i hello
+@end example
-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 @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. In other words, do not remove @code{guix} by running
+@code{guix package -r guix}.
-The tarball in question can be (re)produced and verified simply by
-running the following command in the Guix source tree:
+The binary installation tarball can be (re)produced and verified simply
+by running the following command in the Guix source tree:
@example
make guix-binary.@var{system}.tar.xz
Install the specified @var{package}s.
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} or simply @code{guile-1.8} (in the latter
+@code{guile}, or a package name followed by an at-sign and version number,
+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}
+package, as in @code{gcc:doc} or @code{binutils@@2.22:lib}
(@pxref{Packages with Multiple Outputs}). Packages with a corresponding
name (and optionally version) are searched for among the GNU
distribution modules (@pxref{Package Modules}).
versions from this just-retrieved copy of Guix. Not only that, but all
the Guix commands and Scheme modules will also be taken from that latest
version. New @command{guix} sub-commands added by the update also
-become available@footnote{Under the hood, @command{guix pull} updates
-the @file{~/.config/guix/latest} symbolic link to point to the latest
-Guix, and the @command{guix} command loads code from there.}.
+become available.
+
+Any user can update their Guix copy using @command{guix pull}, and the
+effect is limited to the user who run @command{guix pull}. For
+instance, when user @code{root} runs @command{guix pull}, this has no
+effect on the version of Guix that user @code{alice} sees, and vice
+versa@footnote{Under the hood, @command{guix pull} updates the
+@file{~/.config/guix/latest} symbolic link to point to the latest Guix,
+and the @command{guix} command loads code from there.}.
The @command{guix pull} command is usually invoked with no arguments,
but it supports the following options:
argument.
@deffn {Scheme Procedure} valid-path? @var{server} @var{path}
-Return @code{#t} when @var{path} is a valid store path.
+@cindex invalid store items
+Return @code{#t} when @var{path} designates a valid store item and
+@code{#f} otherwise (an invalid item may exist on disk but still be
+invalid, for instance because it is the result of an aborted or failed
+build.)
+
+A @code{&nix-protocol-error} condition is raised if @var{path} is not
+prefixed by the store directory (@file{/gnu/store}).
@end deffn
@deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} [@var{references}]
locally instead of allowing downloads of pre-built binaries
(@pxref{Substitutes}).
+@item --no-grafts
+Do not ``graft'' packages. In practice, this means that package updates
+available as grafts are not applied. @xref{Security Updates}, for more
+information on grafts.
+
@item --rounds=@var{n}
Build each derivation @var{n} times in a row, and raise an error if
consecutive build results are not bit-for-bit identical.
of a package is deterministic. @xref{Invoking guix challenge}, for more
background information and tools.
-@item --no-grafts
-Do not ``graft'' packages. In practice, this means that package updates
-available as grafts are not applied. @xref{Security Updates}, for more
-information on grafts.
-
@item --derivations
@itemx -d
Return the derivation paths, not the output paths, of the given
@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:
+package name by an at-sign and a version number as in the following example:
@example
-guix import hackage mtl-2.1.3.1
+guix import hackage mtl@@2.1.3.1
@end example
@item elpa
the updater for @uref{https://pypi.python.org, PyPI} packages.
@item gem
the updater for @uref{https://rubygems.org, RubyGems} packages.
+@item github
+the updater for @uref{https://github.com, GitHub} packages.
@end table
For instance, the following command only checks for updates of Emacs
@end table
+The @code{github} updater uses the
+@uref{https://developer.github.com/v3/, GitHub API} to query for new
+releases. When used repeatedly e.g. when refreshing all packages,
+GitHub will eventually refuse to answer any further API requests. By
+default 60 API requests per hour are allowed, and a full refresh on all
+GitHub packages in Guix requires more than this. Authentication with
+GitHub through the use of an API token alleviates these limits. To use
+an API token, set the environment variable @code{GUIX_GITHUB_TOKEN} to a
+token procured from @uref{https://github.com/settings/tokens} or
+otherwise.
+
+
@node Invoking guix lint
@section Invoking @command{guix lint}
The @command{guix lint} command is meant to help package developers avoid
@code{device} is interpreted as a partition unique identifier (UUID).
UUIDs may be converted from their string representation (as shown by the
-@command{tune2fs -l} command) using the @code{uuid} form, like this:
+@command{tune2fs -l} command) using the @code{uuid} form@footnote{The
+@code{uuid} form expects 16-byte UUIDs as defined in
+@uref{https://tools.ietf.org/html/rfc4122, RFC@tie{}4122}. This is the
+form of UUID used by the ext2 family of file systems and others, but it
+is different from ``UUIDs'' found in FAT file systems, for instance.},
+like this:
@example
(file-system
@end defvr
-@deffn {Scheme 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
+@deffn {Scheme Procedure} syslog-service @
+ [#:config-file @var{%default-syslog.conf}]
+Return a service that runs @command{syslogd}. If configuration file
+name @var{config-file} is not specified, use some reasonable default
settings.
+
+@xref{syslogd invocation,,, inetutils, GNU Inetutils}, for more
+information on the configuration file syntax.
@end deffn
@anchor{guix-configuration-type}
@var{file} must be the name of a file containing an
@code{operating-system} declaration. @var{action} specifies how the
-operating system is instantiate. Currently the following values are
+operating system is instantiated. Currently the following values are
supported:
@table @code
@end table
@node Running GuixSD in a VM
-@subsection Running GuixSD in a virtual machine
+@subsection Running GuixSD in a Virtual Machine
One way to run GuixSD in a virtual machine (VM) is to build a GuixSD
virtual machine image using @command{guix system vm-image}
Udev extensions are composed into a list of rules, but the udev service
value is itself a @code{<udev-configuration>} record. So here, we
-extend that record by appending the list of rules is contains to the
+extend that record by appending the list of rules it contains to the
list of contributed rules.
@end table
@cindex PID 1
@cindex init system
-The @code{(gnu services shepherd)} provides a way to define services
-managed by the GNU@tie{}Shepherd, which is GuixSD initialization
-system---the first process that is started when the system boots,
-aka. PID@tie{}1 (@pxref{Introduction,,, shepherd, The GNU Shepherd
-Manual}).
+The @code{(gnu services shepherd)} module provides a way to define
+services managed by the GNU@tie{}Shepherd, which is the GuixSD
+initialization system---the first process that is started when the
+system boots, aka. PID@tie{}1 (@pxref{Introduction,,, shepherd, The GNU
+Shepherd Manual}).
Services in the Shepherd can depend on each other. For instance, the
SSH daemon may need to be started after the syslog daemon has been
(replacement bash-fixed)))
@end example
-From there on, any package depending directly or indirectly on Bash that
-is installed will automatically be ``rewritten'' to refer to
+From there on, any package depending directly or indirectly on Bash---as
+reported by @command{guix gc --requisites} (@pxref{Invoking guix
+gc})---that is installed is automatically ``rewritten'' to refer to
@var{bash-fixed} instead of @var{bash}. This grafting process takes
time proportional to the size of the package, but expect less than a
-minute for an ``average'' package on a recent machine.
+minute for an ``average'' package on a recent machine. Grafting is
+recursive: when an indirect dependency requires grafting, then grafting
+``propagates'' up to the package that the user is installing.
Currently, the graft and the package it replaces (@var{bash-fixed} and
@var{bash} in the example above) must have the exact same @code{name}
HCoop / jackhill / guix / guix.git / blobdiff