Copyright @copyright{} 2012, 2013, 2014, 2015 Ludovic Courtès@*
Copyright @copyright{} 2013, 2014 Andreas Enge@*
Copyright @copyright{} 2013 Nikita Karetnikov@*
+Copyright @copyright{} 2015 Mathieu Lirzin@*
+Copyright @copyright{} 2014 Pierre-Antoine Rault@*
Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer
Permission is granted to copy, distribute and/or modify this document
@titlepage
@title GNU Guix Reference Manual
@subtitle Using the GNU Guix Functional Package Manager
-@author Ludovic Courtès
-@author Andreas Enge
-@author Nikita Karetnikov
+@author The GNU Guix Developers
@page
@vskip 0pt plus 1filll
* Introduction:: What is Guix about?
* Installation:: Installing Guix.
* Package Management:: Package installation, upgrade, etc.
+* Emacs Interface:: Using Guix from Emacs.
* Programming Interface:: Using Guix in Scheme.
* Utilities:: Package management commands.
* GNU Distribution:: Software for your friendly GNU system.
* 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.
+* Application Setup:: Application-specific setup.
Setting Up the Daemon
* Features:: How Guix will make your life brighter.
* Invoking guix package:: Package installation, removal, etc.
-* Emacs Interface:: Package management from Emacs.
* Substitutes:: Downloading pre-built binaries.
* Packages with Multiple Outputs:: Single source package, multiple outputs.
* Invoking guix gc:: Running the garbage collector.
* Invoking guix pull:: Fetching the latest Guix and distribution.
* Invoking guix archive:: Exporting and importing store files.
+Emacs Interface
+
+* Initial Setup: Emacs Initial Setup. Preparing @file{~/.emacs}.
+* Package Management: Emacs Package Management. Managing packages and generations.
+* Popup Interface: Emacs Popup Interface. Magit-like interface for guix commands.
+* Prettify Mode: Emacs Prettify. Abbreviating @file{/gnu/store/@dots{}} file names.
+* Build Log Mode: Emacs Build Log. Highlighting Guix build logs.
+* Completions: Emacs Completions. Completing @command{guix} shell command.
+
Programming Interface
* Defining Packages:: Defining new packages.
Utilities
* Invoking guix build:: Building packages from the command line.
+* Invoking guix edit:: Editing package definitions.
* Invoking guix download:: Downloading a file and printing its hash.
* Invoking guix hash:: Computing the cryptographic hash of a file.
* Invoking guix import:: Importing package definitions.
* Invoking guix refresh:: Updating package definitions.
* Invoking guix lint:: Finding errors in package definitions.
+* Invoking guix size:: Profiling disk usage.
+* Invoking guix graph:: Visualizing the graph of packages.
* Invoking guix environment:: Setting up development environments.
* Invoking guix publish:: Sharing substitutes.
* X Window:: Graphical display.
* Desktop Services:: D-Bus and desktop services.
* Database Services:: SQL databases.
+* Web Services:: Web servers.
* 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.
+* Synopses and Descriptions:: Helping users find the right package.
* Python Modules:: Taming the snake.
* Perl Modules:: Little pearls.
* Fonts:: Fond of fonts.
+Contributing
+
+* Building from Git:: The latest and greatest.
+* Running Guix Before It Is Installed:: Hacker tricks.
+* The Perfect Setup:: The right tools.
+* Coding Style:: Hygiene of the contributor.
+* Submitting Patches:: Share your work.
+
+Coding Style
+
+* Programming Paradigm:: How to compose your elements.
+* Modules:: Where to store your code?
+* Data Types and Pattern Matching:: Implementing data structures.
+* Formatting Code:: Writing conventions.
+
@end detailmenu
@end menu
* 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.
+* Application Setup:: Application-specific setup.
@end menu
@node Binary Installation
As @code{root}, run:
@example
-# cd /
-# tar xf guix-binary-@value{VERSION}.@var{system}.tar.xz
+# cd /tmp
+# tar --warning=no-timestamp -xf \
+ guix-binary-@value{VERSION}.@var{system}.tar.xz
+# mv var/guix /var/ && mv gnu /
@end example
This creates @file{/gnu/store} (@pxref{The Store}) and @file{/var/guix}.
Do @emph{not} unpack the tarball on a working Guix system since that
would overwrite its own essential files.
+The @code{--warning=no-timestamp} option makes sure GNU@tie{}tar does
+not emit warnings about ``implausibly old time stamps'' (such
+warnings were triggered by GNU@tie{}tar 1.26 and older; recent
+versions are fine.)
+They stem from the fact that all the
+files in the archive have their modification time set to zero (which
+means January 1st, 1970.) This is done on purpose to make sure the
+archive content is independent of its creation time, thus making it
+reproducible.
+
@item
Make @code{root}'s profile available under @file{~/.guix-profile}:
~root/.guix-profile
@end example
+@item
+Create the group and user accounts for build users as explained below
+(@pxref{Build Environment Setup}).
+
@item
Run the daemon:
# ~root/.guix-profile/bin/guix-daemon --build-users-group=guixbuild
@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}.
+
@item
Make the @command{guix} command available to other users on the machine,
for instance with:
@end example
@end enumerate
-And that's it!
+And that's it! For additional tips and tricks, @pxref{Application
+Setup}.
The @code{guix} package must remain available in @code{root}'s
profile, or it would become subject to garbage collection---in which
@noindent
The number of build users determines how many build jobs may run in
parallel, as specified by the @option{--max-jobs} option
-(@pxref{Invoking guix-daemon, @option{--max-jobs}}).
-The @code{guix-daemon} program may then be run as @code{root} with:
+(@pxref{Invoking guix-daemon, @option{--max-jobs}}). The
+@code{guix-daemon} program may then be run as @code{root} with the
+following command@footnote{If your machine uses the systemd init system,
+dropping the @file{@var{prefix}/lib/systemd/system/guix-daemon.service}
+file in @file{/etc/systemd/system} will ensure that
+@command{guix-daemon} is automatically started.}:
@example
# guix-daemon --build-users-group=guixbuild
(user "alice")
(private-key
(string-append (getenv "HOME")
- "/.ssh/id-rsa-for-guix"))))
+ "/.lsh/identity-for-guix"))))
@end example
@noindent
@item private-key
The SSH private key file to use when connecting to the machine.
+Currently offloading uses GNU@tie{}lsh as its SSH client
+(@pxref{Invoking lsh,,, GNU lsh Manual}). Thus, the key file here must
+be an lsh key file. This may change in the future, though.
+
@item parallel-builds
The number of builds that may run in parallel on the machine (1 by
default.)
The @code{guix} command must be in the search path on the build
machines, since offloading works by invoking the @code{guix archive} and
-@code{guix build} commands.
+@code{guix build} commands. In addition, the Guix modules must be in
+@code{$GUILE_LOAD_PATH} on the build machine---you can check whether
+this is the case by running:
+
+@example
+lsh build-machine guile -c '(use-modules (guix config))'
+@end example
There's one last thing to do once @file{machines.scm} is in place. As
explained above, when offloading, files are transferred back and forth
-between the machine stores. For this to work, you need to generate a
-key pair to allow the daemon to export signed archives of files from the
-store (@pxref{Invoking guix archive}):
+between the machine stores. For this to work, you first need to
+generate a key pair on each machine to allow the daemon to export signed
+archives of files from the store (@pxref{Invoking guix archive}):
@example
# guix archive --generate-key
@end example
@noindent
-Thus, when receiving files, a machine's build daemon can make sure they
-are genuine, have not been tampered with, and that they are signed by an
-authorized key.
+Each build machine must authorize the key of the master machine so that
+it accepts store items it receives from the master:
+
+@example
+# guix archive --authorize < master-public-key.txt
+@end example
+
+@noindent
+Likewise, the master machine must authorize the key of each build machine.
+
+All the fuss with keys is here to express pairwise mutual trust
+relations between the master and the build machines. Concretely, when
+the master receives files from a build machine (and @i{vice versa}), its
+build daemon can make sure they are genuine, have not been tampered
+with, and that they are signed by an authorized key.
@node Invoking guix-daemon
remote procedure call (@pxref{The Store}).
@item --substitute-urls=@var{urls}
+@anchor{daemon-substitute-urls}
Consider @var{urls} the default whitespace-separated list of substitute
source URLs. When this option is omitted, @indicateurl{http://hydra.gnu.org}
is used.
By default, files added to the store are automatically ``deduplicated'':
if a newly added file is identical to another one found in the store,
the daemon makes the new file a hard link to the other file. This can
-noticeably reduce disk usage, at the expense of slightly increasde
+noticeably reduce disk usage, at the expense of slightly increased
input/output load at the end of a build process. This option disables
this optimization.
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.
+@node Application Setup
+@section Application Setup
-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:
+When using Guix on top of GNU/Linux distribution other than GuixSD, a
+few additional steps are needed to get everything in place. Here are
+some of them.
-@example
-$ sudo ./pre-inst-env guix-daemon --build-users-group=guixbuild
-$ ./pre-inst-env guix build hello
-@end example
+@subsection Locales
-@noindent
-Similarly, for a Guile session using the Guix modules:
+@anchor{locales-and-locpath}
+@cindex locales, when not on GuixSD
+@vindex LOCPATH
+Packages installed @i{via} Guix will not use the host system's locale
+data. Instead, you must first install one of the locale packages
+available with Guix and then define the @code{LOCPATH} environment
+variable (@pxref{Locale Names, @code{LOCPATH},, libc, The GNU C Library
+Reference Manual}):
@example
-$ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
+$ guix package -i glibc-locales
+$ export LOCPATH=$HOME/.guix-profile/lib/locale
@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}.
+Note that the @code{glibc-locales} package contains data for all the
+locales supported by the GNU@tie{}libc and weighs in at around
+110@tie{}MiB. Alternately, the @code{glibc-utf8-locales} is smaller but
+limited to a few UTF-8 locales.
-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:
+@subsection X11 Fonts
-@lisp
-;; Assuming the Guix checkout is in ~/src/guix.
-(add-to-list 'geiser-guile-load-path "~/src/guix")
-@end lisp
+The majority of graphical applications use Fontconfig to locate and
+load fonts and perform X11-client-side rendering. Guix's
+@code{fontconfig} package looks for fonts in @file{$HOME/.guix-profile}
+by default. Thus, to allow graphical applications installed with Guix
+to display fonts, you will have to install fonts with Guix as well.
+Essential font packages include @code{gs-fonts}, @code{font-dejavu}, and
+@code{font-gnu-freefont-ttf}.
+@c TODO What else?
@c *********************************************************************
@node Package Management
This chapter describes the main features of Guix, as well as the package
management tools it provides. Two user interfaces are provided for
-routine package management tasks: a command-line interface
-(@pxref{Invoking guix package, @code{guix package}}), and a visual user
-interface in Emacs (@pxref{Emacs Interface}).
+routine package management tasks: A command-line interface described below
+(@pxref{Invoking guix package, @code{guix package}}), as well as a visual user
+interface in Emacs described in a subsequent chapter (@pxref{Emacs Interface}).
@menu
* Features:: How Guix will make your life brighter.
* Invoking guix package:: Package installation, removal, etc.
-* Emacs Interface:: Package management from Emacs.
* Substitutes:: Downloading pre-built binaries.
* Packages with Multiple Outputs:: Single source package, multiple outputs.
* Invoking guix gc:: Running the garbage collector.
package, which may be insufficient when needing a specific output of a
multiple-output package.
+@item --install-from-file=@var{file}
+@itemx -f @var{file}
+Install the package that the code within @var{file} evaluates to.
+
+As an example, @var{file} might contain a definition like this
+(@pxref{Defining Packages}):
+
+@example
+@verbatiminclude package-hello.scm
+@end example
+
+Developers may find it useful to include such a @file{package.scm} file
+in the root of their project's source tree that can be used to test
+development snapshots and create reproducible development environments
+(@pxref{Invoking guix environment}).
+
@item --remove=@var{package} @dots{}
@itemx -r @var{package} @dots{}
Remove the specified @var{package}s.
processes, it supports all the common build options that @command{guix
build} supports (@pxref{Invoking guix build, common build options}).
-@include emacs.texi
-
@node Substitutes
@section Substitutes
The @code{hydra.gnu.org} server is a front-end to a build farm that
builds packages from the GNU distribution continuously for some
architectures, and makes them available as substitutes. This is the
-default source of substitutes; it can be overridden by passing
-@command{guix-daemon} the @code{--substitute-urls} option
-(@pxref{Invoking guix-daemon}).
+default source of substitutes; it can be overridden by passing the
+@option{--substitute-urls} option either to @command{guix-daemon}
+(@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}})
+or to client tools such as @command{guix package}
+(@pxref{client-substitute-urls,, client @option{--substitute-urls}
+option}).
@cindex security
@cindex digital signatures
library, whereas the latter depend on Tcl/Tk and the underlying X
libraries. In this case, we leave the command-line tools in the default
output, whereas the GUIs are in a separate output. This allows users
-who do not need the GUIs to save space.
+who do not need the GUIs to save space. The @command{guix size} command
+can help find out about such situations (@pxref{Invoking guix size}).
+@command{guix graph} can also be helpful (@pxref{Invoking guix graph}).
There are several such multiple-output packages in the GNU distribution.
Other conventional output names include @code{lib} for libraries and
@item --requisites
@itemx -R
+@cindex closure
List the requisites of the store files passed as arguments. Requisites
include the store files themselves, their references, and the references
of these, recursively. In other words, the returned list is the
@dfn{transitive closure} of the store files.
+@xref{Invoking guix size}, for a tool to profile the size of an
+element's closure. @xref{Invoking guix graph}, for a tool to visualize
+the graph of references.
+
@end table
Lastly, the following options allow you to check the integrity of the
same options that can be passed to the @command{guix build} command
(@pxref{Invoking guix build, common build options}).
+@c *********************************************************************
+@include emacs.texi
@c *********************************************************************
@node Programming Interface
#:use-module (guix packages)
#:use-module (guix download)
#:use-module (guix build-system gnu)
- #:use-module (guix licenses))
+ #:use-module (guix licenses)
+ #:use-module (gnu packages gawk))
(define-public hello
(package
(name "hello")
- (version "2.8")
+ (version "2.10")
(source (origin
- (method url-fetch)
- (uri (string-append "mirror://gnu/hello/hello-" version
- ".tar.gz"))
- (sha256
- (base32 "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"))))
+ (method url-fetch)
+ (uri (string-append "mirror://gnu/hello/hello-" version
+ ".tar.gz"))
+ (sha256
+ (base32
+ "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
(build-system gnu-build-system)
(arguments `(#:configure-flags '("--enable-silent-rules")))
(inputs `(("gawk" ,gawk)))
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
+tool (@pxref{Invoking guix build}). You can easily jump back to the
+package definition using the @command{guix edit} command
+(@pxref{Invoking guix edit}).
+@xref{Packaging Guidelines}, for
more information on how to test package definitions, and
@ref{Invoking guix lint}, for information on how to check a definition
for style conformance.
Which Perl package is used can be specified with @code{#:perl}.
@end defvr
+@defvr {Scheme Variable} r-build-system
+This variable is exported by @code{(guix build-system r)}. It
+implements the build procedure used by @uref{http://r-project.org, R}
+packages, which essentially is little more than running @code{R CMD
+INSTALL --library=/gnu/store/@dots{}} in an environment where
+@code{R_LIBS_SITE} contains the paths to all R package inputs. Tests
+are run after installation using the R function
+@code{tools::testInstalledPackage}.
+@end defvr
+
@defvr {Scheme Variable} ruby-build-system
This variable is exported by @code{(guix build-system ruby)}. It
implements the RubyGems build procedure used by Ruby packages, which
involves running @code{gem build} followed by @code{gem install}.
+The @code{source} field of a package that uses this build system
+typically references a gem archive, since this is the format that Ruby
+developers use when releasing their software. The build system unpacks
+the gem archive, potentially patches the source, runs the test suite,
+repackages the gem, and installs it. Additionally, directories and
+tarballs may be referenced to allow building unreleased gems from Git or
+a traditional source release tarball.
+
Which Ruby package is used can be specified with the @code{#:ruby}
-parameter.
+parameter. A list of additional flags to be passed to the @command{gem}
+command can be specified with the @code{#:gem-flags} parameter.
@end defvr
@defvr {Scheme Variable} waf-build-system
parameter which defaults to @code{ghc}.
@end defvr
+@defvr {Scheme Variable} emacs-build-system
+This variable is exported by @code{(guix build-system emacs)}. It
+implements an installation procedure similar to the one of Emacs' own
+packaging system (@pxref{Packages,,, emacs, The GNU Emacs Manual}).
+
+It first creates the @code{@var{package}-autoloads.el} file, then it
+byte compiles all Emacs Lisp files. Differently from the Emacs
+packaging system, the Info documentation files are moved to the standard
+documentation directory and the @file{dir} file is deleted. Each
+package is installed in its own directory under
+@file{share/emacs/site-lisp/guix.d}.
+@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,
Conceptually, the @dfn{store} is where derivations that have been
successfully built are stored---by default, under @file{/gnu/store}.
Sub-directories in the store are referred to as @dfn{store paths}. The
-store has an associated database that contains information such has the
+store has an associated database that contains information such as the
store paths referred to by each store path, and the list of @emph{valid}
store paths---paths that result from a successful build.
@var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
[#:recursive? #f] [#:inputs '()] [#:env-vars '()] @
[#:system (%current-system)] [#:references-graphs #f] @
- [#:allowed-references #f] [#:leaked-env-vars #f] [#:local-build? #f]
+ [#:allowed-references #f] [#:leaked-env-vars #f] [#:local-build? #f] @
+ [#:substitutable? #t]
Build a derivation with the given arguments, and return the resulting
@code{<derivation>} object.
good candidate for offloading and should rather be built locally
(@pxref{Daemon Offload Setup}). This is the case for small derivations
where the costs of data transfers would outweigh the benefits.
+
+When @var{substitutable?} is false, declare that substitutes of the
+derivation's output should not be used (@pxref{Substitutes}). This is
+useful, for instance, when building packages that capture details of the
+host CPU instruction set.
@end deffn
@noindent
[#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
[#:recursive? #f] [#:env-vars '()] [#:modules '()] @
[#:references-graphs #f] [#:allowed-references #f] @
- [#:local-build? #f] [#:guile-for-build #f]
+ [#:local-build? #f] [#:substitutable? #t] [#:guile-for-build #f]
Return a derivation that executes Scheme expression @var{exp} as a
builder for derivation @var{name}. @var{inputs} must be a list of
@code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
@code{%guile-for-build} fluid is used instead.
See the @code{derivation} procedure for the meaning of
-@var{references-graphs}, @var{allowed-references}, and @var{local-build?}.
+@var{references-graphs}, @var{allowed-references}, @var{local-build?},
+and @var{substitutable?}.
@end deffn
@noindent
#$output)))
@end example
-Calling the monadic @code{sh-symlink} has no effect. To get the desired
-effect, one must use @code{run-with-store}:
+@c See
+@c <https://syntaxexclamation.wordpress.com/2014/06/26/escaping-continuations/>
+@c for the funny quote.
+Calling the monadic @code{sh-symlink} has no effect. As someone once
+said, ``you exit a monad like you exit a building on fire: by running''.
+So, to exit the monad and get the desired effect, one must use
+@code{run-with-store}:
@example
(run-with-store (open-connection) (sh-symlink))
processes that use them.
@end itemize
+@cindex lowering, of high-level objects in gexps
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
+derivations or files in the store can be defined,
+such that these objects can also be inserted
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
[#:module-path @var{%load-path}] @
[#:references-graphs #f] [#:allowed-references #f] @
[#:leaked-env-vars #f] @
- [#:local-build? #f] [#:guile-for-build #f]
+ [#:script-name (string-append @var{name} "-builder")] @
+ [#:local-build? #f] [#:substitutable? #t] [#: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}.
+@var{guile-for-build} (a derivation) on @var{system}; @var{exp} is
+stored in a file called @var{script-name}. 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
meant to be used in the build stratum, these modules are kept in the
@code{(guix build @dots{})} name space.
+@cindex lowering, of high-level objects in gexps
+Internally, high-level objects are @dfn{lowered}, using their compiler,
+to either derivations or store items. For instance, lowering a package
+yields a derivation, and lowering a @code{plain-file} yields a store
+item. This is achieved using the @code{lower-object} monadic procedure.
+
+@deffn {Monadic Procedure} lower-object @var{obj} [@var{system}] @
+ [#:target #f]
+Return as a value in @var{%store-monad} the derivation or store item
+corresponding to @var{obj} for @var{system}, cross-compiling for
+@var{target} if @var{target} is true. @var{obj} must be an object that
+has an associated gexp compiler, such as a @code{<package>}.
+@end deffn
+
@c *********************************************************************
@node Utilities
@menu
* Invoking guix build:: Building packages from the command line.
+* Invoking guix edit:: Editing package definitions.
* Invoking guix download:: Downloading a file and printing its hash.
* Invoking guix hash:: Computing the cryptographic hash of a file.
* Invoking guix import:: Importing package definitions.
* Invoking guix refresh:: Updating package definitions.
* Invoking guix lint:: Finding errors in package definitions.
+* Invoking guix size:: Profiling disk usage.
+* Invoking guix graph:: Visualizing the graph of packages.
* Invoking guix environment:: Setting up development environments.
* Invoking guix publish:: Sharing substitutes.
@end menu
guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz
@end example
+@dots{} or to build from a checkout in a pristine environment:
+
+@example
+$ git clone git://git.sv.gnu.org/guix.git
+$ guix build guix --with-source=./guix
+@end example
+
@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
collector root.
@item --log-file
-Return the build log file names for the given
+Return the build log file names or URLs for the given
@var{package-or-derivation}s, or raise an error if build logs are
missing.
guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
@end example
+If a log is unavailable locally, and unless @code{--no-substitutes} is
+passed, the command looks for a corresponding log on one of the
+substitute servers (as specified with @code{--substitute-urls}.)
+So for instance, let's say you want to see the build log of GDB on MIPS
+but you're actually on an @code{x86_64} machine:
+
+@example
+$ guix build --log-file gdb -s mips64el-linux
+http://hydra.gnu.org/log/@dots{}-gdb-7.10
+@end example
+
+You can freely access a huge library of build logs!
@end table
@cindex common build options
When substituting a pre-built binary fails, fall back to building
packages locally.
+@item --substitute-urls=@var{urls}
+@anchor{client-substitute-urls}
+Consider @var{urls} the whitespace-separated list of substitute source
+URLs, overriding the default list of URLs of @command{guix-daemon}
+(@pxref{daemon-substitute-urls,, @command{guix-daemon} URLs}).
+
+This means that substitutes may be downloaded from @var{urls}, provided
+they are signed by a key authorized by the system administrator
+(@pxref{Substitutes}).
+
@item --no-substitutes
Do not use substitutes for build products. That is, always build things
locally instead of allowing downloads of pre-built binaries
@end defvr
+@node Invoking guix edit
+@section Invoking @command{guix edit}
+
+@cindex package definition, editing
+So many packages, so many source files! The @command{guix edit} command
+facilitates the life of packagers by pointing their editor at the source
+file containing the definition of the specified packages. For instance:
+
+@example
+guix edit gcc-4.8 vim
+@end example
+
+@noindent
+launches the program specified in the @code{EDITOR} environment variable
+to edit the recipe of GCC@tie{}4.8.4 and that of Vim.
+
+If you are using Emacs, note that the Emacs user interface provides
+similar functionality in the ``package info'' and ``package list''
+buffers created by @kbd{M-x guix-search-by-name} and similar commands
+(@pxref{Emacs Commands}).
+
+
@node Invoking guix download
@section Invoking @command{guix download}
guix import pypi itsdangerous
@end example
+@item gem
+@cindex gem
+Import meta-data from @uref{https://rubygems.org/,
+RubyGems}@footnote{This functionality requires Guile-JSON to be
+installed. @xref{Requirements}.}. Information is taken from the
+JSON-formatted description available at @code{rubygems.org} and includes
+most relevant information, including runtime dependencies. There are
+some caveats, however. The meta-data doesn't distinguish between
+synopses and descriptions, so the same string is used for both fields.
+Additionally, the details of non-Ruby dependencies required to build
+native extensions is unavailable and left as an exercise to the
+packager.
+
+The command below imports meta-data for the @code{rails} Ruby package:
+
+@example
+guix import gem rails
+@end example
+
@item cpan
@cindex CPAN
Import meta-data from @uref{https://www.metacpan.org/, MetaCPAN}.
guix import cpan Acme::Boolean
@end example
+@item cran
+@cindex CRAN
+Import meta-data from @uref{http://cran.r-project.org/, CRAN}, the
+central repository for the @uref{http://r-project.org, GNU@tie{}R
+statistical and graphical environment}.
+
+Information is extracted from the HTML package description.
+
+The command command below imports meta-data for the @code{Cairo}
+R package:
+
+@example
+guix import cran Cairo
+@end example
+
@item nix
Import meta-data from a local copy of the source of the
@uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This
Specific command-line options are:
@table @code
+@item --stdin
+@itemx -s
+Read a Cabal file from the standard input.
@item --no-test-dependencies
@itemx -t
-Do not include dependencies only required to run the test suite.
+Do not include dependencies required by the test suites only.
+@item --cabal-environment=@var{alist}
+@itemx -e @var{alist}
+@var{alist} is a Scheme alist defining the environment in which the
+Cabal conditionals are evaluated. The accepted keys are: @code{os},
+@code{arch}, @code{impl} and a string representing the name of a flag.
+The value associated with a flag has to be either the symbol
+@code{true} or @code{false}. The value associated with other keys
+has to conform to the Cabal file format definition. The default value
+associated with the keys @code{os}, @code{arch} and @code{impl} is
+@samp{linux}, @samp{x86_64} and @samp{ghc} respectively.
@end table
The command below imports meta-data for the latest version of the
-@code{HTTP} Haskell package without including test dependencies:
+@code{HTTP} Haskell package without including test dependencies and
+specifying the value of the flag @samp{network-uri} as @code{false}:
@example
-guix import hackage -t HTTP
+guix import hackage -t -e "'((\"network-uri\" . false))" HTTP
@end example
A specific package version may optionally be specified by following the
guix import hackage mtl-2.1.3.1
@end example
-Currently only indentation structured Cabal files are supported.
+@item elpa
+@cindex elpa
+Import meta-data from an Emacs Lisp Package Archive (ELPA) package
+repository (@pxref{Packages,,, emacs, The GNU Emacs Manual}).
+
+Specific command-line options are:
+
+@table @code
+@item --archive=@var{repo}
+@itemx -a @var{repo}
+@var{repo} identifies the archive repository from which to retrieve the
+information. Currently the supported repositories and their identifiers
+are:
+@itemize -
+@item
+@uref{http://elpa.gnu.org/packages, GNU}, selected by the @code{gnu}
+identifier. This is the default.
+
+@item
+@uref{http://stable.melpa.org/packages, MELPA-Stable}, selected by the
+@code{melpa-stable} identifier.
+
+@item
+@uref{http://melpa.org/packages, MELPA}, selected by the @code{melpa}
+identifier.
+@end itemize
+@end table
@end table
The structure of the @command{guix import} code is modular. It would be
@item source
@itemx home-page
+@itemx source-file-name
Probe @code{home-page} and @code{source} URLs and report those that are
-invalid.
+invalid. Check that the source file name is meaningful, e.g. is not
+just a version number or ``git-checkout'', and should not have a
+@code{file-name} declared (@pxref{origin Reference}).
+
+@item formatting
+Warn about obvious source code formatting issues: trailing white space,
+use of tabulations, etc.
@end table
The general syntax is:
@end table
+@node Invoking guix size
+@section Invoking @command{guix size}
+
+The @command{guix size} command helps package developers profile the
+disk usage of packages. It is easy to overlook the impact of an
+additional dependency added to a package, or the impact of using a
+single output for a package that could easily be split (@pxref{Packages
+with Multiple Outputs}). These are the typical issues that
+@command{guix size} can highlight.
+
+The command can be passed a package specification such as @code{gcc-4.8}
+or @code{guile:debug}, or a file name in the store. Consider this
+example:
+
+@example
+$ guix size coreutils
+store item total self
+/gnu/store/@dots{}-coreutils-8.23 70.0 13.9 19.8%
+/gnu/store/@dots{}-gmp-6.0.0a 55.3 2.5 3.6%
+/gnu/store/@dots{}-acl-2.2.52 53.7 0.5 0.7%
+/gnu/store/@dots{}-attr-2.4.46 53.2 0.3 0.5%
+/gnu/store/@dots{}-gcc-4.8.4-lib 52.9 15.7 22.4%
+/gnu/store/@dots{}-glibc-2.21 37.2 37.2 53.1%
+@end example
+
+@cindex closure
+The store items listed here constitute the @dfn{transitive closure} of
+Coreutils---i.e., Coreutils and all its dependencies, recursively---as
+would be returned by:
+
+@example
+$ guix gc -R /gnu/store/@dots{}-coreutils-8.23
+@end example
+
+Here the output shows 3 columns next to store items. The first column,
+labeled ``total'', shows the size in mebibytes (MiB) of the closure of
+the store item---that is, its own size plus the size of all its
+dependencies. The next column, labeled ``self'', shows the size of the
+item itself. The last column shows the ratio of the item's size to the
+space occupied by all the items listed here.
+
+In this example, we see that the closure of Coreutils weighs in at
+70@tie{}MiB, half of which is taken by libc. (That libc represents a
+large fraction of the closure is not a problem @i{per se} because it is
+always available on the system anyway.)
+
+When the package passed to @command{guix size} is available in the
+store, @command{guix size} queries the daemon to determine its
+dependencies, and measures its size in the store, similar to @command{du
+-ms --apparent-size} (@pxref{du invocation,,, coreutils, GNU
+Coreutils}).
+
+When the given package is @emph{not} in the store, @command{guix size}
+reports information based on information about the available substitutes
+(@pxref{Substitutes}). This allows it to profile disk usage of store
+items that are not even on disk, only available remotely.
+
+The available options are:
+
+@table @option
+
+@item --substitute-urls=@var{urls}
+Use substitute information from @var{urls}.
+@xref{client-substitute-urls, the same option for @code{guix build}}.
+
+@item --map-file=@var{file}
+Write to @var{file} a graphical map of disk usage as a PNG file.
+
+For the example above, the map looks like this:
+
+@image{images/coreutils-size-map,5in,, map of Coreutils disk usage
+produced by @command{guix size}}
+
+This option requires that
+@uref{http://wingolog.org/software/guile-charting/, Guile-Charting} be
+installed and visible in Guile's module search path. When that is not
+the case, @command{guix size} fails as it tries to load it.
+
+@item --system=@var{system}
+@itemx -s @var{system}
+Consider packages for @var{system}---e.g., @code{x86_64-linux}.
+
+@end table
+
+@node Invoking guix graph
+@section Invoking @command{guix graph}
+
+@cindex DAG
+Packages and their dependencies form a @dfn{graph}, specifically a
+directed acyclic graph (DAG). It can quickly become difficult to have a
+mental model of the package DAG, so the @command{guix graph} command is
+here to provide a visual representation of the DAG. @command{guix
+graph} emits a DAG representation in the input format of
+@uref{http://www.graphviz.org/, Graphviz}, so its output can be passed
+directly to Graphviz's @command{dot} command, for instance. The general
+syntax is:
+
+@example
+guix graph @var{options} @var{package}@dots{}
+@end example
+
+For example, the following command generates a PDF file representing the
+package DAG for the GNU@tie{}Core Utilities, showing its build-time
+dependencies:
+
+@example
+guix graph coreutils | dot -Tpdf > dag.pdf
+@end example
+
+The output looks like this:
+
+@image{images/coreutils-graph,2in,,Dependency graph of the GNU Coreutils}
+
+Nice little graph, no?
+
+But there's more than one graph! The one above is concise: it's the
+graph of package objects, omitting implicit inputs such as GCC, libc,
+grep, etc. It's often useful to have such a concise graph, but
+sometimes you want to see more details. @command{guix graph} supports
+several types of graphs, allowing you to choose the level of details:
+
+@table @code
+@item package
+This is the default type, the one we used above. It shows the DAG of
+package objects, excluding implicit dependencies. It is concise, but
+filters out many details.
+
+@item bag-emerged
+This is the package DAG, @emph{including} implicit inputs.
+
+For instance, the following command:
+
+@example
+guix graph --type=bag-emerged coreutils | dot -Tpdf > dag.pdf
+@end example
+
+... yields this bigger graph:
+
+@image{images/coreutils-bag-graph,,5in,Detailed dependency graph of the GNU Coreutils}
+
+At the bottom of the graph, we see all the implicit inputs of
+@var{gnu-build-system} (@pxref{Build Systems, @code{gnu-build-system}}).
+
+Now, note that the dependencies of those implicit inputs---that is, the
+@dfn{bootstrap dependencies} (@pxref{Bootstrapping})---are not shown
+here, for conciseness.
+
+@item bag
+Similar to @code{bag-emerged}, but this time including all the bootstrap
+dependencies.
+
+@item derivations
+This is the most detailed representation: It shows the DAG of
+derivations (@pxref{Derivations}) and plain store items. Compared to
+the above representation, many additional nodes are visible, including
+builds scripts, patches, Guile modules, etc.
+
+@end table
+
+All the above types correspond to @emph{build-time dependencies}. The
+following graph type represents the @emph{run-time dependencies}:
+
+@table @code
+@item references
+This is the graph of @dfn{references} of a package output, as returned
+by @command{guix gc --references} (@pxref{Invoking guix gc}).
+
+If the given package output is not available in the store, @command{guix
+graph} attempts to obtain dependency information from substitutes.
+@end table
+
+The available options are the following:
+
+@table @option
+@item --type=@var{type}
+@itemx -t @var{type}
+Produce a graph output of @var{type}, where @var{type} must be one of
+the values listed above.
+
+@item --list-types
+List the supported graph types.
+
+@item --expression=@var{expr}
+@itemx -e @var{expr}
+Consider the package @var{expr} evaluates to.
+
+This is useful to precisely refer to a package, as in this example:
+
+@example
+guix graph -e '(@@@@ (gnu packages commencement) gnu-make-final)'
+@end example
+@end table
+
+
@node Invoking guix environment
@section Invoking @command{guix environment}
@cindex reproducible build environments
+@cindex development environments
The purpose of @command{guix environment} is to assist hackers in
creating reproducible development environments without polluting their
package profile. The @command{guix environment} tool takes one or more
guix environment @var{options} @var{package}@dots{}
@end example
-The following examples spawns a new shell that is capable of building
-the GNU Guile source code:
+The following example spawns a new shell set up for the development of
+GNU@tie{}Guile:
@example
guix environment guile
It contains the necessary search paths for building the given package
added to the existing environment variables. To create a ``pure''
environment in which the original environment variables have been unset,
-use the @code{--pure} option.
+use the @code{--pure} option@footnote{Users sometimes wrongfully augment
+environment variables such as @code{PATH} in their @file{~/.bashrc}
+file. As a consequence, when @code{guix environment} launches it, Bash
+may read @file{~/.bashrc}, thereby introducing ``impurities'' in these
+environment variables. It is an error to define such environment
+variables in @file{.bashrc}; instead, they should be defined in
+@file{.bash_profile}, which is sourced only by log-in shells.
+@xref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}, for
+details on Bash start-up files.}.
+
+@vindex GUIX_ENVIRONMENT
+@command{guix environment} defines the @code{GUIX_ENVIRONMENT}
+variable in the shell it spaws. This allows users to, say, define a
+specific prompt for development environments in their @file{.bashrc}
+(@pxref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}):
+
+@example
+if [ -n "$GUIX_ENVIRONMENT" ]
+then
+ export PS1="\u@@\h \w [dev]\$ "
+fi
+@end example
Additionally, more than one package may be specified, in which case the
union of the inputs for the given packages are used. For example, the
guix environment guile --exec=make
@end example
-The following options are available:
+In other situations, it is more convenient to specify the list of
+packages needed in the environment. For example, the following command
+runs @command{python} from an environment containing Python@tie{}2.7 and
+NumPy:
+
+@example
+guix environment --ad-hoc python2-numpy python-2.7 -E python
+@end example
+
+The available options are summarized below.
@table @code
@item --expression=@var{expr}
@itemx -e @var{expr}
Create an environment for the package that @var{expr} evaluates to.
+For example, running:
+
+@example
+guix environment -e '(@@ (gnu packages maths) petsc-openmpi)'
+@end example
+
+starts a shell with the environment for this specific variant of the
+PETSc package.
+
@item --load=@var{file}
@itemx -l @var{file}
Create an environment for the package that the code within @var{file}
evaluates to.
+As an example, @var{file} might contain a definition like this
+(@pxref{Defining Packages}):
+
+@example
+@verbatiminclude environment-gdb.scm
+@end example
+
+
@item --exec=@var{command}
@item -E @var{command}
Execute @var{command} in the new environment.
runs @command{guile} in an environment where Guile and Guile-SDL are
available.
+Note that this example implicitly asks for the default output of
+@code{guile} and @code{guile-sdl} but it is possible to ask for a
+specific output---e.g., @code{glib:bin} asks for the @code{bin} output
+of @code{glib} (@pxref{Packages with Multiple Outputs}).
+
@item --pure
Unset existing environment variables when building the new environment.
This has the effect of creating an environment in which search paths
@item --search-paths
Display the environment variable definitions that make up the
environment.
+
+@item --system=@var{system}
+@itemx -s @var{system}
+Attempt to build for @var{system}---e.g., @code{i686-linux}.
@end table
It also supports all of the common build options that @command{guix
The distribution provides core GNU packages such as GNU libc, GCC, and
Binutils, as well as many GNU and non-GNU applications. The complete
list of available packages can be browsed
-@url{http://www.gnu.org/software/guix/package-list.html,on-line} or by
+@url{http://www.gnu.org/software/guix/packages,on-line} or by
running @command{guix package} (@pxref{Invoking guix package}):
@example
Intel 32-bit architecture (IA32), Linux-Libre kernel;
@item armhf-linux
-ARMv7-A architecture with hard float, Thumb-2 and VFP3D16 coprocessor,
+ARMv7-A architecture with hard float, Thumb-2 and NEON,
using the EABI hard-float ABI, and Linux-Libre kernel.
@item mips64el-linux
get a feel of what that means.)
@item
-The system does not yet provide GNOME and KDE; it provides Xfce, though,
-if graphical desktop environments are your thing.
+The system does not yet provide full GNOME and KDE desktops. Xfce and
+Enlightenment are available though, if graphical desktop environments
+are your thing, as well as a number of X11 window managers.
@item
Support for the Logical Volume Manager (LVM) is missing.
(@pxref{Services}).
@item
-On the order of 1,900 packages are available, which means that you may
+More than 2,000 packages are available, but you may
occasionally find that a useful package is missing.
@end itemize
more information, @pxref{Invoking guix system}. This command may trigger
downloads or builds of missing packages, which can take some time.
-Once that command has completed---and hopefully succeeded!---you can
-run @command{reboot} and boot into the new system. Cross fingers, and
-join us on @code{#guix} on the Freenode IRC network or on
+Once that command has completed---and hopefully succeeded!---you can run
+@command{reboot} and boot into the new system. The @code{root} password
+in the new system is initially empty; other users' passwords need to be
+initialized by running the @command{passwd} command as @code{root},
+unless your configuration specifies otherwise
+(@pxref{user-account-password, user account passwords}).
+
+Join us on @code{#guix} on the Freenode IRC network or on
@file{guix-devel@@gnu.org} to share your experience---good or not so
good.
only the Linux-libre kernel is supported. In the future, it will be
possible to use the GNU@tie{}Hurd.}.
+@item @code{kernel-arguments} (default: @code{'()})
+List of strings or gexps representing additional arguments to pass on
+the kernel's command-line---e.g., @code{("console=ttyS0")}.
+
@item @code{bootloader}
The system bootloader configuration object. @xref{GRUB Configuration}.
List of string-valued G-expressions denoting setuid programs.
@xref{Setuid Programs}.
-@item @code{sudoers} (default: @var{%sudoers-specification})
-@cindex sudoers
+@item @code{sudoers-file} (default: @var{%sudoers-specification})
+@cindex sudoers file
The contents of the @file{/etc/sudoers} file as a file-like object
(@pxref{G-Expressions, @code{local-file} and @code{plain-file}}).
is interpreted as a partition label name; when it is @code{uuid},
@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:
+
+@example
+(file-system
+ (mount-point "/home")
+ (type "ext4")
+ (title 'uuid)
+ (device (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")))
+@end example
+
The @code{label} and @code{uuid} options offer a way to refer to disk
-partitions without having to hard-code their actual device name.
+partitions without having to hard-code their actual device
+name@footnote{Note that, while it is tempting to use
+@file{/dev/disk/by-uuid} and similar device names to achieve the same
+result, this is not recommended: These special device nodes are created
+by the udev daemon and may be unavailable at the time the device is
+mounted.}.
However, when a file system's source is a mapped device (@pxref{Mapped
Devices}), its @code{device} field @emph{must} refer to the mapped
@item @code{create-mount-point?} (default: @code{#f})
When true, the mount point is created if it does not exist yet.
+@item @code{dependencies} (default: @code{'()})
+This is a list of @code{<file-system>} objects representing file systems
+that must be mounted before (and unmounted after) this one.
+
+As an example, consider a hierarchy of mounts: @file{/sys/fs/cgroup} is
+a dependency of @file{/sys/fs/cgroup/cpu} and
+@file{/sys/fs/cgroup/memory}.
+
@end table
@end deftp
@defvr {Scheme Variable} %base-file-systems
These are essential file systems that are required on normal systems,
-such as @var{%devtmpfs-file-system} and @var{%immutable-store} (see
+such as @var{%pseudo-terminal-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
-The @code{devtmpfs} file system to be mounted on @file{/dev}. This is a
-requirement for udev (@pxref{Base Services, @code{udev-service}}).
-@end defvr
-
@defvr {Scheme Variable} %pseudo-terminal-file-system
This is the file system to be mounted as @file{/dev/pts}. It supports
@dfn{pseudo-terminals} created @i{via} @code{openpty} and similar
account. System accounts are sometimes treated specially; for instance,
graphical login managers do not list them.
+@anchor{user-account-password}
@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
A @dfn{locale} defines cultural conventions for a particular language
and region of the world (@pxref{Locales,,, libc, The GNU C Library
Reference Manual}). Each locale has a name that typically has the form
-@code{@var{language}_@var{territory}.@var{charset}}---e.g.,
+@code{@var{language}_@var{territory}.@var{codeset}}---e.g.,
@code{fr_LU.utf8} designates the locale for the French language, with
cultural conventions from Luxembourg, and using the UTF-8 encoding.
(charset "EUC-JP")))
@end example
+@vindex LOCPATH
+The compiled locale definitions are available at
+@file{/run/current-system/locale}, which is the default location where
+the GNU@tie{}libc looks for locale data. This can be overridden using
+the @code{LOCPATH} environment variable (@pxref{locales-and-locpath,
+@code{LOCPATH} and locale packages}).
+
The @code{locale-definition} form is provided by the @code{(gnu system
locale)} module. Details are given below.
@end deftp
@defvr {Scheme Variable} %default-locale-definitions
-An arbitrary list of commonly used locales, used as the default value of
-the @code{locale-definitions} field of @code{operating-system}
+An arbitrary list of commonly used UTF-8 locales, used as the default
+value of the @code{locale-definitions} field of @code{operating-system}
declarations.
+
+@cindex locale name
+@cindex normalized codeset in locale names
+These locale definitions use the @dfn{normalized codeset} for the part
+that follows the dot in the name (@pxref{Using gettextized software,
+normalized codeset,, libc, The GNU C Library Reference Manual}). So for
+instance it has @code{uk_UA.utf8} but @emph{not}, say,
+@code{uk_UA.UTF-8}.
@end defvr
@node Services
* X Window:: Graphical display.
* Desktop Services:: D-Bus and desktop services.
* Database Services:: SQL databases.
+* Web Services:: Web servers.
* Various Services:: Other services.
@end menu
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}).
+the @code{elogind} login and seat manager, the Polkit privilege service,
+the GeoClue location service, an NTP client (@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}
@var{services} must be equal to @code{(list avahi)}.
@end deffn
+@deffn {Monadic Procedure} elogind-service @
+ [#:elogind @var{elogind}] [#:config @var{config}]
+Return a service that runs the @code{elogind} login and
+seat management daemon. @uref{https://github.com/andywingo/elogind,
+Elogind} exposes a D-Bus interface that can be used to know which users
+are logged in, know what kind of sessions they have open, suspend the
+system, inhibit system suspend, reboot the system, and other tasks.
+
+Elogind handles most system-level power events for a computer, for
+example suspending the system when a lid is closed, or shutting it down
+when the power button is pressed.
+
+The @var{config} keyword argument specifies the configuration for
+elogind, and should be the result of a @code{(elogind-configuration
+(@var{parameter} @var{value})...)} invocation. Available parameters and
+their default values are:
+
+@table @code
+@item kill-user-processes?
+@code{#f}
+@item kill-only-users
+@code{()}
+@item kill-exclude-users
+@code{("root")}
+@item inhibit-delay-max-seconds
+@code{5}
+@item handle-power-key
+@code{poweroff}
+@item handle-suspend-key
+@code{suspend}
+@item handle-hibernate-key
+@code{hibernate}
+@item handle-lid-switch
+@code{suspend}
+@item handle-lid-switch-docked
+@code{ignore}
+@item power-key-ignore-inhibited?
+@code{#f}
+@item suspend-key-ignore-inhibited?
+@code{#f}
+@item hibernate-key-ignore-inhibited?
+@code{#f}
+@item lid-switch-ignore-inhibited?
+@code{#t}
+@item holdoff-timeout-seconds
+@code{30}
+@item idle-action
+@code{ignore}
+@item idle-action-seconds
+@code{(* 30 60)}
+@item runtime-directory-size-percent
+@code{10}
+@item runtime-directory-size
+@code{#f}
+@item remove-ipc?
+@code{#t}
+@item suspend-state
+@code{("mem" "standby" "freeze")}
+@item suspend-mode
+@code{()}
+@item hibernate-state
+@code{("disk")}
+@item hibernate-mode
+@code{("platform" "shutdown")}
+@item hybrid-sleep-state
+@code{("disk")}
+@item hybrid-sleep-mode
+@code{("suspend" "platform" "shutdown")}
+@end table
+@end deffn
+
+@deffn {Monadic Procedure} polkit-service @
+ [#:polkit @var{polkit}]
+Return a service that runs the Polkit privilege manager.
+@uref{http://www.freedesktop.org/wiki/Software/polkit/, Polkit} allows
+system administrators to grant access to privileged operations in a
+structured way. For example, polkit rules can allow a logged-in user
+whose session is active to shut down the machine, if there are no other
+users active.
+@end deffn
+
@deffn {Monadic Procedure} upower-service [#:upower @var{upower}] @
[#:watts-up-pro? #f] @
[#:poll-batteries? #t] @
site} for more information.
@end deffn
+@deffn {Scheme Procedure} geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()]
+Return an configuration allowing an application to access GeoClue
+location data. @var{name} is the Desktop ID of the application, without
+the @code{.desktop} part. If @var{allowed?} is true, the application
+will have access to location information by default. The boolean
+@var{system?} value indicates that an application is a system component
+or not. Finally @var{users} is a list of UIDs of all users for which
+this application is allowed location info access. An empty users list
+means that all users are allowed.
+@end deffn
+
+@defvr {Scheme Variable} %standard-geoclue-applications
+The standard list of well-known GeoClue application configurations,
+granting authority to GNOME's date-and-time utility to ask for the
+current location in order to set the time zone, and allowing the Firefox
+(IceCat) and Epiphany web browsers to request location information.
+Firefox and Epiphany both query the user before allowing a web page to
+know the user's location.
+@end defvr
+
+@deffn {Monadic Procedure} geoclue-service [#:colord @var{colord}] @
+ [#:whitelist '()] @
+ [#:wifi-geolocation-url "https://location.services.mozilla.com/v1/geolocate?key=geoclue"] @
+ [#:submit-data? #f]
+ [#:wifi-submission-url "https://location.services.mozilla.com/v1/submit?key=geoclue"] @
+ [#:submission-nick "geoclue"] @
+ [#:applications %standard-geoclue-applications]
+Return a service that runs the GeoClue location service. This service
+provides a D-Bus interface to allow applications to request access to a
+user's physical location, and optionally to add information to online
+location databases. See
+@uref{https://wiki.freedesktop.org/www/Software/GeoClue/, the GeoClue
+web site} for more information.
+@end deffn
+
@node Database Services
@subsubsection Database Services
@var{data-directory}.
@end deffn
+@node Web Services
+@subsubsection Web Services
+
+The @code{(gnu services web)} module provides the following service:
+
+@deffn {Monadic Procedure} nginx-service [#:nginx nginx] @
+ [#:log-directory ``/var/log/nginx''] @
+ [#:run-directory ``/var/run/nginx''] @
+ [#:config-file]
+
+Return a service that runs @var{nginx}, the nginx web server.
+
+The nginx daemon loads its runtime configuration from @var{config-file}.
+Log files are written to @var{log-directory} and temporary runtime data
+files are written to @var{run-directory}. For proper operation, these
+arguments should match what is in @var{config-file} to ensure that the
+directories are created when the service is activated.
+
+@end deffn
+
@node Various Services
@subsubsection Various Services
@cindex setuid programs
Some programs need to run with ``root'' privileges, even when they are
launched by unprivileged users. A notorious example is the
-@command{passwd} programs, which can users can run to change their
-password, and which requires write access to the @file{/etc/passwd} and
+@command{passwd} program, which users can run to change their
+password, and which needs to access the @file{/etc/passwd} and
@file{/etc/shadow} files---something normally restricted to root, for
obvious security reasons. To address that, these executables are
@dfn{setuid-root}, meaning that they always run with root privileges
* Software Freedom:: What may go into the distribution.
* Package Naming:: What's in a name?
* Version Numbers:: When the name is not enough.
+* Synopses and Descriptions:: Helping users find the right package.
* Python Modules:: Taming the snake.
* Perl Modules:: Little pearls.
* Fonts:: Fond of fonts.
@example
(define-public gtk+
(package
- (name "gtk+")
- (version "3.9.12")
- ...))
+ (name "gtk+")
+ (version "3.9.12")
+ ...))
(define-public gtk+-2
(package
- (name "gtk+")
- (version "2.24.20")
- ...))
+ (name "gtk+")
+ (version "2.24.20")
+ ...))
@end example
If we also wanted GTK+ 3.8.2, this would be packaged as
@example
(define-public gtk+-3.8
(package
- (name "gtk+")
- (version "3.8.2")
- ...))
+ (name "gtk+")
+ (version "3.8.2")
+ ...))
@end example
+@node Synopses and Descriptions
+@subsection Synopses and Descriptions
+
+As we have seen before, each package in GNU@tie{}Guix includes a
+synopsis and a description (@pxref{Defining Packages}). Synopses and
+descriptions are important: They are what @command{guix package
+--search} searches, and a crucial piece of information to help users
+determine whether a given package suits their needs. Consequently,
+packagers should pay attention to what goes into them.
+
+Synopses must start with a capital letter and must not end with a
+period. They must not start with ``a'' or ``the'', which usually does
+not bring anything; for instance, prefer ``File-frobbing tool'' over ``A
+tool that frobs files''. The synopsis should say what the package
+is---e.g., ``Core GNU utilities (file, text, shell)''---or what it is
+used for---e.g., the synopsis for GNU@tie{}grep is ``Print lines
+matching a pattern''.
+
+Keep in mind that the synopsis must be meaningful for a very wide
+audience. For example, ``Manipulate alignments in the SAM format''
+might make sense for a seasoned bioinformatics researcher, but might be
+fairly unhelpful or even misleading to a non-specialized audience. It
+is a good idea to come up with a synopsis that gives an idea of the
+application domain of the package. In this example, this might give
+something like ``Manipulate nucleotide sequence alignments'', which
+hopefully gives the user a better idea of whether this is what they are
+looking for.
+
+@cindex Texinfo markup, in package descriptions
+Descriptions should take between five and ten lines. Use full
+sentences, and avoid using acronyms without first introducing them.
+Descriptions can include Texinfo markup, which is useful to introduce
+ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or
+hyperlinks (@pxref{Overview, overview of Texinfo,, texinfo, GNU
+Texinfo}). User interfaces such as @command{guix package --show} take
+care of rendering it appropriately.
+
+Synopses and descriptions are translated by volunteers
+@uref{http://translationproject.org/domain/guix-packages.html, at the
+Translation Project} so that as many users as possible can read them in
+their native language. User interfaces search them and display them in
+the language specified by the current locale.
+
+Translation is a lot of work so, as a packager, please pay even more
+attention to your synopses and descriptions as every change may entail
+additional work for translators.
+
@node Python Modules
@subsection Python Modules
platform. Lastly, the generated binaries could be broken for some
reason.
-
@c *********************************************************************
-@node Contributing
-@chapter Contributing
-
-This project is a cooperative effort, and we need your help to make it
-grow! Please get in touch with us on @email{guix-devel@@gnu.org} and
-@code{#guix} on the Freenode IRC network. We welcome ideas, bug
-reports, patches, and anything that may be helpful to the project. We
-particularly welcome help on packaging (@pxref{Packaging Guidelines}).
-
-Please see the
-@url{http://git.savannah.gnu.org/cgit/guix.git/tree/HACKING,
-@file{HACKING} file} that comes with the Guix source code for practical
-details about contributions.
-
+@include contributing.texi
@c *********************************************************************
@node Acknowledgments
HCoop / jackhill / guix / guix.git / blobdiff