mcpp.toml

[package]
namespace   = "mcpplibs"
name        = "openkal-emscripten"
version     = "0.1.1"
description = "An implementation of openkal for Emscripten, written ABOVE a C library rather than beneath one, because on this platform there is no kernel to issue calls to."
license     = "Apache-2.0"

# The layer this package supplies, in the vocabulary the engine resolves.
#
# `mcpp:kernel-abi` names the platform interface a C library sits on. Here that
# reading is inverted and the declaration is still correct: this package answers
# to `openkal` for programs that use openkal, and what it is written on happens
# to be a C library. Clause 2 permits it in as many words --- "an implementation
# may be built upon a C library, beneath one, or without one" --- and this is
# the first implementation in the ecosystem to take the first of the three.
provides    = ["mcpp:kernel-abi=openkal"]
authors     = ["mcpplibs"]
repo        = "https://github.com/mcpplibs/openkal-emscripten"

[dependencies]
openkal = "0.12.0"

[build]
# THE DIALECT FLAGS ARE THE SAME AS EVERY OTHER IMPLEMENTATION'S AND THE REASON
# IS NOT. Elsewhere they exist because no C library is available to unwind
# through; here one is. They stay because a C entry point must not let an
# exception escape either way, and because a module interface records the
# dialect it was compiled under: a translation unit compiled without exceptions
# cannot import one compiled with them, and the conformance tests import the
# specification's modules as consumers rather than as parts of this package.
#
# The stack protector is off for the ordinary reason a forwarding layer turns it
# off: it buys nothing over a call that immediately enters libc, and it costs a
# thread-local read on every function in the surface.
flags = [
  { glob = "src/**", cxxflags = ["-fno-exceptions", "-fno-rtti",
                                 "-fno-stack-protector"] },
]

# THE SOURCE SET IS ALL OF `src/`, AND THE FEATURE SUBTRACTS FROM IT.
#
# `[features].<name>.sources` is not an addition to the source set -- a glob
# listed there is EXCLUDED from the default build and compiled only when the
# feature is active. So `src/threads/task.cpp` has to be matched here for the
# feature to be able to gate it; restricting this list to `src/*.cpp` removed
# it from both, and the task interface then existed in neither link. Measured:
# `task.o` appeared in no build directory, with and without the feature.
sources = ["src/**/*.cpp"]

[features]
default = []

# THREADS ARE A LINK-TIME DECISION ON THIS PLATFORM, WHICH NO OTHER
# IMPLEMENTATION HAS TO SAY.
#
# Emscripten compiles `pthread_create` either way; whether it can create
# anything depends on `-pthread`, which selects a different C library build and
# a different loader contract (SharedArrayBuffer, a worker pool). So the
# capability is not a property of the machine this runs on, and it is not
# discoverable at run time by anything this package can ask.
#
# THE SWITCH IS THE ARTEFACT'S, SO THE ROOT MANIFEST STATES IT. `-pthread`
# changes the module configuration of every translation unit in the link, the
# specification package's included, so it cannot be a flag of this package's
# own units. mcpp 2026.9.12.2 carries it as a typed member of the root's target
# table,
#
#   [target.'cfg(os = "emscripten")'.abi]
#   threads = true
#
# which reaches the standard library module, every translation unit and the
# link. This feature states that it needs the switch: a build that activates it
# without the table is refused before anything compiles, naming the feature and
# the table.
#
# `kal_task_props` reports the consequence: with the switch the word carries
# KAL_TASK_PROP_PARALLEL, and without it `kal_task_start` reports
# kal_err_not_supported -- clause 6.2's third time, a capability word read
# before use. The code keys on `__EMSCRIPTEN_PTHREADS__`, which the compiler
# defines when `-pthread` is passed: one mechanism, and it is the compiler's own
# answer to "was this compiled with threads".
threads = { requires_abi = { threads = true } }