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
+28
View File
@@ -76,6 +76,34 @@ linked binaries (see `docs/overview.md`):
Every public function carries the tightest correct attribute.
## Profile gating
Profile-gated code follows these formatting and naming conventions (the
semantic classification of functions into levels lives in
`docs/compatibility.md`, not here):
- Public headers gate declarations with `#if VLIBC_LEVEL >= N`. Prefer the
`VLIBC_LEVEL_GE(n)` helper from `include/vlibc/features.h`; fall back to the
raw comparison only when the level is a literal constant:
```c
#if VLIBC_LEVEL_GE(2)
size_t strlcpy(char *dst, const char *src, size_t n);
#endif
```
- Group implementation sources by level in `Makefile.am` using the per-level
conditionals `if PROFILE_GE_2` / `if PROFILE_GE_3`, mirroring the
`#if VLIBC_LEVEL >= N` rule in headers.
- Standard headers use `VLIBC_`-prefixed include guards
(`VLIBC_STDDEF_H`, `VLIBC_STRING_H`), never the `_STDDEF_H`-style reserved
forms. A leading underscore is reserved for the implementation and the
C/POSIX standards (see Naming); the `VLIBC_` prefix stays out of the
reserved namespace while remaining unambiguous.
- Intent attributes respect the gating: `pure` / `const` are only valid on
side-effect-free functions. Never annotate a mutating function (`memcpy`,
`memmove`, `memset`, `strlcpy`, `strlcat`) with either.
## Error handling
- No empty blocks; no silent failure.