Make build graph configuration-independent

9 files changed, 245 insertions, 139 deletions

diff --git a/cli/build/root.build b/cli/build/root.build
index 0753a9e..ceeaf6c 100644
--- a/cli/build/root.build
+++ b/cli/build/root.build
@@ -4,10 +4,12 @@
 # Note that we cannot install the development build. This is due to both the
 # bootstrap cli (which we need to run) and the final cli (which we need to
 # install) depending on libcutl (so we need it to be both "for-install" and
-# "for-run"). Nor can we run the final cli to generate the man pages.
+# "for-run"). Nor can we run such final cli to generate the man pages.
 #
 config [bool] config.cli.develop ?= false
 
+develop = $config.cli.develop
+
 define cli: file
 cli{*}: extension = cli
 
diff --git a/cli/cli/.gitignore b/cli/cli/.gitignore
index 79562f1..614e56f 100644
--- a/cli/cli/.gitignore
+++ b/cli/cli/.gitignore
@@ -1,5 +1,5 @@
 /cli
-/bootstrap/cli/cli
+/pregenerated/cli/cli
 /version.hxx
 /options.?xx
 
diff --git a/cli/cli/buildfile b/cli/cli/buildfile
index dc5d75b..4e51ea5 100644
--- a/cli/cli/buildfile
+++ b/cli/cli/buildfile
@@ -25,91 +25,118 @@ libue{cli}: $hdr $src $all_s $all_t {hxx}{version} $libs
 
 hxx{version}: in{version} $src_root/manifest
 
-# Build options (both bootstrap and final version).
+# Build options (apply to both bootstrap and final version).
 #
 cxx.poptions =+ "-I$out_root" "-I$src_root"
 
+# CLI uses its own generated code to handle the command line. To solve the
+# chicken and egg problem that this poses we keep pregenerated source code in
+# pregenerated/.
+#
+# In the consumption build ($config.cli.develop == false), we just use this
+# pregenerated source code to build the final version of the compiler. In the
+# development build ($config.cli.develop == true) we use this pregenerated
+# source code to build a bootstrap version of the compiler which we then use
+# to regenerate the source code and build that final version from that.
+
+## Consumption build ($develop == false).
+#
+
+# Use pregenerated versions to build the final version of cli.
+#
+libue{cli}: pregenerated/{hxx ixx cxx}{**}: include = (!$develop)
+
+if! $develop
+  cxx.poptions =+ "-I($src_base/pregenerated)" # Note: must come first.
+
+# Distribute pregenerated versions only in the consumption build.
+#
+pregenerated/{hxx ixx cxx}{*}: dist = (!$develop)
+
+#
+##
+
+## Development build ($develop == true).
+#
+libue{cli}: {hxx ixx cxx}{options}: include = $develop
+
 # Bootstrap.
 #
 # The plan is as follows:
 #
 # 1. Build the bootstrap version of cli using a copy of options.?xx saved in
-#    bootstrap/cli/.
+#    pregenerated/cli/.
 #
-# 2. Use that to re-generate options.?xx. If the result differs from the
-#    saved version, copy it over and fail the build, asking for a restart.
+# 2. Use that to regenerate options.?xx. If the result differs from the saved
+#    version, copy it over and fail the build, asking for a restart.
 #
-# 3. Otherwise, proceed to build the final version of cli.
+# 3. Otherwise, proceed to build the final version of cli using regenerated
+#    options.?xx.
 #
-if $config.cli.develop
+pregenerated/
 {
-  libue{cli}: {hxx ixx cxx}{options}
+  # This should only apply to the bootstrap build.
+  #
+  cxx.poptions =+ "-I$src_base" # Note: must come first.
 
-  bootstrap/
+  cli/
   {
-    # This should only apply to the bootstrap build.
+    # Note: semantics/ and traversal/ do not include options.hxx so we can
+    #       share their object files.
     #
-    cxx.poptions =+ "-I$src_base" # Note: must come first.
-
-    cli/
-    {
-      # Note: semantics/ and traversal/ do not include options.hxx so we can
-      #       share their object files.
-      #
-      exe{cli}: obj{cli $name($src) options} ../../{$all_s $all_t} $libs
+    exe{cli}: obj{cli $name($src) options} ../../{$all_s $all_t} $libs
 
-      for s: cli $name($src)
-        obj{$s}: ../../cxx{$s} $libs
+    for s: cli $name($src)
+      obj{$s}: ../../cxx{$s} $libs
 
-      obj{options}: {hxx ixx cxx}{options}
+    obj{options}: {hxx ixx cxx}{options}
 
-      obj{cli}: cxx.poptions += -DCLI_BOOTSTRAP
-    }
+    obj{cli}: cxx.poptions += -DCLI_BOOTSTRAP
   }
+}
 
