Merge branch 'master' into core-updates

1 files changed, 124 insertions, 19 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index 592ec3cb1d..a650a55d51 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -399,6 +399,21 @@ for instance with:
 # ln -s /var/guix/profiles/per-user/root/guix-profile/bin/guix
 @end example
 
+It is also a good idea to make the Info version of this manual available
+there:
+
+@example
+# mkdir -p /usr/local/share/info
+# cd /usr/local/share/info
+# for i in /var/guix/profiles/per-user/root/guix-profile/share/info/* ;
+  do ln -s $i ; done
+@end example
+
+That way, assuming @file{/usr/local/share/info} is in the search path,
+running @command{info guix} will open this manual (@pxref{Other Info
+Directories,,, texinfo, GNU Texinfo}, for more details on changing the
+Info search path.)
+
 @item
 To use substitutes from @code{hydra.gnu.org} (@pxref{Substitutes}),
 authorize them:
@@ -754,7 +769,7 @@ machines, since offloading works by invoking the @code{guix archive} and
 this is the case by running:
 
 @example
-lsh build-machine guile -c '(use-modules (guix config))'
+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
@@ -3973,6 +3988,14 @@ Keep the build tree of failed builds.  Thus, if a build fail, its build
 tree is kept under @file{/tmp}, in a directory whose name is shown at
 the end of the build log.  This is useful when debugging build issues.
 
+@item --keep-going
+@itemx -k
+Keep going when some of the derivations fail to build; return only once
+all the builds have either completed or failed.
+
+The default behavior is to stop as soon as one of the specified
+derivations has failed.
+
 @item --dry-run
 @itemx -n
 Do not build the derivations.
@@ -4271,11 +4294,12 @@ guix import cpan Acme::Boolean
 
 @item cran
 @cindex CRAN
+@cindex Bioconductor
 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 package's DESCRIPTION file.
+Information is extracted from the package's @code{DESCRIPTION} file.
 
 The command command below imports meta-data for the @code{Cairo}
 R package:
@@ -4284,6 +4308,21 @@ R package:
 guix import cran Cairo
 @end example
 
+When @code{--archive=bioconductor} is added, meta-data is imported from
+@uref{http://www.bioconductor.org/, Bioconductor}, a repository of R
+packages for for the analysis and comprehension of high-throughput
+genomic data in bioinformatics.
+
+Information is extracted from a package's @code{DESCRIPTION} file
+published on the web interface of the Bioconductor SVN repository.
+
+The command command below imports meta-data for the @code{GenomicRanges}
+R package:
+
+@example
+guix import cran --archive=bioconductor GenomicRanges
+@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
@@ -4482,6 +4521,8 @@ the updater for GNOME packages;
 the updater for @uref{http://elpa.gnu.org/, ELPA} packages;
 @item cran
 the updater for @uref{http://cran.r-project.org/, CRAN} packages;
+@item bioconductor
+the updater for @uref{http://www.bioconductor.org/, Bioconductor} R packages;
 @item pypi
 the updater for @uref{https://pypi.python.org, PyPI} packages.
 @end table
@@ -5674,17 +5715,23 @@ above, such as @code{host-name} and @code{bootloader}, are mandatory.
 Others, such as @code{packages} and @code{services}, can be omitted, in
 which case they get a default value.
 
+Below we discuss the effect of some of the most important fields
+(@pxref{operating-system Reference}, for details about all the available
+fields), and how to @dfn{instantiate} the operating system using
+@command{guix system}.
+
+@unnumberedsubsubsec Globally-Visible Packages
+
 @vindex %base-packages
-The @code{packages} field lists
-packages that will be globally visible on the system, for all user
-accounts---i.e., in every user's @code{PATH} environment variable---in
-addition to the per-user profiles (@pxref{Invoking guix package}).  The
-@var{%base-packages} variable 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 @code{packages} field lists packages that will be globally visible
+on the system, for all user accounts---i.e., in every user's @code{PATH}
+environment variable---in addition to the per-user profiles
+(@pxref{Invoking guix package}).  The @var{%base-packages} variable
+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}).
 
 @findex specification->package
 Referring to packages by variable name, like @var{tcpdump} above, has
@@ -5706,6 +5753,8 @@ version:
                     %base-packages)))
 @end lisp
 
+@unnumberedsubsubsec System Services
+
 @vindex %base-services
 The @code{services} field lists @dfn{system services} to be made
 available when the system starts (@pxref{Services}).
@@ -5754,10 +5803,24 @@ more, would look like this:
 @xref{Desktop Services}, for the exact list of services provided by
 @var{%desktop-services}.  @xref{X.509 Certificates}, for background
 information about the @code{nss-certs} package that is used here.
-@xref{operating-system Reference}, for details about all the available
-@code{operating-system} fields.
 
