# vlibc

A modern replacement for glibc: a performant, standard-conforming C library
with modern extensions and high glibc compatibility.

vlibc is written in C (C23, with C2y/C29 opt-in), built with Autotools and a
single compiler (GCC, no fallback). Full static linking is a first-class,
required capability.

## Capabilities

- **Five compatibility profiles**, from the lightest to the most compatible:
  1. `--enable-onlyposix` — pure POSIX, nothing more.
  2. `--enable-muslmimic` — musl-like, light and musl-compatible.
  3. `--enable-muslext` — musl-extended.
  4. `--enable-spoof` — a glibc replica, for drop-in compatibility with
     scripts and programs that rely on long-standing glibc behavior.
  5. *(default)* — **vlibc**: glibc-extended, without the spoofing layer, but
     with extended standard features and high glibc compatibility.
- **Profiles 1-3 are functional.** `--enable-onlyposix`, `--enable-muslmimic`,
  and `--enable-muslext` build with real build-time profile gating: a generated
  `include/vlibc/features.h` exposes `VLIBC_LEVEL`, the public `<stddef.h>` and
  `<string.h>` headers are gated by it, and an initial string slice (`memcpy`,
  `memmove`, `memset`, `strlen`, `strcmp`, `strlcpy`, `strlcat`,
  `strcasestr`) is compiled per level. Profiles 4 and 5 (`spoof`, `vlibc`)
  remain configure-level declarations in this increment.
- **Two install methods** (`--with-install=`):
  - `alongside` (default) — install next to the system libc, under a
    vlibc-specific tree; the system libc is left untouched.
  - `overwrite` — replace the system libc in place.
- **`vlibc-gcc` and `vlibc-clang`** compiler drivers, so consuming projects
  build against vlibc with either compiler.
- **Full static linking** is required for every profile except `spoof`.
- **Compiler intent** is declared on the public API (e.g.
  `__attribute__((const))`) so the compiler can fold and eliminate calls,
  keeping statically linked binaries small.

## Build

```sh
./autogen.sh                 # regenerate build system + configure
make                          # build
make debug                    # build with -O0 -g3 into bin/debug/
make release                  # build with -O3 into bin/release/
make bench                    # build and run benchmarks
make clean                    # remove build artifacts
make compile-commands         # regenerate compile_commands.json (needs bear)
```

Common configure options:

```sh
./autogen.sh --enable-spoof                     # glibc replica profile
./autogen.sh --with-install=overwrite           # replace system libc
./autogen.sh --with-libc=glibc                  # benchmark against glibc
./autogen.sh --enable-c29                       # experimental C2y (C29)
```

User-provided `CFLAGS` and `LDFLAGS` are honored.

## Layout

```
include/        public headers (mandatory)
src/            implementation sources
benchmarks/     benchmark harnesses (vs. glibc/musl)
docs/           behavior and glibc-difference documentation
thirdparty/     vendored third-party libraries
tools/          vlibc-gcc / vlibc-clang driver templates
bin/{release,debug}/  build outputs
```

## Documentation

- `docs/overview.md` — what vlibc is and how it behaves.
- `docs/compatibility.md` — the five profiles and glibc differences.
- `docs/install.md` — the two install methods.
- `CONTRIBUTING.md` — how to contribute.
- `STYLEGUIDE.md` — how code should look.