besa 0.1.0__tar.gz

besa-0.1.0/.clang-format

@@ -0,0 +1,76 @@
+#-------------------------------------------------------------------------------
+# SPDX-License-Identifier: Apache-2.0
+#-------------------------------------------------------------------------------
+---
+Language:        Cpp
+# BasedOnStyle:  LLVM
+AccessModifierOffset: -2
+AlignAfterOpenBracket: AlwaysBreak
+AlignEscapedNewlinesLeft: false
+AlignOperands:   true
+AlignTrailingComments: true
+AllowAllParametersOfDeclarationOnNextLine: true
+AllowShortBlocksOnASingleLine: false
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortIfStatementsOnASingleLine: false
+AllowShortLoopsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: InlineOnly
+AlwaysBreakAfterDefinitionReturnType: false
+AlwaysBreakTemplateDeclarations: true
+AlwaysBreakBeforeMultilineStrings: true
+BreakBeforeBinaryOperators: true
+BreakBeforeTernaryOperators: true
+BreakConstructorInitializersBeforeComma: false
+BinPackParameters: false
+BinPackArguments: false
+ColumnLimit:  100
+ConstructorInitializerAllOnOneLineOrOnePerLine: true
+ConstructorInitializerIndentWidth: 0
+DerivePointerAlignment: false
+ExperimentalAutoDetectBinPacking: false
+IndentCaseLabels: false
+IndentWrappedFunctionNames: false
+IndentFunctionDeclarationAfterType: false
+MaxEmptyLinesToKeep: 1
+KeepEmptyLinesAtTheStartOfBlocks: true
+NamespaceIndentation: None
+ObjCBlockIndentWidth: 2
+ObjCSpaceAfterProperty: false
+ObjCSpaceBeforeProtocolList: true
+PenaltyBreakBeforeFirstCallParameter: 19
+PenaltyBreakComment: 300
+PenaltyBreakString: 1000
+PenaltyBreakFirstLessLess: 120
+PenaltyExcessCharacter: 1000000
+PenaltyReturnTypeOnItsOwnLine: 1000000
+PointerAlignment: Left
+SpacesBeforeTrailingComments: 1
+Cpp11BracedListStyle: true
+Standard:        Cpp11
+IndentWidth:     2
+TabWidth:        2
+UseTab:          Never
+BreakBeforeBraces: Stroustrup
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+SpacesInAngles:  false
+SpaceInEmptyParentheses: false
+SpacesInCStyleCastParentheses: false
+SpaceAfterCStyleCast: false
+SpacesInContainerLiterals: true
+SpaceBeforeAssignmentOperators: true
+ContinuationIndentWidth: 2
+CommentPragmas:  '^ IWYU pragma:'
+SortIncludes: 'CaseSensitive'
+SpaceBeforeParens: ControlStatements
+DisableFormat:   false
+StatementMacros: [
+  'NOLA_GLOBAL',
+  'NOLA_HOST',
+  'NOLA_DEVICE',
+  'NOLA_HOST_DEVICE'
+]
+---
+Language: Json
+DisableFormat: true
+---

besa-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,52 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+
+      - name: Install Python
+        run: uv python install
+
+      - name: Build ProperDocs site
+        run: uv run --group docs properdocs build --strict
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload GitHub Pages artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

besa-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+.pytest_cache/
+.venv/
+build/
+dist/
+*.egg-info/
+.spack-env/
+spack.lock

besa-0.1.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.5
+Name: besa
+Version: 0.1.0
+Summary: Declarative project development tooling for CMake and Python projects
+Project-URL: Documentation, https://ambhora.github.io/besa/
+Project-URL: Source, https://github.com/ambhora/besa
+Author-email: Jayesh Badwaik <j.badwaik@fz-juelich.de>
+License-Expression: Apache-2.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# BESA
+
+BESA is project-development tooling for declarative, self-contained build descriptions. Its current
+focus is C++/CMake plus a minimal Python project generator.
+
+```console
+uv run besa cpp generate --path /tmp --name example
+cd /tmp/example
+cmake --workflow --preset gcc --fresh
+```
+
+A generated C++ project vendors the BESA CMake implementation under `cmake/besa`; it does not require
+BESA to remain installed in order to build.
+
+Run the BESA regression suite with:
+
+```console
+uv run --group test pytest --basetemp=build/test
+```
+
+Build the ProperDocs site with:
+
+```console
+uv run --group docs properdocs build
+```
+
+See the full documentation under `docs/` or the GitHub Pages site.

