From eb5fbfce760416f964b2b29da142ed4fc7bf4811 Mon Sep 17 00:00:00 2001
From: Dylan Baker <dylan@pnwbakers.com>
Date: Mon, 17 May 2021 16:51:20 -0700
Subject: [PATCH] docs: Add a document on using Rust in Meson

This is hardly complete, but it's a start.
---
 docs/markdown/Rust.md | 56 +++++++++++++++++++++++++++++++++++++++++++
 docs/sitemap.txt      |  1 +
 2 files changed, 57 insertions(+)
 create mode 100644 docs/markdown/Rust.md

diff --git a/docs/markdown/Rust.md b/docs/markdown/Rust.md
new file mode 100644
index 000000000000..076386189032
--- /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.60
+
+You can use a "structured source" for this. Structured sources are a dictionary
+mapping a string of the directory ('' means root), 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/sitemap.txt b/docs/sitemap.txt
index 11b64e0c7120..e562ac79d8d4 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