mcpp.toml

# mcpplibs/openkal-platform -- the platform of the ok-image targets
# (`<arch>-openkal`; mcpp SPEC-013, openkal SPEC clause 12).
#
# A data package: everything the openkal ecosystem agrees on for an ok image --
# how one is compiled and linked, the notes it carries and the check that
# accepts it, its names, the loader that runs it, the program that carries it
# (M3) -- and the versions of the family that are built and tested together.
# mcpp pins one version of it for the two targets, which is what "built-in
# support" for them is; a project may select another with
# `[target.<selector>] platform = "openkal-platform@<version>"`. The one program
# here is the plugin (`build.mcpp`), which provides the `okb` package format.
[package]
namespace   = "mcpplibs"
name        = "openkal-platform"
version     = "0.28.1"
description = "The platform of ok images (<arch>-openkal): their toolchain, C library and C++ run-time, tools, compile and link conventions, seal, runner and carrier, as one versioned statement mcpp reads."
license     = "Apache-2.0"
authors     = ["mcpplibs"]
repo        = "https://github.com/mcpplibs/openkal-platform"
# 2026.11.10.1: openkal-run (from 0.6.0) binds the interfaces its
# implementation provides (MCPP_KERNEL_ABI_INTERFACES), and FreeBSD's rows are
# built-in. 2026.11.9.1: openkal-run (from 0.5.4) states its openkal implementation as a
# capability with a default per system (`[defaults]`).
# 2026.11.13.1: the UEFI row (the PE rows' C environment by the container, a
# provider's link and runner over `base = "none"', a row's link emulation
# without its machine). 2026.11.14.1: a planned row is served by the platform
# chosen for it when the platform lists the row with a toolchain, so the i686
# rows below need no toolchain named by the project.
mcpp        = ">=2026.11.14.1"

[platform]
# `i686-openkal` (0.28.0): the image of the thirty-two bit class, i386 (openkal
# 0.25.1, clauses 5.5 and 12.2; openkal-image 0.6.3 reads, checks and loads it).
# mcpp registers the row `planned'; this list, with `toolchain', serves it
# (mcpp 2026.11.14.1), and `--target openkal' builds every leg.
targets   = ["x86_64-openkal", "aarch64-openkal", "i686-openkal"]
toolchain = "llvm@23.1.3"
# The loader runs an image of its own architecture on Linux, macOS and Windows;
# `hosts` are the systems and architectures openkal-tools builds it for, which is
# where a package that needs it can run (mcpp's `runs_on`). FreeBSD (0.26.0):
# okrun over openkal-freebsd, beneath openkal-musl or beside the system's libc.
# `built-as` (0.27.0; mcpp 2026.11.12.1 reads it, an earlier mcpp names the key
# and ignores it): the identity the runner's program for a host pair is built
# as, where the engine holds no convention for the system. A package that
# carries its runner (`mcpp pack --mode self-contained --systems all`) builds
# FreeBSD's as the musl identity this platform's hosted arrangement serves: one
# static program, the same whichever machine packs it. `uefi-x86_64` (0.28.0):
# the runner is a UEFI application of the row this platform defines below (the
# core runner, which carries what it runs), so an ok image packs for firmware.
# `dos-i686` (0.28.0; technical experiment only): the core runner as a program
# of the DOS row below, so an i386 image packs for DOS (mcpp 2026.11.13.1 builds
# a system's runner as the row the platform defines for it).
runner    = { cmd = ["okrun", "{}"], host = "same-arch", hosts = ["linux-x86_64", "linux-aarch64", "macos-aarch64", "windows-x86_64", "freebsd-x86_64", "freebsd-aarch64", "uefi-x86_64", "dos-i686"], built-as = { "freebsd-x86_64" = "x86_64-freebsd-musl", "freebsd-aarch64" = "aarch64-freebsd-musl" } }
# `mcpp pack --mode self-contained`: a program of the packing machine that
# carries the image in a section and runs it through libokrun (M3).
carrier   = { package = "openkal-run@0.6.4", section = ".oke", main = "carrier/main.cpp" }
# The `okb` package format (`mcpp pack --pkg-format okb`): the images of every
# architecture as one file okrun runs (openkal-image docs/okb.md).
plugin    = "build.mcpp"

