Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 33 additions & 33 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ jobs:

- name: Install mcpp
run: |
# ⚠️ A LOOP, BECAUSE ONE `xlings update` CAN RETURN A STALE INDEX
# A LOOP, BECAUSE ONE `xlings update` CAN RETURN A STALE INDEX
# WITHOUT SAYING SO.
#
# The index is published as an artifact behind a pointer, and that
Expand All @@ -57,7 +57,7 @@ jobs:
# of the two situations it is.
for attempt in 1 2 3 4 5 6; do
xlings update > /dev/null 2>&1 || true
if # ⚠️ THE PIN MAY NAME THE RELEASE THIS RUN IS VALIDATING, which does
if # THE PIN MAY NAME THE RELEASE THIS RUN IS VALIDATING, which does
# not exist yet — that is the whole point of MCPP_SOURCE_REF. Bootstrap
# from whatever the index has; the step below replaces it with the
# build under review, and the pin is what an ordinary run tests.
Expand All @@ -73,7 +73,7 @@ jobs:
echo "the index has not caught up yet (attempt $attempt of 6); waiting 60s"
sleep 60
done
# ⚠️⚠️ TRANSITION: GIVE THE BOOTSTRAP THE glibc ITS BINDING NAMES.
# TRANSITION: GIVE THE BOOTSTRAP THE glibc ITS BINDING NAMES.
#
# `xim:glibc`'s `latest` moved from `2.44` to `2.44.2`. A payload
# directory is named after the version a request RESOLVED to, while a
Expand All @@ -85,13 +85,13 @@ jobs:
# error: selected RuntimeBinding glibc@2.44 requires payload
# '…/xpkgs/xim-x-glibc/2.44', but it is not installed
#
# ⚠️ On every NEW machine and on none that already existed, which is why
# On every NEW machine and on none that already existed, which is why
# it is invisible from a developer's own. Measured on `main` as readily
# as on any branch — the index records the same failure verbatim in
# `pkgs/g/glibc.lua` and states the rule it broke: "The index is DATA
# and the client is a PROGRAM: the consumer ships first."
#
# REMOVE THIS once a released mcpp resolves it. `mcpp 2026.8.27.1`
# REMOVE THIS once a released mcpp resolves it. `mcpp 2026.8.27.1`
# accepts an installed payload whose version REFINES the requested one
# (`payload_dir_for_version`), so a bootstrap from it needs nothing
# here. Until then the missing payload is simply installed.
Expand All @@ -103,13 +103,13 @@ jobs:
fi
mcpp --version
mcpp self config --mirror GLOBAL
# ⭐⭐ CROSS-VALIDATION: BUILD THE mcpp UNDER REVIEW AND USE THAT ONE.
# CROSS-VALIDATION: BUILD THE mcpp UNDER REVIEW AND USE THAT ONE.
#
# Empty in the ordinary run, so this job keeps testing the RELEASED
# mcpp the pin above names. Set it — `workflow_dispatch` input, or the
# repository variable — and the same job runs against that source.
#
# ⚠️ THIS EXISTS BECAUSE THE ORDER USED TO BE WRONG. Several mcpp
# THIS EXISTS BECAUSE THE ORDER USED TO BE WRONG. Several mcpp
# releases went out green and only then turned this ecosystem red: the
# engine's own CI cannot see a defect that appears only in a real
# dependency graph, and this repository could not see the engine until
Expand All @@ -122,7 +122,7 @@ jobs:
[ -d "$src" ] || git clone --quiet --depth 1 \
--branch "$MCPP_SOURCE_REF" \
https://github.com/mcpp-community/mcpp.git "$src"
# ⚠️ THE CLONE'S OWN WORKSPACE PIN MUST NOT DECIDE WHICH mcpp
# THE CLONE'S OWN WORKSPACE PIN MUST NOT DECIDE WHICH mcpp
# BUILDS IT. `.xlings.json` at mcpp's root pins the mcpp that
# compiles mcpp, and that pin does not move when mcpp is released —
# so a build inside the checkout obeys it and tries to install a
Expand All @@ -135,7 +135,7 @@ jobs:
# above, which is exactly what removing the file leaves.
rm -f "$src/.xlings.json"
( cd "$src" && mcpp build --release )
# ⚠️ BOTH SPELLINGS, AND NO `-perm`. The matrix reaches Windows and
# BOTH SPELLINGS, AND NO `-perm`. The matrix reaches Windows and
# macOS runners too: on Windows the artefact is `mcpp.exe`, and
# `-perm -u+x` is not a question that filesystem answers the way this
# expects. Measured: `Finished release [optimized] in 173.44s`
Expand All @@ -149,13 +149,13 @@ jobs:
\( -name mcpp -o -name mcpp.exe \) | head -1)
[ -n "$built" ] || { echo "::error::mcpp did not build from $MCPP_SOURCE_REF"; exit 1; }
echo "$(cd "$(dirname "$built")" && pwd)" >> "$GITHUB_PATH"
# ⚠️ Reported, because a PATH entry that does not win looks exactly
# Reported, because a PATH entry that does not win looks exactly
# like one that does until something built with the wrong engine.
echo "under review: $("$built" --version) (from $MCPP_SOURCE_REF)"
fi


