* Package Modules:: Packages from the programmer's viewpoint.
* Defining Packages:: Defining new packages.
* Build Systems:: Specifying how packages are built.
+* Build Phases:: Phases of the build process of a package.
* Build Utilities:: Helpers for your package definitions and more.
* The Store:: Manipulating the package store.
* Derivations:: Low-level interface to package derivations.
* Service Reference:: API reference.
* Shepherd Services:: A particular type of service.
+Installing Debugging Files
+
+* Separate Debug Info:: Installing 'debug' outputs.
+* Rebuilding Debug Info:: Building missing debug info.
+
Bootstrapping
* Reduced Binary Seed Bootstrap:: A Bootstrap worthy of GNU.
@vindex GUIX_EXECUTION_ENGINE
When running a wrapped program, you can explicitly request one of the
execution engines listed above by setting the
-@code{GUIX_EXECUTION_ENGINE} environment variable accordingly.
+@env{GUIX_EXECUTION_ENGINE} environment variable accordingly.
@end quotation
@cindex entry point, for Docker images
* Package Modules:: Packages from the programmer's viewpoint.
* Defining Packages:: Defining new packages.
* Build Systems:: Specifying how packages are built.
+* Build Phases:: Phases of the build process of a package.
* Build Utilities:: Helpers for your package definitions and more.
* The Store:: Manipulating the package store.
* Derivations:: Low-level interface to package derivations.
the package you are interested in from another repository, using the
@code{guix import} command (@pxref{Invoking guix import}).
-In the example above, @var{hello} is defined in a module of its own,
+In the example above, @code{hello} is defined in a module of its own,
@code{(gnu packages hello)}. Technically, this is not strictly
necessary, but it is convenient to do so: all the packages defined in
modules under @code{(gnu packages @dots{})} are automatically known to
@item
@cindex GNU Build System
The @code{build-system} field specifies the procedure to build the
-package (@pxref{Build Systems}). Here, @var{gnu-build-system}
+package (@pxref{Build Systems}). Here, @code{gnu-build-system}
represents the familiar GNU Build System, where packages may be
configured, built, and installed with the usual @code{./configure &&
make && make check && make install} command sequence.
@item
The @code{arguments} field specifies options for the build system
(@pxref{Build Systems}). Here it is interpreted by
-@var{gnu-build-system} as a request run @file{configure} with the
+@code{gnu-build-system} as a request run @file{configure} with the
@option{--enable-silent-rules} flag.
@cindex quote
@item
The @code{inputs} field specifies inputs to the build process---i.e.,
build-time or run-time dependencies of the package. Here, we define an
-input called @code{"gawk"} whose value is that of the @var{gawk}
-variable; @
var{gawk} is itself bound to a @code{<package>} object.
+input called @code{"gawk"} whose value is that of the @code{gawk}
+variable; @
code{gawk} is itself bound to a @code{<package>} object.
@cindex backquote (quasiquote)
@findex `
Reference Manual}).
Note that GCC, Coreutils, Bash, and other essential tools do not need to
-be specified as inputs here. Instead, @var{gnu-build-system} takes care
+be specified as inputs here. Instead, @code{gnu-build-system} takes care
of ensuring that they are present (@pxref{Build Systems}).
However, any other dependencies need to be specified in the
@node origin Reference
@subsection @code{origin} Reference
-This section summarizes all the options available in @code{origin}
-declarations (@pxref{Defining Packages}).
+This section documents @dfn{origins}. An @code{origin} declaration
+specifies data that must be ``produced''---downloaded, usually---and
+whose content hash is known in advance. Origins are primarily used to
+represent the source code of packages (@pxref{Defining Packages}). For
+that reason, the @code{origin} form allows you to declare patches to
+apply to the original source code as well as code snippets to modify it.
@deftp {Data Type} origin
This is the data type representing a source code origin.
@var{url-fetch} method of @code{(guix download)}, the valid @code{uri}
values are: a URL represented as a string, or a list thereof.
+@cindex fixed-output derivations, for download
@item @code{method}
-A procedure that handles the URI.
-
-Examples include:
-
-@table @asis
-@item @var{url-fetch} from @code{(guix download)}
-download a file from the HTTP, HTTPS, or FTP URL specified in the
-@code{uri} field;
-
-@vindex git-fetch
-@item @var{git-fetch} from @code{(guix git-download)}
-clone the Git version control repository, and check out the revision
-specified in the @code{uri} field as a @code{git-reference} object; a
-@code{git-reference} looks like this:
+A monadic procedure that handles the given URI. The procedure must
+accept at least three arguments: the value of the @code{uri} field and
+the hash algorithm and hash value specified by the @code{hash} field.
+It must return a store item or a derivation in the store monad
+(@pxref{The Store Monad}); most methods return a fixed-output derivation
+(@pxref{Derivations}).
-@lisp
-(git-reference
- (url "https://git.savannah.gnu.org/git/hello.git")
- (commit "v2.10"))
-@end lisp
-@end table
+Commonly used methods include @code{url-fetch}, which fetches data from
+a URL, and @code{git-fetch}, which fetches data from a Git repository
+(see below).
@item @code{sha256}
A bytevector containing the SHA-256 hash of the source. This is
as ensuring that @var{value} has the right size for @var{algorithm}.
@end deftp
+As we have seen above, how exactly the data an origin refers to is
+retrieved is determined by its @code{method} field. The @code{(guix
+download)} module provides the most common method, @code{url-fetch},
+described below.
+
+@deffn {Scheme Procedure} url-fetch @var{url} @var{hash-algo} @var{hash} @
+ [name] [#:executable? #f]
+Return a fixed-output derivation that fetches data from @var{url} (a
+string, or a list of strings denoting alternate URLs), which is expected
+to have hash @var{hash} of type @var{hash-algo} (a symbol). By default,
+the file name is the base name of URL; optionally, @var{name} can
+specify a different file name. When @var{executable?} is true, make the
+downloaded file executable.
+
+When one of the URL starts with @code{mirror://}, then its host part is
+interpreted as the name of a mirror scheme, taken from @file{%mirror-file}.
+
+Alternatively, when URL starts with @code{file://}, return the
+corresponding file name in the store.
+@end deffn
+
+Likewise, the @code{(guix git-download)} module defines the
+@code{git-download} origin method, which fetches data from a Git version
+control repository, and the @code{git-reference} data type to describe
+the repository and revision to fetch.
+
+@deffn {Scheme Procedure} git-fetch @var{ref} @var{hash-algo} @var{hash}
+Return a fixed-output derivation that fetches @var{ref}, a
+@code{<git-reference>} object. The output is expected to have recursive
+hash @var{hash} of type @var{hash-algo} (a symbol). Use @var{name} as
+the file name, or a generic name if @code{#f}.
+@end deffn
+
+@deftp {Data Type} git-reference
+This data type represents a Git reference for @code{git-fetch} to
+retrieve.
+
+@table @asis
+@item @code{url}
+The URL of the Git repository to clone.
+
+@item @code{commit}
+This string denotes either the commit to fetch (a hexadecimal string,
+either the full SHA1 commit or a ``short'' commit string; the latter is
+not recommended) or the tag to fetch.
+
+@item @code{recursive?} (default: @code{#f})
+This Boolean indicates whether to recursively fetch Git sub-modules.
+@end table
+
+The example below denotes the @code{v2.10} tag of the GNU@tie{}Hello
+repository:
+
+@lisp
+(git-reference
+ (url "https://git.savannah.gnu.org/git/hello.git")
+ (commit "v2.10"))
+@end lisp
+
+This is equivalent to the reference below, which explicitly names the
+commit:
+
+@lisp
+(git-reference
+ (url "https://git.savannah.gnu.org/git/hello.git")
+ (commit "dc7dc56a00e48fe6f231a58f6537139fe2908fb9"))
+@end lisp
+@end deftp
+
@node Build Systems
@section Build Systems
@code{%standard-phases} is a list of symbol/procedure pairs, where the
procedure implements the actual phase.
-The list of phases used for a particular package can be changed with the
-@code{#:phases} parameter. For instance, passing:
-
-@example
-#:phases (modify-phases %standard-phases (delete 'configure))
-@end example
-
-means that all the phases described above will be used, except the
-@code{configure} phase. @xref{Build Utilities}, for more info on
-@code{modify-phases} and build phases in general.
+@xref{Build Phases}, for more info on build phases and ways to customize
+them.
In addition, this build system ensures that the ``standard'' environment
for GNU packages is available. This includes tools such as GCC, libc,
specified in the @code{#:cargo-inputs} and @code{#:cargo-development-inputs}
parameters available to cargo. It will also remove an included
@code{Cargo.lock} file to be recreated by @code{cargo} during the
-@code{build} phase. The @code{install} phase installs any crate the binaries
-if they are defined by the crate.
+@code{build} phase. The @code{install} phase installs the binaries
+defined by the crate.
@end defvr
julia} packages, which essentially is similar to running @samp{julia -e
'using Pkg; Pkg.add(package)'} in an environment where
@env{JULIA_LOAD_PATH} contains the paths to all Julia package inputs.
-Tests are run not run.
+Tests are run with @code{Pkg.test}.
Julia packages require the source @code{file-name} to be the real name of the
package, correctly capitalized.
@code{build-expression->derivation}}).
@end defvr
+@node Build Phases
+@section Build Phases
+
+@cindex build phases, for packages
+Almost all package build systems implement a notion @dfn{build phases}:
+a sequence of actions that the build system executes, when you build the
+package, leading to the installed byproducts in the store. A notable
+exception is the ``bare-bones'' @code{trivial-build-system}
+(@pxref{Build Systems}).
+
+As discussed in the previous section, those build systems provide a
+standard list of phases. For @code{gnu-build-system}, the standard
+phases include an @code{unpack} phase to unpack the source code tarball,
+a @command{configure} phase to run @code{./configure}, a @code{build}
+phase to run @command{make}, and (among others) an @code{install} phase
+to run @command{make install}; @pxref{Build Systems}, for a more
+detailed view of these phases. Likewise, @code{cmake-build-system}
+inherits these phases, but its @code{configure} phase runs
+@command{cmake} instead of @command{./configure}. Other build systems,
+such as @code{python-build-system}, have a wholly different list of
+standard phases. All this code runs on the @dfn{build side}: it is
+evaluated when you actually build the package, in a dedicated build
+process spawned by the build daemon (@pxref{Invoking guix-daemon}).
+
+Build phases are represented as association lists or ``alists''
+(@pxref{Association Lists,,, guile, GNU Guile Reference Manual}) where
+each key is a symbol for the name of the phase and the associated value
+is a procedure that accepts an arbitrary number of arguments. By
+convention, those procedures receive information about the build in the
+form of @dfn{keyword parameters}, which they can use or ignore.
+
+For example, here is how @code{(guix build gnu-build-system)} defines
+@code{%standard-phases}, the variable holding its alist of build
+phases@footnote{We present a simplified view of those build phases, but
+do take a look at @code{(guix build gnu-build-system)} to see all the
+details!}:
+
+@lisp
+;; The build phases of 'gnu-build-system'.
+
+(define* (unpack #:key source #:allow-other-keys)
+ ;; Extract the source tarball.
+ (invoke "tar" "xvf" source))
+
+(define* (configure #:key outputs #:allow-other-keys)
+ ;; Run the 'configure' script. Install to output "out".
+ (let ((out (assoc-ref outputs "out")))
+ (invoke "./configure"
+ (string-append "--prefix=" out))))
+
+(define* (build #:allow-other-keys)
+ ;; Compile.
+ (invoke "make"))
+
+(define* (check #:key (test-target "check") (tests? #true)
+ #:allow-other-keys)
+ ;; Run the test suite.
+ (if tests?
+ (invoke "make" test-target)
+ (display "test suite not run\n")))
+
+(define* (install #:allow-other-keys)
+ ;; Install files to the prefix 'configure' specified.
+ (invoke "make" "install"))
+
+(define %standard-phases
+ ;; The list of standard phases (quite a few are omitted
+ ;; for brevity). Each element is a symbol/procedure pair.
+ (list (cons 'unpack unpack)
+ (cons 'configure configure)
+ (cons 'build build)
+ (cons 'check check)
+ (cons 'install install)))
+@end lisp
+
+This shows how @code{%standard-phases} is defined as a list of
+symbol/procedure pairs (@pxref{Pairs,,, guile, GNU Guile Reference
+Manual}). The first pair associates the @code{unpack} procedure with
+the @code{unpack} symbol---a name; the second pair defines the
+@code{configure} phase similarly, and so on. When building a package
+that uses @code{gnu-build-system} with its default list of phases, those
+phases are executed sequentially. You can see the name of each phase
+started and completed in the build log of packages that you build.
+
+Let's now look at the procedures themselves. Each one is defined with
+@code{define*}: @code{#:key} lists keyword parameters the procedure
+accepts, possibly with a default value, and @code{#:allow-other-keys}
+specifies that other keyword parameters are ignored (@pxref{Optional
+Arguments,,, guile, GNU Guile Reference Manual}).
+
+The @code{unpack} procedure honors the @code{source} parameter, which
+the build system uses to pass the file name of the source tarball (or
+version control checkout), and it ignores other parameters. The
+@code{configure} phase only cares about the @code{outputs} parameter, an
+alist mapping package output names to their store file name
+(@pxref{Packages with Multiple Outputs}). It extracts the file name of
+for @code{out}, the default output, and passes it to
+@command{./configure} as the installation prefix, meaning that
+@command{make install} will eventually copy all the files in that
+directory (@pxref{Configuration, configuration and makefile
+conventions,, standards, GNU Coding Standards}). @code{build} and
+@code{install} ignore all their arguments. @code{check} honors the
+@code{test-target} argument, which specifies the name of the Makefile
+target to run tests; it prints a message and skips tests when
+@code{tests?} is false.
+
+@cindex build phases, customizing
+The list of phases used for a particular package can be changed with the
+@code{#:phases} parameter of the build system. Changing the set of
+build phases boils down to building a new alist of phases based on the
+@code{%standard-phases} alist described above. This can be done with
+standard alist procedures such as @code{alist-delete} (@pxref{SRFI-1
+Association Lists,,, guile, GNU Guile Reference Manual}); however, it is
+more convenient to do so with @code{modify-phases} (@pxref{Build
+Utilities, @code{modify-phases}}).
+
+Here is an example of a package definition that removes the
+@code{configure} phase of @code{%standard-phases} and inserts a new
+phase before the @code{build} phase, called
+@code{set-prefix-in-makefile}:
+
+@lisp
+(define-public example
+ (package
+ (name "example")
+ ;; other fields omitted
+ (build-system gnu-build-system)
+ (arguments
+ '(#:phases (modify-phases %standard-phases
+ (delete 'configure)
+ (add-before 'build 'set-prefix-in-makefile
+ (lambda* (#:key outputs #:allow-other-keys)
+ ;; Modify the makefile so that its
+ ;; 'PREFIX' variable points to "out".
+ (let ((out (assoc-ref outputs "out")))
+ (substitute* "Makefile"
+ (("PREFIX =.*")
+ (string-append "PREFIX = "
+ out "\n")))
+ #true))))))))
+@end lisp
+
+The new phase that is inserted is written as an anonymous procedure,
+introduced with @code{lambda*}; it honors the @code{outputs} parameter
+we have seen before. @xref{Build Utilities}, for more about the helpers
+used by this phase, and for more examples of @code{modify-phases}.
+
+@cindex code staging
+@cindex staging, of code
+Keep in mind that build phases are code evaluated at the time the
+package is actually built. This explains why the whole
+@code{modify-phases} expression above is quoted (it comes after the
+@code{'} or apostrophe): it is @dfn{staged} for later execution.
+@xref{G-Expressions}, for an explanation of code staging and the
+@dfn{code strata} involved.
+
@node Build Utilities
@section Build Utilities
@subsection Build Phases
@cindex build phases
-The @code{(guix build utils)} also contains tools to manipulate
-@dfn{build phases} as found in @code{gnu-build-system} and in fact most
-build systems (@pxref{Build Systems}). Build phases are represented as
-association lists or ``alists'' (@pxref{Association Lists,,, guile, GNU
-Guile Reference Manual}) where each key is a symbol for the name of the
-phase, and the associated value is a procedure that accepts an arbitrary
-number of arguments.
+The @code{(guix build utils)} also contains tools to manipulate build
+phases as used by build systems (@pxref{Build Systems}). Build phases
+are represented as association lists or ``alists'' (@pxref{Association
+Lists,,, guile, GNU Guile Reference Manual}) where each key is a symbol
+naming the phase and the associated value is a procedure (@pxref{Build
+Phases}).
Guile core and the @code{(srfi srfi-1)} module both provide tools to
manipulate alists. The @code{(guix build utils)} module complements
build the derivations; they are run by the daemon in a container
(@pxref{Invoking guix-daemon}).
+@cindex code staging
+@cindex staging, of code
@cindex strata of code
It should come as no surprise that we like to write these build actions
in Scheme. When we do that, we end up with two @dfn{strata} of Scheme
@dfn{staging}.}: the ``host code''---code that defines packages, talks
to the daemon, etc.---and the ``build code''---code that actually
performs build actions, such as making directories, invoking
-@command{make}, etc.
+@command{make}, and so on (@pxref{Build Phases}).
To describe a derivation and its build actions, one typically needs to
embed build code inside host code. It boils down to manipulating build
@code{let-system} is useful in the occasional case where the object
spliced into the gexp depends on the target system, as in this example:
-@example
+@lisp
#~(system*
#+(let-system system
(cond ((string-prefix? "armhf-" system)
(else
(error "dunno!"))))
"-net" "user" #$image)
-@end example
+@end lisp
@end deffn
@deffn {Scheme Syntax} with-parameters ((@var{parameter} @var{value}) @dots{}) @var{exp}
@command{guix upgrade} attempts to apply transformation options
initially used when creating the profile to the upgraded packages.
+The available options are listed below. Most commands support them and
+also support a @option{--help-transform} option that lists all the
+available options and a synopsis (these options are not shown in the
+@option{--help} output for brevity).
+
@table @code
@item --with-source=@var{source}
@var{package}, then the resulting package may be unusable. Use with
care!
+@cindex debugging info, rebuilding
+@item --with-debug-info=@var{package}
+Build @var{package} in a way that preserves its debugging info and graft
+it onto packages that depend on it. This is useful if @var{package}
+does not already provide debugging info as a @code{debug} output
+(@pxref{Installing Debugging Files}).
+
+For example, suppose you're experiencing a crash in Inkscape and would
+like to see what's up in GLib, a library deep down in Inkscape's
+dependency graph. GLib lacks a @code{debug} output, so debugging is
+tough. Fortunately, you rebuild GLib with debugging info and tack it on
+Inkscape:
+
+@example
+guix install inkscape --with-debug-info=glib
+@end example
+
+Only GLib needs to be recompiled so this takes a reasonable amount of
+time. @xref{Installing Debugging Files}, for more info.
+
+@quotation Note
+Under the hood, this option works by passing the @samp{#:strip-binaries?
+#f} to the build system of the package of interest (@pxref{Build
+Systems}). Most build systems support that option but some do not. In
+that case, an error is raised.
+
+Likewise, if a C/C++ package is built without @code{-g} (which is rarely
+the case), debugging info will remain unavailable even when
+@code{#:strip-binaries?} is false.
+@end quotation
+
@cindex tool chain, changing the build tool chain of a package
@item --with-c-toolchain=@var{package}=@var{toolchain}
This option changes the compilation of @var{package} and everything that
When @option{--archive=bioconductor} is added, metadata is imported from
@uref{https://www.bioconductor.org/, Bioconductor}, a repository of R
-packages for for the analysis and comprehension of high-throughput
+packages for the analysis and comprehension of high-throughput
genomic data in bioinformatics.
Information is extracted from the @file{DESCRIPTION} file contained in the
Reference, @code{services}}).
Additionally, the @code{gnome-desktop-service-type},
-@code{xfce-desktop-service}, @code{mate-desktop-service-type} and
-@code{enlightenment-desktop-service-type} procedures can add GNOME, Xfce, MATE
-and/or Enlightenment to a system. To ``add GNOME'' means that system-level
-services like the backlight adjustment helpers and the power management
-utilities are added to the system, extending @code{polkit} and @code{dbus}
-appropriately, allowing GNOME to operate with elevated privileges on a
-limited number of special-purpose system interfaces. Additionally,
-adding a service made by @code{gnome-desktop-service-type} adds the GNOME
-metapackage to the system profile. Likewise, adding the Xfce service
-not only adds the @code{xfce} metapackage to the system profile, but it
-also gives the Thunar file manager the ability to open a ``root-mode''
-file management window, if the user authenticates using the
-administrator's password via the standard polkit graphical interface.
-To ``add MATE'' means that @code{polkit} and @code{dbus} are extended
-appropriately, allowing MATE to operate with elevated privileges on a
-limited number of special-purpose system interfaces. Additionally,
-adding a service of type @code{mate-desktop-service-type} adds the MATE
-metapackage to the system profile. ``Adding Enlightenment'' means that
-@code{dbus} is extended appropriately, and several of Enlightenment's binaries
-are set as setuid, allowing Enlightenment's screen locker and other
-functionality to work as expected.
+@code{xfce-desktop-service}, @code{mate-desktop-service-type},
+@code{lxqt-desktop-service-type} and @code{enlightenment-desktop-service-type}
+procedures can add GNOME, Xfce, MATE and/or Enlightenment to a system. To
+``add GNOME'' means that system-level services like the backlight adjustment
+helpers and the power management utilities are added to the system, extending
+@code{polkit} and @code{dbus} appropriately, allowing GNOME to operate with
+elevated privileges on a limited number of special-purpose system interfaces.
+Additionally, adding a service made by @code{gnome-desktop-service-type} adds
+the GNOME metapackage to the system profile. Likewise, adding the Xfce
+service not only adds the @code{xfce} metapackage to the system profile, but
+it also gives the Thunar file manager the ability to open a ``root-mode'' file
+management window, if the user authenticates using the administrator's
+password via the standard polkit graphical interface. To ``add MATE'' means
+that @code{polkit} and @code{dbus} are extended appropriately, allowing MATE
+to operate with elevated privileges on a limited number of special-purpose
+system interfaces. Additionally, adding a service of type
+@code{mate-desktop-service-type} adds the MATE metapackage to the system
+profile. ``Adding Enlightenment'' means that @code{dbus} is extended
+appropriately, and several of Enlightenment's binaries are set as setuid,
+allowing Enlightenment's screen locker and other functionality to work as
+expected.
The desktop environments in Guix use the Xorg display server by
default. If you'd like to use the newer display server protocol
@end table
@end deftp
+@deffn {Scheme Variable} lxqt-desktop-service-type
+This is the type of the service that runs the @uref{https://lxqt.github.io,
+LXQt desktop environment}. Its value is a @code{lxqt-desktop-configuration}
+object (see below).
+
+This service adds the @code{lxqt} package to the system
+profile.
+@end deffn
+
+@deftp {Data Type} lxqt-desktop-configuration
+Configuration record for the LXQt desktop environment.
+
+@table @asis
+@item @code{lxqt} (default: @code{lxqt})
+The LXQT package to use.
+@end table
+@end deftp
+
@deffn {Scheme Variable} enlightenment-desktop-service-type
Return a service that adds the @code{enlightenment} package to the system
profile, and extends dbus with actions from @code{efl}.
@var{client-conf}.
@item @var{script-file} (default: @code{(file-append pulseaudio "/etc/pulse/default.pa")})
-Script file to use as as @file{default.pa}.
+Script file to use as @file{default.pa}.
@item @var{system-script-file} (default: @code{(file-append pulseaudio "/etc/pulse/system.pa")})
-Script file to use as as @file{system.pa}.
+Script file to use as @file{system.pa}.
@end table
@end deftp
@cindex SQL
The @code{(gnu services databases)} module provides the following services.
-@deffn {Scheme Procedure} postgresql-service [#:postgresql postgresql] @
- [#:config-file] [#:data-directory ``/var/lib/postgresql/data''] @
- [#:port 5432] [#:locale ``en_US.utf8''] [#:extension-packages '()]
-Return a service that runs @var{postgresql}, the PostgreSQL database
-server.
+@subsubheading PostgreSQL
+
+The following example describes a PostgreSQL service with the default
+configuration.
-The PostgreSQL daemon loads its runtime configuration from @var{config-file},
-creates a database cluster with @var{locale} as the default
-locale, stored in @var{data-directory}. It then listens on @var{port}.
+@lisp
+(service postgresql-service-type
+ (postgresql-configuration
+ (postgresql postgresql-10)))
+@end lisp
If the services fails to start, it may be due to an incompatible
cluster already present in @var{data-directory}. Adjust it (or, if you
createdb $MY_USER_LOGIN # Replace appropriately.
@end example
+@deftp {Data Type} postgresql-configuration
+Data type representing the configuration for the
+@code{postgresql-service-type}.
+
+@table @asis
+@item @var{postgresql}
+PostgreSQL package to use for the service.
+
+@item @var{port} (default: @code{5432})
+Port on which PostgreSQL should listen.
+
+@item @var{locale} (default: @code{"en_US.utf8"})
+Locale to use as the default when creating the database cluster.
+
+@item @var{config-file} (default: @code{(postgresql-config-file)})
+The configuration file to use when running PostgreSQL. The default
+behaviour uses the postgresql-config-file record with the default values
+for the fields.
+
+@item @var{data-directory} (default: @code{"/var/lib/postgresql/data"})
+Directory in which to store the data.
+
+@item @var{extension-packages} (default: @code{'()})
@cindex postgresql extension-packages
Additional extensions are loaded from packages listed in
@var{extension-packages}. Extensions are available at runtime. For instance,
There is no need to add this field for contrib extensions such as hstore or
dblink as they are already loadable by postgresql. This field is only
required to add extensions provided by other packages.
-@end deffn
+
+@end table
+@end deftp
+
+@subsubheading MariaDB/MySQL
@deffn {Scheme Procedure} mysql-service [#:config (mysql-configuration)]
Return a service that runs @command{mysqld}, the MySQL or MariaDB
@end table
@end deftp
+@subsubheading Memcached
+
@defvr {Scheme Variable} memcached-service-type
This is the service type for the @uref{https://memcached.org/,
Memcached} service, which provides a distributed in memory cache. The
@end table
@end deftp
+@subsubheading MongoDB
+
@defvr {Scheme Variable} mongodb-service-type
This is the service type for @uref{https://www.mongodb.com/, MongoDB}.
The value for the service type is a @code{mongodb-configuration} object.
@end table
@end deftp
+@subsubheading Redis
+
@defvr {Scheme Variable} redis-service-type
This is the service type for the @uref{https://redis.io/, Redis}
key/value store, whose value is a @code{redis-configuration} object.
@table @asis
@item @code{id} (default: @code{""})
-An identifier for ether configuration fields to refer to this key. IDs must be
+An identifier for other configuration fields to refer to this key. IDs must be
unique and must not be empty.
@item @code{address} (default: @code{'()})
effect; this can be used as a trick to implement an external mixer
External Mixer) or no mixer (@code{none}).
-@item @code{extra-options} (default: @code{'()"})
+@item @code{extra-options} (default: @code{'()})
An association list of option symbols to string values to be appended to
the audio output configuration.
@deftypevr {@code{libvirt-configuration} parameter} boolean listen-tls?
Flag listening for secure TLS connections on the public TCP/IP port.
-must set @code{listen} for this to have any effect.
+You must set @code{listen} for this to have any effect.
It is necessary to setup a CA and issue server certificates before using
this capability.
@end deftypevr
@deftypevr {@code{libvirt-configuration} parameter} boolean listen-tcp?
-Listen for unencrypted TCP connections on the public TCP/IP port. must
+Listen for unencrypted TCP connections on the public TCP/IP port. You must
set @code{listen} for this to have any effect.
Using the TCP socket requires SASL authentication by default. Only SASL
mechanisms which support data encryption are allowed. This is
-DIGEST_MD5 and GSSAPI (Kerberos5)
+DIGEST_MD5 and GSSAPI (Kerberos5).
Defaults to @samp{#f}.
@end deftypevr
@deftypevr {@code{libvirt-configuration} parameter} string tls-port
-Port for accepting secure TLS connections This can be a port number, or
-service name
+Port for accepting secure TLS connections. This can be a port number,
+or service name.
Defaults to @samp{"16514"}.
@end deftypevr
@deftypevr {@code{libvirt-configuration} parameter} string tcp-port
-Port for accepting insecure TCP connections This can be a port number,
-or service name
+Port for accepting insecure TCP connections. This can be a port number,
+or service name.
Defaults to @samp{"16509"}.
Logging filters.
A filter allows to select a different logging level for a given category
-of logs The format for a filter is one of:
+of logs. The format for a filter is one of:
@itemize @bullet
@item
with forwarded ports:
@example
-@var{ssh-port}: @code{(+ 11004 (* 1000 @var{ID}))}
+@var{secrets-port}: @code{(+ 11004 (* 1000 @var{ID}))}
@var{ssh-port}: @code{(+ 10022 (* 1000 @var{ID}))}
@var{vnc-port}: @code{(+ 15900 (* 1000 @var{ID}))}
@end example
@defvr {Scheme Variable} ganeti-watcher-service-type
@command{ganeti-watcher} is a script designed to run periodically and ensure
the health of a cluster. It will automatically restart instances that have
-stopped without Ganetis consent, and repairs DRBD links in case a node has
+stopped without Ganeti's consent, and repairs DRBD links in case a node has
rebooted. It also archives old cluster jobs and restarts Ganeti daemons
that are not running. If the cluster parameter @code{ensure_node_health}
is set, the watcher will also shutdown instances and DRBD devices if the
service.
@table @asis
-@item @code{size} (default @var{"1G"})
+@item @code{size} (default @code{"1G"})
This is the amount of space you wish to provide for the zram device. It
accepts a string and can be a number of bytes or use a suffix, eg.:
-@var{"512M"} or @var{1024000}.
-@item @code{compression-algorithm} (default @var{'lzo})
+@code{"512M"} or @code{1024000}.
+@item @code{compression-algorithm} (default @code{'lzo})
This is the compression algorithm you wish to use. It is difficult to
list all the possible compression options, but common ones supported by
-Guix's Linux Libre Kernel include @var{'lzo}, @var{'lz4} and @var{'zstd}.
-@item @code{memory-limit} (default @var{0})
+Guix's Linux Libre Kernel include @code{'lzo}, @code{'lz4} and @code{'zstd}.
+@item @code{memory-limit} (default @code{0})
This is the maximum amount of memory which the zram device can use.
Setting it to '0' disables the limit. While it is generally expected
that compression will be 2:1, it is possible that uncompressable data
can be written to swap and this is a method to limit how much memory can
be used. It accepts a string and can be a number of bytes or use a
-suffix, eg.: @var{"2G"}.
-@item @code{priority} (default @var{-1})
+suffix, eg.: @code{"2G"}.
+@item @code{priority} (default @code{-1})
This is the priority of the swap device created from the zram device.
@code{swapon} accepts values between -1 and 32767, with higher values
indicating higher priority. Higher priority swap will generally be used
@defvr {Scheme Variable} rshiny-service-type
This is a type of service which is used to run a webapp created with
-@code{r-shiny}. This service sets the @code{R_LIBS_USER} environment
+@code{r-shiny}. This service sets the @env{R_LIBS_USER} environment
variable and runs the provided script to call @code{runApp}.
@deftp {Data Type} rshiny-configuration
@table @asis
@item @code{gfxmode} (default: @code{'("auto")})
-The GRUB @code{gfxmode} to set (a list of screen resolution strings, see
+The GRUB @code{gfxmode} to set (a list of screen resolution strings,
@pxref{gfxmode,,, grub, GNU GRUB manual}).
@end table
@end deftp
debugger, GDB, to map binary code to source code; it is required to
debug a compiled program in good conditions.
+This chapter explains how to use separate debug info when packages
+provide it, and how to rebuild packages with debug info when it's
+missing.
+
+@menu
+* Separate Debug Info:: Installing 'debug' outputs.
+* Rebuilding Debug Info:: Building missing debug info.
+@end menu
+
+@node Separate Debug Info
+@section Separate Debug Info
+
The problem with debugging information is that is takes up a fair amount
of disk space. For example, debugging information for the GNU C Library
weighs in at more than 60 MiB. Thus, as a user, keeping all the
@c XXX: keep me up-to-date
The @code{debug} output mechanism in Guix is implemented by the
@code{gnu-build-system} (@pxref{Build Systems}). Currently, it is
-opt-in---debugging information is available only for the packages
-with definitions explicitly declaring a @code{debug} output. This may be
-changed to opt-out in the future if our build farm servers can handle
-the load. To check whether a package has a @code{debug} output, use
-@command{guix package --list-available} (@pxref{Invoking guix package}).
+opt-in---debugging information is available only for the packages with
+definitions explicitly declaring a @code{debug} output. To check
+whether a package has a @code{debug} output, use @command{guix package
+--list-available} (@pxref{Invoking guix package}).
+
+Read on for how to deal with packages lacking a @code{debug} output.
+
+@node Rebuilding Debug Info
+@section Rebuilding Debug Info
+
+@cindex debugging info, rebuilding
+As we saw above, some packages, but not all, provide debugging info in a
+@code{debug} output. What can you do when debugging info is missing?
+The @option{--with-debug-info} option provides a solution to that: it
+allows you to rebuild the package(s) for which debugging info is
+missing---and only those---and to graft those onto the application
+you're debugging. Thus, while it's not as fast as installing a
+@code{debug} output, it is relatively inexpensive.
+
+Let's illustrate that. Suppose you're experiencing a bug in Inkscape
+and would like to see what's going on in GLib, a library that's deep
+down in its dependency graph. As it turns out, GLib does not have a
+@code{debug} output and the backtrace GDB shows is all sadness:
+
+@example
+(gdb) bt
+#0 0x00007ffff5f92190 in g_getenv ()
+ from /gnu/store/@dots{}-glib-2.62.6/lib/libglib-2.0.so.0
+#1 0x00007ffff608a7d6 in gobject_init_ctor ()
+ from /gnu/store/@dots{}-glib-2.62.6/lib/libgobject-2.0.so.0
+#2 0x00007ffff7fe275a in call_init (l=<optimized out>, argc=argc@@entry=1, argv=argv@@entry=0x7fffffffcfd8,
+ env=env@@entry=0x7fffffffcfe8) at dl-init.c:72
+#3 0x00007ffff7fe2866 in call_init (env=0x7fffffffcfe8, argv=0x7fffffffcfd8, argc=1, l=<optimized out>)
+ at dl-init.c:118
+@end example
+
+To address that, you install Inkscape linked against a variant GLib that
+contains debug info:
+
+@example
+guix install inkscape --with-debug-info=glib
+@end example
+
+This time, debugging will be a whole lot nicer:
+
+@example
+$ gdb --args sh -c 'exec inkscape'
+@dots{}
+(gdb) b g_getenv
+Function "g_getenv" not defined.
+Make breakpoint pending on future shared library load? (y or [n]) y
+Breakpoint 1 (g_getenv) pending.
+(gdb) r
+Starting program: /gnu/store/@dots{}-profile/bin/sh -c exec\ inkscape
+@dots{}
+(gdb) bt
+#0 g_getenv (variable=variable@@entry=0x7ffff60c7a2e "GOBJECT_DEBUG") at ../glib-2.62.6/glib/genviron.c:252
+#1 0x00007ffff608a7d6 in gobject_init () at ../glib-2.62.6/gobject/gtype.c:4380
+#2 gobject_init_ctor () at ../glib-2.62.6/gobject/gtype.c:4493
+#3 0x00007ffff7fe275a in call_init (l=<optimized out>, argc=argc@@entry=3, argv=argv@@entry=0x7fffffffd088,
+ env=env@@entry=0x7fffffffd0a8) at dl-init.c:72
+@dots{}
+@end example
+
+Much better!
+Note that there can be packages for which @option{--with-debug-info}
+will not have the desired effect. @xref{Package Transformation Options,
+@option{--with-debug-info}}, for more information.
@node Security Updates
@chapter Security Updates
HCoop / jackhill / guix / guix.git / blobdiff