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:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user