CARGO.ECLASS

Section: eclass-manpages (5)
Updated: May 2025
Index Return to Main Contents

NAME

cargo.eclass - common functions and variables for cargo builds

SUPPORTED EAPIS

TRANSITIVELY PROVIDED ECLASSES

rust

FUNCTIONS

_cargo_set_crate_uris <crates>

Generates the URIs to put in SRC_URI to help fetch dependencies. Constructs a list of crates from its arguments. If no arguments are provided, it uses the CRATES variable. The value is set as CARGO_CRATE_URIS.

cargo_crate_uris [<crates>...]

Generates the URIs to put in SRC_URI to help fetch dependencies. Constructs a list of crates from its arguments. If no arguments are provided, it uses the CRATES variable.

cargo_gen_config

Generate the $CARGO_HOME/config.toml necessary to use our local registry and settings. Cargo can also be configured through environment variables in addition to the TOML syntax below. For each configuration key below of the form foo.bar the environment variable CARGO_FOO_BAR can also be used to define the value. Environment variables will take precedence over TOML configuration, and currently only integer, boolean, and string keys are supported. For example the build.jobs key can also be defined by CARGO_BUILD_JOBS. Or setting CARGO_TERM_VERBOSE=false in make.conf will make build quieter.

cargo_target_dir

Return the directory within target that contains the build, e.g. target/aarch64-unknown-linux-gnu/release.

cargo_update_crates

Helper function to call `cargo update --offline` with the given Cargo.toml. This will update Cargo.{toml,lock}. This should provide a straightforward approach to updating vulnerable crates in a package.

To use: replace any vulnerable crates in ${CRATES} with updated (and compatible) versions, then call `cargo_update_crates` in src_prepare. If Cargo.toml is not in the root of ${S}, pass the path to the Cargo.toml as the first argument. It is up to the ebuild to ensure that the updated crates are compatible with the package and that no unexpected breakage occurs.

cargo_src_unpack

Unpacks the package and the cargo registry.

cargo_live_src_unpack

Runs 'cargo fetch' and vendors downloaded crates for offline use, used in live ebuilds. NOTE: might require passing --frozen to cargo_src_configure if git dependencies are used.

cargo_src_configure

Configure cargo package features and arguments. Extra positional arguments supplied to this function will be passed to cargo in all phases. Make sure all cargo subcommands support flags passed here.

Example of a package that explicitly builds only 'baz' binary and enables 'barfeature' and optional 'foo' feature. It will pass '--features barfeature --features foo --bin baz' in src_{compile,test,install}.

src_configure() {         local myfeatures=(
                barfeature
                $(usev foo)
        )
        cargo_src_configure --bin baz
}

In some cases crates may need the '--no-default-features' option, as there is no way to disable a single default feature, except disabling all. It can be passed directly to cargo_src_configure.

Some live/9999 ebuild may need the '--frozen' option, if git crates are used. Otherwise src_install phase may query network again and fail.

cargo_env Command with its arguments

Run the given command under an environment needed for performing tasks with Cargo such as building. RUSTFLAGS are appended to additional flags set here. Ensure these are set consistently between Cargo invocations, otherwise rebuilds will occur. Project-specific rustflags set against [build] will not take affect due to Cargo limitations, so add these to your ebuild's RUSTFLAGS if they seem important.

cargo_src_compile

Build the package using cargo build.

cargo_src_install

Installs the binaries generated by cargo. In some cases workspaces need an alternative --path parameter. Defaults to '--path ./' if no path is specified. '--path ./somedir' can be passed directly to cargo_src_install.

cargo_src_test

Test the package using cargo test.

ECLASS VARIABLES

CRATES (SET BEFORE INHERIT)

Bash string containing all crates that are to be downloaded. It is used by cargo_crate_uris. Typically generated by app-portage/pycargoebuild.

Ideally, crate names and versions should be separated by a `@` character. A legacy syntax using hyphen is also supported but it is much slower.

Example: CRATES=" metal@1.2.3 bar@4.5.6 iron_oxide@0.0.1 " inherit cargo ... SRC_URI="${CARGO_CRATE_URIS}"

CRATE_PATHS_OVERRIDE (SET BEFORE INHERIT)

Bash string containing crates that will be used to override dependencies via generated `paths = ['/path/to/crate']` configuration. This is not "smart", _all crates_ which match the `Cargo.toml` for a given crate/path will be overridden, ignoring lockfiles, version constraints, etc.

This should be used as a last resort where (e.g.) you are bootstrapping Rust and need to override a vendored crate with a newer version, and all versions in use are compatible.

