From adc8527ff2a32f71e7b93938aa22ec5fde38114a Mon Sep 17 00:00:00 2001
From: Karen Arutyunov <karen@codesynthesis.com>
Date: Wed, 23 Oct 2019 22:55:57 +0300
Subject: Add support for tests, examples, and benchmarks package manifest
 values

---
 doc/manual.cli | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 65 insertions(+), 9 deletions(-)

(limited to 'doc/manual.cli')

diff --git a/doc/manual.cli b/doc/manual.cli
index d2457da..41973f7 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -784,6 +784,24 @@ bpkg -v update <package-name>
 #
 bpkg -v test <package-name>
 
+# for each package referred to by the tests, examples, or benchmarks
+# package manifest values:
+#
+{
+  # bpkg.configure.build
+  #
+  bpkg -v build --yes --configure-only \\
+       '<package-name> [<version-constraint>]'
+
+  # bpkg.update.update
+  #
+  bpkg -v update <package-name>
+
+  # bpkg.test.test
+  #
+  bpkg -v test <package-name>
+}
+
 # if config.install.root is specified:
 #
 {
@@ -807,11 +825,46 @@ bpkg -v test <package-name>
     #
     b -v test
   }
-}
 
-# bpkg.uninstall.uninstall
-#
-bpkg -v uninstall <package-name>
+  # if any of the tests, examples, or benchmarks package manifest
+  # values are specified:
+  #
+  {
+    # bpkg.test-installed.create
+    #
+    bpkg -V create <config-args> <env-modules> <env-config-args>
+
+    # bpkg.configure.add
+    #
+    bpkg -v add <repository-url>
+
+    # bpkg.configure.fetch
+    #
+    bpkg -v fetch --trust <repository-fp>
+
+    # for each package referred to by the tests, examples, or benchmarks
+    # package manifest values:
+    #
+    {
+      # bpkg.configure.build
+      #
+      bpkg -v build --yes --configure-only \\
+           '<package-name> [<version-constraint>]'
+
+      # bpkg.update.update
+      #
+      bpkg -v update <package-name>
+
+      # bpkg.test.test
+      #
+      bpkg -v test <package-name>
+    }
+  }
+
+  # bpkg.uninstall.uninstall
+  #
+  bpkg -v uninstall <package-name>
+}
 \
 
 For details on configuring and testing installation refer to
@@ -891,9 +944,10 @@ expressions are included into the build task manifest.
 Values in the \c{<config-arg>} list can be opionally prefixed with the \i{step
 id} or a leading portion thereof to restrict it to a specific step, operation,
 or tool in the \i{worked script} (see \l{#arch-worker Worker
-Logic}). Unprefixed values only apply to the \c{bpkg.configure.create} and
-\c{b.test-installed.create} steps. Note that options with values can only be
-specified using the single argument notation. For example:
+Logic}). Unprefixed values only apply to the \c{bpkg.configure.create},
+\c{b.test-installed.create}, and \c{bpkg.test-installed.create} steps. Note
+that options with values can only be specified using the single argument
+notation. For example:
 
 \
 bpkg:--fetch-timeout=600 bpkg.configure.fetch:--fetch-timeout=60 b:-j1
@@ -962,8 +1016,10 @@ If the \c{<config-arg>} list contains the \c{config.install.root} variable
 that applies to the \c{bpkg.configure.create} step, then in addition to
 building and possibly running tests, the \c{bbot} worker will also test
 installing and uninstalling each package. Furthermore, if the package contains
-subprojects that support the test operation, then the worker will additionally
-build such subprojects against the installation and run their tests.
+subprojects that support the test operation and/or refers to other packages
+via the \c{tests}, \c{examples}, or c\{benchmarks} manifest values, then the
+worker will additionally build such subprojects/packages against the
+installation and run their tests.
 
 Two types of installations can be tested: \i{system} and \i{private}. A system
 installation uses a well-known location, such as \c{/usr} or \c{/usr/local},
-- 
cgit v1.1