besa-0.1.0/docs/explanation/configuration-lifecycle.md

@@ -0,0 +1,28 @@
+# Configuration lifecycle
+
+BESA deliberately separates configuration selection from project construction.
+
+Before `besa_configure_complete()`, the project declares the configuration sets which it owns:
+features, default features, test modes, and default test modes. It may also register feature,
+devtool, and test-mode constraints. Devtool and warning capability names themselves are supplied by
+BESA, so projects select them but do not redeclare their allow-lists.
+
+`besa_configure_complete()` then resolves four independent families:
+
+1. `PROJECT_FEATURES` over the project's feature defaults;
+2. `PROJECT_DEVTOOLS` over BESA's supported devtools;
+3. `TEST_MODES` over the project's test-mode defaults;
+4. `PROJECT_WARNINGS` over BESA's supported warning policies.
+
+Duplicate or unknown selections are rejected first. Project constraints run against the fully
+resolved feature/devtool/test-mode sets next. Only after every constraint succeeds does BESA publish
+the resolved booleans, enable compiler languages implied by `toolchain-*`, and create any
+compiler-dependent instrumentation policy.
+
+After this phase boundary, dependencies, directories, targets, and tests are processed against a
+frozen configuration. This prevents a dependency or subdirectory from implicitly changing the
+meaning of configuration selection halfway through a configure run.
+
+Project-wide packaging and instrumentation reporting need the final target/dependency graph. BESA
+therefore schedules those operations with CMake's deferred-call mechanism and executes them after the
+project tree has been processed.

besa-0.1.0/docs/explanation/dependencies.md

@@ -0,0 +1,17 @@
+# Dependency model
+
+BESA separates **why** a dependency exists from **how** CMake discovers it.
+
+`KIND` is one of `NORMAL`, `BUILD`, or `DEV`. Normal dependencies belong to the product and are
+written into generated consumer package metadata. Build dependencies are needed to construct the
+software but not to consume it. Dev dependencies belong to testing, documentation, analysis, or
+other development workflows and are never propagated to consumers.
+
+`PROVIDER` currently distinguishes `CMAKE` from `PKGCONFIG`. The CMake provider deliberately relies on
+`find_package()` rather than requiring a particular metadata format. Consequently a dependency can
+move from a traditional CMake package config toward CPS when the active CMake/dependency supports it
+without changing the BESA project declaration.
+
+This information is intentionally richer than a raw `find_package()` call because it is also the
+foundation for a future package/build model in which normal, build, and dev dependency graphs can be
+handled differently.

besa-0.1.0/docs/explanation/features-and-instrumentation.md

@@ -0,0 +1,25 @@
+# Configuration families are intentionally orthogonal
+
+BESA keeps several configuration concepts separate because they answer different questions.
+
+A **feature** changes project capability or topology: examples are `build-source`, `toolchain-cuda`, `toolchain-hip`, `toolchain-asm`,
+`project-kosha25`, and `user-docs`. Feature names and defaults are defined by the project. Feature
+selectors decide whether directories and dependencies participate in the project graph.
+
+A **devtool** changes how existing targets are instrumented or checked: examples are ASan, coverage,
+clang-tidy, formatting, and surrogate-header validation. Devtool names are capabilities defined by
+BESA; the project only selects which ones to use. Project-specific constraints may still reject
+particular combinations.
+
+A **warning policy** modifies compiler diagnostics. Warning policies are also defined by BESA and are
+composable: `essential;error` means “enable the essential warning set and promote warnings to
+errors.” They do not alter project topology.
+
+A **test mode** is a project-defined workflow selector. Tests state which modes they support, and are
+built/registered only when at least one supported mode is enabled. BESA gives the names no intrinsic
+meaning.
+
+This separation keeps source build descriptions stable as project workflows and developer tooling
+evolve. A future BESA version can change coverage implementation, add another warning policy, or add
+a new devtool without forcing projects to rewrite target construction code. Conversely, projects can
+add new feature or test-mode names without requiring changes to BESA.

besa-0.1.0/docs/explanation/self-contained-projects.md

