Add vlibc scaffold, build system, and documentation

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).
This commit is contained in:
2026-08-31 17:06:01 -04:00
parent 3f63ae1cdd
commit 180c1107b6
25 changed files with 17796 additions and 1 deletions
+46
View File
@@ -0,0 +1,46 @@
# 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.