docs(profile): document gating mechanism, classification rule, slice manifest

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <[email protected]>
This commit is contained in:
2026-08-31 19:54:40 -04:00
co-authored by Sisyphus
parent f07b270675
commit 060fc03ab7
3 changed files with 80 additions and 0 deletions
+45
View File
@@ -11,6 +11,51 @@ mutually exclusive; the default is `vlibc`.
| 4 | `--enable-spoof` | `spoof` | A glibc replica: emulates glibc for drop-in compatibility, higher than `muslext` or `vlibc` full. |
| 5 | *(default)* | `vlibc` | glibc-extended: glibc minus its baggage, plus extended standard features. High (but not spoof-level) glibc compatibility. |
## Profile mechanism
The profiles map onto a single integer level, `VLIBC_LEVEL`. Levels are
**cumulative**: a profile at level N exposes everything whose minimum level is
`<= N`.
| Level | Classification |
|-------|-----------------------------------------|
| 1 | ISO C + POSIX base |
| 2 | + BSD / XSI extensions |
| 3 | + GNU extensions |
Public headers gate declarations with `#if VLIBC_LEVEL >= N`; a function whose
minimum level is 2 is only declared when the active profile is level 2 or
higher. The build applies the same rule to sources via
`AM_CONDITIONAL([PROFILE_GE_2])` and `AM_CONDITIONAL([PROFILE_GE_3])`, so each
level's implementation files are only compiled when the selected profile
reaches that level.
The generated installed header `include/vlibc/features.h` exposes the macros
the gating is based on:
- `VLIBC_LEVEL` — the active profile's integer level.
- `VLIBC_PROFILE` — the selected profile name.
- `VLIBC_LEVEL_GE(n)` — expands to 1 when `VLIBC_LEVEL >= n`, 0 otherwise.
### Slice manifest
The initial implementation covers eight string/memory functions, classified as
follows:
| Function | Level | Origin |
|--------------|-------|---------|
| `memcpy` | L1 | ISO C |
| `memmove` | L1 | ISO C |
| `memset` | L1 | ISO C |
| `strlen` | L1 | ISO C |
| `strcmp` | L1 | ISO C |
| `strlcpy` | L2 | BSD |
| `strlcat` | L2 | BSD |
| `strcasestr` | L3 | GNU |
Profiles 4 and 5 (`spoof`, `vlibc`) build on the same level mechanism but are
not implemented in this increment beyond their configure declarations.
## Differences from glibc
- **No legacy baggage.** vlibc targets modern, standard-conforming behavior and