huntedbytheirs
180c1107b6
Establish the repository layout per Vox guidelines (layouts/C.md, building/C.md): Autotools build (GCC-only, C23), five compatibility profiles (--enable-onlyposix/--enable-muslmimic/--enable-muslext/ --enable-spoof, default vlibc), alongside/overwrite install methods, vlibc-gcc/vlibc-clang drivers, static-linking requirement (except spoof), benchmark harness, and tooling (.clang-format/.clang-tidy/ .clangd + compile_commands.json).
47 lines
1.9 KiB
Markdown
47 lines
1.9 KiB
Markdown
# Overview
|
|
|
|
vlibc is Vox's replacement for glibc: a C and POSIX library that is modern,
|
|
standard-conforming, and fast. The behavior of the software and its
|
|
differences from glibc are documented here so they can be understood without
|
|
reading optimized source.
|
|
|
|
## Goals
|
|
|
|
- **Replace glibc** for the programs that want a lighter, faster, and cleaner
|
|
libc, while retaining high compatibility.
|
|
- **Be benchmarkable**: every component is measured against glibc (and musl);
|
|
a component slower than what it replaces is considered failing
|
|
(`musts/BENCHMARKING.md`).
|
|
- **Static-linking first**: fully static linking is a hard requirement for
|
|
every profile except `spoof`.
|
|
- **Honor user flags**: `CFLAGS` and `LDFLAGS` are respected; the build uses
|
|
exactly one compiler (GCC) with no fallback.
|
|
|
|
## Compatibility profiles
|
|
|
|
See `docs/compatibility.md` for the five profiles (`onlyposix`, `muslmimic`,
|
|
`muslext`, `spoof`, `vlibc`) and their differences from glibc.
|
|
|
|
## Install methods
|
|
|
|
See `docs/install.md` for the `alongside` and `overwrite` install methods and
|
|
the `vlibc-gcc` / `vlibc-clang` drivers.
|
|
|
|
## Compiler intent
|
|
|
|
Static linking pulls a whole library into every binary, which is expensive in
|
|
size. To offset this, the public API declares *intent* to the compiler via
|
|
attributes such as `__attribute__((const))` and `__attribute__((pure))`. When
|
|
the compiler knows a call has no side effects and a predictable result, it can
|
|
fold or eliminate it during optimization, shrinking the final binary even when
|
|
vlibc is statically linked in full.
|
|
|
|
This is a deliberate design constraint: every public function carries the
|
|
tightest correct intent attribute (see `STYLEGUIDE.md`).
|
|
|
|
## Status
|
|
|
|
This repository is currently a stub — the layout, build system, documentation,
|
|
and a minimal public API (`vlibc_version()`) are in place. Individual library
|
|
components are added incrementally, each with benchmarks.
|