*** DRAFT ***
SQLite is written in C. To compile SQLite, you use a C-compiler to convert the C-language source code into binary machine code.
Except it is not quite that simple. The SQLite project makes a distinction between "canonical source code" and the "amalgamation". Here is what the SQLite developers mean by those terms:
Canonical Source Code or Canonical Sources → The canonical source code is the urtext for SQLite. These are the source code files that are typed in and maintained by the SQLite developers and that are stored under the source code management system. If you pull a copy of the SQLite source code from its Fossil repository (https://sqlite.org/src) or from the GitHub mirror (https://github.com/sqlite/sqlite), you get the canonical source code.
Amalgamation → As part of the build process for SQLite, the canonical source code files get transformed and concatenated together into a few big C-language code files:
These "amalgamation" source files are also C-code. Combining lots of smaller code files together into a few big C-code files makes SQLite easier to compile. And it helps the C-compiler optimize the code so that it runs faster.
If you want to compile SQLite yourself, for use in your own projects, should you start with the canonical source code or with the amalgamation?
The following diagram illustrates the complete SQLite build process:
The complete build process starts with the canonical source code files on the left side of the diagram. There are between 100 and 200 separate canonical source files (depending on the SQLite version). Some of those canonical source files get transformed by preprocessor programs to generate "intermediate source files". One example of a preprocessor is the Lemon parser generator program. One of the canonical source code files is parse.y which is an LALR(1) grammar for the SQL dialect understood by SQLite. Lemon converts that grammer into C-code that implements a pushdown automaton that will parse SQL text into an abstract syntax tree. There are many other examples of programs and scripts in SQLite that transform the code that the SQLite developers edit into code that can be understood by C compilers. Not all canonical source code files are preprocessed, but a fair number of them are.
After preprocessing, there are some scripts that gather together the many intermediate source files and the remaining canonical source files and concatentates them together to generate the "amalgamation". Often when we say "the amalgamation" we mean just the file "sqlite3.c" which contains the bulk of the SQLite source code. But the corresponding header file "sqlite3.h" is also constructed from other files. And the source code to the SQLite command-line shell is an amalgamation contained in "shell.c".
The amalgamation files can then be processed by any ordinary C compiler to render the final build products, shown on the right side of the diagram. (The diagram shows build product filenames as they might appear on Windows. Substitute whatever alternative names are appropriate for your system.)
To compile SQLite from canonical sources, you download a tarball or ZIP archive of the canonical source tree, unpack that archive, then run either "./configure && make" on unix or "nmake /f Makefile.msc" on Windows. More details available at the following:
With each release of SQLite, the developers make available pre-built copies of the SQLite amalgamation files that you can get from the Download Page. Look for files named "sqlite-amalgamation-NNNNNNN.zip" and "sqlite-autoconf-NNNNNNN.tar.gz". The first is just the amalgamation source files. The second also includes a "configure" script and Makefile.
Fewer Files To Worry With
You can embedded the amalgamation files you need in your own source tree, and compile them using your own Makefile. You don't really need a separate "configure" script or Makefile. Add the "sqlite3.c" and "sqlite3.h" files into your own source tree, and then they will always be there without creating a new dependency. When you want to upgrade, just download the latest version and replace the ones in your own source tree.
Less To Download
The amalgamation archives are less than 1/4th the size of the complete SQLite source tree. So there is less to download.
You Will End Up Using The Amalgamation Regardless
If you build from canonical sources, the Makefile first builds the amalgamation and then compiles the amalgamation into binary machine code. Why not just skip that first step and go right to compiling the amalgamation directly?
You Know That The Amalgamation You Are Using Has Been Testing And Vetted By The SQLite Developers
If you pull down the pre-build amalgamation files, you can have confidence that those exact source files have been run through the SQLite developers rigorous testing process. You don't have to worry that you somehow broke something as you were compiling the canonical sources into the amalgamation.
Access To More Compile-Time Options
SQLite support many, many compile-time options, some of which work with the amalgamation, but some of which do not. Depending on what compile-time options you want to use, you may need to build from canonical sources.
Access To Historical And Unreleased Versions Of SQLite
The amalgamation source code is normally only available for the latest released version of SQLite. If you want an historical version of SQLite, or if you want to try out the latest unreleased trunk version of SQLite because it has some new feature that you like or because you just want to contribute back by helping with pre-release testing, then you must compile from canonical source.
Easier To Customize The Code
If you are making your own custom enhancements or modifications to SQLite, then you should probably work with the canonical sources. The amalgamation is designed to be friendly to C-compilers, not human programmers. You can, in theory, make custom modifications directly to the amalgamation source code, but you will have an easier time of it if you use the canonical source files.
The decision of whether to build SQLite from the amalgamation or from canonical sources depends on your specific circumstances. Review the advantages and disadvantages to each approach outlined in the paragraphs above and decide for yourself.
This page last modified on 2025-01-01 21:26:31 UTC
*** DRAFT ***