feat: env-var for additional interpreter args in bootstrap stage 1 (#2654)
There is no means to be able to provide additional interpreter arguments
to the `bash`-based stage 1 bootstrap system at launch time.
The Intelli-J / Bazel plugin typically launches a `py_*` rule build
product with something like this (abridged) using a Python interpreter
from the local environment;
```
python3 /path/to/pydev/pydevd.py --client 127.0.0.1 --port 12344 --file /path/to/built/python-file
```
When the `bash`-based bootstrap process is used, this mechanism not
longer works. This PR will mean that a potential future Intelli-j /
Bazel plugin version may be able to launch the build product differently
and inject additional interpreter arguments so that the debug system can
be stood up in this sort of a way;
```
RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS="/path/to/pydev/pydevd.py --client 127.0.0.1 --port 12344 --file" /path/to/bash-bootstrap-stage1-script
```
The work to support this in the Intelli-J / Bazel plugin has not been
done; it would have to be undertaken some time after this change were
available.
---------
Co-authored-by: Ignas Anikevicius <240938+aignas@users.noreply.github.com>
Co-authored-by: Richard Levasseur <rlevasseur@google.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
index dc24193..15fb211 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -94,6 +94,9 @@
* (rules) APIs for creating custom rules based on the core py_binary, py_test,
and py_library rules
([#1647](https://github.com/bazelbuild/rules_python/issues/1647))
+* (rules) Added env-var to allow additional interpreter args for stage1 bootstrap.
+ See {obj}`RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS` environment variable.
+ Only applicable for {obj}`--bootstrap_impl=script`.
* (rules) Added {obj}`interpreter_args` attribute to `py_binary` and `py_test`,
which allows pass arguments to the interpreter before the regular args.
diff --git a/docs/environment-variables.md b/docs/environment-variables.md
index d50070a..c7c0181 100644
--- a/docs/environment-variables.md
+++ b/docs/environment-variables.md
@@ -1,5 +1,33 @@
# Environment Variables
+::::{envvar} RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS
+
+This variable allows for additional arguments to be provided to the Python interpreter
+at bootstrap time when the `bash` bootstrap is used. If
+`RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS` were provided as `-Xaaa`, then the command
+would be;
+
+```
+python -Xaaa /path/to/file.py
+```
+
+This feature is likely to be useful for the integration of debuggers. For example,
+it would be possible to configure the `RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS` to
+be set to `/path/to/debugger.py --port 12344 --file` resulting
+in the command executed being;
+
+```
+python /path/to/debugger.py --port 12345 --file /path/to/file.py
+```
+
+:::{seealso}
+The {bzl:obj}`interpreter_args` attribute.
+:::
+
+:::{versionadded} VERSION_NEXT_FEATURE
+
+::::
+
:::{envvar} RULES_PYTHON_BOOTSTRAP_VERBOSE
When `1`, debug information about bootstrapping of a program is printed to
diff --git a/python/private/py_executable.bzl b/python/private/py_executable.bzl
index d190544..bbaed31 100644
--- a/python/private/py_executable.bzl
+++ b/python/private/py_executable.bzl
@@ -98,6 +98,10 @@
Only supported for {obj}`--bootstrap_impl=script`. Ignored otherwise.
:::
+:::{seealso}
+The {obj}`RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS` environment variable
+:::
+
:::{versionadded} VERSION_NEXT_FEATURE
:::
""",
diff --git a/python/private/stage1_bootstrap_template.sh b/python/private/stage1_bootstrap_template.sh
index 523210a..bd142cf 100644
--- a/python/private/stage1_bootstrap_template.sh
+++ b/python/private/stage1_bootstrap_template.sh
@@ -202,6 +202,7 @@
declare -a interpreter_env
declare -a interpreter_args
+declare -a additional_interpreter_args
# Don't prepend a potentially unsafe path to sys.path
# See: https://docs.python.org/3.11/using/cmdline.html#envvar-PYTHONSAFEPATH
@@ -220,6 +221,12 @@
interpreter_args+=("-XRULES_PYTHON_ZIP_DIR=$zip_dir")
fi
+if [[ -n "${RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS}" ]]; then
+ read -a additional_interpreter_args <<< "${RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS}"
+ interpreter_args+=("${additional_interpreter_args[@]}")
+ unset RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS
+fi
+
export RUNFILES_DIR
command=(
