Devel-C (#63)

Expand and harden C and Fortran binding support

  - add target-probed direct-C wrapping for scalars, pointers, arrays, strings,
    hidden outputs, status projection, collision forwarding, and exact ABI types
  - broaden Fortran support for character data, abstract hierarchies, generic
    constructors, ownership, and dependency-ordered compilation
  - complete semantic policy before planning and make generated cleanup safe
    across coercion, native-status, and result-conversion failures
  - add maintained libm, TA-Lib, BSPLINE, BLAS, LAPACK, FFTPACK, and MINPACK
    validation with portable compiler and platform coverage
  - reorganize tests around feature and pipeline ownership and strengthen
    end-to-end contract, build, and memory-safety evidence
  - rewrite the documentation around current workflows, support boundaries,
    architecture, and real-library examples while removing obsolete material
- Remove old documentation and add c-support

Author: saidctb

.githooks/pre-push

@@ -12,7 +12,7 @@ DOCUMENTATION_SMOKE_TESTS = (
     "tests/docs/test_user_content.py",
 )
 WRAPPER_SMOKE_TEST = (
-    "tests/fortran/building_shared_library/end_to_end/test_source_build_modes.py::"
+    "tests/fortran/infrastructure/building/end_to_end/test_source_build_modes.py::"
     "test_fortran_wrapper_default_module_name_does_not_collide_with_root_function"
 )
 REQUIRED_TESTS = ("tests/tools", "tests/workflows")

.github/pull_request_template.md

@@ -2,7 +2,10 @@
 - 
 
 ## Test plan
-- [ ] `PYTHONPATH=. pytest -q`
+- Focused commands run:
+  - <!-- Add each command that you ran. -->
+- Skipped or CI-only coverage, including any real-library lanes:
+  - <!-- Name skipped coverage and why it was not run locally. -->
 
 ## Merge checklist
 - [ ] All required checks are **green**.

.github/workflows/merge-validation.yml

@@ -439,113 +439,21 @@ jobs:
             python tools/print_pytest_failures.py "$report"
           done
 
-  native-libraries:
-    name: BLAS + LAPACK + FFTPACK + MINPACK · Ubuntu 24.04 · Python 3.12
+  real-libraries-portability:
+    name: Real Libraries Portability
     needs: [unit-tests, unit-tests-macos]
     if: >-
       ${{ !contains(github.event.pull_request.labels.*.name, 'ignore-real-library-wrappers') }}
-    runs-on: ubuntu-24.04
-    timeout-minutes: 120
-    permissions:
-      contents: read
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 2
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-      - name: Install test dependencies
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install -e ".[qa]"
-          python -m pip install \
-            "numpy==2.5.1" \
-            "meson==1.11.2" \
-            "ninja==1.13.0" \
-            "scipy==1.18.0"
-      - name: Install pinned GFortran and LAPACK link dependencies
-        shell: bash
-        run: |
-          packages=(libblas-dev liblapack-dev)
-          if ! command -v "$PRIK_GFORTRAN_BINARY" >/dev/null 2>&1; then
-            packages+=("$PRIK_GFORTRAN_PACKAGE")
-          fi
-          sudo apt-get update
-          sudo apt-get install --yes "${packages[@]}"
-          compiler_dir="$RUNNER_TEMP/prik-gfortran"
-          mkdir -p "$compiler_dir"
-          ln -sf "$(command -v "$PRIK_GFORTRAN_BINARY")" "$compiler_dir/gfortran"
-          echo "$compiler_dir" >> "$GITHUB_PATH"
-          "$compiler_dir/gfortran" --version
-      - name: Restore compiled native library cache
-        uses: actions/cache@v4
-        with:
-          path: ${{ runner.temp }}/prik-real-library-native
-          key: real-libraries-${{ runner.os }}-gfortran13-${{ hashFiles('examples/blas/native/**', 'examples/lapack/native/**') }}
-      - name: Run BLAS example and CI full-surface audit
-        env:
-          PYTHONPATH: .
-          HYPOTHESIS_PROFILE: ci
-          PRIK_REAL_LIBRARY_NATIVE_CACHE_DIR: ${{ runner.temp }}/prik-real-library-native
-        run: |
-          source examples/blas/build_all.sh
-          python -m pytest -q examples/blas/tests examples/blas/ci/full_surface.py
-      - name: Report reviewed LAPACK inventory
-        env:
-          PYTHONPATH: .
-        run: |
-          python - <<'PY'
-          from examples.lapack.routine_inventory import (
-              EXPECTED_LAPACK_PROCEDURES,
-              EXPECTED_LAPACK_SOURCE_FILES,
-              F2PY_SCALAR_WRITEBACK_ROUTINES,
-              ROUTINE_GROUPS,
-              ROUTINES,
-              SCIPY_VERSION,
-          )
-
-          print(f"SciPy version: {SCIPY_VERSION}")
-          print(f"LAPACK implementation sources: {EXPECTED_LAPACK_SOURCE_FILES}")
-          print(f"Expected PRIK procedures: {EXPECTED_LAPACK_PROCEDURES}")
-          print(f"Selected float64 correctness routines: {len(ROUTINES)}")
-          print(f"f2py scalar writebacks: {len(F2PY_SCALAR_WRITEBACK_ROUTINES)}")
-          for family, routines in ROUTINE_GROUPS.items():
-              print(f"  {family}: {len(routines)}")
-          PY
-      - name: Run LAPACK example and CI full-surface audit
-        env:
-          PYTHONPATH: .
-          HYPOTHESIS_PROFILE: ci
-          PRIK_REAL_LIBRARY_NATIVE_CACHE_DIR: ${{ runner.temp }}/prik-real-library-native
-        run: |
-          source examples/lapack/build_all.sh
-          python -m pytest -q examples/lapack/tests examples/lapack/ci/full_surface.py
-      - name: Run FFTPACK 31-procedure full-surface audit
-        env:
-          PYTHONPATH: .
-          HYPOTHESIS_PROFILE: ci
-        run: |
-          source examples/fftpack/build_all.sh
-          python -m pytest -q examples/fftpack/tests
-      - name: Run MINPACK 22-procedure and parameter-array full-surface audit
-        env:
-          PYTHONPATH: .
-          HYPOTHESIS_PROFILE: ci
-        run: |
-          source examples/minpack/build_all.sh
-          python -m pytest -q examples/minpack/tests
+    uses: ./.github/workflows/real-libraries-portability.yml
 
   documentation-benchmark:
     name: Documentation performance benchmark · Ubuntu 24.04 ARM64 · Python 3.12
-    needs: native-libraries
+    needs: real-libraries-portability
     if: >-
       ${{
         always() &&
-        (needs.native-libraries.result == 'success' ||
-         (needs.native-libraries.result == 'skipped' &&
+        (needs.real-libraries-portability.result == 'success' ||
+         (needs.real-libraries-portability.result == 'skipped' &&
           contains(github.event.pull_request.labels.*.name, 'ignore-real-library-wrappers')))
       }}
     runs-on: ubuntu-24.04-arm
@@ -687,7 +595,7 @@ jobs:
       - compiler-smoke-macos
       - unit-tests
       - unit-tests-macos
-      - native-libraries
+      - real-libraries-portability
       - documentation-benchmark
       - documentation-build
     runs-on: ubuntu-24.04
@@ -698,10 +606,10 @@ jobs:
       COMPILER_SMOKE_MACOS_RESULT: ${{ needs.compiler-smoke-macos.result }}
       UNIT_TESTS_RESULT: ${{ needs.unit-tests.result }}
       UNIT_TESTS_MACOS_RESULT: ${{ needs.unit-tests-macos.result }}
-      NATIVE_LIBRARIES_RESULT: ${{ needs.native-libraries.result }}
+      REAL_LIBRARIES_PORTABILITY_RESULT: ${{ needs.real-libraries-portability.result }}
       DOCUMENTATION_BENCHMARK_RESULT: ${{ needs.documentation-benchmark.result }}
       DOCUMENTATION_BUILD_RESULT: ${{ needs.documentation-build.result }}
-      IGNORE_NATIVE_LIBRARIES: ${{ contains(github.event.pull_request.labels.*.name, 'ignore-real-library-wrappers') }}
+      IGNORE_REAL_LIBRARIES_PORTABILITY: ${{ contains(github.event.pull_request.labels.*.name, 'ignore-real-library-wrappers') }}
     steps:
       - name: Require every staged validation result
         shell: bash
@@ -713,15 +621,15 @@ jobs:
             "compiler-smoke-macos=$COMPILER_SMOKE_MACOS_RESULT" \
             "unit-tests=$UNIT_TESTS_RESULT" \
             "unit-tests-macos=$UNIT_TESTS_MACOS_RESULT" \
-            "native-libraries=$NATIVE_LIBRARIES_RESULT" \
+            "real-libraries-portability=$REAL_LIBRARIES_PORTABILITY_RESULT" \
             "documentation-benchmark=$DOCUMENTATION_BENCHMARK_RESULT" \
             "documentation-build=$DOCUMENTATION_BUILD_RESULT"
           do
             stage=${staged_result%%=*}
             result=${staged_result#*=}
-            if [[ "$stage" == "native-libraries" && \
+            if [[ "$stage" == "real-libraries-portability" && \
                   "$result" == "skipped" && \
-                  "$IGNORE_NATIVE_LIBRARIES" == "true" ]]; then
+                  "$IGNORE_REAL_LIBRARIES_PORTABILITY" == "true" ]]; then
               continue
             fi
             if [[ "$result" != "success" ]]; then

.github/workflows/real-libraries-portability.yml

@@ -0,0 +1,159 @@
+name: Real Libraries Portability
+
+on:
+  workflow_call:
+  push:
+    branches:
+      - main
+      - release/*
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: real-libraries-portability-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  examples:
+    name: Real Libraries Portability · ${{ matrix.target }} · Python 3.12
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 120
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - target: Linux x86-64
+            cache_key: linux-x86-64
+            runner: ubuntu-24.04
+            fortran_compiler: gfortran-13
+            fortran_c_compiler: gcc-13
+            primary_c_compiler: gcc-13
+            secondary_c_compiler: clang-18
+          - target: Linux ARM64
+            cache_key: linux-arm64
+            runner: ubuntu-24.04-arm
+            fortran_compiler: gfortran-13
+            fortran_c_compiler: gcc-13
+            primary_c_compiler: gcc-13
+            secondary_c_compiler: clang-18
+          - target: macOS Intel
+            cache_key: macos-intel
+            runner: macos-15-intel
+            fortran_compiler: gfortran-13
+            fortran_c_compiler: gcc-13
+            primary_c_compiler: clang
+            secondary_c_compiler: gcc-13
+          - target: macOS ARM64
+            cache_key: macos-arm64
+            runner: macos-15
+            fortran_compiler: gfortran-13
+            fortran_c_compiler: gcc-13
+            primary_c_compiler: clang
+            secondary_c_compiler: gcc-13
+    env:
+      PRIK_REAL_LIBRARY_NATIVE_JOBS: "8"
+      PYTHONPATH: .
+      HYPOTHESIS_PROFILE: ci
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install Ubuntu native dependencies
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install --yes gfortran-13 libblas-dev liblapack-dev
+      - name: Ensure macOS GNU compilers are available
+        if: runner.os == 'macOS'
+        run: |
+          if ! command -v "${{ matrix.fortran_compiler }}" >/dev/null 2>&1 || \
+             ! command -v "${{ matrix.fortran_c_compiler }}" >/dev/null 2>&1; then
+            brew install gcc@13
+          fi
+      - name: Configure GNU Fortran and C
+        shell: bash
+        run: |
+          compiler_dir="$RUNNER_TEMP/prik-example-compilers"
+          mkdir -p "$compiler_dir"
+          ln -sf "$(command -v "${{ matrix.fortran_compiler }}")" "$compiler_dir/gfortran"
+          ln -sf "$(command -v "${{ matrix.fortran_c_compiler }}")" "$compiler_dir/gcc"
+          echo "$compiler_dir" >> "$GITHUB_PATH"
+          echo "PRIK_REAL_LIBRARY_NATIVE_CACHE_DIR=$RUNNER_TEMP/prik-example-native" >> "$GITHUB_ENV"
+          echo "PRIK_TALIB_CACHE_DIR=$RUNNER_TEMP/prik-ta-lib-native" >> "$GITHUB_ENV"
+      - name: Install example dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[qa]" \
+            "numpy==2.5.1" \
+            "meson==1.11.2" \
+            "ninja==1.13.0" \
+            "scipy==1.18.0"
+      - name: Restore compiled BLAS and LAPACK cache
+        uses: actions/cache@v4
+        with:
+          path: ${{ runner.temp }}/prik-example-native
+          key: real-libraries-portability-${{ matrix.cache_key }}-gfortran13-${{ hashFiles('examples/native_library.py', 'examples/fortran/blas/native/**', 'examples/fortran/lapack/native/**', 'examples/fortran/lapack/support/**', 'examples/fortran/lapack/xblas_sources.txt') }}
+      - name: Restore pinned TA-Lib cache
+        uses: actions/cache@v4
+        with:
+          path: ${{ runner.temp }}/prik-ta-lib-native
+          key: real-libraries-portability-${{ matrix.cache_key }}-ta-lib-v0.7.1-${{ hashFiles('examples/c/ta_lib/native_build.py') }}
+      - name: Show target and compilers
+        run: |
+          uname -a
+          python --version
+          gfortran --version
+          gcc --version
+          "${{ matrix.primary_c_compiler }}" --version
+          "${{ matrix.secondary_c_compiler }}" --version
+      - name: Run libm with ${{ matrix.primary_c_compiler }}
+        env:
+          PRIK_LIBM_CC: ${{ matrix.primary_c_compiler }}
+        run: |
+          source examples/c/libm/build_all.sh
+          python -m pytest -q examples/c/libm/tests
+      - name: Run libm with ${{ matrix.secondary_c_compiler }}
+        env:
+          PRIK_LIBM_CC: ${{ matrix.secondary_c_compiler }}
+        run: |
+          source examples/c/libm/build_all.sh
+          python -m pytest -q examples/c/libm/tests
+      - name: Run TA-Lib with ${{ matrix.primary_c_compiler }}
+        env:
+          PRIK_TALIB_CC: ${{ matrix.primary_c_compiler }}
+        run: |
+          source examples/c/ta_lib/build_all.sh
+          python -m pytest -q examples/c/ta_lib/tests
+      - name: Run BLAS example
+        run: |
+          source examples/fortran/blas/build_all.sh
+          python -m pytest -q examples/fortran/blas/tests
+          if [[ "${{ matrix.target }}" == "Linux x86-64" ]]; then
+            python -m pytest -q examples/fortran/blas/ci/full_surface.py
+          fi
+      - name: Run LAPACK example
+        run: |
+          source examples/fortran/lapack/build_all.sh
+          python -m pytest -q examples/fortran/lapack/tests
+          if [[ "${{ matrix.target }}" == "Linux x86-64" ]]; then
+            python -m pytest -q examples/fortran/lapack/ci/full_surface.py
+          fi
+      - name: Run FFTPACK example
+        run: |
+          source examples/fortran/fftpack/build_all.sh
+          python -m pytest -q examples/fortran/fftpack/tests
+      - name: Run MINPACK example
+        run: |
+          source examples/fortran/minpack/build_all.sh
+          python -m pytest -q examples/fortran/minpack/tests
+      - name: Run BSPLINE-FORTRAN example
+        run: |
+          source examples/fortran/bspline/build_all.sh
+          python -m pytest -q examples/fortran/bspline/tests