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