From 1c30f9e9c4fca846f05e881638920a9beb082fd1 Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Thu, 8 Jun 2023 13:31:08 +0200
Subject: Add support for buildfile importation

---
 libbuild2/file.hxx | 52 +++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 45 insertions(+), 7 deletions(-)

(limited to 'libbuild2/file.hxx')

diff --git a/libbuild2/file.hxx b/libbuild2/file.hxx
index 5847498..6c5097d 100644
--- a/libbuild2/file.hxx
+++ b/libbuild2/file.hxx
@@ -19,6 +19,28 @@ namespace build2
   class lexer;
   class parser;
 
+  // The following filesystem entries in the build/ subdirectory are reserved
+  // by the build2 core:
+  //
+  // build/            -- build2 core-internal build state (e.g., recipes)
+  // bootstrap/        -- bootstrap state and hooks
+  // bootstrap.build   -- bootstrap buildfile
+  // root/             -- root load hooks
+  // root.build        -- root buildfile
+  // export.build      -- export stub
+  // export/           -- exported buildfiles
+  //
+  // The build/, bootstrap/, root/, and config.build entries are in .gitignore
+  // as generated by bdep-new.
+  //
+  // The rest of the filesystem entries are shared between the project and the
+  // modules that it loads. In particular, if a project loads module named
+  // <mod>, then the <mod>.build, <mod>/, *.<mod> entries (spelled in any
+  // case) are reserved to this module and should not be used by the project
+  // unless explicitly allowed by the module. By convention, <mod>/build/ is
+  // for module-internal build state (e.g., C++ modules side-build) and is
+  // .gitignore'ed.
+  //
   LIBBUILD2_SYMEXPORT extern const dir_path std_build_dir;  // build/
 
   // build/root.build
@@ -339,7 +361,9 @@ namespace build2
   // Note also that we return names rather than a single name: while normally
   // it will be a single target name, it can be an out-qualified pair (if
   // someone wants to return a source target) but it can also be a non-target
-  // since we don't restrict what users can import/export.
+  // since we don't restrict what users can import/export. If name has
+  // buildfile type, then the result is an absolute buildfile target to be
+  // included (once) at the point of importation.
   //
   // Finally, note that import is (and should be kept) idempotent or, more
   // precisely, "accumulatively idempotent" in that additional steps may be
@@ -358,7 +382,7 @@ namespace build2
   // Import phase 2.
   //
   const target&
-  import (context&, const prerequisite_key&);
+  import2 (context&, const prerequisite_key&);
 
   // As above but import the target "here and now" without waiting for phase 2
   // (and thus omitting any rule-specific logic). This version of import is,
@@ -383,6 +407,9 @@ namespace build2
   // target::as_name() for details) as well as the kind of import that was
   // performed.
   //
+  // Note: cannot be used to import buildfile targets (use import_buildfile()
+  // instead).
+  //
   template <typename T>
   struct import_result
   {
@@ -391,6 +418,13 @@ namespace build2
     import_kind kind;
   };
 
+  // Print import_direct<exe>() result either as a target for a normal import
+  // or as a process path for ad hoc and fallback imports. Normally used in
+  // build system modules to print the configuration report.
+  //
+  LIBBUILD2_SYMEXPORT ostream&
+  operator<< (ostream&, const import_result<exe>&);
+
   import_result<target>
   import_direct (scope& base,
                  name,
@@ -433,12 +467,16 @@ namespace build2
                  bool, bool, bool,
                  const location&, const char* = "import");
 
-  // Print import_direct<exe>() result either as a target for a normal import
-  // or as a process path for ad hoc and fallback imports. Normally used in
-  // build system modules to print the configuration report.
+  // The import_direct() equivalent for importing buildfile targets. Return
+  // empty name if optional and not found. Note that the returned file path is
+  // not necessarily checked for existence so sourcing it may still fail.
   //
-  LIBBUILD2_SYMEXPORT ostream&
-  operator<< (ostream&, const import_result<exe>&);
+  // Note also that this function can be used for an ad hoc import by passing
+  // an absolute target name as would be returned by the normal import (can be
+  // useful for importing own buildfiles).
+  //
+  LIBBUILD2_SYMEXPORT path
+  import_buildfile (scope& base, name, bool optional, const location&);
 
   // As import phase 2 but only imports as an already existing target. But
   // unlike it, this function can be called during the load and execute
-- 
cgit v1.1