How To Compile SQLite (2024)

Overview

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 compilingSQLite. That would be difficult since each development situationis different.Rather, this article describes and illustrates the principles behind thecompilation of SQLite. Typical compilation commands are provided as exampleswith the expectation that application developers can use these examplesas guidance for developing their own custom compilation procedures.In other words, this article provides ideas and insights, not turnkeysolutions.

SQLite is built from over one hundred files of C code and scriptspread across multiple directories. The implementation of SQLite is pureANSI-C, but many of the C-language source code files are eithergenerated or transformed by auxiliary C programs and AWK, SED, and TCLscripts prior to being incorporated into the finished SQLite library.Building the necessary C programs and transforming and/or creating theC-language source code for SQLite is a complex process.

To simplify matters, SQLite is also available as a pre-packagedamalgamation source code file: sqlite3.c. The amalgamation isa single file of ANSI-C code that implements the entire SQLite library.The amalgamation is much easier to deal with. Everything is containedwithin a single code file, so it is easy to drop into the source treeof a larger C or C++ program. All the code generation and transformationsteps have already been carried out so there are no auxiliary C programsto configure and compile and no scripts to run. And, because the entirelibrary is contained in a single translation unit, compilers are able todo more advanced optimizations resulting in a 5% to 10% performanceimprovement. 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 certainlypossible, but it is not recommended. For some specialized applications, itmight be necessary to modify the build process in ways that cannot be doneusing just the prebuilt amalgamation source file downloaded from the website.For those situations, it is recommended that a customized amalgamation bebuilt (as described below)and used. In other words, even if a project requires building SQLitebeginning with individual source files, it is still recommended that anamalgamation source file be used as an intermediate step.

A build of the command-line interface requires three sourcefiles:

• sqlite3.c: The SQLite amalgamation source file
• sqlite3.h: The header files that accompanies sqlite3.c anddefines the C-language interfaces to SQLite.
• shell.c: The command-line interface program itself.This is the C source code file that contains the definition ofthe main() routine and the loop that prompts for user inputand passes that input into the SQLite database engine for processing.

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

To build the CLI, simply put these three files in the same directoryand compile them together. Using MSVC:

cl shell.c sqlite3.c -Fesqlite3.exe

On Unix systems (or on Windows using cygwin or mingw+msys)the command typically looks something like this:

gcc shell.c sqlite3.c -lpthread -ldl -lm -o sqlite3

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

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

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

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

One might want to provide other compile-time options such as

• -DSQLITE_ENABLE_FTS4 or -DSQLITE_ENABLE_FTS5 for full-text search,
• -DSQLITE_ENABLE_RTREE for the R*Tree search engine extension,
• -DSQLITE_ENABLE_DBSTAT_VTAB for the dbstat virtual table, or
• -DSQLITE_ENABLE_MATH_FUNCTIONS for extended math functions.

In order to see extra commentary in EXPLAIN listings, add the-DSQLITE_ENABLE_EXPLAIN_COMMENTS option. Add -DHAVE_READLINE andthe -lreadline and -lncurses libraries to get command-line editingsupport. One might also want to specify some compiler optimizationswitches. (The precompiled CLI available for download from the SQLitewebsite uses "-Os".) There are countless possible variations here. Acommand to compile a full-featured shell might look something likethis:

gcc -Os -I. -DSQLITE_THREADSAFE=0 -DSQLITE_ENABLE_FTS4 \ -DSQLITE_ENABLE_FTS5 -DSQLITE_ENABLE_JSON1 \ -DSQLITE_ENABLE_RTREE -DSQLITE_ENABLE_EXPLAIN_COMMENTS \ -DHAVE_READLINE \ shell.c sqlite3.c -ldl -lm -lreadline -lncurses -o sqlite3

The key point is this: Building the CLI consists of compilingtogether two C-language files. The shell.c file contains thedefinition of the entry point and the user input loop and theSQLite amalgamation sqlite3.c contains the complete implementationof the SQLite library.

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

To generate a TCL-loadable library for SQLite on Linux, the followingcommand will suffice:

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