# A program launched under a host debugger, distinct from a board debug server.
[platform.runners]
debuggee = ["okrun", "--debugger", "{}"]

# The C library and the C++ run-time inside an image. A package of the graph
# that provides a layer takes its place (`provides`), and `false` leaves it out.
[platform.layers]
compiler-runtime = "openkal-llvm-runtime@0.20.3"
"c++-abi"        = "openkal-llvm-runtime@0.20.3"
c-abi            = { name = "openkal-musl", version = "0.29.7", default-features = false, features = ["posix", "malloc-mimalloc"] }

# Built for the building machine: `okld` writes and checks the notes, `okrun`
# runs an image, `okprof` reads what a measured run recorded (0.23.0: the
# order of a start's first executions, which a producer lays its code out by
# and writes as the touch note).
[platform.tools]
okld   = "openkal-tools@0.6.4"
okrun  = "openkal-tools@0.6.4"
okprof = "openkal-tools@0.6.4"
# The seal of the DOS row (0.28.0): the stub of openkal-dos before an executable.
okdos  = "openkal-dos-tools@0.1.0"

# Every unit of an image (SPEC 12.2):
#   -fPIC              the image is ET_DYN and has no text relocation;
#   -femulated-tls     a variable is found through `__emutls_get_address`, which
#                      the image supplies: one system does not let a program set
#                      the thread pointer, another does not let it change it;
#   -fvisibility=hidden
#                      an image exports what its source marks
#                      `visibility("default")`, so the link can drop what
#                      nothing reaches and the requirements note names only the
#                      interfaces the program uses;
#   -fasynchronous-unwind-tables
#                      every frame, C's included, can be unwound: a C++
#                      exception crosses the unwinder's own C and the C library's;
#   -Xclang -fstack-clash-protection
#                      a frame larger than a page is probed page by page, as one
#                      system commits a thread's stack as its guard is touched;
#   -ffunction-sections -fdata-sections
#                      each function and object in a section of its own, so the
#                      link's `--gc-sections` discards what nothing reaches at
#                      that grain, not at a translation unit's.
#
# AND, FROM 0.23.0, WHAT A PROGRAM IS OBSERVED AND HELD BY (mcpp design
# 2026-11-03, part 4):
#   -fno-omit-frame-pointer -mno-omit-leaf-frame-pointer
#                      every frame is a link of the chain the implementation's
#                      sampler and fault report walk (openkal 0.23, entry 56);
#   -fstack-protector-strong -mstack-protector-guard=global
#                      a frame with an array or an address taken is guarded,
#                      the guard a variable the C library sets from the
#                      environment's randomness, not a thread pointer's slot,
#                      which an image has none of;
#   -ftrivial-auto-var-init=zero
#                      a local variable read before it is written reads zero;
#   -D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE_FAST
#                      the C++ library's cheap checks: an index out of bounds
#                      ends the program rather than reading beyond.
[platform.build]
cflags   = ["-fPIC", "-femulated-tls", "-fvisibility=hidden", "-fasynchronous-unwind-tables", "-Xclang", "-fstack-clash-protection", "-ffunction-sections", "-fdata-sections",
            "-fno-omit-frame-pointer", "-mno-omit-leaf-frame-pointer", "-fstack-protector-strong", "-mstack-protector-guard=global", "-ftrivial-auto-var-init=zero"]
cxxflags = ["-fPIC", "-femulated-tls", "-fvisibility=hidden", "-fasynchronous-unwind-tables", "-Xclang", "-fstack-clash-protection", "-ffunction-sections", "-fdata-sections",
            "-fno-omit-frame-pointer", "-mno-omit-leaf-frame-pointer", "-fstack-protector-strong", "-mstack-protector-guard=global", "-ftrivial-auto-var-init=zero",
            "-D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE_FAST"]
asmflags = ["-fPIC", "-femulated-tls", "-fvisibility=hidden", "-fasynchronous-unwind-tables", "-Xclang", "-fstack-clash-protection"]

# x86-64: an indirect branch lands on `endbr64` and a return is checked against
# a shadow stack, where the system enforces either (-fcf-protection=full); the
# instructions are no-ops where it does not.
[platform.build.'cfg(arch = "x86_64")']
cflags   = ["-fcf-protection=full"]
cxxflags = ["-fcf-protection=full"]
asmflags = ["-fcf-protection=full"]