@@ -0,0 +1,14 @@
+# Why generated C++ projects vendor BESA
+
+The Python package is a development tool, not a runtime requirement of generated C++ software.
+`besa cpp generate` copies the current CMake implementation into `cmake/besa`, and the generated
+project finds that local package explicitly.
+
+This has two useful consequences. First, a source checkout remains buildable on a machine which has
+CMake and the project's actual dependencies but no Python BESA installation. Second, upgrading the
+build abstraction is explicit: `besa cpp update` replaces only the BESA-managed module directory and
+never rewrites project-owned CMake.
+
+The generated project's installed CMake package also does not depend on BESA. Target instrumentation
+is build-interface-only and BESA emits normal consumer dependency discovery directly into the
+project's own `<project>Config.cmake`.

besa-0.1.0/docs/how-to/cpp-user-docs.md

@@ -0,0 +1,180 @@
+# Build C++ user documentation
+
+Generated C++ projects publish one documentation site with two rendering layers:
+
+```text
+ProperDocs                            -> site root and prose/information architecture
+Doxygen XML -> Breathe -> Sphinx     -> versioned C/C++ API reference
+```
+
+ProperDocs is always canonical. The Sphinx/Breathe output is mounted below
+`reference/api/<version>/` and every API page contains links back to the main ProperDocs site and the
+API-version landing page.
+
+## Enable the documentation feature
+
+```bash
+cmake -S . -B build -DPROJECT_FEATURES=user-docs
+```
+
+The documentation toolchain requires `properdocs`, `doxygen`, `dot`, `sphinx-build`, Breathe, and
+`sphinx-multiversion`.
+
+## Author the main site
+
+The generated project keeps the two source trees separate:
+
+```text
+properdocs.yml
+
+docs/                       # ProperDocs Markdown
+├── index.md
+└── reference/
+    ├── index.md
+    └── api.md
+
+api-docs/                   # API renderer only
+├── conf.py
+├── Doxyfile
+├── index.rst
+├── api.rst
+└── _templates/
+    └── versioning.html
+```
+
+Because `properdocs.yml` is checked in at the project root, normal ProperDocs authoring works without
+CMake:
+
+```bash
+properdocs serve
+```
+
+The API landing page contains a static `main` fallback for this mode. The complete CMake publication
+build loads the full version list from the generated `versions.json`.
+
+## Build the complete publication site
+
+Commit the API documentation files before a multiversion build, then run:
+
+```bash
+cmake --build build --target user.docs
+```
+
+`user.docs` performs three steps:
+
+1. ProperDocs builds the main site.
+2. sphinx-multiversion builds the API reference for selected local branch heads and tags; each Sphinx
+   build runs Doxygen at `builder-inited`, and Breathe consumes that checkout's Doxygen XML.
+3. BESA assembles the API tree below the ProperDocs API landing page.
+
+The final deployable directory is:
+
+```text
+build/doc/site/
+├── index.html
+├── reference/
+│   └── api/
+│       ├── index.html          # ProperDocs landing page
+│       ├── versions.json       # generated by BESA
+│       ├── main/
+│       ├── v0.1.0/
+│       └── v0.2.0/
+└── .nojekyll
+```
+
+Upload the contents of `build/doc/site/` as the GitHub Pages artifact. ProperDocs' own `index.html`
+remains the site root; no redirect wrapper is required.
+
+## Build only the API renderer
+
+The current checkout can be rendered independently with:
+
+```bash
+cmake --build build --target user.docs.api
+```
+
+Build all selected refs without assembling the ProperDocs site with:
+
+```bash
+cmake --build build --target user.docs.multiversion
+```
+
+The raw multiversion API output is:
+
+```text
+build/doc/api/multiversion/
+├── versions.json
+├── main/
+├── v0.1.0/
+└── v0.2.0/
+```
+
+This directory is an API component, not the final website.
+
+## Navigation back to ProperDocs
+
+`api-docs/_templates/versioning.html` adds two persistent entries to the Sphinx sidebar:
+
+- **Main documentation** returns to the ProperDocs site root.
+- **API versions** returns to the ProperDocs `reference/api/` landing page.
+
+BESA computes the number of path levels from the configured API mount point and passes it to Sphinx.
+The links are therefore relative and do not depend on a GitHub Pages repository prefix, hostname, or
+custom domain.
+
+## CI and remote branch heads
+
+sphinx-multiversion builds local branch heads and tags by default. In CI, make sure the refs you want
+to publish are fetched. If you explicitly want remote refs instead, configure sphinx-multiversion in
+`api-docs/conf.py`.
+
+## Install built documentation
+
+After building `user.docs`, a normal CMake install includes the complete assembled site:
+
+```bash
+cmake --install build --prefix <prefix>
+```
+
+The site is installed below `share/doc/<project>/`. The install source is optional, so installing a
+library/binary build that never built documentation still succeeds.
+
+## Develop documentation from the Spack environment
+
+Generated C++ projects include an independent Spack environment whose root package is
+`<project>-dev-env`. Its variants select development dependencies; they are intentionally independent
+of BESA/CMake feature selection for now.
+
+The generated manifest starts with documentation and test tooling enabled:
+
+```bash
+spack env activate .
+spack concretize
+spack install
+```
+
+After installation and activation, `properdocs`, `sphinx-build`, `sphinx-multiversion`, Doxygen, and
+the other documentation tools are available from the Spack environment view. No project-local Python
+`pyproject.toml` or virtual environment is required.
+
+Change the dependency selection with ordinary Spack variants, for example:
+
+```bash
+spack change <project>-dev-env~docs+coverage+cuda
+spack concretize -f
+spack install
+```
+
+Select the corresponding BESA/CMake features and devtools separately. BESA does not synchronize the
+Spack and CMake selections automatically.
+
+With the `+docs` Spack variant installed, run from the project root:
+
+```bash
+properdocs serve
+```
+
+The generated ProperDocs hook is active only for `serve`. It watches `src/` and `api-docs/`, builds
+`user.docs.api` in `build/properdocs` when those inputs change, and mounts the current API beneath
+`reference/api/main/`. A normal `properdocs build` remains a plain ProperDocs build; the CMake
+`user.docs` target continues to own the full multiversion publication assembly.

