document the buildtime environment variables

cuda_bindings/docs/source/environment_variables.md

@@ -0,0 +1,13 @@
+# Environment Variables
+
+## Build-Time Environment Variables
+
+- `CUDA_HOME` or `CUDA_PATH`: Specifies the location of the CUDA Toolkit.
+
+- `CUDA_PYTHON_PARSER_CACHING` : bool, toggles the caching of parsed header files during the cuda-bindings build process. If caching is enabled (`CUDA_PYTHON_PARSER_CACHING` is True), the cache path is set to ./cache_<library_name>, where <library_name> is derived from the cuda toolkit libraries used to build cuda-bindings.
+
+- `CUDA_PYTHON_PARALLEL_LEVEL` (previously `PARALLEL_LEVEL`) : int, sets the number of threads used in the compilation of extension modules. Not setting it or setting it to 0 would disable parallel builds.
+
+## Runtime Environment Variables
+
+- `CUDA_PYTHON_CUDA_PER_THREAD_DEFAULT_STREAM` : When set to 1, the default stream is the per-thread default stream. When set to 0, the default stream is the legacy default stream. This defaults to 0, for the legacy default stream. See [Stream Synchronization Behavior](https://docs.nvidia.com/cuda/cuda-runtime-api/stream-sync-behavior.html) for an explanation of the legacy and per-thread default streams.

cuda_bindings/docs/source/index.rst

@@ -9,6 +9,7 @@
    overview.md
    motivation.md
    release.md
+   environment_variables.md
    api.rst
 
 

cuda_bindings/docs/source/install.md

@@ -37,6 +37,8 @@ Source builds require that the provided CUDA headers are of the same major.minor
 $ export CUDA_HOME=/usr/local/cuda
 ```
 
+See [Environment Variables](environment_variables.md) for a description of other build-time environment variables.
+
 ```{note}
 Only `cydriver`, `cyruntime` and `cynvrtc` are impacted by the header requirement.
 ```

cuda_bindings/setup.py

@@ -15,6 +15,7 @@
 import sys
 import sysconfig
 import tempfile
+from warnings import warn
 
 from Cython import Tempita
 from Cython.Build import cythonize
@@ -32,7 +33,15 @@
     raise RuntimeError("Environment variable CUDA_HOME or CUDA_PATH is not set")
 
 CUDA_HOME = CUDA_HOME.split(os.pathsep)
-nthreads = int(os.environ.get("PARALLEL_LEVEL", "0") or "0")
+if os.environ.get("PARALLEL_LEVEL") is not None:
+    warn(
+        "Environment variable PARALLEL_LEVEL is deprecated. Use CUDA_PYTHON_PARALLEL_LEVEL instead",
+        DeprecationWarning,
+        stacklevel=1,
+    )
+    nthreads = int(os.environ.get("PARALLEL_LEVEL", "0"))
+else:
+    nthreads = int(os.environ.get("CUDA_PYTHON_PARALLEL_LEVEL", "0") or "0")
 PARSER_CACHING = os.environ.get("CUDA_PYTHON_PARSER_CACHING", False)
 PARSER_CACHING = bool(PARSER_CACHING)
 
@@ -80,7 +89,7 @@
 found_values = []
 
 include_path_list = [os.path.join(path, "include") for path in CUDA_HOME]
-print(f'Parsing headers in "{include_path_list}" (Caching {PARSER_CACHING})')
+print(f'Parsing headers in "{include_path_list}" (Caching = {PARSER_CACHING})')
 for library, header_list in header_dict.items():
     header_paths = []
     for header in header_list: