Environment variables¶

Truco

Avoid using external environment variables for a project to configure package options such as compiler flags or interpreters. Managing these options inside a releng-tool project configuration or package definitions can improve configuration management.

Common¶

When configuration, package definitions or various scripts are invoked by releng-tool, the following environment variables are available:

`BUILD_DIR`¶

The build directory. By default, this will be a folder build found inside the configured output directory. For example:

<root-dir>/output/build

`CACHE_DIR`¶

The cache directory. By default, this will be a folder cache found inside the configured root directory. For example:

<root-dir>/cache

`DL_DIR`¶

The download directory. By default, this will be a folder dl found inside the configured root directory. For example:

<root-dir>/dl

`HOST_BIN_DIR`¶

Added in version 0.14.

The host directory’s prefixed bin directory. For example:

<root-dir>/output/build

`HOST_DIR`¶

The host directory. By default, this will be a folder host found inside the configured output directory. For example:

<root-dir>/output/host

`HOST_INCLUDE_DIR`¶

Added in version 0.12.

The host directory’s prefixed include directory.

`HOST_LIB_DIR`¶

Added in version 0.12.

The host directory’s prefixed library directory.

`IMAGES_DIR`¶

The images directory. By default, this will be a folder images found inside the configured output directory. For example:

<root-dir>/output/images

`LICENSE_DIR`¶

The licenses directory. By default, this will be a folder licenses found inside the configured output directory. For example:

<root-dir>/output/licenses

`NJOBS`¶

Number of calculated jobs to allow at a given time. Unless explicitly set by a system builder on the command line, the calculated number of jobs should be equal to the number of physical cores on the host. When building a specific package and the package overrides the number of jobs to use, the package-defined count will be used instead. This configuration will always be a value of at least one (1).

`NJOBSCONF`¶

Number of jobs to allow at a given time. Unlike NJOBS, NJOBSCONF provides the requested configured number of jobs to use. The value may be set to zero (0) to indicate an automatic detection of jobs to use. This can be useful for tools which have their own automatic job count implementation and do not want to rely on the value defined by NJOBS. When building a specific package and the package overrides the number of jobs to use, the package-defined count will be used instead.

`OUTPUT_DIR`¶

The output directory. By default, this will be a folder output found inside the configured root directory. For example:

<root-dir>/output

`PKG_BUILD_BASE_DIR`¶

Added in version 0.12.

The directory for a specific package’s base directory for buildable content. In most cases, this value will be the same as PKG_BUILD_DIR. However, if LIBFOO_BUILD_SUBDIR is configured, PKG_BUILD_DIR will also include the configured sub-directory. The value of LIBFOO_BUILD_SUBDIR does not adjust the value of PKG_BUILD_BASE_DIR.

`PKG_BUILD_DIR`¶

The directory for a specific package’s buildable content.

`PKG_BUILD_OUTPUT_DIR`¶

The directory for where a package’s build output will be stored.

`PKG_CACHE_DIR`¶

The location of the cache directory for a package. If a package defines a fetch from a repository which can be locally cached, this cache directory represents the location where the local cache of content will be held. For example, if a provide defines a Git-based site, a local cache of the Git repository will be stored in this location. Typically, packages should not need to operate on the cache directory except for advanced cases.

`PKG_CACHE_FILE`¶

The location of the cache file for a package. If a package defines a fetch of an archive from a remote source, after the fetch stage is completed, the archive can be found in this location.

For example, if a package defines a site https://www.example.com/test.tgz, the resulting cache file may be <root>/output/dl/test-1.0.tgz.

`PKG_DEFDIR`¶

The package’s definition directory.

For example, for a package test, the definition directory would be <root>/package/test.

`PKG_DEVMODE`¶

Added in version 0.13.

Whether the package is configured for development mode. If a package is configured for development mode, the environment variable will be set to a value of one (i.e. PKG_DEVMODE=1).

`PKG_INTERNAL`¶

Whether or not the package is considered «internal». If internal, the environment variable will be set to a value of one (i.e. PKG_INTERNAL=1).

`PKG_LOCALSRCS`¶

Added in version 0.13.

Whether the package is configured for local-sources mode. If a package is configured for local-sources, the environment variable will be set to a value of one (i.e. PKG_LOCALSRCS=1).

`PKG_NAME`¶

The name of the package.

`PKG_REVISION`¶

The site revision of the package.

`PKG_SITE`¶

The site of the package.

`PKG_VERSION`¶