# AArch64: two systems reserve the platform register, and the outlined atomic
# helpers read the processor's features through an operating system's interface.
# A return address is signed and an indirect branch lands on a mark
# (-mbranch-protection=pac-ret+bti), which a processor without them executes as
# no-ops; the loader asks for the marks to be enforced where every object of the
# image carries them (openkal 0.23, KAL_EXEC_MAP_BTI). Not `standard': clang 23
# counts the guarded control stack in it (__ARM_FEATURE_GCS_DEFAULT), whose
# unwinder needs <arm_acle.h> of a C library and a system that enables the
# stack for a program, neither of which an image has --- libunwind's build
# failed on it (CI, aarch64).
[platform.build.'cfg(arch = "aarch64")']
cflags   = ["-ffixed-x18", "-mno-outline-atomics", "-mbranch-protection=pac-ret+bti"]
cxxflags = ["-ffixed-x18", "-mno-outline-atomics", "-mbranch-protection=pac-ret+bti"]
asmflags = ["-ffixed-x18", "-mno-outline-atomics", "-mbranch-protection=pac-ret+bti"]

# i386 (0.28.0): the 486's instructions (-march=i486) are the least machine an
# i386 image runs on: DOSBox Staging 0.83, which runs the DOS row and its
# carrier, executes RDTSC and not CMPXCHG8B under every `cputype' (measured), so
# a sixty-four bit atomic is compiler-rt's call (atomic.c) rather than the
# Pentium's instruction. An image is then the same bytes on Linux, on Windows and
# beneath DOS's carrier. The floating point is the x87's, the convention's own
# (SPEC 12.2).
# The stack is aligned to sixteen bytes at a call (SPEC 12.2): the image's triple
# names no system, for which clang keeps four, and a loader's code built for its
# system relies on sixteen (measured: `movaps' of okrun's kal_time_monotonic,
# entered from an image built at four, faults).
[platform.build.'cfg(arch = "i686")']
cflags   = ["-march=i486", "-mstack-alignment=16"]
cxxflags = ["-march=i486", "-mstack-alignment=16"]
asmflags = ["-march=i486"]

# The link, by `ld.lld` itself: position-independent, every loadable segment
# aligned to 64 KiB (the largest protection granularity among the systems),
# bound now, no executable stack, both hash tables, what nothing reaches
# discarded, identical functions whose address nothing takes folded into one,
# and the unwind index an unwinder finds through `dl_iterate_phdr`; the relative
# relocations packed (`-z pack-relative-relocs`, SPEC 12.2's packed relative
# form): a loader reads clangd's 164 000 of them from 32 KiB rather than 3.9 MB
# on every start, and the image is 4 MB smaller. `-z rela`: i386's default is
# REL, whose addend is the word the relocation writes; an image states its
# addends (RELA) on every architecture, so a loader and a placement read one
# form (SPEC 12.2; the option is the default's form on the sixty-four bit ones).
# An executable image is entered at `ok_main`, which its C library defines; its
# notes come from `okld note-source`; `okld note` writes its requirements,
# `okld place` its writable segments computed for the base it chooses from the
# image's bytes (openkal 0.23: a loader given that base applies only the
# relocations that name a symbol, and the image's read-only-after-relocation
# data are its file's pages), and `okld check` accepts it, against the images it
# needs, before it is published. An image is named by its build-id
# (`--build-id=sha1`, 0.23.0), by which a debugger finds what `okld debug-split`
# keeps apart from it.
[platform.link]
driver = "lld"
start  = "ok_main"
flags  = ["-shared", "-z", "max-page-size=65536", "-z", "pack-relative-relocs", "-z", "rela", "-z", "now", "-z", "noexecstack",
          "--hash-style=both", "--gc-sections", "--icf=safe", "--eh-frame-hdr", "--build-id=sha1", "--emit-relocs",
          "-mllvm", "-emulated-tls"]
