Skip to content

Commit 8aaecb6

Browse files
lewingCopilot
andcommitted
Document WASI sysroot shim header approach
Add a README.md in src/coreclr/pal/src/include/pal/wasi/ that explains: - Why WASI needs a directory of #include_next wrapper headers (the WASI sysroot is missing entire POSIX subsystems: signals, ucontext, parts of pthread, sys/wait, sys/vfs, sys/resource, dlfcn, link, pwd). - Why the conventional HAVE_* configure-check pattern used by Haiku, FreeBSD, OpenBSD, Apple wasn't chosen (the gap spans dozens of files, not a handful of symbols). - How the shims are wired into the build via include_directories(BEFORE SYSTEM ...) at CoreCLR scope, and why the scope cannot be narrowed to PAL alone (minipal, debug, hosts consume the shimmed headers too). - Where link-time stubs live (pal/src/arch/wasm/stubs.cpp, pal/src/arch/wasm/mmap-wasi.c). - When a shim should be removed (upstream provides the symbol, call sites collapse, or the symbol becomes unused). Also expand the in-place comment on the include_directories line in src/coreclr/CMakeLists.txt to point at the README so future maintainers encounter the rationale next to the code rather than only via grep. Co-authored-by: Copilot <[email protected]>
1 parent 48653be commit 8aaecb6

2 files changed

Lines changed: 97 additions & 1 deletion

File tree

‎src/coreclr/CMakeLists.txt‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,13 @@ if(CLR_CMAKE_TARGET_WASI)
4242
# WASI doesn't define these fcntl constants — provide them as no-ops
4343
add_compile_definitions(F_DUPFD_CLOEXEC=1030)
4444
add_compile_definitions(O_CLOEXEC=0)
45-
# WASI stub headers for missing POSIX headers
45+
# WASI sysroot is missing entire POSIX subsystems (signal, ucontext, parts
46+
# of pthread, sys/wait, sys/vfs, sys/resource, dlfcn, link, pwd). The shim
47+
# headers under pal/src/include/pal/wasi/ use #include_next to layer the
48+
# missing declarations and link-time stubs on top of the WASI sysroot
49+
# headers. They must be visible BEFORE SYSTEM at the CoreCLR scope because
50+
# minipal, debug, hosts and other non-PAL targets also include the affected
51+
# headers. See pal/src/include/pal/wasi/README.md for the design rationale.
4652
include_directories(BEFORE SYSTEM ${CMAKE_CURRENT_SOURCE_DIR}/pal/src/include/pal/wasi)
4753
endif()
4854

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# WASI POSIX shim headers
2+
3+
This directory contains a set of header wrappers that augment the WASI sysroot
4+
with POSIX declarations and inline stub implementations required by the
5+
CoreCLR PAL and adjacent components (minipal, debug, hosts).
6+
7+
## Why this exists
8+
9+
Unlike Linux, macOS, FreeBSD, OpenBSD, Android, or Haiku, the WASI sysroot
10+
is missing entire POSIX subsystems:
11+
12+
| Subsystem | Status in WASI |
13+
|-----------|---------------|
14+
| Signals (`<signal.h>`, `sigaction`, `siginfo_t`, `sigaltstack`) | Most declarations hidden behind `__wasilibc_unmodified_upstream` |
15+
| `<ucontext.h>` | Not provided |
16+
| `<pthread.h>` | Partial — `pthread_setschedparam`, `pthread_getschedparam`, `pthread_exit` declarations missing |
17+
| `<sys/wait.h>` | Not provided |
18+
| `<sys/vfs.h>` (statfs) | Not provided |
19+
| `<sys/resource.h>` (rusage) | Partial |
20+
| `<dlfcn.h>` (dynamic loading) | Not provided |
21+
| `<link.h>` (link map) | Not provided |
22+
| `<pwd.h>` (user database) | Not provided |
23+
24+
The PAL and adjacent code consume these headers from dozens of translation
25+
units. Two patterns were considered:
26+
27+
### Alternative 1 — `HAVE_*` configure checks (the dominant PAL pattern)
28+
29+
Existing platforms (Haiku, FreeBSD, OpenBSD, Apple) handle missing pieces by:
30+
31+
1. Probing for the missing symbol in `pal/src/configure.cmake` with
32+
`check_include_files` / `check_function_exists`.
33+
2. Wrapping each call site in `#if HAVE_<NAME>`.
34+
3. Adding inline stubs to the shared `.cpp` file behind `#ifdef <PLATFORM>`.
35+
36+
This works well when the gap is small (e.g., Haiku is missing a handful of
37+
symbols). It scales poorly for WASI because the gap spans *most of POSIX*
38+
across *many* PAL files. Applying it here would produce hundreds of
39+
`#if HAVE_*` blocks scattered across `pal/src/{thread,exception,signal,
40+
synchmgr,init,debug,loader,map,misc}/`.
41+
42+
### Alternative 2 — Sysroot shim headers (the approach taken)
43+
44+
A single directory of `#include_next` wrappers layers the missing
45+
declarations and link-time-stubbed inline functions on top of the WASI
46+
sysroot. Each shim is small (10–100 lines) and lives next to its peers,
47+
making the platform delta inspectable in one place.
48+
49+
The shim approach is similar to how Apple's `sys/sysctl.h` or Linux's
50+
`linux/elf.h` are sometimes wrapped by build systems that need to add
51+
missing typedefs.
52+
53+
## How the shims are wired into the build
54+
55+
`src/coreclr/CMakeLists.txt` adds the shim directory via
56+
57+
include_directories(BEFORE SYSTEM ...pal/src/include/pal/wasi)
58+
59+
inside the `if(CLR_CMAKE_TARGET_WASI)` block. The `BEFORE SYSTEM` placement
60+
ensures the wrapper resolves before the WASI sysroot's own `<signal.h>`,
61+
allowing each wrapper to do `#include_next <signal.h>` to chain to the
62+
underlying header and then add missing declarations on top.
63+
64+
The scope is intentionally the entire CoreCLR build, not just PAL.
65+
`minipal/Unix/doublemapping.cpp` and `debug/dbgutil/` also include
66+
`<link.h>`, `<dlfcn.h>`, and `<sys/resource.h>`. Limiting the scope to PAL
67+
would require either narrowing the consumer set (large refactor) or
68+
duplicating the include-directory glue in every subdirectory that needs it.
69+
70+
## Link-time stubs
71+
72+
Header declarations alone are not enough — when the PAL references
73+
`pthread_setschedparam` (declared in the shim) the linker still needs a
74+
definition. Trivial stubs (return -1, no-op, etc.) live in
75+
`pal/src/arch/wasm/stubs.cpp`. Heavier shims like the
76+
`posix_memalign`-backed arena allocator that replaces `mmap` for anonymous
77+
mappings live next to them in `mmap-wasi.c`.
78+
79+
## When to remove a shim
80+
81+
A shim should be removed (and the symbol absorbed back into the shared PAL)
82+
when one of the following becomes true:
83+
84+
1. The upstream WASI sysroot starts providing the missing declaration.
85+
Track [WebAssembly/wasi-libc](https://github.com/WebAssembly/wasi-libc)
86+
for additions.
87+
2. The number of call sites in CoreCLR shrinks to a handful, at which point
88+
`HAVE_*` configure checks become cheaper than a wrapper header.
89+
3. The symbol becomes completely unused in the WASI build, in which case
90+
the shim can be deleted outright.

0 commit comments

Comments
 (0)