Merge branch 'master' into staging

2 files changed, 175 insertions, 36 deletions

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 00edd47710..1b1875fa0c 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -298,11 +298,7 @@ This mailing list is backed by a Debbugs instance accessible at
 of submissions.  Each message sent to that mailing list gets a new
 tracking number assigned; people can then follow up on the submission by
 sending email to @code{@var{NNN}@@debbugs.gnu.org}, where @var{NNN} is
-the tracking number.  When sending a patch series, please first send one
-message to @email{guix-patches@@gnu.org}, and then send subsequent
-patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure they are kept
-together.  See @uref{https://debbugs.gnu.org/Advanced.html, the Debbugs
-documentation}, for more information.
+the tracking number (@pxref{Sending a Patch Series}).
 
 Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
 standards, GNU Coding Standards}); you can check the commit history for
@@ -434,7 +430,25 @@ Please follow our code formatting rules, possibly running the
 
 When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as
 a subject.  You may use your email client or the @command{git
-send-email} command.  We prefer to get patches in plain text messages,
-either inline or as MIME attachments.  You are advised to pay attention if
-your email client changes anything like line breaks or indentation which
-could potentially break the patches.
+send-email} command (@pxref{Sending a Patch Series}).  We prefer to get
+patches in plain text messages, either inline or as MIME attachments.
+You are advised to pay attention if your email client changes anything
+like line breaks or indentation which could potentially break the
+patches.
+
+When a bug is resolved, please close the thread by sending an email to
+@email{@var{NNN}-done@@debbugs.gnu.org}.
+
+@unnumberedsubsec Sending a Patch Series
+@anchor{Sending a Patch Series}
+@cindex patch series
+@cindex @code{git send-email}
+@cindex @code{git-send-email}
+
+When sending a patch series (e.g., using @code{git send-email}), please
+first send one message to @email{guix-patches@@gnu.org}, and then send
+subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure
+they are kept together.  See
+@uref{https://debbugs.gnu.org/Advanced.html, the Debbugs documentation}
+for more information.
+@c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html
diff --git a/doc/guix.texi b/doc/guix.texi
index 70a9e36f4d..601cf51b37 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -27,7 +27,7 @@ Copyright @copyright{} 2016 Chris Marusich@*
 Copyright @copyright{} 2016, 2017 Efraim Flashner@*
 Copyright @copyright{} 2016 John Darrington@*
 Copyright @copyright{} 2016 ng0@*
-Copyright @copyright{} 2016 Jan Nieuwenhuizen@*
+Copyright @copyright{} 2016, 2017 Jan Nieuwenhuizen@*
 Copyright @copyright{} 2016 Julien Lepiller@*
 Copyright @copyright{} 2016 Alex ter Weele@*
 Copyright @copyright{} 2017 Clément Lassieur@*
@@ -38,8 +38,9 @@ Copyright @copyright{} 2017 Thomas Danckaert@*
 Copyright @copyright{} 2017 humanitiesNerd@*
 Copyright @copyright{} 2017 Christopher Allan Webber@*
 Copyright @copyright{} 2017 Marius Bakke@*
-Copyright @copyright{} 2017 Hartmut Goebel
+Copyright @copyright{} 2017 Hartmut Goebel@*
 Copyright @copyright{} 2017 Maxim Cournoyer@*
+Copyright @copyright{} 2017 Tobias Geerinckx-Rice
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -2142,6 +2143,8 @@ your system has unpatched security vulnerabilities.
 @cindex security
 @cindex digital signatures
 @cindex substitutes, authorization thereof
+@cindex access control list (ACL), for substitutes
+@cindex ACL (access control list), for substitutes
 To allow Guix to download substitutes from @code{hydra.gnu.org} or a
 mirror thereof, you
 must add its public key to the access control list (ACL) of archive
@@ -2190,9 +2193,29 @@ The following files would be downloaded:
 This indicates that substitutes from @code{hydra.gnu.org} are usable and
 will be downloaded, when possible, for future builds.
 
-Guix ignores substitutes that are not signed, or that are not signed by
-one of the keys listed in the ACL.  It also detects and raises an error
-when attempting to use a substitute that has been tampered with.
+Guix detects and raises an error when attempting to use a substitute
+that has been tampered with.  Likewise, it ignores substitutes that are
+not signed, or that are not signed by one of the keys listed in the ACL.
+
+There is one exception though: if an unauthorized server provides
+substitutes that are @emph{bit-for-bit identical} to those provided by
+an authorized server, then the unauthorized server becomes eligible for
+downloads.  For example, assume we have chosen two substitute servers
+with this option:
+
+@example
+--substitute-urls="https://a.example.org https://b.example.org"
+@end example
+
+@noindent
+@cindex reproducible builds
+If the ACL contains only the key for @code{b.example.org}, and if
+@code{a.example.org} happens to serve the @emph{exact same} substitutes,
+then Guix will download substitutes from @code{a.example.org} because it
+comes first in the list and can be considered a mirror of
+@code{b.example.org}.  In practice, independent build machines usually
+produce the same binaries, thanks to bit-reproducible builds (see
+below).
 
 @vindex http_proxy
 Substitutes are downloaded over HTTP or HTTPS.
@@ -3788,6 +3811,61 @@ need to be copied into place.  It copies font files to standard
 locations in the output directory.
 @end defvr
 
+@defvr {Scheme Variable} meson-build-system
+This variable is exported by @code{(guix build-system meson)}.  It
+implements the build procedure for packages that use
+@url{http://mesonbuild.com, Meson} as their build system.
+
+It adds both Meson and @uref{https://ninja-build.org/, Ninja} to the set
+of inputs, and they can be changed with the parameters @code{#:meson}
+and @code{#:ninja} if needed.  The default Meson is
+@code{meson-for-build}, which is special because it doesn't clear the
+@code{RUNPATH} of binaries and libraries when they are installed.
+
+This build system is an extension of @var{gnu-build-system}, but with the
+following phases changed to some specific for Meson:
+
+@table @code
+
+@item configure
+The phase runs @code{meson} with the flags specified in
+@code{#:configure-flags}.  The flag @code{--build-type} is always set to
+@code{plain} unless something else is specified in @code{#:build-type}.
+
+@item build
+The phase runs @code{ninja} to build the package in parallel by default, but
+this can be changed with @code{#:parallel-build?}.
+
+@item check
+The phase runs @code{ninja} with the target specified in @code{#:test-target},
+which is @code{"test"} by default.
+
+@item install
+The phase runs @code{ninja install} and can not be changed.
+@end table
+
+Apart from that, the build system also adds the following phases:
+
+@table @code
+
+@item fix-runpath
+This phase tries to locate the local directories in the package being build,
+which has libraries that some of the binaries need.  If any are found, they will
+be added to the programs @code{RUNPATH}.  It is needed because
+@code{meson-for-build} keeps the @code{RUNPATH} of binaries and libraries from
+when they are build, but often that is not the @code{RUNPATH} we want.
+Therefor it is also shrinked to the minimum needed by the program.
+
+@item glib-or-gtk-wrap
+This phase is the phase provided by @code{glib-or-gtk-build-system}, and it
+is not enabled by default.  It can be enabled with @code{#:glib-or-gtk?}.
+
+@item glib-or-gtk-compile-schemas
+This phase is the phase provided by @code{glib-or-gtk-build-system}, and it
+is not enabled by default.  It can be enabled with @code{#:glib-or-gtk?}.
+@end table
+@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,
@@ -6382,10 +6460,10 @@ Use substitute information from @var{urls}.
 Sort lines according to @var{key}, one of the following options:
 
 @table @code
-@item closure
-the total size of the item's closure (the default);
 @item self
-the size of each item.
+the size of each item (the default);
+@item closure
+the total size of the item's closure.
 @end table
 
 @item --map-file=@var{file}
@@ -7852,7 +7930,12 @@ Once you are done partitioning the target hard disk drive, you have to
 create a file system on the relevant partition(s)@footnote{Currently
 GuixSD only supports ext4 and btrfs file systems.  In particular, code
 that reads partition UUIDs and labels only works for these file system
-types.}.
+types.}.  For the ESP, if you have one and assuming it is
+@file{/dev/sda2}, run:
+
+@example
+mkfs.fat -F32 /dev/sda2
+@end example
 
 Preferably, assign partitions a label so that you can easily and
 reliably refer to them in @code{file-system} declarations (@pxref{File
@@ -8163,8 +8246,9 @@ environment variable---in addition to the per-user profiles
 provides all the tools one would expect for basic user and administrator
 tasks---including the GNU Core Utilities, the GNU Networking Utilities,
 the GNU Zile lightweight text editor, @command{find}, @command{grep},
-etc.  The example above adds tcpdump to those, taken from the @code{(gnu
-packages admin)} module (@pxref{Package Modules}).  The
+etc.  The example above adds GNU@tie{}Screen and OpenSSH to those,
+taken from the @code{(gnu packages screen)} and @code{(gnu packages ssh)}
+modules (@pxref{Package Modules}).  The
 @code{(list package output)} syntax can be used to add a specific output
 of a package:
 
@@ -11658,7 +11742,7 @@ and policy files.  For example, to allow avahi-daemon to use the system bus,
 
 @deffn {Scheme Procedure} elogind-service [#:config @var{config}]
 Return a service that runs the @code{elogind} login and
-seat management daemon.  @uref{https://github.com/andywingo/elogind,
+seat management daemon.  @uref{https://github.com/elogind/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.
@@ -14036,7 +14120,7 @@ A simple example configuration is given below.
 @example
 (service nginx-service-type
          (nginx-configuration
-           (server-list
+           (server-blocks
              (list (nginx-server-configuration
                      (server-name '("www.example.com"))
                      (root "/srv/http/www.example.com")
@@ -14084,7 +14168,7 @@ The directory to which NGinx will write log files.
 The directory in which NGinx will create a pid file, and write temporary
 files.
 
-@item @code{server-list} (default: @code{'()})
+@item @code{server-blocks} (default: @code{'()})
 A list of @dfn{server blocks} to create in the generated configuration
 file, the elements should be of type
 @code{<nginx-server-configuration>}.
@@ -14095,7 +14179,7 @@ HTTPS.
 @example
 (service nginx-service-type
          (nginx-configuration
-           (server-list
+           (server-blocks
              (list (nginx-server-configuration
                      (server-name '("www.example.com"))
                      (root "/srv/http/www.example.com")
@@ -14104,12 +14188,12 @@ HTTPS.
                      (ssl-certificate-key #f))))))
 @end example
 
-@item @code{upstream-list} (default: @code{'()})
+@item @code{upstream-blocks} (default: @code{'()})
 A list of @dfn{upstream blocks} to create in the generated configuration
 file, the elements should be of type
 @code{<nginx-upstream-configuration>}.
 
-Configuring upstreams through the @code{upstream-list} can be useful
+Configuring upstreams through the @code{upstream-blocks} can be useful
 when combined with @code{locations} in the
 @code{<nginx-server-configuration>} records.  The following example
 creates a server configuration with one location configuration, that
@@ -14120,7 +14204,7 @@ requests with two servers.
 (service
   nginx-service-type
   (nginx-configuration
-    (server-list
+    (server-blocks
       (list (nginx-server-configuration
               (server-name '("www.example.com"))
               (root "/srv/http/www.example.com")
@@ -14132,20 +14216,19 @@ requests with two servers.
                   (nginx-location-configuration
                   (uri "/path1")
                   (body '("proxy_pass http://server-proxy;"))))))))
-    (upstream-list
+    (upstream-blocks
       (list (nginx-upstream-configuration
               (name "server-proxy")
               (servers (list "server1.example.com"
                              "server2.example.com")))))))
 @end example
 
-@item @code{config-file} (default: @code{#f})
-If the @var{config-file} is provided, this will be used, rather than
+@item @code{file} (default: @code{#f})
+If a configuration @var{file} is provided, this will be used, rather than
 generating a configuration file from the provided @code{log-directory},
-@code{run-directory}, @code{server-list} and @code{upstream-list}.  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.
+@code{run-directory}, @code{server-blocks} and @code{upstream-blocks}.  For
+proper operation, these arguments should match what is in @var{file} to ensure
+that the directories are created when the service is activated.
 
 This can be useful if you have an existing configuration file, or it's
 not possible to do what is required through the other parts of the
@@ -15223,7 +15306,7 @@ packages, as prescribed in the @file{gnu-system.scm} example spec:
                (#:branch . "master"))))
   (service cuirass-service-type
            (cuirass-configuration
-            (specifications #~(list #$spec)))))
+            (specifications #~(list '#$spec)))))
 @end example
 
 While information related to build jobs is located directly in the
@@ -15254,7 +15337,7 @@ Cuirass jobs.
 Location of sqlite database which contains the build results and previously
 added specifications.
 
-@item @code{port} (default: @code{8080})
+@item @code{port} (default: @code{8081})
 Port number used by the HTTP server.
 
 @item @code{specifications} (default: @code{#~'()})
@@ -17368,6 +17451,42 @@ operating system is instantiated.  Currently the following values are
 supported:
 
 @table @code
+@item search
+Display available service type definitions that match the given regular
+expressions, sorted by relevance:
+
+@example
+$ guix system search console font
+name: console-fonts
+location: gnu/services/base.scm:729:2
+extends: shepherd-root
+description: Install the given fonts on the specified ttys (fonts are
++ per virtual console on GNU/Linux).  The value of this service is a list
++ of tty/font pairs like:
++ 
++      '(("tty1" . "LatGrkCyr-8x16"))
+relevance: 20
+
+name: mingetty
+location: gnu/services/base.scm:1048:2
+extends: shepherd-root
+description: Provide console login using the `mingetty' program.
+relevance: 2
+
+name: login
+location: gnu/services/base.scm:775:2
+extends: pam
+description: Provide a console log-in service as specified by its
++ configuration value, a `login-configuration' object.
+relevance: 2
+
+@dots{}
+@end example
+
+As for @command{guix package --search}, the result is written in
+@code{recutils} format, which makes it easy to filter the output
+(@pxref{Top, GNU recutils databases,, recutils, GNU recutils manual}).
+
 @item reconfigure
 Build the operating system described in @var{file}, activate it, and
 switch to it@footnote{This action (and the related actions
@@ -17997,6 +18116,12 @@ Udev extensions are composed into a list of rules, but the udev service
 value is itself a @code{<udev-configuration>} record.  So here, we
 extend that record by appending the list of rules it contains to the
 list of contributed rules.
+
+@item description
+This is a string giving an overview of the service type.  The string can
+contain Texinfo markup (@pxref{Overview,,, texinfo, GNU Texinfo}).  The
+@command{guix system search} command searches these strings and displays
+them (@pxref{Invoking guix system}).
 @end table
 
 There can be only one instance of an extensible service type such as