Building shared libraries for Mac OS X and Windows is not nearly so simple,unfortunately. For those platforms it is best to use the configure scriptand 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 forSQLite includes a main() procedure that initializes a TCL interpreterand enters a command-line loop when it is compiled with -DTCLSH=1. Thecommand above works on both Linux and Mac OS X, though one may need to adjustthe library options depending on the platform and which version of TCL oneis linking against.

The versions of the SQLite amalgamation that are supplied on thedownload page are normally adequate for most users. However, someprojects may want or need to build their own amalgamations. A commonreason for building a custom amalgamation is in order to use certaincompile-time options to customize the SQLite library. Recall thatthe SQLite amalgamation contains a lot of C-code that is generated byauxiliary programs and scripts. Many of the compile-timeoptions effect this generated code and must be supplied to the codegenerators before the amalgamation is assembled. The set ofcompile-time options that must be passed into the code generators canvary from one release of SQLite to the next, but at the time of thiswriting (circa SQLite 3.6.20, 2009-11-04) the set of options that mustbe known by the code generators includes:

• SQLITE_ENABLE_UPDATE_DELETE_LIMIT
• SQLITE_OMIT_ALTERTABLE
• SQLITE_OMIT_ANALYZE
• SQLITE_OMIT_ATTACH
• SQLITE_OMIT_AUTOINCREMENT
• SQLITE_OMIT_CAST
• SQLITE_OMIT_COMPOUND_SELECT
• SQLITE_OMIT_EXPLAIN
• SQLITE_OMIT_FOREIGN_KEY
• SQLITE_OMIT_PRAGMA
• SQLITE_OMIT_REINDEX
• SQLITE_OMIT_SUBQUERY
• SQLITE_OMIT_TEMPDB
• SQLITE_OMIT_TRIGGER
• SQLITE_OMIT_VACUUM
• SQLITE_OMIT_VIEW
• SQLITE_OMIT_VIRTUALTABLE

To build a custom amalgamation, first download the original individualsource files onto a Unix or Unix-like development platform.Be sure to get the original sourcefiles not the "preprocessed source files". One can obtain the completeset of original source files either from the download page or directlyfrom 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 (forexample) "bld". First construct an appropriate Makefile by eitherrunning the configure script at the top of the SQLite source tree, or bymaking 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

Or on Windows with MSVC:

nmake /f Makefile.msc 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 sourcefile that includes the TCL interface.Afterwards, the needed files can be copied into project directories andcompiled according to the procedures outlined above.

To build a DLL of SQLite for use in Windows, first acquire theappropriate amalgamated source code files, sqlite3.c and sqlite3.h.These can eitherbe downloaded from the SQLite websiteor custom generated from sources as shown above.

With source code files in the working directory, a DLLcan be generated using MSVC with the following command:

cl sqlite3.c -link -dll -out:sqlite3.dll

The above command should be run from the MSVC Native Tools CommandPrompt. If you have MSVC installed on your machine, you probablyhave multiple versions of this Command Prompt, for native buildsfor x86 and x64, and possibly also for cross-compiling to ARM.Use the appropriate Command Prompt depending on the desired DLL.

If using the MinGW compiler, the command-line is this:

gcc -shared sqlite3.c -o sqlite3.dll

Note that MinGW generates 32-bit DLLs only. There is a separateMinGW64 project that can be used to generate 64-bit DLLs. Presumablythe command-line syntax is similar.Also note that recent versions of MSVC generate DLLs that will not workon WinXP and earlier versions of Windows. So for maximum compatibilityof your generated DLL, MinGW is recommended. A good rule-of-thumbis to generate 32-bit DLLs using MinGW and 64-bit DLLs using MSVC.

In most cases, you will want to supplement the basic commands above withcompile-time options appropriate for your application. Commonly usedcompile-time options include:

• -Os - Optimize for size.Make the DLL as small as possible.

• -O2 - Optimize for speed. This will make the DLL larger byunrolling loops and inlining functions.

• -DSQLITE_ENABLE_FTS4 -Include the full-text search engine code in SQLite.

• -DSQLITE_ENABLE_RTREE - Include the R-Tree extension.

• -DSQLITE_ENABLE_COLUMN_METADATA -This enables some extra APIs that are required by some common systems,including Ruby-on-Rails.

This page last modified on 2023-10-10 17:29:48 UTC