monad-repl: Add REPL commands to inspect package arguments.

* guix/monad-repl.scm (keyword-argument-value, package-argument-command):
New procedures.
(phases, configure-flags, make-flags): New REPL commands.
* doc/guix.texi (package Reference): Link to “Using Guix Interactively”.
(Defining Package Variants): Add “Tips” quotation.
(Build Phases): Add “Tip” quotation.
(Using Guix Interactively): Document the new REPL commands.

Change-Id: I7049c1d8aa9241e07d7c921aa396e578a1b4ef16

1 files changed, 61 insertions, 0 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index 1fd2e21608..7dde9b727b 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -7975,6 +7975,10 @@ The exact set of supported keywords depends on the build system
 @code{#:phases}.  The @code{#:phases} keyword in particular lets you
 modify the set of build phases for your package (@pxref{Build Phases}).
 
+The REPL has dedicated commands to interactively inspect values of some
+of these arguments, as a convenient debugging aid (@pxref{Using Guix
+Interactively}).
+
 @quotation Compatibility Note
 Until version 1.3.0, the @code{arguments} field would typically use
 @code{quote} (@code{'}) or @code{quasiquote} (@code{`}) and no
@@ -8774,6 +8778,23 @@ when @var{cut?} returns true for a given package.  When @var{deep?} is true, @va
 applied to implicit inputs as well.
 @end deffn
 
+@quotation Tips
+Understanding what a variant really looks like can be difficult as one
+starts combining the tools shown above.  There are several ways to
+inspect a package before attempting to build it that can prove handy:
+
+@itemize
+@item
+You can inspect the package interactively at the REPL, for instance to
+view its inputs, the code of its build phases, or its configure flags
+(@pxref{Using Guix Interactively}).
+
+@item
+When rewriting dependencies, @command{guix graph} can often help
+visualize the changes that are made (@pxref{Invoking guix graph}).
+@end itemize
+@end quotation
+
 @node Writing Manifests
 @section Writing Manifests
 
@@ -10585,6 +10606,11 @@ we have seen before.  @xref{Build Utilities}, for more about
 the helpers used by this phase, and for more examples of
 @code{modify-phases}.
 
+@quotation Tip
+You can inspect the code associated with a package's @code{#:phases}
+argument interactively, at the REPL (@pxref{Using Guix Interactively}).
+@end quotation
+
 @cindex code staging
 @cindex staging, of code
 Keep in mind that build phases are code evaluated at the time the
@@ -12763,6 +12789,30 @@ scheme@@(guix-user)> (scandir (string-append $3 "/bin"))
 $5 = ("." ".." "egrep" "fgrep" "grep")
 @end example
 
+As a packager, you may be willing to inspect the build phases or flags
+of a given package; this is particularly useful when relying a lot on
+inheritance to define package variants (@pxref{Defining Package
+Variants}) or when package arguments are a result of some computation,
+both of which can make it harder to foresee what ends up in the package
+arguments.  Additional commands let you inspect those package arguments:
+
+@example
+scheme@@(guix-user)> ,phases grep
+$1 = (modify-phases %standard-phases
+       (add-after 'install 'fix-egrep-and-fgrep
+         (lambda* (#:key outputs #:allow-other-keys)
+           (let* ((out (assoc-ref outputs "out"))
+                  (bin (string-append out "/bin")))
+             (substitute* (list (string-append bin "/egrep")
+                                (string-append bin "/fgrep"))
+               (("^exec grep")
+                (string-append "exec " bin "/grep")))))))
+scheme@@(guix-user)> ,configure-flags findutils
+$2 = (list "--localstatedir=/var")
+scheme@@(guix-user)> ,make-flags binutils
+$3 = '("MAKEINFO=true")
+@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:
@@ -12794,6 +12844,17 @@ This is similar to the @option{--verbosity} command-line option
 shows build events only, and higher levels print build logs.
 @end deffn
 
+@deffn {REPL command} phases @var{package}
+@deffnx {REPL command} configure-flags @var{package}
+@deffnx {REPL command} make-flags @var{package}
+These REPL commands return the value of one element of the
+@code{arguments} field of @var{package} (@pxref{package Reference}): the
+first one show the staged code associated with @code{#:phases}
+(@pxref{Build Phases}), the second shows the code for
+@code{#:configure-flags}, and @code{,make-flags} returns the code for
+@code{#:make-flags}.
+@end deffn
+
 @deffn {REPL command} run-in-store @var{exp}
 Run @var{exp}, a monadic expression, through the store monad.
 @xref{The Store Monad}, for more information.