From f61074c1182ebbde3e5bf701fb38f5a7c6f2c940 Mon Sep 17 00:00:00 2001 From: Fabio M Date: Mon, 22 Jun 2026 19:46:12 -0500 Subject: [PATCH 1/5] Remove "Verify C++23 standard" step from build job --- .github/workflows/ci.yml | 20 -------------------- 1 file changed, 20 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 851c084..31d3dc4 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -42,26 +42,6 @@ jobs: CC: ${{ matrix.compiler == 'gcc' && 'gcc' || 'clang' }} CXX: ${{ matrix.compiler == 'gcc' && 'g++' || 'clang++' }} - - name: Verify C++23 standard - run: | - echo "=== Compiler Information ===" - ${{ matrix.compiler == 'gcc' && 'g++' || 'clang++' }} --version - echo "" - echo "=== Checking C++ standard in compile commands ===" - if [ -f "build/${{ matrix.preset }}/compile_commands.json" ]; then - # Extract and display C++ standard flags - grep -o '\-std=[^ " ]*' "build/${{ matrix.preset }}/compile_commands.json" | sort -u || echo "No -std flag found" - # Verify C++23 is being used - if grep -q '\-std=c++2[3b]' "build/${{ matrix.preset }}/compile_commands.json"; then - echo "✓ C++23 standard verified" - else - echo "✗ C++23 standard NOT found in compile commands" - exit 1 - fi - else - echo "Warning: compile_commands.json not found" - fi - - name: Build run: cmake --build --preset ${{ matrix.preset }} From 9ceccb641ba026c769e79cd8e130ee956b4a8955 Mon Sep 17 00:00:00 2001 From: Fabio M Date: Mon, 22 Jun 2026 19:52:01 -0500 Subject: [PATCH 2/5] Cache conan dependencies for faster CI builds --- .github/workflows/ci.yml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 31d3dc4..fa9b3e5 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -25,6 +25,12 @@ jobs: - name: Checkout code uses: actions/checkout@v4 + - name: Cache Conan packages + uses: actions/cache@v4 + with: + path: ~/.conan2 + key: conan-${{ matrix.os }}-${{ matrix.compiler }}-${{ matrix.preset }}-${{ hashFiles('conanfile.*') }} + - name: Install Conan run: pipx install conan @@ -56,6 +62,12 @@ jobs: - name: Checkout code uses: actions/checkout@v4 + - name: Cache Conan packages + uses: actions/cache@v4 + with: + path: ~/.conan2 + key: conan-ubuntu-latest-gcc-debug-coverage-${{ hashFiles('conanfile.*') }} + - name: Install Conan run: pipx install conan From 240dcbfc19081f9e34cc5b052035e5f22030b52e Mon Sep 17 00:00:00 2001 From: Fabio M Date: Mon, 22 Jun 2026 20:11:06 -0500 Subject: [PATCH 3/5] Create CI_CACHING.md --- docs/CI_CACHING.md | 77 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 docs/CI_CACHING.md diff --git a/docs/CI_CACHING.md b/docs/CI_CACHING.md new file mode 100644 index 0000000..48f3cfd --- /dev/null +++ b/docs/CI_CACHING.md @@ -0,0 +1,77 @@ +# CI Caching Guide + +This document explains how GitHub Actions caching works in this project's CI pipeline. + +--- + +## How CI Jobs Run + +Each CI job starts on a **fresh virtual machine** with: +- No previous build artifacts +- No installed tools (except GitHub-provided defaults) +- No cached data in the filesystem + +Data only persists between runs through: +- **Caches** (dependency caching) +- **Artifacts** (explicit upload/download) +- **External storage** (GitHub Packages, etc.) + +--- + +## Conan Dependency Caching + +This project caches Conan packages (`~/.conan2`) to speed up builds. + +### Cache Key Structure + +The cache key includes: +- **OS** (e.g., `ubuntu-latest`, `macos-latest`) +- **Compiler** (e.g., `gcc`, `clang`) +- **Preset** (e.g., `release-strict`, `debug-sanitizers`) +- **Conanfile hash** (automatically invalidates when dependencies change) + +Example: `conan-ubuntu-latest-gcc-release-strict-` + +### Cache Behavior + +- **Persistence:** 7 days after last access +- **Scope:** Repository and branch (main branch caches are available to PRs) +- **Invalidation:** Automatic when `conanfile.txt` or `conanfile.py` changes + +--- + +## Cache Hit Scenarios + +### Best Scenarios (High Hit Rate) + +1. **Frequent commits without dependency changes** — Every build hits the cache +2. **PRs targeting main** — Reuse caches created by main branch builds +3. **Stable dependency periods** — Weeks without updating dependencies + +### Worst Scenarios (Cache Misses) + +- Modifying `conanfile.txt` or `conanfile.py` +- First build on a new branch that diverged before dependencies were cached +- After 7 days of inactivity (cache expires) + +--- + +## Benefits + +- **Time savings:** 1-5+ minutes per job (skips downloading/building dependencies) +- **Cost reduction:** Fewer CI minutes consumed +- **Network efficiency:** Reduced external API calls + +--- + +## Summary + +| Aspect | Behavior | +|---|---| +| Cache persistence | 7 days after last access | +| Cache scope | Repository + branch | +| Invalidation | Automatic on conanfile changes | +| Best use case | Stable dependencies with frequent builds | +| Time saved | 1-5+ minutes per job | + +For more information on the CI pipeline, see `.github/workflows/ci.yml`. From c85119052cdb2afb107b97b3c1f9e8d800a9fc90 Mon Sep 17 00:00:00 2001 From: Fabio M Date: Tue, 23 Jun 2026 05:53:40 -0500 Subject: [PATCH 4/5] Set values for CC (C Compiler) and CXX (C++ Compiler) predefined environment variables for the Conan steps so Conan builds packages with the correct compiler --- .github/workflows/ci.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index fa9b3e5..19f67eb 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -36,11 +36,17 @@ jobs: - name: Configure Conan profile run: conan profile detect --force + env: + CC: ${{ matrix.compiler == 'gcc' && 'gcc' || 'clang' }} + CXX: ${{ matrix.compiler == 'gcc' && 'g++' || 'clang++' }} - name: Install dependencies run: | BUILD_TYPE=$(echo "${{ matrix.preset }}" | grep -q "release" && echo "Release" || echo "Debug") conan install . --build=missing -s build_type=$BUILD_TYPE -s compiler.cppstd=23 + env: + CC: ${{ matrix.compiler == 'gcc' && 'gcc' || 'clang' }} + CXX: ${{ matrix.compiler == 'gcc' && 'g++' || 'clang++' }} - name: Configure CMake run: cmake --preset ${{ matrix.preset }} From 7244c3d2eee779e602080183f3f7146a37b63704 Mon Sep 17 00:00:00 2001 From: Fabio M Date: Tue, 23 Jun 2026 06:06:42 -0500 Subject: [PATCH 5/5] Update CI_CACHING.md + Create CI.md, both containing information regarding CC/CXX --- docs/CI.md | 49 ++++++++++++++++++++++++++++++++++++++++++++++ docs/CI_CACHING.md | 12 ++++++++++++ 2 files changed, 61 insertions(+) create mode 100644 docs/CI.md diff --git a/docs/CI.md b/docs/CI.md new file mode 100644 index 0000000..117cb76 --- /dev/null +++ b/docs/CI.md @@ -0,0 +1,49 @@ +# CI Compiler Configuration + +This document explains how compilers are configured in the CI pipeline. + +--- + +## What are CC and CXX? + +**CC** and **CXX** are standard environment variables that tell build tools which compilers to use: + +- **CC** — Path to the C compiler (e.g., `gcc`, `clang`) +- **CXX** — Path to the C++ compiler (e.g., `g++`, `clang++`) + +These variables are recognized by: +- CMake +- Make +- Conan +- Most Unix-based build systems + +--- + +## How This Project Uses CC/CXX + +The CI matrix tests multiple compilers across different operating systems: + +| OS | Compiler | CC | CXX | +|---|---|---|---| +| ubuntu-latest | gcc | gcc | g++ | +| ubuntu-latest | clang | clang | clang++ | +| macos-latest | clang | clang | clang++ | + +The workflow sets these variables for all build steps: + +```yaml +env: + CC: ${{ matrix.compiler == 'gcc' && 'gcc' || 'clang' }} + CXX: ${{ matrix.compiler == 'gcc' && 'g++' || 'clang++' }} +``` + +--- + +## Why This Matters + +Setting CC/CXX ensures: +1. **Consistent compiler selection** — All tools (Conan, CMake, etc.) use the same compiler +2. **Correct cache segmentation** — Dependencies are built with the intended compiler +3. **Reproducible builds** — Same inputs produce same outputs regardless of system defaults + +For more information on caching, see [CI Caching Guide](CI_CACHING.md). diff --git a/docs/CI_CACHING.md b/docs/CI_CACHING.md index 48f3cfd..8cf1d72 100644 --- a/docs/CI_CACHING.md +++ b/docs/CI_CACHING.md @@ -38,6 +38,18 @@ Example: `conan-ubuntu-latest-gcc-release-strict-` - **Scope:** Repository and branch (main branch caches are available to PRs) - **Invalidation:** Automatic when `conanfile.txt` or `conanfile.py` changes +### Why CC/CXX Must Be Passed to Conan + +The cache key includes the compiler (gcc/clang), so Conan must actually use that compiler when building packages. Without setting `CC` and `CXX`: + +- Conan detects the system default compiler (usually gcc on Ubuntu) +- Both gcc and clang cache keys end up storing identical gcc-built packages +- You waste cache storage and risk compiler mismatches + +By setting `CC`/`CXX` for Conan steps, each cache key contains packages built with the correct compiler, keeping the cache segmentation accurate and meaningful. + +See [CI Compiler Configuration](CI.md) for details on CC/CXX. + --- ## Cache Hit Scenarios