*** DRAFT ***
About Sitemap Documentation Download License News Support

How To Compile SQLite

SQLite is ANSI-C source code. It must be compiled into machine code before it is useful. This article is a guide to the various ways of compiling SQLite.

This article does not contain a step-by-step recipe for compiling SQLite. That would be difficult since each development situation is different. Rather, this article describes and illustrates the principals behind the compilation of SQLite. Typical compilation commands are provided as examples with the expectation that application developers can use these examples as guidance for developing their own custom compilation procedures. In other words, this article provides ideas and insights, not turnkey solutions.

Amalgamation Versus Individual Source Files

SQLite is built from literally hundreds of files of C code and script spread across multiple directories. The implementation of SQLite is pure ANSI-C, but many of the C-language source code files are either either generated or transformed by auxiliary C programs and AWK, SED, and TCL scripts prior to being incorporated into the finished SQLite library. Building the necessary C programs and transforming and/or creating the C-language source code for SQLite is a complex process.

To simplify matters, SQLite is also available as a pre-packaged amalgamation source code file: sqlite3.c. The amalgamation is a single file of ANSI-C code that implements the entire SQLite library. The amalgamation is much easier to deal with. Everything is contained within a single code files, so it is easy to drop into the source tree of a larger C or C++ program. All the code generation and transformation steps have already been carried out so there are no auxiliary C programs to configure and compile and no scripts to run. And, because the entire library is contained in a single translation unit, compilers are able to do more advanced optimizations resulting in a 5% to 10% performance improvement. For these reasons, the amalgamation source file ("sqlite3.c") is recommended for all applications.

The use of the amalgamation is recommended for all applications.

Building SQLite directly from individual source code files is certainly possible, but it is not recommended. For some specialized applications, it might be necessary to modify the build process in ways that cannot be done using just the prebuilt amalgamation source file downloaded from the website. For those situations, it is recommended that a customized amalgamation be built (as described below) and used. In other words, even if a project requires building SQLite beginning with individual source files, it is still recommended that an amalgamation source file be used as an intermediate step.

Compiling The Command-Line Interface

A build of the command-line interface requires three source files:

All three of the above source files are contained in the amalgamation tarball available on the download page.

To build the CLI, simply put these three files in the same directory and compile them together. The command to compile C programs varies from one machine to the next but on unix systems typically looks something like this:

gcc shell.c sqlite3.c -lpthread -ldl

The pthreads library is needed to make SQLite threadsafe. But since the CLI is single threaded, we could instruct SQLite to build in a non-threadsafe mode and thereby omit the pthreads library:

gcc -DSQLITE_THREADSAFE=0 shell.c sqlite3.c -ldl

The -ldl library is needed to support dynamic loading, the sqlite3_load_extension() interface and the load_extension() SQL function. If these features are not required, then they can be omitted using SQLITE_OMIT_LOAD_EXTENSION compile-time option:

gcc -DSQLITE_THREADSAFE=0 -DSQLITE_OMIT_LOAD_EXTENSION shell.c sqlite3.c

One might want to provide other compile-time options such as SQLITE_ENABLE_FTS3 for full-text search or SQLITE_ENABLE_RTREE for the R*Tree search engine extension. And one would normally to specify some compiler optimization switches too. (The precompiled CLI available for download from the SQLite website uses "-Os".) There are countless possible variations here.

The key point is this: Building the CLI consists of compiling together two C-language files. The shell.c file contains the definition of the entry point and the user input loop and the SQLite amalgamation sqlite3.c contains the complete implementation of the SQLite library.

Compiling The TCL Interface

The TCL interface for SQLite is a small module that is added into the regular amalgamation. The result is a new amalgamated source file called "tclsqlite3.c". This single source file is all that is needed to generate a shared library that can be loaded into a standard tclsh or wish using the TCL load command, or to generate a standalone tclsh that comes with SQLite built in. A copy of the tcl amalgamation is included on the download page as a file in the TEA tarball.

To generate a TCL-loadable library for SQLite on linux, the following command will suffice:

gcc -o libtclsqlite3.so -shared tclsqlite3.c -lpthread -ldl -ltcl

Building shared libraries for Mac OSX and Windows is not nearly so simple, unfortunately. For those platforms it is best to use the configure script and makefile that is included with the TEA tarball.

To generate a standalone tclsh that is statically linked with SQLite, use this compiler invocation:

gcc -DTCLSH=1 tclsqlite3.c -ltcl -lpthread -ldl -lz -lm

The trick here is the -DTCLSH=1 option. The TCL interface module for SQLite includes a main() procedure that initializes a TCL interpreter and enters a command-line loop when it is compiled with -DTCLSH=1. The command above works on both Linux and Mac OSX, though one may need to adjust the library options depending on the platform and which version of TCL one is linking against.

Building The Amalgamation

The versions of the SQLite amalgamation that are supplied on the download page are normally adequate for most users. However, some projects may want or need to build their own amalgamations. A common reason for building a custom amalgamation is in order to use certain compile-time options to customize the SQLite library. Recall that the SQLite amalgamation contains a lot of C-code that is generated by auxiliary programs and scripts. Many of the compile-time options effect this generated code and must be supplied to the code generators before the amalgamation is assembled. The set of compile-time options that must be passed into the code generators can vary from one release of SQLite to the next, but at the time of this writing (circa SQLite 3.6.20, 2009-11-04) the set of options that must be known by the code generators includes:

To build a custom amalgamation, first download the original individual source files onto a unix or unix-like development platform. (Any linux or mac osx machine will suffice. Windows will work if loaded with cygwin.) Be sure to get the original source files not the "preprocessed source files". One can obtain the complete set of original source files either from the download page or directly from the configuration management system.

Suppose the SQLite source tree is stored in a directory named "sqlite". Plan to construct the amalgamation in a parallel directory named (for example) "bld". First construct an appropriate Makefile by either running the configure script at the top of the SQLite source tree, or by making a copy of one of the template Makefiles at the top of the source tree. Then hand edit this Makefile to include the desired compile-time options. Finally run:

make sqlite3.c

The "sqlite3.c" make target will automatically construct the regular "sqlite3.c" amalgamation source file, its header file "sqlite3.h", and the "tclsqlite3.c" amalgamation source file that includes the TCL interface. Afterwards, the needed files can be copied into project directories and compiled according to the procedures outlined above.

*** DRAFT ***