Cargo package

Dodane w wersji 1.3.

Zmienione w wersji 1.4: Added support for dependency patching.

A Cargo package provides support for processing a Cargo supported module.

LIBFOO_TYPE = 'cargo'

During the configuration stage of a Cargo package, cargo will be invoked to generate build files for the module. After fetching and extracting a package, cargo vendor will be invoked to download any defined dependencies defined in Cargo.toml. After all dependencies are acquired, a build stage will be triggered using cargo build, followed by an installation stage using cargo install. Each stage can be configured to manipulate environment variables and options used by the Cargo executable.

Cargo packages are handled a bit differently compared to other package types. In order to support having Cargo application packages work with library dependencies managed in a releng-tool project, all Cargo packages in play will need to be extracted ahead of time before any individual Cargo package can be built.

For any Cargo package that defines a dependency to another Cargo package that is defined inside a releng-tool project, dependencies will be automatically patched to use the local package definition.

The following shows the default arguments used in stages and outlines configuration options that are available for an Cargo package to set. See also the Cargo package examples. All stages are invoked with:

  • A PKG_BUILD_DIR working directory.

  • The environment variable CARGO_HOME set to <CACHE_DIR>/.cargo (see also CACHE_DIR).

Cargo package do not have a configuration stage.

The build stage invokes cargo build with the arguments:

cargo build \
    --locked \
    --manifest-path Cargo.toml \
    --offline \
    --release \
    --target-dir <CARGO_STAGING_DIR>

With the following environment variables set:

CARGO_BUILD_JOBS=<NJOBS>

If LIBFOO_VCS_TYPE is configured to local, the --locked argument is not provided by default.

If a package defines build options that define a build profile (--profile), the --release argument is not provided by default.

The Cargo target directory is based on BUILD_DIR and .releng-tool-cargo-target folder:

<root-dir>/output/build/.releng-tool-cargo-target

The environment variable CARGO_BUILD_JOBS is populated by either the --jobs argument or LIBFOO_FIXED_JOBS.

The install stage invokes cargo install with the arguments:

cargo install \
    --force \
    --locked \
    --no-track \
    --offline \
    --path . \
    --root <TARGET_DIR> \
    --target-dir <CARGO_STAGING_DIR>

The Cargo target directory is based on BUILD_DIR and .releng-tool-cargo-target folder:

<root-dir>/output/build/.releng-tool-cargo-target

The --root path will be set to the target sysroot the package should install into (see also LIBFOO_INSTALL_TYPE). cargo install may be invoked multiple times for each target it needs to install into. Although, if a package defines build options that define a root path (--root), an install is only invoked once with the provided path.

The installation stage can be skipped by configuring LIBFOO_CARGO_NOINSTALL.

LIBFOO_BUILD_DEFS

Zmienione w wersji 2.2: Support added for path-like values.

Provides a means to pass definitions into the build process. This option can is defined as a dictionary of string pairs. This field is optional.

LIBFOO_BUILD_DEFS = {
    # adds "-Doption=value" to the command
    'option': 'value',
}

LIBFOO_BUILD_ENV

Zmienione w wersji 2.2: Support added for path-like values.

Provides a means to pass environment variables into the build process. This option is defined as a dictionary with key-value pairs where the key is the environment name and the value is the environment variable’s value. This field is optional.

LIBFOO_BUILD_ENV = {
    'OPTION': 'VALUE',
}

LIBFOO_BUILD_OPTS

Zmienione w wersji 2.2: Support added for path-like values.

Provides a means to pass command line options into the build process. This option can be defined as a dictionary of string pairs or a list with strings – either way defined will generate argument values to include in the build event. This field is optional.

LIBFOO_BUILD_OPTS = {
    # adds "--option value" to the command
    '--option': 'value',
}

# (or)

LIBFOO_BUILD_OPTS = [
    # adds "--some-option" to the command
    '--some-option',
]

LIBFOO_CARGO_NAME

Dodane w wersji 1.4.

Provides an explicit name to use for a Cargo package. By default, the used Cargo name is assumed to be the same as the package name used in releng-tool. If the names do not match, it is recommended to explicitly set the package name as it will be used to patch package dependencies together.

LIBFOO_CARGO_NAME = 'example-name'

LIBFOO_CARGO_NOINSTALL

Dodane w wersji 1.4.

Specifies whether the Cargo package should skip an attempt to invoke the install command. This option can be helpful when defining a Cargo package that is used as a library (instead of a full application). By default, the installation stage is invoked with a value of False.

LIBFOO_CARGO_NOINSTALL = True

LIBFOO_ENV

Dodane w wersji 0.17.

Zmienione w wersji 2.2: Support added for path-like values.

Provides a means to pass environment variables into all stages for a package. This option is defined as a dictionary with key-value pairs where the key is the environment name and the value is the environment variable’s value. This field is optional.

LIBFOO_ENV = {
    'OPTION': 'VALUE',
}

LIBFOO_INSTALL_DEFS

Zmienione w wersji 2.2: Support added for path-like values.

Provides a means to pass definitions into the installation process. This option can is defined as a dictionary of string pairs. This field is optional.

LIBFOO_INSTALL_DEFS = {
    # adds "--option=value" to the command
    '--option': 'value',
}

LIBFOO_INSTALL_ENV

Zmienione w wersji 2.2: Support added for path-like values.

Provides a means to pass environment variables into the installation process. This option is defined as a dictionary with key-value pairs where the key is the environment name and the value is the environment variable’s value. This field is optional.

LIBFOO_INSTALL_ENV = {
    'OPTION': 'VALUE',
}

LIBFOO_INSTALL_OPTS

Zmienione w wersji 2.2: Support added for path-like values.

Provides a means to pass command line options into the installation process. This option can be defined as a dictionary of string pairs or a list with strings – either way defined will generate argument values to include in the installation event. This field is optional.

LIBFOO_INSTALL_OPTS = {
    # adds "--option value" to the command
    '--option': 'value',
}

# (or)

LIBFOO_INSTALL_OPTS = [
    # adds "--some-option" to the command
    '--some-option',
]