-  <{hxx ixx cxx}{options}>: cli{options} bootstrap/cli/exe{cli}
-  {
-    options = --include-with-brackets --include-prefix cli   \
-              --guard-prefix CLI --generate-file-scanner     \
-              --generate-specifier --generate-modifier       \
-              --suppress-undocumented --reserved-name stdout
+# In the development build distribute regenerated {hxx ixx cxx}{options},
+# remapping their locations to the paths of the pregenerated versions (which
+# are only distributed in the consumption build; see above). This way we make
+# sure that the distributed files are always up-to-date.
+#
+<{hxx ixx cxx}{options}>: cli{options} pregenerated/cli/exe{cli}
+{
+  options = --include-with-brackets --include-prefix cli   \
+            --guard-prefix CLI --generate-file-scanner     \
+            --generate-specifier --generate-modifier       \
+            --suppress-undocumented --reserved-name stdout
 
-    # Symlink the generated code in src for convenience of development.
-    #
-    backlink = true
-  }
-  {{
-    diag cli ($<[0])
-    ($<[1]) $options -o $out_base $path($<[0])
+  dist = ($develop ? pregenerated/cli/ : false)
 
-    # If the result differs from the bootstrap version, copy it over and
-    # request the build restart.
-    #
-    if diff $src_base/bootstrap/cli/options.hxx $path($>[0]) >- && \
-       diff $src_base/bootstrap/cli/options.ixx $path($>[1]) >- && \
-       diff $src_base/bootstrap/cli/options.cxx $path($>[2]) >-
-      exit
-    end
-
-    cp $path($>[0]) $src_base/bootstrap/cli/options.hxx
-    cp $path($>[1]) $src_base/bootstrap/cli/options.ixx
-    cp $path($>[2]) $src_base/bootstrap/cli/options.cxx
-
-    exit "bootstrap options.?xx have changed, restart the build"
-  }}
+  # Symlink the generated code in src for convenience of development.
+  #
+  backlink = true
 }
-else
-{
-  # Use bootstrap options.?xx to build the final version of cli.
+%
+if $develop
+{{
+  diag cli ($<[0])
+  ($<[1]) $options -o $out_base $path($<[0])
+
+  # If the result differs from the bootstrap version, copy it over and
+  # request the build restart.
   #
-  libue{cli}: bootstrap/cli/{hxx ixx cxx}{options}
-  cxx.poptions =+ "-I($src_base/bootstrap)" # Note: must come first.
+  if diff $src_base/pregenerated/cli/options.hxx $path($>[0]) >- && \
+     diff $src_base/pregenerated/cli/options.ixx $path($>[1]) >- && \
+     diff $src_base/pregenerated/cli/options.cxx $path($>[2]) >-
+    exit
+  end
 
-  ./: cli{options} # Keep in distribution.
-}
+  cp $path($>[0]) $src_base/pregenerated/cli/options.hxx
+  cp $path($>[1]) $src_base/pregenerated/cli/options.ixx
+  cp $path($>[2]) $src_base/pregenerated/cli/options.cxx
+
+  exit "bootstrap options.?xx have changed, restart the build"
+}}
 
-# Build options (final version only).
 #
+##
 
 # Pass the copyright notice extracted from the LICENSE file.
 #
diff --git a/cli/cli/bootstrap/cli/options.cxx b/cli/cli/pregenerated/cli/options.cxx
index 2cb2f75..2cb2f75 100644
--- a/cli/cli/bootstrap/cli/options.cxx
+++ b/cli/cli/pregenerated/cli/options.cxx
diff --git a/cli/cli/bootstrap/cli/options.hxx b/cli/cli/pregenerated/cli/options.hxx
index 08180f3..08180f3 100644
--- a/cli/cli/bootstrap/cli/options.hxx
+++ b/cli/cli/pregenerated/cli/options.hxx
diff --git a/cli/cli/bootstrap/cli/options.ixx b/cli/cli/pregenerated/cli/options.ixx
index e3fd397..e3fd397 100644
--- a/cli/cli/bootstrap/cli/options.ixx
+++ b/cli/cli/pregenerated/cli/options.ixx
diff --git a/cli/doc/buildfile b/cli/doc/buildfile
index 09202ad..61dfd4f 100644
--- a/cli/doc/buildfile
+++ b/cli/doc/buildfile
@@ -16,15 +16,37 @@ pdf{*}: extension = pdf
 define html2ps: file
 html2ps{*}: extension = html2ps
 
-./: css{default} xhtml{cli-guide} bootstrap/{man1 xhtml}{cli}
+./: css{default} xhtml{cli-guide}
 
