~ubuntu-branches/ubuntu/wily/sqlite3/wily

onfocus="entersearch()" onblur="leavesearch()" style="width:24ex;padding:1px 1ex; border:solid white 1px; font-size:0.9em ; font-style:italic;color:#044a64;" value="Search SQLite Docs...">

112

113

</form>

114

</div>

115

</table>

116

</div></div></div></div>

117

</td></tr></table>

118

119

120

121

122

123

124

125

Custom Builds Of SQLite<br>

126

or<br>

127

Porting SQLite To New Operating Systems

128

</h1>

129

130

<h2>1.0 Introduction</h2>

131

132

<p>For most applications, the recommended method for building

133

SQLite is to use <a href="amalgamation.html">the amalgamation</a> code

134

file, <b>sqlite3.c</b>, and its corresponding header file

135

<b>sqlite3.h</b>. The sqlite3.c code file should compile and

136

run on any Unix, Windows, OS/2, or Mac OS X system without any changes

137

or special compiler options. Most applications can simply include

138

the sqlite3.c file together with the other C code files that make

139

up the application, compile them all together, and have working

140

and well configured version of SQLite.</p>

141

142

<blockquote><i>Most applications work great with SQLite in its

143

default configuration and with no special compile-time configuration.

144

Most developers should be able to completely ignore this document

145

and simply build SQLite from

146

<a href="amalgamation.html">the amalgamation</a> without any

147

special knowledge and without taking any special actions.</i></blockquote>

148

149

<p>However, highly tuned and specialized

150

applications may want or need to replace some of

151

SQLite's built-in system interfaces with alternative implementations

152

more suitable for the needs of the application. SQLite is designed

153

to be easily reconfigured at compile-time to meet the specific

154

needs of individual projects. Among the compile-time configuration

155

options for SQLite are these:</p>

156

157

<ul>

158

<li><p> Replace the built-in mutex subsystem with an alternative

159

implementation. </p></li>

160

161

<li><p> Completely disable all mutexing for use in single-threaded

162

applications. </p></li>

163

164

<li><p> Reconfigure the memory allocation subsystem to use a memory

165

allocator other the malloc() implementation from the standard

166

library. </p></li>

167

168

<li><p> Realign the memory allocation subsystem so that it never calls

169

malloc() at all but instead satisfies all memory requests using

170

a fixed-size memory buffer assigned to SQLite at startup. </p></li>

171

172

<li><p> Replace the interface to the file system with an alternative

173

design. In other words, override all of the system calls that

174

SQLite makes in order to talk to the disk with a completely different

175

set of system calls. </p></li>

176

177

<li><p> Override other operating system interfaces such as calls to obtain

178

Zulu or local time. </p></li>

179

</ul>

180

181

<p>Generally speaking, there are three separate subsystems within

182

SQLite that can be modified or overridden at compile-time. The

183

mutex subsystem is used to serialize access to SQLite resources that

184

are shared among threads. The memory allocation subsystem is used

185

to allocate memory required by SQLite objects and for the database

186

cache. Finally, the <a href="c3ref/vfs.html">Virtual File System</a> subsystem is

187

used to provide a portable interface between SQLite and the underlying

188

operating system and especially the file system. We call these three

189

subsystems the "interface" subsystems of SQLite.</p>

190

191

<p>We emphasis that most applications are well-served by the

192

built-in default implementations of the SQLite interface subsystems.

193

Developers are encouraged to use the

194

default built-in implementations whenever possible

195

and to build SQLite without any special compile-time options or parameters.

196

However, some highly specialized applications may benefit from

197

substituting or modifying one or more of these built-in SQLite

198

interface subsystems.

199

Or, if SQLite is used on an operating system other than

200

Unix (Linux or Mac OS X), Windows (Win32 or WinCE), or OS/2 then none

201

of the interface subsystems that come built into SQLite will work

202

and the application will need to provide alternative implementations

203

suitable for the target platform.</p>

204

205

<h2>2.0 Configuring Or Replacing The Mutex Subsystem</h2>

206

207

<p>In a multithreaded environment, SQLite uses mutexes to serialize

208

access to shared resources.

209

The mutex subsystem is only required for applications that access

210

SQLite from multiple threads. For single-threaded applications, or

211

applications which only call SQLite from a single thread, the mutex

212

subsystem can be completely disabled by recompiling with the following

213

option:</p>

214

215

216

-DSQLITE_THREADSAFE=0

217

</pre></blockquote>

218

219

<p>Mutexes are cheap but they are not free, so performance will be better

220

when mutexes are completely disabled. The resulting library footprint

221

will also be a little smaller. Disabling the mutexes at compile-time

222

is a recommended optimization for applications where it makes sense.</p>

223

224

<p>When using SQLite as a shared library, an application can test to see

