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
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
|
<!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>How To Compile SQLite</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">
How To Compile SQLite
</div>
<div class="fancy_toc">
<a onclick="toggle_toc()">
<span class="fancy_toc_mark" id="toc_mk">►</span>
Table Of Contents
</a>
<div id="toc_sub"><div class="fancy-toc1"><a href="#amalgamation_versus_individual_source_files">1. Amalgamation Versus Individual Source Files</a></div>
<div class="fancy-toc1"><a href="#compiling_the_command_line_interface">2. Compiling The Command-Line Interface</a></div>
<div class="fancy-toc1"><a href="#compiling_the_tcl_interface">3. Compiling The TCL Interface</a></div>
<div class="fancy-toc1"><a href="#building_the_amalgamation">4. Building The Amalgamation</a></div>
<div class="fancy-toc1"><a href="#building_a_windows_dll">5. Building A Windows DLL</a></div>
</div>
</div>
<script>
function toggle_toc(){
var sub = document.getElementById("toc_sub")
var mk = document.getElementById("toc_mk")
if( sub.style.display!="block" ){
sub.style.display = "block";
mk.innerHTML = "▼";
} else {
sub.style.display = "none";
mk.innerHTML = "►";
}
}
</script>
</div>
<title>How To Compile SQLite</title>
<h2 style="margin-left:1.0em" notoc="1" id="overview"> Overview</h2>
<p>
SQLite is ANSI-C source code.
It must be compiled into machine code before it is useful.
This article is a guide to the various ways of compiling SQLite.
</p>
<p>This article does not contain a step-by-step recipe for compiling
SQLite. That would be difficult since each development situation
is different.
Rather, this article describes and illustrates the principles behind the
compilation of SQLite. Typical compilation commands are provided as examples
with the expectation that application developers can use these examples
as guidance for developing their own custom compilation procedures.
In other words, this article provides ideas and insights, not turnkey
solutions.</p>
<h1 id="amalgamation_versus_individual_source_files"><span>1. </span>Amalgamation Versus Individual Source Files</h1>
<p>SQLite is built from over one hundred files of C code and script
spread across multiple directories. The implementation of SQLite is pure
ANSI-C, but many of the C-language source code files are either
generated or transformed by auxiliary C programs and AWK, SED, and TCL
scripts prior to being incorporated into the finished SQLite library.
Building the necessary C programs and transforming and/or creating the
C-language source code for SQLite is a complex process.</p>
<p>To simplify matters, SQLite is also available as a pre-packaged
<a href="amalgamation.html">amalgamation</a> source code file: <b>sqlite3.c</b>. The amalgamation is
a single file of ANSI-C code that implements the entire SQLite library.
The amalgamation is much easier to deal with. Everything is contained
within a single code file, so it is easy to drop into the source tree
of a larger C or C++ program. All the code generation and transformation
steps have already been carried out so there are no auxiliary C programs
to configure and compile and no scripts to run. And, because the entire
library is contained in a single translation unit, compilers are able to
do more advanced optimizations resulting in a 5% to 10% performance
improvement. For these reasons, the amalgamation source file
("<b>sqlite3.c</b>") is recommended for all applications.</p>
<blockquote><i>
The use of the <a href="amalgamation.html">amalgamation</a> is recommended for all applications.
</i></blockquote>
<p>Building SQLite directly from individual source code files is certainly
possible, but it is not recommended. For some specialized applications, it
might be necessary to modify the build process in ways that cannot be done
using just the prebuilt amalgamation source file downloaded from the website.
For those situations, it is recommended that a customized amalgamation be
built (as described <a href="howtocompile.html#amal">below</a>)
and used. In other words, even if a project requires building SQLite
beginning with individual source files, it is still recommended that an
amalgamation source file be used as an intermediate step.</p>
<a name="cli"></a>
<h1 id="compiling_the_command_line_interface"><span>2. </span>Compiling The Command-Line Interface</h1>
<p>A build of the <a href="cli.html">command-line interface</a> requires three source
files:</p>
<ul>
<li><b>sqlite3.c</b>: The SQLite amalgamation source file
</li><li><b>sqlite3.h</b>: The header files that accompanies sqlite3.c and
defines the C-language interfaces to SQLite.
</li><li><b>shell.c</b>: The command-line interface program itself.
This is the C source code file that contains the definition of
the <b>main()</b> routine and the loop that prompts for user input
and passes that input into the SQLite database engine for processing.
</li></ul>
<p>All three of the above source files are contained in the
<a href="download.html">amalgamation tarball</a> available on the <a href="download.html">download page</a>.</p>
<p>To build the CLI, simply put these three files in the same directory
and compile them together. Using MSVC:
</p><blockquote><pre>
cl shell.c sqlite3.c -Fesqlite3.exe
</pre></blockquote>
<p>On Unix systems (or on Windows using cygwin or mingw+msys)
the command typically looks something like this:</p>
<blockquote><pre>
gcc shell.c sqlite3.c -lpthread -ldl -lm -o sqlite3
</pre></blockquote>
<p>The pthreads library is needed to make SQLite threadsafe. But
since the CLI is single threaded, we could instruct SQLite to build
in a non-threadsafe mode and thereby omit the pthreads library:</p>
<blockquote><pre>
gcc -DSQLITE_THREADSAFE=0 shell.c sqlite3.c -ldl -lm -o sqlite3
</pre></blockquote>
<p>The -ldl library is needed to support dynamic loading, the
<a href="c3ref/load_extension.html">sqlite3_load_extension()</a> interface and the
<a href="lang_corefunc.html#load_extension">load_extension() SQL function</a>. If these features are not required,
then they can be omitted using <a href="compile.html#omit_load_extension">SQLITE_OMIT_LOAD_EXTENSION</a> compile-time
option:</p>
<blockquote><pre>
gcc -DSQLITE_THREADSAFE=0 -DSQLITE_OMIT_LOAD_EXTENSION shell.c sqlite3.c -o sqlite3
</pre></blockquote>
<p>One might want to provide other <a href="compile.html">compile-time options</a> such as</p>
<ul>
<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>
<li><a href="compile.html#enable_rtree">-DSQLITE_ENABLE_RTREE</a> for the R*Tree search engine extension,</li>
<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>
<li><a href="compile.html#enable_math_functions">-DSQLITE_ENABLE_MATH_FUNCTIONS</a> for extended math functions.</li>
</ul>
<p>In order to see extra commentary in <a href="lang_explain.html">EXPLAIN</a> listings, add the
<a href="compile.html#enable_explain_comments">-DSQLITE_ENABLE_EXPLAIN_COMMENTS</a> option. Add -DHAVE_READLINE and
the -lreadline and -lncurses libraries to get command-line editing
support. One might also want to specify some compiler optimization
switches. (The precompiled CLI available for download from the SQLite
website uses "-Os".) There are countless possible variations here. A
command to compile a full-featured shell might look something like
this:</p>
<blockquote><pre>
gcc -Os -I. -DSQLITE_THREADSAFE=0 -DSQLITE_ENABLE_FTS4 \
-DSQLITE_ENABLE_FTS5 -DSQLITE_ENABLE_JSON1 \
-DSQLITE_ENABLE_RTREE -DSQLITE_ENABLE_EXPLAIN_COMMENTS \
-DHAVE_READLINE \
shell.c sqlite3.c -ldl -lm -lreadline -lncurses -o sqlite3
</pre></blockquote>
<p>The key point is this: Building the CLI consists of compiling
together two C-language files. The <b>shell.c</b> file contains the
definition of the entry point and the user input loop and the
SQLite amalgamation <b>sqlite3.c</b> contains the complete implementation
of the SQLite library.</p>
<a name="tcl"></a>
<h1 id="compiling_the_tcl_interface"><span>3. </span>Compiling The TCL Interface</h1>
<p>The TCL interface for SQLite is a small module that is added into
the regular amalgamation. The result is a new amalgamated source
file called "<b>tclsqlite3.c</b>". This single source file is all that
is needed to generate a shared library that can be loaded into a
standard
<a href="http://wiki.tcl-lang.org/2541">tclsh</a> or
<a href="http://wiki.tcl-lang.org/2364">wish</a> using the
<a href="http://wiki.tcl-lang.org/9830">TCL load command</a>, or to generate a
standalone tclsh that comes with SQLite built in.
A copy of the tcl amalgamation
is included on the <a href="download.html">download page</a> as a file in the <a href="download.html">TEA tarball</a>.</p>
<p>To generate a TCL-loadable library for SQLite on Linux, the following
command will suffice:</p>
<blockquote><pre>
gcc -o libtclsqlite3.so -shared tclsqlite3.c -lpthread -ldl -ltcl
</pre></blockquote>
<p>Building shared libraries for Mac OS X and Windows is not nearly so simple,
unfortunately. For those platforms it is best to use the configure script
and makefile that is included with the <a href="download.html">TEA tarball</a>.</p>
<p>To generate a standalone tclsh that is statically linked with SQLite,
use this compiler invocation:</p>
<blockquote><pre>
gcc -DTCLSH=1 tclsqlite3.c -ltcl -lpthread -ldl -lz -lm
</pre></blockquote>
<p>The trick here is the -DTCLSH=1 option. The TCL interface module for
SQLite includes a <b>main()</b> procedure that initializes a TCL interpreter
and enters a command-line loop when it is compiled with -DTCLSH=1. The
command above works on both Linux and Mac OS X, though one may need to adjust
the library options depending on the platform and which version of TCL one
is linking against.</p>
<a name="amal"></a>
<h1 id="building_the_amalgamation"><span>4. </span>Building The Amalgamation</h1>
<p>The versions of the SQLite amalgamation that are supplied on the
<a href="download.html">download page</a> are normally adequate for most users. However, some
projects may want or need to build their own amalgamations. A common
reason for building a custom amalgamation is in order to use certain
<a href="compile.html">compile-time options</a> to customize the SQLite library. Recall that
the SQLite amalgamation contains a lot of C-code that is generated by
auxiliary programs and scripts. Many of the compile-time
options effect this generated code and must be supplied to the code
generators before the amalgamation is assembled. The set of
compile-time options that must be passed into the code generators can
vary from one release of SQLite to the next, but at the time of this
writing (circa SQLite 3.6.20, 2009-11-04) the set of options that must
be known by the code generators includes:</p>
<ul>
<li><a href="compile.html#enable_update_delete_limit">SQLITE_ENABLE_UPDATE_DELETE_LIMIT</a>
</li><li><a href="compile.html#omit_altertable">SQLITE_OMIT_ALTERTABLE</a>
</li><li><a href="compile.html#omit_analyze">SQLITE_OMIT_ANALYZE</a>
</li><li><a href="compile.html#omit_attach">SQLITE_OMIT_ATTACH</a>
</li><li><a href="compile.html#omit_autoincrement">SQLITE_OMIT_AUTOINCREMENT</a>
</li><li><a href="compile.html#omit_cast">SQLITE_OMIT_CAST</a>
</li><li><a href="compile.html#omit_compound_select">SQLITE_OMIT_COMPOUND_SELECT</a>
</li><li><a href="compile.html#omit_explain">SQLITE_OMIT_EXPLAIN</a>
</li><li><a href="compile.html#omit_foreign_key">SQLITE_OMIT_FOREIGN_KEY</a>
</li><li><a href="compile.html#omit_pragma">SQLITE_OMIT_PRAGMA</a>
</li><li><a href="compile.html#omit_reindex">SQLITE_OMIT_REINDEX</a>
</li><li><a href="compile.html#omit_subquery">SQLITE_OMIT_SUBQUERY</a>
</li><li><a href="compile.html#omit_tempdb">SQLITE_OMIT_TEMPDB</a>
</li><li><a href="compile.html#omit_trigger">SQLITE_OMIT_TRIGGER</a>
</li><li><a href="compile.html#omit_vacuum">SQLITE_OMIT_VACUUM</a>
</li><li><a href="compile.html#omit_view">SQLITE_OMIT_VIEW</a>
</li><li><a href="compile.html#omit_virtualtable">SQLITE_OMIT_VIRTUALTABLE</a>
</li></ul>
<p>To build a custom amalgamation, first download the original individual
source files onto a Unix or Unix-like development platform.
Be sure to get the original source
files not the "preprocessed source files". One can obtain the complete
set of original source files either from the <a href="download.html">download page</a> or directly
from the <a href="https://www.sqlite.org/src">configuration management system</a>.</p>
<p>Suppose the SQLite source tree is stored in a directory named "sqlite".
Plan to construct the amalgamation in a parallel directory named (for
example) "bld". First construct an appropriate Makefile by either
running the configure script at the top of the SQLite source tree, or by
making a copy of one of the template Makefiles at the top of the source tree.
Then hand edit this Makefile to include the desired compile-time options.
Finally run:</p>
<blockquote><pre>
make sqlite3.c
</pre></blockquote>
<p>Or on Windows with MSVC:
</p><blockquote><pre>
nmake /f Makefile.msc sqlite3.c
</pre></blockquote>
<p>The "sqlite3.c" make target will automatically construct the regular
"<b>sqlite3.c</b>" amalgamation source file, its header file
"<b>sqlite3.h</b>", and the "<b>tclsqlite3.c</b>" amalgamation source
file that includes the TCL interface.
Afterwards, the needed files can be copied into project directories and
compiled according to the procedures outlined above.</p>
<a name="dll"></a>
<h1 id="building_a_windows_dll"><span>5. </span>Building A Windows DLL</h1>
<p>To build a DLL of SQLite for use in Windows, first acquire the
appropriate amalgamated source code files, sqlite3.c and sqlite3.h.
These can either
be downloaded from the <a href="https://www.sqlite.org/download.html">SQLite website</a>
or custom generated from sources as shown above.</p>
<p>With source code files in the working directory, a DLL
can be generated using MSVC with the following command:
</p><blockquote><pre>
cl sqlite3.c -link -dll -out:sqlite3.dll
</pre></blockquote>
<p>The above command should be run from the MSVC Native Tools Command
Prompt. If you have MSVC installed on your machine, you probably
have multiple versions of this Command Prompt, for native builds
for x86 and x64, and possibly also for cross-compiling to ARM.
Use the appropriate Command Prompt depending on the desired DLL.</p>
<p>If using the MinGW compiler, the command-line is this:
</p><blockquote><pre>
gcc -shared sqlite3.c -o sqlite3.dll
</pre></blockquote>
<p>Note that MinGW generates 32-bit DLLs only. There is a separate
MinGW64 project that can be used to generate 64-bit DLLs. Presumably
the command-line syntax is similar.
Also note that recent versions of MSVC generate DLLs that will not work
on WinXP and earlier versions of Windows. So for maximum compatibility
of your generated DLL, MinGW is recommended. A good rule-of-thumb
is to generate 32-bit DLLs using MinGW and 64-bit DLLs using MSVC.
</p><p>In most cases, you will want to supplement the basic commands above with
<a href="compile.html">compile-time options</a> appropriate for your application. Commonly used
compile-time options include:
</p><ul>
<li><p><b>-Os</b> - Optimize for size.
Make the DLL as small as possible.</p>
</li><li><p><b>-O2</b> - Optimize for speed. This will make the DLL larger by
unrolling loops and inlining functions.</p>
</li><li><p><b>-DSQLITE_ENABLE_FTS4</b> -
Include the <a href="fts3.html">full-text search</a> engine code in SQLite.
</p></li><li><p><b>-DSQLITE_ENABLE_RTREE</b> - Include the <a href="rtree.html">R-Tree extension</a>.
</p></li><li><p><b>-DSQLITE_ENABLE_COLUMN_METADATA</b> -
This enables some extra APIs that are required by some common systems,
including Ruby-on-Rails.
</p></li></ul>
|
