Merge branch 'master' into staging

2 files changed, 196 insertions, 9 deletions

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 6a2564b07d..02c7c5ae59 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -225,8 +225,7 @@ $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
 @noindent
 @cindex REPL
 @cindex read-eval-print loop
-@dots{} and for a REPL (@pxref{Using Guile Interactively,,, guile, Guile
-Reference Manual}):
+@dots{} and for a REPL (@pxref{Using Guix Interactively}):
 
 @example
 $ ./pre-inst-env guile
@@ -279,8 +278,8 @@ prepared Guile object (@file{.go}) files.
 
 You can run @command{make} automatically as you work using
 @command{watchexec} from the @code{watchexec} package.  For example,
-to build again each time you update a package file, you can run
-@samp{watchexec -w gnu/packages make -j4}.
+to build again each time you update a package file, run
+@samp{watchexec -w gnu/packages -- make -j4}.
 
 @node The Perfect Setup
 @section The Perfect Setup
@@ -292,7 +291,7 @@ Manual}).  First, you need more than an editor, you need
 wonderful @url{https://nongnu.org/geiser/, Geiser}.  To set that up, run:
 
 @example
-guix package -i emacs guile emacs-geiser emacs-geiser-guile
+guix install emacs guile emacs-geiser emacs-geiser-guile
 @end example
 
 Geiser allows for interactive and incremental development from within
diff --git a/doc/guix.texi b/doc/guix.texi
index a7ac74b416..3c5864ec1a 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -299,6 +299,7 @@ Programming Interface
 * The Store Monad::             Purely functional interface to the store.
 * G-Expressions::               Manipulating build expressions.
 * Invoking guix repl::          Programming Guix in Guile.
+* Using Guix Interactively::    Fine-grain interaction at the REPL.
 
 Defining Packages
 
@@ -7100,6 +7101,7 @@ package definitions.
 * The Store Monad::             Purely functional interface to the store.
 * G-Expressions::               Manipulating build expressions.
 * Invoking guix repl::          Programming Guix in Guile
+* Using Guix Interactively::    Fine-grain interaction at the REPL.
 @end menu
 
 @node Package Modules
@@ -10860,8 +10862,9 @@ So, to exit the monad and get the desired effect, one must use
 @end lisp
 
 Note that the @code{(guix monad-repl)} module extends the Guile REPL with
-new ``meta-commands'' to make it easier to deal with monadic procedures:
-@code{run-in-store}, and @code{enter-store-monad}.  The former is used
+new ``commands'' to make it easier to deal with monadic procedures:
+@code{run-in-store}, and @code{enter-store-monad} (@pxref{Using Guix
+Interactively}).  The former is used
 to ``run'' a single monadic value through the store:
 
 @example
@@ -10886,6 +10889,9 @@ scheme@@(guile-user)>
 Note that non-monadic values cannot be returned in the
 @code{store-monad} REPL.
 
+Other meta-commands are available at the REPL, such as @code{,build} to
+build a file-like object (@pxref{Using Guix Interactively}).
+
 The main syntactic forms to deal with monads in general are provided by
 the @code{(guix monads)} module and are described below.
 
@@ -11778,7 +11784,8 @@ lines at the top of the script:
 @code{!#}
 @end example
 
-Without a file name argument, a Guile REPL is started:
+Without a file name argument, a Guile REPL is started, allowing for
+interactive use (@pxref{Using Guix Interactively}):
 
 @example
 $ guix repl
@@ -11834,6 +11841,132 @@ Inhibit loading of the @file{~/.guile} file.  By default, that
 configuration file is loaded when spawning a @code{guile} REPL.
 @end table
 
+@node Using Guix Interactively
+@section Using Guix Interactively
+
+@cindex interactive use
+@cindex REPL, read-eval-print loop
+The @command{guix repl} command gives you access to a warm and friendly
+@dfn{read-eval-print loop} (REPL) (@pxref{Invoking guix repl}).  If
+you're getting into Guix programming---defining your own packages,
+writing manifests, defining services for Guix System or Guix Home,
+etc.---you will surely find it convenient to toy with ideas at the REPL.
+
+If you use Emacs, the most convenient way to do that is with Geiser
+(@pxref{The Perfect Setup}), but you do not have to use Emacs to enjoy
+the REPL@.  When using @command{guix repl} or @command{guile} in the
+terminal, we recommend using Readline for completion and Colorized to
+get colorful output.  To do that, you can run:
+
+@example
+guix install guile guile-readline guile-colorized
+@end example
+
+@noindent
+... and then create a @file{.guile} file in your home directory containing
+this:
+
+@lisp
+(use-modules (ice-9 readline) (ice-9 colorized))
+
+(activate-readline)
+(activate-colorized)
+@end lisp
+
+The REPL lets you evaluate Scheme code; you type a Scheme expression at
+the prompt, and the REPL prints what it evaluates to:
+
+@example
+$ guix repl
+scheme@@(guix-user)> (+ 2 3)
+$1 = 5
+scheme@@(guix-user)> (string-append "a" "b")
+$2 = "ab"
+@end example
+
+It becomes interesting when you start fiddling with Guix at the REPL.
+The first thing you'll want to do is to ``import'' the @code{(guix)}
+module, which gives access to the main part of the programming
+interface, and perhaps a bunch of useful Guix modules.  You could type
+@code{(use-modules (guix))}, which is valid Scheme code to import a
+module (@pxref{Using Guile Modules,,, guile, GNU Guile Reference
+Manual}), but the REPL provides the @code{use} @dfn{command} as a
+shorthand notation (@pxref{REPL Commands,,, guile, GNU Guile Reference
+Manual}):
+
+@example
+scheme@@(guix-user)> ,use (guix)
+scheme@@(guix-user)> ,use (gnu packages base)
+@end example
+
+Notice that REPL commands are introduced by a leading comma.  A REPL
+command like @code{use} is not valid Scheme code; it's interpreted
+specially by the REPL.
+
+Guix extends the Guile REPL with additional commands for convenience.
+Among those, the @code{build} command comes in handy: it ensures that
+the given file-like object is built, building it if needed, and returns
+its output file name(s).  In the example below, we build the
+@code{coreutils} and @code{grep} packages, as well as a ``computed
+file'' (@pxref{G-Expressions, @code{computed-file}}), and we use the
+@code{scandir} procedure to list the files in Grep's @code{/bin}
+directory:
+
+@example
+scheme@@(guix-user)> ,build coreutils
+$1 = "/gnu/store/@dots{}-coreutils-8.32-debug"
+$2 = "/gnu/store/@dots{}-coreutils-8.32"
+scheme@@(guix-user)> ,build grep
+$3 = "/gnu/store/@dots{}-grep-3.6"
+scheme@@(guix-user)> ,build (computed-file "x" #~(mkdir #$output))
+building /gnu/store/@dots{}-x.drv...
+$4 = "/gnu/store/@dots{}-x"
+scheme@@(guix-user)> ,use(ice-9 ftw)
+scheme@@(guix-user)> (scandir (string-append $3 "/bin"))
+$5 = ("." ".." "egrep" "fgrep" "grep")
+@end example
+
+At a lower-level, a useful command is @code{lower}: it takes a file-like
+object and ``lowers'' it into a derivation (@pxref{Derivations}) or a
+store file:
+
+@example
+scheme@@(guix-user)> ,lower grep
+$6 = #<derivation /gnu/store/@dots{}-grep-3.6.drv => /gnu/store/@dots{}-grep-3.6 7f0e639115f0>
+scheme@@(guix-user)> ,lower (plain-file "x" "Hello!")
+$7 = "/gnu/store/@dots{}-x"
+@end example
+
+The full list of REPL commands can be seen by typing @code{,help guix}
+and is given below for reference.
+
+@deffn {REPL command} build @var{object}
+Lower @var{object} and build it if it's not already built, returning its
+output file name(s).
+@end deffn
+
+@deffn {REPL command} lower @var{object}
+Lower @var{object} into a derivation or store file name and return it.
+@end deffn
+
+@deffn {REPL command} verbosity @var{level}
+Change build verbosity to @var{level}.
+
+This is similar to the @option{--verbosity} command-line option
+(@pxref{Common Build Options}): level 0 means total silence, level 1
+shows build events only, and higher levels print build logs.
+@end deffn
+
+@deffn {REPL command} run-in-store @var{exp}
+Run @var{exp}, a monadic expresssion, through the store monad.
+@xref{The Store Monad}, for more information.
+@end deffn
+
+@deffn {REPL command} enter-store-monad
+Enter a new REPL to evaluate monadic expressions (@pxref{The Store
+Monad}).  You can quit this ``inner'' REPL by typing @code{,q}.
+@end deffn
+
 @c *********************************************************************
 @node Utilities
 @chapter Utilities
@@ -37648,6 +37781,13 @@ bootloader boot menu:
 Describe the running system generation: its file name, the kernel and
 bootloader used, etc., as well as provenance information when available.
 
+The @code{--list-installed} flag is available, with the same
+syntax that is used in @command{guix package --list-installed}
+(@pxref{Invoking guix package}).  When the flag is used,
+the description will include a list of packages that are currently
+installed in the system profile, with optional filtering based on a
+regular expression.
+
 @quotation Note
 The @emph{running} system generation---referred to by
 @file{/run/current-system}---is not necessarily the @emph{current}
@@ -37675,6 +37815,11 @@ generations that are up to 10 days old:
 $ guix system list-generations 10d
 @end example
 
+The @code{--list-installed} flag may also be specified, with the same
+syntax that is used in @command{guix package --list-installed}.  This
+may be helpful if trying to determine when a package was added to the
+system.
+
 @end table
 
 The @command{guix system} command has even more to offer!  The following
@@ -39663,6 +39808,23 @@ contents of the extensions will be added to the end of the corresponding
 Bash configuration files (@pxref{Bash Startup Files,,, bash, The GNU
 Bash Reference Manual}.
 
+For example, here is how you would define a service that extends the
+Bash service such that @file{~/.bash_profile} defines an additional
+environment variable, @env{PS1}:
+
+@lisp
+(define bash-fancy-prompt-service
+  (simple-service 'bash-fancy-prompt
+                  home-bash-service-type
+                  (home-bash-extension
+                   (environment-variables
+                    '(("PS1" . "\\u \\wλ "))))))
+@end lisp
+
+You would then add @code{bash-fancy-prompt-service} to the list in the
+@code{services} field of your @code{home-environment}.  The reference of
+@code{home-bash-extension} follows.
+
 @deftp {Data Type} home-bash-extension
 Available @code{home-bash-extension} fields are:
 
@@ -40345,6 +40507,17 @@ install anything.
 Describe the current home generation: its file name, as well as
 provenance information when available.
 
+To show installed packages in the current home generation's profile, the
+@code{--list-installed} flag is provided, with the same syntax that is
+used in @command{guix package --list-installed} (@pxref{Invoking guix
+package}).  For instance, the following command shows a table of all the
+packages with ``emacs'' in their name that are installed in the current
+home generation's profile:
+
+@example
+guix home describe --list-installed=emacs
+@end example
+
 @item list-generations
 List a summary of each generation of the home environment available on
 disk, in a human-readable way.  This is similar to the
@@ -40357,9 +40530,14 @@ generations displayed.  For instance, the following command displays
 generations that are up to 10 days old:
 
 @example
-$ guix home list-generations 10d
+guix home list-generations 10d
 @end example
 
+The @code{--list-installed} flag may also be specified, with the same
+syntax that is used in @command{guix home describe}.  This may be
+helpful if trying to determine when a package was added to the home
+profile.
+
 @item import
 Generate a @dfn{home environment} from the packages in the default
 profile and configuration files found in the user's home directory.  The
@@ -40787,6 +40965,16 @@ package, you can try and import it (@pxref{Invoking guix import}):
 guix import texlive @var{package}
 @end example
 
+Additional options include:
+
+@table @code
+@item --recursive
+@itemx -r
+Traverse the dependency graph of the given upstream package recursively
+and generate package expressions for all those packages that are not yet
+in Guix.
+@end table
+
 @quotation Note
 @TeX{} Live packaging is still very much work in progress, but you can
 help!  @xref{Contributing}, for more information.