Skip to content

S24.06: Retire Example/FreeRtos/HelloWorld bring-up smoke binary #335

Description

@DavidCozens

Parent epic: #254 (E24: Code Hygiene)

Should land before: #333 (S24.05 moves Example/FreeRtos/SingleTask/Bdd/Targets/FreeRtos/. Retiring HelloWorld first lets that story relocate a clean single-child tree instead of a two-child one that needs splitting mid-move.)

Overview

Example/FreeRtos/HelloWorld/ is a minimal QEMU bring-up smoke ELF
— one task printing one line over the CMSDK UART, no IP stack, no
syslog. It was the right shape during S08 bring-up when the
cross-compile / scheduler / UART / newlib chain was the unknown.
After S08.03 + S08.04 closed out, Example/FreeRtos/SingleTask/
exercises every layer HelloWorld did, plus FreeRTOS-Plus-TCP, plus
the full library, plus the BDD scenarios. The diagnostic separation
HelloWorld provided is no longer load-bearing.

Why

  • SingleTask is a strict superset of HelloWorld at runtime. If
    SingleTask hangs before the SolidSyslog> prompt, the
    toolchain/scheduler/UART/newlib chain is suspect — same signal
    HelloWorld gave. After the prompt, IP/syslog is in play.
  • The HelloWorld retirement was already flagged as a slice-3 gate
    in the S08.04 plan (see DEVLOG 2026-05-11 "S08.04 slice 2"
    Deferred to slice 3 — HelloWorld retirement decision).
  • Pre-launch (v0.0.0); no external readers.
  • Carrying both means two QEMU smoke steps in CI's
    build-freertos-target job and two VS Code launch/task entries
    to keep in sync.

In scope

  • Delete Example/FreeRtos/HelloWorld/ (directory + its
    add_subdirectory(HelloWorld) line in
    Example/FreeRtos/CMakeLists.txt).
  • .github/workflows/ci.ymlbuild-freertos-target job:
    • Drop SolidSyslogFreeRtosHelloWorld from the cmake --build --target ... list.
    • Drop the HelloWorld QEMU smoke step that runs the ELF and
      asserts on its stdout.
    • The SingleTask cross-build remains; it is itself the smoke.
  • .vscode/tasks.json — the freertos-cross branch of the
    build-and-test task currently builds
    SolidSyslogFreeRtosHelloWorld. Switch to
    SolidSyslogFreeRtosSingleTask. The "run on QEMU (FreeRTOS)"
    task's -kernel ...HelloWorld.elf path becomes
    ...SingleTask/SolidSyslogFreeRtosSingleTask.elf.
  • .vscode/launch.json — rename / repoint the
    Debug FreeRTOS HelloWorld (QEMU) launch config to the
    SingleTask ELF. (Bikeshed: "Debug FreeRTOS SingleTask (QEMU)".)
  • Example/FreeRtos/README.md — rewrite the table (one row,
    SingleTask) and update the VS Code Ctrl+Shift+B / Run-task /
    command-line / GDB sections to reference the SingleTask ELF
    path.
  • docs/ci.md — update the build-freertos-target row (the
    "QEMU bring-up smoke for HelloWorld" wording).
  • docs/containers.md — update the Debug FreeRTOS HelloWorld (QEMU) reference to match the renamed launch config.
  • Example/FreeRtos/Common/CMSDK_UART.md — strip the "HelloWorld"
    contextual references (the doc is still useful for SingleTask).
  • Example/FreeRtos/cmake/arm-none-eabi.cmake — comment-only
    cleanup of the HelloWorld / SingleTask mention.

Acceptance criteria

  • Example/FreeRtos/HelloWorld/ no longer exists.
  • build-freertos-target CI job is green, builds only the
    SingleTask ELF, and still serves the artefact to
    bdd-freertos-qemu.
  • bdd-freertos-qemu is green.
  • No references to SolidSyslogFreeRtosHelloWorld or
    HelloWorld.elf remain in CMakeLists, CI workflow, VS Code
    config, or live docs (DEVLOG history is exempt).
  • VS Code build/run/debug tasks under the freertos-target
    service drive SingleTask end-to-end.

Out of scope

Risks

  • After deletion, the only thing that exercises the cross-compile
    • QEMU boot path under CI is SingleTask. If SingleTask fails to
      build before reaching main, CI will surface the same failure
      HelloWorld would have — but the diff is one toolchain bring-up
      vs. a binary that also pulls in FreeRTOS-Plus-TCP and the
      library. If the toolchain regressions we've actually hit in CI
      history were FreeRTOS-Plus-TCP-aware, this is a net-zero. If
      any were lower-layer (linker script, vector table, newlib
      retargeting), SingleTask still catches them — but with a longer
      "where in the boot did it fail" investigation window.
  • Mitigation: SingleTask's main boots a Service task before
    the IP stack is up, and the BDD harness times out on a missing
    prompt — same human-readable signal HelloWorld's stdout gave.

References

  • Memory: project_freertos_helloworld_retirement (watching
    brief carried through S08.04).
  • DEVLOG 2026-05-11 "S08.04 slice 2: FreeRTOS example switches
    to CircularBuffer + FreeRtosMutex" — Deferred to slice 3
    flagged the retirement gate.
  • E24 E24: Code Hygiene #254 charter — "Other code-quality work that doesn't
    belong under a capability-focused epic".

Metadata

Metadata

Assignees

No one assigned

    Labels

    storyStory issue

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions