1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
|
<!DOCTYPE html>
<html><head>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<link href="sqlite.css" rel="stylesheet">
<title>The SQLite Amalgamation</title>
<!-- path= -->
</head>
<body>
<div class=nosearch>
<a href="index.html">
<img class="logo" src="images/sqlite370_banner.gif" alt="SQLite" border="0">
</a>
<div><!-- IE hack to prevent disappearing logo --></div>
<div class="tagline desktoponly">
Small. Fast. Reliable.<br>Choose any three.
</div>
<div class="menu mainmenu">
<ul>
<li><a href="index.html">Home</a>
<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
<li class='wideonly'><a href='about.html'>About</a>
<li class='desktoponly'><a href="docs.html">Documentation</a>
<li class='desktoponly'><a href="download.html">Download</a>
<li class='wideonly'><a href='copyright.html'>License</a>
<li class='desktoponly'><a href="support.html">Support</a>
<li class='desktoponly'><a href="prosupport.html">Purchase</a>
<li class='search' id='search_menubutton'>
<a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
</ul>
</div>
<div class="menu submenu" id="submenu">
<ul>
<li><a href='about.html'>About</a>
<li><a href='docs.html'>Documentation</a>
<li><a href='download.html'>Download</a>
<li><a href='support.html'>Support</a>
<li><a href='prosupport.html'>Purchase</a>
</ul>
</div>
<div class="searchmenu" id="searchmenu">
<form method="GET" action="search">
<select name="s" id="searchtype">
<option value="d">Search Documentation</option>
<option value="c">Search Changelog</option>
</select>
<input type="text" name="q" id="searchbox" value="">
<input type="submit" value="Go">
</form>
</div>
</div>
<script>
function toggle_div(nm) {
var w = document.getElementById(nm);
if( w.style.display=="block" ){
w.style.display = "none";
}else{
w.style.display = "block";
}
}
function toggle_search() {
var w = document.getElementById("searchmenu");
if( w.style.display=="block" ){
w.style.display = "none";
} else {
w.style.display = "block";
setTimeout(function(){
document.getElementById("searchbox").focus()
}, 30);
}
}
function div_off(nm){document.getElementById(nm).style.display="none";}
window.onbeforeunload = function(e){div_off("submenu");}
/* Disable the Search feature if we are not operating from CGI, since */
/* Search is accomplished using CGI and will not work without it. */
if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
document.getElementById("search_menubutton").style.display = "none";
}
/* Used by the Hide/Show button beside syntax diagrams, to toggle the */
function hideorshow(btn,obj){
var x = document.getElementById(obj);
var b = document.getElementById(btn);
if( x.style.display!='none' ){
x.style.display = 'none';
b.innerHTML='show';
}else{
x.style.display = '';
b.innerHTML='hide';
}
return false;
}
var antiRobot = 0;
function antiRobotGo(){
if( antiRobot!=3 ) return;
antiRobot = 7;
var j = document.getElementById("mtimelink");
if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
}
function antiRobotDefense(){
document.body.onmousedown=function(){
antiRobot |= 2;
antiRobotGo();
document.body.onmousedown=null;
}
document.body.onmousemove=function(){
antiRobot |= 2;
antiRobotGo();
document.body.onmousemove=null;
}
setTimeout(function(){
antiRobot |= 1;
antiRobotGo();
}, 100)
antiRobotGo();
}
antiRobotDefense();
</script>
<div class=fancy>
<div class=nosearch>
<div class="fancy_title">
The SQLite Amalgamation
</div>
</div>
<h1 id="executive_summary"><span>1. </span>Executive Summary</h1>
<p>Over 100 separate source files are concatenated into a
single large file of C-code named "sqlite3.c" and
referred to as "the amalgamation". The amalgamation
contains everything an application needs to embed SQLite.
</p><p>Combining all the code for SQLite into one big file makes SQLite
easier to deploy — there is just one file to keep track of.
And because all code is in
a single translation unit, compilers can do
better inter-procedure and inlining optimization
resulting in machine code that is between 5% and 10% faster.
</p><h1 id="the_sqlite_amalgamation"><span>2. </span>The SQLite Amalgamation</h1>
<p>The SQLite library consists of 111 files of C code
(as of <a href="releaselog/3_37_0.html">Version 3.37.0</a> - 2021-11-27)
in the core with 22 additional files that
implement certain commonly used extensions.
Of the 133
main source files, about 75% are C code and about 25% are C header files.
Most of these are "source" files in the sense that they are stored
in the <a href="https://www.sqlite.org/src">SQLite version control system</a>
and are edited manually in an ordinary text editor.
But some of the C-language files are generated using scripts
or auxiliary programs. For example, the
<a href="https://www.sqlite.org/src/artifact?ci=trunk&filename=src/parse.y">parse.y</a>
file contains an LALR(1) grammar of the SQL language which is compiled,
by the <a href="lemon.html">Lemon parser generator</a>, to produce a parser contained in the file
"parse.c" accompanied by token identifiers in "parse.h".
</p>
<p>The makefiles for SQLite have an "sqlite3.c" target for building the
amalgamation, to contain all C code for the core SQLite library and the
<a href="fts3.html">FTS3</a>, <a href="fts5.html">FTS5</a>, <a href="rtree.html">RTREE</a>, <a href="dbstat.html">DBSTAT</a>, <a href="json1.html">JSON1</a>,
<a href="rbu.html">RBU</a> and <a href="sessionintro.html">SESSION</a>
extensions.
This file contains about 238K lines of code
(or 145K if you omit blank lines and comments) and is over 8.4 megabytes
in size (as of 2021-12-29).
</p><p>Though the various extensions are included in the
"sqlite3.c" amalgamation file, they are disabled using #ifdef statements.
Activate the extensions using <a href="compile.html">compile-time options</a> like:
</p><ul>
<li> <a href="compile.html#enable_fts3">-DSQLITE_ENABLE_FTS3</a>
</li><li> <a href="compile.html#enable_fts5">-DSQLITE_ENABLE_FTS5</a>
</li><li> <a href="compile.html#enable_rtree">-DSQLITE_ENABLE_RTREE</a>
</li><li> <a href="compile.html#enable_dbstat_vtab">-DSQLITE_ENABLE_DBSTAT_VTAB</a>
</li><li> <a href="compile.html#enable_rbu">-DSQLITE_ENABLE_RBU</a>
</li><li> <a href="compile.html#enable_session">-DSQLITE_ENABLE_SESSION</a>
</li></ul>
<p>The amalgamation contains everything you need to integrate SQLite
into a larger project. Just copy the amalgamation into your source
directory and compile it along with the other C code files in your project.
(A <a href="howtocompile.html">more detailed discussion</a> of the compilation process is
available.)
You may also want to make use of the "sqlite3.h" header file that
defines the programming API for SQLite.
The sqlite3.h header file is available separately.
The sqlite3.h file is also contained within the amalgamation, in
the first few thousand lines. So if you have a copy of
sqlite3.c but cannot seem to locate sqlite3.h, you can always
regenerate the sqlite3.h by copying and pasting from the amalgamation.</p>
<p>In addition to making SQLite easier to incorporate into other
projects, the amalgamation also makes it run faster. Many
compilers are able to do additional optimizations on code when
it is contained with in a single translation unit such as it
is in the amalgamation. We have measured performance improvements
of between 5 and 10% when we use the amalgamation to compile
SQLite rather than individual source files. The downside of this
is that the additional optimizations often take the form of
function inlining which tends to make the size of the resulting
binary image larger.</p>
<a name="amal32k"></a>
<h1 id="the_split_amalgamation"><span>3. </span>The Split Amalgamation</h1>
<p>Developers sometimes experience trouble debugging the
quarter-million line amalgamation source file because some debuggers
are only able to handle source code line numbers less than 32,768.
The amalgamation source code runs fine. One just cannot single-step
through it in a debugger.
</p><p>To circumvent this limitation, the amalgamation is also available in
a split form, consisting of files "sqlite3-1.c", "sqlite3-2.c", and
so forth, where each file is less than 32,768 lines in length and
where the concatenation of the files contain all of the code for the
complete amalgamation. Then there is a separate source file named
"sqlite3-all.c" which basically consists of code like this:
</p><div class="codeblock"><pre>#include "sqlite3-1.c"
#include "sqlite3-2.c"
#include "sqlite3-3.c"
#include "sqlite3-4.c"
#include "sqlite3-5.c"
#include "sqlite3-6.c"
#include "sqlite3-7.c"
</pre></div>
<p>Applications using the split amalgamation simply compile against
"sqlite3-all.c" instead of "sqlite3.c". The two files work exactly
the same. But with "sqlite3-all.c", no single source file contains more
than 32,767 lines of code, and so it is more convenient to use some
debuggers. The downside of the split amalgamation is that it consists
of 6 C source code files instead of just 1.
<a name="amalgtarball"></a>
</p><h1 id="download_copies_of_the_precompiled_amalgamation"><span>4. </span>Download Copies Of The Precompiled Amalgamation</h1>
<p>The amalgamation and
the sqlite3.h header file are available on
the <a href="download.html">download page</a> as a file
named sqlite-amalgamation-X.zip
where the X is replaced by the appropriate version number.</p>
<a name="amalgbuild"></a>
<h1 id="building_the_amalgamation_from_canonical_source_code"><span>5. </span>Building The Amalgamation From Canonical Source Code</h1>
<p>To build the amalgamation (either the full amalgamation or the
split amalgamation), first
<a href="getthecode.html">get the canonical source code</a> from one of the three servers.
Then, on both unix-like systems and on Windows systems that have the
free <a href="http://mingw.org/wiki/msys">MinGW</a> development environment
installed, the amalgamation can be built using the
following commands:
</p><div class="codeblock"><pre>sh configure
make sqlite3.c
</pre></div>
<p>To build using Microsoft Visual C++, run this command:
</p><div class="codeblock"><pre>nmake /f makefile.msc sqlite3.c
</pre></div>
<p>In both cases, the split amalgamation can be obtained by
substituting "sqlite3-all.c" for "sqlite3.c" as the make target.
</p><h2 id="dependencies"><span>5.1. </span>Dependencies</h2>
<p>The build process makes extensive use of the
<a href="http://www.tcl-lang.org/">Tcl</a> scripting language. You will need to have a
copy of TCL installed in order for the make targets above to work.
Easy-to-use installers can be obtained from <a href="http://www.tcl-lang.org/">http://www.tcl-lang.org/</a>.
Many unix workstations have Tcl installed by default.
</p><h2 id="see_also"><span>5.2. </span>See Also</h2>
<p>Additional notes on compiling SQLite can be found on the
<a href="howtocompile.html">How To Compile SQLite</a> page.
</p>
|