inputs = [{ from = ["okld", "note-source"], as = "ok-notes.S" }]
exe    = "{name}.oke"
shared = "lib{name}.okso"
# The declarative seal is also available while preparing the platform's
# build program. Its program statement replaces this sequence with the selected
# toolchain's objcopy followed by the same note/place/check operations.
seal   = [["okld", "note", "{}"], ["okld", "place", "{}"], ["okld", "check", "{}", "--with", "{needed}"]]

# A host triple selecting this platform (`x86_64-linux-gnu`, `aarch64-macos`,
# `x86_64-windows-gnu`) takes the same C library and C++ run-time over the
# system's openkal implementation, compiled by the same toolchain.
[platform.hosted]
# On Windows the arrangement is the GNU ABI's (or musl's) row: a C library of the
# graph and libc++ above it are not the MSVC runtime's.
# On FreeBSD (0.26.0) the C library's implementation is openkal-freebsd in its
# standalone arrangement, which openkal-musl names for that system: the rows
# `<arch>-freebsd-musl` are the system with no C library of its own beneath.
# `i686-linux-musl` (0.28.0) is the thirty-two bit row of Linux (openkal 0.25.1,
# clause 5.5): openkal-linux's i386 system-call layer beneath openkal-musl's.
targets   = ["x86_64-linux-gnu", "aarch64-linux-gnu", "x86_64-linux-musl", "aarch64-linux-musl",
             "x86_64-macos", "aarch64-macos", "x86_64-windows-gnu", "x86_64-windows-musl",
             "x86_64-freebsd-musl", "aarch64-freebsd-musl", "i686-linux-musl"]
toolchain = "llvm@23.1.3"

[platform.hosted.layers]
compiler-runtime = "openkal-llvm-runtime@0.20.3"
"c++-abi"        = "openkal-llvm-runtime@0.20.3"
c-abi            = { name = "openkal-musl", version = "0.29.7", default-features = false, features = ["posix", "malloc-mimalloc"] }

# UEFI (0.28.0): applications the firmware loads, on the same C library and C++
# run-time over openkal-uefi (openkal-musl names it, `standalone', on
# `cfg(os = "uefi")'). The row is PE: the C environment is the PE rows'
# (mcpp 2026.11.13.1 realises it by the container, as on Windows), linked by
# ld.lld's MinGW driver (`link-emulation = "i386pep"') as an EFI application.
# The provider states the row's own conventions (`base = "none"': none of the
# ok images' compile, link or seal), its layers and its runner: dirun boots the
# application with xim's OVMF and its profile, and the board's exit
# (board/qemu-exit.S, QEMU's debug-exit port) returns the status; the same file
# makes standard error the console (OVMF's StdErr reaches no serial reader). The
# machine has 2 GiB: memory is backed when the allocator reserves it, and the
# allocator of a carrier and of the image it carries each place an arena at a
# 256 MiB alignment (512 MiB, dirun's default, held one). A program that
# wants no C library states `c-abi = false' for the row and is linked over
# openkal-uefi alone.
[[platform.define]]
triple         = "x86_64-uefi"
clang-triple   = "x86_64-unknown-uefi"
object-format  = "pe"
execution      = "uefi"
exe-suffix     = ".efi"
link-emulation = "i386pep"

[[platform.provider]]
name   = "uefi"
serves = ["x86_64-uefi"]
base   = "none"
hosted = true

layers = { compiler-runtime = "openkal-llvm-runtime@0.20.3", "c++-abi" = "openkal-llvm-runtime@0.20.3", c-abi = { name = "openkal-musl", version = "0.29.7", default-features = false, features = ["posix", "malloc-mimalloc"] } }
link   = { driver = "lld", start = "efi_main", flags = ["--subsystem", "efi_application", "--gc-sections"], exe = "{name}.efi", inputs = [{ file = "board/qemu-exit.S" }], seal = [] }
runner = { cmd = ["dirun", "--payload", "{}", "--profile", "{pkg:ovmf}/dirun.toml", "--emulator", "{pkg:qemu-x86}/bin/qemu-system-x86_64", "--memory", "2048"], hosts = ["linux-x86_64", "linux-aarch64", "macos-aarch64", "windows-x86_64"], requires = ["xim:dirun@0.3.2", "xim:qemu-x86@9.2.4-1", "xim:ovmf@9.2.4-1"] }

