kas uses a number of environment variables to configure its behavior.
The `Variables Glossary`_ provides an overview, wherein the tuple (C,K,E)
denotes the scope of the variable.

By default, kas does not inherit the full host shell environment into the
build environment. Instead, kas constructs a controlled environment to
improve reproducibility and reduce host contamination.

How additional environment variables are handled depends on their scope and
on the selected sub-command. Where supported, variables can be defined in the
kas configuration or preserved explicitly from the host environment, for
example with ``-E/--preserve-env``.

When using ``kas-container``, this is more limited, especially for variables
that contain file or directory paths, because the container may use a
different directory layout.

All directories that are passed to kas by setting the corresponding
environment variables (e.g. ``KAS_WORK_DIR``, ``KAS_BUILD_DIR``, ...) must
not overlap with each other, except for overlapping with ``KAS_WORK_DIR``
(i.e. the build|sstate|downloads|repo-ref dirs can be below the work dir).
Environment variables that reference a file or directory must have a valid
path that is accessible and readable.

Variable Scope
~~~~~~~~~~~~~~

**kas-container (C)**

The variable is processed or forwarded by the ``kas-container`` script.
For some variables, the variable is re-written to the container's
directory layout.

.. note::
    The ``env`` section of the `project configuration` can be used to make
    arbitrary environment variables available to the build environment. When
    invoking the build via ``kas-container``, make sure to also forward the
    corresponding environment variables into the container.

**kas (K)**

The variable is processed by kas itself. Some variables (e.g. the credentials
for the awscli) are re-written to configuration files to also support older
versions of the tooling.

**build environment (E)**

The variable is exported into the build environment. In this environment, the
``bitbake`` command is executed.

**config-file (c)**

The variable can be set in the ``env`` section of the
:ref:`project-configuration-label`. Note, that a value provided by the calling
environment takes precedence over the value in the configuration file.

Variables Glossary
~~~~~~~~~~~~~~~~~~

These environment variables are processed before the configuration file is
read (except if stated otherwise). By that, they cannot be defined or
overwritten using the ``env`` section of the config file.

