# 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.