refactor: single DEB for header-only lib; backend selected by consumer via NUMPYCPP_STD_ONLY

- CMakeLists.txt: one DEB (numpycpp-dev-<ver>-Linux.deb) — no flavor suffix
- numpycpp-config.cmake.in: cmake config propagates -ldl (bitexact) or
  -DNUMPYCPP_STD_ONLY (std) automatically based on consumer's NUMPYCPP_STD_ONLY
- CI: single package job builds one DEB
- README: document both backends with find_package examples

Author: peng.li24

.github/workflows/ci.yml

@@ -1,17 +1,16 @@
 # CI: build and test both backends on every push/PR.
 #
-# Two jobs run in parallel:
+# Two test jobs run in parallel:
 #   test-bitexact — NUMPYCPP_STD_ONLY=OFF (default)
 #     All 900 tests verify IEEE-754 bit-identical results vs numpy.
 #     Requires: numpy .so loaded (OpenBLAS + SVML dlsym), AVX-512 capable CPU.
 #
 #   test-std       — NUMPYCPP_STD_ONLY=ON
-#     Same API, pure <cmath> + C++ loops. Tests run with atol/rtol tolerance.
+#     Same API, pure <cmath> + C++ loops. ~423 precision-independent tests.
 #     No external math dependencies.
 #
-# DEB packaging (flavor appears after version number in filename):
-#   cmake -DNUMPYCPP_STD_ONLY=OFF → numpycpp-dev-<ver>-bitexact-Linux.deb
-#   cmake -DNUMPYCPP_STD_ONLY=ON  → numpycpp-dev-<ver>-std-Linux.deb
+# DEB packaging: single DEB (header-only — backend is consumer's compile choice)
+#   cmake .. → numpycpp-dev-<ver>-Linux.deb
 
 name: CI
 
@@ -110,31 +109,26 @@ jobs:
           cd tests
           python -m pytest test_all.py -q --tb=short --no-header -k "not (test_unary_math or test_dot or test_norm or test_matmul or TestEinsum or test_avx512_boundary or test_nan_passthrough or test_nan_mixed or test_domain or signed_zero or _inf or test_sign_inf)"
 
-  # ── Job 3: package both DEBs ─────────────────────────────────────────────────
+  # ── Job 3: package DEB ───────────────────────────────────────────────────────
   package:
-    name: Package DEBs
+    name: Package DEB
     runs-on: ubuntu-latest
     needs: [test-bitexact, test-std]
 
     steps:
       - uses: actions/checkout@v4
 
-      - name: Build bitexact DEB
+      - name: Build DEB
+        # Header-only: both backends ship in one DEB.
+        # Backend is selected by the consumer at cmake configure time
+        # via -DNUMPYCPP_STD_ONLY=ON/OFF.
         run: |
-          cmake -S . -B build_bitexact -DNUMPYCPP_STD_ONLY=OFF
-          cmake --build build_bitexact --target deb
-          ls build_bitexact/numpycpp-dev-*-bitexact-*.deb
+          cmake -S . -B build_deb
+          cmake --build build_deb --target deb
+          ls build_deb/numpycpp-dev-*.deb
 
-      - name: Build std DEB
-        run: |
-          cmake -S . -B build_std_deb -DNUMPYCPP_STD_ONLY=ON
-          cmake --build build_std_deb --target deb
-          ls build_std_deb/numpycpp-dev-*-std-*.deb
-
-      - name: Upload DEBs as artifacts
+      - name: Upload DEB as artifact
         uses: actions/upload-artifact@v4
         with:
