[PATCH] docs: command-line: Clarify environment variable handling

[Yasushi SHOJI]

Explain that kas does not inherit the full host shell environment by
default, but instead constructs a controlled build environment to
improve reproducibility and reduce host contamination.

Also clarify that handling of additional environment variables depends
on their scope and on the selected sub-command. Where supported, they
can be defined in the kas configuration or preserved explicitly from
the host environment, for example with -E/--preserve-env.

Signed-off-by: Yasushi SHOJI <ya...@spacecubics.com>
---

Hi Jan,

This patch is for GitHub issue #178. I hope this looks good to you.

I would also move the "Command Line Usage" page under "User Guide" so
that the order becomes:

1. Getting Started
2. Command Line Usage
3. Sub-commands

This way, readers can learn about environment variables before getting
into the details of sub-command and configurations.

If you want, I can send that change as well.

Best,
--
yashi


docs/command-line/environment-variables.inc | 9 +++++++++
1 file changed, 9 insertions(+)

diff --git a/docs/command-line/environment-variables.inc b/docs/command-line/environment-variables.inc
index 62d366d..e7141d0 100644
--- a/docs/command-line/environment-variables.inc
+++ b/docs/command-line/environment-variables.inc
@@ -2,6 +2,15 @@ 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
+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``.
+
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``
--
2.53.0

[Jan Kiszka]

"Note that preserving environment variables across `kas-container` is
further limited, primarily due to different directory layouts."

> +
> 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``
> --
> 2.53.0

Sounds good to me otherwise.

Thanks,
Jan

--
Siemens AG, Foundational Technologies
Linux Expert Center

[Yasushi SHOJI]

Explain that kas does not inherit the full host shell environment by
default, but instead constructs a controlled build environment to
improve reproducibility and reduce host contamination.

Also clarify that handling of additional environment variables depends
on their scope and on the selected sub-command. Where supported, they
can be defined in the kas configuration or preserved explicitly from
the host environment, for example with -E/--preserve-env.

Signed-off-by: Yasushi SHOJI <ya...@spacecubics.com>
---

docs/command-line/environment-variables.inc | 13 +++++++++++++
1 file changed, 13 insertions(+)

diff --git a/docs/command-line/environment-variables.inc b/docs/command-line/environment-variables.inc
index 62d366d..915aa32 100644
--- a/docs/command-line/environment-variables.inc
+++ b/docs/command-line/environment-variables.inc
@@ -2,6 +2,19 @@ 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.

[Jan Kiszka]

Thanks, applied.