Debian Codegraph @

Tools/jit/README.md

raw ◀ ▶
Source reconstructed at patch state 0 of 1 — not the installed (fully patched) source.
1 Debian patch touch this file
1 The JIT Compiler
2 ================
3
4 This version of CPython can be built with an experimental just-in-time compiler[^pep-744]. While most everything you already know about building and using CPython is unchanged, you will probably need to install a compatible version of LLVM first.
5
6 Python 3.11 or newer is required to build the JIT.
7
8 ## Installing LLVM
9
10 The JIT compiler does not require end users to install any third-party dependencies, but part of it must be *built* using LLVM[^why-llvm]. You are *not* required to build the rest of CPython using LLVM, or even the same version of LLVM (in fact, this is uncommon).
11
12 LLVM version 19 is required. Both `clang` and `llvm-readobj` need to be installed and discoverable (version suffixes, like `clang-19`, are okay). It's highly recommended that you also have `llvm-objdump` available, since this allows the build script to dump human-readable assembly for the generated code.
13
14 It's easy to install all of the required tools:
15
16 ### Linux
17
18 Install LLVM 19 on Ubuntu/Debian:
19
20 ```sh
21 wget https://apt.llvm.org/llvm.sh
22 chmod +x llvm.sh
23 sudo ./llvm.sh 19
24 ```
25
26 Install LLVM 19 on Fedora Linux 40 or newer:
27
28 ```sh
29 sudo dnf install 'clang(major) = 19' 'llvm(major) = 19'
30 ```
31
32 ### macOS
33
34 Install LLVM 19 with [Homebrew](https://brew.sh):
35
36 ```sh
37 brew install llvm@19
38 ```
39
40 Homebrew won't add any of the tools to your `$PATH`. That's okay; the build script knows how to find them.
41
42 ### Windows
43
44 LLVM is downloaded automatically (along with other external binary dependencies) by `PCbuild\build.bat`.
45
46 Otherwise, you can install LLVM 19 [by searching for it on LLVM's GitHub releases page](https://github.com/llvm/llvm-project/releases?q=19), clicking on "Assets", downloading the appropriate Windows installer for your platform (likely the file ending with `-win64.exe`), and running it. **When installing, be sure to select the option labeled "Add LLVM to the system PATH".**
47
48 Alternatively, you can use [chocolatey](https://chocolatey.org):
49
50 ```sh
51 choco install llvm --version=19.1.0
52 ```
53
54
55 ## Building
56
57 For `PCbuild`-based builds, pass the `--experimental-jit` option to `build.bat`.
58
59 For all other builds, pass the `--enable-experimental-jit` option to `configure`.
60
61 Otherwise, just configure and build as you normally would. Cross-compiling "just works", since the JIT is built for the host platform.
62
63 The JIT can also be enabled or disabled using the `PYTHON_JIT` environment variable, even on builds where it is enabled or disabled by default. More details about configuring CPython with the JIT and optional values for `--enable-experimental-jit` can be found [here](https://docs.python.org/dev/using/configure.html#cmdoption-enable-experimental-jit).
64
65 [^pep-744]: [PEP 744](https://peps.python.org/pep-0744/)
66
67 [^why-llvm]: Clang is specifically needed because it's the only C compiler with support for guaranteed tail calls (`musttail`), which are required by CPython's continuation-passing-style approach to JIT compilation. Since LLVM also includes other functionalities we need (namely, object file parsing and disassembly), it's convenient to only support one toolchain at this time.