+--------------------------+--------------------------------------------------+
| Environment variables    | Description                                      |
+==========================+==================================================+
| ``KAS_WORK_DIR``         | The path of the kas work directory, current work |
| (C, K)                   | directory is the default. This directory must    |
|                          | exist if set.                                    |
+--------------------------+--------------------------------------------------+
| ``KAS_BUILD_DIR``        | The path of the build directory,                 |
| (C, K)                   | ``${KAS_WORK_DIR}/build`` is the default.        |
|                          | The parent directory must exist if set.          |
|                          | kas adds a ``CACHEDIR.TAG``.                     |
+--------------------------+--------------------------------------------------+
| ``KAS_REPO_REF_DIR``     | The path to the repository reference directory.  |
| (C, K)                   | Repositories in this directory are used as       |
|                          | references when cloning. In order for kas to     |
|                          | find those repositories, they have to be named   |
|                          | in a specific way. The repo URLs are translated  |
|                          | like this:                                       |
|                          | ``https://github.com/siemens/meta-iot2000.git``  |
|                          | resolves to the name                             |
|                          | ``github.com.siemens.meta-iot2000.git``.         |
|                          | Repositories that are not found will be cloned   |
|                          | below this directory. Multiple instances of kas  |
|                          | can simultaneously work on the same directory,   |
|                          | as long as the underlying filesystem is POSIX    |
|                          | compatible. This directory must exist if set.    |
+--------------------------+--------------------------------------------------+
| ``KAS_DISTRO``           | This overwrites the respective setting in the    |
| ``KAS_MACHINE``          | configuration file.                              |
| ``KAS_TARGET``           |                                                  |
| ``KAS_TASK``             |                                                  |
| (C, K)                   |                                                  |
+--------------------------+--------------------------------------------------+
| ``KAS_PREMIRRORS``       | Specifies alternatives for repo URLs. Just like  |
| (C, K)                   | bitbake ``PREMIRRORS``, this variable consists   |
|                          | of new-line separated entries. Each entry        |
|                          | defines a regular expression to match a URL and, |
|                          | space-separated, its replacement. E.g.:          |
|                          | ``http://.*\.someurl\.io/                        |
|                          | http://localmirror.net/``                        |
+--------------------------+--------------------------------------------------+
| ``DISTRO_APT_PREMIRRORS``| Specifies alternatives for apt URLs. Just like   |
| (C,c)                    | ``KAS_PREMIRRORS``.                              |
+--------------------------+--------------------------------------------------+
| ``KAS_CLONE_DEPTH``      | Perform shallow git clone/fetch using --depth=N  |
| (C, K)                   | specified by this variable. This is useful in    |
|                          | case CI always starts with empty work directory  |
|                          | and this directory is always discarded after the |
|                          | CI run.                                          |
+--------------------------+--------------------------------------------------+
| ``SSH_PRIVATE_KEY``      | Variable containing the private key that should  |
| (K)                      | be added to an internal ssh-agent. This key      |
|                          | cannot be password protected. This setting is    |
|                          | useful for CI build servers. On desktop          |
|                          | machines, an ssh-agent running outside the kas   |
|                          | environment is more useful.                      |
+--------------------------+--------------------------------------------------+
| ``SSH_PRIVATE_KEY_FILE`` | Path to the private key file that should be      |
| (K)                      | added to an internal ssh-agent. This key cannot  |
|                          | be password protected. This setting is useful    |
|                          | for CI build servers. On desktop machines, an    |
|                          | ssh-agent running outside the kas environment is |
|                          | more useful.                                     |
+--------------------------+--------------------------------------------------+
| ``SSH_AUTH_SOCK``        | SSH authentication socket. Used for cloning over |
| (C,K,E)                  | SSH (alternative to ``SSH_PRIVATE_KEY`` or       |
|                          | ``SSH_PRIVATE_KEY_FILE``).                       |
+--------------------------+--------------------------------------------------+
| ``DL_DIR``               | Environment variables that are transferred to    |
| ``SSTATE_DIR``           | the bitbake environment. The ``DL_DIR``,         |
| ``SSTATE_MIRRORS``       | ``SSTATE_DIR`` and ``BB_HASHSERVE_DB_DIR``       |
| ``BB_HASHSERVE_DB_DIR``  | directories are created along with their         |
| ``BB_HASHSERVE``         | parents, if set.                                 |
| ``BB_HASHSERVE_UPSTREAM``|                                                  |
| (C,K,E,c)                |                                                  |
+--------------------------+--------------------------------------------------+
| ``TMPDIR`` (K,E,c)       | Directory for temporary files.                   |
+--------------------------+--------------------------------------------------+
| ``http_proxy``           | These variables define the proxy configuration   |
| ``https_proxy``          | bitbake should use.                              |
| ``ftp_proxy``            |                                                  |
| ``no_proxy``             |                                                  |
| (C,K,E)                  |                                                  |
+--------------------------+--------------------------------------------------+
| ``GIT_PROXY_COMMAND`` (E)| Set proxy for native git fetches. ``NO_PROXY``   |
| ``NO_PROXY`` (C,K,E)     | is evaluated by OpenEmbedded's oe-git-proxy      |
|                          | script.                                          |
+--------------------------+--------------------------------------------------+
| ``SHELL``                | The shell to start when using the ``shell``      |
| (C,K,E)                  | command and in the bitbake environment.          |
+--------------------------+--------------------------------------------------+
| ``TERM``                 | The terminal options used in the ``shell``       |
| (C,K,E)                  | command and in the bitbake environment.          |
+--------------------------+--------------------------------------------------+
| ``TZ`` (C)               | Timezone settings.                               |
+--------------------------+--------------------------------------------------+
| ``AWS_CONFIG_FILE``      | Path to the awscli configuration and credentials |
| |aws_cred|               | files that are copied to the kas home dir.       |
| (K,C)                    |                                                  |
+--------------------------+--------------------------------------------------+
| |git_cred|               | Allows one to set and configure the git          |
| (K,C)                    | credential helper in the `.gitconfig` of the kas |
|                          | user.                                            |
+--------------------------+--------------------------------------------------+
| |kas_git_cred_store|     | Path to a git credential store file on the host. |
| (C)                      | When set, the file is bind-mounted into the      |
|                          | container (read-only) and the git credential     |
|                          | store helper is configured to use it.            |
|                          | Equivalent to ``--git-credential-store``.        |
+--------------------------+--------------------------------------------------+
| |kas_git_cred_socket|    | Path to the git credential cache daemon socket   |
| (C)                      | on the host. When set, the socket is             |
|                          | bind-mounted into the container and the git      |
|                          | credential cache helper is configured to use it. |
|                          | Equivalent to ``--git-credential-socket``.       |
+--------------------------+--------------------------------------------------+
| ``GITCONFIG_FILE``       | Path to a `.gitconfig` file which will be        |
| (K,C)                    | copied to the kas home dir as `.gitconfig`.      |
+--------------------------+--------------------------------------------------+
| ``NETRC_FILE``           | Path to a .netrc file which will be copied to    |
| (K,C)                    | the kas home dir as .netrc.                      |
+--------------------------+--------------------------------------------------+
| ``NPMRC_FILE``           | Path to a .npmrc file which will be copied to    |
| (K,C)                    | the kas home dir as .npmrc.                      |
+--------------------------+--------------------------------------------------+
| ``REGISTRY_AUTH_FILE``   | Path to a container registry authentication file.|
| (K,C)                    |                                                  |
+--------------------------+--------------------------------------------------+
| |ci_server_vars|         | Environment variables from GitLab CI, if set     |
| ``CI_JOB_TOKEN``         | .netrc is configured to allow fetching from      |
| ``CI_JOB_URL``           | the GitLab instance. An entry will be appended   |
| ``CI_REGISTRY``          | in case ``NETRC_FILE`` was given as well. Note   |
| ``CI_REGISTRY_USER``     | that if the file already contains an entry for   |
| (K)                      | that host most tools would probably take that    |
|                          | first one. The job URL is added to the           |
|                          | provenance attestation (if enabled).             |
|                          | If ``CI_REGISTRY`` and ``CI_REGISTRY_USER`` is   |
|                          | also set, a container registry login file is     |
|                          | created, which is used by docker, podman and     |
|                          | skopeo. In case ``REGISTRY_AUTH_FILE`` was given |
|                          | as well, the CI login data will be appended to   |
|                          | that file.                                       |
|                          | The required base64 encoded login data is        |
|                          | generated by kas.                                |
+--------------------------+--------------------------------------------------+
| ``GITHUB_ACTIONS``       | Environment variables from GitHub actions or     |
| ``GITLAB_CI``            | GitLab CI. If set to `true`, `.gitconfig` is     |
| (K)                      | automatically imported.                          |
|                          | For details, see ``GITCONFIG_FILE``.             |
+--------------------------+--------------------------------------------------+
| ``REMOTE_CONTAINERS`` (K)| Environment variables related to VSCode Remote   |
| ``REMOTE_CONTAINERS_<x>``| Containers. If running in this environment,      |
| (K,E)                    | `.gitconfig` is automatically imported.          |
+--------------------------+--------------------------------------------------+
| ``BB_NUMBER_THREADS``    | Environment variables to control the concurrency.|
| ``PARALLEL_MAKE``        |                                                  |
| (C,K,E)                  |                                                  |
+--------------------------+--------------------------------------------------+
| ``KAS_IMAGE_VERSION`` (C)| Select the version of the (official) kas         |
|                          | container (e.g. 4.5).                            |
+--------------------------+--------------------------------------------------+
| |container-distro| (C)   | Select the base distro and its release of the    |
|                          | container image (e.g. ``debian-bookworm``).      |
|                          | If not specified, the default (most-recent       |
|                          | supported) distro version is used.               |
+--------------------------+--------------------------------------------------+
| ``KAS_CONTAINER_IMAGE``  | Select the container image (full OCI path        |
| (C)                      | including tag).                                  |
+--------------------------+--------------------------------------------------+
| ``KAS_CONTAINER_ENGINE`` | Explicitly set the container engine (either      |
| (C)                      | ``docker`` or ``podman``). If not set, this is   |
|                          | auto-detected (preference: docker).              |
+--------------------------+--------------------------------------------------+
| ``KAS_SUDO_CMD``         | Explicitly set the sudo command (either ``sudo`` |
| (C)                      | or ``run0``) for operations that require higher  |
|                          | privileges. If not set, this is auto-detected    |
|                          | (preference: ``sudo``). Note, that ``run0`` does |
|                          | not preserve the environment and cannot setup    |
|                          | loopback devices.                                |
+--------------------------+--------------------------------------------------+
| ``KAS_BUILDTOOLS_DIR``   | Explicitly set the path where kas will download  |
| (C,K)                    | and install buildtools. If not set, kas will use |
|                          | ``KAS_BUILD_DIR/buildtools`` as the default path.|
+--------------------------+--------------------------------------------------+
| NO_COLOR (C,K,E)         | Prevents the addition of ANSI color to all output|
|                          | when this variable has a non-empty value.        |
+--------------------------+--------------------------------------------------+

.. |aws_cred| replace:: ``AWS_ROLE_ARN``
                        ``AWS_SHARED_CREDENTIALS_FILE``
                        ``AWS_WEB_IDENTITY_TOKEN_FILE``
.. |git_cred| replace:: ``GIT_CREDENTIAL_HELPER``
                        ``GIT_CREDENTIAL_USEHTTPPATH``
.. |kas_git_cred_store| replace:: ``KAS_GIT_CREDENTIAL_STORE``
.. |kas_git_cred_socket| replace:: ``KAS_GIT_CREDENTIAL_SOCKET``
.. |ci_server_vars| replace:: ``CI_SERVER_HOST``
                              ``CI_SERVER_PORT``
                              ``CI_SERVER_PROTOCOL``
                              ``CI_SERVER_SHELL_SSH_HOST``
                              ``CI_SERVER_SHELL_SSH_PORT``
.. |container-distro| replace:: ``KAS_CONTAINER_IMAGE_DISTRO``

.. only:: html

    For details about the access of remote resources, see
    :ref:`checkout-creds-label`.
