Clarify why LLVM is required

brandtbucher · brandtbucher · commit d01a2c7419ca · 2024-01-10T16:31:02.000-08:00
diff --git a/Tools/jit/README.md b/Tools/jit/README.md
@@ -3,15 +3,15 @@ The JIT Compiler
 
 This version of CPython can be built with an experimental just-in-time compiler. 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.
 
-### Installing LLVM
+## Installing LLVM
 
-The JIT compiler does not require end users to install any third-party dependencies, but part of it must be *built* using 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).
+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).
 
 LLVM version 16 is required. Both `clang` and `llvm-readobj` need to be installed and discoverable (version suffixes, like `clang-16`, 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.
 
 It's easy to install all of the required tools:
 
-#### Linux
+### Linux
 
 Install LLVM 16 on Ubuntu/Debian:
 
@@ -21,7 +21,7 @@ chmod +x llvm.sh
 sudo ./llvm.sh 16
 ```
 
-#### macOS
+### macOS
 
 Install LLVM 16 with [Homebrew](https://brew.sh):
 
@@ -31,16 +31,18 @@ $ brew install llvm@16
 
 Homebrew won't add any of the tools to your `$PATH`. That's okay; the build script knows how to find them.
 
-#### Windows
+### Windows
 
 LLVM 16 can be installed on Windows by using the installers published on [LLVM's GitHub releases page](https://github.com/llvm/llvm-project/releases/tag/llvmorg-16.0.6).
 
 [Here's a recent one.](https://github.com/llvm/llvm-project/releases/download/llvmorg-16.0.6/LLVM-16.0.6-win64.exe) **When installing, be sure to select the option labeled "Add LLVM to the system PATH".**
 
-### Building
+## Building
 
 For `PCbuild`-based builds, pass the new `--experimental-jit` option to `build.bat`.
 
 For all other builds, pass the new `--enable-experimental-jit` option to `configure`.
 
 Otherwise, just configure and build as you normally would. Cross-compiling "just works", since the JIT is built for the host platform.
+
+[^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.
