GeezerVison

Stacked on #656. One commit: "Let a configured "on" compile through cmake where
SuiteSparse uses cmake". #652 adds a sentence to the user guide saying that on Windows
a configured "on" becomes "run" ("Say that the JIT stays at "run" on Windows, where
SuiteSparse compiles with cmake"); this PR rewrites that sentence.

The problem

SuiteSparse built with MSVC, as conda-forge builds it for Windows, compiles JIT kernels
only through cmake: gb.ss.config["jit_use_cmake"] is True there and cannot be set
False. SuiteSparse passes the configured compiler to cmake as CMAKE_C_COMPILER, which
cmake's Visual Studio generator ignores; it finds Visual Studio's compiler itself.
conda-forge's builds configure the build machine's cl.exe, a path under
C:/Program Files/Microsoft Visual Studio/ that users rarely have. #652 sets "on" at
init only where the configured compiler exists, so on Windows a configured "on"
(GRAPHBLAS_JIT_C_CONTROL=on, gb.config.set(jit_c_control="on") or a YAML file)
quietly became "run", and nothing compiled. main behaves the same.

The cmake path itself works on Windows CI. #652's test_set_jit_c_control_at_init
pointed the compiler setting at a directory and expected the probe to fail; on every
Windows job with a JIT build in one CI run of this stack (81 jobs, SuiteSparse 8.2.0
through 10.5.2 and upstream), the probe compiled through cmake and the control stayed
"on" (fixed in #652 by "Skip the unusable-compiler probe check where SuiteSparse
compiles with cmake").

What changes

• A configured "on" looks for cmake where SuiteSparse uses it. At init, where
  jit_use_cmake is True, python-graphblas checks for cmake on the PATH
  (shutil.which) instead of the configured compiler path, then probes as before by
  compiling a small type. A failing probe still means "run", with no error. Nothing
  changes where jit_use_cmake is False, which is everywhere but MSVC builds unless a
  user sets it.
• UDT work never raises the default "run" where jit_use_cmake is True. Elsewhere,
  UDT operators and registration from C source raise the default "run" to "on" when
  they need a kernel. Through cmake each kernel costs about 10 seconds (below), so
  there only an "on" the user set compiles, even where the configured compiler happens
  to exist (the build machine's cl.exe path, or conda's clang.exe, which the
  compiler repair finds). UDT operators then call their Numba functions. Registering C
  source under that "run" raises an error that says SuiteSparse compiles through cmake
  here and that gb.ss.config["jit_c_control"] = "on" opts in, instead of suggesting
  gb.ss.fix_jit_config(), which does not help there.
• The probe's name includes the cmake settings. The probe type is named after a
  hash of the toolchain settings, so a toolchain the cache has not seen compiles a
  probe of its own rather than loading one that another toolchain left there.
  jit_use_cmake and jit_c_cmake_libs are now part of that hash; without them, a
  probe through cmake on Linux or macOS loaded the probe compiled directly and tested
  nothing. Each existing cache compiles its probe once more (about 0.3 s directly). A
  test fails if either setting is taken out of the hash, and checks that init, which
  reads the settings through the C API, names the probe as later calls do.
• Diagnostics. scripts/jit_diagnostics.py prints cmake's path and
  jit_use_cmake, times the diagnostic type's registration, and ends with a new
  section that sets "on" as init does, with burble on, then prints the resulting
  control and how long the probe took, through cmake or the compiler. When
  fix_jit_config() returns None it now says "no compiler found to repair from"; it
  said "no conda", also with CONDA_PREFIX set.
• Docs. The user guide's JIT section says that on Windows "on" needs cmake
  (conda install cmake) and Visual Studio or its Build Tools rather than the
  configured compiler, that UDT work does not raise the default "run" there, and that a
  new kernel takes about 10 seconds through cmake on Windows. The UDT page's list of
  what raises "run" gains the exception, and so do the jit_c_control and
  jit_use_cmake entries of gb.ss.config.

Cost of a kernel through cmake

In that CI run the test made exactly one cold compile through cmake per Windows job, so
the time it took measures one kernel. Over the 81 jobs: median 10.4 s, 90th percentile
16.2 s, fastest 2.6 s, slowest 56 s. Each kernel gets a fresh build directory and a
fresh cmake configure, so a real kernel costs at least this much. For comparison, on an
M-series Mac the probe compiles in 0.2 to 0.3 s directly and in about 0.6 s through
cmake with its Makefile generator.

What Windows CI should show

• JIT diagnostics: a cmake: which=... line and jit_use_cmake: True. The "JIT
  compilation test" still fails under the default "run", now with the cmake message.
  The new last section shows the cmake and MSBuild output, then Result: on and
  Probe through cmake: N s, one more sample of the cost above in every job. A wheel
  draw (SuiteSparse without the JIT) shows Result: run and No probe: ....
• Tests: on JIT draws, test_ss_import_leaves_jit_c_control_alone[on] (a fresh
  process with GRAPHBLAS_JIT_C_CONTROL=on) and
  test_set_jit_c_control_at_init_compiles_through_cmake assert "on" after a real
  compile through cmake; if it fails, the assertion asks whether Visual Studio's C
  compiler is installed. The rest of test_ssjit.py still skips its JIT tests on
  Windows (see the second question below), and the tests that need UDT work to raise
  "run" skip wherever SuiteSparse compiles only through cmake.

Tested locally on macOS (arm64, SuiteSparse 10.5.2, cmake 4.3): test_ssjit.py and
test_core.py with --runslow (90 passed, 1 skipped), and test_op.py and
test_dtype.py with --runslow. The cmake branches ran there with jit_use_cmake set
to True, including a real probe through cmake on a fresh cache; MSVC and the Visual
Studio generator run only on CI.

Open questions

1. Should UDT work ever use cmake by default? In this PR it never does. At about
   10 s per kernel, a session that touches a handful of UDT operations would wait tens
   of seconds to minutes the first time (the cache keeps the kernels for later runs).
   Without it, Windows users get the Numba fallback, typically 2 to 3 times slower for
   elementwise operations, unless they set "on".
2. fix_jit_config() in the tests' _setup_jit. It repairs only the compiler path,
   so on Windows it returns None and test_ssjit.py compiles no JIT kernels there.
   Making it accept cmake would run them all through cmake: test_ssjit.py and
   test_core.py compile about 261 kernels into a fresh cache, roughly 45 minutes per
   Windows job at 10 s each.

🤖 Generated with Claude Code