Handover: install-story cleanup — preflight, BLAS surfacing, macOS Python guidance¶

Filed: 2026-05-16, install-docs chat Status: four commits shipped to main (c277c95 → ff25b0e → 40fbbcb → 022c68f). One open thread documented in § “Open: preflight gap I couldn’t reproduce” below. Next chat continues on: different physical machine. Roadmap direction unchanged — see § “Where to pick up the roadmap” at the bottom.

TL;DR¶

Mike hit a fresh-macOS install failure: setup_native_deps.sh died mid-build_libint.sh because cmake / ninja / libomp / etc. weren’t installed yet. The user-facing docs also still advertised pip install vibe-qc (vibe-qc isn’t on PyPI). This session fixed the install story end-to-end:

setup_native_deps.sh now runs a comprehensive preflight that verifies build tooling, headers, OpenMP, BLAS, and Python ≥3.11 before any building happens. Missing items get accumulated into a single consolidated report with copy-paste per-distro install one-liners.
The _safe_build_env.sh helper (sourced by every build_*.sh) also runs a minimal cmake+ninja check so direct invocation of any build_*.sh is also caught upfront (not just via setup_native_deps.sh).
Docs (docs/installation.md, docs/quickstart.md, README.md) scrubbed of misleading pip install vibe-qc claims and rewritten to surface BLAS as a first-class linked dependency.
macOS-specific Python footgun documented: Apple’s /usr/bin/python3 is currently 3.9 and does not meet the ≥3.11 minimum from pyproject.toml; the preflight catches this case explicitly and prints the brew install python@3.14 + eval "$(brew shellenv)" + brew link --overwrite --force recovery recipe.
Eigen check unified across macOS/Linux to use pkg-config eigen3 first with a broader header-path fallback. Homebrew’s eigen formula is currently 5.0.1; called this out in both the Requirements section and the macOS install section so users don’t worry when brew info eigen shows 5.x.

What shipped¶

Commit `c277c95` — docs + scripts: install preflight, BLAS surfacing, macOS python guidance¶

The big one (21 files, +693/−134):

scripts/setup_native_deps.sh — entire preflight added. Verifies: cmake (≥3.20), ninja, make, git, curl, tar, pkg-config, a C++17 compiler, python3 (≥3.11), libomp (macOS), Boost / Eigen / GMP headers, BLAS+LAPACK (Apple Accelerate confirmed on macOS; OpenBLAS / MKL detected on Linux; netlib → soft warning; missing → hard fail with install command). Bails with one consolidated report. Honors WITH_OPENBLAS=1 (gfortran becomes required) and VIBEQC_SKIP_PREFLIGHT=1 (skip the check; not recommended).
docs/installation.md — BLAS in the opening linked-libs list, refreshed per-platform install commands (now include pkg-config, libopenblas-dev liblapacke-dev / blas-openblas / openblas-devel lapack-devel), added a Fedora/RHEL recipe, added macOS Python upgrade walkthrough with brew install python@3.14 + brew shellenv + brew link --overwrite --force fallback. Added “Preflight told me X is missing” + “python ≥3.11 on PATH” Common-issues entries.
docs/quickstart.md — pip install vibe-qc replaced with a “not on PyPI yet” callout pointing to installation.md.
README.md + AGENTS.md — corrected “PyPI distribution is pip install vibe-qc” lines, refreshed install blocks with new packages.
Swept stray pip install vibe-qc[…] strings from python/vibeqc/{runner,ase,ase_periodic,dispersion,benchmark,banner,__init__,basis_library/README}.py, scripts/{install_optional_tools.sh,fetch_bse_aux_bases.py}, examples/quickstart.py, tests/test_ecp_library.py, pyproject.toml, docs/tutorial/14_dispersion.md, docs/user_guide/{external_codes,output_files}.md.

Commit `ff25b0e` — scripts: cmake+ninja check in `_safe_build_env.sh` helper¶

Belt-and-braces. setup_native_deps.sh’s preflight catches missing ninja, but each build_*.sh can also be invoked directly (e.g. for a single-dep rebuild after a version bump). The helper now does a minimal cmake+ninja check that fires upfront for direct invocations.

To stay out of the way of the comprehensive preflight, the outer entry-points (setup_native_deps.sh, update.sh) export VIBEQC_TOOLING_CHECKED=1 before sourcing the helper. That suppresses the helper’s terse check (so the user sees the comprehensive preflight report instead) and propagates the marker to child build_*.sh so they also no-op. Opt-out: same VIBEQC_SKIP_PREFLIGHT=1.

