@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.
* 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.
* 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.
@example
# cd /tmp
-# tar xf guix-binary-@value{VERSION}.@var{system}.tar.xz
+# tar --warning=no-timestamp -xf \
+ guix-binary-@value{VERSION}.@var{system}.tar.xz
# mv var/guix /var/ && mv gnu /
@end example
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}:
@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
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.
@subsection Locales
+@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
@subsection X11 Fonts
-The majority of graphical applications uses Fontconfig to locate and
+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}.
+@code{font-gnu-freefont-ttf}.
@c TODO What else?
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
output, whereas the GUIs are in a separate output. This allows users
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
@dfn{transitive closure} of the store files.
@xref{Invoking guix size}, for a tool to profile the size of an
-element's closure.
+element's closure. @xref{Invoking guix graph}, for a tool to visualize
+the graph of references.
@end table
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)))
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
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.
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] @
+ [#: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
* 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
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
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
@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:
@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.
@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}
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.
@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 (@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
HCoop / jackhill / guix / guix.git / blobdiff