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.24.2"
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"
mcpp        = ">=2026.11.3.1"

[platform]
targets   = ["x86_64-openkal", "aarch64-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`).
runner    = { cmd = ["okrun", "{}"], host = "same-arch", hosts = ["linux-x86_64", "linux-aarch64", "macos-aarch64", "windows-x86_64"] }
# `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.5.1", 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.19.2"
"c++-abi"        = "openkal-llvm-runtime@0.19.2"
c-abi            = { name = "openkal-musl", version = "0.28.1", 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.5.1"
okrun  = "openkal-tools@0.5.1"
okprof = "openkal-tools@0.5.1"

# 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"]

# 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.
# 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", "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.
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"]
toolchain = "llvm@23.1.3"

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

# 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):
# 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.24.0"
openkal-linux        = "0.25.0"
openkal-macos        = "0.22.1"
openkal-windows      = "0.20.0"
openkal-musl         = "0.28.1"
openkal-llvm-runtime = "0.19.2"
openkal-ld           = "0.5.1"
openkal-run          = "0.5.1"
openkal-tools        = "0.5.1"

# 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.5.1", tools = ["okld"] }

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