Tooling

spin

The repo's developer-facing CLI. Configured by .spin/cmds.toml. Per CLAUDE.md, the only sanctioned lint and dev driver.

spin help          # list commands
spin lint          # run lints
spin fixlint       # apply auto-fixes
spin test          # run tests (delegates to test/run_test.py)

spin lint shells out to lintrunner underneath.

lintrunner

Configured by .lintrunner.toml (~53K lines). Runs:

• clang-format and clang-tidy on C++ headers/sources.
• ruff and flake8 on Python.
• mypy (mypy.ini) and pyrefly (pyrefly.toml) for type checks.
• A long list of project-specific linters: LINTRUNNER_CMD_NEWLINES, MYPY, MYPYSTRICT, PYREFLY, RUFF, RUSTFMT, SPACES, TABS, TYPEIGNORE, MERGE_CONFLICTLESS_CSV, EXEC, NEWLINE, BLACK, CMAKE, CLANGFORMAT, CLANGTIDY, WORKFLOWS, BUILD_PIN_TXT, OPS_TEST_TARGETS, …

Most of these have --fix support; spin fixlint runs the --fixable ones.

CI: GitHub Actions

Workflows under .github/workflows/. Top-level files:

• _linux-build.yml, _linux-test.yml, _mac-build.yml, _mac-test.yml, _win-build.yml, _win-test.yml, _rocm-test.yml, _xpu-test.yml, _mps-test.yml, …
• pull.yml — runs on every PR.
• trunk.yml — runs on main.
• nightly.yml — runs nightly wheel builds.
• inductor.yml, inductor-perf-test-nightly-*.yml — Inductor jobs.
• release-cut.yml — release branch cut automation.
• A few hundred more for specific targets.

The orchestration is fairly stylized: most build/test workflows are reusable templates parameterized by Docker image, Python version, build environment, and test sharding.

Codegen

Most of the C++/Python boilerplate in PyTorch is generated, not hand-written. Codegen runs as a CMake step (cmake/Codegen.cmake) before C++ compilation.

What	Where it lives
ATen op stubs, dispatcher reg	torchgen/
Autograd kernels, backward Nodes	tools/autograd/
Python bindings	tools/setup_helpers/cmake.py invokes torchgen
Type stubs	tools/pyi/gen_pyi.py
Selective build (mobile)	torchgen/selective_build/
ExecuTorch ops	torchgen/executorch/
Static runtime ops	torchgen/static_runtime/

Outputs land in build/aten/src/ATen/, torch/csrc/autograd/generated/, build/torch/csrc/, etc.

Build internals

• setup.py (~60K lines) — entry point. Drives CMake, runs codegen, produces wheels.
• cmake/ — modules that set up MKL, MAGMA, NCCL, FBGEMM, KINETO, etc.
• tools/build_pytorch_libs.py — older driver; mostly subsumed by setup.py.
• requirements.txt, requirements-build.txt — the minimal Python deps to build.
• .bazelignore, BUILD.bazel, *.bzl, buckbuild.bzl, pt_ops.bzl, pt_template_srcs.bzl — Bazel/Buck files for internal Meta builds. External users rarely touch these.

Pre-commit hooks

scripts/install_hooks.sh (if present) installs a git pre-commit that runs lintrunner --paths-cmd 'git diff --cached'. Optional but recommended.

Lint-runner internals worth knowing

• LINTRUNNER_FILE_PATTERN controls which lints run on which files.
• --init downloads tool binaries (clang-tidy, etc.) into ~/.cache/lintrunner/.
• --all-files runs every lint on every file (slow; usually CI-only).
• LINTRUNNER_CMD env var lets workflows override the binary path.

Common debugging during the build

• "undefined reference to at::*" — ATen header changes that aren't being recompiled. pip install -e . -v --no-build-isolation again; in extreme cases delete build/ and rebuild.
• "could not find CUDA" — CUDA toolkit isn't on PATH. export CUDA_HOME=/usr/local/cuda.
• "FBGEMM compile error" — USE_FBGEMM=0 to skip; you lose some quantized perf but the build proceeds.
• "link runs forever" — MAX_JOBS=1 for the link step. gold or mold linkers help substantially.

Where to look

File	Purpose
.spin/cmds.toml	spin commands
.lintrunner.toml	Lint configuration
.github/workflows/	CI
cmake/Codegen.cmake	Codegen CMake driver
setup.py	Build entry
torchgen/	The codegen package
tools/autograd/	Autograd codegen
tools/pyi/gen_pyi.py	Type stub generator