Debian Codegraph @

www/amalgamation.html

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