-Assuming the above snippet is stored in the @file{my-system-config.scm}
+Again, @var{%desktop-services} is just a list of service objects.  If
+you want to remove services from there, you can do so using the
+procedures for list filtering (@pxref{SRFI-1 Filtering and
+Partitioning,,, guile, GNU Guile Reference Manual}).  For instance, the
+following expression returns a list that contains all the services in
+@var{%desktop-services} minus the Avahi service:
+
+@example
+(remove (lambda (service)
+          (eq? (service-kind service) avahi-service-type))
+        %desktop-services)
+@end example
+
+@unnumberedsubsubsec Instantiating the System
+
+Assuming the @code{operating-system} declaration
+is stored in the @file{my-system-config.scm}
 file, the @command{guix system reconfigure my-system-config.scm} command
 instantiates that configuration, and makes it the default GRUB boot
 entry (@pxref{Invoking guix system}).
@@ -5779,6 +5842,8 @@ something went wrong with the latest generation.  Reassuring, no?  The
 @command{guix system list-generations} command lists the system
 generations available on disk.
 
+@unnumberedsubsubsec The Programming Interface
+
 At the Scheme level, the bulk of an @code{operating-system} declaration
 is instantiated with the following monadic procedure (@pxref{The Store
 Monad}):
@@ -5792,6 +5857,11 @@ the packages, configuration files, and other supporting files needed to
 instantiate @var{os}.
 @end deffn
 
+This procedure is provided by the @code{(gnu system)} module.  Along
+with @code{(gnu services)} (@pxref{Services}), this module contains the
+guts of GuixSD.  Make sure to visit it!
+
+
 @node operating-system Reference
 @subsection @code{operating-system} Reference
 
@@ -6288,7 +6358,7 @@ using the @code{locale} field of the @code{operating-system} declaration
 That locale must be among the @dfn{locale definitions} that are known to
 the system---and these are specified in the @code{locale-definitions}
 slot of @code{operating-system}.  The default value includes locale
-definition for some widely used locales, but not for all the available
+definitions for some widely used locales, but not for all the available
 locales, in order to save space.
 
 If the locale specified in the @code{locale} field is not among the
@@ -6762,13 +6832,14 @@ and lines for hidden services added via @code{tor-hidden-service}.  Run
 @command{man tor} for information about the configuration file.
 @end deffn
 
+@cindex hidden service
 @deffn {Scheme Procedure} tor-hidden-service @var{name} @var{mapping}
 Define a new Tor @dfn{hidden service} called @var{name} and implementing
 @var{mapping}.  @var{mapping} is a list of port/host tuples, such as:
 
 @example
- '((22 \"127.0.0.1:22\")
-   (80 \"127.0.0.1:8080\"))
+ '((22 "127.0.0.1:22")
+   (80 "127.0.0.1:8080"))
 @end example
 
 In this example, port 22 of the hidden service is mapped to local port 22, and
@@ -8907,7 +8978,7 @@ Now that you know all the features that initial RAM disks produced by
 further.
 
 @deffn {Monadic Procedure} base-initrd @var{file-systems} @
-       [#:qemu-networking? #f] [#:virtio? #f] [#:volatile-root? #f] @
+       [#:qemu-networking? #f] [#:virtio? #t] [#:volatile-root? #f] @
        [#:extra-modules '()] [#:mapped-devices '()]
 Return a monadic derivation that builds a generic initrd.  @var{file-systems} is
 a list of file-systems to be mounted by the initrd, possibly in addition to
@@ -10060,6 +10131,40 @@ If we also wanted GTK+ 3.8.2, this would be packaged as
     ...))
 @end example
 
+@c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>,
+@c for a discussion of what follows.
+@cindex version number, for VCS snapshots
+Occasionally, we package snapshots of upstream's version control system
+(VCS) instead of formal releases.  This should remain exceptional,
+because it is up to upstream developers to clarify what the stable
+release is.  Yet, it is sometimes necessary.  So, what should we put in
+the @code{version} field?
+
+Clearly, we need to make the commit identifier of the VCS snapshot
+visible in the version string, but we also need to make sure that the
+version string is monotonically increasing so that @command{guix package
+--upgrade} can determine which version is newer.  Since commit
+identifiers, notably with Git, are not monotonically increasing, we add
+a revision number that we increase each time we upgrade to a newer
+snapshot.  The resulting version string looks like this:
+
+@example
+2.0.11-3.cabba9e
+  ^    ^    ^
+  |    |    `-- upstream commit ID
+  |    |
+  |    `--- Guix package revision
+  |
+latest upstream version
+@end example
+
+It is a good idea to strip commit identifiers in the @code{version}
+field to, say, 7 digits.  It avoids an aesthetic annoyance (assuming
+aesthetics have a role to play here) as well as problems related to OS
+limits such as the maximum shebang length (127 bytes for the Linux
+kernel.)  It is best to use the full commit identifiers in
+@code{origin}s, though, to avoid ambiguities.
+
 @node Synopses and Descriptions
 @subsection Synopses and Descriptions