Add C++17 bindings

Author: palchukovsky

.github/workflows/release.yml

@@ -271,15 +271,11 @@ jobs:
           echo "WHEEL_PATH=${WHEEL_PATH}" >> "$GITHUB_ENV"
 
       - name: Install built wheel
-        if:
-          matrix.name == 'linux-x86_64-manylinux2014' || !startsWith(matrix.os,
-          'ubuntu')
+        if: matrix.name == 'linux-x86_64-manylinux2014' || !startsWith(matrix.os, 'ubuntu')
         run: "$PYTHON_PATH" -m pip install --force-reinstall --no-deps "${{ env.WHEEL_PATH }}"
 
       - name: Verify wheel import and version
-        if:
-          matrix.name == 'linux-x86_64-manylinux2014' || !startsWith(matrix.os,
-          'ubuntu')
+        if: matrix.name == 'linux-x86_64-manylinux2014' || !startsWith(matrix.os, 'ubuntu')
         shell: bash
         env:
           BASE_VERSION: ${{ needs.verify-tag.outputs.base_version }}
@@ -520,11 +516,19 @@ jobs:
           $src = "target/${{ matrix.target }}/release/${{ matrix.lib_name }}"
           $dst = "dist/openpit-ffi--${{ matrix.goos }}-${{ matrix.goarch }}-${{ matrix.lib_name }}"
           Copy-Item $src $dst -Force
+          $implibSrc = "$src.lib"
+          if (!(Test-Path $implibSrc)) {
+            throw "MSVC import library not found at $implibSrc"
+          }
+          $implibDst = "$dst.lib"
+          Copy-Item $implibSrc $implibDst -Force
           Copy-Item bindings/c/openpit.h dist/openpit.h -Force
           Copy-Item LICENSE dist/LICENSE -Force
           Copy-Item OWNERS dist/OWNERS -Force
           $hash = (Get-FileHash -Path $dst -Algorithm SHA256).Hash.ToLower()
           Set-Content -Path "$dst.sha256" -Value $hash
+          $implibHash = (Get-FileHash -Path $implibDst -Algorithm SHA256).Hash.ToLower()
+          Set-Content -Path "$implibDst.sha256" -Value $implibHash
 
       - name: Upload runtime artifacts
         if: ${{ needs.verify-tag.outputs.release_mode == 'production' }}
@@ -543,12 +547,82 @@ jobs:
           if-no-files-found: error
           retention-days: 1
 
