mirror of https://github.com/astral-sh/uv
169 lines
7.3 KiB
Markdown
169 lines
7.3 KiB
Markdown
# Windows trampolines
|
|
|
|
This is a fork of
|
|
[posy trampolines](https://github.com/njsmith/posy/tree/dda22e6f90f5fefa339b869dd2bbe107f5b48448/src/trampolines/windows-trampolines/posy-trampoline).
|
|
|
|
## Building
|
|
|
|
### Cross-compiling from Linux
|
|
|
|
Install [cargo xwin](https://github.com/rust-cross/cargo-xwin). Use your package manager to install
|
|
LLD and add the `rustup` targets:
|
|
|
|
```shell
|
|
sudo apt install llvm clang lld
|
|
cargo install cargo-xwin
|
|
rustup toolchain install nightly-2025-02-16
|
|
rustup component add rust-src --toolchain nightly-2025-02-16-x86_64-unknown-linux-gnu
|
|
rustup target add --toolchain nightly-2025-02-16 i686-pc-windows-msvc
|
|
rustup target add --toolchain nightly-2025-02-16 x86_64-pc-windows-msvc
|
|
rustup target add --toolchain nightly-2025-02-16 aarch64-pc-windows-msvc
|
|
```
|
|
|
|
Then, build the trampolines for all supported architectures:
|
|
|
|
```shell
|
|
cargo +nightly-2025-02-16 xwin build --xwin-arch x86 --release --target i686-pc-windows-msvc
|
|
cargo +nightly-2025-02-16 xwin build --release --target x86_64-pc-windows-msvc
|
|
cargo +nightly-2025-02-16 xwin build --release --target aarch64-pc-windows-msvc
|
|
```
|
|
|
|
### Cross-compiling from macOS
|
|
|
|
Install [cargo xwin](https://github.com/rust-cross/cargo-xwin). Use your package manager to install
|
|
LLVM and add the `rustup` targets:
|
|
|
|
```shell
|
|
brew install llvm
|
|
cargo install cargo-xwin
|
|
rustup toolchain install nightly-2025-02-16
|
|
rustup component add rust-src --toolchain nightly-2025-02-16-aarch64-apple-darwin
|
|
rustup target add --toolchain nightly-2025-02-16 i686-pc-windows-msvc
|
|
rustup target add --toolchain nightly-2025-02-16 x86_64-pc-windows-msvc
|
|
rustup target add --toolchain nightly-2025-02-16 aarch64-pc-windows-msvc
|
|
```
|
|
|
|
Then, build the trampolines for all supported architectures:
|
|
|
|
```shell
|
|
cargo +nightly-2025-02-16 xwin build --release --target i686-pc-windows-msvc
|
|
cargo +nightly-2025-02-16 xwin build --release --target x86_64-pc-windows-msvc
|
|
cargo +nightly-2025-02-16 xwin build --release --target aarch64-pc-windows-msvc
|
|
```
|
|
|
|
### Updating the prebuilt executables
|
|
|
|
After building the trampolines for all supported architectures:
|
|
|
|
```shell
|
|
cp target/aarch64-pc-windows-msvc/release/uv-trampoline-console.exe trampolines/uv-trampoline-aarch64-console.exe
|
|
cp target/aarch64-pc-windows-msvc/release/uv-trampoline-gui.exe trampolines/uv-trampoline-aarch64-gui.exe
|
|
cp target/x86_64-pc-windows-msvc/release/uv-trampoline-console.exe trampolines/uv-trampoline-x86_64-console.exe
|
|
cp target/x86_64-pc-windows-msvc/release/uv-trampoline-gui.exe trampolines/uv-trampoline-x86_64-gui.exe
|
|
cp target/i686-pc-windows-msvc/release/uv-trampoline-console.exe trampolines/uv-trampoline-i686-console.exe
|
|
cp target/i686-pc-windows-msvc/release/uv-trampoline-gui.exe trampolines/uv-trampoline-i686-gui.exe
|
|
```
|
|
|
|
### Testing the trampolines
|
|
|
|
To perform a basic smoke test of the trampolines, run the following commands on a Windows machine,
|
|
from the root of the repository:
|
|
|
|
```shell
|
|
cargo clean
|
|
cargo run venv
|
|
cargo run pip install black
|
|
.venv\Scripts\black --version
|
|
```
|
|
|
|
## Background
|
|
|
|
### What is this?
|
|
|
|
Sometimes you want to run a tool on Windows that's written in Python, like `black` or `mypy` or
|
|
`jupyter` or whatever. But, Windows does not know how to run Python files! It knows how to run
|
|
`.exe` files. So we need to somehow convert our Python file a `.exe` file.
|
|
|
|
That's what this does: it's a generic "trampoline" that lets us generate custom `.exe`s for
|
|
arbitrary Python scripts, and when invoked it bounces to invoking `python <the script>` instead.
|
|
|
|
### How do you use it?
|
|
|
|
Basically, this looks up `python.exe` (for console programs) and invokes
|
|
`python.exe path\to\the\<the .exe>`.
|
|
|
|
The intended use is:
|
|
|
|
- take your Python script, name it `__main__.py`, and pack it into a `.zip` file. Then concatenate
|
|
that `.zip` file onto the end of one of our prebuilt `.exe`s.
|
|
- After the zip file content, write the path to the Python executable that the script uses to run
|
|
the Python script as UTF-8 encoded string, followed by the path's length as a 32-bit little-endian
|
|
integer.
|
|
- At the very end, write the magic number `UVUV` in bytes.
|
|
|
|
| `launcher.exe` |
|
|
| :-------------------------: |
|
|
| `<zipped python script>` |
|
|
| `<path to python.exe>` |
|
|
| `<len(path to python.exe)>` |
|
|
| `<b'U', b'V', b'U', b'V'>` |
|
|
|
|
Then when you run `python` on the `.exe`, it will see the `.zip` trailer at the end of the `.exe`,
|
|
and automagically look inside to find and execute `__main__.py`. Easy-peasy.
|
|
|
|
### Why does this exist?
|
|
|
|
I probably could have used Vinay's C++ implementation from `distlib`, but what's the fun in that? In
|
|
particular, optimizing for binary size was entertaining (these are ~7x smaller than the distlib,
|
|
which doesn't matter much, but does a little bit, considering that it gets added to every Python
|
|
script). There are also some minor advantages, like I think the Rust code is easier to understand
|
|
(multiple files!) and it's convenient to be able to straightforwardly code the Python-finding logic
|
|
we want. But mostly it was just an interesting challenge.
|
|
|
|
This does owe a _lot_ to the `distlib` implementation though. The overall logic is copied
|
|
more-or-less directly.
|
|
|
|
### Anything I should know for hacking on this?
|
|
|
|
In order to minimize binary size, this uses, `panic="abort"`, and carefully avoids using
|
|
`core::fmt`. This removes a bunch of runtime overhead: by default, Rust "hello world" on Windows is
|
|
~150 KB! So these binaries are ~10x smaller.
|
|
|
|
Of course the tradeoff is that this is an awkward super-limited environment. No C runtime and
|
|
limited platform APIs... you don't even panicking support by default. To work around this:
|
|
|
|
- We use `windows` to access Win32 APIs directly. Who needs a C runtime? Though uh, this does mean
|
|
that literally all of our code is `unsafe`. Sorry!
|
|
|
|
- `diagnostics.rs` uses `ufmt` and some cute Windows tricks to get a convenient version of
|
|
`eprintln!` that works without `core::fmt`, and automatically prints to either the console if
|
|
available or pops up a message box if not.
|
|
|
|
- All the meat is in `bounce.rs`.
|
|
|
|
Miscellaneous tips:
|
|
|
|
- `cargo-bloat` is a useful tool for checking what code is ending up in the final binary and how
|
|
much space it's taking. (It makes it very obvious whether you've pulled in `core::fmt`!)
|
|
|
|
- Lots of Rust built-in panicking checks will pull in `core::fmt`, e.g., if you ever use `.unwrap()`
|
|
then suddenly our binaries double in size, because the `if foo.is_none() { panic!(...) }` that's
|
|
hidden inside `.unwrap()` will invoke `core::fmt`, even if the unwrap will actually never fail.
|
|
`.unwrap_unchecked()` avoids this. Similar for `slice[idx]` vs `slice.get_unchecked(idx)`.
|
|
|
|
### How do you build this stupid thing?
|
|
|
|
Building this can be frustrating, because the low-level compiler/runtime machinery have a bunch of
|
|
implicit assumptions about the environment they'll run in, and the facilities it provides for things
|
|
like `memcpy`, unwinding, etc. So we need to replace the bits that we actually need, and which bits
|
|
we need can change depending on stuff like optimization options. For example: we use
|
|
`panic="abort"`, so we don't actually need unwinding support, but at lower optimization levels the
|
|
compiler might not realize that, and still emit references to the unwinding
|
|
helper`__CxxFrameHandler3`. And then the linker blows up because that symbol doesn't exist.
|
|
|
|
```
|
|
cargo build --release --target i686-pc-windows-msvc
|
|
cargo build --release --target x86_64-pc-windows-msvc
|
|
cargo build --release --target aarch64-pc-windows-msvc
|
|
```
|