225

whether or not mutexes have been disabled using the

226

<a href="c3ref/threadsafe.html">sqlite3_threadsafe()</a> API. Applications that link against SQLite at

227

run-time and use SQLite from multiple threads should probably check this

228

API to make sure they did not accidentally get linked against a version of

229

the SQLite library that has its mutexes disabled. Single-threaded

230

applications will, of course, work correctly regardless of whether or

231

not SQLite is configured to be threadsafe, though they will be a little

232

bit faster when using versions of SQLite with mutexes disabled.</p>

233

234

<p>SQLite mutexes can also be disabled at run-time using the

235

<a href="c3ref/config.html">sqlite3_config()</a> interface. To completely disable all mutexing,

236

the application can invoke:</p>

237

238

239

sqlite3_config(SQLITE_CONFIG_SINGLETHREAD);

240

</pre></blockquote>

241

242

<p>Disabling mutexes at run-time is not as effective as disabling them

243

at compile-time since SQLite still must do a test of a boolean variable

244

to see if mutexes are enabled or disabled at each point where a mutex

245

might be required. But there is still a performance advantage for

246

disabling mutexes at run-time.</p>

247

248

<p>For multi-threaded applications that are careful about how they

249

manage threads, SQLite supports an alternative run-time configuration

250

that is half way between not using any mutexes and the default situation

251

of mutexing everything in sight. This in-the-middle mutex alignment can

252

be established as follows:</p>

253

254

255

sqlite3_config(SQLITE_CONFIG_MULTITHREAD);

256

sqlite3_config(SQLITE_CONFIG_MEMSTATUS, 0);

257

</pre></blockquote>

258

259

<p>There are two separate configuration changes here which can

260

be used either togethr or separately. The

261

<a href="c3ref/c_config_getmalloc.html#sqliteconfigmultithread">SQLITE_CONFIG_MULTITHREAD</a> setting disables the mutexes that

262

serialize access to <a href="c3ref/sqlite3.html">database connection</a> objects and

263

<a href="c3ref/stmt.html">prepared statement</a> objects. With this setting, the application

264

is free to use SQLite from multiple threads, but it must make sure

265

than no two threads try to access the same <a href="c3ref/sqlite3.html">database connection</a>

266

or any <a href="c3ref/stmt.html">prepared statements</a> associated with the same

267

<a href="c3ref/sqlite3.html">database connection</a> at the same time. Two threads can use SQLite

268

at the same time, but they must use separate <a href="c3ref/sqlite3.html">database connections</a>.

269

The second <a href="c3ref/c_config_getmalloc.html#sqliteconfigmemstatus">SQLITE_CONFIG_MEMSTATUS</a> setting disables the mechanism

270

in SQLite that tracks the total size of all outstanding memory

271

allocation requests. This omits the need to mutex each call

272

to <a href="c3ref/free.html">sqlite3_malloc()</a> and <a href="c3ref/free.html">sqlite3_free()</a>, which saves a huge

273

number of mutex operations. But a consequence of disabling the

274

memory statistics mechanism is that the

275

<a href="c3ref/memory_highwater.html">sqlite3_memory_used()</a>, <a href="c3ref/memory_highwater.html">sqlite3_memory_highwater()</a>, and

276

<a href="c3ref/soft_heap_limit64.html">sqlite3_soft_heap_limit64()</a> interfaces cease to work.

277

</p>

278

279

<p>SQLite uses pthreads for its mutex implementation on Unix and

280

SQLite requires a recursive mutex. Most modern pthread implementations

281

support recursive mutexes, but not all do. For systems that do not

282

support recursive mutexes, it is recommended that applications operate

283

in single-threaded mode only. If this is not possible, SQLite provides

284

an alternative recursive mutex implementation built on top of the

285

standard "fast" mutexes of pthreads. This alternative

286

implementation should work correctly as long as pthread_equal() is

287

atomic and the processor has a coherent data cache. The alternative

288

recursive mutex implementation is enabled by the following

289

compiler command-line switch:</p>

290

291

292

-DSQLITE_HOMEGROWN_RECURSIVE_MUTEX=1

293

</pre></blockquote>

294

295

<p>When porting SQLite to a new operating system, it is usually necessary

296

to completely replace the built-in mutex subsystem with an alternative

297

built around the mutex primitives of the new operating system. This

298

is accomplished by compiling SQLite with the following option:</p>

299

300

301

-DSQLITE_MUTEX_APPDEF=1

302

</pre></blockquote>

303

304

<p>When SQLite is compiled with the SQLITE_MUTEX_APPDEF=1 option, it

305

completely omits the implementation of its

306

<a href="c3ref/mutex_alloc.html">mutex primitive functions</a>. But the SQLite

307

library still attempts to call these functions where necessary, so the