besa-0.1.0/docs/how-to/dependencies.md

@@ -0,0 +1,39 @@
+# Add dependencies
+
+Declare a CMake-resolved normal dependency with:
+
+```cmake
+besa_dependency_add(
+  NAME fmt
+  KIND NORMAL
+  PROVIDER CMAKE
+  VISIBILITY PRIVATE
+)
+```
+
+Declare a development-only dependency with:
+
+```cmake
+besa_dependency_add(
+  NAME Catch2
+  VERSION 3
+  KIND DEV
+  PROVIDER CMAKE
+)
+```
+
+Conditional dependencies use the same selector grammar as directories:
+
+```cmake
+besa_dependency_add(
+  NAME Doxygen
+  KIND DEV
+  PROVIDER CMAKE
+  WHEN ALL_OF user-docs
+)
+```
+
+For pkg-config metadata use `PROVIDER PKGCONFIG`.
+
+`NORMAL` dependencies are recorded in the generated `<project>Config.cmake`. `BUILD` and `DEV`
+dependencies are intentionally absent from consumer package metadata.

besa-0.1.0/docs/how-to/feature-constraints.md

@@ -0,0 +1,129 @@
+# Add configuration constraints
+
+BESA lets a project reject otherwise valid combinations in three independently resolved
+configuration families:
+
+- project features;
+- BESA devtools;
+- project test modes.
+
+Constraints run inside `besa_configure_complete()` after defaults/overrides have been resolved, but
+before toolchain languages or compiler-dependent instrumentation are activated. Each callback uses
+named arguments and returns a boolean plus an optional error message.
+
+## Feature constraints
+
+Define a callback:
+
+```cmake
+function(no_cuda_and_hip)
+  besa_feature_constraint_arguments_parse(
+    PREFIX ARG
+    ARGUMENTS ${ARGN}
+  )
+
+  if("toolchain-cuda" IN_LIST ARG_FEATURES
+     AND "toolchain-hip" IN_LIST ARG_FEATURES)
+    set("${ARG_OUTPUT_VARIABLE}" FALSE PARENT_SCOPE)
+    set(
+      "${ARG_ERROR_VARIABLE}"
+      "CUDA and HIP cannot be enabled together in this project."
+      PARENT_SCOPE
+    )
+    return()
+  endif()
+
+  set("${ARG_OUTPUT_VARIABLE}" TRUE PARENT_SCOPE)
+  set("${ARG_ERROR_VARIABLE}" "" PARENT_SCOPE)
+endfunction()
+
+besa_register_feature_constraint(
+  FUNCTION no_cuda_and_hip
+)
+```
+
+BESA invokes the function with `OUTPUT_VARIABLE`, `ERROR_VARIABLE`, and `FEATURES`.
+
+## Devtool constraints
+
+A project can impose policy on BESA-defined devtools without redefining which devtools BESA
+supports:
+
+```cmake
+function(no_asan_with_coverage)
+  besa_devtool_constraint_arguments_parse(
+    PREFIX ARG
+    ARGUMENTS ${ARGN}
+  )
+
+  if("asan" IN_LIST ARG_DEVTOOLS
+     AND "coverage" IN_LIST ARG_DEVTOOLS)
+    set("${ARG_OUTPUT_VARIABLE}" FALSE PARENT_SCOPE)
+    set(
+      "${ARG_ERROR_VARIABLE}"
+      "This project does not support ASan and coverage in the same build."
+      PARENT_SCOPE
+    )
+    return()
+  endif()
+
+  set("${ARG_OUTPUT_VARIABLE}" TRUE PARENT_SCOPE)
+  set("${ARG_ERROR_VARIABLE}" "" PARENT_SCOPE)
+endfunction()
+
+besa_register_devtool_constraint(
+  FUNCTION no_asan_with_coverage
+)
+```
+
+The callback receives `OUTPUT_VARIABLE`, `ERROR_VARIABLE`, and `DEVTOOLS`.
+
+## Test-mode constraints
+
+Test-mode constraints are available for projects whose test workflows have incompatible
+combinations:
+
+```cmake
+function(no_commit_with_nightly)
+  besa_test_mode_constraint_arguments_parse(
+    PREFIX ARG
+    ARGUMENTS ${ARGN}
+  )
+
+  if("ci-commit" IN_LIST ARG_MODES
+     AND "nightly" IN_LIST ARG_MODES)
+    set("${ARG_OUTPUT_VARIABLE}" FALSE PARENT_SCOPE)
+    set(
+      "${ARG_ERROR_VARIABLE}"
+      "ci-commit and nightly are separate test workflows."
+      PARENT_SCOPE
+    )
+    return()
+  endif()
+
+  set("${ARG_OUTPUT_VARIABLE}" TRUE PARENT_SCOPE)
+  set("${ARG_ERROR_VARIABLE}" "" PARENT_SCOPE)
+endfunction()
+
+besa_register_test_mode_constraint(
+  FUNCTION no_commit_with_nightly
+)
+```
+
+The callback receives `OUTPUT_VARIABLE`, `ERROR_VARIABLE`, and `MODES`.
+
+## Complete configuration after registration
+
+Register every constraint before the configuration phase is closed:
+
+```cmake
+besa_register_feature_constraint(FUNCTION no_cuda_and_hip)
+besa_register_devtool_constraint(FUNCTION no_asan_with_coverage)
+besa_register_test_mode_constraint(FUNCTION no_commit_with_nightly)
+
+besa_configure_complete()
+```
+
+If a callback sets its output variable to false, BESA reports the callback-provided error with
+`message(FATAL_ERROR)`. A false result with no error text still rejects the configuration with a
+generic constraint diagnostic.

