Proposal: `rust.workspace()` Cargo integration

[bonzini]

This is a proposal for more complete integration of Cargo.toml parsing in the Rust module. For simple projects (without complex build.rs scripts), building becomes straightforward:

cargo = import('rust').workspace()
cargo.library()  # For library crates
# or
cargo.executables()  # For binary crates

Any build.rs scripts are ignored. Subprojects with complex build scripts will need manual configuration, unless the script is unnecessary when building with Meson. Extremely common crates (anyhow, thiserror, libc, serde, proc_macro2, unicode_ident, syn, quote, etc.) could be distributed as wraps to minimize manual dependency management.

Module-level Method

rust.workspace(default_features: bool = true, features: list[str] |dict[bool|feature], dev_dependencies: bool | list[str] = true, build_dependencies: bool | list[str] = false)

Returns a new workspace object corresponding to the Cargo.toml file in the root of the source tree. Optionally disable default features and set a desired list of features instead.

Feature objects can be used to modify default features (enabled = force true, auto = true if part of the default features, disabled = force false).

Optionally add some or all dev_dependencies/build_dependencies. build_dependencies are built for the BUILD machine, you generally want some of them (e.g. phf_codegen) but not all of them (e.g. not cc).

#15158 implements methods marked with "✅"

Workspace Object

All methods accept a name parameter that can be omitted or '' to refer to the root package of the workspace (or the sole package if not a workspace).

Additional features compared to built-in functions

• rust_args for --cfg, --check-cfg, and lint options from Cargo.toml and feature resolution are added automatically
• [dependencies] sections are used to build a rust_dependency_map
• If a dependency has not yet been built, library targets are attempted to build automatically.
• An extra cfg: list[str] parameter is converted into --cfg options

Accessor Methods

workspace.packages()

Returns the chosen set of packages in the workspace.

workspace.package([name][, native: bool])

Returns a package object for the given package. Name is empty for the root package, not empty for workspace packages.

workspace.subproject(name[, api][, native: bool]) ✅

Returns a read-only package object for the given dependency. (Could possibly be used by the generated meson.build for Cargo subprojects?).

Package object for subprojects

package.features() ✅

Returns the resolved set of features for the given package.

package.all_features() ✅

Returns all features defined by the given package.

package.dependency([rust_abi: 'rust|c|proc-macro']) ✅

Return the dep object for the given package.

Package object for toplevel Cargo.toml packages

package.rustc_args()

Returns compiler arguments from Cargo.toml lints and from feature resolution

package.env()

Returns environment variables that Cargo would set.

package.rust_dependency_map()

Return the dependency map built from the Cargo.toml [dependencies] section

rust_abi must be specified in the rare case where both Rust and C libraries are built

package.library(cfg: list[str] = [], rust_abi: 'rust'|'c', **kwargs) (rlib/dylib)

package.proc_macro(cfg: list[str] = [], **kwargs)

Build the library target for the specified package (or root package if name is empty) and ABI. Pass extra arguments to the underlying Meson library function.

Shared/static/both libraries is obtained from [lib] section. Fails if the given kind of library is not found in [lib].

Executable Building Methods

package.executables(list[str] = (all targets), cfg: list[str] = [], **kwargs)

Build binary targets for the specified package. If positional arguments are absent, builds all binaries. Extra arguments are passed to executable().

Returns a dictionary mapping target names to executable objects.

Test and Example Methods

package.tests(list[str] = (all targets), cfg: list[str] = [], **kwargs)

package.benchmarks(list[str] = (all targets), cfg: list[str] = [], **kwargs)

package.examples(list[str] = (all targets), cfg: list[str] = [], **kwargs)

Build test/benchmark/example targets for the specified package. If targets is absent, builds all targets of that type. Extra arguments are passed to executable().

Tests/benchmarks are automatically passed to rust.test()/rust.benchmark() and extra arguments can be passed to those functions as well - complete list of arguments TBD.

Returns a dictionary mapping target names to executable objects.

package.doctest(**kwargs)

Build doctests for the specified package. Extra arguments are passed to rust.doctest(). The doc suite is automatically added.

Usage Examples

Simple Library Crate

cargo = import('rust').workspace()
cargo.package().library()

CLI Application

cargo = import('rust').workspace()
cargo.package().executables()

Workspace with Multiple Packages

cargo = import('rust').workspace()
cargo.package('myproject-core').library(install: false)
cargo.package('myproject-cli').executables()

With Custom Configuration

cargo = import('rust').workspace(default_features: get_option('default'),
  features: {
    'f1': get_option('f1'),
    'f2': get_option('f2'),
  })
cargo.package().executables()

See also

• cargo: Add support for target specific dependencies #13780
• cargo: reintroduce feature options, as a means to provide input for the interpreter #14660
• cargo: Add global features options #14663
• Workspace support for Cargo subprojects #14880
• do not process Cargo.lock for dependent crates, if parent has Cargo.lock #14906
• Support [lints] table in Cargo.toml #14921
• Use toplevel Cargo.toml for feature resolution #15158

[bonzini]

@xclaesse @dcbaker you might be interested :)

[xclaesse]

I'm not sure to understand what this is solving. Cargo itself already has a workspace concept that we don't yet support, I feel reusing the same terminology here would be confusing.

[bonzini]

Cargo itself already has a workspace concept that we don't yet support, I feel reusing the same terminology here would be confusing.

It's reusing it on purpose. Meson supports a single Cargo.lock file and a single set of features, and this is where the affinity between a Meson build directory and a Cargo workspace starts. Quoting from https://doc.rust-lang.org/cargo/reference/workspaces.html "all packages share a common Cargo.lock file which resides in the source root" but also:

• a Meson build directory has "commands that run across all workspace members", e.g. meson test or ninja clippy
• all packages share a common output directory, which in Meson is the build root

So the idea is to provide an object to organize the build of all packages in the "Meson workspace", no matter if they:

• are Cargo subprojects or members of the Cargo workspace (including the root or sole package)
• have only Rust dependencies (and therefore their build process in entirely described by Cargo.toml) or also C dependencies (and therefore need some rules to be written by hand)

Operating on a "workspace" fixes the ordering problem with declaring dependencies, by including an arbitrary number of user packages in the feature resolution instead of operating one subproject at a time. However, this is not even the main thing that the proposal adds—which is to extend Cargo.toml parsing to crates defined by the project, as opposed to just dependencies.

This in turn solves issues such as:

• it simplifies a lot the configuration of Rust projects, for example by reusing configuration like [lints] (see this handy but bulky script in QEMU)
• it lets you use [dependencies] as an entry point for configuring subproject features (in addition to specifying features based on Meson options)

[xclaesse]

I better understand your intention here, I'm not yet entirely onboard.

We need a way to "prepare" multiple crates from the meson main project before generating their AST and getting a dependency object.

Something like

rust.cargo_prepare('foo-1-rs', features:...)
rust.cargo_prepare('bar-1-rs', features:...)
foo_dep = dependency('foo-1-rs')

That way if foo and bar both depends on a common crate, that crate can be configured with all need features.