hiero-ledger / hiero-ledger/hiero-sdk-cpp
[Beginner]: Add `linux-x64-gcc-{debug,release}` presets and document `linux-x64-{debug,release}` as GCC defaults
- Dominant language
- C++
- Stars
- 42
- Forks
- 108
- Avg merge
- 11h 45m
- Merged PRs (30d)
- 2
Description
### 🐥 Beginner Friendly
This issue is a great fit for contributors who are ready to explore the Hiero C++ codebase a little more and take on slightly more independent work.
Beginner Issues often involve reading existing C++ code, understanding how different parts of the SDK fit together, and making small, thoughtful updates that follow established patterns.
The goal is to support skill growth while keeping the experience approachable, well-scoped, and enjoyable.
> [!IMPORTANT]
> ### 🐥 About Beginner Issues
>
> Beginner Issues are a great next step for contributors who feel comfortable with the basic project workflow and want to explore the codebase a little more.
>
> These issues often involve:
> - Reading existing C++ code
> - Understanding how different parts of the SDK fit together
> - Making small, thoughtful updates that follow established patterns
>
> You'll usually see Beginner Issues focused on things like:
> - Small, well-scoped improvements to existing tests
> - Narrow updates to `src` functionality (e.g. refining helpers or improving readability)
> - Documentation or comment clarity
> - Enhancements to existing examples
>
> Other types of contributions — such as brand-new features, broader system changes, or deeper technical work — are just as valuable and may use different labels.
### 👾 Description of the Task
The current Linux configure presets are `linux-x64-debug` and `linux-x64-release`. They build with the system default compiler — GCC on the supported runner image — but the preset names do not communicate this, and the compiler is not set explicitly in the preset. Once additional compiler presets land (#1619, #1620), having an unqualified name that is implicitly "the GCC one" without saying so anywhere is fragile: a future runner-image change to the default `cc` symlink could silently flip the compiler underneath us.
This issue introduces explicit, self-describing names `linux-x64-gcc-debug` and `linux-x64-gcc-release` for CI matrix use, while keeping the unqualified `linux-x64-{debug,release}` names as the canonical entry points for local development. The unqualified names will be made explicit (via inheritance from the gcc-named presets) rather than relying on implicit PATH-based compiler resolution. No preset is deprecated.
Relevant files:
```
CMakePresets.json
.github/workflows/zxc-build-library.yaml
.github/workflows/on-schedule-builds.yaml
CLAUDE.md
README.md
```
### 💡 Proposed Approach
Use CMake preset inheritance so both names point at the same configuration, with the compiler set explicitly in the canonical preset:
1. **Define** `linux-x64-gcc-debug` and `linux-x64-gcc-release` as the canonical presets, containing the actual cache variables and `CMAKE_C_COMPILER`/`CMAKE_CXX_COMPILER` set explicitly to `gcc`/`g++`.
2. **Redefine** `linux-x64-debug` and `linux-x64-release` as thin presets that `inherits` from the new ones and contain no other cache variables. These remain the recommended dev-facing entry point — they are **not** deprecated.
3. **Update CI matrix references** — `.github/workflows/zxc-build-library.yaml`, `.github/workflows/on-schedule-builds.yaml` — to use the explicit `linux-x64-gcc-*` names so each job advertises which compiler it is exercising.
4. **Update documentation** in `CLAUDE.md` and `README.md` to call out that `linux-x64-{debug,release}` defaults to GCC, and to describe the compiler-explicit `linux-x64-gcc-*` (and forthcoming `linux-x64-clang-*`) names as alternatives intended for CI matrix coverage and contributors specifically testing toolchain portability.
The same naming pattern (`---`) should be applied consistently as new presets are added in the sibling Clang issues, so the project converges on a self-describing convention for the compiler-explicit names without retiring the short, dev-friendly defaults.
Trade-offs:
- **Apply the same explicit-compiler pattern to `macos-arm64-*` and `windows-x64-*`?** Not in this issue. Those preset names are also implicitly "the only compiler we have on that platform," but adding compiler-explicit aliases now means churn without a concrete second compiler in sight. Defer until/if a second compiler is added on those platforms.
- **Why keep `linux-x64-{debug,release}` as the dev-facing default rather than directing everyone to `linux-x64-gcc-*`?** The unqualified names are what contributors already know from `CLAUDE.md`, `README.md`, and muscle memory; they are the path of least friction for someone who just wants to build the SDK and does not have an opinion about compilers. The compiler-explicit names earn their value in CI matrix logs (where you want to see `Build (Linux, gcc)` / `Build (Linux, clang+libstdc++)` side-by-side), not in onboarding flows. Keeping both, with the unqualified set as the dev default, gives explicit-compiler hygiene without forcing contributors to form an opinion they do not have.
### 👩💻 Implementation Steps
- [ ] In `CMakePresets.json`, add new configure presets:
- `linux-x64-gcc-debug` — inherits from `vcpkg-base`, sets `CMAKE_C_COMPILER=gcc`, `CMAKE_CXX_COMPILER=g++`, `VCPKG_TARGET_TRIPLET=x64-linux`, `CMAKE_BUILD_TYPE=Debug`
- `linux-x64-gcc-release` — same but `CMAKE_BUILD_TYPE=Release`
- [ ] Modify the existing `linux-x64-debug` and `linux-x64-release` configure presets so they `inherits` from the new gcc-named presets and contain no other cache variables. Do **not** mark them deprecated; their `description` field should make clear they are aliases that default to GCC (for example: `"Linux x64 Debug — defaults to GCC; alias of linux-x64-gcc-debug."`).
- [ ] If the project defines build presets matching the configure presets, mirror the same alias-via-inheritance pattern there.
- [ ] Verify both old and new names still work locally:
```bash
cmake --preset linux-x64-gcc-debug
cmake --preset linux-x64-debug # alias, points at the same configuration
```
Note: the build directory is `${sourceDir}/build/${presetName}`, so the alias preset and the canonical preset will produce *different* build directories. Both work, but switching between names triggers a separate configure.
- [ ] Update CI workflows to use the explicit names so each job's logs advertise its compiler:
- `.github/workflows/zxc-build-library.yaml` — replace `linux-x64-*` matrix entry references with `linux-x64-gcc-*`
- `.github/workflows/on-schedule-builds.yaml` — same
- [ ] Update documentation:
- `CLAUDE.md` — Build Commands section. Document that `linux-x64-{debug,release}` is the recommended preset for normal local development and defaults to GCC. List the compiler-explicit `linux-x64-gcc-*` / `linux-x64-clang-*` names alongside, noting they exist for CI matrix coverage and for contributors specifically testing toolchain portability.
- `README.md` — mirror the same coverage in setup instructions: lead with `linux-x64-{debug,release}` as the default and call out that it defaults to GCC; mention the compiler-explicit variants as alternatives.
- Any other docs under `docs/` that reference preset names should follow the same pattern.
- [ ] Run a configure + build with both the new canonical preset and the alias to confirm parity.
### ✔️ Acceptance Criteria
- [ ] `linux-x64-gcc-debug` and `linux-x64-gcc-release` presets exist with explicit `CMAKE_C_COMPILER=gcc` / `CMAKE_CXX_COMPILER=g++` and produce equivalent builds to the previous `linux-x64-debug` / `linux-x64-release`
- [ ] `linux-x64-debug` and `linux-x64-release` continue to work as thin aliases that inherit from the gcc-named presets, and remain the recommended dev-facing entry point (no deprecation markers anywhere)
- [ ] CI workflows reference the explicit `linux-x64-gcc-*` names so each job advertises its compiler
- [ ] `CLAUDE.md` and `README.md` document that `linux-x64-{debug,release}` defaults to GCC and call out the compiler-explicit alternatives
- [ ] No CI workflow regressions (Linux PR build still passes)
- [ ] 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:
- **Why now:** the project is about to add `linux-x64-clang-libstdcxx-*` and `linux-x64-clang-libcxx-*` presets (tracked in sibling issues). Establishing the explicit `---` convention now — for the compiler-explicit names — means future preset additions slot in cleanly alongside `linux-x64-gcc-*` without requiring a follow-up rename round.
- **Why keep the unqualified names rather than rename them:** the unqualified names are the contributor-facing default that already lives in CLAUDE.md, README, IDE configs, and local scripts. Removing them would force every new contributor to form an opinion about compiler choice before they can build, when most contributors just want a working build. Keeping the short names as GCC-defaulting aliases preserves the onboarding path while still moving the compiler choice from implicit (PATH-based) to explicit (set in the preset).
- **`macos-x64-*` presets:** an earlier review surfaced that the `macos-x64-debug`/`-release` presets are not exercised in CI today (the CI uses `macos-arm64-*`). Whether to revisit those is a separate discussion and out of scope here.
- **Related sibling issues:** #1619 (Intermediate / PR gate — Clang + libstdc++), #1620 (Intermediate / nightly — Clang + libc++).
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 in CMakePresets.json by comparing the existing linux-x64-debug and linux-x64-release presets, then inspect the Linux matrix references in .github/workflows/zxc-build-library.yaml and .github/workflows/on-schedule-builds.yaml. Update the named presets, aliases, workflows, CLAUDE.md, and README.md as specified, then run configure and build commands with both the GCC presets and aliases to confirm parity.
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
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100