besa-0.1.0/docs/how-to/features.md

@@ -0,0 +1,49 @@
+# Configure features
+
+Declare every supported feature before the configuration phase closes:
+
+```cmake
+besa_features_add(
+  FEATURES
+    build-source
+    toolchain-cpp
+    toolchain-cuda
+    toolchain-hip
+    toolchain-asm
+    user-docs
+)
+
+besa_features_default(
+  FEATURES
+    build-source
+    toolchain-cpp
+)
+
+besa_configure_complete()
+```
+
+`PROJECT_FEATURES` is an override set applied to the defaults:
+
+```console
+cmake -S . -B build/cuda \
+  -DPROJECT_FEATURES='toolchain-cuda;~toolchain-cpp'
+```
+
+Positive entries enable a feature. `~feature` disables a default feature. Each underlying feature may
+appear at most once in `PROJECT_FEATURES`; contradictory or repeated entries are rejected.
+
+Features beginning with `toolchain-` are special. BESA currently maps:
+
+- `toolchain-c` to CMake language `C`;
+- `toolchain-cpp` to `CXX`;
+- `toolchain-cuda` to `CUDA`;
+- `toolchain-hip` to `HIP`;
+- `toolchain-fortran` to `Fortran`;
+- `toolchain-asm` to `ASM`.
+
+BESA enables `ASM` after all other selected toolchain languages. This follows CMake's recommendation
+that assembly support be enabled last so an enabled C or C++ compiler can be considered for assembly
+sources.
+
+A project may declare another `toolchain-*` name, but enabling it is an error until the installed BESA
+version knows how to map it to a CMake language.