Commit `40fbbcb` — preflight: unify eigen check via pkg-config + broader fallback paths¶

The original macOS branch only looked at hardcoded header paths and skipped pkg-config entirely. Brew actually ships eigen3.pc at /opt/homebrew/opt/eigen/share/pkgconfig/eigen3.pc, so pkg-config is the authoritative probe on Mac too. Extracted a _check_eigen helper that tries pkg-config eigen3 first, then falls back to a wider set of known header paths covering Apple Silicon + Intel Homebrew + /usr/local + Debian multi-arch + Arch/Fedora layouts. Both macOS and Linux preflight branches now call the same function.

Commit `022c68f` — docs/installation: Homebrew’s eigen 5.0.x is fine¶

Mirror the Arch section “Eigen 5.0.x is fine” callout into the macOS section so brew users seeing eigen: stable 5.0.1 from brew info eigen don’t worry they need to pin Eigen 3. Generalized the Requirements line too: Homebrew + Arch ship 5.0.x today, Debian/Ubuntu still ship 3.4.x, all three work because libint 2.13.1’s CMake module handles either layout.

Open: preflight gap I couldn’t reproduce¶

Mike reported, after c277c95 was on main:

ninja is also missing and not checked

I verified my preflight does catch missing ninja in both code paths (reproduced with env -i PATH=… shadowing). My guess at the actual symptom was: Mike was invoking a build_*.sh directly, where the helper-level check didn’t yet exist. Patched by ff25b0e.

Then:

it also not really checks for eigen

Same — my macOS eigen check was hardcoded paths only and didn’t use pkg-config. Patched by 40fbbcb.

What’s still unresolved: I never got the actual reproducer (command Mike ran + the preflight output he saw). Both fixes are my best-guess interpretation. The next chat, on the new machine, should:

Run ./scripts/setup_native_deps.sh on a fresh git clone with only stock tooling present.
Watch the preflight catch each missing tool in turn as prerequisites get installed.
If anything slips through, capture the exact command + output and either patch or file an issue against the install-story commits.

Where to pick up the roadmap¶

This session was a docs / install-tooling sweep, not a research arc. Roadmap-level work resumes from wherever the active periodic-SCF / molecular-methods / basissetdev chats left off — see:

docs/roadmap.md — milestone ladder v0.1 → v2.0.
docs/release_v0_8_0_prep.md — current minor-release prep state; Phase-by-phase status.
Any .release-status/v0.8.0/*.md drop-box files surviving in the destination machine’s checkout (per CLAUDE.md § 3 these are gitignored / local-only).
The periodic-SCF arc is now spread across two separate chats (GDF variant, dipole variant) running in isolation and converging on main post-hoc; the periodic handover docs that previously lived here were removed in the 2026-05-17 archive sweep (see git log --diff-filter=D --name-only docs/ for the manifest).

How to bootstrap the new machine¶

Per the (now-cleaned-up) docs/installation.md:

git clone https://gitlab.peintinger.com/mpei/vibeqc.git
cd vibeqc
./scripts/setup_native_deps.sh       # preflight + build, ~15–40 min
python3 -m venv .venv
.venv/bin/pip install -e '.[test]'

The preflight will tell you what to brew install / pacman -S / apt install / dnf install first if anything’s missing. On macOS, verify python3 --version shows ≥3.11 (Apple’s /usr/bin/python3 is 3.9 and too old); install brew install python@3.14 and run eval "$(/opt/homebrew/bin/brew shellenv)" if not.

Files touched (full list)¶

AGENTS.md
README.md
docs/installation.md
docs/quickstart.md
docs/tutorial/14_dispersion.md
docs/user_guide/external_codes.md
docs/user_guide/output_files.md
examples/quickstart.py
pyproject.toml
python/vibeqc/__init__.py
python/vibeqc/ase.py
python/vibeqc/ase_periodic.py
python/vibeqc/banner.py
python/vibeqc/basis_library/README.md
python/vibeqc/benchmark.py
python/vibeqc/dispersion.py
python/vibeqc/runner.py
scripts/_safe_build_env.sh
scripts/fetch_bse_aux_bases.py
scripts/install_optional_tools.sh
scripts/setup_native_deps.sh
scripts/update.sh
tests/test_ecp_library.py

23 files total across the 4 commits (some files touched by multiple commits).