379 lines
16 KiB
HTML
379 lines
16 KiB
HTML
|
<!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;
|
||
|
|
}
|
||
|
|
</script>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<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 togethr 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>
|
||
|
|
|