docs(03-build): add QNX SDP provisioning

Author: AlexanderLanin

.github/workflows/pr.yml

@@ -49,3 +49,25 @@ jobs:
           path: _build
           retention-days: 1
           if-no-files-found: error
+
+      # FIXME: remove this block
+      - name: Create build metadata
+        # FIXME: temp for development
+        # "ref_name": "${{ github.ref_name }}",
+        run: |
+          cat > build-info.json <<'EOF'
+          {
+            "event_name": "${{ github.event_name }}",
+            "pr_number": "${{ github.event.pull_request.number }}",
+            "ref_name": "main",
+            "head_sha": "${{ github.sha }}"
+          }
+          EOF
+
+      # FIXME: remove this block
+      - name: Upload build metadata
+        uses: actions/upload-artifact@v7.0.1
+        with:
+          name: build-metadata
+          path: build-info.json
+          retention-days: 1

docs/explanation/03-build-infrastructure.md

@@ -208,6 +208,71 @@ Rust already shows the same separation more explicitly. [eclipse-score/toolchain
 - Shared toolchains need visible ownership and an upgrade cadence or repositories will drift again.
 - **Biggest gap**: no cross-repository process clearly defines who owns toolchain baselines and how changes propagate.
 
+### 3.3.5 QNX SDP Provisioning
+
+*How the QNX Software Development Platform is obtained and made available to Bazel C++ builds.*
+
+The QNX SDP — the compiler, headers, and libraries required for QNX cross-compilation — is a commercial artifact distributed separately from the toolchain configuration. Its provisioning path is distinct from the Bazel toolchain registration in `bazel_cpp_toolchains` and determines how reliably builds can acquire the SDP in CI and in local developer environments.
+
+License on CI:  A separate [`setup-qnx-sdp`](https://github.com/eclipse-score/cicd-actions) composite action handles license activation only; it does not fetch or unpack the SDP
+
+License locally: License credentials are injected through environment variables.
+
+#### Today
+
+The SDP is downloaded as a tar archive from QNX.com via a hardcoded dependency URL in Bazel. Forks may overwrite this dependency.
+
+```{mermaid}
+flowchart LR
+    qnxcom(["QNX.com"])
+    sdp_tar["`QNX SDP
+〈artefact: tar〉`"]
+    env_cfg(["Local Environment variables"])
+    license(["License"])
+    action_setup["`setup-qnx-sdp
+(license only)`"]
+    bazel["Bazel build C++"]
+
+    qnxcom --> sdp_tar
+    sdp_tar -->|"hardcoded dependency URL"| bazel
+    action_setup --> license
+    env_cfg --> license
+    
+    license -->|"activates license only"| bazel
+```
+
+The license and the SDP fetch are deliberately separate.
+
+#### Soon (planned)
+
+The target model does not rely on QMX.com, but rather uses the QNX CLI distributed with QNX Software Center to produce a local SDP. That SDP is then stored in bazel cache, on your local computer, in ci cache, on protected eclipse artefact storage, or on company-internal artefact storage — and Bazel receives a user-defined flag that tells it where to find the SDP. For local developer environments the intended invocation is:
+
+```text
+bazel run //:local_qnx_sdp -- --path=/opt/qnx_sdp
+# or
+local_qnx_sdp.sh --path=/opt/qnx_sdp
+```
+
+```{mermaid}
+flowchart TD
+    qnx_sc(["QNX Software Center"])
+    qnx_cli["`QNX CLI
+〈tool〉`"]
+    sdp_dir["`QNX SDP
+〈artefact: directory tree〉`"]
+    art_store[("Artefact storage
+eclipse · company-internal · local")]
+    bazel["Bazel build C++"]
+
+    qnx_sc -.-> qnx_cli
+    qnx_cli -.-> sdp_dir
+    sdp_dir -.-> art_store
+    art_store -.->|"user-defined flag"| bazel
+```
+
+The central unsolved problem in this model is how we can provide this SDP as a true bazel dependency to qnx-related builds, as it has a **non-deterministic SDP output**. So building the SDP on the fly produces a different archive hash on every invocation. Bazel treats a changed hash as a changed dependency, which invalidates the **entire** C++ build cache and forces a full recompilation of all downstream targets on every run. Until the SDP can be built deterministically using it as a bazel dependency is not practical.
+
+
 ## 3.4 Build Reproducibility & Evidence ⚪
 
 *Ensuring builds are deterministic and produce trustworthy evidence from the same inputs.*

docs/explanation/04-testing-infrastructure.md

@@ -69,12 +69,18 @@ The execution pipeline for ITF tests follows a layered model. Bazel invokes a py
 ```{mermaid}
 graph TD
     bazel["bazel test //path:my_itf_test"]
-    pytest["pytest runner\n(py_itf_test macro)"]
-    plugin["ITF Plugin\n(Docker / QEMU / Hardware)"]
-    target["Target environment\n(container / VM / device)"]
-    caps["@requires_capabilities\nskip if not available"]
-    results["JUnit XML\n($XML_OUTPUT_FILE)"]
-    trace["@add_test_properties\ntraceability metadata"]
+    pytest["`pytest runner
+(py_itf_test macro)`"]
+    plugin["`ITF Plugin
+(Docker / QEMU / Hardware)`"]
+    target["`Target environment
+(container / VM / device)`"]
+    caps["`@requires_capabilities
+skip if not available`"]
+    results["`JUnit XML
+($XML_OUTPUT_FILE)`"]
+    trace["`@add_test_properties
+traceability metadata`"]
 
     bazel --> pytest
     pytest --> plugin

docs/explanation/07-automation-integration.md

@@ -24,21 +24,26 @@ graph TD
     schedule["Schedule / release trigger"]
 
     subgraph shared["Shared workflow libraries"]
-        cwf["`cicd-workflows\non-pr.yml · daily.yml`"]
-        cac["`cicd-actions\n(composite actions)`"]
+        cwf["`cicd-workflows
+on-pr.yml · daily.yml`"]
+        cac["`cicd-actions
+(composite actions)`"]
     end
 
     subgraph runners["Runners"]
-        cloud["GitHub-hosted\n(cloud: x86, ARM, KVM)"]
-        hw["Self-hosted\n(hardware: RPi, automotive SoC)"]
+        cloud["`GitHub-hosted
+(cloud: x86, ARM, KVM)`"]
+        hw["`Self-hosted
+(hardware: RPi, automotive SoC)`"]
     end
 
     pr --> cwf
     schedule --> cwf
     cwf --> cac
     cac --> cloud
     cac --> hw
-    cloud --> results["Status checks\nArtifacts / evidence"]
+    cloud --> results["`Status checks
+Artifacts / evidence`"]
     hw --> results
     results -->|"required checks via otterdog"| pr
 ```