PyTorch PR maps 9 CMake build stages to help developers navigate the build system
PyTorch's root CMakeLists.txt finally gets a roadmap—no more reading 2,000 lines to find a build step.
PyTorch's build system has long been a maze: the root CMakeLists.txt is thousands of lines, and finding where a specific build step lives meant reading the entire file. PR #193615, authored by albanD with the diff generated and reviewed by Claude Code, fixes this with a comment-only change that adds a nine-stage map at the top of the file. The stages are listed in execution order: bootstrap and env-var forwarding, pre-build submodule/NCCL setup, options, dependencies, codegen, the main build, export plus optional binaries/JNI, Python packaging, and the configuration summary. Each stage names the specific cmake/ module or subdirectory that implements it, giving developers direct pointers instead of guesswork.
The PR also calls out the environment variables that configure the build, pointing Stage 1 at cmake/EnvVarForwarding.cmake, while noting exceptions like third-party paths (MKLROOT, ROCM_PATH) and a few niche flags read directly where they are used. Both the spin develop and spin install docstrings gain a sentence referencing the new overview and the module list. Each stage description was cross-checked against its named module, and the change was verified with BUILD_CONFIG spin develop, spin develop --help, spin install --help, and spin lint. As a comment-only PR, it introduces zero risk to build behavior—just a significant improvement in developer experience for anyone touching PyTorch's build configuration.
- Nine build stages are now documented at the top of the root CMakeLists.txt, each pointing to its cmake/ module or subdirectory
- Stage 1 highlights cmake/EnvVarForwarding.cmake as the place to find build-configuring environment variables, with exceptions like MKLROOT and ROCM_PATH
- spin develop and spin install docstrings updated; verified with BUILD_CONFIG spin develop and related commands—no build behavior changes
Why It Matters
This cuts the time needed to understand PyTorch's complex build, letting contributors find and modify build steps in minutes, not hours.