Expose default build profile as QISKIT_BUILD_PROFILE (#15242)

We previously have read an undocumented environment variable
`RUST_DEBUG` as part of `setup.py` and used this to force debug mode
in `pip install .`.

This instead formalises the system into a `QISKIT_BUILD_PROFILE`
environment variable with the values `release` and `debug`, which can
(and do) publicly document.  For convenience, we still read `RUST_DEBUG`
as a fallback.

Author: jakelishman

CONTRIBUTING.md

@@ -126,14 +126,24 @@ If you use Rustup, it will automatically install the correct Rust version
 currently used by the project.
 
 Once you have a Rust compiler installed, you can rely on the normal Python
-build/install steps to install Qiskit. This means you just run
-`pip install .` in your local git clone to build and install Qiskit.
-
-Do note that if you do use develop mode/editable install (via `python setup.py develop` or `pip install -e .`) the Rust extension will be built in debug mode
-without any optimizations enabled. This will result in poor runtime performance.
-If you'd like to use an editable install with an optimized binary you can
-run `python setup.py build_rust --release --inplace` after you install in
-editable mode to recompile the rust extensions in release mode.
+build/install steps to install Qiskit. This means you run `pip install .` or
+`pip install -e .` in your local git clone to build and install Qiskit.
+Note that changes to Rust files will not be reflected in an editable install
+until you recompile.  You can recompile the Rust components of an editable
+install by running
+```
+python setup.py build_rust --inplace [--release | --debug]
+```
+Modifications to Rust files will not take effect until the Rust extension module
+is recompiled with the above command.
+
+By default, `pip install .` will build the Rust components in "release" mode
+and `pip install -e .` (or `python setup.py build_rust --inplace`) will build
+them in "debug" mode, without optimizations.  Debug mode will have poor
+runtime performance.  You can set the environment variable `QISKIT_BUILD_PROFILE`
+to `release` or `debug` to control the default.  The `--release`/`--debug` flag
+to `build_rust` overrides this default.
+
 
 Note that in order to run `python setup.py ...` commands you need to have the 
 build dependency packages, which are listed in the `pyproject.toml` file under 

releasenotes/notes/build-profile-envvar-43adf332f7ed69e0.yaml

@@ -0,0 +1,6 @@
+---
+build:
+  - |
+    The build system now reads the environment variable ``QISKIT_BUILD_PROFILE`` to
+    choose whether to build in ``release`` or ``debug`` modes. If this is not set, ``pip install .``
+    will (continue to) default to release mode, and ``pip install -e .`` to debug mode.

setup.py

@@ -13,6 +13,7 @@
 "The Qiskit setup file."
 
 import os
+import warnings
 from setuptools import setup
 from setuptools_rust import Binding, RustExtension
 
@@ -26,9 +27,23 @@
 # unergonomic to do otherwise.
 
 
-# If RUST_DEBUG is set, force compiling in debug mode. Else, use the default behavior of whether
-# it's an editable installation.
-rust_debug = True if os.getenv("RUST_DEBUG") == "1" else None
+# Check for a default build profile from the environment (`--release` or `--debug` flags to
+# `build_rust` override this default).  If not present, we also check if `RUST_DEBUG=1` for
+# convenience, since we did that (undocumented) until Qiskit 2.4.
+if (build_profile := os.getenv("QISKIT_BUILD_PROFILE", None)) is None:
+    rust_debug = os.getenv("RUST_DEBUG", None) == "1" or None
+else:
+    match build_profile.lower():
+        case "debug":
+            rust_debug = True
+        case "release":
+            rust_debug = False
+        case _:
+            warnings.warn(
+                f"QISKIT_BUILD_PROFILE set to unknown value '{build_profile}'."
+                " Valid values are 'debug' and 'release'."
+            )
+            rust_debug = None
 
 # If QISKIT_NO_CACHE_GATES is set then don't enable any features while building
 #

tox.ini

@@ -44,7 +44,7 @@ commands = python tools/run_cargo_test.py
 # still run fast enough.
 [testenv:.pkg-rust]
 setenv =
-  RUST_DEBUG=1
+  QISKIT_BUILD_PROFILE=debug
 
 [testenv:lint]
 basepython = python3
@@ -104,7 +104,7 @@ allowlist_externals =
   doxygen
 setenv =
   {[testenv]setenv}
-  RUST_DEBUG=1  # Faster to compile.
+  QISKIT_BUILD_PROFILE=debug
 commands_pre =
   {[testenv]install_command} -r{toxinidir}/requirements-optional.txt -r{toxinidir}/requirements-dev.txt
 commands =