docs: add release notes for rust.workspace()

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

Author: bonzini

docs/markdown/Rust.md

@@ -98,3 +98,40 @@ target is a proc macro or dylib, or it depends on a dylib, in which case [`-C
 prefer-dynamic`](https://doc.rust-lang.org/rustc/codegen-options/index.html#prefer-dynamic)
 will be passed to the Rust compiler, and the standard libraries will be
 dynamically linked.
+
+## Cargo interaction
+
+*Since 1.10.0*
+
+In most cases, a Rust program will use Cargo to download crates.  Meson is able
+to build Rust library crates based on a `Cargo.toml` file; each external crate
+corresponds to a subproject.  Rust module's ` that do not need a `build.rs` file
+need no intervention, whereas if a `build.rs` file is present it needs to be
+converted manually to Meson code.
+
+To enable automatic configuration of Cargo dependencies, your project must
+have `Cargo.toml` and `Cargo.lock` files in the root source directory;
+this enables proper feature resolution across crates.  You can then
+create a workspace object using the Rust module, and retrieve specific
+packages from the workspace:
+
+```meson
+rust = import('rust')
+cargo = rust.workspace()
+anyhow_dep = ws.subproject('anyhow').dependency()
+```
+
+The workspace object also enables configuration of Cargo features, for example
+from Meson options:
+
+```meson
+ws = rust.workspace(
+    features: ['feature1', 'feature2'])
+```
+
+### Limitations
+
+All your own crates must be built using the usual Meson functions such as
+[[static_library]] or [[executable]].  In the future, workspace object
+functionality will be extended to help building rustc command lines
+based on features, dependency names, and so on.

docs/markdown/Wrap-dependency-system-manual.md

@@ -368,10 +368,7 @@ Since *1.5.0* Cargo wraps can also be provided with `Cargo.lock` file at the roo
 of (sub)project source tree. Meson will automatically load that file and convert
 it into a series of wraps definitions.
 
-Since *1.10.0* Workspace Cargo.toml are supported. For the time being it is
-recommended to regroup all Cargo dependencies inside a single workspace invoked
-from the main Meson project. When invoking multiple different Cargo subprojects
-from Meson, feature resolution of common dependencies might be wrong.
+Since *1.10.0* Workspace Cargo.toml are supported.
 
 ## Using wrapped projects
 

docs/markdown/snippets/cargo-workspace-object.md

@@ -0,0 +1,13 @@
+## Cargo workspace object
+
+Meson now is able to parse the toplevel `Cargo.toml` file of the
+project when the `workspace()` method of the Rust module is called.
+This guarantees that features are resolved according to what is
+in the `Cargo.toml` file, and in fact enables configuration of
+features for the build.
+
+The returned object also allows retrieving features and dependencies
+for Cargo subprojects.
+
+While Cargo subprojects remain experimental, the Meson project will
+try to keep the workspace object reasonably backwards-compatible.