0.12 (2022-05-02)¶

Support package variable overrides using the command line¶

Package variables can now be overridden from the command line. Consider the following site example:

LIBFOO_SITE = 'git@example.com:base/libfoo.git'

This Git-sourced package will cache the repository found at git@example.com:base/libfoo.git before extracting the configured revision into the package’s build output directory. If a developer wanted to temporarily override this option for a build, the following shows how a developer can override the site variable:

releng-tool LIBFOO_SITE=https://example.com/libfoo.git

Note that complex package variables may not be able to be overridden from the command line.

Support environment variable injection using the command line¶

Environment variables can now be injected into the releng-tool process from the command line. While users can use either export/set variables in their environments, or (on Unix) prefix a command call with variable assignments; the ways to do this is not consistent. A desire was to allow users to be able to inject environment options in a way similar to how Makefile calls can perform variable assignments through the command line. For example:

make TEST=1

This new feature enables such a capability by scanning the argument options of a releng-tool invoke and applying key-value pair entries into the working environment. Before, users would have to perform something such as the following:

(*nix)
MY_CUSTOM_ENV=testing releng-tool
(*nix; alternative)
export MY_CUSTOM_ENV=testing
releng-tool
(windows)
set MY_CUSTOM_ENV=testing
releng-tool

With this change, the following will work for any environment:

releng-tool MY_CUSTOM_ENV=testing

Package-specific command line execution¶

Developer now have an easy way to issue raw commands inside a package’s prepared build directory. For example, developing/testing with an autotools project, a developer can issue a manual configuration request to test/sanity check options:

releng-tool libfoo-exec "./configure --help"

This is to help developers try out alternative commands/actions without manually editing their package’s definition; as well as avoiding the need to navigate to an output directory, manually preparing environment variables and issuing raw commands in an output directory.

New environment/script variables¶

This release includes a series of new environment/script variables to help developers better tailor their package definitions.

The PKG_BUILD_BASE_DIR has been introduced, providing a way for a package to reference the root of a package’s extracted folder. In most cases, the PKG_BUILD_DIR variable can be used to serve this purpose; however, if a package defines LIBFOO_BUILD_SUBDIR, the build directory will be resolved to the subdirectory location in the extracted folder. If a package utilizes the subdirectory configuration and still wishes to somehow reference extracted content from the root of the extracted package, this “base” directory can be used.

Several prefixed-related directories are also defined. These can be used to allow a developer to reference specific include or library paths for the host, staging or target areas. The following lists the newly added prefixed-related variables:

HOST_INCLUDE_DIR (e.g. <host-dir>/usr/include)
HOST_LIB_DIR (e.g. <host-dir>/usr/lib)
PREFIXED_HOST_DIR (e.g. <host-dir>/usr)
PREFIXED_STAGING_DIR (e.g. <staging-dir>/usr)
PREFIXED_TARGET_DIR (e.g. <target-dir>/usr)
STAGING_INCLUDE_DIR (e.g. <staging-dir>/usr/include)
STAGING_LIB_DIR (e.g. <staging-dir>/usr/lib)
TARGET_INCLUDE_DIR (e.g. <target-dir>/usr/include)
TARGET_LIB_DIR (e.g. <target-dir>/usr/lib)

New include script function¶

The releng_include helper function has been added to allow releng-tool script to load scripts alongside a given script – providing a way to split up a script across multiple files. For example, a script-based package with a libfoo-build build script can split various build operations across multiple files and include them in their build script:

[package/libfoo/libfoo-build]

# perform various tasks
releng_include('build-task-a')
releng_include('build-task-b')

[package/libfoo/build-task-a]

note('performing task a')
...

[package/libfoo/build-task-b]

note('performing task b')
...

Correct Git cache management with branch updates¶

For VCS-based sites, the revision field can accept a branch value for the respective VCS-type. In this case, specifying the branch of a Git repository as the version or revision value will fetch the branch from the configured site before attempting to extract/build the package. For example:

LIBFOO_REVISION = 'my-feature-branch'

With releng-tool, once a package is fetched, it will not be fetched again. For branch-based references, this may not be ideal if the branch is expected to update over time. Users could build from a clean environment, but this can add additional build time where many packages are used and each one needs to re-download/re-build their sources. For a user to perform a rebuild of a VCS-type project, the following steps should be supported:

releng-tool libfoo-fetch    # fetch the new version of a branch
releng-tool libfoo-clean    # remove any previously extracted files
releng-tool libfoo          # build the package again

An issue with releng-tool’s Git extraction process would incorrectly extract the contents of the previously cached revision of a branch the first time it has been extracted from an updated fetch. This release includes corrections to this process to always use the most recently updated revision for a branch is used after performing a fresh fetch/clean with cached content.