# Contributing to nulsl-libc

Thank you for helping Null Linux get a libc that fits in /dev/null.

## Ground rules

1. **C17, and only C17.** No GNU-isms in the language you write (inline
   asm stays in the arch files where it belongs). The build forces
   `-std=c17 -ffreestanding -fno-builtin`; make sure your code compiles
   clean under `-Wall -Wextra -Wshadow -Wpointer-arith`.
2. **Stay lean.** Null Linux runs a GUI in 32 MB. If a change adds RAM
   per process, it needs a better justification than convenience.
3. **AI drafts, humans ship.** AI-generated code is welcome as a draft,
   but it must be reviewed, understood, and improved by a human before it
   lands. If you cannot explain every line, do not open the PR.
4. **The kernel is the API.** Prefer a raw syscall wrapper over
   inventing library machinery. `syscall()` is the only ABI surface —
   keep it that way (see [docs/syscalls.md](docs/syscalls.md)).

## Structure

- `include/` — public headers. Declarations only; the `struct nulsl_file`
  layout and friends stay private in `src/internal.h`.
- `src/` — implementations. One file per header/domain; keep files small
  (a `#include` short of 250 lines is a good ceiling).
- `src/crt/crt0.S` — the entry point. Kept out of `libc.a` on purpose.
- `tests/` — anything you add must be exercised (`make check`).
- `benchmarks/` — anything performance-relevant needs a benchmark
  (`make bench`); if it isn't memory-lean, it doesn't ship.

## The stub convention

Not implemented yet? It still needs its standard signature in the public
header, a documented error return, `errno = ENOSYS`, and a `/* TODO */`
comment naming what it needs. That is a feature, not a placeholder: every
stub fails loudly instead of silently misbehaving.

## Adding a syscall wrapper

1. Number in `include/sys/syscall.h` (guarded, ABI in comment).
2. Declaration in the right public header.
3. Thin wrapper in the right `src/` file — one `syscall()` call, nothing
   else. If it needs to be a stub, follow the stub convention.
4. Update `docs/syscalls.md` (the table).
5. Extend a test in `tests/`.

## Workflow

```sh
./autogen.sh
make release && make check && make bench
make debug        # for actual debugging (bin/debug/, -O0 -g)
```

- Style: `clang-format -i` on your diff (see `.clang-format`); keep diffs
  formatted, small, and single-purpose.
- LSP: `make compile_commands` (needs `bear`) for clangd.
- Verify: `make check` must pass; run `make bench` before and after to
  show you did not make anything slower.
- Commits: small, atomic, descriptive. This project is written by humans
  and reviewed by humans; keep the history reviewable.
- PRs: one idea per PR, with tests. If the change is a stub → real
  transition, say which roadmap item it completes.

## Communication

Open an issue or a PR on
<https://git.spectoria.dev/The-Null-Linux-Project/nulsl-libc>.