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
42 changes: 35 additions & 7 deletions examples/portable/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ different ways:
| macOS | `cfg(os = "macos")` | `openkal-macos` |
| iOS, both simulator arches | `cfg(os = "ios")` | `openkal-macos`, unchanged |
| Windows | `cfg(windows)` | `openkal-windows` |
| Web (Emscripten) | `cfg(os = "emscripten")` | `openkal-emscripten` |
| Web (Emscripten) | `cfg(os = "emscripten")` | `openkal-emscripten`, which provides twelve of fifteen |

**Android needs no line of its own**, because `aarch64-linux-android` has
`os = "linux"`: the kernel IS Linux, bionic is a C library above it, and an
Expand All @@ -48,12 +48,40 @@ same call numbers, the same calling convention — and what differs between macO
and iOS is the SDK and the deployment-target flag, which belong to the build
tool. So one `cfg` line selects the macOS implementation for all three iOS rows.

**The Web needed new software.** Emscripten has no kernel to issue a call to,
so an implementation there cannot be written beneath a C library and has to sit
above one. `openkal-emscripten` provides twelve of the fifteen interfaces; this
program uses eight, all of which are among them. A program that used
`openkal.process` would fail at link naming the symbol, which is how a partial
surface reports itself.
**The Web needed new software, and this program does not fit on it.**
Emscripten has no kernel to issue a call to, so an implementation there cannot
be written beneath a C library and has to sit above one. `openkal-emscripten`
is that implementation, and it provides twelve of the fifteen interfaces: there
is no fork, no exec and no second address space on this platform, so
`openkal.process`, `openkal.exec` and `openkal.space` are absent. This program
uses `openkal.process` and `openkal.task`.

So the Web line is here to show the BOUNDARY, and the boundary is a link error.
Measured:

```
$ mcpp build --target wasm32-emscripten
wasm-ld: error: obj/main.o: undefined symbol: kal_process_spawn
wasm-ld: error: obj/main.o: undefined symbol: kal_process_wait
wasm-ld: error: obj/main.o: undefined symbol: kal_process_close
wasm-ld: error: obj/main.o: undefined symbol: kal_task_start
wasm-ld: error: obj/main.o: undefined symbol: kal_task_join
wasm-ld: error: obj/main.o: undefined symbol: kal_task_wait
wasm-ld: error: obj/main.o: undefined symbol: kal_task_wake
```

Seven names, each one the program used and the platform does not have. That is
clause 6.2's second time and it is the mechanism rather than a defect: the
dependency RESOLVED, the compile succeeded, and the report arrived at the
earliest moment the information existed. An implementation that had provided
those seven so that they returned an error would have produced a program that
links, runs, and fails somewhere a reader cannot connect to a missing facility.

`openkal.task` is a second question on this platform and has the same answer
here. It is carried by `openkal-emscripten`'s `threads` feature, because
`-pthread` selects a different C library build and memory model; with that
feature the four `kal_task_*` names above resolve. The three `kal_process_*`
names never will.

## The version pins here are a claim, and they were wrong

Expand Down
19 changes: 15 additions & 4 deletions examples/portable/mcpp.toml
Original file line number Diff line number Diff line change
Expand Up @@ -66,9 +66,20 @@ openkal-macos = "0.9.0"
# ABOVE one, which clause 2 permits. `openkal-emscripten` is that
# implementation.
#
# It provides twelve of the fifteen interfaces. This program uses eight, all of
# which are among them; a program that used `openkal.process` would fail at
# LINK naming the symbol, which is clause 6.2's second time and is how a
# partial surface reports itself.
# 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"
Loading