CARGO.ECLASS
Section: eclass-manpages (5)Updated: Mar 2023
Index Return to Main Contents
NAME
cargo.eclass - common functions and variables for cargo buildsSUPPORTED EAPIS
7 8FUNCTIONS
- 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_urisIf 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.orgREPORTING BUGS
Please report bugs via https://bugs.gentoo.org/FILES
cargo.eclassSEE ALSO
ebuild(5)https://gitweb.gentoo.org/repo/gentoo.git/log/eclass/cargo.eclass
Index
This document was created by man2html, using the manual pages.
Time: 03:27:02 GMT, March 21, 2023