hiero-ledger / hiero-ledger/hiero-sdk-cpp

[Intermediate]: Add `linux-x64-clang-libstdcxx` preset and gate PRs on a Linux Clang build

Open
#1,619 6 comments 0 reactions 0 assignees View on GitHub
priority: medium scope: build skill: intermediate status: ready for dev
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.