diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/markdown/Rust.md | 37 | ||||
| -rw-r--r-- | docs/markdown/Wrap-dependency-system-manual.md | 5 | ||||
| -rw-r--r-- | docs/markdown/snippets/cargo-workspace-object.md | 13 |
3 files changed, 51 insertions, 4 deletions
diff --git a/docs/markdown/Rust.md b/docs/markdown/Rust.md index 67bbdec5b..c93eadf02 100644 --- a/docs/markdown/Rust.md +++ b/docs/markdown/Rust.md @@ -106,3 +106,40 @@ target name. First, dashes, spaces and dots are replaced with underscores. Sec *since 1.10.0* anything after the first `+` is dropped. This allows creating multiple targets for the same crate name, for example when the same crate is built multiple times with different features, or for both the build and the host machine. + +## Cargo interaction + +*Since 1.11.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_ws = rustmod.workspace() +anyhow_dep = ws.subproject('anyhow').dependency() +``` + +The workspace object also enables configuration of Cargo features, for example +from Meson options: + +```meson +cargo_ws = rustmod.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. diff --git a/docs/markdown/Wrap-dependency-system-manual.md b/docs/markdown/Wrap-dependency-system-manual.md index 4a7250d3b..3e251d725 100644 --- a/docs/markdown/Wrap-dependency-system-manual.md +++ b/docs/markdown/Wrap-dependency-system-manual.md @@ -372,10 +372,7 @@ crates into a series of wraps definitions. Since *1.11.0* the overlay directory dependency name for `crates.io` URLs, and the final component of the URL (possibly with the `.git` suffix removed) for "git" URLs. -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 diff --git a/docs/markdown/snippets/cargo-workspace-object.md b/docs/markdown/snippets/cargo-workspace-object.md new file mode 100644 index 000000000..c6bc4d4ba --- /dev/null +++ b/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. |