-if $config.cli.develop
+# Man pages.
+#
+
+## Consumption build ($develop == false).
+#
+
+# Use pregenerated versions in the consumption build.
+#
+./: pregenerated/{man1 xhtml}{*}: include = (!$develop)
+
+# Distribute pregenerated versions only in the consumption build.
+#
+pregenerated/{man1 xhtml}{*}: dist = (!$develop)
+
+#
+##
+
+## Development build ($develop == true).
+#
+
+./: {man1 xhtml}{cli}: include = $develop
+
+if $develop
 {
   doc_version = [string] "$version.major\.$version.minor\.$version.patch"
   if $version.pre_release
     doc_version += "-$version.pre_release_string"
 
-  # Let's take the last for-digit number to cover 2000-2021,2022.
+  # Let's take the last four-digit number to cover 2000-2021,2022.
   #
   doc_year = $regex.replace($copyright, '.+[-, ]([0-9][0-9][0-9][0-9]) .+', '\1')
 
@@ -33,87 +55,142 @@ if $config.cli.develop
 
   # We use the cli version we've built to generate the documentation.
   #
-  # Note: avoid cleaning it through this dependency.
-  #
   include ../cli/
+}
+
+# Note: avoid cleaning exe{cli} through this dependency.
+#
+{man1 xhtml}{cli}: ../cli/exe{cli}: clean = false
 
-  {xhtml man1}{cli}: ../cli/exe{cli}: clean = false
-
-  ./: man1{cli}: ../cli/cli{options} file{cli-prologue.1 cli-epilogue.1}
-  {{
-    diag cli --man ($<[1])
-
-    # Use the copyright year to approximate the last authoring date.
-    #
-    ($<[0]) --generate-man  $man_options     \
-            -v date="January $doc_year"      \
-            --man-prologue-file $path($<[2]) \
-            --man-epilogue-file $path($<[3]) \
-            --stdout $path($<[1]) >$path($>)
-
-    # If the result differs from the bootstrap version, copy it over. Unlike
-    # the bootstrap cli case, here we don't need to cause a build restart.
-    #
-    if! diff $src_base/bootstrap/cli.1 $path($>) >-
-      cp $path($>) $src_base/bootstrap/cli.1
-    end
-  }}
-
-  ./: xhtml{cli}: $src_root/cli/cli{options} \
-                  file{cli-prologue.xhtml cli-epilogue.xhtml}
-  {{
-    diag cli --html ($<[1])
-
-    ($<[0]) --generate-html $man_options      \
-            --html-prologue-file $path($<[2]) \
-            --html-epilogue-file $path($<[3]) \
-            --stdout $path($<[1]) >$path($>)
-
-    if! diff $src_base/bootstrap/cli.xhtml $path($>) >-
-      cp $path($>) $src_base/bootstrap/cli.xhtml
-    end
-  }}
+# In the development build distribute regenerated versions, remapping their
+# locations to the paths of the pregenerated versions (which are only
+# distributed in the consumption build; see above). This way we make sure that
+# the distributed files are always up-to-date.
+#
+{man1 xhtml}{cli}: dist = ($develop ? pregenerated/ : false)
 
