| name | nosphera2-build-system |
| description | Use when working in the NoSpherA2 repository on CMake presets, dependency bootstrap/cache flow, build targets, tests, CI build failures, runtime-library copying, or agent guidance updates after the build-system restructure. |
NoSpherA2 Build System
Start Here
Treat CMakePresets.json, the top-level CMakeLists.txt, and .github/workflows/c-cpp_all.yml as the current sources of truth. Older notes may mention removed preset names such as windows-msvc-release-full, linux-gcc, macos-release-full-arm64, or windows-msvc-debug; verify against the live preset file before using them.
For a fresh checkout, bootstrap dependencies first:
cmake -P scripts/BootstrapMicromamba.cmake
Then configure/build with an active preset:
cmake --preset release-windows
cmake --build --preset release-windows
Common preset families are:
- Windows:
release-windows, debug-windows
- Linux:
release-linux, debug-linux
- macOS:
release-macos-arm64, release-macos-x86_64, debug-macos-arm64, debug-macos-x86_64
- macOS universal build target:
cmake --build --preset release-macos-universal
Use cmake --list-presets=all for a complete view. A plain cmake --list-presets can hide configure presets that do not match the host platform.
Target Layout
The top-level CMake project configures dependencies and then builds project targets:
libcint, occ, mdspan, and featomic/featomic are consumed with add_subdirectory.BasisSetGenerator builds BasisSetConverter, which generates Src/basis_data.cpp.Src/core builds the static NoSpherA2Core target and alias NoSpherA2::Core.app builds the NoSpherA2 executable.Src/dll builds the optional DLL when NOSPHERA2_BUILD_DLL=ON.tests/src builds NoSpherA2_Tests when NOSPHERA2_BUILD_TESTS=ON.
Runtime outputs are under the preset build tree's bin directory, for example build/release-windows/bin/NoSpherA2.exe.
CMake Options
- Use
-DNOSPHERA2_BUILD_TESTS=ON before running CTest.
- Use
-DNOSPHERA2_BUILD_DLL=ON only when the Windows DLL target is needed.
- Use
-DNOSPHERA2_DEPENDENCIES_ONLY=ON only for dependency-cache or dependency-prebuild workflows. The top-level CMakeLists.txt returns before adding NoSpherA2 targets in this mode.
CI restores or builds a dependency-only tree, saves that cache, then reconfigures the same build directory with NOSPHERA2_BUILD_TESTS=ON and NOSPHERA2_DEPENDENCIES_ONLY=OFF.
Tests
Preferred CMake validation:
cmake --preset <preset> -DNOSPHERA2_BUILD_TESTS=ON
cmake --build --preset <preset>
ctest --preset <preset> --output-on-failure
Python golden-file tests remain available:
uv run pytest
Set NOS_EXE for Python tests when the executable is not on PATH. Set OCC_DATA_PATH when the runtime data path is not discoverable; CTest defaults this to occ/share.
When adding or changing tests, keep tests/tests.toml, tests/src, Windows/Tests/Tests.cpp, and UNIT_TESTS_STATUS.md aligned for the affected coverage.
Windows Notes
For preset builds on Windows, use an x64 Visual Studio Developer shell or another environment where Ninja can find cl.exe and the MSVC headers. Missing standard headers such as stdlib.h, string.h, or stdio.h usually indicate shell/toolchain setup, not a broken source rewrite.
The Visual Studio solution under Windows/ is legacy but still useful for DLL/OCC integration debugging. VS tests must remain in-process through NoSpherA2_DLL.dll; do not add subprocess fallbacks for crashing tests.
The VS NoSpherA2/NoSpherA2_LIB projects share an OutDir (Windows\Windows_utils\NoSpherA2_universal.props) pointing at build\$(Configuration)_$(Platform)\ (e.g. build\Release_x64\NoSpherA2.exe) — a sibling of, but distinct from, the CMake preset output build\release-windows\bin\NoSpherA2.exe. Windows\Tests\Tests.vcxproj was not repointed and still builds to Windows\Tests\$(Configuration)_$(Platform)\.
Dependency Boundaries
Do not edit submodules casually. Prefer parent-project CMake or generated-source workarounds when fixing integration issues from the parent repository.
The parent project currently rewrites selected libcint source files under the build tree to make #pragma GCC ivdep portable to MSVC. Preserve this parent-side approach unless the user explicitly asks for a submodule fix.