# ⚠️⚠️ A JOB THAT RESOLVES THE PUBLISHED SPECIFICATION CANNOT REVIEW A
# A JOB THAT RESOLVES THE PUBLISHED SPECIFICATION CANNOT REVIEW A
# CHANGE TO ONE.
#
# Another step in this file already clones the specification and
Expand All @@ -167,7 +167,7 @@ jobs:
# synced index ... the index is current, so this name is either
# wrong or not published yet
#
# ⭐⭐ THE UNIT IS THE JOB, NOT THE REPOSITORY. Measured 2026-08-28 across
# THE UNIT IS THE JOB, NOT THE REPOSITORY. Measured 2026-08-28 across
# the eight repositories of this ecosystem while one change spanned all of
# them: seven jobs in three repositories had this shape, and every one of
# those repositories ALSO had a job that substituted correctly --- which is
Expand All @@ -187,11 +187,11 @@ jobs:
else
echo "the specification has no $OPENKAL_BRANCH; its default branch is used"
fi
# ⚠️ EVERY MANIFEST THAT NAMES IT, AND BY THE SAME FORM. mcpp refuses
# EVERY MANIFEST THAT NAMES IT, AND BY THE SAME FORM. mcpp refuses
# a graph in which one package reaches a dependency by version and
# another by path, so substituting only the root leaves the build
# refusing for a second reason instead of the first.
# ⚠️ NOT `sed -i'. This step runs on macOS and on Windows too, and
# NOT `sed -i'. This step runs on macOS and on Windows too, and
# BSD sed requires an argument to -i that GNU sed refuses. A temporary
# file is the spelling that holds on all three.
subst() { # subst <file> <relative-path-to-the-specification>
Expand All @@ -212,7 +212,7 @@ jobs:
mcpp build
EXE=$(find target -name "hello.exe" | head -1)

# ⚠️ THE TOOLCHAIN THAT BUILT THE IMAGE, NOT LLVM.
# THE TOOLCHAIN THAT BUILT THE IMAGE, NOT LLVM.
#
# This target resolves to mingw-cross-gcc, so on a machine that has
# never built anything else there is no LLVM to borrow `llvm-readobj`
Expand All @@ -224,7 +224,7 @@ jobs:
OD=$(ls -d "$HOME"/.mcpp/registry/data/xpkgs/xim-x-mingw-cross-gcc/*/bin/x86_64-w64-mingw32-objdump | head -1)
test -x "$OD"

# ⚠️ Subsystem 10 is what makes firmware load it. A Windows console
# Subsystem 10 is what makes firmware load it. A Windows console
# subsystem would build, link, and never be executed by UEFI.
# Measured spelling from this objdump: `Subsystem 0000000a (EFI application)`.
"$OD" -p "$EXE" | grep -qE 'Subsystem[[:space:]]+0000000a'
Expand Down Expand Up @@ -259,7 +259,7 @@ jobs:
# A package that has only ever been built from Linux is a package whose
# consumers must use Linux, and nothing in these sources says so.
#
# ⚠️ A TOOLCHAIN AXIS IS ABSENT HERE, AND THAT IS MEASURED RATHER THAN
# A TOOLCHAIN AXIS IS ABSENT HERE, AND THAT IS MEASURED RATHER THAN
# ASSUMED. The row for a bare-metal triple names its compiler, and the
# command-line override does not displace it: `--toolchain gcc@16.1.0` on a
# `riscv64-none-elf` build resolves llvm@22.1.8 regardless. A matrix over
Expand All @@ -268,7 +268,7 @@ jobs:
# choice is real — openkal, whose declarations are compiled by three families
# on three systems.
#
# ⚠️ BUILD ONLY, AND DELIBERATELY. Behaviour is asserted once, above, under an
# BUILD ONLY, AND DELIBERATELY. Behaviour is asserted once, above, under an
# emulator. Booting the same image from three systems would be a statement
# about the emulator rather than about this package, and "the image does what
# the README says" does not become more true for having been observed from
Expand Down Expand Up @@ -312,7 +312,7 @@ jobs:

- name: Install mcpp
run: |
# ⚠️ A LOOP, BECAUSE ONE `xlings update` CAN RETURN A STALE INDEX
# A LOOP, BECAUSE ONE `xlings update` CAN RETURN A STALE INDEX
# WITHOUT SAYING SO.
#
# The index is published as an artifact behind a pointer, and that
Expand All @@ -333,7 +333,7 @@ jobs:
# of the two situations it is.
for attempt in 1 2 3 4 5 6; do
xlings update > /dev/null 2>&1 || true
if # ⚠️ THE PIN MAY NAME THE RELEASE THIS RUN IS VALIDATING, which does
if # THE PIN MAY NAME THE RELEASE THIS RUN IS VALIDATING, which does
# not exist yet — that is the whole point of MCPP_SOURCE_REF. Bootstrap
# from whatever the index has; the step below replaces it with the
# build under review, and the pin is what an ordinary run tests.
Expand All @@ -349,7 +349,7 @@ jobs:
echo "the index has not caught up yet (attempt $attempt of 6); waiting 60s"
sleep 60
done
# ⚠️⚠️ TRANSITION: GIVE THE BOOTSTRAP THE glibc ITS BINDING NAMES.
# TRANSITION: GIVE THE BOOTSTRAP THE glibc ITS BINDING NAMES.
#
# `xim:glibc`'s `latest` moved from `2.44` to `2.44.2`. A payload
# directory is named after the version a request RESOLVED to, while a
Expand All @@ -361,13 +361,13 @@ jobs:
# error: selected RuntimeBinding glibc@2.44 requires payload
# '…/xpkgs/xim-x-glibc/2.44', but it is not installed
#
# ⚠️ On every NEW machine and on none that already existed, which is why
# On every NEW machine and on none that already existed, which is why
# it is invisible from a developer's own. Measured on `main` as readily
# as on any branch — the index records the same failure verbatim in
# `pkgs/g/glibc.lua` and states the rule it broke: "The index is DATA
# and the client is a PROGRAM: the consumer ships first."
#
# REMOVE THIS once a released mcpp resolves it. `mcpp 2026.8.27.1`
# REMOVE THIS once a released mcpp resolves it. `mcpp 2026.8.27.1`
# accepts an installed payload whose version REFINES the requested one
# (`payload_dir_for_version`), so a bootstrap from it needs nothing
# here. Until then the missing payload is simply installed.
Expand All @@ -379,13 +379,13 @@ jobs:
fi
mcpp --version
mcpp self config --mirror GLOBAL
# ⭐⭐ CROSS-VALIDATION: BUILD THE mcpp UNDER REVIEW AND USE THAT ONE.
# CROSS-VALIDATION: BUILD THE mcpp UNDER REVIEW AND USE THAT ONE.
#
# Empty in the ordinary run, so this job keeps testing the RELEASED
# mcpp the pin above names. Set it — `workflow_dispatch` input, or the
# repository variable — and the same job runs against that source.
#
# ⚠️ THIS EXISTS BECAUSE THE ORDER USED TO BE WRONG. Several mcpp
# THIS EXISTS BECAUSE THE ORDER USED TO BE WRONG. Several mcpp
# releases went out green and only then turned this ecosystem red: the
# engine's own CI cannot see a defect that appears only in a real
# dependency graph, and this repository could not see the engine until
Expand All @@ -398,7 +398,7 @@ jobs:
[ -d "$src" ] || git clone --quiet --depth 1 \
--branch "$MCPP_SOURCE_REF" \
https://github.com/mcpp-community/mcpp.git "$src"
# ⚠️ THE CLONE'S OWN WORKSPACE PIN MUST NOT DECIDE WHICH mcpp
# THE CLONE'S OWN WORKSPACE PIN MUST NOT DECIDE WHICH mcpp
# BUILDS IT. `.xlings.json` at mcpp's root pins the mcpp that
# compiles mcpp, and that pin does not move when mcpp is released —
# so a build inside the checkout obeys it and tries to install a
Expand All @@ -411,7 +411,7 @@ jobs:
# above, which is exactly what removing the file leaves.
rm -f "$src/.xlings.json"
( cd "$src" && mcpp build --release )
# ⚠️ BOTH SPELLINGS, AND NO `-perm`. The matrix reaches Windows and
# BOTH SPELLINGS, AND NO `-perm`. The matrix reaches Windows and
# macOS runners too: on Windows the artefact is `mcpp.exe`, and
# `-perm -u+x` is not a question that filesystem answers the way this
# expects. Measured: `Finished release [optimized] in 173.44s`
Expand All @@ -425,13 +425,13 @@ jobs:
\( -name mcpp -o -name mcpp.exe \) | head -1)
[ -n "$built" ] || { echo "::error::mcpp did not build from $MCPP_SOURCE_REF"; exit 1; }
echo "$(cd "$(dirname "$built")" && pwd)" >> "$GITHUB_PATH"
# ⚠️ Reported, because a PATH entry that does not win looks exactly
# Reported, because a PATH entry that does not win looks exactly
# like one that does until something built with the wrong engine.
echo "under review: $("$built" --version) (from $MCPP_SOURCE_REF)"
fi


# ⚠️⚠️ A JOB THAT RESOLVES THE PUBLISHED SPECIFICATION CANNOT REVIEW A
# A JOB THAT RESOLVES THE PUBLISHED SPECIFICATION CANNOT REVIEW A
# CHANGE TO ONE.
#
# Another step in this file already clones the specification and
Expand All @@ -443,7 +443,7 @@ jobs:
# synced index ... the index is current, so this name is either
# wrong or not published yet
#
# ⭐⭐ THE UNIT IS THE JOB, NOT THE REPOSITORY. Measured 2026-08-28 across
# THE UNIT IS THE JOB, NOT THE REPOSITORY. Measured 2026-08-28 across
# the eight repositories of this ecosystem while one change spanned all of
# them: seven jobs in three repositories had this shape, and every one of
# those repositories ALSO had a job that substituted correctly --- which is
Expand All @@ -463,11 +463,11 @@ jobs:
else
echo "the specification has no $OPENKAL_BRANCH; its default branch is used"
fi
# ⚠️ EVERY MANIFEST THAT NAMES IT, AND BY THE SAME FORM. mcpp refuses
# EVERY MANIFEST THAT NAMES IT, AND BY THE SAME FORM. mcpp refuses
# a graph in which one package reaches a dependency by version and
# another by path, so substituting only the root leaves the build
# refusing for a second reason instead of the first.
# ⚠️ NOT `sed -i'. This step runs on macOS and on Windows too, and
# NOT `sed -i'. This step runs on macOS and on Windows too, and
# BSD sed requires an argument to -i that GNU sed refuses. A temporary
# file is the spelling that holds on all three.
subst() { # subst <file> <relative-path-to-the-specification>
Expand All @@ -479,7 +479,7 @@ jobs:
subst mcpp.toml .spec
- name: The EFI application cross-builds
run: |
# ⚠️ TWICE, AND THE FIRST IS ALLOWED TO FAIL — every row of this
# TWICE, AND THE FIRST IS ALLOWED TO FAIL — every row of this
# matrix is a machine that has never targeted this triple, which is
# precisely where mcpp's lazy install of the target C library shows.
# The first build compiles sources needing its headers before they
Expand Down
10 changes: 5 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,11 @@ target = "x86_64-windows-gnu"
ldflags = ["-nostdlib", "-Wl,--subsystem,10", "-Wl,-e,efi_main"]

[dependencies]
openkal = "0.9.0"
openkal-uefi = "0.3.0"
openkal = "0.13.0"
openkal-uefi = "0.7.0"
```

## ⚠️ The target is `x86_64-windows-gnu`, and that is not a workaround
## The target is `x86_64-windows-gnu`, and that is not a workaround

A UEFI application is PE/COFF with subsystem 10, entered through the Microsoft
x64 calling convention. Both are properties this toolchain already has, so
Expand All @@ -38,7 +38,7 @@ way. This backend is mostly forwarding:
| `memory` | `AllocatePool` / `FreePool` |
| `abort` | `Exit` |

⚠️ `process` and `task` are absent because UEFI has no process model. An
`process` and `task` are absent because UEFI has no process model. An
application is the only thing running, and an interface provided in part would
be worse than one provided not at all — `import openkal.process;` does not
resolve, which is the honest answer rather than a set of calls that always fail.
Expand Down Expand Up @@ -66,7 +66,7 @@ bytes. A stricter request is satisfied by over-allocating and storing the
original pointer immediately before the aligned address, which is what a C
library does where the platform lacks `aligned_alloc`.

**Input.** ⚠️ `kal_stream_read` reports end of input rather than pretending.
**Input.** `kal_stream_read` reports end of input rather than pretending.
UEFI's console input is a key-stroke protocol with a wait event, not a byte
stream; presenting it as one would give a reader something that appears to work
and silently loses every key that is not a plain character.
Expand Down
4 changes: 2 additions & 2 deletions examples/hello/mcpp.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,14 @@ version = "0.1.0"

[build]
target = "x86_64-windows-gnu"
# ⚠️ The three that make this an application firmware will load, rather than a
# The three that make this an application firmware will load, rather than a
# Windows one. `-nostdlib` removes the C runtime and the default import
# libraries; `--subsystem,10` is EFI_APPLICATION; the entry point is the one
# UEFI calls, not `mainCRTStartup`.
ldflags = ["-nostdlib", "-Wl,--subsystem,10", "-Wl,-e,efi_main"]

[dependencies]
# ⚠️ THE FORM MUST MATCH THE ONE THE IMPLEMENTATION USES, not merely the
# THE FORM MUST MATCH THE ONE THE IMPLEMENTATION USES, not merely the
# version. mcpp refuses a graph in which one package reaches a dependency by
# version and another by git:
#
Expand Down
2 changes: 1 addition & 1 deletion examples/hello/src/main.cpp
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
// A UEFI application written against openkal, with no UEFI type in sight.
//
// ⚠️ `kal_main` and not `main`: nothing here supplies a C runtime, and the
// `kal_main` and not `main`: nothing here supplies a C runtime, and the
// backend's `efi_main` is what firmware calls. That indirection is the point —
// the same source compiles against any openkal implementation.
import openkal.stream;
Expand Down
6 changes: 3 additions & 3 deletions mcpp.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# openkal on UEFI Boot Services.
#
# ⚠️ THE TARGET IS `x86_64-windows-gnu`, AND THAT IS NOT A WORKAROUND.
# THE TARGET IS `x86_64-windows-gnu`, AND THAT IS NOT A WORKAROUND.
#
# A UEFI application is PE/COFF with subsystem 10, entered through the Microsoft
# x64 calling convention. Both are properties this toolchain already has, so
Expand All @@ -15,7 +15,7 @@
[package]
namespace = "mcpplibs"
name = "openkal-uefi"
version = "0.6.0"
version = "0.7.0"
description = "An implementation of openkal on UEFI Boot Services, for applications the firmware loads before an operating system exists"
license = "Apache-2.0"

Expand All @@ -32,7 +32,7 @@ authors = ["mcpplibs"]
repo = "https://github.com/mcpplibs/openkal-uefi"

[dependencies]
openkal = "0.12.0"
openkal = "0.13.0"

[build]
flags = [
Expand Down
Loading
Loading