Skip to content

Commit b2efbe9

Browse files
Adityarya11Adityarya11
committed
feat: added CI workflow for examples.
Signed-off-by: Aditya Arya <arya050411@gmail.com>
1 parent 1f35a14 commit b2efbe9

5 files changed

Lines changed: 404 additions & 32 deletions

File tree

‎.ci/examples-manifest.txt‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Example execution manifest for CI.
2+
# Format:
3+
# <binary-name>|<mode>|<timeout-seconds>|<args>|<note>
4+
# mode: run or skip
5+
6+
hiero-sdk-cpp-consensus-pub-sub-chunked-example|skip|180||Infinite receive loop by design.
7+
hiero-sdk-cpp-validate-checksum-example|skip|180||Interactive std::cin loop is not CI-safe.
8+
hiero-sdk-cpp-schedule-network-update-example|skip|180||Sleeps for one hour by design.
9+
hiero-sdk-cpp-solidity-precompile-example|skip|180||Path assumptions differ between source and CI runtime.
10+
hiero-sdk-cpp-zero-token-operations-example|skip|180||Path assumptions differ between source and CI runtime.
11+
12+
hiero-sdk-cpp-token-metadata-example|run|240|-ft|Requires either -ft or -nft argument.
13+
hiero-sdk-cpp-consensus-pub-sub-example|run|240||Longer timeout for network propagation.
14+
hiero-sdk-cpp-consensus-pub-sub-with-submit-key-example|run|240||Longer timeout for network propagation.
15+
hiero-sdk-cpp-long-term-scheduled-transaction-example|run|240||Longer timeout due scheduled execution flow.

‎.github/workflows/flow-run-examples.yaml‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
name: Run Examples
2+
3+
# --- ORIGINAL TRIGGERS (RESTORE FOR FINAL UPSTREAM PR) ---
4+
# on:
5+
# pull_request:
6+
# push:
7+
# branches:
8+
# - main
9+
# - "release/**"
10+
# workflow_dispatch:
11+
12+
# -----------------------------------------------------------------------------
13+
# --- FORK TESTING TRIGGERS (REMOVE THIS BLOCK BEFORE FINAL UPSTREAM PR) ---
14+
# -----------------------------------------------------------------------------
15+
on:
16+
pull_request:
17+
branches:
18+
- main
19+
types:
20+
- opened
21+
- reopened
22+
- synchronize
23+
push:
24+
branches:
25+
- "**"
26+
workflow_dispatch:
27+
28+
defaults:
29+
run:
30+
shell: bash
31+
32+
permissions:
33+
contents: read
34+
35+
concurrency:
36+
group: run-examples-${{ github.event.pull_request.number || github.ref }}
37+
cancel-in-progress: true
38+
39+
jobs:
40+
run-examples:
41+
name: Build and run SDK examples (Linux + Solo)
42+
43+
# --- ORIGINAL RUNNER (RESTORE FOR FINAL UPSTREAM PR) ---
44+
# runs-on: hiero-client-sdk-linux-large
45+
46+
# -------------------------------------------------------------------------
47+
# --- FORK TESTING RUNNER (REMOVE BEFORE FINAL UPSTREAM PR) ---
48+
# -------------------------------------------------------------------------
49+
runs-on: ubuntu-latest
50+
timeout-minutes: 60
51+
52+
steps:
53+
- name: Harden runner (audit outbound calls)
54+
uses: step-security/harden-runner@f808768d1510423e83855289c910610ca9b43176 # v2.17.0
55+
with:
56+
egress-policy: audit
57+
58+
- name: Checkout repository
59+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
60+
with:
61+
submodules: true
62+
63+
- name: Use Node.js 22
64+
uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
65+
with:
66+
node-version: 22
67+
68+
- name: Install build dependencies
69+
run: |
70+
sudo apt-get update
71+
sudo apt-get install -y pkg-config libc6-dbg libgtest-dev build-essential
72+
73+
- name: Ensure binary cache path exists
74+
run: mkdir -p "${{ github.workspace }}/b/vcpkg_cache"
75+
76+
- name: Install CMake and Ninja
77+
uses: step-security/get-cmake@81a83056b6dd1f2bcf67bc6f26b7b08e1cbb86bc # v4.2.3
78+
with:
79+
useCloudCache: true
80+
81+
- name: Setup VCPkg
82+
uses: step-security/run-vcpkg@48490398616947b0df92dc1b24aab5339a66f9f0 # v11.5.2
83+
with:
84+
binaryCachePath: ${{ github.workspace }}/b/vcpkg_cache
85+
86+
- name: Convert VCPkg to full clone
87+
working-directory: vcpkg
88+
run: |
89+
if [[ "$(git rev-parse --is-shallow-repository)" == "true" ]]; then
90+
git fetch --unshallow --prune
91+
else
92+
git fetch --prune
93+
fi
94+
95+
- name: Prepare Hiero Solo
96+
id: solo
97+
uses: hiero-ledger/hiero-solo-action@692b186bd2e4c8d46b9deb1c067dc6ddcf0abcd7 # v0.18.0
98+
with:
99+
soloVersion: v0.68.0
100+
installMirrorNode: true
101+
mirrorNodeVersion: v0.151.0
102+
hieroVersion: v0.72.0
103+
dualMode: true
104+
105+
- name: Configure CMake
106+
run: |
107+
cmake --preset linux-x64-release \
108+
-DBUILD_EXAMPLES=ON \
109+
-DBUILD_TESTS=OFF \
110+
-DBUILD_TCK=OFF \
111+
-DBUILD_TCK_TESTS=OFF
112+
113+
- name: Build examples
114+
run: |
115+
cmake --build build/linux-x64-release --config Release -j 6
116+
117+
- name: Run examples
118+
env:
119+
OPERATOR_ID: ${{ steps.solo.outputs.accountId }}
120+
OPERATOR_KEY: ${{ steps.solo.outputs.privateKey }}
121+
HIERO_TESTNET_CONFIG_PATH: config/local_node.json
122+
HIERO_NETWORK: testnet
123+
NETWORK_NAME: testnet
124+
PASSPHRASE: passphrase
125+
DEFAULT_TIMEOUT_SECONDS: "180"
126+
EXECUTABLES_DIRECTORY: build/linux-x64-release/src/sdk/examples/Release
127+
EXAMPLE_MANIFEST_PATH: .ci/examples-manifest.txt
128+
run: |
129+
chmod +x ./run_examples.sh
130+
./run_examples.sh
131+
132+
- name: Publish example summary
133+
if: always()
134+
run: |
135+
if [[ -f .ci/example-results.txt ]]; then
136+
cat .ci/example-results.txt >> "$GITHUB_STEP_SUMMARY"
137+
else
138+
echo "No example results were generated." >> "$GITHUB_STEP_SUMMARY"
139+
fi
140+
141+
if [[ -f .ci/example-failures.txt ]] && [[ -s .ci/example-failures.txt ]]; then
142+
{
143+
echo
144+
echo "Failure excerpts"
145+
echo '```text'
146+
cat .ci/example-failures.txt
147+
echo '```'
148+
} >> "$GITHUB_STEP_SUMMARY"
149+
fi
150+
151+
- name: Upload example run logs (always)
152+
if: always()
153+
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
154+
with:
155+
name: run-examples-logs
156+
path: |
157+
.ci/example-results.txt
158+
.ci/example-failures.txt
159+
.ci/example-logs/
160+
if-no-files-found: ignore

‎README.md‎

