mcpp.toml

# The program declares the contract and names no implementation. Whoever builds
# it names one: an ordinary consumer writes the line below, and an
# implementation's continuous integration substitutes a path to itself.
#
# That the implementation is named here rather than in the source is the
# arrangement this example exists to demonstrate.
[package]
name    = "portable"
version = "0.1.0"

[dependencies]
openkal = "0.12.0"

# AND THE VERSIONS HAVE TO FOLLOW THE SOURCE, which is the reason this example
# is a criterion rather than an assumption.
#
# `src/main.cpp` was updated for 0.11's `kal_spawn` --- one struct where there
# had been three declarations --- and these four pins were not. So the example
# built nothing on any target:
#
#   src/main.cpp:256:19: error: 'kal_spawn' does not name a type
#
# A version pin in an example is a claim about what that example builds
# against, and nothing checked it: the example is not in any package's build,
# so no repository's continuous integration compiled it. The platform legs
# below exist so that it cannot go stale silently again.
[target.'cfg(os = "linux")'.dependencies]
openkal-linux = "0.12.0"

[target.'cfg(os = "macos")'.dependencies]
openkal-macos = "0.9.0"

[target.'cfg(windows)'.dependencies]
openkal-windows = "0.7.0"

# ANDROID IS NOT A LINE HERE, AND THAT IS THE POINT.
#
# `aarch64-linux-android` and `x86_64-linux-android` have `os = "linux"`,
# because the kernel IS Linux: bionic is a C library above it, and an
# implementation written on the kernel's own system-call interface does not
# know which C library sits above it. So `cfg(os = "linux")` above already
# selects `openkal-linux` for both Android rows, and adding an Android line
# would be adding a second name for one answer.
#
# Verified against the released engine rather than assumed: both ABIs build
# over `openkal-linux` and their objects name no C library symbol, and a
# program over openkal alone ran on an emulator.

# iOS REUSES THE macOS IMPLEMENTATION, AND THAT NEEDED A LINE BECAUSE THE OS
# SEGMENT DIFFERS.
#
# Darwin is Darwin: the same Mach traps, the same BSD call numbers, the same
# calling convention. What differs between macOS and iOS is the SDK and the
# deployment-target flag, which are the build tool's business and not the
# implementation's -- so this is one `cfg` line and no new package.
#
# All three iOS rows match: the device and both simulator arches carry
# `os = "ios"`.
[target.'cfg(os = "ios")'.dependencies]
openkal-macos = "0.9.0"

# THE WEB IS THE ONE PLATFORM THAT NEEDED NEW SOFTWARE.
#
# Emscripten has no kernel to issue a call to, so an implementation cannot be
# written the way the other four are -- beneath a C library -- and must sit
# ABOVE one, which clause 2 permits. `openkal-emscripten` is that
# implementation.
#
# IT PROVIDES TWELVE OF THE FIFTEEN INTERFACES, AND THIS PROGRAM DOES NOT FIT
# ON IT. There is no fork, no exec and no second address space on this
# platform, so `openkal.process`, `openkal.exec` and `openkal.space` are
# absent -- and this program uses `openkal.process` and `openkal.task`.
#
# The line stays, because what it demonstrates is the BOUNDARY. Measured:
#
#   wasm-ld: error: obj/main.o: undefined symbol: kal_process_spawn
#   ... and six more, one per name the program used and the platform lacks
#
# The dependency resolved and the compile succeeded; the report arrived at the
# earliest moment the information existed, which is clause 6.2's second time.
# An implementation that had provided those names so that they returned an
# error would have produced a program that links, runs, and fails where a
# reader cannot connect it to a missing facility. See the README.
[target.'cfg(os = "emscripten")'.dependencies]
openkal-emscripten = "0.1.0"