Skip to content

INSTALL.md: document the installers, the tested configurations, and packaging - #191

Closed
mmelnich wants to merge 1 commit into
randblas-install-ps1from
randblas-install-docs
Closed

INSTALL.md: document the installers, the tested configurations, and packaging#191
mmelnich wants to merge 1 commit into
randblas-install-ps1from
randblas-install-docs

Conversation

@mmelnich

Copy link
Copy Markdown
Contributor

Problem

INSTALL.md opened by describing the manual build, which is now the longer path; said nothing about the installer scripts; had no statement of which configurations are actually tested (you had to read the workflow files); had nothing for packagers; and one claim was wrong.

What this PR does

A quick-start section at the top. The installers are the shortest path to a working RandBLAS, so they come first. It states the toolchain contract plainly — you bring a C++20 compiler, CMake 3.21 and Git; the script supplies everything above that, and installs nothing system-wide. It also covers the two things people will otherwise get wrong: sharing one dependency tree with RandLAPACK via RANDNLA_PROJECT_DIR, and why examples/ is opt-in.

Appendix B.1, a tested-configuration table. Every row is a CI lane, so it is a claim about what is exercised on every commit rather than what we believe should work, with the compiler floor (gcc ≥ 13, for C++20 concepts) stated up front.

Appendix B.2, the integer-width policy — ILP64 wherever the backend can genuinely provide it, LP64 where it cannot, with the reason per backend. The OpenBLAS case is worth reading: BLAS++ probes int32 before int64 and blas_int only filters library names, so for MKL the choice is real and verifiable, while for OpenBLAS an LP64 build passes the int32 probe and is accepted. Anyone with an ILP64 OpenBLAS has to point at it explicitly with --blas=custom, and the docs now say so instead of leaving it to be discovered.

Appendix B.3, the packaging contract for conda-forge and Spack: which dependencies are genuinely required, that nothing is downloaded during configure, that LP64 is the default and therefore agrees with conda-forge's libblas metapackage, that RandBLAS never selects a BLAS itself so BLA_VENDOR stays with the packager, and that the installed package relocates correctly.

One correction. The guide said RandBLAS selects /openmp:experimental under MSVC. It selects /openmp:llvm, and has since #184.

Notes for reviewers

…ackaging

Three additions and one correction.

A quick-start section at the top, because the installers are now the shortest
path to a working RandBLAS and the guide opened by describing the manual one.
It states the toolchain contract plainly -- you bring a C++20 compiler, CMake
3.21 and Git, the script supplies everything above that -- and covers sharing
a dependency tree with RandLAPACK through RANDNLA_PROJECT_DIR, and why
examples are opt-in.

Appendix B, a tested-configuration table. Every row is a CI lane, so it says
what is actually exercised rather than what we believe should work. It also
explains the integer-width policy and, in particular, why OpenBLAS is the
awkward case: BLAS++ probes int32 before int64 and blas_int only filters
library names, so for MKL the choice is real and verifiable while for OpenBLAS
an LP64 build passes the int32 probe and is accepted. Anyone with an ILP64
OpenBLAS has to point at it explicitly, and now the documentation says so.

Appendix B also carries the packaging contract for conda-forge and Spack:
which dependencies are actually required, that nothing is downloaded during
configure, that LP64 is the default and therefore agrees with conda-forge's
libblas metapackage, that RandBLAS never selects a BLAS itself, and that the
installed package relocates correctly.

Correction: the guide said RandBLAS selects /openmp:experimental under MSVC.
It selects /openmp:llvm, and has since #184.
@rileyjmurray
rileyjmurray force-pushed the randblas-install-docs branch from de007bd to 27f3262 Compare August 13, 2026 17:11
@mmelnich

Copy link
Copy Markdown
Contributor Author

Folded into #187 at Riley's request ("please combine PRs 187, 190, and 191 — they have no business landing separately"). The commit is unchanged, now sitting on randblas-install-sh alongside the rest of the installer work. Nothing was dropped: the consolidated branch's tree is byte-identical to the state that was tested and green here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant