Debian Codegraph @

www/amalg-v-canon.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 Amalgamation Versus Canonical Sources</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 Amalgamation Versus Canonical Sources
122 </div>
123 </div>
124
125
126
127
128 <h1 id="which_code_base_should_i_use_to_build_sqlite_"><span>1. </span>Which Code Base Should I Use To Build SQLite?</h1>
129
130 <p>
131 SQLite is written in C. To compile SQLite, you use a C-compiler to
132 convert the C-language source code into binary machine code.
133
134 </p><p>
135 Except it is not quite that simple. The SQLite project makes a
136 distinction between "canonical source code" and the "amalgamation".
137 Here is what the SQLite developers mean by those terms:
138
139 <a name="canon"></a>
140
141 </p><h2 id="canonical_sources_vs_amalgamation"><span>1.1. </span>Canonical Sources vs. Amalgamation</h2>
142
143 <ul>
144 <li><p><b>Canonical Source Code</b> or <b>Canonical Sources &rarr;</b>
145 The canonical source code is the urtext for SQLite.
146 These are the source code files that are typed in and
147 maintained by the SQLite developers and that are stored under
148 the source code management system. If you
149 pull a copy of the SQLite source code from its Fossil repository
150 (<a href="https://sqlite.org/src">https://sqlite.org/src</a>) or from the GitHub mirror
151 (<a href="https://github.com/sqlite/sqlite">https://github.com/sqlite/sqlite</a>), you get the canonical
152 source code.
153
154 </p></li><li><p><b>Amalgamation &rarr;</b>
155 As part of the build process for SQLite, the canonical source code
156 files get transformed and concatenated together into a few big
157 C-language code files:
158 </p><ul>
159 <li> sqlite3.c
160 </li><li> sqlite3.h
161 </li><li> shell.c
162 </li></ul>
163 <p>These "<a href="amalgamation.html">amalgamation</a>" source files are also C-code. Combining
164 lots of smaller code files together into a few big C-code files
165 makes SQLite easier to compile. And it helps the C-compiler optimize
166 the code so that it runs faster.
167 </p></li></ul>
168
169 <p>
170 If you want to compile SQLite yourself, for use in your own projects,
171 should you start with the canonical source code or with the amalgamation?
172
173 </p><h1 id="background"><span>2. </span>Background</h1>
174
175 <p>
176 The following diagram illustrates the complete SQLite build process:
177 </p>
178
179 <center><div style="max-width:857px;"><svg xmlns='http://www.w3.org/2000/svg' style='font-size:initial;' class="pikchr" viewBox="0 0 857.479 705.305" data-pikchr-date="20250319161943">
180 <path d="M17.9827,237.413L89.9827,237.413L89.9827,151.013L68.3827,129.413L17.9827,129.413Z" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
181 <path d="M68.3827,129.413L68.3827,151.013L89.9827,151.013" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
182 <circle cx="53.9827" cy="251.586" r="2.16" style="fill:rgb(0,0,0);stroke-width:2.16;stroke:rgb(0,0,0);" />
183 <circle cx="53.9827" cy="265.759" r="2.16" style="fill:rgb(0,0,0);stroke-width:2.16;stroke:rgb(0,0,0);" />
184 <circle cx="53.9827" cy="279.933" r="2.16" style="fill:rgb(0,0,0);stroke-width:2.16;stroke:rgb(0,0,0);" />
185 <path d="M17.9827,402.106L89.9827,402.106L89.9827,315.706L68.3827,294.106L17.9827,294.106Z" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
186 <path d="M68.3827,294.106L68.3827,315.706L89.9827,315.706" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
187 <path d="M17.9827,538.452L89.9827,538.452L89.9827,452.052L68.3827,430.452L17.9827,430.452Z" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
188 <path d="M68.3827,430.452L68.3827,452.052L89.9827,452.052" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
189 <circle cx="53.9827" cy="552.626" r="2.16" style="fill:rgb(0,0,0);stroke-width:2.16;stroke:rgb(0,0,0);" />
190 <circle cx="53.9827" cy="566.799" r="2.16" style="fill:rgb(0,0,0);stroke-width:2.16;stroke:rgb(0,0,0);" />
191 <circle cx="53.9827" cy="580.972" r="2.16" style="fill:rgb(0,0,0);stroke-width:2.16;stroke:rgb(0,0,0);" />
192 <path d="M17.9827,703.145L89.9827,703.145L89.9827,616.745L68.3827,595.145L17.9827,595.145Z" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
193 <path d="M68.3827,595.145L68.3827,616.745L89.9827,616.745" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
194 <path d="M146.676,402.106L203.369,402.106L203.369,129.413L146.676,129.413Z" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
195 <text x="175.022" y="255.679" text-anchor="middle" fill="rgb(0,0,0)" transform="rotate(-90 175.022,265.759)" dominant-baseline="central">Preprocessor Scripts</text>
196 <text x="175.022" y="275.839" text-anchor="middle" fill="rgb(0,0,0)" transform="rotate(-90 175.022,265.759)" dominant-baseline="central">And Programs</text>
197 <polygon points="146.676,183.413 135.156,187.733 135.156,179.093" style="fill:rgb(0,0,0)"/>
198 <path d="M89.9827,183.413L140.916,183.413" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
199 <polygon points="146.676,348.106 135.156,352.426 135.156,343.786" style="fill:rgb(0,0,0)"/>
200 <path d="M89.9827,348.106L140.916,348.106" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
201 <path d="M260.061,237.413L332.061,237.413L332.061,151.013L310.461,129.413L260.061,129.413Z" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
202 <path d="M310.461,129.413L310.461,151.013L332.061,151.013" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
203 <circle cx="296.061" cy="251.586" r="2.16" style="fill:rgb(0,0,0);stroke-width:2.16;stroke:rgb(0,0,0);" />
204 <circle cx="296.061" cy="265.759" r="2.16" style="fill:rgb(0,0,0);stroke-width:2.16;stroke:rgb(0,0,0);" />
205 <circle cx="296.061" cy="279.933" r="2.16" style="fill:rgb(0,0,0);stroke-width:2.16;stroke:rgb(0,0,0);" />
206 <path d="M260.061,402.106L332.061,402.106L332.061,315.706L310.461,294.106L260.061,294.106Z" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
207 <path d="M310.461,294.106L310.461,315.706L332.061,315.706" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
208 <polygon points="260.061,183.413 248.541,187.733 248.541,179.093" style="fill:rgb(0,0,0)"/>
209 <path d="M203.369,183.413L254.301,183.413" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
210 <polygon points="260.061,348.106 248.541,352.426 248.541,343.786" style="fill:rgb(0,0,0)"/>
211 <path d="M203.369,348.106L254.301,348.106" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
212 <path d="M417.101,617.085L473.794,617.085L473.794,215.473L417.101,215.473Z" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
213 <text x="445.447" y="416.279" text-anchor="middle" fill="rgb(0,0,0)" transform="rotate(-90 445.447,416.279)" dominant-baseline="central">Amalgamator Scripts</text>
214 <polygon points="417.101,295.795 406.705,289.216 413.594,284.002" style="fill:rgb(0,0,0)"/>
215 <path d="M332.061,183.413L413.625,291.202" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
216 <polygon points="417.101,376.118 404.808,376.617 407.511,368.41" style="fill:rgb(0,0,0)"/>
217 <path d="M332.061,348.106L411.63,374.316" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
218 <polygon points="417.101,456.44 405.991,461.727 405.254,453.119" style="fill:rgb(0,0,0)"/>
219 <path d="M89.9827,484.452L411.362,456.932" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
220 <polygon points="417.101,536.763 407.609,544.591 404.802,536.42" style="fill:rgb(0,0,0)"/>
221 <path d="M89.9827,649.145L411.653,538.634" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
222 <path d="M530.487,470.279L602.487,470.279L602.487,383.879L580.887,362.279L530.487,362.279Z" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
223 <path d="M580.887,362.279L580.887,383.879L602.487,383.879" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
224 <text x="566.487" y="416.279" text-anchor="middle" fill="rgb(0,0,0)" transform="rotate(-90 566.487,416.279)" dominant-baseline="central">sqlite3.h</text>
225 <path d="M530.487,333.933L602.487,333.933L602.487,247.533L580.887,225.933L530.487,225.933Z" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
226 <path d="M580.887,225.933L580.887,247.533L602.487,247.533" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
227 <text x="566.487" y="279.933" text-anchor="middle" fill="rgb(0,0,0)" transform="rotate(-90 566.487,279.933)" dominant-baseline="central">sqlite3.c</text>
228 <path d="M530.487,606.626L602.487,606.626L602.487,520.226L580.887,498.626L530.487,498.626Z" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
229 <path d="M580.887,498.626L580.887,520.226L602.487,520.226" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
230 <text x="566.487" y="552.626" text-anchor="middle" fill="rgb(0,0,0)" transform="rotate(-90 566.487,552.626)" dominant-baseline="central">shell.c</text>
231 <polygon points="530.487,279.933 518.967,284.253 518.967,275.613" style="fill:rgb(0,0,0)"/>
232 <path d="M473.794,279.933L524.727,279.933" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
233 <polygon points="530.487,416.279 518.967,420.599 518.967,411.959" style="fill:rgb(0,0,0)"/>
234 <path d="M473.794,416.279L524.727,416.279" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
235 <polygon points="530.487,552.626 518.967,556.946 518.967,548.306" style="fill:rgb(0,0,0)"/>
236 <path d="M473.794,552.626L524.727,552.626" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
237 <path d="M659.18,552.626L715.872,552.626L715.872,279.933L659.18,279.933Z" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
238 <text x="687.526" y="416.279" text-anchor="middle" fill="rgb(0,0,0)" transform="rotate(-90 687.526,416.279)" dominant-baseline="central">C Compiler</text>
239 <polygon points="659.18,348.106 648.492,342.011 655.135,336.486" style="fill:rgb(0,0,0)"/>
240 <path d="M602.487,279.933L655.497,343.677" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
241 <polygon points="659.18,416.279 647.66,420.599 647.66,411.959" style="fill:rgb(0,0,0)"/>
242 <path d="M602.487,416.279L653.42,416.279" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
243 <polygon points="659.18,484.452 655.135,496.072 648.492,490.548" style="fill:rgb(0,0,0)"/>
244 <path d="M602.487,552.626L655.497,488.881" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
245 <path d="M772.565,402.106L844.565,402.106L844.565,315.706L822.965,294.106L772.565,294.106Z" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
246 <path d="M822.965,294.106L822.965,315.706L844.565,315.706" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
247 <text x="808.565" y="348.106" text-anchor="middle" fill="rgb(0,0,0)" transform="rotate(-90 808.565,348.106)" dominant-baseline="central">libsqlite3.dll</text>
248 <path d="M772.565,538.452L844.565,538.452L844.565,452.052L822.965,430.452L772.565,430.452Z" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
249 <path d="M822.965,430.452L822.965,452.052L844.565,452.052" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
250 <text x="808.565" y="484.452" text-anchor="middle" fill="rgb(0,0,0)" transform="rotate(-90 808.565,484.452)" dominant-baseline="central">sqlite3.exe</text>
251 <polygon points="772.565,348.106 761.045,352.426 761.045,343.786" style="fill:rgb(0,0,0)"/>
252 <path d="M715.872,348.106L766.805,348.106" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
253 <polygon points="772.565,484.452 761.045,488.772 761.045,480.132" style="fill:rgb(0,0,0)"/>
254 <path d="M715.872,484.452L766.805,484.452" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
255 <text x="53.9827" y="17.28" text-anchor="middle" font-style="italic" font-weight="bold" fill="rgb(0,0,0)" dominant-baseline="central">Canonical</text>
256 <text x="53.9827" y="37.44" text-anchor="middle" font-style="italic" font-weight="bold" fill="rgb(0,0,0)" dominant-baseline="central">Source</text>
257 <text x="53.9827" y="57.6" text-anchor="middle" font-style="italic" font-weight="bold" fill="rgb(0,0,0)" dominant-baseline="central">Files</text>
258 <polygon points="53.9827,101.066 49.6627,89.5465 58.3027,89.5465" style="fill:rgb(0,0,0)"/>
259 <path d="M53.9827,72.72L53.9827,95.3065" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
260 <text x="296.061" y="17.28" text-anchor="middle" font-style="italic" font-weight="bold" fill="rgb(0,0,0)" dominant-baseline="central">Intermediate</text>
261 <text x="296.061" y="37.44" text-anchor="middle" font-style="italic" font-weight="bold" fill="rgb(0,0,0)" dominant-baseline="central">Source</text>
262 <text x="296.061" y="57.6" text-anchor="middle" font-style="italic" font-weight="bold" fill="rgb(0,0,0)" dominant-baseline="central">Files</text>
263 <polygon points="296.061,101.066 291.741,89.5465 300.381,89.5465" style="fill:rgb(0,0,0)"/>
264 <path d="M296.061,72.72L296.061,95.3065" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
265 <text x="566.487" y="57.6" text-anchor="middle" font-style="italic" font-weight="bold" fill="rgb(0,0,0)" dominant-baseline="central">Amalgamation</text>
266 <polygon points="566.487,101.066 562.167,89.5465 570.807,89.5465" style="fill:rgb(0,0,0)"/>
267 <path d="M566.487,72.72L566.487,95.3065" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
268 <text x="808.565" y="37.44" text-anchor="middle" font-style="italic" font-weight="bold" fill="rgb(0,0,0)" dominant-baseline="central">Build</text>
269 <text x="808.565" y="57.6" text-anchor="middle" font-style="italic" font-weight="bold" fill="rgb(0,0,0)" dominant-baseline="central">Products</text>
270 <polygon points="808.565,101.066 804.245,89.5465 812.885,89.5465" style="fill:rgb(0,0,0)"/>
271 <path d="M808.565,72.72L808.565,95.3065" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />
272 </svg>
273 </div></center>
274
275 <p>
276 The complete build process starts with the canonical source code files
277 on the left side of the diagram. There are between 100 and 200 separate
278 canonical source files (depending on the SQLite version). Some of those
279 canonical source files get transformed by preprocessor programs to generate
280 "intermediate source files". One example of a preprocessor is the
281 <a href="lemon.html">Lemon</a> parser generator program. One of the canonical source code files is
282 <a href="https://sqlite.org/src/file/src/parse.y">parse.y</a> which is an LALR(1) grammar
283 for the SQL dialect understood by SQLite. Lemon converts that grammar
284 into C-code that implements a
285 <a href="https://en.wikipedia.org/wiki/Pushdown_automaton">pushdown automaton</a> that
286 will parse SQL text into an
287 <a href="https://en.wikipedia.org/wiki/Abstract_syntax_tree">abstract syntax tree</a>.
288 There are many other examples of programs and scripts in SQLite that
289 transform the code that the SQLite developers edit into code that can be
290 understood by C compilers. Not all canonical source code files are
291 preprocessed, but a fair number of them are.
292
293 </p><p>
294 After preprocessing, there are some scripts that gather together the many
295 intermediate source files and the remaining canonical source files and
296 concatenates them together to generate the "<a href="amalgamation.html">amalgamation</a>". Often when
297 we say "the amalgamation" we mean just the file "sqlite3.c" which contains
298 the bulk of the SQLite source code. But the corresponding header file
299 "sqlite3.h" is also constructed from other files. And the source code
300 to the SQLite <a href="cli.html">command-line shell</a> is an amalgamation contained
301 in "shell.c".
302
303 </p><p>
304 The amalgamation files can then be processed by any ordinary C compiler
305 to render the final build products, shown on the right side of the
306 diagram. (The diagram shows build product filenames as they might
307 appear on Windows. Substitute whatever alternative names
308 are appropriate for your system.)
309
310 </p><h1 id="how_to_compile_from_canonical_sources"><span>3. </span>How To Compile From Canonical Sources</h1>
311
312 <p>
313 To compile SQLite from canonical sources, you
314 download a tarball or ZIP archive of the canonical source tree, unpack
315 that archive, then run either
316 "<tt>./configure && make</tt>" on unix or
317 "<tt>nmake /f Makefile.msc</tt>" on Windows.
318 More details available at the following:
319
320 </p><p>
321 </p><ul>
322 <li><a href="https://sqlite.org/src/file/doc/compile-for-unix.md">How To Compile On Unix</a>
323 </li><li><a href="https://sqlite.org/src/file/doc/compile-for-windows.md">How To Compile On Windows</a>
324 </li></ul>
325
326 <h1 id="how_to_compile_from_the_amalgamation"><span>4. </span>How To Compile From The Amalgamation</h1>
327
328 <p>
329 With each release of SQLite, the developers make available pre-built copies of
330 the SQLite amalgamation files that you can get from the
331 <a href="https://sqlite.org/download.html">Download Page</a>. Look for files named
332 "<tt>sqlite-amalgamation-</tt><i>NNNNNNN</i><tt>.zip</tt>" and
333 "<tt>sqlite-autoconf-</tt><i>NNNNNNN</i><tt>.tar.gz</tt>". The first is
334 just the amalgamation source files. The second also includes a
335 "configure" script and Makefile.
336
337 </p><h1 id="advantages_of_building_from_the_amalgamation"><span>5. </span>Advantages Of Building From The Amalgamation</h1>
338
339 <ol>
340 <li><p><b>Fewer Files To Worry With</b>
341 </p><p>You can embed the amalgamation files you need in
342 your own source tree, and compile them using your own
343 Makefile. You don't really need a separate "configure"
344 script or Makefile. Add the "sqlite3.c" and "sqlite3.h"
345 files into your own source tree, and then they will always
346 be there without creating a new dependency. When you want
347 to upgrade, just download the latest version and replace
348 the ones in your own source tree.
349
350 </p></li><li><p><b>Less To Download</b>
351 </p><p>The amalgamation archives are less than 1/4th the size
352 of the complete SQLite source tree. So there is less to
353 download.
354
355 </p></li><li><p><b>You Will End Up Using The Amalgamation Regardless</b>
356 </p><p>If you build from canonical sources, the Makefile first
357 builds the amalgamation and then compiles the amalgamation into
358 binary machine code. Why not just skip that first step
359 and go right to compiling the amalgamation directly?
360
361 </p></li><li><p><b>You Know That The Amalgamation You Are Using
362 Has Been Testing And Vetted By The SQLite Developers</b>
363 </p><p>If you pull down the pre-build amalgamation files, you can
364 have confidence that those exact source files have been
365 run through the SQLite developers <a href="testing.html">rigorous testing process</a>.
366 You don't have to worry that you somehow broke something as you
367 were compiling the canonical sources into the amalgamation.
368 </p></li></ol>
369
370 <h1 id="advantages_of_building_from_canonical_sources"><span>6. </span>Advantages Of Building From Canonical Sources</h1>
371
372 <ol>
373 <li><p><b>Access To More Compile-Time Options</b>
374 </p><p>SQLite supports <a href="compile.html">many, many compile-time options</a>,
375 some of which work with the amalgamation, but some of which do not. Depending
376 on what compile-time options you want to use, you may need to build from
377 canonical sources.
378
379 </p></li><li><p><b>Access To Historical And Unreleased Versions Of SQLite</b>
380 </p><p>The amalgamation source code is normally only available for the
381 latest released version of SQLite. If you want an historical version
382 of SQLite, or if you want to try out the latest unreleased trunk version
383 of SQLite because it has some new feature that you like or because you
384 just want to contribute back by helping with pre-release testing, then
385 you must compile from canonical source.
386
387 </p></li><li><p><b>Easier To Customize The Code</b>
388 </p><p>If you are making your own custom enhancements or modifications
389 to SQLite, then you should probably work with the canonical
390 sources. The amalgamation is designed to be friendly to
391 C-compilers, not human programmers. You can, in theory, make
392 custom modifications directly to the amalgamation source code,
393 but you will have an easier time of it if you use the
394 canonical source files.
395 </p></li></ol>
396
397 <h1 id="summary_which_should_you_choose"><span>7. </span>Summary: Which Should You Choose</h1>
398
399 <p>
400 The decision of whether to build SQLite from the amalgamation
401 or from canonical sources depends on your specific circumstances.
402 Review the advantages and disadvantages to each approach outlined
403 in the paragraphs above and decide for yourself.
404 </p><p align="center"><small><i>This page was last updated on 2025-07-12 15:11:36Z </small></i></p>
405