308

application must itself implement the

309

<a href="c3ref/mutex_alloc.html">mutex primitive functions</a> and link them together

310

with SQLite.</p>

311

312

<h2>3.0 Configuring Or Replacing The Memory Allocation Subsystem</h2>

313

314

<p>By default, SQLite obtains the memory it needs for objects and

315

cache from the malloc()/free() implementation of the standard library.

316

There is also on-going work with experimental memory allocators that

317

satisfy all memory requests from a single fixed memory buffer handed

318

to SQLite at application start. Additional information on these

319

experimental memory allocators will be provided in a future revision

320

of this document.</p>

321

322

<p>SQLite supports the ability of an application to specify an alternative

323

memory allocator at run-time by filling in an instance of the

324

<a href="c3ref/mem_methods.html">sqlite3_mem_methods</a> object with pointers to the routines of the

325

alternative implementation then registering the new alternative

326

implementation using the <a href="c3ref/config.html">sqlite3_config()</a> interface.

327

For example:</p>

328

329

330

sqlite3_config(SQLITE_CONFIG_MALLOC, &my_malloc_implementation);

331

</pre></blockquote>

332

333

<p>SQLite makes a copy of the content of the <a href="c3ref/mem_methods.html">sqlite3_mem_methods</a> object

334

so the object can be modified after the <a href="c3ref/config.html">sqlite3_config()</a> call returns.</p>

335

336

<h2>4.0 Adding New Virtual File Systems</h2>

337

338

<p>Since <a href="releaselog/3_5_0.html">version 3.5.0</a>, SQLite has supported an interface called the

339

<a href="c3ref/vfs.html">virtual file system</a> or "VFS".

340

This object is somewhat misnamed since it

341

is really an interface to the whole underlying operating system, not

342

just the filesystem.</p>

343

344

<p> One of the interesting features

345

of the VFS interface is that SQLite can support multiple VFSes at the

346

same time. Each <a href="c3ref/sqlite3.html">database connection</a> has to choose a single VFS for its

347

use when the connection is first opened using <a href="c3ref/open.html">sqlite3_open_v2()</a>.

348

But if a process contains multiple <a href="c3ref/sqlite3.html">database connections</a> each can choose

349

a different VFS. VFSes can be added at run-time using the

350

<a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a> interface.</p>

351

352

<p>The default builds for SQLite on Unix, Windows, and OS/2 include

353

a VFS appropriate for the target platform. SQLite builds for other

354

operating systems do not contain a VFS by default, but the application

355

can register one or more at run-time.</p>

356

357

<h2>5.0 Porting SQLite To A New Operating System</h2>

358

359

<p>In order to port SQLite to a new operating system - an operating

360

system not supported by default - the application

361

must provide...</p>

362

363

<ul>

364

<li> a working mutex subsystem (but only if it is multithreaded), </li>

365

<li> a working memory allocation subsystem (assuming it lacks malloc()

366

in its standard library), and</li>

367

<li> a working VFS implementation.</li>

368

</ul>

369

370

<p>All of these things can be provided in a single auxiliary C code file

371

and then linked with the stock "sqlite3.c" code file to generate a working

372

SQLite build for the target operating system. In addition to the

373

alternative mutex and memory allocation subsystems and the new VFS,

374

the auxiliary C code file should contain implementations for the

375

following two routines:</p>

376

377

<ul>

378

<li> <a href="c3ref/initialize.html">sqlite3_os_init()</a> </li>

379

<li> <a href="c3ref/initialize.html">sqlite3_os_end()</a> </li>

380

</ul>

381

382

<p>The "sqlite3.c" code file contains default implementations of a VFS

383

and of the <a href="c3ref/initialize.html">sqlite3_initialize()</a> and <a href="c3ref/initialize.html">sqlite3_shutdown()</a> functions that

384

are appropriate for Unix, Windows, and OS/2.

385

To prevent one of these default components from being loaded when sqlite3.c

386

is compiled, it is necessary to add the following compile-time

387

option:</p>

388

389

390

-DSQLITE_OS_OTHER=1

391

</pre></blockquote>

392

393

394

<p>The SQLite core will call <a href="c3ref/initialize.html">sqlite3_initialize()</a> early. The auxiliary

395

C code file can contain an implementation of sqlite3_initialize() that

396

registers an appropriate VFS and also perhaps initializes an alternative

397

mutex system (if mutexes are required) or does any memory allocation

398

subsystem initialization that is required.

399

The SQLite core never calls <a href="c3ref/initialize.html">sqlite3_shutdown()</a> but it is part of the

400

official SQLite API and is not otherwise provided when compiled with

401

-DSQLITE_OS_OTHER=1, so the auxiliary C code file should probably provide

402

it for completeness.</p>

403