Add build target keyword parameter 'build_subdir' [v8]

Place the build products in a directory of the specified name
somewhere within the build directory. This allows use of the target
that includes a specific directory name:

        #include <subdir/configure.h>

This also allows creating targets with the same basename by using
different subdirectory names.

v2:
    Move build_subdir to Target class.
    Error if path separator in build_dir

v3:
    Rename to 'build_subdir' to make it clear that the name is
    appended to a meson-specific build directory, and does not
    provide the user with a way to define the overall meson build
    hierarchy.

    Allow build_subdir to include path separators.

    Support 'build_subdir' for configure_file.

    build_subdir must not exist in the source directory and
    must not contain '..'

    Add documentation and tests

v4:
    Rebase and prepare for version 1.9.1

    Add failing test case when build_subdir is present in the
    project.

    Add release note snippet

v5:
    Clarify wording on restrictions on the value of build_subdir. Use
    the same wording in each place this restriction is described.

v6:
    Move path validation to shared function, validate_build_subdir,
    instead of duplicating the tests in two places.

v7:
    Update version numbers to 1.10.0
    Add TypedDict updates.
    Remove spurious build_subdir instance variable

v8:
    Oops, missed one version number update.

Signed-off-by: Keith Packard <keithp@keithp.com>

3 files changed, 62 insertions, 0 deletions

diff --git a/docs/markdown/snippets/build_subdir.md b/docs/markdown/snippets/build_subdir.md
new file mode 100644
index 000000000..0c115d05d
--- /dev/null
+++ b/docs/markdown/snippets/build_subdir.md
@@ -0,0 +1,26 @@
+## Added `build_subdir` arg to various targets
+
+`custom_target()`, `build_target()` and `configure_file()` now support
+the `build_subdir` argument. This directs meson to place the build
+result within the specified sub-directory path of the build directory.
+
+```meson
+configure_file(input : files('config.h.in'),
+               output : 'config.h',
+               build_subdir : 'config-subdir',
+               install_dir : 'share/appdir',
+               configuration : conf)
+```
+
+This places the build result, `config.h`, in a sub-directory named
+`config-subdir`, creating it if necessary. To prevent collisions
+within the build directory, `build_subdir` is not allowed to match a
+file or directory in the source directory nor contain '..' to refer to
+the parent of the build directory. `build_subdir` does not affect the
+install directory path at all; `config.h` will be installed as
+`share/appdir/config.h`. `build_subdir` may contain multiple levels of
+directory names.
+
+This allows construction of files within the build system that have
+any required trailing path name components as well as building
+multiple files with the same basename from the same source directory.
diff --git a/docs/yaml/functions/_build_target_base.yaml b/docs/yaml/functions/_build_target_base.yaml
index 4cd91affe..f1dc09df0 100644
--- a/docs/yaml/functions/_build_target_base.yaml
+++ b/docs/yaml/functions/_build_target_base.yaml
@@ -354,3 +354,21 @@ kwargs:
     description: |
       If set, generates a GIR file with the given name. If this is unset then
       no GIR file will be generated.
+
+  build_subdir:
+    type: str
+    since: 1.10.0
+    description:
+      Places the build results in a subdirectory of the given name
+      rather than directly into the build directory. This does not
+      affect the install directory, which uses install_dir.
+
+      This allows inserting a directory name into the build path,
+      either when needed to use the build result while building other
+      targets or as a way to support multiple targets with the same
+      basename by using unique build_subdir values for each one.
+
+      To prevent collisions within the build directory, build_subdir
+      is not allowed to match a file or directory in the source
+      directory, nor contain '..' to refer to the parent of the build
+      directory.
diff --git a/docs/yaml/functions/configure_file.yaml b/docs/yaml/functions/configure_file.yaml
index 2deeff445..32cb55964 100644
--- a/docs/yaml/functions/configure_file.yaml
+++ b/docs/yaml/functions/configure_file.yaml
@@ -155,3 +155,21 @@ kwargs:
     description: |
       When specified, macro guards will be used instead of '#pragma once'. The
       macro guard name will be the specified name.
+
+  build_subdir:
+    type: str
+    since: 1.10.0
+    description:
+      Places the build results in a subdirectory of the given name
+      rather than directly into the build directory. This does not
+      affect the install directory, which uses install_dir.
+
+      This allows inserting a directory name into the build path,
+      either when needed to use the build result while building other
+      targets or as a way to support multiple targets with the same
+      basename by using unique build_subdir values for each one.
+
+      To prevent collisions within the build directory, build_subdir
+      is not allowed to match a file or directory in the source
+      directory, nor contain '..' to refer to the parent of the build
+      directory.