Add CMake integration (#68)

Add first-class CMake integration

Add UsePRIK.cmake and PRIKConfig.cmake for building PRIK extensions
inside existing CMake projects, with structural configure-time planning
and incremental build-time generation.

Support CMake targets, native sources, link dependencies, compiler and
wrapper flags, linker-language selection, depfiles, and stable generated
source graphs.

Package the CMake modules for direct discovery, find_package(PRIK),
scikit-build-core's cmake.module entry point, and the cmake-dir and
install-dir CLI helpers.

Add integration tests, installed-wheel discovery tests, runnable CMake
examples, and user documentation for the supported discovery and build
workflows.

Author: saidctb

.github/workflows/merge-validation.yml

@@ -281,6 +281,19 @@ jobs:
           ln -sf "$(command -v "$PRIK_GFORTRAN_BINARY")" "$compiler_dir/gfortran"
           echo "$compiler_dir" >> "$GITHUB_PATH"
           "$compiler_dir/gfortran" --version
+      - name: Verify CMake build tooling
+        shell: bash
+        run: |
+          if ! command -v cmake >/dev/null 2>&1; then
+            echo "cmake is missing, so the CMake integration tests would deselect themselves" >&2
+            exit 1
+          fi
+          cmake --version
+          if command -v ninja >/dev/null 2>&1; then
+            ninja --version
+          else
+            echo "::warning::ninja is missing; CMake tests fall back to the Makefile generator"
+          fi
       - name: Run tests
         if: ${{ !matrix.coverage }}
         shell: bash
@@ -401,6 +414,19 @@ jobs:
           gfortran --version
           command -v gcc
           gcc --version
+      - name: Verify CMake build tooling
+        shell: bash
+        run: |
+          if ! command -v cmake >/dev/null 2>&1; then
+            echo "cmake is missing, so the CMake integration tests would deselect themselves" >&2
+            exit 1
+          fi
+          cmake --version
+          if command -v ninja >/dev/null 2>&1; then
+            ninja --version
+          else
+            echo "::warning::ninja is missing; CMake tests fall back to the Makefile generator"
+          fi
       - name: Show repository-owned lane plan
         run: |
           python tools/run_fortran_toolchain_lane.py \

.github/workflows/publish-to-pypi.yml

@@ -62,6 +62,8 @@ jobs:
           "$RUNNER_TEMP/prik-release-check/bin/prik" --version
           "$RUNNER_TEMP/prik-release-check/bin/python" -c \
             'import importlib.metadata as m, prik; assert prik.__version__ == m.version("prik")'
+          "$RUNNER_TEMP/prik-release-check/bin/python" -c \
+            'from prik.cmake import cmake_module_dir; assert (cmake_module_dir() / "UsePRIK.cmake").is_file()'
           "$RUNNER_TEMP/prik-release-check/bin/prik" --help
           "$RUNNER_TEMP/prik-release-check/bin/python" -m prik --help
       - name: Upload distributions

.github/workflows/tests.yml

@@ -45,6 +45,19 @@ jobs:
           ln -sf "$(command -v "$PRIK_GFORTRAN_BINARY")" "$compiler_dir/gfortran"
           echo "$compiler_dir" >> "$GITHUB_PATH"
           "$compiler_dir/gfortran" --version
+      - name: Verify CMake build tooling
+        shell: bash
+        run: |
+          if ! command -v cmake >/dev/null 2>&1; then
+            echo "cmake is missing, so the CMake integration tests would deselect themselves" >&2
+            exit 1
+          fi
+          cmake --version
+          if command -v ninja >/dev/null 2>&1; then
+            ninja --version
+          else
+            echo "::warning::ninja is missing; CMake tests fall back to the Makefile generator"
+          fi
       - name: Run tests
         shell: bash
         env:
@@ -122,6 +135,19 @@ jobs:
           gfortran --version
           command -v gcc
           gcc --version
+      - name: Verify CMake build tooling
+        shell: bash
+        run: |
+          if ! command -v cmake >/dev/null 2>&1; then
+            echo "cmake is missing, so the CMake integration tests would deselect themselves" >&2
+            exit 1
+          fi
+          cmake --version
+          if command -v ninja >/dev/null 2>&1; then
+            ninja --version
+          else
+            echo "::warning::ninja is missing; CMake tests fall back to the Makefile generator"
+          fi
       - name: Show repository-owned lane plan
         run: |
           python tools/run_fortran_toolchain_lane.py \

CHANGELOG.md

@@ -7,6 +7,75 @@ release tags add a leading `v` to the package version.
 
 ## Unreleased
 
+- Added CMake integration through the packaged `UsePRIK.cmake` helper and a
+  `prik generate --cmake` standalone-project mode. CMake generates PRIK wrapper
+  sources as build outputs and owns native compilation, linking, external
+  targets, and incremental rebuilds while preserving per-source flags,
+  compiler-required ABI options, preprocessing dependencies, and linker
+  language from PRIK's completed build plan.
+
+- CMake contract modules now distinguish semantic `NATIVE_LANGUAGE` from the
+  final `LINKER_LANGUAGE`, keep native compilation flags target-local, and
+  report a clear error when CMake's C language is not enabled.
+
+- CMake dependency targets now propagate their native compile usage
+  requirements, and standalone `--cmake --lto` initializes IPO for native and
+  generated targets.
+
+- CMake configuration no longer runs PRIK's semantic pipeline. It asks for a
+  structural plan -- deterministic generated filenames, the link driver, and
+  compiler-profile ABI flags -- and the full pipeline then runs once at build
+  time. Configuring a 300-procedure module's plan drops from about 2.5s to
+  0.4s, and the structural query no longer grows with source size.
+
+- Generated CMake targets have a fixed source list. The optional collision
+  adapter and Fortran bridge units are always written, holding a
+  symbol-free placeholder when unused, so a semantic edit changes file
+  contents instead of the build graph and never forces a CMake reconfigure.
+  Transitive semantic inputs now reach CMake through a generated dependency
+  file, which raises the CMake floor for the packaged helper to 3.21.
+
+- `prik generate --cmake` keeps each native link input in its own CMake
+  category: prebuilt objects, archives, and shared libraries stay filesystem
+  paths in `LINK_LIBRARIES` instead of becoming ambiguous relative tokens,
+  while library names and linker arguments keep their meaning and order.
+
+- CMake native object targets receive `LINK_LIBRARIES` with the caller's link
+  syntax unchanged, so `debug`/`optimized` keywords and generator-expression
+  entries keep selecting usage requirements per configuration instead of being
+  flattened or dropped.
+
+- CMake mode rejects a `.C` source suffix, which CMake compiles as C++ while
+  PRIK plans the source as C, and reports a clear error when a module
+  contributes native Fortran sources without CMake's Fortran language enabled.
+
+- `prik_add_module()` accepts `LIBRARY_DIRS`, mapping it to
+  `target_link_directories()` and the extension's `BUILD_RPATH`.
+  `generate --cmake` translates `--native-library-dir` into `LIBRARY_DIRS`, so
+  a shared native library outside the system search path is found both at link
+  time and on import without `LD_LIBRARY_PATH`.
+
+- `prik-build.json` schema 5 records generated/native compilation-unit ABI
+  flags and explicit native linker-language requirements.
+
+- PRIK's CMake modules are packaged inside the `prik` distribution and
+  discovered automatically. scikit-build-core builds pick the directory up
+  through a `cmake.module` entry point, so `include(UsePRIK)` needs no lookup,
+  and a packaged `PRIKConfig.cmake` makes `find_package(PRIK CONFIG REQUIRED)`
+  load the same helper. `prik cmake-dir` prints the packaged module directory
+  and `prik install-dir` the prefix PRIK's data files are installed under, for
+  `-DPRIK_DIR=` and `-DCMAKE_PREFIX_PATH=`. `cmake_module_dir()` and the
+  `share/prik/cmake` installation are unchanged.
+
+- The Ubuntu and macOS unit-test jobs now fail when CMake is missing instead of
+  letting the CMake integration tests deselect themselves, and report a missing
+  Ninja as a warning because those tests then use the Makefile generator.
+
+- Added the runnable `examples/cmake/` project, which builds one Fortran module
+  through every CMake discovery route -- scikit-build-core's entry point,
+  `CMAKE_MODULE_PATH`, `PRIK_DIR`, and an installation prefix -- with a script
+  that runs each route and calls the built extension.
+
 - Array handles support allocatable and pointer arguments, results, module
   variables, derived fields, optional arguments, and matching ordinary-array
   parameters. Numeric and character arrays accept supported forward and

MANIFEST.in

@@ -1,3 +1,4 @@
 include CHANGELOG.md
 include CITATION.cff
 include .artifacts/.gitignore
+recursive-include prik/cmake_modules *.cmake

docs/developer/packages/pipeline.md

@@ -86,6 +86,7 @@ prik/pipeline/
 
 `build.py` is the orchestration hub. Its public records describe inputs and
 results without executing a build: `NativeCompilationUnit`,
+`GeneratedCompilationUnit`,
 `NativePrebuiltArtifact`, `NativeLinkItem`, `NativeBuildPlan`, and
 `WrapperBuildResult`. Its three public entrypoints are source-first builds,
 contract-first builds, and replay of a saved contract-build manifest.
@@ -114,6 +115,18 @@ source collections stay distinct, a source-free `.pyi` build states its native
 language instead of deriving it from a compiler or ABI decorator, and prebuilt
 objects, archives, and libraries stay ordered `NativeLinkItem` records.
 
+Build integrations consume the completed result rather than compiler command
+logs. Native and generated compilation units retain their own requested flags,
+required ABI flags, and include directories; the result also records every
+semantic/preprocessing dependency and the final linker language. This is the
+lossless boundary used by `UsePRIK.cmake` for regeneration, linker-driver
+selection, and target-local compilation. CMake places native units in a
+private per-module object target so source properties cannot leak between
+PRIK extension targets; generated sources remain on the Python extension
+target. CMake dependency targets stay attached to the extension for linking
+and are also attached to that object target when present, so their usage
+requirements reach native compilation.
+
 `WrapperBuildResult` and saved `.pyi` manifests report each generated native
 group's kind, language, member keys, and source paths, so zero-source,
 adapter-only, support-only, and mixed output stay factual across direct builds,