Link the build env var reference from CONTRIBUTING/README (#193617)

## Author Notes

Trying to link to the source of truth so it's easier to discover.

## Agent Notes

> The comment block at the top of `cmake/EnvVarForwarding.cmake` is the source of truth for build
> environment variables: which ones exist, what they do, and how each reaches CMake. Nothing in
> `CONTRIBUTING.md` pointed at it, and three of the `README.md` mentions were plain text rather than
> links, so it was hard to find. This adds a link from the "Build only what you need" list and the
> build-troubleshooting step in `CONTRIBUTING.md`, makes the `README.md` mentions links, and adds a
> pointer to the Copilot instructions. Links are relative paths with no line anchor, matching the two
> `README.md` links that already existed -- a `#L` anchor is only safe when pinned to a commit, and
> nothing validates one (`scripts/lint_xrefs.sh` strips the fragment before checking the target
> exists). Three inaccuracies noticed while linking are fixed in passing, since the newly linked file
> is what makes them visible as wrong: `CMAKE_FRESH` was removed along with `setup.py`, so it is
> dropped from the example command; the same step described the build as "running `make` from the
> `build` directory", which predates scikit-build-core; and `CUDA_DEVICE_DEBUG` is read in
> `cmake/public/cuda.cmake` but never forwarded from the environment, so it is now shown as
> `-C cmake.define.CUDA_DEVICE_DEBUG=1` and added to the CMake-options section of the reference file.
>
> Documentation-only, so there is no behavior to test; `spin lint` passes.

This PR was authored with the help of Claude Code.

Pull Request resolved: https://github.com/pytorch/pytorch/pull/193617
Approved by: https://github.com/pytorchgreenlight, https://github.com/janeyx99
This commit is contained in:
albanD
2026-08-19 14:07:02 +00:00
committed by PyTorch MergeBot
parent 0e6694d34b
commit 82e62d5724
4 changed files with 21 additions and 7 deletions
+2
View File
@@ -51,6 +51,8 @@ Speed up builds:
- Install `ninja` (`pip install ninja`) for faster builds
- Use `ccache` for incremental compilation caching
Full list of build environment variables: [`cmake/EnvVarForwarding.cmake`](../cmake/EnvVarForwarding.cmake)
Rebuild specific targets: `(cd build && ninja <target>)`
### Testing
+14 -4
View File
@@ -134,10 +134,12 @@ Follow the instructions for [installing PyTorch from source](https://github.com/
python -m pip install --group dev
python -m pip install --no-build-isolation -v -e .
```
4. The main step within `python -m pip install -e . -v --no-build-isolation` is running `make` from the `build` directory. If you want to
experiment with some environment variables, you can pass them into the command:
4. The main step within `python -m pip install -e . -v --no-build-isolation` is the CMake build in the
`build` directory (`ninja` by default). If you want to experiment with some environment variables, you
can pass them into the command (see
[`cmake/EnvVarForwarding.cmake`](./cmake/EnvVarForwarding.cmake) for the environment variables the build forwards):
```bash
ENV_KEY1=ENV_VAL1[, ENV_KEY2=ENV_VAL2]* CMAKE_FRESH=1 python -m pip install --no-build-isolation -v -e .
ENV_KEY1=ENV_VAL1[, ENV_KEY2=ENV_VAL2]* python -m pip install --no-build-isolation -v -e .
```
5. Try installing PyTorch without build isolation by adding `--no-build-isolation` to the `pip install` command.
This will use the current environment's packages instead of creating a new isolated environment for the build.
@@ -798,6 +800,9 @@ On the initial build, you can also speed things up by disabling the features you
- `USE_CPU_VECTORIZATION=0` will disable building vectorized CPU kernel variants (AVX2, AVX512, VSX, ZVECTOR, SVE). Only the scalar DEFAULT kernels are built. Fine for correctness/dispatch work; not for CPU benchmarking.
- `USE_COLORIZE_OUTPUT=1` will colorize compiler output for easier reading.
The full list of build environment variables, what each one does, and how it reaches CMake is
documented at the top of [`cmake/EnvVarForwarding.cmake`](./cmake/EnvVarForwarding.cmake).
For example, a good default for the most minimal build is to add to your bashrc is:
```bash
alias BUILD_CONFIG='CMAKE_GENERATOR=Ninja USE_DISTRIBUTED=0 USE_FLASH_ATTENTION=0 USE_MEM_EFF_ATTENTION=0 USE_MKLDNN=0 USE_CUDA=0 BUILD_TEST=0 USE_FBGEMM=0 USE_NNPACK=0 USE_XNNPACK=0 BUILD_LAZY_TS_BACKEND=0 USE_PYTORCH_QNNPACK=0 USE_CPU_VECTORIZATION=0 USE_COLORIZE_OUTPUT=1'
@@ -1075,9 +1080,14 @@ Set `TORCH_SHOW_CPP_STACKTRACES=1` to get the C++ stacktrace when an error occur
If you are working on the CUDA code, here are some useful CUDA debugging tips:
1. `CUDA_DEVICE_DEBUG=1` will enable CUDA device function debug symbols (`-g -G`).
1. `CUDA_DEVICE_DEBUG` will enable CUDA device function debug symbols (`-g -G`).
This will be particularly helpful in debugging device code. However, it will
slow down the build process for about 50% (compared to only `DEBUG=1`), so use wisely.
Unlike `DEBUG`, it is read as a CMake variable rather than forwarded from the environment, so
pass it at install time (it has no effect on MSVC builds):
```bash
python -m pip install -e . -v --no-build-isolation -C cmake.define.CUDA_DEVICE_DEBUG=1
```
2. `cuda-gdb` and `compute-sanitizer` are your best CUDA debugging friends. Unlike`gdb`,
`cuda-gdb` can display actual values in a CUDA tensor (rather than all zeros).
3. CUDA supports a lot of C++17/20 features, which include `std::numeric_limits`, `std::nextafter`,
+3 -3
View File
@@ -209,7 +209,7 @@ If you want to compile with CUDA support, [select a supported version of CUDA fr
Note: You could refer to the [cuDNN Support Matrix](https://docs.nvidia.com/deeplearning/cudnn/backend/latest/reference/support-matrix.html) for cuDNN versions with the various supported CUDA, CUDA driver, and NVIDIA hardware.
If you want to disable CUDA support, export the environment variable `USE_CUDA=0`.
Other potentially useful environment variables are documented in `cmake/EnvVarForwarding.cmake`. If
Other potentially useful environment variables are documented in [`cmake/EnvVarForwarding.cmake`](./cmake/EnvVarForwarding.cmake). If
CUDA is installed in a non-standard location, set PATH so that the nvcc you
want to use can be found (e.g., `export PATH=/usr/local/cuda-12.8/bin:$PATH`).
@@ -223,7 +223,7 @@ If you want to compile with ROCm support, install
By default the build system expects ROCm to be installed in `/opt/rocm`. If ROCm is installed in a different directory, the `ROCM_PATH` environment variable must be set to the ROCm installation directory. The build system automatically detects the AMD GPU architecture. Optionally, the AMD GPU architecture can be explicitly set with the `PYTORCH_ROCM_ARCH` environment variable [AMD GPU architecture](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html#supported-gpus)
If you want to disable ROCm support, export the environment variable `USE_ROCM=0`.
Other potentially useful environment variables are documented in `cmake/EnvVarForwarding.cmake`.
Other potentially useful environment variables are documented in [`cmake/EnvVarForwarding.cmake`](./cmake/EnvVarForwarding.cmake).
##### Intel GPU Support
If you want to compile with Intel GPU support, follow these
@@ -231,7 +231,7 @@ If you want to compile with Intel GPU support, follow these
- Intel GPU is supported for Linux and Windows.
If you want to disable Intel GPU support, export the environment variable `USE_XPU=0`.
Other potentially useful environment variables are documented in `cmake/EnvVarForwarding.cmake`.
Other potentially useful environment variables are documented in [`cmake/EnvVarForwarding.cmake`](./cmake/EnvVarForwarding.cmake).
#### Get the PyTorch Source
+2
View File
@@ -105,6 +105,8 @@
# debug flags (may OOM nvcc). This was always a CMake
# option; the setup.py comment that listed it as an env
# var was inaccurate -- it was never forwarded.
# CUDA_DEVICE_DEBUG build CUDA device code with -g -G (read in
# cmake/public/cuda.cmake; no effect on MSVC)
#
# Removed with setup.py (no longer available):
# CMAKE_FRESH force a fresh configure. Delete the build/ directory