Merge pull request #9339 from dcbaker/submit/structured_sources

Structured Sources

6 files changed, 108 insertions, 1 deletions

diff --git a/docs/markdown/Rust.md b/docs/markdown/Rust.md
new file mode 100644
index 0000000..b2376c3
--- /dev/null
+++ b/docs/markdown/Rust.md
@@ -0,0 +1,56 @@
+---
+title: Rust
+short-description: Working with Rust in Meson
+---
+
+# Using Rust with Meson
+
+## Mixing Rust and non-Rust sources
+
+Meson currently does not support creating a single target with Rust and non Rust
+sources mixed together, therefore one must compile multiple libraries and link
+them.
+
+```meson
+rust_lib = static_library(
+    'rust_lib',
+    sources : 'lib.rs',
+    ...
+)
+
+c_lib = static_library(
+    'c_lib',
+    sources : 'lib.c',
+    link_with : rust_lib,
+)
+```
+This is an implementation detail of Meson, and is subject to change in the future.
+
+## Mixing Generated and Static sources
+
+*Note* This feature was added in 0.62
+
+You can use a [[structured_source]] for this. Structured sources are a dictionary
+mapping a string of the directory, to a source or list of sources.
+When using a structured source all inputs *must* be listed, as Meson may copy
+the sources from the source tree to the build tree.
+
+Structured inputs are generally not needed when not using generated sources.
+
+As an implementation detail, Meson will attempt to determine if it needs to copy
+files at configure time and will skip copying if it can. Copying is done at
+build time (when necessary), to avoid reconfiguring when sources change.
+
+```meson
+executable(
+    'rust_exe',
+    structured_sources(
+        'main.rs',
+        {
+            'foo' : ['bar.rs', 'foo/lib.rs', generated_rs],
+            'foo/bar' : [...],
+            'other' : [...],
+        }
+    )
+)
+```
diff --git a/docs/markdown/snippets/structured_sources.md b/docs/markdown/snippets/structured_sources.md
new file mode 100644
index 0000000..19fdc86
--- /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/sitemap.txt b/docs/sitemap.txt
index 11b64e0..e562ac7 100644
--- a/docs/sitemap.txt
+++ b/docs/sitemap.txt
@@ -63,6 +63,7 @@ index.md
 		Vala.md
 		D.md
 		Cython.md
+		Rust.md
 		IDE-integration.md
 		Custom-build-targets.md
 		Build-system-converters.md
diff --git a/docs/yaml/functions/_build_target_base.yaml b/docs/yaml/functions/_build_target_base.yaml
index 88fb8ae..87966f6 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 0000000..a5f0a83
--- /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 0000000..839575d
--- /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]].