Adding upstream version 3.40.1.upstream/3.40.1 upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
author: Daniel Baumann <daniel.baumann@progress-linux.org> 2024-05-05 17:28:19 +0000
committer: Daniel Baumann <daniel.baumann@progress-linux.org> 2024-05-05 17:28:19 +0000
commit: 18657a960e125336f704ea058e25c27bd3900dcb (patch)
tree: 17b438b680ed45a996d7b59951e6aa34023783f2 /www/howtocompile.html
parent: Initial commit. (diff)
download: sqlite3-18657a960e125336f704ea058e25c27bd3900dcb.tar.xz
sqlite3-18657a960e125336f704ea058e25c27bd3900dcb.zip
1 files changed, 460 insertions, 0 deletions
diff --git a/www/howtocompile.html b/www/howtocompile.html
new file mode 100644
index 0000000..4082ab3
--- /dev/null
+++ b/www/howtocompile.html
@@ -0,0 +1,460 @@
+<!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">&#x25ba;</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 = "&#x25bc;";
+} else {
+sub.style.display = "none";
+mk.innerHTML = "&#x25ba;";
+}
+}
+</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 principals 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
+<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,
+<a href="compile.html#enable_rtree">-DSQLITE_ENABLE_RTREE</a> for the R*Tree search engine extension,
+<a href="compile.html#enable_json1">-DSQLITE_ENABLE_JSON1</a> to include <a href="json1.html">JSON SQL functions</a>, or
+<a href="compile.html#enable_dbstat_vtab">-DSQLITE_ENABLE_DBSTAT_VTAB</a> for the <a href="dbstat.html">dbstat virtual table</a>.
+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.
+On unix systems, add -DHAVE_USLEEP=1 if the host machine supports the
+usleep() system call.  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 &#92;
+   -DSQLITE_ENABLE_FTS5 -DSQLITE_ENABLE_JSON1 &#92;
+   -DSQLITE_ENABLE_RTREE -DSQLITE_ENABLE_EXPLAIN_COMMENTS &#92;
+   -DHAVE_USLEEP -DHAVE_READLINE &#92;
+   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="http://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="http://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>
+<p align="center"><small><i>This page last modified on  <a href="https://sqlite.org/docsrc/honeypot" id="mtimelink"  data-href="https://sqlite.org/docsrc/finfo/pages/howtocompile.in?m=7a488b0570e1db92a">2021-10-12 03:48:52</a> UTC </small></i></p>
+
author	Daniel Baumann <daniel.baumann@progress-linux.org>	2024-05-05 17:28:19 +0000
committer	Daniel Baumann <daniel.baumann@progress-linux.org>	2024-05-05 17:28:19 +0000
commit	18657a960e125336f704ea058e25c27bd3900dcb (patch)
tree	17b438b680ed45a996d7b59951e6aa34023783f2 /www/howtocompile.html
parent	Initial commit. (diff)
download	sqlite3-18657a960e125336f704ea058e25c27bd3900dcb.tar.xz sqlite3-18657a960e125336f704ea058e25c27bd3900dcb.zip