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/custombuild.html
parent: Initial commit. (diff)
download: sqlite3-upstream.tar.xz
sqlite3-upstream.zip
1 files changed, 403 insertions, 0 deletions
diff --git a/www/custombuild.html b/www/custombuild.html
new file mode 100644
index 0000000..94f52a6
--- /dev/null
+++ b/www/custombuild.html
@@ -0,0 +1,403 @@
+<!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>Custom Builds Of 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>
+
+
+
+
+<h1 align="center">
+Custom Builds Of SQLite<br>
+or<br>
+Porting SQLite To New Operating Systems
+</h1>
+
+<h2>1.0 Introduction</h2>
+
+<p>For most applications, the recommended method for building
+SQLite is to use <a href="amalgamation.html">the amalgamation</a> code
+file, <b>sqlite3.c</b>, and its corresponding header file
+<b>sqlite3.h</b>.  The sqlite3.c code file should compile and
+run on any Unix, Windows system without any changes
+or special compiler options.  Most applications can simply include
+the sqlite3.c file together with the other C code files that make
+up the application, compile them all together, and have working
+and well configured version of SQLite.</p>
+
+<blockquote><i>Most applications work great with SQLite in its
+default configuration and with no special compile-time configuration.
+Most developers should be able to completely ignore this document
+and simply build SQLite from
+<a href="amalgamation.html">the amalgamation</a> without any
+special knowledge and without taking any special actions.</i></blockquote>
+
+<p>However, highly tuned and specialized
+applications may want or need to replace some of
+SQLite's built-in system interfaces with alternative implementations
+more suitable for the needs of the application.  SQLite is designed
+to be easily reconfigured at compile-time to meet the specific
+needs of individual projects.  Among the compile-time configuration
+options for SQLite are these:</p>
+
+<ul>
+<li><p> Replace the built-in mutex subsystem with an alternative
+        implementation.  </p></li>
+
+<li><p> Completely disable all mutexing for use in single-threaded
+        applications. </p></li>
+
+<li><p> Reconfigure the memory allocation subsystem to use a memory
+        allocator other the malloc() implementation from the standard
+        library. </p></li>
+
+<li><p> Realign the memory allocation subsystem so that it never calls
+        malloc() at all but instead satisfies all memory requests using
+        a fixed-size memory buffer assigned to SQLite at startup. </p></li>
+
+<li><p> Replace the interface to the file system with an alternative
+        design.  In other words, override all of the system calls that
+        SQLite makes in order to talk to the disk with a completely different
+        set of system calls. </p></li>
+
+<li><p> Override other operating system interfaces such as calls to obtain
+        Zulu or local time. </p></li>
+</ul>
+
+<p>Generally speaking, there are three separate subsystems within
+SQLite that can be modified or overridden at compile-time.  The
+mutex subsystem is used to serialize access to SQLite resources that
+are shared among threads.  The memory allocation subsystem is used
+to allocate memory required by SQLite objects and for the database
+cache.  Finally, the <a href="c3ref/vfs.html">Virtual File System</a> subsystem is
+used to provide a portable interface between SQLite and the underlying
+operating system and especially the file system.  We call these three
+subsystems the "interface" subsystems of SQLite.</p>
+
+<p>We emphasis that most applications are well-served by the 
+built-in default implementations of the SQLite interface subsystems.
+Developers are encouraged to use the
+default built-in implementations whenever possible
+and to build SQLite without any special compile-time options or parameters.
+However, some highly specialized applications may benefit from
+substituting or modifying one or more of these built-in SQLite
+interface subsystems.
+Or, if SQLite is used on an operating system other than
+Unix (Linux or Mac OS X), Windows (Win32 or WinCE), or OS/2 then none
+of the interface subsystems that come built into SQLite will work
+and the application will need to provide alternative implementations
+suitable for the target platform.</p>
+
+<h2>2.0 Configuring Or Replacing The Mutex Subsystem</h2>
+
+<p>In a multithreaded environment, SQLite uses mutexes to serialize
+access to shared resources.
+The mutex subsystem is only required for applications that access
+SQLite from multiple threads.  For single-threaded applications, or
+applications which only call SQLite from a single thread, the mutex
+subsystem can be completely disabled by recompiling with the following
+option:</p>
+
+<blockquote><pre>
+-DSQLITE_THREADSAFE=0
+</pre></blockquote>
+
+<p>Mutexes are cheap but they are not free, so performance will be better
+when mutexes are completely disabled.  The resulting library footprint
+will also be a little smaller.  Disabling the mutexes at compile-time
+is a recommended optimization for applications where it makes sense.</p>
+
+<p>When using SQLite as a shared library, an application can test to see
+whether or not mutexes have been disabled using the
+<a href="c3ref/threadsafe.html">sqlite3_threadsafe()</a> API.  Applications that link against SQLite at
+run-time and use SQLite from multiple threads should probably check this
+API to make sure they did not accidentally get linked against a version of
+the SQLite library that has its mutexes disabled.  Single-threaded
+applications will, of course, work correctly regardless of whether or
+not SQLite is configured to be threadsafe, though they will be a little
+bit faster when using versions of SQLite with mutexes disabled.</p>
+
+<p>SQLite mutexes can also be disabled at run-time using the
+<a href="c3ref/config.html">sqlite3_config()</a> interface.  To completely disable all mutexing,
+the application can invoke:</p>
+
+<blockquote><pre>
+sqlite3_config(SQLITE_CONFIG_SINGLETHREAD);
+</pre></blockquote>
+
+<p>Disabling mutexes at run-time is not as effective as disabling them
+at compile-time since SQLite still must do a test of a boolean variable
+to see if mutexes are enabled or disabled at each point where a mutex
+might be required.  But there is still a performance advantage for
+disabling mutexes at run-time.</p>
+
+<p>For multi-threaded applications that are careful about how they
+manage threads, SQLite supports an alternative run-time configuration
+that is half way between not using any mutexes and the default situation
+of mutexing everything in sight.  This in-the-middle mutex alignment can
+be established as follows:</p>
+
+<blockquote><pre>
+sqlite3_config(SQLITE_CONFIG_MULTITHREAD);
+sqlite3_config(SQLITE_CONFIG_MEMSTATUS, 0);
+</pre></blockquote>
+
+<p>There are two separate configuration changes here which can
+be used either together or separately. The
+<a href="c3ref/c_config_covering_index_scan.html#sqliteconfigmultithread">SQLITE_CONFIG_MULTITHREAD</a> setting disables the mutexes that
+serialize access to <a href="c3ref/sqlite3.html">database connection</a> objects and 
+<a href="c3ref/stmt.html">prepared statement</a> objects.  With this setting, the application
+is free to use SQLite from multiple threads, but it must make sure
+than no two threads try to access the same <a href="c3ref/sqlite3.html">database connection</a>
+or any <a href="c3ref/stmt.html">prepared statements</a> associated with the same 
+<a href="c3ref/sqlite3.html">database connection</a> at the same time.  Two threads can use SQLite
+at the same time, but they must use separate <a href="c3ref/sqlite3.html">database connections</a>.
+The second <a href="c3ref/c_config_covering_index_scan.html#sqliteconfigmemstatus">SQLITE_CONFIG_MEMSTATUS</a> setting disables the mechanism
+in SQLite that tracks the total size of all outstanding memory
+allocation requests.  This omits the need to mutex each call
+to <a href="c3ref/free.html">sqlite3_malloc()</a> and <a href="c3ref/free.html">sqlite3_free()</a>, which saves a huge
+number of mutex operations.  But a consequence of disabling the
+memory statistics mechanism is that the 
+<a href="c3ref/memory_highwater.html">sqlite3_memory_used()</a>, <a href="c3ref/memory_highwater.html">sqlite3_memory_highwater()</a>, and
+<a href="c3ref/hard_heap_limit64.html">sqlite3_soft_heap_limit64()</a> interfaces cease to work.
+</p>
+
+<p>SQLite uses pthreads for its mutex implementation on Unix and
+SQLite requires a recursive mutex.  Most modern pthread implementations
+support recursive mutexes, but not all do.  For systems that do not
+support recursive mutexes, it is recommended that applications operate
+in single-threaded mode only.  If this is not possible, SQLite provides
+an alternative recursive mutex implementation built on top of the
+standard "fast" mutexes of pthreads.  This alternative
+implementation should work correctly as long as pthread_equal() is
+atomic and the processor has a coherent data cache.  The alternative
+recursive mutex implementation is enabled by the following
+compiler command-line switch:</p>
+
+<blockquote><pre>
+-DSQLITE_HOMEGROWN_RECURSIVE_MUTEX=1
+</pre></blockquote>
+
+<p>When porting SQLite to a new operating system, it is usually necessary
+to completely replace the built-in mutex subsystem with an alternative
+built around the mutex primitives of the new operating system.  This
+is accomplished by compiling SQLite with the following option:</p>
+
+<blockquote><pre>
+-DSQLITE_MUTEX_APPDEF=1
+</pre></blockquote>
+
+<p>When SQLite is compiled with the SQLITE_MUTEX_APPDEF=1 option, it
+completely omits the implementation of its 
+<a href="c3ref/mutex_alloc.html">mutex primitive functions</a>.  But the SQLite
+library still attempts to call these functions where necessary, so the
+application must itself implement the
+<a href="c3ref/mutex_alloc.html">mutex primitive functions</a> and link them together
+with SQLite.</p>
+
+<h2>3.0 Configuring Or Replacing The Memory Allocation Subsystem</h2>
+
+<p>By default, SQLite obtains the memory it needs for objects and
+cache from the malloc()/free() implementation of the standard library.
+There is also on-going work with experimental memory allocators that
+satisfy all memory requests from a single fixed memory buffer handed
+to SQLite at application start.  Additional information on these
+experimental memory allocators will be provided in a future revision
+of this document.</p>
+
+<p>SQLite supports the ability of an application to specify an alternative
+memory allocator at run-time by filling in an instance of the
+<a href="c3ref/mem_methods.html">sqlite3_mem_methods</a> object with pointers to the routines of the
+alternative implementation then registering the new alternative
+implementation using the <a href="c3ref/config.html">sqlite3_config()</a> interface.
+For example:</p>
+
+<blockquote><pre>
+sqlite3_config(SQLITE_CONFIG_MALLOC, &my_malloc_implementation);
+</pre></blockquote>
+
+<p>SQLite makes a copy of the content of the <a href="c3ref/mem_methods.html">sqlite3_mem_methods</a> object
+so the object can be modified after the <a href="c3ref/config.html">sqlite3_config()</a> call returns.</p>
+
+<h2>4.0 Adding New Virtual File Systems</h2>
+
+<p>Since <a href="releaselog/3_5_0.html">version 3.5.0</a> (2007-09-04), 
+SQLite has supported an interface called the
+<a href="c3ref/vfs.html">virtual file system</a> or "VFS".
+This object is somewhat misnamed since it
+is really an interface to the whole underlying operating system, not
+just the filesystem.</p>
+
+<p> One of the interesting features
+of the VFS interface is that SQLite can support multiple VFSes at the
+same time.  Each <a href="c3ref/sqlite3.html">database connection</a> has to choose a single VFS for its
+use when the connection is first opened using <a href="c3ref/open.html">sqlite3_open_v2()</a>.
+But if a process contains multiple <a href="c3ref/sqlite3.html">database connections</a> each can choose
+a different VFS.  VFSes can be added at run-time using the
+<a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a> interface.</p>
+
+<p>The default builds for SQLite on Unix, Windows, and OS/2 include 
+a VFS appropriate for the target platform.  SQLite builds for other
+operating systems do not contain a VFS by default, but the application
+can register one or more at run-time.</p>
+
+<h2>5.0 Porting SQLite To A New Operating System</h2>
+
+<p>In order to port SQLite to a new operating system - an operating
+system not supported by default - the application
+must provide...</p>
+
+<ul>
+<li> a working mutex subsystem (but only if it is multithreaded), </li>
+<li> a working memory allocation subsystem (assuming it lacks malloc()
+in its standard library), and</li>
+<li> a working VFS implementation.</li>
+</ul>
+
+<p>All of these things can be provided in a single auxiliary C code file
+and then linked with the stock "sqlite3.c" code file to generate a working
+SQLite build for the target operating system.  In addition to the
+alternative mutex and memory allocation subsystems and the new VFS,
+the auxiliary C code file should contain implementations for the
+following two routines:</p>
+
+<ul>
+<li> <a href="c3ref/initialize.html">sqlite3_os_init()</a> </li>
+<li> <a href="c3ref/initialize.html">sqlite3_os_end()</a> </li>
+</ul>
+
+<p>The "sqlite3.c" code file contains default implementations of a VFS
+and of the <a href="c3ref/initialize.html">sqlite3_initialize()</a> and <a href="c3ref/initialize.html">sqlite3_shutdown()</a> functions that
+are appropriate for Unix, Windows, and OS/2.
+To prevent one of these default components from being loaded when sqlite3.c
+is compiled, it is necessary to add the following compile-time
+option:</p>
+
+<blockquote><pre>
+-DSQLITE_OS_OTHER=1
+</pre></blockquote>
+
+
+<p>The SQLite core will call <a href="c3ref/initialize.html">sqlite3_initialize()</a> early.  The auxiliary
+C code file can contain an implementation of sqlite3_initialize() that
+registers an appropriate VFS and also perhaps initializes an alternative
+mutex system (if mutexes are required) or does any memory allocation
+subsystem initialization that is required.
+The SQLite core never calls <a href="c3ref/initialize.html">sqlite3_shutdown()</a> but it is part of the
+official SQLite API and is not otherwise provided when compiled with
+-DSQLITE_OS_OTHER=1, so the auxiliary C code file should probably provide
+it for completeness.</p>
+<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/custombuild.in?m=681be6b966409b3f6">2021-11-17 15:30:21</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/custombuild.html
parent	Initial commit. (diff)
download	sqlite3-upstream.tar.xz sqlite3-upstream.zip