From 9cf7a125613f8cc929828780b8c7aefd0d3ee4ac Mon Sep 17 00:00:00 2001 From: Dylan Baker Date: Fri, 4 Mar 2022 15:26:50 -0800 Subject: [PATCH] docs: Add docs for structured_sources --- docs/markdown/snippets/structured_sources.md | 26 ++++++++++++++++++++ docs/yaml/functions/_build_target_base.yaml | 2 +- docs/yaml/functions/structured_sources.yaml | 21 ++++++++++++++++ docs/yaml/objects/structured_src.yaml | 3 +++ 4 files changed, 51 insertions(+), 1 deletion(-) create mode 100644 docs/markdown/snippets/structured_sources.md create mode 100644 docs/yaml/functions/structured_sources.yaml create mode 100644 docs/yaml/objects/structured_src.yaml diff --git a/docs/markdown/snippets/structured_sources.md b/docs/markdown/snippets/structured_sources.md new file mode 100644 index 000000000..19fdc86f2 --- /dev/null +++ b/docs/markdown/snippets/structured_sources.md @@ -0,0 +1,26 @@ +## structured_sources() + +A new function, `structured_sources()` has been added. This function allows +languages like Rust which depend on the filesystem layout at compile time to mix +generated and static sources. + +```meson +executable( + 'main', + structured_sources( + 'main.rs, + {'mod' : generated_mod_rs}, + ) +) +``` + +Meson will then at build time copy the files into the build directory (if +necessary), so that the desired file structure is laid out, and compile that. In +this case: + +``` +root/ + main.rs + mod/ + mod.rs +``` diff --git a/docs/yaml/functions/_build_target_base.yaml b/docs/yaml/functions/_build_target_base.yaml index 68df5d85f..4db37f4d8 100644 --- a/docs/yaml/functions/_build_target_base.yaml +++ b/docs/yaml/functions/_build_target_base.yaml @@ -49,7 +49,7 @@ kwargs: eg: `cpp_args` for C++ sources: - type: str | file | custom_tgt | custom_idx | generated_list + type: str | file | custom_tgt | custom_idx | generated_list | structured_src description: Additional source files. Same as the source varargs. build_by_default: diff --git a/docs/yaml/functions/structured_sources.yaml b/docs/yaml/functions/structured_sources.yaml new file mode 100644 index 000000000..a5f0a83f3 --- /dev/null +++ b/docs/yaml/functions/structured_sources.yaml @@ -0,0 +1,21 @@ +name: structured_sources +returns: structured_src +since: 0.62.0 +description: | + Create a StructuredSource object, which is opaque and may be passed as a source + to any build_target (including static_library, shared_library, executable, + etc.). This is useful for languages like Rust, which use the filesystem layout + to determine import names. This is only allowed in Rust targets, and cannot be + mixed with non structured inputs. + +posargs: + root: + type: list[str | file | custom_tgt | custom_idx | generated_list] + description: Sources to put at the root of the generated structure + +optargs: + additional: + type: dict[str | file | custom_tgt | custom_idx | generated_list] + description: | + Additional sources, where the key is the directory under the root to place + the values diff --git a/docs/yaml/objects/structured_src.yaml b/docs/yaml/objects/structured_src.yaml new file mode 100644 index 000000000..839575d7c --- /dev/null +++ b/docs/yaml/objects/structured_src.yaml @@ -0,0 +1,3 @@ +name: structured_src +long_name: Structured Source +description: Opaque object returned by [[structured_sources]].