+  build-cpp-distributable:
+    name: Build C++ distributable
+    needs:
+      - verify
+      - verify-tag
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Load CI versions
+        shell: bash
+        run: cat "$GITHUB_WORKSPACE/.github/ci-versions.env" >> "$GITHUB_ENV"
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: ${{ env.CI_RUST }}
+
+      - name: Cache Rust build
+        uses: Swatinem/rust-cache@v2
+
+      - name: Setup CMake
+        uses: jwlawson/actions-setup-cmake@v2
+        with:
+          cmake-version: "3.28"
+
+      - name: Setup just
+        uses: extractions/setup-just@v3
+
+      - name: Build C++ binding
+        shell: bash
+        run: just build-cpp
+
+      - name: Install C++ binding into staging prefix
+        shell: bash
+        env:
+          VERSION: ${{ needs.verify-tag.outputs.version }}
+        run: |
+          set -euo pipefail
+          cmake --install bindings/cpp/build \
+            --prefix /tmp/openpit-cpp-install \
+            --config Release
+          cp LICENSE /tmp/openpit-cpp-install/LICENSE
+          cp OWNERS  /tmp/openpit-cpp-install/OWNERS
+
+      - name: Package C++ distributable
+        shell: bash
+        env:
+          VERSION: ${{ needs.verify-tag.outputs.version }}
+        run: just --justfile "$JUSTFILE" package-cpp /tmp/openpit-cpp-install
+
+      - name: Upload C++ artifact
+        if: ${{ needs.verify-tag.outputs.release_mode == 'production' }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: cpp-distributable
+          path: dist/openpit-cpp--*.tar.gz*
+          if-no-files-found: error
+
+      - name: Upload C++ artifact (dry-run)
+        if: ${{ needs.verify-tag.outputs.release_mode == 'dry-run' }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: cpp-distributable
+          path: dist/openpit-cpp--*.tar.gz*
+          if-no-files-found: error
+          retention-days: 1
+
   publish-go-sources:
     name: Publish pit-go sources
     needs:
       - publish-rust
       - publish-sdist
       - build-runtime-artifacts
+      - build-cpp-distributable
       - verify-tag
     runs-on: ubuntu-22.04
     permissions:
@@ -708,6 +782,7 @@ jobs:
       - publish-rust
       - publish-sdist
       - build-runtime-artifacts
+      - build-cpp-distributable
       - verify-tag
     if: ${{ needs.verify-tag.outputs.release_mode == 'production' }}
     runs-on: ubuntu-22.04
@@ -724,6 +799,12 @@ jobs:
           path: release-assets
           merge-multiple: true
 
+      - name: Download C++ distributable artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: cpp-distributable
+          path: release-assets
+
       - name: Create GitHub Release with runtime assets
         shell: bash
         run: |
@@ -736,8 +817,12 @@ jobs:
           - crates.io: https://crates.io/crates/openpit
           - PyPI: https://pypi.org/project/openpit/${{ needs.verify-tag.outputs.version }}/
 
-          Runtime artifacts for Go SDK delivery are attached to this release
-          (`.so`, `.dylib`, `.dll` and `.sha256` files per target).
+          Runtime artifacts for SDK delivery are attached to this release
+          (\`.so\`, \`.dylib\`, \`.dll\`, Windows \`.dll.lib\`, and
+          \`.sha256\` files per target).
+
+          The C++ distributable (\`openpit-cpp--${{ needs.verify-tag.outputs.version }}.tar.gz\`)
+          contains the public headers and CMake config-file package.
           EOF
 
           mapfile -t ASSETS < <(find release-assets -type f | sort)

.github/workflows/verify.yml

@@ -128,6 +128,98 @@ jobs:
       - name: Check C
         run: just --justfile "$JUSTFILE" test-c-examples
 
+  cpp:
+    name: C++ checks (${{ matrix.name }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: linux-gcc
+            os: ubuntu-22.04
+            cc: gcc
+            cxx: g++
+          - name: linux-clang
+            os: ubuntu-22.04
+            cc: clang
+            cxx: clang++
+          - name: macos-appleclang
+            os: macos-14
+            cc: clang
+            cxx: clang++
+          - name: windows-msvc
+            os: windows-2022
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Load CI versions
+        shell: bash
+        run: cat "$GITHUB_WORKSPACE/.github/ci-versions.env" >> "$GITHUB_ENV"
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: ${{ env.CI_RUST }}
+
+      - name: Cache Rust build
+        uses: Swatinem/rust-cache@v2
+
+      - name: Setup CMake
+        uses: jwlawson/actions-setup-cmake@v2
+        with:
+          cmake-version: "3.28"
+
+      - name: Setup just
+        uses: extractions/setup-just@v3
+
+      - name: Install C++ tooling (Linux)
+        if: startsWith(matrix.os, 'ubuntu')
+        run: |
+          sudo apt-get update
+          sudo apt-get install --yes clang-format clang-tidy doxygen
+
+      - name: Install C++ tooling (macOS)
+        if: startsWith(matrix.os, 'macos')
+        run: brew install clang-format doxygen
+
+      - name: Build C++ binding
+        shell: bash
+        run: |
+          if [[ -n "${{ matrix.cc }}" ]]; then
+            export CC="${{ matrix.cc }}"
+            export CXX="${{ matrix.cxx }}"
+          fi
+          just build-cpp
+
+      - name: Test C++ binding
+        shell: bash
+        run: just test-cpp
+
+      - name: Build and test C++ examples
+        shell: bash
+        run: |
+          if [[ -n "${{ matrix.cc }}" ]]; then
+            export CC="${{ matrix.cc }}"
+            export CXX="${{ matrix.cxx }}"
+          fi
+          just test-examples-cpp
+
+      - name: Check C++ formatting
+        if: ${{ matrix.os != 'windows-2022' }}
+        shell: bash
+        run: just fmt-check-cpp
+
+      - name: Generate C++ API reference
+        if: ${{ matrix.os != 'windows-2022' }}
+        shell: bash
+        run: just gen-docs-cpp
+
+      - name: Lint C++ sources
+        if: startsWith(matrix.os, 'ubuntu')
+        shell: bash
+        run: just lint-cpp
+
   go:
     name: Go checks
     runs-on: ubuntu-22.04

README.md

@@ -5,8 +5,9 @@
 [![Verify](https://github.com/openpitkit/pit/actions/workflows/verify.yml/badge.svg)](https://github.com/openpitkit/pit/actions/workflows/verify.yml) [![Release](https://github.com/openpitkit/pit/actions/workflows/release.yml/badge.svg)](https://github.com/openpitkit/pit/actions/workflows/release.yml) [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
 [![Go version](https://img.shields.io/badge/go-1.22%2B-00ADD8)](https://pkg.go.dev/go.openpit.dev/openpit) [![Module](https://img.shields.io/badge/module-go.openpit.dev%2Fopenpit-00ADD8)](https://pkg.go.dev/go.openpit.dev/openpit)
 [![Python versions](https://img.shields.io/pypi/pyversions/openpit)](https://pypi.org/project/openpit/) [![PyPI](https://img.shields.io/pypi/v/openpit)](https://pypi.org/project/openpit/)
+[![C++17](https://img.shields.io/badge/C%2B%2B-17-00599C)](bindings/cpp/README.md)
 [![Rust](https://img.shields.io/badge/rust-1.75+-orange)](https://crates.io/crates/openpit) [![crates.io](https://img.shields.io/crates/v/openpit)](https://crates.io/crates/openpit)
-[![C API](https://img.shields.io/badge/C%20API-header%20%2B%20docs-4b5563)](docs/c-api/index.md)
+[![C API](https://img.shields.io/badge/C%20API-blue)](bindings/c/README.md)
 <!-- markdownlint-enable MD013 -->
 
 OpenPit is a workspace for embeddable pre-trade risk components. Before an
@@ -67,6 +68,7 @@ policy APIs:
 
 - [Go custom policies](https://github.com/openpitkit/pit/wiki/Policy-API#go-interface)
 - [Python custom policies](https://github.com/openpitkit/pit/wiki/Policy-API#python-interface)
+- [C++ custom policies](https://github.com/openpitkit/pit/wiki/Policy-API#c-interface)
 - [Rust custom policies](https://github.com/openpitkit/pit/wiki/Policy-API#rust-interface)
 
 ## Versioning Policy (Pre‑1.0)
@@ -87,9 +89,10 @@ constraints that tolerate API evolution during the pre-stable phase.
 - [Go SDK README](bindings/go/README.md) - integrate OpenPit from Go.
 - [Python SDK README](bindings/python/README.md) - the `openpit` Python
   package.
+- [C++ SDK README](bindings/cpp/README.md) - C++17 CMake package.
 - [`openpit` crate README](crates/openpit/README.md) - Rust interface with a
   runnable example.
-- [C SDK README](bindings/c/README.md) - C ABI for environments that
+- [C SDK README](bindings/c/README.md) - C interface for environments that
   integrate through C.
 - [examples/](examples/) - end-to-end runnable scenarios.
 - [Wiki](https://github.com/openpitkit/pit/wiki) - conceptual pages and
@@ -103,6 +106,9 @@ constraints that tolerate API evolution during the pre-stable phase.
 - Python `>=3.10` if you build or test Python bindings
 - `maturin` and `pytest` if you build or test Python bindings
 - Go `1.22` if you build or test Go bindings
+- CMake `>=3.21`, a C++17 compiler, `clang-format`, `clang-tidy`, and
+  `doxygen` if you build, test, format, lint, or generate C++ bindings,
+  examples, and reference docs
 
 ```bash
 python3.10 -m venv .venv
@@ -159,6 +165,28 @@ Go tests then expect the path to that library through
 development inside the `pit` repository - consumers installing the SDK with
 `go get` do not need to set it.
 
+#### C++
+
+The C++ binding is a header-only C++17 SDK. In-repo builds link it against the
+locally built native runtime:
+
+```bash
+just build-cpp
+just build-examples-cpp
+```
+
+Manual:
+
+```bash
+cargo build -p openpit-ffi --release --locked
+cmake -S bindings/cpp -B bindings/cpp/build \
+  -DOPENPIT_RUNTIME_LIBRARY="$PWD/target/release/libopenpit_ffi.dylib"
+cmake --build bindings/cpp/build
+```
+
+On Linux, use `libopenpit_ffi.so` instead of `libopenpit_ffi.dylib`. On
+Windows, use `openpit_ffi.dll`.
+
 ### Tests
 
 With [Just](https://just.systems/):
@@ -178,6 +206,10 @@ just test-python-integration
 # Go:
 just test-go
 just test-go-race
+
+# C++:
+just test-cpp
+just test-examples-cpp
 ```
 
 Manual:
@@ -205,4 +237,12 @@ export OPENPIT_RUNTIME_LIBRARY_PATH="$(pwd)/../../target/release/libopenpit_ffi.
 # macOS: use libopenpit_ffi.dylib instead.
 go test ./...
 go test -race ./...
+
+# C++:
+cd ../..
+cargo build -p openpit-ffi --release --locked
+cmake -S bindings/cpp -B bindings/cpp/build \
+  -DOPENPIT_RUNTIME_LIBRARY="$PWD/target/release/libopenpit_ffi.dylib"
+cmake --build bindings/cpp/build
+ctest --test-dir bindings/cpp/build --output-on-failure
 ```

bindings/c/README.md

@@ -1,7 +1,7 @@
 # OpenPit (Pre-trade Integrity Toolkit) for C
 
 <!-- markdownlint-disable MD013 -->
-[![Verify](https://github.com/openpitkit/pit/actions/workflows/verify.yml/badge.svg)](https://github.com/openpitkit/pit/actions/workflows/verify.yml) [![Release](https://github.com/openpitkit/pit/actions/workflows/release.yml/badge.svg)](https://github.com/openpitkit/pit/actions/workflows/release.yml) [![C API](https://img.shields.io/badge/C%20API-header%20%2B%20docs-4b5563)](../../docs/c-api/index.md) [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](../../LICENSE)
+[![Verify](https://github.com/openpitkit/pit/actions/workflows/verify.yml/badge.svg)](https://github.com/openpitkit/pit/actions/workflows/verify.yml) [![Release](https://github.com/openpitkit/pit/actions/workflows/release.yml/badge.svg)](https://github.com/openpitkit/pit/actions/workflows/release.yml) [![C API](https://img.shields.io/badge/C%20API-blue)](../../docs/c-api/index.md) [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](../../LICENSE)
 <!-- markdownlint-enable MD013 -->
 
 `openpit.h` is an embeddable pre-trade risk SDK entrypoint for integrating
@@ -112,7 +112,7 @@ Built-in policies:
 - plus your own via the [policy SDK](https://github.com/openpitkit/pit/wiki/Policy-API).
 
 The primary integration model is to build project-specific policies against the
-public C API: [the C API docs](https://github.com/openpitkit/pit/blob/main/docs/c-api/index.md).
+public C API: [the C API docs](../../docs/c-api/index.md).
 
 Two types of rejections are supported: a full kill switch for the account and a
 rejection of only the current request. Kill switches are intended for
@@ -493,7 +493,7 @@ Example flow:
 7. apply one execution report built as a POD payload
 8. inspect whether post-trade state triggered a kill switch
 
-For the full type and ownership reference, use the generated C manual:
+For the full type and ownership reference, use the C manual:
 [docs/c-api/index.md](https://github.com/openpitkit/pit/blob/main/docs/c-api/index.md).
 
 ## Errors
@@ -510,8 +510,7 @@ Input validation errors and API misuse are reported through two channels:
   message with `openpit_shared_string_view()`, then release with
   `openpit_destroy_shared_string()`
 - read `OpenPitPretradeRejectCode` for stable machine-readable business reject categories
-- use the generated C docs for ownership and lifetime rules of every returned
-  pointer
+- use the C docs for ownership and lifetime rules of every returned pointer
 
 The example above uses both channels: