hiero-ledger / hiero-ledger/hiero-sdk-cpp
[Intermediate]: Add `linux-x64-clang-libstdcxx` preset and gate PRs on a Linux Clang build
- Dominant language
- C++
- Stars
- 42
- Forks
- 108
- Avg merge
- 11h 45m
- Merged PRs (30d)
- 2
Description
### 🧩 Intermediate Friendly
This issue is a good fit for contributors who are already familiar with the Hiero C++ SDK and feel comfortable navigating the codebase.
Intermediate Issues often involve:
- Exploring existing implementations
- Understanding how different components work together
- Making thoughtful changes that follow established patterns
The goal is to support deeper problem-solving while keeping the task clear, focused, and enjoyable to work on.
> [!IMPORTANT]
> ### 🧭 About Intermediate Issues
>
> Intermediate Issues are a great next step for contributors who enjoy digging into the codebase and reasoning about how things work.
>
> These issues often:
> - Involve multiple related files or components
> - Encourage investigation and understanding of existing behavior
> - Leave room for thoughtful implementation choices
> - Stay focused on a clearly defined goal
>
> Other kinds of contributions — from beginner-friendly tasks to large system-level changes — are just as valuable and use different labels.
### 👾 Description of the Task
PR-level CI today builds the SDK on Linux only with the runner's default compiler (GCC). Clang-specific compilation issues — for example, the `[[nodiscard]] friend bool operator==(...)` pattern that PR #1516 cleaned up — are not caught until the nightly macOS build runs ~24 hours after merge, by which point the regression has already landed on `main`.
The SDK ships to consumers using both GCC and Clang on Linux. Adding a Clang build job at PR time would catch the most common class of "macOS broke" issues (which are typically Clang frontend issues, not Apple-SDK issues) on the existing self-hosted Linux runners — without paying for GitHub-hosted macOS minutes (~50 min/run) or Windows minutes (~2h 45m/run).
Relevant files:
```
CMakePresets.json
.github/workflows/zxc-build-library.yaml
src/sdk/main/** (only if Clang surfaces errors)
```
### 💡 Proposed Approach
Add a new Clang preset that uses **libstdc++** (the system stdlib that GCC also uses), so vcpkg dependencies built with the existing `x64-linux` triplet remain ABI-compatible. No custom vcpkg triplet is required for this issue.
Wire the new preset into the CI matrix as a parallel job alongside the existing GCC build, on the same self-hosted runner pool. Both builds should run in parallel so wall-clock PR time does not increase materially.
Fix whatever Clang-specific build errors surface. Most likely candidates: stricter handling of attributes on declarations, unused-variable warnings (if `-Werror` is in scope), template-instantiation differences. Keep fixes minimal and idiomatic — avoid Clang-only workarounds; prefer corrections that compile cleanly under both compilers.
Trade-offs:
- **libstdc++ vs libc++:** libstdc++ is chosen here because it shares the system C++ ABI with GCC-built vcpkg dependencies. A separate `linux-x64-clang-libcxx` preset is tracked in a follow-up issue.
- **PR gate vs advisory:** start as a hard PR gate. If it proves too noisy, demote to advisory; do not start as advisory because that defeats the purpose.
### 👩💻 Implementation Steps
- [ ] Add new configure presets in `CMakePresets.json`:
- `linux-x64-clang-libstdcxx-debug`
- `linux-x64-clang-libstdcxx-release`
Each should inherit from `vcpkg-base`, set `CMAKE_C_COMPILER=clang`, `CMAKE_CXX_COMPILER=clang++`, `VCPKG_TARGET_TRIPLET=x64-linux`, and the appropriate `CMAKE_BUILD_TYPE`.
- [ ] Add corresponding build presets if the project uses build-preset entries.
- [ ] Verify the preset configures and builds cleanly locally:
```bash
cmake --preset linux-x64-clang-libstdcxx-debug -DBUILD_TESTS=ON
cmake --build -j 6 --preset linux-x64-clang-libstdcxx-debug
```
- [ ] Address any Clang-specific compilation errors. Keep fixes idiomatic for both compilers; do not introduce Clang-only conditional code.
- [ ] Add a Clang job to the build matrix in `.github/workflows/zxc-build-library.yaml`. Run on the same `hiero-client-sdk-linux-large` self-hosted runner. Ensure the new job runs in parallel with the existing GCC job (i.e., it does not extend wall-clock CI time).
- [ ] Confirm the new job runs on every PR via `flow-pull-request-checks.yaml` and that it is required for merge.
- [ ] Run the test suite under the new preset and confirm parity with the GCC build:
```bash
ctest -j 6 -C Debug --test-dir build/linux-x64-clang-libstdcxx-debug -E NodeUpdateTransactionIntegrationTests --output-on-failure
```
- [ ] Update `CLAUDE.md` and `README.md` to document the new preset alongside the existing ones.
### ✔️ Acceptance Criteria
- [ ] `linux-x64-clang-libstdcxx-debug` and `linux-x64-clang-libstdcxx-release` presets exist and configure/build cleanly on Linux with Clang
- [ ] A new "Build (Linux, clang+libstdc++)" job runs on every PR and is required for merge
- [ ] The new job runs in parallel with the existing GCC job and does not materially increase PR wall-clock time
- [ ] All existing unit and integration tests pass under the Clang build
- [ ] Any source-level fixes compile cleanly under both GCC and Clang
- [ ] Documentation (`CLAUDE.md`, `README.md`) lists the new preset
- [ ] No unrelated behavior or API changes are introduced
---
### 📋 Step-by-Step Contribution Guide
To help keep contributions consistent and easy to review, we recommend following these steps:
- [ ] Comment `/assign` to request the issue
- [ ] Wait for assignment
- [ ] Fork the repository and create a branch
- [ ] Set up the project using the instructions in `README.md`
- [ ] Make the requested changes
- [ ] Sign each commit using `-s -S`
- [ ] Push your branch and open a pull request
Read [Workflow Guide](https://github.com/hiero-ledger/hiero-sdk-cpp/blob/main/docs/training/workflow.md) for step-by-step workflow guidance.
Read [README.md](https://github.com/hiero-ledger/hiero-sdk-cpp/blob/main/README.md) for setup instructions.
❗ Pull requests **cannot be merged** without `S` and `s` signed commits.
See the [Signing Guide](https://github.com/hiero-ledger/hiero-sdk-cpp/blob/main/docs/training/signing.md).
### 🤔 Additional Information
Context for the chosen scope:
- **Recent precedent:** PR #1516 (`refactor: replace friend operator== with member operator==`) fixed a Clang-only compilation error that landed on `main` because the PR-level CI matrix is GCC-only. This issue exists to prevent that class of regression.
- **Why libstdc++:** vcpkg's default `x64-linux` triplet builds C++ dependencies (gRPC, Protobuf, abseil, log4cxx) with the system default compiler, which links against libstdc++. Using Clang+libstdc++ keeps the SDK ABI-compatible with the existing dependency cache. A libc++ variant is tracked separately because it requires a custom vcpkg triplet and a full dep rebuild.
- **Compiler version:** prefer the Clang version available by default on the `hiero-client-sdk-linux-large` runner image. If a specific version is required, document the choice in `CLAUDE.md`.
- **Related follow-up issues:** `add-preset-linux-clang-libcxx.md` (libc++ variant for nightly), `add-preset-linux-gcc.md` (rename + deprecation cycle for the existing `linux-x64-{debug,release}` presets).
If you have questions while working on this issue, feel free to ask! [Hiero-SDK-C++ Discord](https://discord.com/channels/905194001349627914/1337424839761465364)
Contributor guide
Research direction
Start with CMakePresets.json and .github/workflows/zxc-build-library.yaml, comparing the existing Linux GCC presets and build job. Run the listed cmake configure/build commands and the ctest command with the new preset. Done means the Clang libstdc++ presets build and test cleanly, the required parallel PR job is wired in, and CLAUDE.md and README.md document the presets.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cmake, cpp, github-actions
- Domain
- build-system, ci-cd, documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100