Debian Codegraph @

www/howtocompile.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>How To Compile SQLite</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 How To Compile SQLite
122 </div>
123 <details class="fancy_toc">
124 <summary>Table Of Contents</summary>
125 <div id="toc_sub"><div class="fancy-toc1"><a href="#overview">1. Overview</a></div>
126 <div class="fancy-toc1"><a href="#amalgamation_versus_individual_source_files">2. Amalgamation Versus Individual Source Files</a></div>
127 <div class="fancy-toc1"><a href="#compiling_the_command_line_interface">3. Compiling The Command-Line Interface</a></div>
128 <div class="fancy-toc1"><a href="#compiling_the_tcl_interface">4. Compiling The TCL Interface</a></div>
129 <div class="fancy-toc1"><a href="#building_the_amalgamation">5. Building The Amalgamation</a></div>
130 <div class="fancy-toc1"><a href="#building_a_windows_dll">6. Building A Windows DLL</a></div>
131 </div>
132 </details>
133 </div>
134
135
136
137
138
139
140 <h1 id="overview"><span>1. </span>Overview</h1>
141
142 <p>
143 Compile SQLite like this:
144 </p><ul>
145 <li> Unix and Mac &rarr; <tt><b><big>./configure && make</big></b></tt>
146 </li><li> Windows &rarr; <tt><b><big>nmake /f Makefile.msc</big></b></tt>
147 </li></ul>
148
149
150 <p> The commands above will build the <a href="amalgamation.html">amalgamation</a> and the
151 <a href="cli.html">Command Line Interface</a> (aka: <a href="cli.html">CLI</a>). There are no (required) dependencies,
152 so the commands above should work as long as you have a compiler
153 installed. No third-party software is needed. For more detail see:
154 </p><ul>
155 <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>
156 </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>
157 </li></ul>
158
159
160 <p>But this article is not about providing a step-by-step recipe for compiling
161 SQLite. Rather, this article describes the principles behind the
162 compilation of SQLite. Typical compilation commands are provided as examples
163 with the expectation that application developers can use these examples
164 as guidance for developing their own custom compilation procedures.
165 In other words, this article provides ideas and insights, not turnkey
166 solutions. So if the overview commands above don't tell you want you
167 wanted to know, keep reading.</p>
168
169 <h1 id="amalgamation_versus_individual_source_files"><span>2. </span>Amalgamation Versus Individual Source Files</h1>
170
171 <p>SQLite is built from over one hundred files of C code and script
172 spread across multiple directories. The implementation of SQLite is pure
173 ANSI-C, but many of the C-language source code files are either
174 generated or transformed by auxiliary C programs and AWK, SED, and TCL
175 scripts prior to being incorporated into the finished SQLite library.
176 Building the necessary C programs and transforming and/or creating the
177 C-language source code for SQLite is a complex process.</p>
178
179 <p>To simplify matters, SQLite is also available as a pre-packaged
180 <a href="amalgamation.html">amalgamation</a> source code file: <b>sqlite3.c</b>. The amalgamation is
181 a single file of ANSI-C code that implements the entire SQLite library.
182 The amalgamation is much easier to deal with. Everything is contained
183 within a single code file, so it is easy to drop into the source tree
184 of a larger C or C++ program. All the code generation and transformation
185 steps have already been carried out so there are no auxiliary C programs
186 to configure and compile and no scripts to run. And, because the entire
187 library is contained in a single translation unit, compilers are able to
188 do more advanced optimizations resulting in a 5% to 10% performance
189 improvement. For these reasons, the amalgamation source file
190 ("<b>sqlite3.c</b>") is recommended for all applications.</p>
191
192 <blockquote><i>
193 The use of the <a href="amalgamation.html">amalgamation</a>, either downloaded pre-built from the website or
194 built yourself from <a href="amalg-v-canon.html#canon">canonical sources</a>, is recommended for all applications.
195 </i></blockquote>
196
197 <p>Linking the SQLite library to your application using
198 individual source code files is possible. However,
199 it is much easier to either download the amalgamation or
200 build it yourself using the "sqlite3.c" makefile target and
201 then use the amalgamation for subsequent build steps.
202 For some specialized applications, it
203 might be necessary to do a custom build of the amalgamation using
204 non-standard compile-time options rather than using the pre-built
205 amalgamation from the website.
206 In other words, even if a project requires building SQLite
207 beginning with individual source files, it is still recommended that an
208 amalgamation source file be used as an intermediate step.</p>
209
210 <a name="cli"></a>
211
212 <h1 id="compiling_the_command_line_interface"><span>3. </span>Compiling The Command-Line Interface</h1>
213
214 <p>A build of the <a href="cli.html">command-line interface</a> requires three source
215 files:</p>
216
217 <ul>
218 <li><b>sqlite3.c</b>: The SQLite amalgamation source file
219 </li><li><b>sqlite3.h</b>: The header file that accompanies sqlite3.c and
220 defines the C-language interfaces to SQLite.
221 </li><li><b>shell.c</b>: The command-line interface program itself.
222 This is the C source code file that contains the definition of
223 the <b>main()</b> routine and the loop that prompts for user input
224 and passes that input into the SQLite database engine for processing.
225 </li></ul>
226
227 <p>All three of the above source files are contained in the
228 <a href="download.html">amalgamation tarball</a> available on the <a href="download.html">download page</a>.
229 Or they can be built from <a href="amalg-v-canon.html#canon">canonical sources</a> using the "sqlite3.c"
230 makefile target.
231
232 </p><p>To build the CLI, simply put these three files in the same directory
233 and compile them together. Using MSVC:
234
235 </p><blockquote><pre>
236 cl shell.c sqlite3.c -Fesqlite3.exe
237 </pre></blockquote>
238
239 <p>On Unix systems
240 the command typically looks something like this:</p>
241
242 <blockquote><pre>
243 gcc shell.c sqlite3.c -lpthread -ldl -lm -o sqlite3
244 </pre></blockquote>
245
246 <p>The pthreads library is needed to make SQLite threadsafe. But
247 since the CLI is single threaded, we could instruct SQLite to build
248 in a non-threadsafe mode and thereby omit the pthreads library:</p>
249
250 <blockquote><pre>
251 gcc -DSQLITE_THREADSAFE=0 shell.c sqlite3.c -ldl -lm -o sqlite3
252 </pre></blockquote>
253
254 <p>The -ldl library is needed to support dynamic loading, the
255 <a href="c3ref/load_extension.html">sqlite3_load_extension()</a> interface and the
256 <a href="lang_corefunc.html#load_extension">load_extension() SQL function</a>. If these features are not required,
257 then they can be omitted using <a href="compile.html#omit_load_extension">SQLITE_OMIT_LOAD_EXTENSION</a> compile-time
258 option:</p>
259
260 <blockquote><pre>
261 gcc -DSQLITE_THREADSAFE=0 -DSQLITE_OMIT_LOAD_EXTENSION shell.c sqlite3.c -lm -o sqlite3
262 </pre></blockquote>
263
264 <p>One might want to provide other <a href="compile.html">compile-time options</a> such as</p>
265
266 <ul>
267 <li><a href="compile.html#enable_fts4">-DSQLITE_ENABLE_FTS4</a> or <a href="compile.html#enable_fts5">-DSQLITE_ENABLE_FTS5</a> for full-text search,</li>
268 <li><a href="compile.html#enable_rtree">-DSQLITE_ENABLE_RTREE</a> for the R*Tree search engine extension,</li>
269 <li><a href="compile.html#enable_dbstat_vtab">-DSQLITE_ENABLE_DBSTAT_VTAB</a> for the <a href="dbstat.html">dbstat virtual table</a>, or</li>
270 <li><a href="compile.html#enable_math_functions">-DSQLITE_ENABLE_MATH_FUNCTIONS</a> for extended math functions.</li>
271 </ul>
272
273 <p>In order to see extra commentary in <a href="lang_explain.html">EXPLAIN</a> listings, add the
274 <a href="compile.html#enable_explain_comments">-DSQLITE_ENABLE_EXPLAIN_COMMENTS</a> option. Add -DHAVE_READLINE and
275 the -lreadline and -lncurses libraries to get command-line editing
276 support. One might also want to specify some compiler optimization
277 switches. (The precompiled CLI available for download from the SQLite
278 website uses "-Os".) There are countless possible variations here. A
279 command to compile a full-featured shell might look something like
280 this:</p>
281
282 <blockquote><pre>
283 gcc -Os -I. -DSQLITE_THREADSAFE=0 -DSQLITE_ENABLE_FTS4 &#92;
284 -DSQLITE_ENABLE_FTS5 -DSQLITE_ENABLE_JSON1 &#92;
285 -DSQLITE_ENABLE_RTREE -DSQLITE_ENABLE_EXPLAIN_COMMENTS &#92;
286 -DHAVE_READLINE &#92;
287 shell.c sqlite3.c -ldl -lm -lreadline -lncurses -o sqlite3
288 </pre></blockquote>
289
290 <p>The key point is this: Building the CLI consists of compiling
291 together two C-language files. The <b>shell.c</b> file contains the
292 definition of the entry point and the user input loop and the
293 SQLite amalgamation <b>sqlite3.c</b> contains the complete implementation
294 of the SQLite library.</p>
295
296 <a name="tcl"></a>
297
298 <h1 id="compiling_the_tcl_interface"><span>4. </span>Compiling The TCL Interface</h1>
299
300 <p>The TCL interface for SQLite is a small module that is added into
301 the regular amalgamation. The result is a new amalgamated source
302 file called "<b>tclsqlite3.c</b>". This single source file is all that
303 is needed to generate a shared library that can be loaded into a
304 standard
305 <a href="http://wiki.tcl-lang.org/2541">tclsh</a> or
306 <a href="http://wiki.tcl-lang.org/2364">wish</a> using the
307 <a href="http://wiki.tcl-lang.org/9830">TCL load command</a>, or to generate a
308 standalone tclsh that comes with SQLite built in.</p>
309
310 <p>To generate a TCL-loadable library for SQLite on Linux, the following
311 command will suffice:</p>
312
313 <blockquote><pre>
314 gcc -o libtclsqlite3.so -shared tclsqlite3.c -lpthread -ldl -ltcl
315 </pre></blockquote>
316
317 <p>Building shared libraries for Mac OS X and Windows is not nearly so simple,
318 unfortunately.</p>
319
320 <p>To generate a standalone tclsh that is statically linked with SQLite,
321 use this compiler invocation:</p>
322
323 <blockquote><pre>
324 gcc -DTCLSH=1 tclsqlite3.c -ltcl -lpthread -ldl -lz -lm
325 </pre></blockquote>
326
327 <p>The trick here is the -DTCLSH=1 option. The TCL interface module for
328 SQLite includes a <b>main()</b> procedure that initializes a TCL interpreter
329 and enters a command-line loop when it is compiled with -DTCLSH=1. The
330 command above works on both Linux and Mac OS X, though one may need to adjust
331 the library options depending on the platform and which version of TCL one
332 is linking against.</p>
333
334 <a name="amal"></a>
335
336 <h1 id="building_the_amalgamation"><span>5. </span>Building The Amalgamation</h1>
337
338 <p>The versions of the SQLite amalgamation that are supplied on the
339 <a href="download.html">download page</a> are normally adequate for most users. However, some
340 projects may want or need to build their own amalgamations. A common
341 reason for building a custom amalgamation is in order to use certain
342 <a href="compile.html">compile-time options</a> to customize the SQLite library. Recall that
343 the SQLite amalgamation contains a lot of C-code that is generated by
344 auxiliary programs and scripts. Many of the compile-time
345 options affect this generated code and must be supplied to the code
346 generators before the amalgamation is assembled. The set of
347 compile-time options that must be passed into the code generators can
348 vary from one release of SQLite to the next, but at the time of this
349 writing (circa SQLite 3.6.20, 2009-11-04) the set of options that must
350 be known by the code generators includes:</p>
351
352 <ul>
353 <li><a href="compile.html#enable_update_delete_limit">SQLITE_ENABLE_UPDATE_DELETE_LIMIT</a>
354 </li><li><a href="compile.html#omit_altertable">SQLITE_OMIT_ALTERTABLE</a>
355 </li><li><a href="compile.html#omit_analyze">SQLITE_OMIT_ANALYZE</a>
356 </li><li><a href="compile.html#omit_attach">SQLITE_OMIT_ATTACH</a>
357 </li><li><a href="compile.html#omit_autoincrement">SQLITE_OMIT_AUTOINCREMENT</a>
358 </li><li><a href="compile.html#omit_cast">SQLITE_OMIT_CAST</a>
359 </li><li><a href="compile.html#omit_compound_select">SQLITE_OMIT_COMPOUND_SELECT</a>
360 </li><li><a href="compile.html#omit_explain">SQLITE_OMIT_EXPLAIN</a>
361 </li><li><a href="compile.html#omit_foreign_key">SQLITE_OMIT_FOREIGN_KEY</a>
362 </li><li><a href="compile.html#omit_pragma">SQLITE_OMIT_PRAGMA</a>
363 </li><li><a href="compile.html#omit_reindex">SQLITE_OMIT_REINDEX</a>
364 </li><li><a href="compile.html#omit_subquery">SQLITE_OMIT_SUBQUERY</a>
365 </li><li><a href="compile.html#omit_tempdb">SQLITE_OMIT_TEMPDB</a>
366 </li><li><a href="compile.html#omit_trigger">SQLITE_OMIT_TRIGGER</a>
367 </li><li><a href="compile.html#omit_vacuum">SQLITE_OMIT_VACUUM</a>
368 </li><li><a href="compile.html#omit_view">SQLITE_OMIT_VIEW</a>
369 </li><li><a href="compile.html#omit_virtualtable">SQLITE_OMIT_VIRTUALTABLE</a>
370 </li></ul>
371
372 <p>To build a custom amalgamation, first download the original individual
373 source files onto a Unix or Unix-like development platform.
374 Be sure to get the original source
375 files, not the "preprocessed source files". One can obtain the complete
376 set of original source files either from the <a href="download.html">download page</a> or directly
377 from the <a href="https://sqlite.org/src">configuration management system</a>.</p>
378
379 <p>Suppose the SQLite source tree is stored in a directory named "sqlite".
380 Plan to construct the amalgamation in a parallel directory named (for
381 example) "bld". First construct an appropriate Makefile by either
382 running the configure script at the top of the SQLite source tree, or by
383 making a copy of one of the template Makefiles at the top of the source tree.
384 Then hand edit this Makefile to include the desired compile-time options.
385 Finally run:</p>
386
387 <blockquote><pre>
388 make sqlite3.c
389 </pre></blockquote>
390
391 <p>Or on Windows with MSVC:
392
393 </p><blockquote><pre>
394 nmake /f Makefile.msc sqlite3.c
395 </pre></blockquote>
396
397 <p>The "sqlite3.c" make target will automatically construct the regular
398 "<b>sqlite3.c</b>" amalgamation source file, its header file
399 "<b>sqlite3.h</b>", and the "<b>tclsqlite3.c</b>" amalgamation source
400 file that includes the TCL interface.
401 Afterwards, the needed files can be copied into project directories and
402 compiled according to the procedures outlined above.</p>
403
404 <a name="dll"></a>
405
406 <h1 id="building_a_windows_dll"><span>6. </span>Building A Windows DLL</h1>
407
408 <p>To build a DLL of SQLite for use in Windows, first acquire the
409 appropriate amalgamated source code files, sqlite3.c and sqlite3.h.
410 These can either
411 be downloaded from the <a href="https://sqlite.org/download.html">SQLite website</a>
412 or custom generated from sources as shown above.</p>
413
414 <p>With source code files in the working directory, a DLL
415 can be generated using MSVC with the following command:
416
417 </p><blockquote><pre>
418 cl sqlite3.c -link -dll -out:sqlite3.dll
419 </pre></blockquote>
420
421 <p>The above command should be run from the MSVC Native Tools Command
422 Prompt. If you have MSVC installed on your machine, you probably
423 have multiple versions of this Command Prompt, for native builds
424 for x86 and x64, and possibly also for cross-compiling to ARM.
425 Use the appropriate Command Prompt depending on the desired DLL.</p>
426
427 <p>If using the MinGW compiler, the command-line is this:
428
429 </p><blockquote><pre>
430 gcc -shared sqlite3.c -o sqlite3.dll
431 </pre></blockquote>
432
433 <p>Note that MinGW generates 32-bit DLLs only. There is a separate
434 MinGW64 project that can be used to generate 64-bit DLLs. Presumably
435 the command-line syntax is similar.
436 Also note that recent versions of MSVC generate DLLs that will not work
437 on WinXP and earlier versions of Windows. So for maximum compatibility
438 of your generated DLL, MinGW is recommended. A good rule-of-thumb
439 is to generate 32-bit DLLs using MinGW and 64-bit DLLs using MSVC.
440
441 </p><p>In most cases, you will want to supplement the basic commands above with
442 <a href="compile.html">compile-time options</a> appropriate for your application. Commonly used
443 compile-time options include:
444
445 </p><ul>
446 <li><p><b>-Os</b> - Optimize for size.
447 Make the DLL as small as possible.</p>
448
449 </li><li><p><b>-O2</b> - Optimize for speed. This will make the DLL larger by
450 unrolling loops and inlining functions.</p>
451
452 </li><li><p><b>-DSQLITE_ENABLE_FTS4</b> -
453 Include the <a href="fts3.html">full-text search</a> engine code in SQLite.
454
455 </p></li><li><p><b>-DSQLITE_ENABLE_RTREE</b> - Include the <a href="rtree.html">R-Tree extension</a>.
456
457 </p></li><li><p><b>-DSQLITE_ENABLE_COLUMN_METADATA</b> -
458 This enables some extra APIs that are required by some common systems,
459 including Ruby-on-Rails.
460 </p></li></ul>
461 <p align="center"><small><i>This page was last updated on 2025-11-13 07:12:58Z </small></i></p>
462