From: drh <> Date: Fri, 22 May 2026 11:15:25 +0000 (+0000) Subject: Add a prototype AGENTS.md file X-Git-Url: http://git.ipfire.org/gitweb/index.cgi?a=commitdiff_plain;h=a1e5778889252d2609a59fd9b819d70392c5789e;p=thirdparty%2Fsqlite.git Add a prototype AGENTS.md file FossilOrigin-Name: 3dd1181120b9910a96090b5b3cad5f0829fadeffeb6ffaad17031540a5749513 --- diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..2353027553 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,125 @@ +# AGENTS.md + +Guidance for AI coding agents working in this repository. + +## Project nature + +SQLite is a self-contained, serverless SQL database engine written in C. The +source is **public domain** — no copyright or license header should ever be +added to any file. The blessing comment that appears at the top of each source +file is intentional and should be preserved unchanged. + +SQLite does not accept pull requests without prior agreement and/or +accompanying legal paperwork that places the pull request in the public domain. +However, the human SQLite developers will review a concise and well-written +pull request as a proof-of-concept prior to reimplementing the changes +themselves. + +SQLite does not (currently) accept agentic code. However the project +will accept agentic bug reports that include a reproducible test case. +Patches or pull requests demonstrating a possible fix, for documentation +purposes, are welcomed. + +SQLite uses the [Fossil](https://fossil-scm.org/) for version control, +not Git. The canonical repository is at . + +## Build + +The configure script uses [autosetup](https://msteveb.github.io/autosetup/), +not GNU Autoconf. + +```bash +apt install gcc make tcl-dev # prerequisites (Debian/Ubuntu) + +./configure --dev # debug build +make sqlite3 # CLI shell +make sqlite3d # Debugging variant of the CLI shell +make sqlite3.c # amalgamation (single-file distribution form) +make testfixture # test runner binary (requires tcl-dev) +make tclextension-install # install TCL extension before running tests +``` + +## Testing + +Tests are TCL scripts run through the `testfixture` enhanced interpreter. + +```bash +# From the build directory: +./testfixture test/main.test # single test file +test/testrunner.tcl # quick suite +test/testrunner.tcl full # full suite +test/testrunner.tcl fts5% # pattern match + +# Check for failures: +grep '!' testrunner.log +``` + +`make devtest` is the fastest way to run a representative subset. Always run +at least `devtest` after any change to `src/`. + +## Architecture + +SQL text → **tokenizer** (`tokenize.c`) → **parser** (`parse.y` / Lemon) → +**code generator** (`build.c`, `select.c`, `insert.c`, `update.c`, `delete.c`, +`expr.c`) → **optimizer** (`where*.c`) → **VDBE** (`vdbe.c`) → **B-Tree** +(`btree.c`) → **Pager** (`pager.c`) → **WAL** (`wal.c`) → **VFS** +(`os_unix.c`, `os_win.c`). + +The master internal header is `src/sqliteInt.h`. Major subsystems have private +headers: `vdbeInt.h`, `btreeInt.h`, `whereInt.h`. The public API is defined in +`src/sqlite.h.in` (template) which generates `sqlite3.h`. + +## Do not edit generated files + +These files are produced by scripts and must not be edited by hand: + +| File | Regenerate with | +|---|---| +| `sqlite3.h` | `tool/mksqlite3h.tcl` | +| `parse.c`, `parse.h` | build lemon (`tool/lemon.c`) then run on `src/parse.y` | +| `opcodes.h` | `tool/mkopcodeh.tcl` (reads `src/vdbe.c`) | +| `opcodes.c` | `tool/mkopcodec.tcl` (reads `opcodes.h`) | +| `keywordhash.h` | `tool/mkkeywordhash.c` | +| `pragma.h` | `tool/mkpragmatab.tcl` | +| `sqlite3.c` | `tool/mksqlite3c.tcl` (the amalgamation) | + +Editing rules: +- To add a PRAGMA: edit `tool/mkpragmatab.tcl`, then regenerate `pragma.h`. +- To add a VDBE opcode: add the `case OP_Xxx:` handler in `src/vdbe.c`; the + opcode number and name are extracted automatically by `mkopcodeh.tcl`. +- To change the SQL grammar: edit `src/parse.y`, not `parse.c`. + +## Coding conventions + +- C89/C99 compatible C only. No C++, no STL, no exceptions, no VLAs. +- All memory allocation goes through `sqlite3Malloc` / `sqlite3_malloc64` + (never raw `malloc`). The `sqlite3MallocZero` variant zero-initializes. +- Integer widths: use `i64` (`sqlite3_int64`) for 64-bit values, `u32`/`u64` + for unsigned. Avoid bare `long` or `int` for values that could exceed 2G. +- Error propagation: functions return `SQLITE_OK` (0) on success and a + `SQLITE_*` error code on failure. Many routines also set `db->mallocFailed` + on OOM, allowing deferred error checking. +- Assert liberally for invariants that must hold in correct code; use + `ALWAYS(x)` / `NEVER(x)` for conditions that are logically always + true/false but that the compiler cannot prove. + +## Extensions (`ext/`) + +Extensions are compiled separately from the core and are not part of the +amalgamation by default (except where explicitly included). Major subsystems: + +- `ext/fts5/` — Full-Text Search 5 (current) +- `ext/rtree/` — R-Tree spatial indexing +- `ext/session/` — Changesets and sessions +- `ext/recover/` — Database file recovery +- `ext/misc/` — Single-file utility extensions (many included in the CLI) +- `ext/qrf/` — Query Result Formatter utility library + +## Useful references + +- Architecture: +- File format: +- VDBE opcodes: +- Query planner: +- Lemon parser generator: +- Compile-time options: diff --git a/manifest b/manifest index ea05a71d53..46e29a6f57 100644 --- a/manifest +++ b/manifest @@ -1,8 +1,9 @@ -C Fix\sthe\sVFSes\sso\sthat\sthere\sis\sno\s32-bit\sinteger\soverflow\sin\sthe\nxShmMap\smethod\sif\sthe\sWAL\sfile\ssize\sexceeds\sabout\s25\sterabytes,\sor\nif\sthe\sheader\sis\scorrupted\sto\smake\sSQLite\sthink\sthat\sthe\sWAL\sfile\ssize\nis\sthat\sbig.\n[bugs:/info/2026-05-21T03:53:03Z|Bug\s2026-05-21T03:53:03Z]. -D 2026-05-21T15:14:35.420 +C Add\sa\sprototype\sAGENTS.md\sfile +D 2026-05-22T11:15:25.905 F .fossil-settings/binary-glob 61195414528fb3ea9693577e1980230d78a1f8b0a54c78cf1b9b24d0a409ed6a x F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea +F AGENTS.md 911864e3bae0566aa318b4134ad3568fbbe7b250815f4a55fd3b6c6b0f9bcf47 F LICENSE.md 6bc480fc673fb4acbc4094e77edb326267dd460162d7723c7f30bee2d3d9e97d F Makefile.in 5fda086f33b144da08119255da1d2557f983d0764a13707f05acf0159fd89ba5 F Makefile.linux-generic bd3e3cacd369821a6241d4ea1967395c962dfe3057e38cb0a435cee0e8b789d0 @@ -2205,8 +2206,8 @@ F tool/warnings-clang.sh bbf6a1e685e534c92ec2bfba5b1745f34fb6f0bc2a362850723a9ee F tool/warnings.sh a554d13f6e5cf3760f041b87939e3d616ec6961859c3245e8ef701d1eafc2ca2 F tool/win/sqlite.vsix deb315d026cc8400325c5863eef847784a219a2f F tool/winmain.c 00c8fb88e365c9017db14c73d3c78af62194d9644feaf60e220ab0f411f3604c -P 869a51ae84dfaaf824c872e4b3024f35eea7fa67bb584759a2d42ebf8404ef6e -R 9253aad57f0e0c2cd700de54d1f4d82b +P 9ac4a33a2932d353c4871fd8e09c10addf827f1fc3fc9380037d738cf2cd0353 +R 2bd6937d433d800bf75d925a3aef6528 U drh -Z 444f216a004346dc782c26e43224aa07 +Z 83c1080ffcb6a157fc9e6d16bda364e0 # Remove this line to create a well-formed Fossil manifest. diff --git a/manifest.uuid b/manifest.uuid index 5970dfeaa7..b7bfd73f0c 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -9ac4a33a2932d353c4871fd8e09c10addf827f1fc3fc9380037d738cf2cd0353 +3dd1181120b9910a96090b5b3cad5f0829fadeffeb6ffaad17031540a5749513