INSTALL.md: document the installers, the tested configurations, and packaging - #191
Closed
mmelnich wants to merge 1 commit into
Closed
INSTALL.md: document the installers, the tested configurations, and packaging#191mmelnich wants to merge 1 commit into
mmelnich wants to merge 1 commit into
Conversation
…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
force-pushed
the
randblas-install-docs
branch
from
August 13, 2026 17:11
de007bd to
27f3262
Compare
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 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
INSTALL.mdopened 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 whyexamples/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
int32beforeint64andblas_intonly filters library names, so for MKL the choice is real and verifiable, while for OpenBLAS an LP64 build passes theint32probe 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
libblasmetapackage, that RandBLAS never selects a BLAS itself soBLA_VENDORstays with the packager, and that the installed package relocates correctly.One correction. The guide said RandBLAS selects
/openmp:experimentalunder MSVC. It selects/openmp:llvm, and has since #184.Notes for reviewers