Add installer scripts for Linux, macOS and Windows

[mmelnich]

Problem

RandBLAS has no installer. RandLAPACK's explicitly declines to cover it (install/install.sh: "RandBLAS is intentionally not covered: it stays a git submodule"), so anyone who wants RandBLAS on its own has to hand-build BLAS++ and Random123 and copy a cmake invocation out of INSTALL.md. Release-plan item B1.

Two audiences matter and only one of them runs a script. conda-forge and Spack never execute installers — they run cmake, often with no network. So the installer is a convenience for people, and the packaging-critical requirement is that plain CMake keeps working when nobody runs it. Both are covered.

What this PR adds

install/install.sh, install/install.ps1, an install-script workflow that exercises both, the documentation for them, and the console progress rendering.

Both scripts build into a RandNLA-project tree laid out exactly as RandLAPACK's installer lays one out, and both honour RANDNLA_PROJECT_DIR. Running both projects' installers on one machine therefore shares one dependency tree rather than building BLAS++ twice.

The integer width is read back, not assumed

The part most worth reviewing. BLAS++ probes int32 first and int64 second, and blas_int only filters which library names to consider (cmake/BLASFinder.cmake). That makes ILP64 genuinely detectable for MKL, where mkl_intel_ilp64 is a different library from mkl_intel_lp64 — but not for OpenBLAS, where BLAS++ only ever tries -lopenblas. An LP64 OpenBLAS passes the int32 probe and is accepted, so a successful blas_int=int64 configure proves nothing there.

The resolved width therefore comes from BLAS++'s generated blas/defines.h after the build. My first version recorded which configure attempt succeeded, which would have stamped an LP64 install as ILP64 and let every later run reuse it believing otherwise.

Resulting policy: ILP64 wherever it is real, LP64 with a named warning elsewhere. Accelerate is refused outright for ILP64 — Apple has shipped one since macOS 13.3, but BLAS++ implements only the legacy interface (icl-utk-edu/lapackpp#43, tracked our side as #189). An ILP64 OpenBLAS is reachable through --blas=custom.

Everything pinned, reuse gated on provenance

BLAS++ (3057185), Random123 (v1.14.0), GoogleTest (v1.18.0) and LAPACK++ (40b9d0d) at immutable refs — the same refs RandLAPACK validated. Each install and each source tree carries a provenance stamp and is reused only when it matches what we would build now, including backend and integer width. Without that, changing a pin is a silent no-op for anyone who already ran the script. The source stamp exists because a shallow checkout of a tag does not keep the tag ref locally.

On the Windows side this replaces Clone-Head, which took a branch name and returned early whenever the destination merely existed — so a branch tip could move between runs, and Random123 was fetched at its default branch entirely unpinned. It also moves BLAS++/LAPACK++ off the RaphaelArkadyMeyerNYU/* forks; both MSVC fixes merged upstream on 2026-08-06.

Verification runs, it does not just link

The final step compiles, links and runs a program against the finished install: it sketches a matrix, multiplies through BLAS++, and checks the result is symmetric positive semidefinite. Through BLAS++ rather than raw dgemm_, because that is how RandBLAS actually reaches the BLAS.

The x64 toolchain guard (Windows)

"Developer PowerShell for VS 2022" and "Developer Command Prompt for VS 2022" both default to an x86 toolchain, and an x86 linker cannot use the x64 import libraries every BLAS backend ships. Unchecked, the failure surfaces three layers down as BLAS++ reporting BLAS library not found. Shell bitness is not a usable signal either — the Developer Command Prompt is a 64-bit process that still selects x86 tools. toolchain-arch.ps1 reads VSCMD_ARG_TGT_ARCH, then the bin\Host<host>\<target>\ convention, then cl.exe's banner, and refuses x86 and arm64 with different messages because they need different answers.

Smaller decisions

• GoogleTest is provisioned, because BUILD_TESTS defaults to ON while find_package(GTest) is not REQUIRED — so a machine without it silently produces a build with zero tests.
• Examples are opt-in. They need two dependencies RandBLAS does not (LAPACK++, fast_matrix_market) and examples/CMakeLists.txt requires OpenMP, which stock Apple Clang cannot supply. Declining prints the exact follow-up command; it re-invokes the same script, so there is one code path.
• randblas_stage_runtime_dlls() is now exported from the installed package. Windows searches an executable's own directory first and PATH last, so a downstream project linking installed RandBLAS had no way to find the BLAS DLLs — the function lived only in the build tree. Found because the installer's own verification step is such a consumer.
• The clone is never moved. RandLAPACK's installer relocates its own repository into lib/, which breaks git worktrees. A symlink gives the same layout.
• The log is appended, not truncated — the previous run's output is what you want when this run fails the same way.
• .gitignore matched **install/, intended for build-output trees but also swallowing a source directory named install/. Narrowed to **/*-install/, the pattern RandLAPACK already uses; the !**install/.gitkeep exception it carried was vestigial.
• Progress rendering has three tiers: Unicode bar on a capable terminal, ASCII bar without colour or UTF-8, and one line per step when not a terminal. Tier 0 is a requirement rather than a fallback — redirected output becomes install.log and CI transcripts. The bar is determinate, parsed from Ninja's [12/34] and Make's [ 42%] on the stream already being captured.

CI

The install-script workflow asserts what the core workflows structurally cannot: idempotent re-runs, dependency discovery, the LP64 fallback warning firing for stock OpenBLAS, ILP64 for MKL, Accelerate refusing ILP64, and piped output containing no terminal escape sequences — which is what stops the progress bar from quietly filling every CI log.

A separate packager lane deliberately does not run the installer. It configures with plain CMake against hand-installed dependencies, inside a network namespace with no interfaces, then builds, installs and consumes the result via find_package. If that lane stays green a conda-forge recipe and a Spack package.py are possible.

Verification

Linux (gcc 15.2, oneAPI MKL):

Scenario	Result
Fresh MKL build	9/9 steps, ILP64 confirmed from blas/defines.h
Re-run in place	all six dependency steps reused, seconds
Dependency discovery (*_INSTALL_DIR pre-seeded)	all three reused, step count drops to 3/3
--examples	13/13 steps, all 7 binaries, fast_matrix_market at v1.7.6
--blas=openblas with no OpenBLAS present	clean failure naming both apt packages
--blas=accelerate --blas-int=ilp64	refused at argument parsing
Output redirected	no ANSI escapes, no carriage returns
Progress under a pty	advances 5% → 20% → 49% during the RandBLAS build

Windows 11, Windows PowerShell 5.1 (not pwsh 7), VS 2022 Build Tools:

Scenario	Result
Plain shell, no cl.exe/cmake	refused at preflight with the vcvars64 one-liner
Real x86 toolchain (vcvars32.bat, VSCMD_ARG_TGT_ARCH=x86)	refused with the x86-specific explanation
Full x64 install from scratch	oneMKL via vcpkg, BLAS++, GoogleTest, RandBLAS
Verification program	compiled, linked, staged its DLLs, ran, reported ILP64

All install-script lanes green, including the offline packager lane.

Notes for reviewers

• This PR was consolidated from Add installer scripts for Linux, macOS and Windows #187 + Add install/install.ps1, and pin the Windows dependency provisioner #190 + INSTALL.md: document the installers, the tested configurations, and packaging #191 + install.sh: draw a real progress bar during the build steps #192 per Riley's request. install.sh: draw a real progress bar during the build steps #192 was included for the same reason the other two were — it edits the install.sh this PR introduces — though only three were named. The tree is byte-identical to the state that was tested and green as four separate PRs.
• Two bugs here were only reachable on real hardware, which is worth knowing for how this gets reviewed. $LASTEXITCODE is unset until some native command runs and Set-StrictMode makes reading an unset variable an error, so the installer failed on exactly the runs where every dependency was cached. And the missing randblas_stage_runtime_dlls export only appears when something consumes the installed package.
• vcpkg is kept, deliberately. My plan called for replacing it with pinned NuGet as RandLAPACK did, but Windows: fetch oneMKL through vcpkg manifest mode (fixes setup on VS-bundled vcpkg) #185 had just made vcpkg work in manifest mode with a pinned baseline, and ripping that out immediately would be churn. Worth revisiting: the vcpkg oneMKL path expanded to 6.2 GB on disk during testing, against roughly 155 MB for RandLAPACK's NuGet fetch.
• Windows CI for the installer itself is not added here; the existing core-windows lanes cover the provisioner changes.

[mmelnich]

Combined — #190, #191 and #192 are now folded in here and closed, and the description above is rewritten to cover the whole thing as one change.

Two notes on what I did with the edges of your request:

#192 came along too, though you named only three. It was pushed last so you likely hadn't seen it; it adds the progress rendering to the install.sh this PR introduces, so it belongs to the same unit by exactly the reasoning you gave. Say the word and I'll pull it back out.

#186 stayed separate and has since merged. It was CMake hygiene with no dependency on the installer — the version floor, the fast_matrix_market pin, the configuration summary — so it stood on its own. This PR is now based on main with that included.

Nothing was lost in the consolidation: the branch had been rebased onto main after #186 merged, so rather than force-pushing my local stack over it I replayed the three remaining commits on top. The resulting tree is byte-identical to what was tested and green across the four PRs, which I checked rather than assumed.

One thing in the description worth your attention specifically, since it is the load-bearing decision: BLAS++ probes int32 before int64 and blas_int only filters library names. That makes ILP64 verifiable for MKL and not for OpenBLAS, so the installer reads the width back out of the generated blas/defines.h rather than trusting that its request was honoured. My first version trusted the request, which would have stamped LP64 installs as ILP64 and had every subsequent run reuse them believing otherwise.