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).
2026-08-31 17:06:01 -04:00
parent 3f63ae1cdd
commit 180c1107b6
25 changed files with 17796 additions and 1 deletions
@@ -0,0 +1,76 @@
+# Contributing
+
+## Compiler policy
+
+vlibc is built with **exactly one compiler: GCC**. There is no fallback to
+another compiler (`building/C.md`). This lets vlibc use compiler extensions
+freely while keeping behavior deterministic.
+
+## Building
+
+```sh
+./autogen.sh            # autoreconf + configure
+make                    # build
+make debug              # -O0 -g3 into bin/debug/
+make release            # -O3 into bin/release/
+make bench              # build + run benchmarks
+make clean              # remove artifacts
+```
+
+`autogen.sh` regenerates the build system from `configure.ac` / `Makefile.am`
+and then runs `configure`. The generated `configure` script is tracked; the
+Makefiles it produces are not.
+
+### Compatibility profiles
+
+Pick exactly one (they are mutually exclusive):
+
+| Flag                  | Profile      | Description                       |
+|-----------------------|--------------|-----------------------------------|
+| *(default)*           | `vlibc`      | glibc-extended, extended features |
+| `--enable-onlyposix`  | `onlyposix`  | pure POSIX, nothing more          |
+| `--enable-muslmimic`  | `muslmimic`  | musl-like, light                  |
+| `--enable-muslext`    | `muslext`    | musl-extended                     |
+| `--enable-spoof`      | `spoof`      | glibc replica (drop-in)           |
+
+### Install methods
+
+```sh
+./autogen.sh --with-install=alongside   # default: keep system libc
+./autogen.sh --with-install=overwrite   # replace system libc
+```
+
+### Static linking
+
+Full static linking is **required** for every profile except `spoof`. Configure
+rejects `--disable-static` for those profiles.
+
+## Benchmarks
+
+Every component must be benchmarked against the software it replaces
+(`musts/BENCHMARKING.md`). A component slower than glibc is failing.
+
+```sh
+./autogen.sh --with-libc=glibc   # reference comparison
+make bench
+```
+
+## Style and linting
+
+- `.clang-format` — run `clang-format` before committing; it must agree with
+  `STYLEGUIDE.md`.
+- `.clang-tidy` — `bugprone-*` and `clang-analyzer-*` are warnings-as-errors.
+- Keep `compile_commands.json` fresh (`make compile-commands`) so language
+  servers do not report errors on valid code.
+
+## Vendoring
+
+Third-party code goes in `thirdparty/`, with its upstream source, version, and
+license recorded alongside it. No external downloads at build time.
+
+## Submitting changes
+
+1. Open an issue describing the problem or feature first.
+2. Keep changes small and focused; one concern per change.
+3. Add or update benchmarks and documentation with the change.
+4. Ensure `make debug`, `make release`, and `make bench` pass.