CARGO-MODULE(5)

NAME
cargo-module - devel/cargo port module

DESCRIPTION
This manual page documents the behavior of setting MODULES=devel/cargo in the ports(7) tree.

Automates download and compilation of dependencies of a Rust project using cargo(1).

During fetch, static dependencies ("crates") listed in MODCARGO_CRATES are downloaded using MODCARGO_DIST_SUBDIR as DIST_SUBDIR.

During post-extract, crates defined in MODCARGO_CRATES are moved to the MODCARGO_VENDOR_DIR directory. If MODCARGO_CRATES_BUILDDEP is enabled, the module may modify vendored crates in order to prefer system libraries instead of bundled upstream copies. This affects several common “-sys” crates such as “openssl-sys” and “libsqlite3-sys”.

During post-patch, crate-metadata are generated using devel/cargo-generate-vendor.

With CONFIGURE_STYLE set to ‘cargo’, cargo is configured to use MODCARGO_VENDOR_DIR instead of the standard crates-io network source. Finally, any crates listed in MODCARGO_CRATES_UPDATE are updated.

MODCARGO_RUSTFLAGS can be used to pass custom flags to all rustc(1) invocations.

lang/rust is added to MODULES, and devel/cargo-generate-vendor is added to BUILD_DEPENDS.

This module defines:

MODCARGO_BUILD
    Whether to define the default do-build target. Defaults to ‘Yes’.

MODCARGO_BUILD_ARGS
    Additional arguments passed to cargo build.

MODCARGO_CARGOTOML
    Path to cargo manifest. Defaults to ${WRKSRC}/Cargo.toml.

MODCARGO_CARGOLOCK
    Path to Cargo.lock, which is used only by the modcargo-gen-crates target. Defaults to ${MODCARGO_CARGOTOML:toml=lock}.

MODCARGO_CRATES
    Crates that will be downloaded by the module.

MODCARGO_CRATES_BUILDDEP
    Whether to modify vendored crates in order to prefer system libraries over bundled upstream sources. Defaults to ‘Yes’.

MODCARGO_CRATES_KEEP
    List of crates that should not be modified during post-extract. Entries may be specified either as crate names or “name-version”.

MODCARGO_CRATES_UPDATE
    List of crates to update, overriding the version listed in Cargo.lock.

MODCARGO_DIST_SUBDIR
    Subdirectory used for crate distfiles. Defaults to ‘cargo’. If DIST_SUBDIR is defined, MODCARGO_DIST_SUBDIR must also be defined.

MODCARGO_FEATURES
    List of features to be used when building.

MODCARGO_INSTALL
    Whether to define the default do-install target. Defaults to ‘Yes’.

MODCARGO_INSTALL_ARGS
    Additional arguments passed to cargo install.

MODCARGO_INSTALL_TARGET_PATHS
    List of paths to pass to cargo install instead of ~.. Needs to be set for some virtual manifests.

MODCARGO_NO_DEFAULT_FEATURES
    If set to ‘Yes’, pass --no-default-features to cargo commands.

MODCARGO_RUSTFLAGS
    Flags passed to all rustc(1) invocations performed by cargo(1).

MODCARGO_TARGET_DIR
    Location of cargo build artifacts. Defaults to ${WRKBUILD}/target.

MODCARGO_TEST
    Whether to define the default do-test target. Defaults to ‘Yes’.

MODCARGO_TEST_ARGS
    Additional arguments passed to cargo test.

MODCARGO_CARGO_BIN
    Path to the cargo(1) binary. Defaults to the version provided by devel/cargo.

MODCARGO_VENDOR_DIR
    Name of the local directory for vendoring crates. Defaults to ${WRKSRC}/modcargo-crates.

MODCARGO_WANTLIB
    Architecture-specific WANTLIB entries required by all Rust code. It is a copy of MODRUST_WANTLIB provided for simplicity.

The module creates a local cargo configuration in ${WRKDIR}/.cargo/config.toml which configures vendored sources, offline operation, Rust toolchain paths, and build profiles.

This module adds three make(1) targets:

modcargo-metadata
    Rerun the generation of crates' metadata.

modcargo-gen-crates
    Generate the MODCARGO_CRATES list from Cargo.lock (a preliminary crates list is not required).

modcargo-gen-crates-licenses
    Generate the MODCARGO_CRATES list with license information from crates present in the MODCARGO_VENDOR_DIR directory.

SEE ALSO
port-modules(5)