The version of the package.

`PREFIX`¶

The sysroot prefix for the package. By default, this value is configured to /usr; with the exception of Windows builds where this value is empty by default.

`PREFIXED_HOST_DIR`¶

Added in version 0.12.

The host directory with the prefix applied. An example prefixed directory may be as follows:

<root-dir>/output/host/usr

`PREFIXED_STAGING_DIR`¶

Added in version 0.12.

The staging area directory with the prefix applied. An example prefixed directory may be as follows:

<root-dir>/output/staging/usr

`PREFIXED_TARGET_DIR`¶

Added in version 0.12.

The target area directory with the prefix applied. An example prefixed directory may be as follows:

<root-dir>/output/target/usr

`RELENG_CLEAN`¶

Added in version 0.7.

Flag set if performing a clean request.

`RELENG_DEBUG`¶

Added in version 0.7.

Flag set if debug-related information should be shown.

`RELENG_DEVMODE`¶

Added in version 0.2.

The development mode or flag set if in development mode.

`RELENG_DISTCLEAN`¶

Added in version 0.7.

Flag set if performing an extreme pristine clean request.

`RELENG_EXEC`¶

Added in version 1.4.

Flag set if performing a <pkg>-exec request.

`RELENG_FORCE`¶

Added in version 0.11.

Flag set if performing a forced request from the command line.

`RELENG_LOCALSRCS`¶

Added in version 0.2.

Flag set if in local-sources mode.

`RELENG_MRPROPER`¶

Flag set if performing a pristine clean request.

`RELENG_REBUILD`¶

Flag set if performing a re-build request.

`RELENG_RECONFIGURE`¶

Flag set if performing a re-configuration request.

`RELENG_REINSTALL`¶

Flag set if performing a re-install request.

`RELENG_SCRIPT`¶

Added in version 1.0.

The path of the script currently being executed.

`RELENG_SCRIPT_DIR`¶

Added in version 1.0.

The path of the directory holding the script currently being executed.

`RELENG_TARGET_PKG`¶

Added in version 0.13.

The name of the target package (if any) provided by the command line.

`RELENG_VERBOSE`¶

Added in version 0.7.

Flag set if verbose-related information should be shown.

`RELENG_VERSION`¶

Added in version 0.7.

The version of releng-tool.

`ROOT_DIR`¶

The root directory.

`STAGING_BIN_DIR`¶

Added in version 0.14.

The staging area directory’s prefixed bin directory. An example binary directory may be as follows:

<root-dir>/output/staging/usr/bin

`STAGING_DIR`¶

The staging area directory. By default, this will be a folder staging found inside the configured output directory. For example:

<root-dir>/output/staging

`STAGING_INCLUDE_DIR`¶

Added in version 0.12.

The staging area directory’s prefixed include directory. An example include directory may be as follows:

<root-dir>/output/staging/usr/include

`STAGING_LIB_DIR`¶

Added in version 0.12.

The staging area directory’s prefixed library directory. An example library directory may be as follows:

<root-dir>/output/staging/usr/lib

`SYMBOLS_DIR`¶

The symbols area directory. By default, this will be a folder symbols found inside the configured output directory. For example:

<root-dir>/output/symbols

`TARGET_BIN_DIR`¶

Added in version 0.14.

The target area directory’s prefixed bin directory. An example binary directory may be as follows:

<root-dir>/output/target/usr/bin

`TARGET_DIR`¶

The target area directory. By default, this will be a folder target found inside the configured output directory. For example:

<root-dir>/output/target

`TARGET_INCLUDE_DIR`¶

Added in version 0.12.

The target area directory’s prefixed include directory. An example include directory may be as follows:

<root-dir>/output/target/usr/include

`TARGET_LIB_DIR`¶

Added in version 0.12.

The target area directory’s prefixed library directory. An example library directory may be as follows:

<root-dir>/output/target/usr/lib

Package-specific variables¶

Package-specific environment variables are also available if another package or script needs to rely on the (generated) configuration of another package. For example, if a package LIBFOO existed with a package definition:

LIBFOO_VERSION = '1.0.0'

The environment variable LIBFOO_VERSION with a value of 1.0.0 can be used in other configurations and script files. The following package-specific environment variables are available for use, where <PKG> translates to a releng-tool’s determined package key:

`<PKG>_BUILD_DIR`¶

The directory for a defined package’s buildable content.