# DOS (0.28.0; TECHNICAL EXPERIMENT ONLY, openkal-dos's README): programs a DPMI
# host runs, on the same C library and C++ run-time over openkal-dos
# (openkal-musl names it, `standalone', on `cfg(os = "dos")'). A program is the
# stub of openkal-dos followed by an ELF32 i386 executable linked at its address;
# `okdos seal' writes the stub. The row's flags are its conventions: there is no
# thread register the toolchain can address, so thread-local storage is emulated
# (openkal-llvm-runtime builds compiler-rt's `emutls.c' for the row), and a triple
# with no system has no unwind tables by default, which the unwinder's own frames
# need. The stack is aligned to sixteen bytes at a call, the System V i386
# convention that openkal states for an i386 image (SPEC 12.2) and that a triple
# with no system leaves at four: the row's code calls images and is called by
# them. The processor is the 486, as for the i386 ok image (DOSBox Staging 0.83
# executes no CMPXCHG8B, measured). The runner is dirun with DOSBox Staging and CWSDPMI beside the program
# (xim's `dosbox-staging'). The memory allocator is musl's own (`malloc-mallocng'):
# it asks openkal.memory for blocks and nothing else.
[[platform.define]]
triple        = "i686-dos-musl"
clang-triple  = "i386-unknown-none-elf"
object-format = "elf"
data-model    = "ilp32"
exe-suffix    = ".exe"
execution     = "dos"
tier          = "preview"
march         = "i486"
flags         = ["-femulated-tls", "-fasynchronous-unwind-tables", "-mstack-alignment=16", "-ffunction-sections", "-fdata-sections"]

[[platform.provider]]
name   = "dos"
serves = ["i686-dos-musl"]
base   = "none"
hosted = true

layers = { compiler-runtime = "openkal-llvm-runtime@0.20.3", "c++-abi" = "openkal-llvm-runtime@0.20.3", c-abi = { name = "openkal-musl", version = "0.29.7", default-features = false, features = ["posix", "malloc-mallocng"] } }
link   = { driver = "lld", start = "okdos_entry", flags = ["-static", "--image-base=0x1000", "-z", "norelro", "--gc-sections", "--eh-frame-hdr"], seal = [["okdos", "seal", "{}"]] }
runner = { cmd = ["dirun", "--payload", "{}", "--profile", "{pkg:dosbox-staging}/dirun.toml", "--"], hosts = ["linux-x86_64", "macos-aarch64", "windows-x86_64"], requires = ["xim:dirun@0.3.2", "xim:dosbox-staging@0.83.0"] }

