Implement run-time Python interpreter searching #284

chrisnovakovic · 2025-12-01T17:27:42Z

There is currently an assumption that the Python interpreter used while building .pex files (i.e. the value of DefaultInterpreter) is also the Python interpreter that runs them. This can be overridden with the shebang parameter on individual python_binary and python_test targets, which sets the shebang in the generated .pex file to a specific value. The functionality this provides is limited:

If additional interpreter arguments are specified by the target, the generated .pex file will depend on a shell at /bin/sh in the run-time environment (which isn't guaranteed to exist, e.g. in distroless containers), as well as /usr/bin/env (also not guaranteed to exist).
It is possible to build the .pex file using a Python interpreter defined as a build target in the repo, but it isn't possible to run the .pex file using that interpreter because the .pex file's shebang is (by definition) static, but the interpreter's path relative to the .pex file's path varies depending on the context (e.g. whether the .pex file exists inside a build environment vs outside of one). This was discussed in CI: temporarily remove in-repo Python tests #247.

Provide more flexibility in how .pex files are run by prepending a native-code preamble that implements dynamic searching of Python interpreters. The behaviour of this preamble is controlled at run time by a special zip member within the .pex file,
.bootstrap/PLZ_PREAMBLE_CONFIG, which contains a list of candidate paths for Python interpreters under which the .pex file should be executed and a list of arguments to pass to the interpreter when attempting to execute it. The lists can be customised per python_binary or python_test target via the runtime_interpreters and runtime_interpreter_args parameters respectively; new plugin configuration options, DefaultRuntimeInterpreters and DefaultRuntimeInterpreterArgs, provide default values. If both are unspecified, the plugin's current behaviour is maintained (i.e. the same interpreter is used to both build and run the code). The flexibility offered by the new .pex preamble is sufficient to be able to remove python_binary and python_test's shebang parameter (and the DefaultShebang plugin configuration option) altogether.

The new .pex preamble is compact enough to prepend to all .pex files in a repo without collectively making them prohibitively large: ~98KB statically linked with musl on Linux, ~83KB dynamically linked on Darwin (which doesn't have a stable kernel ABI, and strongly discourages static linking).

Among other possibilities, this allows for the creation of .pex files that are truly portable between run-time environments of the same operating system and architecture - e.g., the preamble can be configured to attempt to execute an interpreter that only exists within a production environment (such as a distroless container with its interpreter at /python/bin/python3), falling back on an interpreter defined as a build target in the repo if the .pex file is still located within Please's development/testing environment.

.github/workflows/plugin_test.yaml

chrisnovakovic · 2025-12-01T17:36:03Z

.github/workflows/plugin_test.yaml

  test:
    name: Run tests
    runs-on: ${{ (inputs.platform == 'freebsd_amd64' || inputs.platform == 'linux_amd64') && 'ubuntu-24.04' || (inputs.platform == 'linux_arm64' && 'ubuntu-24.04-arm' || (inputs.platform == 'darwin_amd64' && 'macos-15-intel' || (inputs.platform == 'darwin_arm64' && 'macos-15' || 'unknown'))) }}
    steps:


The proof that all of this works is in the "in-repo please_pex tool" test matrix passing - the others will fail because they use the build defs from this PR but the older stable version of please_pex, which is missing features added by this PR. The GHA workflow is now structured in such a way that only the "in-repo please_pex tool" test matrix needs to pass in order for a new version of please_pex to be released, so after I've tagged a new please_pex version and updated //tools:please_pex to download it, the other test matrices will also start passing again.

toastwaffle

I have reviewed up to and including tools/please_pex/preamble/path.h; will get to the rest tomorrow hopefully

toastwaffle · 2025-12-02T13:12:54Z

build_defs/python.build_defs

+            # If the target name ends with an entry point name, strip it - runtime_deps won't accept
+            # target names containing entry point names (which isn't really a problem for us,
+            # because the entire target will have to be built for the entry point to be provided
+            # anyway).


Should this comment be attached to line 784? Or should line 784 be beneath this comment?

Yeah, I think it makes more sense to move the definition of i_target here.

test/strip_source_test.py

toastwaffle · 2025-12-02T13:17:49Z

third_party/cc/openbsd/BUILD

@@ -0,0 +1,25 @@
+subinclude("///cc//build_defs:c")
+
+remote_file(


What's the rationale for not doing this as a github_repo?

OpenBSD has a pretty big code base and it seemed overkill to download the entire thing for the sake of a 21KB header file.

Makes sense. Might be worth leaving a comment to explain.

toastwaffle · 2025-12-02T13:22:32Z

tools/please_pex/pex/pex.go

 // NewWriter constructs a new Writer.
-func NewWriter(entryPoint, interpreter string, options []string, stamp string, zipSafe, noSite bool) *Writer {
+func NewWriter(entryPoint string, interpreters []string, interpreterArgs []string, stamp string, zipSafe, noSite bool) *Writer {
+	if interpreterArgs == nil {


This needs an explanation comment

As we discussed offline, you're correct that this is unnecessary. Thanks, removed it.

tools/please_pex/pex/pex.go

tools/please_pex/preamble/path.c

chrisnovakovic · 2025-12-03T00:48:05Z

The head of the branch addresses all the comments with a 👍 beneath them, plus (before you get around to reviewing it) a tidy-up of get_config to return an err_t rather than logging errors directly. This also required more liberal use of const in pexerror.c, which can only be a good thing.

chrisnovakovic · 2025-12-03T00:49:26Z

The FreeBSD tests are failing because new Python packages were pushed to Ports, so the hashes changed. I can't wait until the next Quarterly Ports release comes out so we can migrate to that...

chrisnovakovic · 2025-12-03T10:18:26Z

The following rebase will pick up the FreeBSD hash changes, which should cause the tests in the please_pex matrix to start passing again. Apologies for the noise.

There is currently an assumption that the Python interpreter used while building .pex files (i.e. the value of `DefaultInterpreter`) is also the Python interpreter that runs them. This can be overridden with the `shebang` parameter on individual `python_binary` and `python_test` targets, which sets the shebang in the generated .pex file to a specific value. The functionality this provides is limited: - If additional interpreter arguments are specified by the target, the generated .pex file will depend on a shell at `/bin/sh` in the run-time environment (which isn't guaranteed to exist, e.g. in distroless containers), as well as `/usr/bin/env` (also not guaranteed to exist). - It is possible to build the .pex file using a Python interpreter defined as a build target in the repo, but it isn't possible to run the .pex file using that interpreter because the .pex file's shebang is (by definition) static, but the interpreter's path relative to the .pex file's path varies depending on the context (e.g. whether the .pex file exists inside a build environment vs outside of one). This was discussed in please-build#247. Provide more flexibility in how .pex files are run by prepending a native-code preamble that implements dynamic searching of Python interpreters. The behaviour of this preamble is controlled at run time by a special zip member within the .pex file, `.bootstrap/PLZ_PREAMBLE_CONFIG`, which contains a list of candidate paths for Python interpreters under which the .pex file should be executed and a list of arguments to pass to the interpreter when attempting to execute it. The lists can be customised per `python_binary` or `python_test` target via the `runtime_interpreters` and `runtime_interpreter_args` parameters respectively; new plugin configuration options, `DefaultRuntimeInterpreters` and `DefaultRuntimeInterpreterArgs`, provide default values. If both are unspecified, the plugin's current behaviour is maintained (i.e. the same interpreter is used to both build and run the code). The flexibility offered by the new .pex preamble is sufficient to be able to remove `python_binary` and `python_test`'s `shebang` parameter (and the `DefaultShebang` plugin configuration option) altogether. The new .pex preamble is compact enough to prepend to all .pex files in a repo without collectively making them prohibitively large: ~98KB statically linked with musl on Linux, ~83KB dynamically linked on Darwin (which doesn't have a stable kernel ABI, and strongly discourages static linking). Among other possibilities, this allows for the creation of .pex files that are truly portable between run-time environments of the same operating system and architecture - e.g., the preamble can be configured to attempt to execute an interpreter that only exists within a production environment (such as a distroless container with its interpreter at `/python/bin/python3`), falling back on an interpreter defined as a build target in the repo if the .pex file is still located within Please's development/testing environment.

tools/please_pex/preamble/path.c

toastwaffle · 2025-12-03T10:47:17Z

third_party/cc/openbsd/BUILD

@@ -0,0 +1,25 @@
+subinclude("///cc//build_defs:c")
+
+remote_file(


Makes sense. Might be worth leaving a comment to explain.

tools/please_pex/preamble/pexerror.h

toastwaffle · 2025-12-03T11:47:28Z

tools/please_pex/preamble/pexerror.c

+    errmsg_t *errmsg = NULL;
+    size_t len = strlen(msg);
+
+    if (wrapped == NULL) {


should this check be before line 53? seems odd to check for nullness when you've already used wrapped

You're right - to be honest the null check doesn't really make a whole lot of sense (it's not something that can happen at run-time). I'll remove it.

Or maybe just call SLIST_FIRST(wrapped) after the check. I'll do that instead.

tools/please_pex/preamble/preamble.c

toastwaffle · 2025-12-03T13:26:12Z

tools/please_pex/preamble/pexerror.h

+err_t *err_wrap(const char *msg, err_t *wrapped);
+char *err_str(err_t *err);
+
+#endif /* __PEXERROR_H__ */


Suggested change

#endif /* __PEXERROR_H__ */

#endif /* !__PEXERROR_H__ */

I think? the other 2 header files have a ! here

Good catch, thanks. It's only stylistic, but it's good to be consistent.

tools/please_pex/preamble/preamble.c

chrisnovakovic requested a review from toastwaffle December 1, 2025 17:27

chrisnovakovic commented Dec 1, 2025

View reviewed changes

toastwaffle reviewed Dec 2, 2025

View reviewed changes

chrisnovakovic force-pushed the runtime-interpreters branch from d675b31 to 8de7f08 Compare December 3, 2025 10:18

chrisnovakovic added 12 commits December 3, 2025 11:31

Put defines on a single line

d6dfcf8

More sensible var name for preamble file

9b2381a

Always free exe_path

40ff77c

_dir_realpath var names

74f023a

Simplify length comparisons

15741e7

Use err_t and const more

d5f21d7

Return an error if get_plz_bin_path badly fails

1b0c04f

Remove readlink-based logic for getting .pex path on Linux

fa3203c

Simplify path.c further

f8b19e7

Document _XOPEN_SOURCE requirement

de89e0b

Remove unnecessary slice initialiser

f039131

toastwaffle approved these changes Dec 3, 2025

View reviewed changes

chrisnovakovic added 2 commits December 3, 2025 13:41

More sensible wrapped null check

3490d25

!__PEXERROR_H__

a7262eb

chrisnovakovic force-pushed the runtime-interpreters branch from 8de7f08 to a7262eb Compare December 3, 2025 15:08

chrisnovakovic merged commit 4c0d0c0 into please-build:master Dec 3, 2025
24 of 75 checks passed

chrisnovakovic deleted the runtime-interpreters branch December 3, 2025 15:08

		@@ -0,0 +1,25 @@
		subinclude("///cc//build_defs:c")

		remote_file(

Implement run-time Python interpreter searching #284

Implement run-time Python interpreter searching #284

Uh oh!

Conversation

chrisnovakovic commented Dec 1, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

toastwaffle left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chrisnovakovic Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chrisnovakovic commented Dec 3, 2025

Uh oh!

chrisnovakovic commented Dec 3, 2025

Uh oh!

chrisnovakovic commented Dec 3, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

chrisnovakovic Dec 3, 2025 •

edited

Loading