8. Building and Integration

8.1. Requirements

The library requires CMake 3.24 or newer and a C++23 compiler. It has no third-party runtime or numerical dependency. Tests, examples, and command-line tools also use only the standard library.

Documentation additionally requires Doxygen and Python packages from docs/requirements.txt. PDF generation requires latexmk and a LaTeX installation; HTML can be built without LaTeX.

8.2. Recommended Local Build

The routine checked build is:

./scripts/build.sh

It performs these steps:

configures a fresh CMake build with strict warnings;
compiles the static library, examples, tests, and tools;
runs the numerical regression suite;
stages an installation inside the build tree; and
configures, links, and tests an independent find_package consumer.

Generate both manuals only when needed:

./scripts/build.sh --docs

The documentation Python environment is package-local at .venv-docs and is created only for a documentation build.

8.3. Custom Build Directory

Use a command-line option:

./scripts/build.sh --build-dir build-gcc

or the equivalent environment variable:

WIGNER_BUILD_DIR=build-gcc ./scripts/build.sh

Relative paths are interpreted from the directory where the script is invoked, then converted to absolute paths before nested package checks run. This lets several compiler or configuration builds coexist predictably.

8.4. Choosing a Compiler

Set CXX before the first configuration of a build directory:

CXX=g++-14 ./scripts/build.sh --build-dir build-gcc14
CXX=clang++ ./scripts/build.sh --build-dir build-clang

Because the script requests a fresh configuration, changing CXX while reusing a scripted build directory is safe. For manual incremental work, use a separate build directory when changing compilers so cached compiler and ABI information cannot mix.

8.5. Manual CMake Build

The equivalent ordinary build is:

cmake -S . -B build \
    -DWIGNER_BUILD_TESTS=ON \
    -DWIGNER_BUILD_EXAMPLES=ON \
    -DWIGNER_BUILD_EXECUTABLES=ON \
    -DWIGNER_BUILD_DOCUMENTATION=OFF \
    -DWIGNER_WARNINGS_AS_ERRORS=ON
cmake --build build --parallel
ctest --test-dir build --output-on-failure

For an optimized library build, select a configuration appropriate to the generator, for example -DCMAKE_BUILD_TYPE=Release with a single-config generator.

8.6. Installing Wigner

The convenience installer reuses a valid existing build. If none exists, it runs the complete checked build first:

./scripts/install.sh

The default destination is $HOME/.local. Select another prefix explicitly:

./scripts/install.sh --install-dir "$HOME/software/wigner"

Build and installation directories are separate concepts. The build directory holds compiler output and tests; the installation directory holds the public headers, libwigner.a, CMake package files, tools, and documentation.

Both locations also have environment-variable forms:

WIGNER_BUILD_DIR=build-release \
WIGNER_INSTALL_DIR="$HOME/software/wigner" \
    ./scripts/install.sh

Add --docs when the installation must include generated HTML and PDF manuals. Without that flag, authored documentation is still installed but a missing generated manual does not force a rebuild.

8.7. Using an Installed Package

An application uses the exported target:

find_package(wigner CONFIG REQUIRED)
target_link_libraries(my_analysis PRIVATE wigner::wigner)

For a nonstandard prefix, configure the application with:

cmake -S . -B build \
    -DCMAKE_PREFIX_PATH="$HOME/software/wigner"

The imported target supplies the include directory, static archive, and C++23 language requirement. Client code should not include wigner/detail; private implementation headers are not installed.

8.8. Using Wigner as Source

A parent CMake project may also add the source tree:

add_subdirectory(path/to/wigner)
target_link_libraries(my_analysis PRIVATE wigner::wigner)

Tests, examples, and tools default off when Wigner is not the top-level project, so the dependency adds only the library unless the parent explicitly enables more targets.

8.9. Documentation Targets

Enable documentation manually with:

cmake -S . -B build-docs \
    -DWIGNER_BUILD_DOCUMENTATION=ON \
    -DWIGNER_BUILD_PDF_DOCUMENTATION=ON
cmake --build build-docs --target wigner_docs

For HTML only, set WIGNER_BUILD_PDF_DOCUMENTATION=OFF. The individual targets are wigner_doxygen, wigner_docs_html, and, when enabled, wigner_docs_pdf.

8.10. CMake Options

Wigner configuration options
Option	Direct-build default	Purpose
`WIGNER_BUILD_TESTS`	ON	Build and register the regression tests.
`WIGNER_BUILD_EXAMPLES`	ON	Build the compiled teaching examples.
`WIGNER_BUILD_EXECUTABLES`	ON	Build the inspection tools.
`WIGNER_BUILD_DOCUMENTATION`	OFF	Enable Doxygen and Sphinx targets.
`WIGNER_BUILD_PDF_DOCUMENTATION`	ON	Add PDF output when documentation is enabled.
`WIGNER_WARNINGS_AS_ERRORS`	OFF	Make package-local compiler warnings fatal.

8.11. Version Compatibility

The package is currently pre-1.0. CMake package-version compatibility is therefore limited to the same minor release: patch releases are compatible, while a new minor version may revise the API. Compile-time version constants are available from wigner/version.hpp and through the umbrella header.