+man1{cli}: ../cli/cli{options} file{cli-prologue.1 cli-epilogue.1}
+%
+if $develop
+{{
+  diag cli --man ($<[1])
+
+  # Use the copyright year to approximate the last authoring date.
+  #
+  ($<[0]) --generate-man  $man_options     \
+          -v date="January $doc_year"      \
+          --man-prologue-file $path($<[2]) \
+          --man-epilogue-file $path($<[3]) \
+          --stdout $path($<[1]) >$path($>)
+
+  # If the result differs from the pregenerated version, copy it over. Unlike
+  # the bootstrap compiler case, here we don't need to cause a build restart
+  # (since nothing depends on it).
+  #
+  if! diff $src_base/pregenerated/cli.1 $path($>) >-
+    cp $path($>) $src_base/pregenerated/cli.1
+  end
+}}
+
+xhtml{cli}: ../cli/cli{options} file{cli-prologue.xhtml cli-epilogue.xhtml}
+%
+if $develop
+{{
+  diag cli --html ($<[1])
+
+  ($<[0]) --generate-html $man_options      \
+          --html-prologue-file $path($<[2]) \
+          --html-epilogue-file $path($<[3]) \
+          --stdout $path($<[1]) >$path($>)
+
+  if! diff $src_base/pregenerated/cli.xhtml $path($>) >-
+    cp $path($>) $src_base/pregenerated/cli.xhtml
+  end
+}}
+
+#
+##
+
+# Manual.
+#
+# This case is slightly more involved because we make the generation of the
+# manual's ps/pdf optional and also don't keep the result in the repository.
+# Specifically:
+#
+# 1. In the consumption build we will install/redistribute ps/pdf if present.
+#
+# 2. In the development build we will generate ps/pdf if we are able to import
+#    the needed tools, issuing a warning otherwise.
+
+## Consumption build ($develop == false).
+#
+
+# Use pregenerated versions, if exist, in the consumption build.
+#
+./: pregenerated/{ps pdf}{*}: include = (!$develop)
+
+# Distribute pregenerated versions only in the consumption build.
+#
+pregenerated/{ps pdf}{*}: dist = (!$develop)
+
+#
+##
+
+## Development build ($develop == true).
+#
+
+html2pdf = false
+
+if $develop
+{
   # Import the html2ps and ps2pdf programs from the system, if available.
   #
   import? html2ps = html2ps%exe{html2ps}
   import? ps2pdf  = ps2pdf14%exe{ps2pdf14}
 
-  if ($html2ps != [null] && $ps2pdf != [null])
-  {
-    # Note that we include these generated files into the distribution and
-    # don't remove them when cleaning in src (so that clean results in a state
-    # identical to distributed).
-    #
-    ./: ps{cli-guide}: xhtml{cli-guide} html2ps{guide} $html2ps
-    {
-      options =
-
-      dist  = true
-      clean = ($src_root != $out_root)
-    }
-    {{
-      diag html2ps ($<[0])
-      $html2ps $options -f $path($<[1]) -o $path($>) $path($<[0])
-    }}
-
-    ./: pdf{cli-guide}: ps{cli-guide} $ps2pdf
-    {
-      options = -dOptimize=true -dEmbedAllFonts=true
-
-      dist  = true
-      clean = ($src_root != $out_root)
-    }
-    {{
-      diag ps2pdf ($<[0])
-      $ps2pdf $options $path($<[0]) $path($>)
-    }}
-  }
-  else
-  {
+  html2pdf = ($html2ps != [null] && $ps2pdf != [null])
+
+  if! $html2pdf
     warn "html2ps and/or ps2pdf14 are not available, not generating .ps and .pdf documentation"
-    ./: html2ps{guide} # Note: not keeping ps/pdf (could be outdated).
-  }
 }
-else
-  ./: file{cli-prologue* cli-epilogue*} html2ps{guide} {ps pdf}{+cli-guide}
+
+./: {ps pdf}{cli-guide}: include = $html2pdf
+
+# In the development build distribute regenerated versions, remapping their
+# locations to the paths of the pregenerated versions (which are only
+# distributed in the consumption build; see above). This way we make sure that
+# the distributed files are always up-to-date.
+#
+{ps pdf}{cli-guide}: dist = ($html2pdf ? pregenerated/ : false)
+
+# Note: the pregenerated file may not exist, thus --no-cleanup option is
+# required for the cp builtin call.
+#
+ps{cli-guide}: xhtml{cli-guide} html2ps{guide} $html2ps
+{
+  options =
+}
+%
+if $html2pdf
+{{
+  diag html2ps ($<[0])
+  $html2ps $options -f $path($<[1]) -o $path($>) $path($<[0])
+
+  cp --no-cleanup $path($>) $src_base/pregenerated/cli-guide.ps
+}}
+
+pdf{cli-guide}: ps{cli-guide} $ps2pdf
+{
+  options = -dOptimize=true -dEmbedAllFonts=true
+}
+%
+if $html2pdf
+{{
+  diag ps2pdf ($<[0])
+  $ps2pdf $options $path($<[0]) $path($>)
+
+  cp --no-cleanup $path($>) $src_base/pregenerated/cli-guide.pdf
+}}
+
+#
+##
diff --git a/cli/doc/bootstrap/cli.1 b/cli/doc/pregenerated/cli.1
index 2c9645e..8cf5cd1 100644
--- a/cli/doc/bootstrap/cli.1
+++ b/cli/doc/pregenerated/cli.1
@@ -1,7 +1,7 @@
 .\" Process this file with
 .\" groff -man -Tascii cli.1
 .\"
-.TH CLI 1 "January 2022" "CLI 1.2.0-b.8"
+.TH CLI 1 "January 2022" "CLI 1.2.0-b.9"
 .SH NAME
 cli \- command line interface compiler for C++
 .\"
diff --git a/cli/doc/bootstrap/cli.xhtml b/cli/doc/pregenerated/cli.xhtml
index 96dc913..909fa34 100644
--- a/cli/doc/bootstrap/cli.xhtml
+++ b/cli/doc/pregenerated/cli.xhtml
@@ -2,7 +2,7 @@
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
 
 <head>
-  <title>CLI 1.2.0-b.8 Compiler Command Line Manual</title>
+  <title>CLI 1.2.0-b.9 Compiler Command Line Manual</title>
 
   <meta name="copyright" content="&#169; 2009-2022 Code Synthesis Tools CC"/>
   <meta name="keywords" content="cli,command,line,interface,compiler,c++"/>