Merge branch 'master' into staging

1 files changed, 134 insertions, 67 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index 216422fe31..3d1b097447 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -35,7 +35,7 @@ Copyright @copyright{} 2016, 2017, 2018 Chris Marusich@*
 Copyright @copyright{} 2016, 2017, 2018, 2019, 2020 Efraim Flashner@*
 Copyright @copyright{} 2016 John Darrington@*
 Copyright @copyright{} 2016, 2017 Nikita Gillmann@*
-Copyright @copyright{} 2016, 2017, 2018, 2019 Jan Nieuwenhuizen@*
+Copyright @copyright{} 2016, 2017, 2018, 2019, 2020 Jan Nieuwenhuizen@*
 Copyright @copyright{} 2016 Julien Lepiller@*
 Copyright @copyright{} 2016 Alex ter Weele@*
 Copyright @copyright{} 2016, 2017, 2018, 2019 Christopher Baines@*
@@ -1831,7 +1831,7 @@ how to use it, hit the @key{RET} key (``return'' or ``enter'') on the
 link that follows: @pxref{Top, Info reader,, info-stnd, Stand-alone GNU
 Info}.  Hit @kbd{l} afterwards to come back here.
 
-Alternately, run @command{info info} in another tty to keep the manual
+Alternatively, run @command{info info} in another tty to keep the manual
 available.
 @end quotation
 @end ifinfo
@@ -2021,7 +2021,7 @@ Guix System in a virtual machine (VM).
 @section Preparing for Installation
 
 Once you have booted, you can use the guided graphical installer, which makes
-it easy to get started (@pxref{Guided Graphical Installation}).  Alternately,
+it easy to get started (@pxref{Guided Graphical Installation}).  Alternatively,
 if you are already familiar with GNU/Linux and if you want more control than
 what the graphical installer provides, you can choose the ``manual''
 installation process (@pxref{Manual Installation}).
@@ -3900,6 +3900,21 @@ Use @var{profile} instead of @file{~/.config/guix/current}.
 Show which channel commit(s) would be used and what would be built or
 substituted but do not actually do it.
 
+@item --allow-downgrades
+Allow pulling older or unrelated revisions of channels than those
+currently in use.
+
+@cindex downgrade attacks, protection against
+By default, @command{guix pull} protects against so-called ``downgrade
+attacks'' whereby the Git repository of a channel would be reset to an
+earlier or unrelated revision of itself, potentially leading you to
+install older, known-vulnerable versions of software packages.
+
+@quotation Note
+Make sure you understand its security implications before using
+@option{--allow-downgrades}.
+@end quotation
+
 @item --system=@var{system}
 @itemx -s @var{system}
 Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
@@ -5966,9 +5981,13 @@ specified in the @code{uri} field as a @code{git-reference} object; a
 @end table
 
 @item @code{sha256}
