[PATCH 1/1] docs: precisely describe where SHELL env var is in effect

[Felix Moessbauer]

Previously the documentation states that both the SHELL and TERM
variables are only forwarded into the kas shell plugin. This was not
true as they are always forwarded into the bitbake environment (but not
into the bitbake setup script). While this does not matter for normal
bitbake task execution (which is always executed under /bin/sh), it
does matter for the execution of the devshell.

We now align the documentation with the implementation and precisely
state into which environments the variables are forwarded.

No functional change.

Signed-off-by: Felix Moessbauer <felix.mo...@siemens.com>
---
Changes since RFC 1:

- do not change implementation, but align documentation with current implementation
- add new reasoning to commit message

Felix

docs/command-line/environment-variables.inc | 9 +++++----
kas/plugins/shell.py | 4 +++-
2 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/docs/command-line/environment-variables.inc b/docs/command-line/environment-variables.inc
index 875f4b343..c2127c271 100644
--- a/docs/command-line/environment-variables.inc
+++ b/docs/command-line/environment-variables.inc
@@ -132,11 +132,12 @@ overwritten using the ``env`` section of the config file.
| ``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) | plugin. |
+| ``SHELL`` | The shell to start when using the ``shell`` |
+| (C,K,E) | plugin and in the bitbake environment (only |
+| | relevant for the devshell task). |
+--------------------------+--------------------------------------------------+
-| ``TERM`` | The terminal options used in the `shell` plugin. |
-| (C,K,E) | |
+| ``TERM`` | The terminal options used in the ``shell`` |
+| (C,K,E) | plugin and in the bitbake environment. |
+--------------------------+--------------------------------------------------+
| ``TZ`` (C) | Timezone settings. |
+--------------------------+--------------------------------------------------+
diff --git a/kas/plugins/shell.py b/kas/plugins/shell.py
index 802f69e68..8fe1f36bc 100644
--- a/kas/plugins/shell.py
+++ b/kas/plugins/shell.py
@@ -25,7 +25,9 @@
When this command is executed, kas will checkout repositories, setup the
build environment and then start a shell in the build environment. This
can be used to manually run ``bitbake`` with custom command line options
- or to execute other commands such as ``runqemu``.
+ or to execute other commands such as ``runqemu``. The ``SHELL`` environment
+ variable is inherited from the calling environment and controls which shell
+ is started.

For example, to start a shell in the build environment for the file
``kas-project.yml`` you could run::
--
2.50.0

[Jan Kiszka]

I think mentioning explicitly the bitbake tasks that may fall into a
shell will not scale. There e.g. also the UserResolver for
non-applicable patches, and I bet there is even more in OE that we
forget right now.

Jan

> +--------------------------+--------------------------------------------------+
> -| ``TERM`` | The terminal options used in the `shell` plugin. |
> -| (C,K,E) | |
> +| ``TERM`` | The terminal options used in the ``shell`` |
> +| (C,K,E) | plugin and in the bitbake environment. |
> +--------------------------+--------------------------------------------------+
> | ``TZ`` (C) | Timezone settings. |
> +--------------------------+--------------------------------------------------+
> diff --git a/kas/plugins/shell.py b/kas/plugins/shell.py
> index 802f69e68..8fe1f36bc 100644
> --- a/kas/plugins/shell.py
> +++ b/kas/plugins/shell.py
> @@ -25,7 +25,9 @@
> When this command is executed, kas will checkout repositories, setup the
> build environment and then start a shell in the build environment. This
> can be used to manually run ``bitbake`` with custom command line options
> - or to execute other commands such as ``runqemu``.
> + or to execute other commands such as ``runqemu``. The ``SHELL`` environment
> + variable is inherited from the calling environment and controls which shell
> + is started.
>
> For example, to start a shell in the build environment for the file
> ``kas-project.yml`` you could run::


--

Siemens AG, Foundational Technologies
Linux Expert Center

[Felix Moessbauer]

Previously the documentation states that both the SHELL and TERM
variables are only forwarded into the kas shell plugin. This was not
true as they are always forwarded into the bitbake environment (but not
into the bitbake setup script). While this does not matter for normal
bitbake task execution (which is always executed under /bin/sh), it
does matter for the execution of the devshell.

We now align the documentation with the implementation and precisely
state into which environments the variables are forwarded.

No functional change.

Signed-off-by: Felix Moessbauer <felix.mo...@siemens.com>
---

Changes since v1:

- be more generic and just state that the variables are exported
into the bitbake environment.

Changes since RFC 1:

- do not change implementation, but align documentation with current implementation
- add new reasoning to commit message

Felix

docs/command-line/environment-variables.inc | 8 ++++----
kas/plugins/shell.py | 4 +++-
2 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/docs/command-line/environment-variables.inc b/docs/command-line/environment-variables.inc
index 875f4b343..3ed26603a 100644
--- a/docs/command-line/environment-variables.inc
+++ b/docs/command-line/environment-variables.inc
@@ -132,11 +132,11 @@ overwritten using the ``env`` section of the config file.

| ``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) | plugin. |
+| ``SHELL`` | The shell to start when using the ``shell`` |

+| (C,K,E) | plugin and in the bitbake environment. |

+--------------------------+--------------------------------------------------+
-| ``TERM`` | The terminal options used in the `shell` plugin. |
-| (C,K,E) | |
+| ``TERM`` | The terminal options used in the ``shell`` |
+| (C,K,E) | plugin and in the bitbake environment. |
+--------------------------+--------------------------------------------------+
| ``TZ`` (C) | Timezone settings. |
+--------------------------+--------------------------------------------------+
diff --git a/kas/plugins/shell.py b/kas/plugins/shell.py
index 802f69e68..8fe1f36bc 100644
--- a/kas/plugins/shell.py
+++ b/kas/plugins/shell.py
@@ -25,7 +25,9 @@
When this command is executed, kas will checkout repositories, setup the
build environment and then start a shell in the build environment. This
can be used to manually run ``bitbake`` with custom command line options
- or to execute other commands such as ``runqemu``.
+ or to execute other commands such as ``runqemu``. The ``SHELL`` environment
+ variable is inherited from the calling environment and controls which shell
+ is started.

For example, to start a shell in the build environment for the file
``kas-project.yml`` you could run::
--

2.50.0

[Jan Kiszka]

Thanks, applied.

Jan