CodeVetter · Repo Unpack · Contributor handoff
sqlite/sqlite
The hard constraints here are unusual and worth internalizing before touching anything: this is public-domain C with no license headers ever added, it is developed in Fossil (the Git remote is a mirror with different check-in names), and AGENTS.md states outright that the project does not accept agentic code — agentic *bug reports with reproducible test cases* are welcome, and patches are accepted only as proof-of-concept documentation. Practically, that means the safe posture is: read, reproduce, write a `.test` case, and propose rather than land. When editing is in scope, the rules are C89/C99 only, `sqlite3Malloc` family for all allocation, `i64`/`u32`/`u64` for width-sensitive values, `SQLITE_OK`/`SQLITE_*` return codes, liberal `assert` with `ALWAYS`/`NEVER` for compiler-opaque invariants, and never touching a generated file. Always run at least `make devtest` after any `src/` change.
- Read first, in this order: `AGENTS.md` (project constraints and generated-file table), `README.md` (source tree map and build instructions), `src/sqliteInt.h` (6,031 lines — the master internal header), and `src/sqlite.h.in` (the public API template and the source of the API docs).
- Never add a copyright or license header: every file carries the intentional 'May you do good and not evil' blessing comment instead, and adding a header would jeopardize the public-domain status the project depends on.
- Do not hand-edit generated files: `sqlite3.h` (from `tool/mksqlite3h.tcl`), `parse.c`/`parse.h` (lemon on `src/parse.y`), `opcodes.h`/`opcodes.c` (`mkopcodeh.tcl`/`mkopcodec.tcl`), `keywordhash.h` (`tool/mkkeywordhash.c`), `pragma.h` (`tool/mkpragmatab.tcl`), `sqlite3.c` (`tool/mksqlite3c.tcl`).
- Build for development with `./configure --dev`, which `auto.def` translates into `--all --debug`, amalgamation *off* (so each `src/*.c` compiles separately and errors point at real files), and `CFLAGS=-O0 -g`.
- The configure script is autosetup, not GNU Autoconf, and must stay JimTCL-compatible — `autosetup/jimsh0.c` is bundled so the tree can configure without a system tclsh. Project-specific procs are prefixed `sqlite-` (in `autosetup/sqlite-config.tcl`), generic ones `proj-` (in `autosetup/proj.tcl`).
- Tests need TCL: install `tcl-dev`, run `make tclextension-install` before `make devtest`, and note that `testrunner.tcl` will try to re-exec itself under `./testfixture` if `package require sqlite3` fails.
- Minimum test bar for any `src/` change is `make devtest` (`srctree-check` + `sourcetest` + `testrunner.tcl mdevtest`); targeted runs use `./testfixture test/<file>.test` or `test/testrunner.tcl fts5%` pattern matching, and failures are found with `grep '!' testrunner.log`.
- Coding conventions to match: C89/C99 only (no C++/VLAs), all allocation through `sqlite3Malloc`/`sqlite3MallocZero`/`sqlite3_malloc64` rather than raw `malloc`, `i64`/`u32`/`u64` instead of bare `long`/`int` for values that can exceed 2G, `SQLITE_OK`-style return codes with `db->mallocFailed` for deferred OOM detection.
- `assert()` is used as executable documentation throughout and is expected in new code; use `ALWAYS(x)`/`NEVER(x)` for conditions the compiler cannot prove — e.g. `ALWAYS(cnt<=SQLITE_MAX_PREPARE_RETRY)` in the prepare retry loop and `NEVER(pPager->errCode)` in commit.
- Requirement-traceability comments matter: `EVIDENCE-OF: R-#####-#####` markers in the sources tie code to numbered statements in the external documentation (e.g. in `sqlite3_prepare_v2`/`_v3`), and `testcase()` markers mark branches the test suite is expected to cover — preserve both when editing.
- Match the file's existing idiom: this codebase uses two-space indentation, `if( cond ){` spacing with no space after `if`, `/* ... */` block comments only, and `**` comment continuation banners — deviating is immediately visible in diffs.
- Safe edit boundaries: `ext/misc/*.c` single-file extensions and `test/*.test` scripts are the lowest-risk places to add code; `src/btree.c`, `src/pager.c`, `src/wal.c`, `src/vdbe.c` and `src/where.c` are the highest-risk and should not be touched without a reproducing test.
- Known trap: the CLI is not built from `src/shell.c` — that file does not exist in the tree. Edit `src/shell.c.in` and let the build's `INCLUDE`-processing step produce `shell.c`.
- Known trap: when reporting a check-in, use the official Fossil name from `manifest.uuid` (`c9b4695ffae5a3388a49643d6819355851a0fda362cdaf140c59fc934759dcac`), not the Git SHA — the README states these differ for all mirrors.
- Useful debugging levers already in-tree: `SQLITE_DEBUG_BREAK` env var (shell attaches a debugger), `PRAGMA vdbe_trace`/`vdbe_listing`/`vdbe_eqp` via `SQLITE_VdbeTrace` flags in `sqlite3VdbeExec`, `SQLITE_ParserTrace` in `sqlite3RunParser`, and the `.wheretrace`/`.iotrace` dot-commands.