-A bytevector containing the SHA-256 hash of the source.  Typically the
-@code{base32} form is used here to generate the bytevector from a
-base-32 string.
+A bytevector containing the SHA-256 hash of the source.  This is
+equivalent to providing a @code{content-hash} SHA256 object in the
+@code{hash} field described below.
+
+@item @code{hash}
+The @code{content-hash} object of the source---see below for how to use
+@code{content-hash}.
 
 You can obtain this information using @code{guix download}
 (@pxref{Invoking guix download}) or @code{guix hash} (@pxref{Invoking
@@ -6013,6 +6032,30 @@ this is @code{#f}, a sensible default is used.
 @end table
 @end deftp
 
+@deftp {Data Type} content-hash @var{value} [@var{algorithm}]
+Construct a content hash object for the given @var{algorithm}, and with
+@var{value} as its hash value.  When @var{algorithm} is omitted, assume
+it is @code{sha256}.
+
+@var{value} can be a literal string, in which case it is base32-decoded,
+or it can be a bytevector.
+
+The following forms are all equivalent:
+
+@lisp
+(content-hash "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj")
+(content-hash "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj"
+              sha256)
+(content-hash (base32
+               "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj"))
+(content-hash (base64 "kkb+RPaP7uyMZmu4eXPVkM4BN8yhRd8BTHLslb6f/Rc=")
+              sha256)
+@end lisp
+
+Technically, @code{content-hash} is currently implemented as a macro.
+It performs sanity checks at macro-expansion time, when possible, such
+as ensuring that @var{value} has the right size for @var{algorithm}.
+@end deftp
 
 @node Build Systems
 @section Build Systems
@@ -9018,6 +9061,11 @@ Certificates}), unless @option{--no-check-certificate} is used.
 The following options are available:
 
 @table @code
+@item --hash=@var{algorithm}
+@itemx -H @var{algorithm}
+Compute a hash using the specified @var{algorithm}.  @xref{Invoking guix
+hash}, for more information.
+
 @item --format=@var{fmt}
 @itemx -f @var{fmt}
 Write the hash in the format specified by @var{fmt}.  For more
@@ -9057,11 +9105,21 @@ following options:
 
 @table @code
 
+@item --hash=@var{algorithm}
+@itemx -H @var{algorithm}
+Compute a hash using the specified @var{algorithm}, @code{sha256} by
+default.
+
+@var{algorithm} must the name of a cryptographic hash algorithm
+supported by Libgcrypt @i{via} Guile-Gcrypt---e.g., @code{sha512} or
+@code{sha3-256} (@pxref{Hash Functions,,, guile-gcrypt, Guile-Gcrypt
+Reference Manual}).
+
 @item --format=@var{fmt}
 @itemx -f @var{fmt}
 Write the hash in the format specified by @var{fmt}.
 
-Supported formats: @code{nix-base32}, @code{base32}, @code{base16}
+Supported formats: @code{base64}, @code{nix-base32}, @code{base32}, @code{base16}
 (@code{hex} and @code{hexadecimal} can be used as well).
 
 If the @option{--format} option is not specified, @command{guix hash}
@@ -9542,7 +9600,7 @@ gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.
 gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
 @end example
 
-Alternately, one can specify packages to consider, in which case a
+Alternatively, one can specify packages to consider, in which case a
 warning is emitted for packages that lack an updater:
 
 @example
@@ -10727,7 +10785,7 @@ guix challenge git \
 This automatically invokes @command{diffoscope}, which displays detailed
 information about files that differ.
 
-Alternately, we can do something along these lines (@pxref{Invoking guix
+Alternatively, we can do something along these lines (@pxref{Invoking guix
 archive}):
 
 @example
@@ -14519,7 +14577,7 @@ subsystem name and a command (with optional arguments) to execute upon
 subsystem request.
 
 The command @command{internal-sftp} implements an in-process SFTP
-server.  Alternately, one can specify the @command{sftp-server} command:
+server.  Alternatively, one can specify the @command{sftp-server} command:
 @lisp
 (service openssh-service-type
          (openssh-configuration
@@ -26940,14 +26998,14 @@ The GRUB @code{gfxmode} to set (a list of screen resolution strings, see
 @end table
 @end deftp
 
-@defvr {Scheme Variable} %default-theme
-This is the default GRUB theme used by the operating system if no
+@deffn {Scheme Procedure} grub-theme
+Return the default GRUB theme used by the operating system if no
 @code{theme} field is specified in @code{bootloader-configuration}
 record.
 
 It comes with a fancy background image displaying the GNU and Guix
 logos.
-@end defvr
+@end deffn
 
 For example, to override the default resolution, you may use something
 like
@@ -26957,7 +27015,7 @@ like
  (bootloader-configuration
  ;; @dots{}
  (theme (grub-theme
-         (inherit %default-theme)
+         (inherit (grub-theme))
          (gfxmode '("1024x786x32" "auto"))))))
 @end lisp
 
@@ -28718,10 +28776,8 @@ Binutils, libc, and the other packages mentioned above---the
 @dfn{bootstrap binaries}.
 
 These bootstrap binaries are ``taken for granted'', though we can also
-re-create them if needed (more on that later).
-
-For @code{i686-linux} and @code{x86_64-linux} the Guix bootstrap process is
-more elaborate, @pxref{Reduced Binary Seed Bootstrap}.
+re-create them if needed (@pxref{Preparing to Use the Bootstrap
+Binaries}).
 
 @menu
 * Reduced Binary Seed Bootstrap::  A Bootstrap worthy of GNU.
@@ -28737,60 +28793,71 @@ Coreutils, Awk, Findutils, `sed', and `grep' and Guile, GCC, Binutils, and the
 GNU C Library (@pxref{Bootstrapping}).  Usually, these bootstrap binaries are
 ``taken for granted.''
 
-Taking these binaries for granted means that we consider them to be a correct
-and trustworthy `seed' for building the complete system.  Therein lies a
-problem: the current combined size of these bootstrap binaries is about 250MB
-(@pxref{Bootstrappable Builds,,, mes, GNU Mes}).  Auditing or even inspecting
-these is next to impossible.
+Taking the bootstrap binaries for granted means that we consider them to
+be a correct and trustworthy ``seed'' for building the complete system.
+Therein lies a problem: the combined size of these bootstrap binaries is
+about 250MB (@pxref{Bootstrappable Builds,,, mes, GNU Mes}).  Auditing
+or even inspecting these is next to impossible.
 
-For @code{i686-linux} and @code{x86_64-linux}, Guix now features a ``Reduced
-Binary Seed'' bootstrap @footnote{We would like to say: ``Full Source
-Bootstrap'' and while we are working towards that goal it would be hyperbole
-to use that term for what we do now.}.
+For @code{i686-linux} and @code{x86_64-linux}, Guix now features a
+``Reduced Binary Seed'' bootstrap @footnote{We would like to say: ``Full
+Source Bootstrap'' and while we are working towards that goal it would
+be hyperbole to use that term for what we do now.}.
 
 The Reduced Binary Seed bootstrap removes the most critical tools---from a
 trust perspective---from the bootstrap binaries: GCC, Binutils and the GNU C
 Library are replaced by: @code{bootstrap-mescc-tools} (a tiny assembler and
 linker) and @code{bootstrap-mes} (a small Scheme Interpreter and a C compiler
-written in Scheme and the Mes C Library, built for TinyCC and for GCC).  Using
-these new binary seeds and a new set of
-@c
-packages@footnote{@c
-nyacc-boot,
-mes-boot,
-tcc-boot0,
-tcc-boot,
-make-mesboot0,
-diffutils-mesboot,
-binutils-mesboot0,
-gcc-core-mesboot,
-mesboot-headers,
-glibc-mesboot0,
-gcc-mesboot0,
-binutils-mesboot,
-make-mesboot,
-gcc-mesboot1,
-gcc-mesboot1-wrapper,
-glibc-headers-mesboot,
-glibc-mesboot,
-gcc-mesboot,
-and
-gcc-mesboot-wrapper.
-}
-@c
-the ``missing'' Binutils, GCC, and the GNU C Library are built from source.
-From here on the more traditional bootstrap process resumes.  This approach
-has reduced the bootstrap binaries in size to about 130MB.  Work is ongoing to
-reduce this further.  If you are interested, join us on @code{#bootstrappable}
-on the Freenode IRC network.
-
-@c ./pre-inst-env guix graph --type=bag -e '(begin (use-modules (guix packages)) (%current-system "i686-linux") (@@ (gnu packages commencement) gcc-mesboot))' > doc/images/gcc-mesboot-bag-graph.dot
-@c dot -T png doc/images/gcc-mesboot-bag-graph.dot > doc/images/gcc-mesboot-bag-graph.png
-
-Below is the generated dependency graph for @code{gcc-mesboot}, the bootstrap
-compiler used to build the rest of GuixSD.
-
-@image{images/gcc-mesboot-bag-graph,6in,,Dependency graph of the gcc-mesboot}
+written in Scheme and the Mes C Library, built for TinyCC and for GCC).
+
+Using these new binary seeds the ``missing'' Binutils, GCC, and the GNU
+C Library are built from source.  From here on the more traditional
+bootstrap process resumes.  This approach has reduced the bootstrap
+binaries in size to about 145MB in Guix v1.1.
+
+The next step that Guix has taken is to replace the shell and all its
+utilities with implementations in Guile Scheme, the @emph{Scheme-only
+bootstrap}.  Gash (@pxref{Gash,,, gash, The Gash manual}) is a
+POSIX-compatible shell that replaces Bash, and it comes with Gash Utils
+which has minimalist replacements for Awk, the GNU Core Utilities, Grep,
+Gzip, Sed, and Tar.  The rest of the bootstrap binary seeds that were
+removed are now built from source.
+
+Building the GNU System from source is currently only possibly by adding
+some historical GNU packages as intermediate steps@footnote{Packages
+such as @code{gcc-2.95.3}, @code{binutils-2.14}, @code{glibc-2.2.5},
+@code{gzip-1.2.4}, @code{tar-1.22}, and some others.  For details, see
+@file{gnu/packages/commencement.scm}.}.  As Gash and Gash Utils mature,
+and GNU packages become more bootstrappable again (e.g., new releases of
+GNU Sed will also ship as gzipped tarballs again, as alternative to the
+hard to bootstrap @code{xz}-compression), this set of added packages can
+hopefully be reduced again.
+
+The graph below shows the resulting dependency graph for
+@code{gcc-core-mesboot0}, the bootstrap compiler used for the
+traditional bootstrap of the rest of the Guix System.
+
+@c ./pre-inst-env guix graph -e '(@@ (gnu packages commencement) gcc-core-mesboot0)' | sed -re 's,((bootstrap-mescc-tools|bootstrap-mes|guile-bootstrap).*shape =) box,\1 ellipse,' > doc/images/gcc-core-mesboot0-graph.dot
+@image{images/gcc-core-mesboot0-graph,6in,,Dependency graph of gcc-core-mesboot0}
+
+The only significant binary bootstrap seeds that remain@footnote{
+Ignoring the 68KB @code{mescc-tools}; that will be removed later,
+together with @code{mes}.} are a Scheme intepreter and a Scheme
+compiler: GNU Mes and GNU Guile@footnote{Not shown in this graph are the
+static binaries for @file{bash}, @code{tar}, and @code{xz} that are used
+to get Guile running.}.
+
+This further reduction has brought down the size of the binary seed to
+about 60MB for @code{i686-linux} and @code{x86_64-linux}.
+
+Work is ongoing to remove all binary blobs from our free software
+bootstrap stack, working towards a Full Source Bootstrap.  Also ongoing
+is work to bring these bootstraps to the @code{arm-linux} and
+@code{aarch64-linux} architectures and to the Hurd.
+
+If you are interested, join us on @samp{#bootstrappable} on the Freenode
+IRC network or discuss on @email{bug-mes@@gnu.org} or
+@email{gash-devel@@nongnu.org}.
 
 @node Preparing to Use the Bootstrap Binaries
 @section Preparing to Use the Bootstrap Binaries
@@ -28810,7 +28877,7 @@ guix graph -t derivation \
   | dot -Tps > gcc.ps
 @end example
 
-or, for the Reduced Binary Seed bootstrap
+or, for the further Reduced Binary Seed bootstrap
 
 @example
 guix graph -t derivation \