diff options
Diffstat (limited to 'www/howtocompile.html')
| -rw-r--r-- | www/howtocompile.html | 462 |
1 files changed, 462 insertions, 0 deletions
diff --git a/www/howtocompile.html b/www/howtocompile.html new file mode 100644 index 0000000..ffc08af --- /dev/null +++ b/www/howtocompile.html @@ -0,0 +1,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> + + |