.. SPDX-License-Identifier: MIT Building and Integration ======================== 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. Recommended Local Build ----------------------- The routine checked build is: .. code-block:: console ./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: .. code-block:: console ./scripts/build.sh --docs The documentation Python environment is package-local at ``.venv-docs`` and is created only for a documentation build. Custom Build Directory ---------------------- Use a command-line option: .. code-block:: console ./scripts/build.sh --build-dir build-gcc or the equivalent environment variable: .. code-block:: console 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. Choosing a Compiler ------------------- Set ``CXX`` before the first configuration of a build directory: .. code-block:: console 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. Manual CMake Build ------------------ The equivalent ordinary build is: .. code-block:: console 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. Installing Wigner ----------------- The convenience installer reuses a valid existing build. If none exists, it runs the complete checked build first: .. code-block:: console ./scripts/install.sh The default destination is ``$HOME/.local``. Select another prefix explicitly: .. code-block:: console ./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: .. code-block:: console 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. Using an Installed Package -------------------------- An application uses the exported target: .. code-block:: cmake find_package(wigner CONFIG REQUIRED) target_link_libraries(my_analysis PRIVATE wigner::wigner) For a nonstandard prefix, configure the application with: .. code-block:: console 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. Using Wigner as Source ---------------------- A parent CMake project may also add the source tree: .. code-block:: cmake 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. Documentation Targets --------------------- Enable documentation manually with: .. code-block:: console 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``. CMake Options ------------- .. list-table:: Wigner configuration options :header-rows: 1 :widths: 42 18 40 * - 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. 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.