cargo: add configurable features to Interpreter

Add features property to cargo.Interpreter to make default features configurable;
customization of which features are enabled by default is triggered by
rust.workspace().

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

1 files changed, 40 insertions, 0 deletions

diff --git a/docs/markdown/Rust-module.md b/docs/markdown/Rust-module.md
index 64c4c2311..1e8305d07 100644
--- a/docs/markdown/Rust-module.md
+++ b/docs/markdown/Rust-module.md
@@ -174,15 +174,29 @@ Only a subset of [[shared_library]] keyword arguments are allowed:
 
 ### workspace()
 
+Basic usage:
+
 ```
 cargo_ws = rustmod.workspace()
 ```
 
+With custom features:
+
+```
+feature_list = get_feature('f1') ? ['feature1'] : []
+feature_list += get_feature('f2') ? ['feature2'] : []
+cargo_ws = rustmod.workspace(features: feature_list)
+```
+
 *Since 1.11.0*
 
 Create and return a `workspace` object for managing the project's Cargo
 workspace.
 
+Keyword arguments:
+- `default_features`: (`bool`, optional) Whether to enable default features.
+- `features`: (`list[str]`, optional) List of additional features to enable globally.
+
 A project that wishes to use Cargo subprojects should have `Cargo.lock` and `Cargo.toml`
 files in the root source directory, and should call this function before using
 Cargo subprojects.
@@ -190,3 +204,29 @@ Cargo subprojects.
 The first invocation of `workspace()` establishes the *Cargo interpreter*
 that resolves dependencies and features for both the toplevel project (the one
 containing `Cargo.lock`) and all subprojects that are invoked with the `cargo` method,
+
+You can optionally customize the feature set, by providing `default_features`
+and `features` when the Cargo interpreter is established.  If any of these
+arguments is not specified, `default_features` is taken as `true` and
+`features` as the empty list.
+
+Once established, the Cargo interpreter's configuration is locked. Later calls to
+`workspace()` must either omit all arguments (accepting the existing configuration)
+or provide the same set of features as the first call. Mismatched arguments will cause
+a build error.
+
+The recommendation is to not specify any keyword arguments in a subproject, so
+that they simply inherit the parent's configuration.  Be careful about the
+difference between specifying arguments and not doing so:
+
+```
+# always works regardless of parent configuration
+cargo_ws = rustmod.workspace()
+
+# fails if parent configured different features
+cargo_ws = rustmod.workspace(default_features: true)
+cargo_ws = rustmod.workspace(features: [])
+```
+
+The first form says "use whatever features are configured," while the latter forms
+say "require this specific configuration," which may conflict with the parent project.