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