-          name: numpycpp-debs
-          path: |
-            build_bitexact/*.deb
-            build_std_deb/*.deb
+          name: numpycpp-dev-deb
+          path: build_deb/numpycpp-dev-*.deb

CMakeLists.txt

@@ -79,31 +79,21 @@ install(DIRECTORY example/
 )
 
 # ---- CPack DEB packaging ----------------------------------------------------
-# Package name and file name differ by backend flavor.
-# File naming: numpycpp-dev-<version>-<flavor>-Linux.deb
-#   bitexact: numpycpp-dev-1.21.2-bitexact-Linux.deb
-#   std:      numpycpp-dev-1.21.2-std-Linux.deb
-# Package name keeps the flavor so both DEBs can coexist on the same machine.
-if(NUMPYCPP_STD_ONLY)
-    set(_NUMPYCPP_DEB_FLAVOR     "std")
-    set(_NUMPYCPP_DEB_SUMMARY    "C++ numpy-API header-only library — pure std backend (perf-first)")
-else()
-    set(_NUMPYCPP_DEB_FLAVOR     "bitexact")
-    set(_NUMPYCPP_DEB_SUMMARY    "C++ numpy-API header-only library — bit-exact backend (SVML + BLAS)")
-endif()
-
-set(CPACK_PACKAGE_NAME                     "numpycpp-dev-${_NUMPYCPP_DEB_FLAVOR}")
+# Single DEB — header-only library, backend is a consumer compile-time choice.
+# File: numpycpp-dev-<version>-Linux.deb
+set(CPACK_PACKAGE_NAME                     "numpycpp-dev")
 set(CPACK_PACKAGE_VERSION                  ${PROJECT_VERSION})
 set(CPACK_PACKAGE_VENDOR                   "miaobyte")
 set(CPACK_PACKAGE_CONTACT                  "miaobyte")
-set(CPACK_PACKAGE_DESCRIPTION_SUMMARY      "${_NUMPYCPP_DEB_SUMMARY}")
+set(CPACK_PACKAGE_DESCRIPTION_SUMMARY
+    "C++ numpy-API header-only library (bitexact + std backends, C++17)")
 set(CPACK_GENERATOR                        "DEB")
 set(CPACK_DEB_COMPONENT_INSTALL            OFF)
 set(CPACK_DEBIAN_PACKAGE_MAINTAINER        "miaobyte")
 set(CPACK_DEBIAN_PACKAGE_SECTION           "libdevel")
 set(CPACK_DEBIAN_PACKAGE_PRIORITY          "optional")
 set(CPACK_DEBIAN_FILE_NAME
-    "numpycpp-dev-${CPACK_PACKAGE_VERSION}-${_NUMPYCPP_DEB_FLAVOR}-Linux.deb")
+    "numpycpp-dev-${CPACK_PACKAGE_VERSION}-Linux.deb")
 set(CPACK_PACKAGING_INSTALL_PREFIX         "/usr")
 # Wipe the old include tree on install/upgrade so stale headers cannot accumulate.
 set(CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA     "${CMAKE_CURRENT_SOURCE_DIR}/cmake/preinst")
@@ -113,7 +103,7 @@ include(CPack)
 # Convenience target
 add_custom_target(deb
     COMMAND cpack -G DEB
-    COMMENT "Packaging numpycpp-dev-${_NUMPYCPP_DEB_FLAVOR}-${CPACK_PACKAGE_VERSION}-Linux.deb"
+    COMMENT "Packaging numpycpp-dev-${CPACK_PACKAGE_VERSION}-Linux.deb"
 )
 
 message(STATUS "numpycpp v${PROJECT_VERSION}  (header-only C++ library)")

README.md

@@ -69,34 +69,50 @@ Download the [latest `.deb` release](https://github.com/array2d/numpycpp/release
 
 ```bash
 mkdir build && cd build
-cmake .. -DCMAKE_BUILD_TYPE=Release
+cmake ..
 make deb
 sudo dpkg -i numpycpp-dev-*.deb
 ```
 
-Headers are installed to `/usr/include/numpycpp/` along with CMake config. Consuming projects use:
+Headers are installed to `/usr/include/numpycpp/` along with a CMake config that supports both backends.
+
+**CMake — bitexact backend (default)**
+
+```cmake
+find_package(numpycpp REQUIRED)
+target_link_libraries(myapp PRIVATE numpycpp::numpycpp)
+# cmake propagates -ldl automatically — no extra flags needed
+```
+
+**CMake — std backend**
 
 ```cmake
+set(NUMPYCPP_STD_ONLY ON)           # set BEFORE find_package
 find_package(numpycpp REQUIRED)
 target_link_libraries(myapp PRIVATE numpycpp::numpycpp)
+# cmake propagates -DNUMPYCPP_STD_ONLY automatically — no extra flags needed
 ```
 
 **pybind11_add_module users**
 
 With certain CMake / pybind11 version combinations, `pybind11_add_module` may lose IMPORTED targets
-during generation (target exists at configure time but disappears at generate time).
-If you hit this, use the variables-based fallback:
+during generation. If you hit this, use the variables-based fallback:
 
 ```cmake
+set(NUMPYCPP_STD_ONLY OFF)          # or ON for std backend
 find_package(numpycpp REQUIRED)
 pybind11_add_module(mymodule module.cpp)
 target_include_directories(mymodule PRIVATE ${numpycpp_INCLUDE_DIRS})
 target_compile_features(mymodule PRIVATE cxx_std_17)
+# bitexact: add manually → target_link_libraries(mymodule PRIVATE dl)
+# std:      add manually → target_compile_definitions(mymodule PRIVATE NUMPYCPP_STD_ONLY)
 ```
 
 **Manual (header-only)**
 
 Add `-Ipath/to/numpycpp` to your compiler flags and include the headers directly. No build step, no copy required.
+- Bitexact backend: add `-ldl` at link time (no other flags needed at `-O2`; see compiler flags table below)
+- Std backend: add `-DNUMPYCPP_STD_ONLY` (no `-ldl` needed)
 
 ### Testing
 
@@ -119,6 +135,10 @@ numpycpp ships two interchangeable math backends selected via a single cmake fla
 All public APIs (`numpy::exp`, `numpy::dot`, `numpy::einsum`, …) are identical;
 only the internal implementation and precision guarantee differ.
 
+The library is **header-only** — both backends live in the same installed headers.
+The backend is a **consumer compile-time choice**, not an install-time choice.
+One DEB installs everything; `NUMPYCPP_STD_ONLY` selects the backend.
+
 ```cmake
 cmake -DNUMPYCPP_STD_ONLY=OFF ..   # default — bit-exact backend
 cmake -DNUMPYCPP_STD_ONLY=ON  ..   # std / performance-first backend
@@ -130,7 +150,7 @@ cmake -DNUMPYCPP_STD_ONLY=ON  ..   # std / performance-first backend
 | **Dot / matmul** | OpenBLAS ILP64 via `dlsym` | Pure C++ loops (auto-vectorised) |
 | **Precision vs numpy** | **IEEE 754 bit-identical** | 0–2 ULP (not bit-exact) |
 | **External deps** | libdl + numpy `.so` loaded | **None** — pure C++17 |
-| **DEB package** | `numpycpp-dev-<ver>-bitexact-Linux.deb` | `numpycpp-dev-<ver>-std-Linux.deb` |
+| **DEB package** | same `numpycpp-dev-<ver>-Linux.deb` | same `numpycpp-dev-<ver>-Linux.deb` |
 | **cmake propagation** | `target_link_libraries(… dl)` | `target_compile_definitions(… NUMPYCPP_STD_ONLY)` |
 
 #### Compiler flags — bitexact backend (`NUMPYCPP_STD_ONLY=OFF`)
@@ -169,7 +189,7 @@ target_compile_options(<target> PRIVATE
 
 | Flag | Status | Why |
 |------|:------:|-----|
-| `NUMPYCPP_STD_ONLY` | **required** | Selects `std_math_backend.h` + `std_linalg_backend.h` instead of SVML/BLAS bridges. Propagated automatically when using `find_package(numpycpp)` with the std DEB. |
+| `NUMPYCPP_STD_ONLY` | **required** | Selects `std_math_backend.h` + `std_linalg_backend.h` instead of SVML/BLAS bridges. Set via `cmake -DNUMPYCPP_STD_ONLY=ON` or `set(NUMPYCPP_STD_ONLY ON)` before `find_package`. |
 | `-O3 -march=native` | recommended | Enables full auto-vectorisation of the C++ loops (exp/dot/gemm). Without optimisation, std backend is slow. |
 | `-ffp-contract=off` | **not needed** | FMA contraction is welcome in std mode — improves precision and performance of gemm/dot. |
 | `-mavx512f -mprefer-vector-width=256` | **not needed** | SVML bridge not compiled in; no ZMM-trap risk. `-march=native` selects appropriate SIMD automatically. |

numpycpp-config.cmake.in

@@ -1,13 +1,18 @@
 @PACKAGE_INIT@
 
-# Manually create the imported target (no auto-generated targets file).
-# This avoids cmake_policy(PUSH/POP) scope issues present in CMake's
-# install(EXPORT)-generated targets files on CMake >= 3.20.
+# numpycpp -- header-only C++ numpy API library.
 #
-# Use a non-namespaced INTERFACE IMPORTED target as the real target,
-# plus a namespaced ALIAS for conventional CMake usage.  pybind11_add_module
-# has a CMake-level bug with namespaced (::) targets during generation,
-# so users hitting that can link against the bare "numpycpp" target instead.
+# Backend selection (set BEFORE find_package, or via cmake -D):
+#   cmake -DNUMPYCPP_STD_ONLY=OFF ..   # bitexact (default): SVML + OpenBLAS via dlsym
+#   cmake -DNUMPYCPP_STD_ONLY=ON  ..   # std: pure <cmath> + C++ loops, no dlsym
+#
+# The flag is propagated automatically to every target that links numpycpp:
+#   bitexact  → INTERFACE_LINK_LIBRARIES dl
+#   std       → INTERFACE_COMPILE_DEFINITIONS NUMPYCPP_STD_ONLY
+
+# Non-namespaced + namespaced alias.
+# pybind11_add_module users: if the :: target is lost during generation, use
+#   target_include_directories(mymod PRIVATE ${numpycpp_INCLUDE_DIRS})
 add_library(numpycpp INTERFACE IMPORTED)
 
 set_target_properties(numpycpp PROPERTIES
@@ -18,10 +23,20 @@ set_target_properties(numpycpp PROPERTIES
 
 add_library(numpycpp::numpycpp ALIAS numpycpp)
 
-# Fallback variables for environments where CMake targets are unreliable
-# (e.g. pybind11_add_module may lose targets during generation with
-# certain CMake / pybind11 version combinations).
-# Usage: target_include_directories(mymod PRIVATE ${numpycpp_INCLUDE_DIRS})
+# Propagate the correct backend flags to every consumer automatically.
+if(NUMPYCPP_STD_ONLY)
+    # std backend: no external dependencies
+    set_property(TARGET numpycpp APPEND PROPERTY
+        INTERFACE_COMPILE_DEFINITIONS NUMPYCPP_STD_ONLY)
+    message(STATUS "numpycpp: std backend (pure <cmath>, no dlsym)")
+else()
+    # bitexact backend (default): libdl needed for dlsym -> numpy .so at runtime
+    set_property(TARGET numpycpp APPEND PROPERTY
+        INTERFACE_LINK_LIBRARIES dl)
+    message(STATUS "numpycpp: bitexact backend (SVML + OpenBLAS via dlsym, -ldl)")
+endif()
+
+# Fallback variables (pybind11_add_module target-loss workaround)
 set(numpycpp_INCLUDE_DIRS "${PACKAGE_PREFIX_DIR}/include/numpycpp")
 
 check_required_components(numpycpp)