Environment variables
---------------------

.. tip::

    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.

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

.. list-table::
    :widths: auto

    * - ``BUILD_DIR``

      - The build directory.

    * - ``CACHE_DIR``

      - The cache directory.

    * - ``DL_DIR``

      - The download directory.

    * - ``HOST_DIR``

      - The host directory.

    * - ``HOST_INCLUDE_DIR``

      - The host directory's prefixed include directory.

    * - ``HOST_LIB_DIR``

      - The host directory's prefixed library directory.

    * - ``IMAGES_DIR``

      - The images directory.

    * - ``LICENSE_DIR``

      - The licenses directory.

        See also `licenses`_.

    * - .. _CONF_NJOBS:

        ``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``).

    * - .. _CONF_NJOBSCONF:

        ``NJOBSCONF``

      - Number of jobs to allow at a given time. Unlike |CONF_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 |CONF_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.

    * - .. _CONF_PKG_BUILD_BASE_DIR:

        ``PKG_BUILD_BASE_DIR``

      - The directory for a specific package's base directory for buildable
        content. In most cases, this value will be the same as
        |CONF_PKG_BUILD_DIR|_; however, if |LIBFOO_BUILD_SUBDIR|_ is
        configured, |CONF_PKG_BUILD_DIR|_ will include the configured
        sub-directory, where this base directory will not.

        See also |CONF_PKG_BUILD_DIR|_.

    * - .. _CONF_PKG_BUILD_DIR:

        ``PKG_BUILD_DIR``

      - The directory for a specific package's buildable content.

        See also |CONF_PKG_BUILD_BASE_DIR|_ and  |CONF_PKG_BUILD_ODIR|_.

    * - .. _CONF_PKG_BUILD_ODIR:

        ``PKG_BUILD_OUTPUT_DIR``

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

        See also |CONF_PKG_BUILD_DIR|_.

    * - ``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``

      - 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``).

        See also :ref:`development mode <development mode>`.

    * - ``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``).

        See also `internal and external packages`_.

    * - ``PKG_LOCALSRCS``

      - 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``).

        See also :ref:`local-sources mode <local-sources mode>`.

    * - ``PKG_NAME``

      - The name of the package.

    * - ``PKG_REVISION``

      - The site revision of the package.

        See also |LIBFOO_REVISION|_.

    * - ``PKG_SITE``

      - The site of the package.

        See also |LIBFOO_SITE|_.

    * - ``PKG_VERSION``

      - The version of the package.

        See also |LIBFOO_VERSION|_.

    * - ``PREFIX``

      - The sysroot prefix for the package.

    * - ``PREFIXED_HOST_DIR``

      - The host directory with the prefix applied.

    * - ``PREFIXED_STAGING_DIR``

      - The staging area directory with the prefix applied.

    * - ``PREFIXED_TARGET_DIR``

      - The target area directory with the prefix applied.

    * - ``RELENG_CLEAN``

      - Flag set if performing a clean request.

    * - ``RELENG_DEBUG``

      - Flag set if debug-related information should be shown.

    * - ``RELENG_DEVMODE``

      - The development mode or flag set if in
        :ref:`development mode <development mode>`.

    * - ``RELENG_DISTCLEAN``

      - Flag set if performing an extreme pristine clean request.

    * - ``RELENG_FORCE``

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

    * - ``RELENG_LOCALSRCS``

      - Flag set if in :ref:`local-sources mode <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_TARGET_PKG``

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

    * - ``RELENG_VERBOSE``

      - Flag set if verbose-related information should be shown.

    * - ``RELENG_VERSION``

      - The version of releng-tool.

    * - ``ROOT_DIR``

      - The root directory.

    * - ``STAGING_DIR``

      - The staging area directory.

    * - ``STAGING_INCLUDE_DIR``

      - The staging area directory's prefixed include directory.

    * - ``STAGING_LIB_DIR``

      - The staging area directory's prefixed library directory.

    * - ``SYMBOLS_DIR``

      - The symbols area directory.

    * - ``TARGET_DIR``

      - The target area directory.

    * - ``TARGET_INCLUDE_DIR``

      - The target area directory's prefixed include directory.

    * - ``TARGET_LIB_DIR``

      - The target area directory's prefixed library directory.

.. |CONF_NJOBSCONF| replace:: ``NJOBSCONF``
.. |CONF_NJOBS| replace:: ``NJOBS``
.. |CONF_PKG_BUILD_BASE_DIR| replace:: ``PKG_BUILD_BASE_DIR``
.. |CONF_PKG_BUILD_DIR| replace:: ``PKG_BUILD_DIR``
.. |CONF_PKG_BUILD_ODIR| replace:: ``PKG_BUILD_OUTPUT_DIR``

Package-specific environment variables are also available if another package or
script needs to rely on the (generated) configuration of another package. The
following package-specific environment variables are available for use (where
``<PKG>`` translates to a releng-tool's determined package key):

.. list-table::
    :widths: auto

    * - ``<PKG>_BUILD_DIR``

      - The directory for a defined package's buildable content.

    * - ``<PKG>_BUILD_OUTPUT_DIR``

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

    * - ``<PKG>_DEFDIR``

      - The directory where a defined package's definition is stored.

    * - ``<PKG>_NAME``

      - The name of the package.

    * - ``<PKG>_REVISION``

      - The revision of a defined package.

    * - ``<PKG>_VERSION``

      - The version of a defined package.

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

.. list-table::
    :widths: auto

    * - ``RELENG_ASSETS_DIR=<dir>``

      - The asset directory to use.

    * - ``RELENG_CACHE_DIR=<dir>``

      - The cache directory to use.

    * - ``RELENG_DL_DIR=<dir>``

      - The download directory to use.

    * - ``RELENG_IGNORE_RUNNING_AS_ROOT=1``

      - Suppress the warning generated when running releng-tool with a
        root user.
