@@ -120,3 +120,309 @@ LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
120120ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
121121(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
122122SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
123+
124+ # Begin SQLite README.md
125+
126+ <h1 align =" center " >SQLite Source Repository</h1 >
127+
128+ This repository contains the complete source code for the
129+ [ SQLite database engine] ( https://sqlite.org/ ) . Some test scripts
130+ are also included. However, many other test scripts
131+ and most of the documentation are managed separately.
132+
133+ SQLite [ does not use Git] ( https://sqlite.org/whynotgit.html ) .
134+ If you are reading this on GitHub, then you are looking at an
135+ unofficial mirror. See < https://sqlite.org/src > for the official
136+ repository.
137+
138+ ## Obtaining The Code
139+
140+ SQLite sources are managed using the
141+ [ Fossil] ( https://www.fossil-scm.org/ ) , a distributed version control system
142+ that was specifically designed to support SQLite development.
143+ If you do not want to use Fossil, you can download tarballs or ZIP
144+ archives or [ SQLite archives] ( https://sqlite.org/cli.html#sqlar ) as follows:
145+
146+ * Lastest trunk check-in as
147+ [ Tarball] ( https://www.sqlite.org/src/tarball/sqlite.tar.gz ) ,
148+ [ ZIP-archive] ( https://www.sqlite.org/src/zip/sqlite.zip ) , or
149+ [ SQLite-archive] ( https://www.sqlite.org/src/sqlar/sqlite.sqlar ) .
150+
151+ * Latest release as
152+ [ Tarball] ( https://www.sqlite.org/src/tarball/sqlite.tar.gz?r=release ) ,
153+ [ ZIP-archive] ( https://www.sqlite.org/src/zip/sqlite.zip?r=release ) , or
154+ [ SQLite-archive] ( https://www.sqlite.org/src/sqlar/sqlite.sqlar?r=release ) .
155+
156+ * For other check-ins, substitute an appropriate branch name or
157+ tag or hash prefix for "release" in the URLs of the previous
158+ bullet. Or browse the [ timeline] ( https://www.sqlite.org/src/timeline )
159+ to locate the check-in desired, click on its information page link,
160+ then click on the "Tarball" or "ZIP Archive" links on the information
161+ page.
162+
163+ If you do want to use Fossil to check out the source tree,
164+ first install Fossil version 2.0 or later.
165+ (Source tarballs and precompiled binaries available
166+ [ here] ( https://www.fossil-scm.org/fossil/uv/download.html ) . Fossil is
167+ a stand-alone program. To install, simply download or build the single
168+ executable file and put that file someplace on your $PATH.)
169+ Then run commands like this:
170+
171+ mkdir ~/sqlite
172+ cd ~/sqlite
173+ fossil clone https://www.sqlite.org/src sqlite.fossil
174+ fossil open sqlite.fossil
175+
176+ After setting up a repository using the steps above, you can always
177+ update to the lastest version using:
178+
179+ fossil update trunk ;# latest trunk check-in
180+ fossil update release ;# latest official release
181+
182+ Or type "fossil ui" to get a web-based user interface.
183+
184+ ## Compiling
185+
186+ First create a directory in which to place
187+ the build products. It is recommended, but not required, that the
188+ build directory be separate from the source directory. Cd into the
189+ build directory and then from the build directory run the configure
190+ script found at the root of the source tree. Then run "make".
191+
192+ For example:
193+
194+ tar xzf sqlite.tar.gz ;# Unpack the source tree into "sqlite"
195+ mkdir bld ;# Build will occur in a sibling directory
196+ cd bld ;# Change to the build directory
197+ ../sqlite/configure ;# Run the configure script
198+ make ;# Run the makefile.
199+ make sqlite3.c ;# Build the "amalgamation" source file
200+ make test ;# Run some tests (requires Tcl)
201+
202+ See the makefile for additional targets.
203+
204+ The configure script uses autoconf 2.61 and libtool. If the configure
205+ script does not work out for you, there is a generic makefile named
206+ "Makefile.linux-gcc" in the top directory of the source tree that you
207+ can copy and edit to suit your needs. Comments on the generic makefile
208+ show what changes are needed.
209+
210+ ## Using MSVC
211+
212+ On Windows, all applicable build products can be compiled with MSVC.
213+ First open the command prompt window associated with the desired compiler
214+ version (e.g. "Developer Command Prompt for VS2013"). Next, use NMAKE
215+ with the provided "Makefile.msc" to build one of the supported targets.
216+
217+ For example:
218+
219+ mkdir bld
220+ cd bld
221+ nmake /f Makefile.msc TOP=..\sqlite
222+ nmake /f Makefile.msc sqlite3.c TOP=..\sqlite
223+ nmake /f Makefile.msc sqlite3.dll TOP=..\sqlite
224+ nmake /f Makefile.msc sqlite3.exe TOP=..\sqlite
225+ nmake /f Makefile.msc test TOP=..\sqlite
226+
227+ There are several build options that can be set via the NMAKE command
228+ line. For example, to build for WinRT, simply add "FOR_WINRT=1" argument
229+ to the "sqlite3.dll" command line above. When debugging into the SQLite
230+ code, adding the "DEBUG=1" argument to one of the above command lines is
231+ recommended.
232+
233+ SQLite does not require [ Tcl] ( http://www.tcl.tk/ ) to run, but a Tcl installation
234+ is required by the makefiles (including those for MSVC). SQLite contains
235+ a lot of generated code and Tcl is used to do much of that code generation.
236+
237+ ## Source Code Tour
238+
239+ Most of the core source files are in the ** src/** subdirectory. The
240+ ** src/** folder also contains files used to build the "testfixture" test
241+ harness. The names of the source files used by "testfixture" all begin
242+ with "test".
243+ The ** src/** also contains the "shell.c" file
244+ which is the main program for the "sqlite3.exe"
245+ [ command-line shell] ( https://sqlite.org/cli.html ) and
246+ the "tclsqlite.c" file which implements the
247+ [ Tcl bindings] ( https://sqlite.org/tclsqlite.html ) for SQLite.
248+ (Historical note: SQLite began as a Tcl
249+ extension and only later escaped to the wild as an independent library.)
250+
251+ Test scripts and programs are found in the ** test/** subdirectory.
252+ Addtional test code is found in other source repositories.
253+ See [ How SQLite Is Tested] ( http://www.sqlite.org/testing.html ) for
254+ additional information.
255+
256+ The ** ext/** subdirectory contains code for extensions. The
257+ Full-text search engine is in ** ext/fts3** . The R-Tree engine is in
258+ ** ext/rtree** . The ** ext/misc** subdirectory contains a number of
259+ smaller, single-file extensions, such as a REGEXP operator.
260+
261+ The ** tool/** subdirectory contains various scripts and programs used
262+ for building generated source code files or for testing or for generating
263+ accessory programs such as "sqlite3_analyzer(.exe)".
264+
265+ ### Generated Source Code Files
266+
267+ Several of the C-language source files used by SQLite are generated from
268+ other sources rather than being typed in manually by a programmer. This
269+ section will summarize those automatically-generated files. To create all
270+ of the automatically-generated files, simply run "make target_ ; source".
271+ The "target_ ; source" make target will create a subdirectory "tsrc/" and
272+ fill it with all the source files needed to build SQLite, both
273+ manually-edited files and automatically-generated files.
274+
275+ The SQLite interface is defined by the ** sqlite3.h** header file, which is
276+ generated from src/sqlite.h.in, ./manifest.uuid, and ./VERSION. The
277+ [ Tcl script] ( http://www.tcl.tk ) at tool/mksqlite3h.tcl does the conversion.
278+ The manifest.uuid file contains the SHA3 hash of the particular check-in
279+ and is used to generate the SQLITE\_ SOURCE\_ ID macro. The VERSION file
280+ contains the current SQLite version number. The sqlite3.h header is really
281+ just a copy of src/sqlite.h.in with the source-id and version number inserted
282+ at just the right spots. Note that comment text in the sqlite3.h file is
283+ used to generate much of the SQLite API documentation. The Tcl scripts
284+ used to generate that documentation are in a separate source repository.
285+
286+ The SQL language parser is ** parse.c** which is generate from a grammar in
287+ the src/parse.y file. The conversion of "parse.y" into "parse.c" is done
288+ by the [ lemon] ( ./doc/lemon.html ) LALR(1) parser generator. The source code
289+ for lemon is at tool/lemon.c. Lemon uses the tool/lempar.c file as a
290+ template for generating its parser.
291+
292+ Lemon also generates the ** parse.h** header file, at the same time it
293+ generates parse.c. But the parse.h header file is
294+ modified further (to add additional symbols) using the ./addopcodes.tcl
295+ Tcl script.
296+
297+ The ** opcodes.h** header file contains macros that define the numbers
298+ corresponding to opcodes in the "VDBE" virtual machine. The opcodes.h
299+ file is generated by the scanning the src/vdbe.c source file. The
300+ Tcl script at ./mkopcodeh.tcl does this scan and generates opcodes.h.
301+ A second Tcl script, ./mkopcodec.tcl, then scans opcodes.h to generate
302+ the ** opcodes.c** source file, which contains a reverse mapping from
303+ opcode-number to opcode-name that is used for EXPLAIN output.
304+
305+ The ** keywordhash.h** header file contains the definition of a hash table
306+ that maps SQL language keywords (ex: "CREATE", "SELECT", "INDEX", etc.) into
307+ the numeric codes used by the parse.c parser. The keywordhash.h file is
308+ generated by a C-language program at tool mkkeywordhash.c.
309+
310+ The ** pragma.h** header file contains various definitions used to parse
311+ and implement the PRAGMA statements. The header is generated by a
312+ script ** tool/mkpragmatab.tcl** . If you want to add a new PRAGMA, edit
313+ the ** tool/mkpragmatab.tcl** file to insert the information needed by the
314+ parser for your new PRAGMA, then run the script to regenerate the
315+ ** pragma.h** header file.
316+
317+ ### The Amalgamation
318+
319+ All of the individual C source code and header files (both manually-edited
320+ and automatically-generated) can be combined into a single big source file
321+ ** sqlite3.c** called "the amalgamation". The amalgamation is the recommended
322+ way of using SQLite in a larger application. Combining all individual
323+ source code files into a single big source code file allows the C compiler
324+ to perform more cross-procedure analysis and generate better code. SQLite
325+ runs about 5% faster when compiled from the amalgamation versus when compiled
326+ from individual source files.
327+
328+ The amalgamation is generated from the tool/mksqlite3c.tcl Tcl script.
329+ First, all of the individual source files must be gathered into the tsrc/
330+ subdirectory (using the equivalent of "make target_source") then the
331+ tool/mksqlite3c.tcl script is run to copy them all together in just the
332+ right order while resolving internal "#include" references.
333+
334+ The amalgamation source file is more than 200K lines long. Some symbolic
335+ debuggers (most notably MSVC) are unable to deal with files longer than 64K
336+ lines. To work around this, a separate Tcl script, tool/split-sqlite3c.tcl,
337+ can be run on the amalgamation to break it up into a single small C file
338+ called ** sqlite3-all.c** that does #include on about seven other files
339+ named ** sqlite3-1.c** , ** sqlite3-2.c** , ..., ** sqlite3-7.c** . In this way,
340+ all of the source code is contained within a single translation unit so
341+ that the compiler can do extra cross-procedure optimization, but no
342+ individual source file exceeds 32K lines in length.
343+
344+ ## How It All Fits Together
345+
346+ SQLite is modular in design.
347+ See the [ architectural description] ( http://www.sqlite.org/arch.html )
348+ for details. Other documents that are useful in
349+ (helping to understand how SQLite works include the
350+ [ file format] ( http://www.sqlite.org/fileformat2.html ) description,
351+ the [ virtual machine] ( http://www.sqlite.org/opcode.html ) that runs
352+ prepared statements, the description of
353+ [ how transactions work] ( http://www.sqlite.org/atomiccommit.html ) , and
354+ the [ overview of the query planner] ( http://www.sqlite.org/optoverview.html ) .
355+
356+ Years of effort have gone into optimizating SQLite, both
357+ for small size and high performance. And optimizations tend to result in
358+ complex code. So there is a lot of complexity in the current SQLite
359+ implementation. It will not be the easiest library in the world to hack.
360+
361+ Key files:
362+
363+ * ** sqlite.h.in** - This file defines the public interface to the SQLite
364+ library. Readers will need to be familiar with this interface before
365+ trying to understand how the library works internally.
366+
367+ * ** sqliteInt.h** - this header file defines many of the data objects
368+ used internally by SQLite. In addition to "sqliteInt.h", some
369+ subsystems have their own header files.
370+
371+ * ** parse.y** - This file describes the LALR(1) grammar that SQLite uses
372+ to parse SQL statements, and the actions that are taken at each step
373+ in the parsing process.
374+
375+ * ** vdbe.c** - This file implements the virtual machine that runs
376+ prepared statements. There are various helper files whose names
377+ begin with "vdbe". The VDBE has access to the vdbeInt.h header file
378+ which defines internal data objects. The rest of SQLite interacts
379+ with the VDBE through an interface defined by vdbe.h.
380+
381+ * ** where.c** - This file (together with its helper files named
382+ by "where* .c") analyzes the WHERE clause and generates
383+ virtual machine code to run queries efficiently. This file is
384+ sometimes called the "query optimizer". It has its own private
385+ header file, whereInt.h, that defines data objects used internally.
386+
387+ * ** btree.c** - This file contains the implementation of the B-Tree
388+ storage engine used by SQLite. The interface to the rest of the system
389+ is defined by "btree.h". The "btreeInt.h" header defines objects
390+ used internally by btree.c and not published to the rest of the system.
391+
392+ * ** pager.c** - This file contains the "pager" implementation, the
393+ module that implements transactions. The "pager.h" header file
394+ defines the interface between pager.c and the rest of the system.
395+
396+ * ** os_unix.c** and ** os_win.c** - These two files implement the interface
397+ between SQLite and the underlying operating system using the run-time
398+ pluggable VFS interface.
399+
400+ * ** shell.c.in** - This file is not part of the core SQLite library. This
401+ is the file that, when linked against sqlite3.a, generates the
402+ "sqlite3.exe" command-line shell. The "shell.c.in" file is transformed
403+ into "shell.c" as part of the build process.
404+
405+ * ** tclsqlite.c** - This file implements the Tcl bindings for SQLite. It
406+ is not part of the core SQLite library. But as most of the tests in this
407+ repository are written in Tcl, the Tcl language bindings are important.
408+
409+ * ** test* .c** - Files in the src/ folder that begin with "test" go into
410+ building the "testfixture.exe" program. The testfixture.exe program is
411+ an enhanced Tcl shell. The testfixture.exe program runs scripts in the
412+ test/ folder to validate the core SQLite code. The testfixture program
413+ (and some other test programs too) is build and run when you type
414+ "make test".
415+
416+ * ** ext/misc/json1.c** - This file implements the various JSON functions
417+ that are build into SQLite.
418+
419+ There are many other source files. Each has a succinct header comment that
420+ describes its purpose and role within the larger system.
421+
422+
423+ ## Contacts
424+
425+ The main SQLite webpage is [ http://www.sqlite.org/ ] ( http://www.sqlite.org/ )
426+ with geographically distributed backups at
427+ [ http://www2.sqlite.org/ ] ( http://www2.sqlite.org ) and
428+ [ http://www3.sqlite.org/ ] ( http://www3.sqlite.org ) .
0 commit comments