For most packages, this path will match the value specified in <PKG>_BUILD_OUTPUT_DIR. For package types that do not support in-tree building (e.g. CMake), this path may be the parent of the value specified in <PKG>_BUILD_OUTPUT_DIR:

└── my-releng-tool-project/
    ├── output/
    │   └── build/
    │       └── libfoo-1.0.0          <---- LIBFOO_BUILD_DIR
    │           └── releng-output     <---- LIBFOO_BUILD_OUTPUT_DIR
    │               └── ...
    ├── package/
    │   └── libfoo/
    │       └── libfoo.rt
    ├── releng-tool.rt
    ...

For cases where a package uses local sources, this path may change to point to the specified local source path. For example, when configured for local-sources mode, the build directory may exist out of the root directory:

└── libfoo/                           <---- LIBFOO_BUILD_DIR
│   └── ...
└── my-releng-tool-project/
    ├── output/
    │   └── build/
    │       └── libfoo-1.0.0          <---- LIBFOO_BUILD_OUTPUT_DIR
    │           └── ...
    ├── package/
    │   └── libfoo/
    │       └── libfoo.rt
    ├── releng-tool.rt
    ...

Or, when using a local VCS type, the path may be set for a folder inside the package’s definition directory:

└── my-releng-tool-project/
    ├── output/
    │   └── build/
    │       └── libfoo-1.0.0          <---- LIBFOO_BUILD_OUTPUT_DIR
    │           └── ...
    ├── package/
    │   └── libfoo/
    │       └── local/                <---- LIBFOO_BUILD_DIR
    │           └── ...
    │       └── libfoo.rt
    ├── releng-tool.rt
    ...

`<PKG>_BUILD_OUTPUT_DIR`¶

The directory for where a defined package’s build output will be stored.

This location is a path is a folder inside the project’s output/build directory. The name is typically a combination of the package’s name and version (e.g. libfoo-1.0.0):

└── my-releng-tool-project/
    ├── output/
    │   └── build/
    │       └── libfoo-1.0.0          <---- LIBFOO_BUILD_OUTPUT_DIR
    │           └── ...
    ├── package/
    │   └── libfoo/
    │       └── libfoo.rt
    ├── releng-tool.rt
    ...

However, if no version is specified for a package, the folder name may just be libfoo:

└── my-releng-tool-project/
    ├── output/
    │   └── build/
    │       └── libfoo                <---- LIBFOO_BUILD_OUTPUT_DIR
    │           └── ...
    ├── package/
    │   └── libfoo/
    │       └── libfoo.rt
    ├── releng-tool.rt
    ...

Note for some package types, the build output directory may be changed to have an additional path (e.g. output/build/libfoo-1.0.0/releng-output) for package types like CMake. For example:

└── my-releng-tool-project/
    ├── output/
    │   └── build/
    │       └── libfoo-1.0.0
    │           └── releng-output     <---- LIBFOO_BUILD_OUTPUT_DIR
    │               └── ...
    ├── package/
    │   └── libfoo/
    │       └── libfoo.rt
    ├── releng-tool.rt
    ...

`<PKG>_DEFDIR`¶

The directory where a defined package’s definition is stored.

For example, if a package libfoo exists, the LIBFOO_DEFDIR environment variable will contain a directory path matching the path seen below:

└── my-releng-tool-project/
    ├── package/
    │   └── libfoo/                   <---- LIBFOO_DEFDIR
    │       └── libfoo.rt
    ├── releng-tool.rt
    ...

`<PKG>_NAME`¶

The name of the package.

For example, if a package libfoo exists, the LIBFOO_NAME environment variable will have a value of libfoo.

`<PKG>_REVISION`¶

The revision of a defined package. If a package does not define a revision, the value used will match the version value (if set). If no version value exists, this variable may be empty.

`<PKG>_VERSION`¶

The version of a defined package. If a package does not define a version, the value used will match the revision value (if set). If no revision value exists, this variable may be empty.

Script-only variables¶

A series a script-only variables are also available at certain stages of releng-tool.

`RELENG_GENERATED_LICENSES`¶

Added in version 1.3.

Defines a list of generated license files at the end of package processing that is available for post-processing actions to use.

`RELENG_GENERATED_SBOMS`¶

Added in version 1.3.

Defines a list of generated software build of materials (SBOM) files at the end of package processing that is available for post-processing actions to use.

Other variables¶

releng-tool also accepts environment variables for configuring specific features of the releng-tool process. The following environment variables are accepted:

`RELENG_ASSETS_DIR=<dir>`¶

