Windows launchers using posy trampolines (#1092)

## Background

In virtual environments, we want to install python programs as console
commands, e.g. `black .` over `python -m black .`. They may be called
[entrypoints](https://packaging.python.org/en/latest/specifications/entry-points/)
or scripts. For entrypoints, we're given a module name and function to
call in that module.

On Unix, we generate a minimal python script launcher. Text files are
runnable on unix by adding a shebang at their top, e.g.

```python
#!/usr/bin/env python
```

will make the operating system run the file with the current python
interpreter. A venv launcher for black in `/home/ferris/colorize/.venv`
(module name: `black`, function to call: `patched_main`) would look like
this:

```python
#!/home/ferris/colorize/.venv/bin/python
# -*- coding: utf-8 -*-
import re
import sys
from black import patched_main
if __name__ == "__main__":
    sys.argv[0] = re.sub(r"(-script\.pyw|\.exe)?$", "", sys.argv[0])
    sys.exit(patched_main())
```

On windows, this doesn't work, we can only rely on launching `.exe`
files.

## Summary

We use posy's rust implementation of a trampoline, which is based on
distlib's c++ implementation. We pre-build a minimal exe and append the
launcher script as stored zip archive behind it. The exe will look for
the venv python interpreter next to it and use it to execute the
appended script.

The changes in this PR make the `black` entrypoint work:

```powershell
cargo run -- venv .venv
cargo run -q -- pip install black
.\.venv\Scripts\black --version
```

Integration with our existing tests will be done in follow-up PRs.

## Implementation and Details

I've vendored the posy trampoline crate. It is a formatted, renamed and
slightly changed for embedding version of
https://github.com/njsmith/posy/pull/28.

The posy launchers are smaller than the distlib launchers, 16K vs 106K
for black. Currently only `x86_64-pc-windows-msvc` is supported. The
crate requires a nightly compiler for its no-std binary size tricks.

On windows, an application can be launched with a console or without (to
create windows instead), which needs two different launchers. The gui
launcher will subsequently use `pythonw.exe` while the console launcher
uses `python.exe`.
This commit is contained in:
konsti
2024-01-26 14:54:11 +01:00
committed by GitHub
parent f1d3b08c12
commit 39021263dd
24 changed files with 934 additions and 42 deletions
+22
View File
@@ -98,3 +98,25 @@ jobs:
- uses: rui314/setup-mold@v1
- uses: Swatinem/rust-cache@v2
- run: cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
# Separate job for the nightly crate
windows-trampoline:
runs-on: windows-latest
name: "check windows trampoline"
steps:
- uses: actions/checkout@v4
- name: "Install Rust toolchain"
working-directory: crates/puffin-trampoline
run: |
rustup target add x86_64-pc-windows-msvc
rustup component add clippy rust-src --toolchain nightly-2024-01-23-x86_64-pc-windows-msvc
- uses: rui314/setup-mold@v1
- uses: Swatinem/rust-cache@v2
with:
workspaces: "crates/puffin-trampoline"
- name: "Clippy"
working-directory: crates/puffin-trampoline
run: cargo clippy --all-features --locked -- -D warnings
- name: "Build"
working-directory: crates/puffin-trampoline
run: cargo build --release -Z build-std=core,panic_abort,alloc -Z build-std-features=compiler-builtins-mem --target x86_64-pc-windows-msvc