Crate names and versions must be separated by a `@`; multiple crates are separated by a space or newline. Crates in CRATE_PATHS_OVERRIDE are implicitly added to CRATES; they do not need to be listed.

Example: CRATES=" foo@1.2.3
"

CRATE_PATHS_OVERRIDE=" openssl@0.10.35
openssl-sys@0.9.65
"

inherit cargo ... SRC_URI="${CARGO_CRATE_URIS}"

GIT_CRATES (SET BEFORE INHERIT)

Bash associative array containing all of the crates that are to be fetched via git. It is used by cargo_crate_uris. If this is defined, then cargo_src_install will add --frozen to "cargo install". The key is a crate name, the value is a semicolon-separated list of:

- the URI to fetch the crate from.
    - This intelligently handles GitHub and GitLab URIs so that
      just the repository path is needed.
    - The string "%commit%" gets replaced with the commit's checksum. - the checksum of the commit to use. - optionally: the path to look for Cargo.toml in.
  - This will also replace the string "%commit%" with the commit's checksum.
  - Defaults to: "${crate}-%commit%" - optionally: the git host so it would generate tarball download link.
  - E.g. gitlab
  - It fallbacks to detecting from URL if it's gitlab.com or github.com
    if no host provided.

Example of a simple definition with no path to Cargo.toml: declare -A GIT_CRATES=( [home]="https://github.com/rbtcollins/home;a243ee2fbee6022c57d56f5aa79aefe194eabe53"
)

Example with paths defined: declare -A GIT_CRATES=( [rustpython-common]="https://github.com/RustPython/RustPython;4f38cb68e4a97aeea9eb19673803a0bd5f655383;RustPython-%commit%/common"
[rustpython-parser]="https://github.com/RustPython/RustPython;4f38cb68e4a97aeea9eb19673803a0bd5f655383;RustPython-%commit%/compiler/parser"
)

Example with host defined: declare -A GIT_CRATES=( [clapper]="https://gitlab.gnome.org/JanGernert/clapper-rs;530b6fd53a60563d8038f7a1d9d735d6dc496adb;clapper-rs-%commit%/libclapper-rs;gitlab"
)

CARGO_BOOTSTRAP (SET BEFORE INHERIT)

Ignore `_CARGO_ECLASS_RUST_MIN_VER` checks. If you aren't bootstrapping Rust you probably don't need this.

CARGO_OPTIONAL (SET BEFORE INHERIT)

If set to a non-null value, the part of the ebuild before "inherit cargo" will be considered optional. No dependencies will be added and no phase functions will be exported.

If you enable CARGO_OPTIONAL call at least cargo_gen_config manually before using other src_* functions or cargo_env of this eclass. Note that cargo_gen_config is automatically called by cargo_src_unpack.

myfeatures

Optional cargo features defined as bash array. Should be defined before calling cargo_src_configure.

Example of a package that has x11 and wayland features and disables default features. src_configure() {         local myfeatures=(
                $(usex X x11 '')
                $(usev wayland)
        )
        cargo_src_configure --no-default-features
}

ECARGO_HOME (GENERATED BY ECLASS)

Location of the cargo home directory.

ECARGO_REGISTRY_DIR (USER VARIABLE)

Storage directory for cargo registry. Used by cargo_live_src_unpack to cache downloads. This is intended to be set by users. Ebuilds must not set it.

Defaults to "${DISTDIR}/cargo-registry" if not set.

ECARGO_OFFLINE (USER VARIABLE)

If non-empty, this variable prevents online operations in cargo_live_src_unpack. Inherits value of EVCS_OFFLINE if not set explicitly.

ECARGO_VENDOR (GENERATED BY ECLASS)

Location of the cargo vendor directory.

EVCS_UMASK (USER VARIABLE)

Set this variable to a custom umask. This is intended to be set by users. By setting this to something like 002, it can make life easier for people who use cargo in a home directory, but are in the portage group, and then switch over to building with FEATURES=userpriv. Or vice-versa.

CARGO_CRATE_URIS (GENERATED BY ECLASS)

List of URIs to put in SRC_URI created from CRATES variable.

AUTHORS

Doug Goldstein <cardoe@gentoo.org>
Georgy Yakovlev <gyakovlev@gentoo.org>
Matt Jolly <kangie@gentoo.org>

MAINTAINERS

rust@gentoo.org

REPORTING BUGS

Please report bugs via https://bugs.gentoo.org/

FILES

cargo.eclass

This document was created by man2html, using the manual pages.
Time: 03:27:01 GMT, May 22, 2025