Added in version 0.10.

The asset directory to use. The asset directory is the container directory to use for both cache and download content. By default, no asset directory is configured. If a user does not override an asset directory using the --assets-dir argument, the RELENG_ASSETS_DIR can be used as the container directory override for both cache and download content.

`RELENG_CACHE_DIR=<dir>`¶

Added in version 0.10.

The cache directory to use. By default, the cache directory used is configured to <root>/cache. If a user does not override a cache directory using the --cache-dir argument, the RELENG_CACHE_DIR option can be used to override this location.

`RELENG_DL_DIR=<dir>`¶

Added in version 0.10.

The download directory to use. By default, the download directory used is configured to <root>/dl. If a user does not override a download directory using the --dl-dir argument, the RELENG_DL_DIR option can be used to override this location.

`RELENG_GLOBAL_OUTPUT_CONTAINER_DIR=<dir>`¶

Nota

This environment variable is always ignored when either the --out-dir argument or RELENG_OUTPUT_DIR environment variable is used.

Added in version 1.1.

Configures a «global» container directory used to hold the output contents of releng-tool projects. Projects will typically generate output contents inside a project’s <root-dir>/output directory. This can be overridden using the --out-dir argument or RELENG_OUTPUT_DIR environment variable, if a user wishes to generate a build on a different path/partition. While these overrides can help, users managing multiple releng-tool projects will need to tailor a specific output directory value for each project they wish to build. This may be less than ideal if projects typically build in an output folder in a common directory. To help avoid this, this environment variable can be used.

When configuring this option, the default output folder for projects will be set to the provided container directory along with a project’s root directory name:

$RELENG_GLOBAL_OUTPUT_CONTAINER_DIR/<root-directory-name>

This allows a user to build multiple releng-tool projects with output data placed inside a common directory path without needing to explicitly configure a specific output directory each project’s build.

For example, if a user stores multiple projects inside a ~/projects/ path and configures this option to the path /mnt/extern-disk:

export RELENG_GLOBAL_OUTPUT_CONTAINER_DIR=/mnt/extern-disk

The following folder structure should be expected:

├── usr/
│   └── home/
│       └── myuser/
│           └── projects/
│               ├── my-project-a/
│               │   ├── ...
│               │   └── releng-tool.rt
│               └── my-project-b/
│                   ├── ...
│                   └── releng-tool.rt
└── mnt/
    └── extern-disk/
        ├── my-project-a/
        │   └── ...
        └── my-project-b/
            └── ...

`RELENG_IGNORE_RUNNING_AS_ROOT=1`¶

Added in version 0.10.

Suppress the warning generated when running releng-tool with an elevated user.

`RELENG_IGNORE_UNKNOWN_ARGS=1`¶

Added in version 1.3.

Suppress the warning/error generated when running releng-tool with unknown arguments.

`RELENG_OUTPUT_DIR=<dir>`¶

Added in version 1.1.

The output directory to use. By default, the output directory used is configured to <root>/output. If a user does not override an output directory using the --out-dir argument, the RELENG_OUTPUT_DIR option can be used to override this location.

Environment variables¶

Common¶

BUILD_DIR¶

CACHE_DIR¶

DL_DIR¶

HOST_BIN_DIR¶

HOST_DIR¶

HOST_INCLUDE_DIR¶

HOST_LIB_DIR¶

IMAGES_DIR¶

LICENSE_DIR¶

NJOBS¶

NJOBSCONF¶

OUTPUT_DIR¶

PKG_BUILD_BASE_DIR¶

PKG_BUILD_DIR¶

PKG_BUILD_OUTPUT_DIR¶

PKG_CACHE_DIR¶

PKG_CACHE_FILE¶

PKG_DEFDIR¶

PKG_DEVMODE¶

PKG_INTERNAL¶

PKG_LOCALSRCS¶

PKG_NAME¶

PKG_REVISION¶

PKG_SITE¶

PKG_VERSION¶

PREFIX¶

PREFIXED_HOST_DIR¶

PREFIXED_STAGING_DIR¶

PREFIXED_TARGET_DIR¶

RELENG_CLEAN¶

RELENG_DEBUG¶

RELENG_DEVMODE¶

RELENG_DISTCLEAN¶

RELENG_EXEC¶

RELENG_FORCE¶

RELENG_LOCALSRCS¶

RELENG_MRPROPER¶

RELENG_REBUILD¶

RELENG_RECONFIGURE¶

