guix build: Add ‘--dependents’.

* guix/scripts/build.scm (show-help, %options): Add ‘--dependents’.
(dependents): New procedure.
(options->things-to-build): Add ‘store’ parameter; honor ‘dependents’
option.
[for-type]: Handle ‘dependents’ type.
(options->derivations): Update call to ‘options->things-to-build’.
* tests/guix-build.sh: Add test.
* doc/guix.texi (Additional Build Options): Document ‘--dependents’.
(Invoking guix refresh): Cross-reference it.
* doc/contributing.texi (Submitting Patches): Mention it.

Change-Id: I00b6d5831e1f1d35dc8b84a82605391d5a8f417c

2 files changed, 30 insertions, 1 deletions

diff --git a/doc/contributing.texi b/doc/contributing.texi
index e7465fc259..6be879fa66 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1915,7 +1915,9 @@ according to the project's conventions (@pxref{Invoking guix style}).
 
 @item
 Make sure the package builds on your platform, using @command{guix build
-@var{package}}.
+@var{package}}.  Also build at least its direct dependents with
+@command{guix build --dependents=1 @var{package}}
+(@pxref{build-dependents, @command{guix build}}).
 
 @item
 We recommend you also try building the package on other supported
diff --git a/doc/guix.texi b/doc/guix.texi
index f8eefa365b..ba9b75f370 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -13639,6 +13639,31 @@ cross-compile all the dependencies of the given package when it is built
 natively.
 @end quotation
 
+@cindex dependents of a package, building them
+@cindex building the dependents of a package
+@anchor{build-dependents}
+@item --dependents[=@var{depth}]
+@itemx -P [@var{depth}]
+Build the dependents of the following package.  By default, build all
+the direct and indirect dependents; when @var{depth} is provided, limit
+to dependents at that distance: 1 for direct dependents, 2 for
+dependents of dependents, and so on.
+
+For example, the command below builds @emph{all} the dependents of libgit2:
+
+@example
+guix build --dependents libgit2
+@end example
+
+To build all the packages that directly depend on NumPy, run:
+
+@example
+guix build -P1 python-numpy
+@end example
+
+The list of dependents is computed in the same way as with @command{guix
+refresh --list-dependent} (@pxref{Invoking guix refresh}).
+
 @item --source
 @itemx -S
 Build the source derivations of the packages, rather than the packages
@@ -15142,6 +15167,8 @@ result of upgrading one or more packages.
 @command{guix graph}}, for information on how to visualize the list of
 dependents of a package.
 
+@xref{build-dependents, @command{guix build --dependents}}, for a
+convenient way to build all the dependents of a package.
 @end table
 
 Be aware that the @option{--list-dependent} option only