CARGO.ECLASS

Section: eclass-manpages (5)
Updated: Mar 2023
Index Return to Main Contents

NAME

cargo.eclass - common functions and variables for cargo builds

SUPPORTED EAPIS

7 8

FUNCTIONS

cargo_crate_uris

Generates the URIs to put in SRC_URI to help fetch dependencies. Uses first argument as crate list. If no argument provided, uses CRATES variable.

cargo_gen_config

Generate the $CARGO_HOME/config 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_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 for package that explicitly builds only 'baz' binary and enables 'barfeature' and optional 'foo' feature. 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 '--no-default-features' option, as there is no way to disable single feature, except disabling all. It can be passed directly to cargo_src_configure().

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

cargo_src_compile

Build the package using cargo build

cargo_src_install

Installs the binaries generated by cargo In come case workspaces need alternative --path parameter default is '--path ./' if nothing 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 package wants to download used by cargo_crate_uris() Example:

CRATES="
metal-1.2.3
bar-4.5.6
iron_oxide-0.0.1
"
inherit cargo
...
SRC_URI="$(cargo_crate_uris)"

GIT_CRATES

bash associative array containing all crates that a package wants to be fetch by git. The key is the crate name, the value is a semicolon separated list of the following fields:

- the URI to to fetch the crate from
    - this intelligentally handles GitHub URIs and GitLab URIs so
      just the path is needed.
    - the string "%commit%" gets replaced with the commit - the hash of the commit to use - (optional) the path to look for Cargo.toml in
  - this will also replace  the string "%commit%" with the commit
  - if this not provided, it will be generated using the crate name and
    the commit Used by cargo_crate_uris

If this is defined, then cargo_src_install will add --frozen to "cargo install"

Example of simple definition of GIT_CRATES without any paths defined

declare -A GIT_CRATES=(
        [home]="https://github.com/rbtcollins/home;a243ee2fbee6022c57d56f5aa79aefe194eabe53"
)

Example code of how to define GIT_CRATES 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"
)

CARGO_OPTIONAL (SET BEFORE INHERIT)

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

If you enable CARGO_OPTIONAL, you have to set BDEPEND on virtual/rust for your package and call at least cargo_gen_config manually before using other src_ functions 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 package that has x11 and wayland as features, and disables default.

src_configure() {
        local myfeatures=(
        $(usex X x11 '')
                $(usev wayland)
        )
        cargo_src_configure --no-default-features
}

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" it 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.

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.

AUTHORS

Doug Goldstein <cardoe@gentoo.org>
Georgy Yakovlev <gyakovlev@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:02 GMT, March 21, 2023