Lines changed: 40 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ The C++ SDK for interacting with a [Hiero](https://hiero.org) network.
4343
- [NASM](https://www.nasm.us) (`nasm.exe` must be added to `%PATH%`)
4444

4545
#### Run
46+
4647
```powershell
4748
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
4849
```
@@ -93,12 +94,12 @@ cmake --build --preset macos-arm64-release
9394

9495
The following optional flags can be added during configuration:
9596

96-
| Flag | Default | Description |
97-
|------|---------|-------------|
98-
| `BUILD_TESTS` | `OFF` | Include the test suite in the build |
99-
| `BUILD_TCK` | `OFF` | Include TCK tests in the build |
100-
| `BUILD_EXAMPLES` | `OFF` | Include example programs in the build |
101-
| `BUILD_TCK_TESTS`| `OFF` | Include TCK Server unit tests in the build |
97+
| Flag | Default | Description |
98+
| ----------------- | ------- | ------------------------------------------ |
99+
| `BUILD_TESTS` | `OFF` | Include the test suite in the build |
100+
| `BUILD_TCK` | `OFF` | Include TCK tests in the build |
101+
| `BUILD_EXAMPLES` | `OFF` | Include example programs in the build |
102+
| `BUILD_TCK_TESTS` | `OFF` | Include TCK Server unit tests in the build |
102103

103104
Example with all options enabled:
104105

@@ -148,9 +149,7 @@ Once your local network is running, verify the configuration in `config/local_no
148149
"network": {
149150
"0.0.3": "127.0.0.1:50211"
150151
},
151-
"mirrorNetwork": [
152-
"127.0.0.1:5600"
153-
],
152+
"mirrorNetwork": ["127.0.0.1:5600"],
154153
"operator": {
155154
"accountId": "0.0.2",
156155
"privateKey": "302e020100300506032b65700422042091132178e72057a1d7528025956fe39b0b847f200ab59b2fdd367017f3087137"
@@ -172,21 +171,23 @@ Examples demonstrate various SDK features and must be run from the project root
172171

173172
Create a `.env` file in the project root with the following variables:
174173

175-
| Variable | Description |
176-
|----------|-------------|
177-
| `OPERATOR_ID` | The ID of the operator account (e.g., `0.0.1234`) |
178-
| `OPERATOR_KEY` | The DER-encoded hex private key of the operator account |
179-
| `HIERO_NETWORK` | Network name: `mainnet`, `testnet`, or `previewnet` |
180-
| `PASSPHRASE` | (Optional) Passphrase for mnemonic-based key generation |
174+
| Variable | Description |
175+
| --------------- | ------------------------------------------------------- |
176+
| `OPERATOR_ID` | The ID of the operator account (e.g., `0.0.1234`) |
177+
| `OPERATOR_KEY` | The DER-encoded hex private key of the operator account |
178+
| `HIERO_NETWORK` | Network name: `mainnet`, `testnet`, or `previewnet` |
179+
| `PASSPHRASE` | (Optional) Passphrase for mnemonic-based key generation |
181180

182181
### Running Examples
183182

184183
#### Mac
184+
185185
```C++
186186
package/Release/Darwin/arm64/examples/Release/<EXAMPLE-NAME>
187187
```
188188

189189
#### Windows
190+
190191
```C++
191192
package\Release\Windows\AMD64\examples\Release\<EXAMPLE-NAME>
192193
```
@@ -212,7 +213,30 @@ You can run all examples using the provided scripts:
212213
- macOS/Linux: `run_examples.sh`
213214
- Windows: `run_examples.bat`
214215

215-
Before running, update the `EXECUTABLES_DIRECTORY` variable in the script to point to your build output folder.
216+
By default, `run_examples.sh` auto-detects common build output folders. You can override with:
217+
218+
```sh
219+
EXECUTABLES_DIRECTORY=build/linux-x64-release/src/sdk/examples/Release ./run_examples.sh
220+
```
221+
222+
The script also supports manifest-driven behavior for CI:
223+
224+
- `EXAMPLE_MANIFEST_PATH`: Override the manifest path (defaults to `.ci/examples-manifest.txt`)
225+
- `DEFAULT_TIMEOUT_SECONDS`: Per-example timeout default (defaults to `180`)
226+
227+
### CI Example Validation
228+
229+
Examples are automatically validated in CI by the `Run Examples` workflow:
230+
231+
- Workflow: `.github/workflows/flow-run-examples.yaml`
232+
- Manifest: `.ci/examples-manifest.txt`
233+
- Results: `.ci/example-results.txt`
234+
- Failure excerpts: `.ci/example-failures.txt`
235+
236+
The CI workflow sets `HIERO_TESTNET_CONFIG_PATH=config/local_node.json` so examples that call `Client::forTestnet()`
237+
execute against a Solo local network instead of public testnet.
238+
239+
The workflow fails when any non-skipped example fails.
216240

217241
## Contributing
218242

0 commit comments

Comments
 (0)