RELENG_REINSTALL¶

RELENG_SCRIPT¶

RELENG_SCRIPT_DIR¶

RELENG_TARGET_PKG¶

RELENG_VERBOSE¶

RELENG_VERSION¶

ROOT_DIR¶

STAGING_BIN_DIR¶

STAGING_DIR¶

STAGING_INCLUDE_DIR¶

STAGING_LIB_DIR¶

SYMBOLS_DIR¶

TARGET_BIN_DIR¶

TARGET_DIR¶

TARGET_INCLUDE_DIR¶

TARGET_LIB_DIR¶

Package-specific variables¶

<PKG>_BUILD_DIR¶

<PKG>_BUILD_OUTPUT_DIR¶

<PKG>_DEFDIR¶

<PKG>_NAME¶

<PKG>_REVISION¶

<PKG>_VERSION¶

Script-only variables¶

RELENG_GENERATED_LICENSES¶

RELENG_GENERATED_SBOMS¶

Other variables¶

RELENG_ASSETS_DIR=<dir>¶

RELENG_CACHE_DIR=<dir>¶

RELENG_DL_DIR=<dir>¶

RELENG_GLOBAL_OUTPUT_CONTAINER_DIR=<dir>¶

RELENG_IGNORE_RUNNING_AS_ROOT=1¶

RELENG_IGNORE_UNKNOWN_ARGS=1¶

RELENG_OUTPUT_DIR=<dir>¶

`BUILD_DIR`¶

`CACHE_DIR`¶

`DL_DIR`¶

`HOST_BIN_DIR`¶

`HOST_DIR`¶

`HOST_INCLUDE_DIR`¶

`HOST_LIB_DIR`¶

`IMAGES_DIR`¶

`LICENSE_DIR`¶

`NJOBS`¶

`NJOBSCONF`¶

`OUTPUT_DIR`¶

`PKG_BUILD_BASE_DIR`¶

`PKG_BUILD_DIR`¶

`PKG_BUILD_OUTPUT_DIR`¶

`PKG_CACHE_DIR`¶

`PKG_CACHE_FILE`¶

`PKG_DEFDIR`¶

`PKG_DEVMODE`¶

`PKG_INTERNAL`¶

`PKG_LOCALSRCS`¶

`PKG_NAME`¶

`PKG_REVISION`¶

`PKG_SITE`¶

`PKG_VERSION`¶

`PREFIX`¶

`PREFIXED_HOST_DIR`¶

`PREFIXED_STAGING_DIR`¶

`PREFIXED_TARGET_DIR`¶

`RELENG_CLEAN`¶

`RELENG_DEBUG`¶

`RELENG_DEVMODE`¶

`RELENG_DISTCLEAN`¶

`RELENG_EXEC`¶

`RELENG_FORCE`¶

`RELENG_LOCALSRCS`¶

`RELENG_MRPROPER`¶

`RELENG_REBUILD`¶

`RELENG_RECONFIGURE`¶

`RELENG_REINSTALL`¶

`RELENG_SCRIPT`¶

`RELENG_SCRIPT_DIR`¶

`RELENG_TARGET_PKG`¶

`RELENG_VERBOSE`¶

`RELENG_VERSION`¶

`ROOT_DIR`¶

`STAGING_BIN_DIR`¶

`STAGING_DIR`¶

`STAGING_INCLUDE_DIR`¶

`STAGING_LIB_DIR`¶

`SYMBOLS_DIR`¶

`TARGET_BIN_DIR`¶

`TARGET_DIR`¶

`TARGET_INCLUDE_DIR`¶

`TARGET_LIB_DIR`¶

`<PKG>_BUILD_DIR`¶

`<PKG>_BUILD_OUTPUT_DIR`¶

`<PKG>_DEFDIR`¶

`<PKG>_NAME`¶

`<PKG>_REVISION`¶

`<PKG>_VERSION`¶

`RELENG_GENERATED_LICENSES`¶

`RELENG_GENERATED_SBOMS`¶

`RELENG_ASSETS_DIR=<dir>`¶

`RELENG_CACHE_DIR=<dir>`¶

`RELENG_DL_DIR=<dir>`¶

`RELENG_GLOBAL_OUTPUT_CONTAINER_DIR=<dir>`¶

`RELENG_IGNORE_RUNNING_AS_ROOT=1`¶

`RELENG_IGNORE_UNKNOWN_ARGS=1`¶

`RELENG_OUTPUT_DIR=<dir>`¶