Documentation Source Text

Check-in [37edbace2a]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Further miscellaneous documentation improvements.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 37edbace2aaffec6bbb8625bff3edb99f5bb2ff7
User & Date: drh 2009-08-19 15:55:52.000
Context
2009-08-22
02:53
Updates to the query planner documentation. (check-in: ded8a7f88c user: drh tags: trunk)
2009-08-19
15:55
Further miscellaneous documentation improvements. (check-in: 37edbace2a user: drh tags: trunk)
13:54
Fix a typo in the documentation of INSERT. Ticket [e07f262a63441]. (check-in: 6fbc1f9707 user: drh tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to pages/capi3ref.in.
328
329
330
331
332
333
334
335
336

337
338
339
340
341
342
343

<p>Stable interfaces will be maintained indefinitely in a backwards
compatible way.  An application that uses only stable interfaces
should always be able to relink against a newer version of SQLite
without any changes.</p>

<p>Experiemental interfaces are subject to change.  
Applications that use experiemental interfaces
may need to be modified when upgrading to a newer SQLite release.

When new interfaces are added to SQLite, they generally begin
as experimental interfaces.  After an interface has been in use for
a while and the developers are confident that the design of the interface
is sound and worthy of long-term support, the interface is marked
as stable.</p>

<p>Deprecated interfaces have been superceded by better methods of







|
|
>







328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344

<p>Stable interfaces will be maintained indefinitely in a backwards
compatible way.  An application that uses only stable interfaces
should always be able to relink against a newer version of SQLite
without any changes.</p>

<p>Experiemental interfaces are subject to change.  
Applications that use experimental interfaces
may need to be modified when upgrading to a newer SQLite release, though
this is rare.
When new interfaces are added to SQLite, they generally begin
as experimental interfaces.  After an interface has been in use for
a while and the developers are confident that the design of the interface
is sound and worthy of long-term support, the interface is marked
as stable.</p>

<p>Deprecated interfaces have been superceded by better methods of
Changes to pages/cintro.in.
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
  A separate document, [capi3ref | The SQLite C/C++ Interface],
  provides detailed
  specifications for all of the various C/C++ APIs for SQLite.  Once
  the reader
  understands the basic principles of operation for SQLite, 
  [capi3ref | that document] should be used as a reference
  guide.  This article is intended as introduction only and is neither a
  complete or authoritative reference for the SQLite API.
</p>

<tcl>HEADING 1 {Core Objects And Interfaces}</tcl>

<p>
  The principal task of an SQL database engine is to evaluate statements
  of SQL.  In order to accomplish this purpose, the developer needs







|







58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
  A separate document, [capi3ref | The SQLite C/C++ Interface],
  provides detailed
  specifications for all of the various C/C++ APIs for SQLite.  Once
  the reader
  understands the basic principles of operation for SQLite, 
  [capi3ref | that document] should be used as a reference
  guide.  This article is intended as introduction only and is neither a
  complete nor authoritative reference for the SQLite API.
</p>

<tcl>HEADING 1 {Core Objects And Interfaces}</tcl>

<p>
  The principal task of an SQL database engine is to evaluate statements
  of SQL.  In order to accomplish this purpose, the developer needs
Changes to pages/custombuild.in.
1

2

3
4
5
6
7
8
9
10
11
12
13
<title>Custom Builds Of SQLite 3.6</title>



<h1 align="center">
Custom Builds Of SQLite Version 3.6<br>
or<br>
Porting SQLite 3.6 To New Operating Systems Or Unusual Platforms
</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
|
>

>

|

|







1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<title>Custom Builds Of SQLite</title>
<tcl>hd_keywords {porting SQLite} {custom builds}</tcl>


<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
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
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> [sqlite3_initialize()] </li>
<li> [sqlite3_shutdown()] </li>
</ul>

<p>The "sqlite3.c" code file contains default implementations of a VFS
and of the [sqlite3_initialize()] and [sqlite3_shutdown()] 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>

<p>The SQLite core will call [sqlite3_initialize()] 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 [sqlite3_shutdown()] 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>







|
|













<










<
<
<
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288

289
290
291
292
293
294
295
296
297
298



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> [sqlite3_os_init()] </li>
<li> [sqlite3_os_end()] </li>
</ul>

<p>The "sqlite3.c" code file contains default implementations of a VFS
and of the [sqlite3_initialize()] and [sqlite3_shutdown()] 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 [sqlite3_initialize()] 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 [sqlite3_shutdown()] 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>



Changes to pages/docs.in.
151
152
153
154
155
156
157





158
159
160
161
162
163
164
165
166
167
168
169
170





171
172
173
174
175
176
177
doc {Temporary Files Used By SQLite} {tempfiles.html} {
  SQLite can potentially use many different temporary files when
  processing certain SQL statements.  This document describes the
  many kinds of temporary files that SQLite uses and offers suggestions
  for avoiding them on systems where creating a temporary file is an
  expensive operation.
}






doc {How SQLite Implements Atomic Commit} {atomiccommit.html} {
  A description of the logic within SQLite that implements
  transactions with atomic commit, even in the face of power
  failures.
}

doc {Dynamic Memory Allocation in SQLite} {malloc.html} {
  SQLite has a sophisticated memory allocation subsystem that can be
  configured and customized to meet memory usage requirements of the
  application and that is robust against out-of-memory conditions and
  leak-free.  This document provides the details.
}






doc {Locking And Concurrency<br>In SQLite Version 3} {lockingv3.html} {
  A description of how the new locking code in version 3 increases
  concurrency and decreases the problem of writer starvation.
}

doc {Overview Of The Optimizer} {optoverview.html} {







>
>
>
>
>













>
>
>
>
>







151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
doc {Temporary Files Used By SQLite} {tempfiles.html} {
  SQLite can potentially use many different temporary files when
  processing certain SQL statements.  This document describes the
  many kinds of temporary files that SQLite uses and offers suggestions
  for avoiding them on systems where creating a temporary file is an
  expensive operation.
}

doc {In-Memory Databases} {inmemorydb.html} {
  SQLite normally stores content in a disk file.  However, it can also
  be used as an in-memory database engine.  This document explains how.
}

doc {How SQLite Implements Atomic Commit} {atomiccommit.html} {
  A description of the logic within SQLite that implements
  transactions with atomic commit, even in the face of power
  failures.
}

doc {Dynamic Memory Allocation in SQLite} {malloc.html} {
  SQLite has a sophisticated memory allocation subsystem that can be
  configured and customized to meet memory usage requirements of the
  application and that is robust against out-of-memory conditions and
  leak-free.  This document provides the details.
}

doc {Customizing And Porting SQLite} {custombuild.html} {
  This document explains how to customize the build of SQLite and
  how to port SQLite to new platforms.
}

doc {Locking And Concurrency<br>In SQLite Version 3} {lockingv3.html} {
  A description of how the new locking code in version 3 increases
  concurrency and decreases the problem of writer starvation.
}

doc {Overview Of The Optimizer} {optoverview.html} {
Changes to pages/malloc.in.
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211

<p>The default memory allocation settings in SQLite are appropriate
for most applications.  However, applications with unusual or particularly
strict requirements may want to adjust the configuration to more closely
align SQLite to their needs.
Both compile-time and start-time configuration options are available.</p>

<a name="altalloc"></a>
<h3>3.1 Alternative low-level memory allocators</h3>

<p>The SQLite source code includes several different memory allocation
modules that can be selected at compile-time, or to a limited extent
at start-time.</p>

<tcl>hd_fragment defaultalloc {default memory allocator}</tcl>







|







197
198
199
200
201
202
203
204
205
206
207
208
209
210
211

<p>The default memory allocation settings in SQLite are appropriate
for most applications.  However, applications with unusual or particularly
strict requirements may want to adjust the configuration to more closely
align SQLite to their needs.
Both compile-time and start-time configuration options are available.</p>

<tcl>hd_fragment altalloc {built-in memory allocators}</tcl>
<h3>3.1 Alternative low-level memory allocators</h3>

<p>The SQLite source code includes several different memory allocation
modules that can be selected at compile-time, or to a limited extent
at start-time.</p>

<tcl>hd_fragment defaultalloc {default memory allocator}</tcl>