diff options
Diffstat (limited to 'www/custombuild.html')
| -rw-r--r-- | www/custombuild.html | 403 |
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> + |