diff options
Diffstat (limited to 'docs/markdown/Rust-module.md')
| -rw-r--r-- | docs/markdown/Rust-module.md | 40 |
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. |