# The family released together for openkal 0.17 (the 0.17.2 round: okb, the
# runner's bundle and library interfaces, musl's renameat2; the 0.17.3 round:
# musl takes a program's arguments when it is entered; the 0.18.0 round: a
# directory handle names and does not read, musl leaves C++ its `restrict';
# openkal 0.18: openkal.map, musl's mmap of a file, okrun maps what it runs;
# 0.19.1: okrun releases the file it ran once the image is loaded, and digests
# on the processor's SHA-256 instructions; 0.19.2: on Linux aarch64 too, where
# the processor states them; openkal 0.19 (0.20.0): the physical cores and a
# context's claim on the processors, getpid as the environment's identifier,
# flock, and okb chunk digests verified in parallel; 0.20.1: openkal-macos
# 0.17.1, a context's identity without a system call; 0.20.2: openkal-musl
# 0.25.0, threads allocate together and memcmp/strlen a word at a time;
# openkal 0.21 (0.21.0): transfers at an offset, a program's and a unit's
# memory and a limit on it, openkal.region, openkal.prof and openkal.debug,
# instructions from a file; openkal-musl 0.26.0 with mimalloc embedded, memory
# over openkal.region and its string functions in vectors; okrun's measurement
# of an image (okprof), an okb's admission remembered, and an image's
# instructions and read-only data mapped from its file; a program started
# without copying its starter on Linux; 0.21.1: openkal-image 0.3.1, an okb
# member whose admission was remembered is admitted without reading it, with
# openkal-musl 0.26.1 and openkal-llvm-runtime 0.17.1, which pin its loader;
# 0.23.0, openkal 0.23: the system's null device at a started program's
# position, which openkal-musl 0.27.0 maps `/dev/null` onto (openkal 0.22); an
# image placed at its base, and realpath answered by the environment; the
# relative relocations of an image packed; 0.24.1: openkal-musl 0.28.1 keeps a
# directory's whole name, openkal-llvm-runtime 0.19.1 reads a name beneath a
# Windows volume as absolute, openkal-macos 0.22.1 sizes its confinement rules
# to the grants, and openkal-image 0.5.1 starts programs over it; 0.24.2:
# openkal-llvm-runtime 0.19.2 keeps the volume of a name it normalizes or
# appends a rooted name to, the first group released as a leaf and a patch of
# this group through one index change; 0.24.3: openkal-image 0.5.2 reserves a
# thread's stack for an image's main thread on Windows; 0.24.4: openkal-image
# 0.5.3 enters an image in its convention's floating-point state; 0.24.5:
# openkal-image 0.5.4, whose runner's openkal implementation is a capability
# with a default per system, and which mcpp 2026.11.9.1 resolves; 0.25.0, openkal
# 0.25: a second name for a file and the requests to end counted, with
# openkal-linux 0.26.0, openkal-macos 0.23.0, openkal-windows 0.21.0,
# openkal-musl 0.29.0 (a program found by the system's own search rules, link
# over kal_fs_hard_link), openkal-llvm-runtime 0.20.0 and openkal-image 0.5.5;
# 0.26.0, openkal-image 0.6.1 (the runner binds the interfaces its
# implementation provides), openkal-freebsd 0.1.0 beneath openkal-musl 0.29.2 and
# openkal-llvm-runtime 0.20.1 on FreeBSD; 0.27.1, the implementations retire a
# handle before closing it (openkal-linux 0.26.1, openkal-macos 0.23.1,
# openkal-windows 0.21.1) and openkal-musl 0.29.4 delivers what a readiness
# enquiry held with the rest; 0.28.0, openkal 0.25.3 (its suite keeps the surface
# under a discarding link and is an mtest project of its own) and i386: openkal-linux
# 0.26.3, openkal-musl 0.29.5 and openkal-llvm-runtime 0.20.2 for `i686-linux-musl`,
# and the implementations by the specification's minor version (openkal-macos
# 0.23.3, which supplies its libSystem stub only to a link without an SDK, openkal-windows 0.21.2, openkal-freebsd 0.1.2, openkal-image 0.6.2), and
# UEFI: openkal-uefi 0.10.0 beneath openkal-musl 0.29.6 and openkal-llvm-runtime
# 0.20.3, which take the optional interfaces from the implementation (or, in an
# image, at run time) and serve the PE rows by their container, and openkal-image
# 0.6.3, whose runner has a core for an implementation without files, processes
# or threads); 0.28.1, openkal-image 0.6.4 (the runner folds the path it is
# given, `//', `.' and `..', before it looks for the image), openkal-macos 0.23.4
# (`___bzero' in the stub of a link without an SDK, x86_64) and openkal-musl
# 0.29.7 (`uname' names the system a hosted program runs on): one version of
# each in a build. From 0.24.1 the members name one another by
# compatible ranges (`^0.28.0`) and this group chooses the versions: mcpp
# 2026.11.7.1 resolves within it, and a fix of one member is that member's
# release and a patch of this group, released together through one index change
# (tools/family_release.py, .github/workflows/family-release.yml).
[platform.versions]
openkal              = "0.25.3"
openkal-linux        = "0.26.3"
openkal-macos        = "0.23.4"
openkal-windows      = "0.21.2"
openkal-freebsd      = "0.1.2"
openkal-uefi         = "0.10.0"
openkal-dos          = "0.1.0"
openkal-dos-tools    = "0.1.0"
openkal-musl         = "0.29.7"
openkal-llvm-runtime = "0.20.3"
openkal-ld           = "0.6.4"
openkal-run          = "0.6.4"
openkal-tools        = "0.6.4"

# The plugin's tool, `okld bundle`, which writes the okb, and its library, the
# provider of a package format (mcpp.plugins.platform).
[build-dependencies]
openkal-tools = { version = "0.6.4", tools = ["okld"] }

[build-dependencies.mcpp]
plugins = { version = "0.20.0", features = ["plugins-platform"], host-module = true }