1<h1 align="center">SQLite Source Repository</h1> 2 3This repository contains the complete source code for the SQLite database 4engine. Some test scripts are also included. However, many other test scripts 5and most of the documentation are managed separately. 6 7SQLite [does not use Git](https://sqlite.org/whynotgit.html). 8If you are reading this on GitHub, then you are looking at an 9unofficial mirror. See <https://sqlite.org/src> for the official 10repository. 11 12## Obtaining The Code 13 14SQLite sources are managed using the 15[Fossil](https://www.fossil-scm.org/), a distributed version control system 16that was specifically designed to support SQLite development. 17If you do not want to use Fossil, you can download tarballs or ZIP 18archives or [SQLite archives](https://sqlite.org/cli.html#sqlar) as follows: 19 20 * Lastest trunk check-in as 21 [Tarball](https://www.sqlite.org/src/tarball/sqlite.tar.gz), 22 [ZIP-archive](https://www.sqlite.org/src/zip/sqlite.zip), or 23 [SQLite-archive](https://www.sqlite.org/src/sqlar/sqlite.sqlar). 24 25 * Latest release as 26 [Tarball](https://www.sqlite.org/src/tarball/sqlite.tar.gz?r=release), 27 [ZIP-archive](https://www.sqlite.org/src/zip/sqlite.zip?r=release), or 28 [SQLite-archive](https://www.sqlite.org/src/sqlar/sqlite.sqlar?r=release). 29 30 * For other check-ins, substitute an appropriate branch name or 31 tag or hash prefix for "release" in the URLs of the previous 32 bullet. Or browse the [timeline](https://www.sqlite.org/src/timeline) 33 to locate the check-in desired, click on its information page link, 34 then click on the "Tarball" or "ZIP Archive" links on the information 35 page. 36 37If you do want to use Fossil to check out the source tree, 38first install Fossil version 2.0 or later. 39(Source tarballs and precompiled binaries available 40[here](https://www.fossil-scm.org/fossil/uv/download.html). Fossil is 41a stand-alone program. To install, simply download or build the single 42executable file and put that file someplace on your $PATH.) 43Then run commands like this: 44 45 mkdir ~/sqlite 46 cd ~/sqlite 47 fossil clone https://www.sqlite.org/src sqlite.fossil 48 fossil open sqlite.fossil 49 50After setting up a repository using the steps above, you can always 51update to the lastest version using: 52 53 fossil update trunk ;# latest trunk check-in 54 fossil update release ;# latest official release 55 56Or type "fossil ui" to get a web-based user interface. 57 58## Compiling 59 60First create a directory in which to place 61the build products. It is recommended, but not required, that the 62build directory be separate from the source directory. Cd into the 63build directory and then from the build directory run the configure 64script found at the root of the source tree. Then run "make". 65 66For example: 67 68 tar xzf sqlite.tar.gz ;# Unpack the source tree into "sqlite" 69 mkdir bld ;# Build will occur in a sibling directory 70 cd bld ;# Change to the build directory 71 ../sqlite/configure ;# Run the configure script 72 make ;# Run the makefile. 73 make sqlite3.c ;# Build the "amalgamation" source file 74 make test ;# Run some tests (requires Tcl) 75 76See the makefile for additional targets. 77 78The configure script uses autoconf 2.61 and libtool. If the configure 79script does not work out for you, there is a generic makefile named 80"Makefile.linux-gcc" in the top directory of the source tree that you 81can copy and edit to suit your needs. Comments on the generic makefile 82show what changes are needed. 83 84## Using MSVC 85 86On Windows, all applicable build products can be compiled with MSVC. 87First open the command prompt window associated with the desired compiler 88version (e.g. "Developer Command Prompt for VS2013"). Next, use NMAKE 89with the provided "Makefile.msc" to build one of the supported targets. 90 91For example: 92 93 mkdir bld 94 cd bld 95 nmake /f Makefile.msc TOP=..\sqlite 96 nmake /f Makefile.msc sqlite3.c TOP=..\sqlite 97 nmake /f Makefile.msc sqlite3.dll TOP=..\sqlite 98 nmake /f Makefile.msc sqlite3.exe TOP=..\sqlite 99 nmake /f Makefile.msc test TOP=..\sqlite 100 101There are several build options that can be set via the NMAKE command 102line. For example, to build for WinRT, simply add "FOR_WINRT=1" argument 103to the "sqlite3.dll" command line above. When debugging into the SQLite 104code, adding the "DEBUG=1" argument to one of the above command lines is 105recommended. 106 107SQLite does not require [Tcl](http://www.tcl.tk/) to run, but a Tcl installation 108is required by the makefiles (including those for MSVC). SQLite contains 109a lot of generated code and Tcl is used to do much of that code generation. 110 111## Source Code Tour 112 113Most of the core source files are in the **src/** subdirectory. The 114**src/** folder also contains files used to build the "testfixture" test 115harness. The names of the source files used by "testfixture" all begin 116with "test". 117The **src/** also contains the "shell.c" file 118which is the main program for the "sqlite3.exe" 119[command-line shell](https://sqlite.org/cli.html) and 120the "tclsqlite.c" file which implements the 121[Tcl bindings](https://sqlite.org/tclsqlite.html) for SQLite. 122(Historical note: SQLite began as a Tcl 123extension and only later escaped to the wild as an independent library.) 124 125Test scripts and programs are found in the **test/** subdirectory. 126Addtional test code is found in other source repositories. 127See [How SQLite Is Tested](http://www.sqlite.org/testing.html) for 128additional information. 129 130The **ext/** subdirectory contains code for extensions. The 131Full-text search engine is in **ext/fts3**. The R-Tree engine is in 132**ext/rtree**. The **ext/misc** subdirectory contains a number of 133smaller, single-file extensions, such as a REGEXP operator. 134 135The **tool/** subdirectory contains various scripts and programs used 136for building generated source code files or for testing or for generating 137accessory programs such as "sqlite3_analyzer(.exe)". 138 139### Generated Source Code Files 140 141Several of the C-language source files used by SQLite are generated from 142other sources rather than being typed in manually by a programmer. This 143section will summarize those automatically-generated files. To create all 144of the automatically-generated files, simply run "make target_source". 145The "target_source" make target will create a subdirectory "tsrc/" and 146fill it with all the source files needed to build SQLite, both 147manually-edited files and automatically-generated files. 148 149The SQLite interface is defined by the **sqlite3.h** header file, which is 150generated from src/sqlite.h.in, ./manifest.uuid, and ./VERSION. The 151[Tcl script](http://www.tcl.tk) at tool/mksqlite3h.tcl does the conversion. 152The manifest.uuid file contains the SHA3 hash of the particular check-in 153and is used to generate the SQLITE\_SOURCE\_ID macro. The VERSION file 154contains the current SQLite version number. The sqlite3.h header is really 155just a copy of src/sqlite.h.in with the source-id and version number inserted 156at just the right spots. Note that comment text in the sqlite3.h file is 157used to generate much of the SQLite API documentation. The Tcl scripts 158used to generate that documentation are in a separate source repository. 159 160The SQL language parser is **parse.c** which is generate from a grammar in 161the src/parse.y file. The conversion of "parse.y" into "parse.c" is done 162by the [lemon](./doc/lemon.html) LALR(1) parser generator. The source code 163for lemon is at tool/lemon.c. Lemon uses the tool/lempar.c file as a 164template for generating its parser. 165 166Lemon also generates the **parse.h** header file, at the same time it 167generates parse.c. But the parse.h header file is 168modified further (to add additional symbols) using the ./addopcodes.tcl 169Tcl script. 170 171The **opcodes.h** header file contains macros that define the numbers 172corresponding to opcodes in the "VDBE" virtual machine. The opcodes.h 173file is generated by the scanning the src/vdbe.c source file. The 174Tcl script at ./mkopcodeh.tcl does this scan and generates opcodes.h. 175A second Tcl script, ./mkopcodec.tcl, then scans opcodes.h to generate 176the **opcodes.c** source file, which contains a reverse mapping from 177opcode-number to opcode-name that is used for EXPLAIN output. 178 179The **keywordhash.h** header file contains the definition of a hash table 180that maps SQL language keywords (ex: "CREATE", "SELECT", "INDEX", etc.) into 181the numeric codes used by the parse.c parser. The keywordhash.h file is 182generated by a C-language program at tool mkkeywordhash.c. 183 184The **pragma.h** header file contains various definitions used to parse 185and implement the PRAGMA statements. The header is generated by a 186script **tool/mkpragmatab.tcl**. If you want to add a new PRAGMA, edit 187the **tool/mkpragmatab.tcl** file to insert the information needed by the 188parser for your new PRAGMA, then run the script to regenerate the 189**pragma.h** header file. 190 191### The Amalgamation 192 193All of the individual C source code and header files (both manually-edited 194and automatically-generated) can be combined into a single big source file 195**sqlite3.c** called "the amalgamation". The amalgamation is the recommended 196way of using SQLite in a larger application. Combining all individual 197source code files into a single big source code file allows the C compiler 198to perform more cross-procedure analysis and generate better code. SQLite 199runs about 5% faster when compiled from the amalgamation versus when compiled 200from individual source files. 201 202The amalgamation is generated from the tool/mksqlite3c.tcl Tcl script. 203First, all of the individual source files must be gathered into the tsrc/ 204subdirectory (using the equivalent of "make target_source") then the 205tool/mksqlite3c.tcl script is run to copy them all together in just the 206right order while resolving internal "#include" references. 207 208The amalgamation source file is more than 200K lines long. Some symbolic 209debuggers (most notably MSVC) are unable to deal with files longer than 64K 210lines. To work around this, a separate Tcl script, tool/split-sqlite3c.tcl, 211can be run on the amalgamation to break it up into a single small C file 212called **sqlite3-all.c** that does #include on about seven other files 213named **sqlite3-1.c**, **sqlite3-2.c**, ..., **sqlite3-7.c**. In this way, 214all of the source code is contained within a single translation unit so 215that the compiler can do extra cross-procedure optimization, but no 216individual source file exceeds 32K lines in length. 217 218## How It All Fits Together 219 220SQLite is modular in design. 221See the [architectural description](http://www.sqlite.org/arch.html) 222for details. Other documents that are useful in 223(helping to understand how SQLite works include the 224[file format](http://www.sqlite.org/fileformat2.html) description, 225the [virtual machine](http://www.sqlite.org/opcode.html) that runs 226prepared statements, the description of 227[how transactions work](http://www.sqlite.org/atomiccommit.html), and 228the [overview of the query planner](http://www.sqlite.org/optoverview.html). 229 230Years of effort have gone into optimizating SQLite, both 231for small size and high performance. And optimizations tend to result in 232complex code. So there is a lot of complexity in the current SQLite 233implementation. It will not be the easiest library in the world to hack. 234 235Key files: 236 237 * **sqlite.h.in** - This file defines the public interface to the SQLite 238 library. Readers will need to be familiar with this interface before 239 trying to understand how the library works internally. 240 241 * **sqliteInt.h** - this header file defines many of the data objects 242 used internally by SQLite. In addition to "sqliteInt.h", some 243 subsystems have their own header files. 244 245 * **parse.y** - This file describes the LALR(1) grammar that SQLite uses 246 to parse SQL statements, and the actions that are taken at each step 247 in the parsing process. 248 249 * **vdbe.c** - This file implements the virtual machine that runs 250 prepared statements. There are various helper files whose names 251 begin with "vdbe". The VDBE has access to the vdbeInt.h header file 252 which defines internal data objects. The rest of SQLite interacts 253 with the VDBE through an interface defined by vdbe.h. 254 255 * **where.c** - This file (together with its helper files named 256 by "where*.c") analyzes the WHERE clause and generates 257 virtual machine code to run queries efficiently. This file is 258 sometimes called the "query optimizer". It has its own private 259 header file, whereInt.h, that defines data objects used internally. 260 261 * **btree.c** - This file contains the implementation of the B-Tree 262 storage engine used by SQLite. The interface to the rest of the system 263 is defined by "btree.h". The "btreeInt.h" header defines objects 264 used internally by btree.c and not published to the rest of the system. 265 266 * **pager.c** - This file contains the "pager" implementation, the 267 module that implements transactions. The "pager.h" header file 268 defines the interface between pager.c and the rest of the system. 269 270 * **os_unix.c** and **os_win.c** - These two files implement the interface 271 between SQLite and the underlying operating system using the run-time 272 pluggable VFS interface. 273 274 * **shell.c.in** - This file is not part of the core SQLite library. This 275 is the file that, when linked against sqlite3.a, generates the 276 "sqlite3.exe" command-line shell. The "shell.c.in" file is transformed 277 into "shell.c" as part of the build process. 278 279 * **tclsqlite.c** - This file implements the Tcl bindings for SQLite. It 280 is not part of the core SQLite library. But as most of the tests in this 281 repository are written in Tcl, the Tcl language bindings are important. 282 283 * **test*.c** - Files in the src/ folder that begin with "test" go into 284 building the "testfixture.exe" program. The testfixture.exe program is 285 an enhanced Tcl shell. The testfixture.exe program runs scripts in the 286 test/ folder to validate the core SQLite code. The testfixture program 287 (and some other test programs too) is build and run when you type 288 "make test". 289 290 * **ext/misc/json1.c** - This file implements the various JSON functions 291 that are build into SQLite. 292 293There are many other source files. Each has a succinct header comment that 294describes its purpose and role within the larger system. 295 296 297## Contacts 298 299The main SQLite webpage is [http://www.sqlite.org/](http://www.sqlite.org/) 300with geographically distributed backups at 301[http://www2.sqlite.org/](http://www2.sqlite.org) and 302[http://www3.sqlite.org/](http://www3.sqlite.org). 303