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