RUST.ECLASS

Section: eclass-manpages (5)
Updated: Dec 2024
Index Return to Main Contents

NAME

rust.eclass - Utility functions to build against slotted Rust

DESCRIPTION

An eclass to reliably depend on a Rust or Rust/LLVM combination for a given Rust slot. To use the eclass:

1. If required, set RUST_{MAX,MIN}_SLOT to the range of supported slots.

2. If rust is optional, set RUST_OPTIONAL to a non-empty value then
appropriately gate ${RUST_DEPEND}

3. Use rust_pkg_setup, get_rust_prefix or RUST_SLOT.

SUPPORTED EAPIS

FUNCTIONS

_get_rust_slot [-b|-d]

Find the newest Rust install that is acceptable for the package, and print its version number (i.e. SLOT) and type (source or bin[ary]).

If -b is specified, the checks are performed relative to BROOT, and BROOT-path is returned. -b is the default.

If -d is specified, the checks are performed relative to ESYSROOT, and ESYSROOT-path is returned.

If RUST_M{AX,IN}_SLOT is non-zero, then only Rust versions that are not newer or older than the specified slot(s) will be considered. Otherwise, all Rust versions are be considered acceptable.

If the `rust_check_deps()` function is defined within the ebuild, it will be called to verify whether a particular slot is accepable. Within the function scope, RUST_SLOT and LLVM_SLOT will be defined.

The function should return a true status if the slot is acceptable, false otherwise. If rust_check_deps() is not defined, the function defaults to checking whether a suitable Rust package is installed.

get_rust_path prefix slot rust_type

Given argument of slot and rust_type, return an appropriate path for the Rust install. The rust_type should be either "source" or "binary". If the rust_type is not one of these, the function will die.

get_rust_prefix [-b|-d]

Find the newest Rust install that is acceptable for the package, and print an absolute path to it. If both -bin and regular Rust are installed, the regular Rust is preferred.

The options and behavior are the same as get_rust_slot.

rust_prepend_path <slot> <type>

Prepend the path to the specified Rust to PATH and re-export it.

rust_pkg_setup

Prepend the appropriate executable directory for the newest acceptable Rust slot to the PATH. If used with LLVM, an appropriate `llvm-r1_pkg_setup` call should be made in addition to this function. For path determination logic, please see the get_rust_prefix documentation.

The highest acceptable Rust slot can be set in RUST_MAX_VER variable. If it is unset or empty, any slot is acceptable.

The lowest acceptable Rust slot can be set in RUST_MIN_VER variable. If it is unset or empty, any slot is acceptable.

`CARGO` and `RUSTC` variables are set for the selected slot and exported.

The PATH manipulation is only done for source builds. The function is a no-op when installing a binary package.

If any other behavior is desired, the contents of the function should be inlined into the ebuild and modified as necessary.

ECLASS VARIABLES

ERUST_SLOT_OVERRIDE (USER VARIABLE): Specify the version (slot) of Rust to be used by the package. This is useful for troubleshooting and debugging purposes; If unset, the newest acceptable Rust version will be used. May be combined with ERUST_TYPE_OVERRIDE. This variable must not be set in ebuilds.
ERUST_TYPE_OVERRIDE (USER VARIABLE): Specify the type of Rust to be used by the package from options: 'source' or 'binary' (-bin). This is useful for troubleshooting and debugging purposes. If unset, the standard eclass logic will be used to determine the type of Rust to use (i.e. prefer source if binary is also available). May be combined with ERUST_SLOT_OVERRIDE. This variable must not be set in ebuilds.
RUST_MAX_VER: Highest Rust slot supported by the package. Needs to be set before rust_pkg_setup is called. If unset, no upper bound is assumed.
RUST_MIN_VER: Lowest Rust slot supported by the package. Needs to be set before rust_pkg_setup is called. If unset, no lower bound is assumed.
RUST_NEEDS_LLVM: If set to a non-empty value generate a llvm_slot_${llvm_slot}? gated dependency block for rust slots in LLVM_COMPAT. This is useful for packages that need a tight coupling between Rust and LLVM but don't really care _which_ version of Rust is selected. Combine with RUST_MAX_VER and RUST_MIN_VER to limit the range of Rust versions that are acceptable. Will `die` if llvm-r1 is not inherited or an invalid combination of RUST and LLVM slots is detected; this probably means that a LLVM slot in LLVM_COMPAT has had all of its Rust slots filtered.
RUST_MULTILIB: If set to a non-empty value insert MULTILIB_USEDEP into the generated Rust dependency. For this to be useful inherit a multilib eclass and configure the appropriate phase functions.
RUST_DEPEND (GENERATED BY ECLASS): This is an eclass-generated Rust dependency string, filtered by RUST_MAX_VER and RUST_MIN_VER. If RUST_NEEDS_LLVM is set, this is grouped and gated by an appropriate `llvm_slot_x` USE for all implementations listed in LLVM_COMPAT.
RUST_OPTIONAL: If set to a non-empty value, the Rust dependency will not be added to BDEPEND. This is useful for where packages need to gate rust behind certain USE themselves.
RUST_REQ_USE: Additional USE-dependencies to be added to the Rust dependency. This is useful for packages that need to depend on specific Rust features, like clippy or rustfmt. The variable is expanded before being used in the Rust dependency.

AUTHORS

Matt Jolly <kangie@gentoo.org>

MAINTAINERS

Matt Jolly <kangie@gentoo.org>

REPORTING BUGS

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

FILES

rust.eclass

This document was created by man2html, using the manual pages.
Time: 03:27:02 GMT, December 09, 2024