Debian Codegraph @

www/custombuild.html

raw
1 <!DOCTYPE html>
2 <html><head>
3 <meta name="viewport" content="width=device-width, initial-scale=1.0">
4 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
5 <link href="sqlite.css" rel="stylesheet">
6 <title>Custom Builds Of SQLite</title>
7 <!-- path= -->
8 </head>
9 <body>
10 <div class=nosearch>
11 <a href="index.html">
12 <img class="logo" src="images/sqlite370_banner.svg" alt="SQLite" border="0">
13 </a>
14 <div><!-- IE hack to prevent disappearing logo --></div>
15 <div class="tagline desktoponly">
16 Small. Fast. Reliable.<br>Choose any three.
17 </div>
18 <div class="menu mainmenu">
19 <ul>
20 <li><a href="index.html">Home</a>
21 <li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
22 <li class='wideonly'><a href='about.html'>About</a>
23 <li class='desktoponly'><a href="docs.html">Documentation</a>
24 <li class='desktoponly'><a href="download.html">Download</a>
25 <li class='wideonly'><a href='copyright.html'>License</a>
26 <li class='desktoponly'><a href="support.html">Support</a>
27 <li class='desktoponly'><a href="prosupport.html">Purchase</a>
28 <li class='search' id='search_menubutton'>
29 <a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
30 </ul>
31 </div>
32 <div class="menu submenu" id="submenu">
33 <ul>
34 <li><a href='about.html'>About</a>
35 <li><a href='docs.html'>Documentation</a>
36 <li><a href='download.html'>Download</a>
37 <li><a href='support.html'>Support</a>
38 <li><a href='prosupport.html'>Purchase</a>
39 </ul>
40 </div>
41 <div class="searchmenu" id="searchmenu">
42 <form method="GET" action="search">
43 <select name="s" id="searchtype">
44 <option value="d">Search Documentation</option>
45 <option value="c">Search Changelog</option>
46 </select>
47 <input type="text" name="q" id="searchbox" value="">
48 <input type="submit" value="Go">
49 </form>
50 </div>
51 </div>
52 <script>
53 function toggle_div(nm) {
54 var w = document.getElementById(nm);
55 if( w.style.display=="block" ){
56 w.style.display = "none";
57 }else{
58 w.style.display = "block";
59 }
60 }
61 function toggle_search() {
62 var w = document.getElementById("searchmenu");
63 if( w.style.display=="block" ){
64 w.style.display = "none";
65 } else {
66 w.style.display = "block";
67 setTimeout(function(){
68 document.getElementById("searchbox").focus()
69 }, 30);
70 }
71 }
72 function div_off(nm){document.getElementById(nm).style.display="none";}
73 window.onbeforeunload = function(e){div_off("submenu");}
74 /* Disable the Search feature if we are not operating from CGI, since */
75 /* Search is accomplished using CGI and will not work without it. */
76 if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
77 document.getElementById("search_menubutton").style.display = "none";
78 }
79 /* Used by the Hide/Show button beside syntax diagrams, to toggle the */
80 function hideorshow(btn,obj){
81 var x = document.getElementById(obj);
82 var b = document.getElementById(btn);
83 if( x.style.display!='none' ){
84 x.style.display = 'none';
85 b.innerHTML='show';
86 }else{
87 x.style.display = '';
88 b.innerHTML='hide';
89 }
90 return false;
91 }
92 var antiRobot = 0;
93 function antiRobotGo(){
94 if( antiRobot!=3 ) return;
95 antiRobot = 7;
96 var j = document.getElementById("mtimelink");
97 if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
98 }
99 function antiRobotDefense(){
100 document.body.onmousedown=function(){
101 antiRobot |= 2;
102 antiRobotGo();
103 document.body.onmousedown=null;
104 }
105 document.body.onmousemove=function(){
106 antiRobot |= 2;
107 antiRobotGo();
108 document.body.onmousemove=null;
109 }
110 setTimeout(function(){
111 antiRobot |= 1;
112 antiRobotGo();
113 }, 100)
114 antiRobotGo();
115 }
116 antiRobotDefense();
117 </script>
118
119
120
121
122 <h1 align="center">
123 Custom Builds Of SQLite<br>
124 or<br>
125 Porting SQLite To New Operating Systems
126 </h1>
127
128 <h2>1.0 Introduction</h2>
129
130 <p>For most applications, the recommended method for building
131 SQLite is to use <a href="amalgamation.html">the amalgamation</a> code
132 file, <b>sqlite3.c</b>, and its corresponding header file
133 <b>sqlite3.h</b>. The sqlite3.c code file should compile and
134 run on any Unix, Windows system without any changes
135 or special compiler options. Most applications can simply include
136 the sqlite3.c file together with the other C code files that make
137 up the application, compile them all together, and have a working
138 and well configured version of SQLite.</p>
139
140 <blockquote><i>Most applications work great with SQLite in its
141 default configuration and with no special compile-time configuration.
142 Most developers should be able to completely ignore this document
143 and simply build SQLite from
144 <a href="amalgamation.html">the amalgamation</a> without any
145 special knowledge and without taking any special actions.</i></blockquote>
146
147 <p>However, highly tuned and specialized
148 applications may want or need to replace some of
149 SQLite's built-in system interfaces with alternative implementations
150 more suitable for the needs of the application. SQLite is designed
151 to be easily reconfigured at compile-time to meet the specific
152 needs of individual projects. Among the compile-time configuration
153 options for SQLite are these:</p>
154
155 <ul>
156 <li><p> Replace the built-in mutex subsystem with an alternative
157 implementation. </p></li>
158
159 <li><p> Completely disable all mutexing for use in single-threaded
160 applications. </p></li>
161
162 <li><p> Reconfigure the memory allocation subsystem to use a memory
163 allocator other the malloc() implementation from the standard
164 library. </p></li>
165
166 <li><p> Realign the memory allocation subsystem so that it never calls
167 malloc() at all but instead satisfies all memory requests using
168 a fixed-size memory buffer assigned to SQLite at startup. </p></li>
169
170 <li><p> Replace the interface to the file system with an alternative
171 design. In other words, override all of the system calls that
172 SQLite makes in order to talk to the disk with a completely different
173 set of system calls. </p></li>
174
175 <li><p> Override other operating system interfaces such as calls to obtain
176 Zulu or local time. </p></li>
177 </ul>
178
179 <p>Generally speaking, there are three separate subsystems within
180 SQLite that can be modified or overridden at compile-time. The
181 mutex subsystem is used to serialize access to SQLite resources that
182 are shared among threads. The memory allocation subsystem is used
183 to allocate memory required by SQLite objects and for the database
184 cache. Finally, the <a href="c3ref/vfs.html">Virtual File System</a> subsystem is
185 used to provide a portable interface between SQLite and the underlying
186 operating system and especially the file system. We call these three
187 subsystems the "interface" subsystems of SQLite.</p>
188
189 <p>We emphasis that most applications are well-served by the
190 built-in default implementations of the SQLite interface subsystems.
191 Developers are encouraged to use the
192 default built-in implementations whenever possible
193 and to build SQLite without any special compile-time options or parameters.
194 However, some highly specialized applications may benefit from
195 substituting or modifying one or more of these built-in SQLite
196 interface subsystems.
197 Or, if SQLite is used on an operating system other than
198 Unix (Linux or Mac OS X), Windows (Win32 or WinCE), or OS/2 then none
199 of the interface subsystems that come built into SQLite will work
200 and the application will need to provide alternative implementations
201 suitable for the target platform.</p>
202
203 <h2>2.0 Configuring Or Replacing The Mutex Subsystem</h2>
204
205 <p>In a multithreaded environment, SQLite uses mutexes to serialize
206 access to shared resources.
207 The mutex subsystem is only required for applications that access
208 SQLite from multiple threads. For single-threaded applications, or
209 applications which only call SQLite from a single thread, the mutex
210 subsystem can be completely disabled by recompiling with the following
211 option:</p>
212
213 <blockquote><pre>
214 -DSQLITE_THREADSAFE=0
215 </pre></blockquote>
216
217 <p>Mutexes are cheap but they are not free, so performance will be better
218 when mutexes are completely disabled. The resulting library footprint
219 will also be a little smaller. Disabling the mutexes at compile-time
220 is a recommended optimization for applications where it makes sense.</p>
221
222 <p>When using SQLite as a shared library, an application can test to see
223 whether or not mutexes have been disabled using the
224 <a href="c3ref/threadsafe.html">sqlite3_threadsafe()</a> API. Applications that link against SQLite at
225 run-time and use SQLite from multiple threads should probably check this
226 API to make sure they did not accidentally get linked against a version of
227 the SQLite library that has its mutexes disabled. Single-threaded
228 applications will, of course, work correctly regardless of whether or
229 not SQLite is configured to be threadsafe, though they will be a little
230 bit faster when using versions of SQLite with mutexes disabled.</p>
231
232 <p>SQLite mutexes can also be disabled at run-time using the
233 <a href="c3ref/config.html">sqlite3_config()</a> interface. To completely disable all mutexing,
234 the application can invoke:</p>
235
236 <blockquote><pre>
237 sqlite3_config(SQLITE_CONFIG_SINGLETHREAD);
238 </pre></blockquote>
239
240 <p>Disabling mutexes at run-time is not as effective as disabling them
241 at compile-time since SQLite still must do a test of a boolean variable
242 to see if mutexes are enabled or disabled at each point where a mutex
243 might be required. But there is still a performance advantage for
244 disabling mutexes at run-time.</p>
245
246 <p>For multi-threaded applications that are careful about how they
247 manage threads, SQLite supports an alternative run-time configuration
248 that is half way between not using any mutexes and the default situation
249 of mutexing everything in sight. This in-the-middle mutex alignment can
250 be established as follows:</p>
251
252 <blockquote><pre>
253 sqlite3_config(SQLITE_CONFIG_MULTITHREAD);
254 sqlite3_config(SQLITE_CONFIG_MEMSTATUS, 0);
255 </pre></blockquote>
256
257 <p>There are two separate configuration changes here which can
258 be used either together or separately. The
259 <a href="c3ref/c_config_covering_index_scan.html#sqliteconfigmultithread">SQLITE_CONFIG_MULTITHREAD</a> setting disables the mutexes that
260 serialize access to <a href="c3ref/sqlite3.html">database connection</a> objects and
261 <a href="c3ref/stmt.html">prepared statement</a> objects. With this setting, the application
262 is free to use SQLite from multiple threads, but it must make sure
263 than no two threads try to access the same <a href="c3ref/sqlite3.html">database connection</a>
264 or any <a href="c3ref/stmt.html">prepared statements</a> associated with the same
265 <a href="c3ref/sqlite3.html">database connection</a> at the same time. Two threads can use SQLite
266 at the same time, but they must use separate <a href="c3ref/sqlite3.html">database connections</a>.
267 The second <a href="c3ref/c_config_covering_index_scan.html#sqliteconfigmemstatus">SQLITE_CONFIG_MEMSTATUS</a> setting disables the mechanism
268 in SQLite that tracks the total size of all outstanding memory
269 allocation requests. This omits the need to mutex each call
270 to <a href="c3ref/free.html">sqlite3_malloc()</a> and <a href="c3ref/free.html">sqlite3_free()</a>, which saves a huge
271 number of mutex operations. But a consequence of disabling the
272 memory statistics mechanism is that the
273 <a href="c3ref/memory_highwater.html">sqlite3_memory_used()</a>, <a href="c3ref/memory_highwater.html">sqlite3_memory_highwater()</a>, and
274 <a href="c3ref/hard_heap_limit64.html">sqlite3_soft_heap_limit64()</a> interfaces cease to work.
275 </p>
276
277 <p>SQLite uses pthreads for its mutex implementation on Unix and
278 SQLite requires a recursive mutex. Most modern pthread implementations
279 support recursive mutexes, but not all do. For systems that do not
280 support recursive mutexes, it is recommended that applications operate
281 in single-threaded mode only. If this is not possible, SQLite provides
282 an alternative recursive mutex implementation built on top of the
283 standard "fast" mutexes of pthreads. This alternative
284 implementation should work correctly as long as pthread_equal() is
285 atomic and the processor has a coherent data cache. The alternative
286 recursive mutex implementation is enabled by the following
287 compiler command-line switch:</p>
288
289 <blockquote><pre>
290 -DSQLITE_HOMEGROWN_RECURSIVE_MUTEX=1
291 </pre></blockquote>
292
293 <h2>3.0 Configuring Or Replacing The Memory Allocation Subsystem</h2>
294
295 <p>By default, SQLite obtains the memory it needs for objects and
296 cache from the malloc()/free() implementation of the standard library.
297 There is also on-going work with experimental memory allocators that
298 satisfy all memory requests from a single fixed memory buffer handed
299 to SQLite at application start. Additional information on these
300 experimental memory allocators will be provided in a future revision
301 of this document.</p>
302
303 <p>SQLite supports the ability of an application to specify an alternative
304 memory allocator at run-time by filling in an instance of the
305 <a href="c3ref/mem_methods.html">sqlite3_mem_methods</a> object with pointers to the routines of the
306 alternative implementation then registering the new alternative
307 implementation using the <a href="c3ref/config.html">sqlite3_config()</a> interface.
308 For example:</p>
309
310 <blockquote><pre>
311 sqlite3_config(SQLITE_CONFIG_MALLOC, &my_malloc_implementation);
312 </pre></blockquote>
313
314 <p>SQLite makes a copy of the content of the <a href="c3ref/mem_methods.html">sqlite3_mem_methods</a> object
315 so the object can be modified after the <a href="c3ref/config.html">sqlite3_config()</a> call returns.</p>
316
317 <h2>4.0 Adding New Virtual File Systems</h2>
318
319 <p>Since <a href="releaselog/3_5_0.html">version 3.5.0</a> (2007-09-04),
320 SQLite has supported an interface called the
321 <a href="c3ref/vfs.html">virtual file system</a> or "VFS".
322 This object is somewhat misnamed since it
323 is really an interface to the whole underlying operating system, not
324 just the filesystem.</p>
325
326 <p> One of the interesting features
327 of the VFS interface is that SQLite can support multiple VFSes at the
328 same time. Each <a href="c3ref/sqlite3.html">database connection</a> has to choose a single VFS for its
329 use when the connection is first opened using <a href="c3ref/open.html">sqlite3_open_v2()</a>.
330 But if a process contains multiple <a href="c3ref/sqlite3.html">database connections</a> each can choose
331 a different VFS. VFSes can be added at run-time using the
332 <a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a> interface.</p>
333
334 <p>The default builds for SQLite on Unix, Windows, and OS/2 include
335 a VFS appropriate for the target platform. SQLite builds for other
336 operating systems do not contain a VFS by default, but the application
337 can register one or more at run-time.</p>
338
339 <h2>5.0 Porting SQLite To A New Operating System</h2>
340
341 <p>In order to port SQLite to a new operating system - an operating
342 system not supported by default - the application
343 must provide...</p>
344
345 <ul>
346 <li> a working mutex subsystem (but only if it is multithreaded), </li>
347 <li> a working memory allocation subsystem (assuming it lacks malloc()
348 in its standard library), and</li>
349 <li> a working VFS implementation.</li>
350 </ul>
351
352 <p>All of these things can be provided in a single auxiliary C code file
353 and then linked with the stock "sqlite3.c" code file to generate a working
354 SQLite build for the target operating system. In addition to the
355 alternative mutex and memory allocation subsystems and the new VFS,
356 the auxiliary C code file should contain implementations for the
357 following two routines:</p>
358
359 <ul>
360 <li> <a href="c3ref/initialize.html">sqlite3_os_init()</a> </li>
361 <li> <a href="c3ref/initialize.html">sqlite3_os_end()</a> </li>
362 </ul>
363
364 <p>The "sqlite3.c" code file contains default implementations of a VFS
365 and of the <a href="c3ref/initialize.html">sqlite3_initialize()</a> and <a href="c3ref/initialize.html">sqlite3_shutdown()</a> functions that
366 are appropriate for Unix, Windows, and OS/2.
367 To prevent one of these default components from being loaded when sqlite3.c
368 is compiled, it is necessary to add the following compile-time
369 option:</p>
370
371 <blockquote><pre>
372 -DSQLITE_OS_OTHER=1
373 </pre></blockquote>
374
375
376 <p>The SQLite core will call <a href="c3ref/initialize.html">sqlite3_initialize()</a> early. The auxiliary
377 C code file can contain an implementation of sqlite3_initialize() that
378 registers an appropriate VFS and also perhaps initializes an alternative
379 mutex system (if mutexes are required) or does any memory allocation
380 subsystem initialization that is required.
381 The SQLite core never calls <a href="c3ref/initialize.html">sqlite3_shutdown()</a> but it is part of the
382 official SQLite API and is not otherwise provided when compiled with
383 -DSQLITE_OS_OTHER=1, so the auxiliary C code file should probably provide
384 it for completeness.</p>
385 <p align="center"><small><i>This page was last updated on 2026-03-24 11:35:08Z </small></i></p>
386