/ Check-in [5efa2d2a]
Login

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

Overview
Comment:Add a documentation page for compilation options. Still some work to go. (CVS 2117)
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 5efa2d2a602c3b7249c4e6701e97b16b5ad0280d
User & Date: danielk1977 2004-11-20 06:05:56
Context
2004-11-20
08:17
Documentation for REINDEX and ALTER TABLE commands. (CVS 2118) check-in: aceaa5f6 user: danielk1977 tags: trunk
06:05
Add a documentation page for compilation options. Still some work to go. (CVS 2117) check-in: 5efa2d2a user: danielk1977 tags: trunk
2004-11-19
11:59
Split up the lang.html page into a seperate page for each command. (CVS 2116) check-in: ea315668 user: danielk1977 tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to main.mk.

480
481
482
483
484
485
486



487
488
489
490
491
492
493
...
517
518
519
520
521
522
523
524

525
526
527
528
529
530
531

vdbe.html:	$(TOP)/www/vdbe.tcl
	tclsh $(TOP)/www/vdbe.tcl >vdbe.html

version3.html:	$(TOP)/www/version3.tcl
	tclsh $(TOP)/www/version3.tcl >version3.html





# Files to be published on the website.
#
DOC = \
  arch.html \
  arch.png \
  c_interface.html \
................................................................................
  quickstart.html \
  speed.html \
  sqlite.gif \
  sqlite.html \
  support.html \
  tclsqlite.html \
  vdbe.html \
  version3.html


doc:	common.tcl $(DOC)
	mkdir -p doc
	mv $(DOC) doc

# Standard install and cleanup targets
#







>
>
>







 







|
>







480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
...
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535

vdbe.html:	$(TOP)/www/vdbe.tcl
	tclsh $(TOP)/www/vdbe.tcl >vdbe.html

version3.html:	$(TOP)/www/version3.tcl
	tclsh $(TOP)/www/version3.tcl >version3.html

compile.html:	$(TOP)/www/compile.tcl
	tclsh $(TOP)/www/compile.tcl >compile.html


# Files to be published on the website.
#
DOC = \
  arch.html \
  arch.png \
  c_interface.html \
................................................................................
  quickstart.html \
  speed.html \
  sqlite.gif \
  sqlite.html \
  support.html \
  tclsqlite.html \
  vdbe.html \
  version3.html \
  compile.html

doc:	common.tcl $(DOC)
	mkdir -p doc
	mv $(DOC) doc

# Standard install and cleanup targets
#

Changes to src/sqlite.h.in.

8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
...
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
**    May you find forgiveness for yourself and forgive others.
**    May you share freely, never taking more than you give.
**
*************************************************************************
** This header file defines the interface that the SQLite library
** presents to client programs.
**
** @(#) $Id: sqlite.h.in,v 1.122 2004/11/12 15:53:37 danielk1977 Exp $
*/
#ifndef _SQLITE3_H_
#define _SQLITE3_H_
#include <stdarg.h>     /* Needed for the definition of va_list */

/*
** Make sure we can call this stuff from C++.
................................................................................
** a log file of all SQL executed against a database.
*/
void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);

/*
** This routine configures a callback function - the progress callback - that
** is invoked periodically during long running calls to sqlite3_exec(),
** sqlite3_step() and sqlite3_get_table(). An example use for this API is to keep
** a GUI updated during a large query.
**
** The progress callback is invoked once for every N virtual machine opcodes,
** where N is the second argument to this function. The progress callback
** itself is identified by the third argument to this function. The fourth
** argument to this function is a void pointer passed to the progress callback
** function each time it is invoked.
**







|







 







|
|







8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
...
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
**    May you find forgiveness for yourself and forgive others.
**    May you share freely, never taking more than you give.
**
*************************************************************************
** This header file defines the interface that the SQLite library
** presents to client programs.
**
** @(#) $Id: sqlite.h.in,v 1.123 2004/11/20 06:05:56 danielk1977 Exp $
*/
#ifndef _SQLITE3_H_
#define _SQLITE3_H_
#include <stdarg.h>     /* Needed for the definition of va_list */

/*
** Make sure we can call this stuff from C++.
................................................................................
** a log file of all SQL executed against a database.
*/
void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);

/*
** This routine configures a callback function - the progress callback - that
** is invoked periodically during long running calls to sqlite3_exec(),
** sqlite3_step() and sqlite3_get_table(). An example use for this API is to 
** keep a GUI updated during a large query.
**
** The progress callback is invoked once for every N virtual machine opcodes,
** where N is the second argument to this function. The progress callback
** itself is identified by the third argument to this function. The fourth
** argument to this function is a void pointer passed to the progress callback
** function each time it is invoked.
**

Added www/compile.tcl.





































































































































































































































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
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
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
#
# Run this Tcl script to generate the compile.html file.
#
set rcsid {$Id: compile.tcl,v 1.1 2004/11/20 06:05:56 danielk1977 Exp $ }
source common.tcl
header {Compilation Options For SQLite}

puts {
<h1>Compilation Options For SQLite</h1>

<p>
For most purposes, SQLite can be built just fine using the default
compilation options. However, if required, the compile-time options
documented below can be used to 
<a href="#omitfeatures">omit SQLite features</a> (resulting in
a smaller compiled library size) or to change the
<a href="#defaults">default values</a> of some parameters.
</p>
<p>
Every effort has been made to ensure that the various combinations
of compilation options work harmoniously and produce a working library.
Nevertheless, it is strongly recommended that the SQLite test-suite
be executed to check for errors before using an SQLite library built
with non-standard compilation options.
</p>
<a name="defaults"></a>
<h2>Options To Set Default Parameter Values</h2>

<p><b>SQLITE_DEFAULT_AUTOVACUUM=<i>&lt;1 or 0&gt;</i></b><br>
This macro determines if SQLite creates databases with the 
<a href="pragma.html#pragma_auto_vacuum">auto-vacuum</a> 
flag set by default. The default value is 0 (do not create auto-vacuum
databases). In any case the compile-time default may be overridden by the 
"PRAGMA auto_vacuum" command.
</p>

<p><b>SQLITE_DEFAULT_PAGE_SIZE=<i>&lt;bytes&gt;</i></b><br>
This macro is used to set the default page-size used when a
database is created. The value assigned must be a power of 2. The
default value is 1024. The compile-time default may be overridden at 
runtime by the "PRAGMA page_size" command.

<p><b>SQLITE_MAX_PAGE_SIZE=<i>&lt;bytes&gt;</i></b><br>
This is used to set the maximum allowable page-size that can
be specified by the "PRAGMA page_size" command. The default value
is 8192.

<a name="omitfeatures"></a>
<h2>Options To Omit Features</h2>

<p>The following options are used to reduce the size of the compiled
library by omiting optional features. This is probably only useful
in embedded systems where space is especially tight, as even with all
features included the SQLite library is relatively small. Don't forget
to tell your compiler to optimize for binary size! (the -Os option if
using GCC).</p>

<p>The macros in this section do not require values. The following 
compilation switches all have the same effect:<br>
-DSQLITE_OMIT_ALTERTABLE<br>
-DSQLITE_OMIT_ALTERTABLE=1<br>
-DSQLITE_OMIT_ALTERTABLE=0
</p>

<p><b>SQLITE_OMIT_ALTERTABLE</b><br>
When this option is defined, the 
<a href="lang_altertable.html">ALTER TABLE</a> command is not included in the 
library. Executing an ALTER TABLE statement causes a parse error.
</p>
<p><i>TODO: Need a link here - ALTER TABLE is not documented yet</i><p>

<p><b>SQLITE_OMIT_AUTHORIZATION</b><br>
Defining this option omits the authorization callback feature from the
library. The <a href="capi3ref.html#sqlite3_set_authorizer">
sqlite3_set_authorizer()</a> API function is not present in the library.
</p>

<p><b>SQLITE_OMIT_AUTOVACUUM</b><br>
If this option is defined, the library cannot create or write to 
databases that support 
<a href="pragma.html#pragma_auto_vacuum">auto-vacuum</a>. Executing a
"PRAGMA auto_vacuum" statement is not an error, but does not return a value
or modify the auto-vacuum flag in the database file. If a database that
supports auto-vacuum is opened by a library compiled with this option, it
is automatically opened in read-only mode.
</p>

<p><b>SQLITE_OMIT_AUTOINCREMENT</b><br>
This option is used to omit the AUTOINCREMENT functionality. When this 
is macro is defined, columns declared as "INTEGER PRIMARY KEY AUTOINCREMENT"
behave in the same way as columns declared as "INTEGER PRIMARY KEY" when a 
NULL is inserted. The sqlite_sequence system table is neither created, nor
respected if it already exists.
</p>
<p><i>TODO: Need a link here - AUTOINCREMENT is not yet documented</i><p>

<p><b>SQLITE_OMIT_BLOB_LITERAL</b><br>
When this option is defined, it is not possible to specify a blob in
an SQL statement using the X'ABCD' syntax.</p> 
<p>WARNING: The VACUUM command depends on this syntax for vacuuming databases
that contain blobs, so disabling this functionality may render a database
unvacuumable.
</p>
<p><i>TODO: Need a link here - is that syntax documented anywhere?</i><p>

<p><b>SQLITE_OMIT_COMPOUND_SELECT</b><br>
This option is used to omit the compound SELECT functionality. 
<a href="lang_select.html">SELECT statements</a> that use the 
UNION, UNION ALL, INTERSECT or EXCEPT compound SELECT operators will 
cause a parse error.
</p>

<p><b>SQLITE_OMIT_CONFLICT_CLAUSE</b><br>
In the future, this option will be used to omit the 
<a href="lang_conflict.html">ON CONFLICT</a> clause from the library.
</p>

<p><b>SQLITE_OMIT_DATETIME_FUNCS</b><br>
If this option is defined, SQLite's built-in date and time manipulation
functions are omitted. Specifically, the SQL functions julianday(), date(),
time(), datetime() and strftime() are not available. The default column
values CURRENT_TIME, CURRENT_DATE and CURRENT_DATETIME are still available.
</p>

<p><b>SQLITE_OMIT_EXPLAIN</b><br>
Defining this option causes the EXPLAIN command to be omitted from the
library. Attempting to execute an EXPLAIN statement will cause a parse
error.
</p>

<p><b>SQLITE_OMIT_FLOATING_POINT</b><br>
This option is used to omit floating-point number support from the SQLite
library. When specified, specifying a floating point number as a literal 
(i.e. "1.01") results in a parse error.
</p>
<p>In the future, this option may also disable other floating point 
functionality, for example the sqlite3_result_double(), 
sqlite3_bind_double(), sqlite3_value_double() and sqlite3_column_double() 
API functions.
</p>

<p><b>SQLITE_OMIT_FOREIGN_KEY</b><br>
If this option is defined, FOREIGN KEY clauses in column declarations are
ignored.
</p>

<p><b>SQLITE_OMIT_INTEGRITY_CHECK</b><br>
This option may be used to omit the 
<a href="pragma.html#pragma_integrity_check">"PRAGMA integrity_check"</a> 
command from the compiled library.
</p>

<p><b>SQLITE_OMIT_MEMORYDB</b><br>
When this is defined, the library does not respect the special database
name ":memory:" (normally used to create an in-memory database). If 
":memory:" is passed to sqlite3_open(), a file with this name will be 
opened or created.
</p>

<p><b>SQLITE_OMIT_PAGER_PRAGMAS</b><br>
Defining this option omits pragmas related to the pager subsystem from 
the build. Currently, the 
<a href="pragma.html#pragma_default_cache_size">default_cache_size</a> and 
<a href="pragma.html#pragma_cache_size">cache_size</a> pragmas are omitted.
</p>

<p><b>SQLITE_OMIT_PRAGMA</b><br>
This option is used to omit the <a href="pragma.html">PRAGMA command</a> 
from the library. Note that it is useful to define the macros that omit
specific pragmas in addition to this, as they may also remove supporting code
in other sub-systems. This macro removes the PRAGMA command only.
</p>

<p><b>SQLITE_OMIT_PROGRESS_CALLBACK</b><br>
This option may be defined to omit the capability to issue "progress" 
callbacks during long-running SQL statements. The 
<a href="capi3ref.html#sqlite3_progress_handler">sqlite3_progress_handler()</a>
API function is not present in the library.

<p><b>SQLITE_OMIT_REINDEX</b><br>
When this option is defined, the <a href="lang_reindex.html">REINDEX</a> 
command is not included in the library. Executing a REINDEX statement causes 
a parse error.

<p><i>TODO: Need a link here - REINDEX is not documented yet</i><p>

<p><b>SQLITE_OMIT_SCHEMA_PRAGMAS</b><br>
Defining this option omits pragmas for querying the database schema from 
the build. Currently, the 
<a href="pragma.html#pragma_table_info">table_info</a>,
<a href="pragma.html#pragma_index_info">index_info</a>,
<a href="pragma.html#pragma_index_list">index_list</a> and
<a href="pragma.html#pragma_database_list">database_list</a>
pragmas are omitted.
</p>

<p><b>SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS</b><br>
Defining this option omits pragmas for querying the database schema from 
the build. Currently, the 
<a href="pragma.html#pragma_table_info">table_info</a>,
<a href="pragma.html#pragma_index_info">index_info</a>,
<a href="pragma.html#pragma_index_list">index_list</a> and
<a href="pragma.html#pragma_database_list">database_list</a>
pragmas are omitted.
</p>

<p><b>SQLITE_OMIT_TCL_VARIABLE</b><br>
<i>Document me!</i></p>

<p><b>SQLITE_OMIT_TRIGGER</b><br>
<i>Document me!</i></p>

<p><b>SQLITE_OMIT_UTF16</b><br>
<i>Document me!</i></p>

<p><b>SQLITE_OMIT_VACUUM</b><br>
When this option is defined, the <a href="lang_vacuum.html">VACUUM</a> 
command is not included in the library. Executing a VACUUM statement causes 
a parse error.
</p>

<p><b>SQLITE_OMIT_VIEW</b><br>
<i>Document me!</i></p>
}
footer $rcsid

Changes to www/docs.tcl.

1
2
3
4
5
6
7
8
9
10
11
...
105
106
107
108
109
110
111






112
113
114
# This script generates the "docs.html" page that describes various
# sources of documentation available for SQLite.
#
set rcsid {$Id: docs.tcl,v 1.7 2004/11/10 05:48:57 danielk1977 Exp $}
source common.tcl
header {SQLite Documentation}
puts {
<h2>Available Documentation</h2>
<table width="100%" cellpadding="5">
}

................................................................................

doc {VDBE Opcodes} {opcode.html} {
  This document is an automatically generated description of the various
  opcodes that the VDBE understands.  Programmers can use this document as
  a reference to better understand the output of EXPLAIN listings from
  SQLite.
}







puts {</table>}
footer $rcsid



|







 







>
>
>
>
>
>



1
2
3
4
5
6
7
8
9
10
11
...
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
# This script generates the "docs.html" page that describes various
# sources of documentation available for SQLite.
#
set rcsid {$Id: docs.tcl,v 1.8 2004/11/20 06:05:56 danielk1977 Exp $}
source common.tcl
header {SQLite Documentation}
puts {
<h2>Available Documentation</h2>
<table width="100%" cellpadding="5">
}

................................................................................

doc {VDBE Opcodes} {opcode.html} {
  This document is an automatically generated description of the various
  opcodes that the VDBE understands.  Programmers can use this document as
  a reference to better understand the output of EXPLAIN listings from
  SQLite.
}

doc {Compilation Options} {compile.html} {
  This document describes the compile time options that may be set to 
  modify the default behaviour of the library or omit optional features
  in order to reduce binary size.
}

puts {</table>}
footer $rcsid

Changes to www/pragma.tcl.

1
2
3
4
5
6
7
8
9
10
11
...
289
290
291
292
293
294
295

296
297
298
299
300
301
302
303

304
305
306
307
308
309
310
#
# Run this Tcl script to generate the pragma.html file.
#
set rcsid {$Id: pragma.tcl,v 1.4 2004/11/19 11:59:24 danielk1977 Exp $}
source common.tcl
header {Pragma statements supported by SQLite}

proc Section {name {label {}}} {
  puts "\n<hr />"
  if {$label!=""} {
    puts "<a name=\"$label\"></a>"
................................................................................
</ul>
}

Section {Pragmas to debug the library} debug

puts {
<ul>

<li><p><b>PRAGMA integrity_check;</b></p>
    <p>The command does an integrity check of the entire database.  It
    looks for out-of-order records, missing pages, malformed records, and
    corrupt indices.
    If any problems are found, then a single string is returned which is
    a description of all problems.  If everything is in order, "ok" is
    returned.</p></li>


<li><p><b>PRAGMA parser_trace = ON; </b>(1)<b>
    <br>PRAGMA parser_trace = OFF;</b> (0)</p>
    <p>Turn tracing of the SQL parser inside of the
    SQLite library on and off.  This is used for debugging.
    This only works if the library is compiled without the NDEBUG macro.
    </p></li>




|







 







>








>







1
2
3
4
5
6
7
8
9
10
11
...
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
#
# Run this Tcl script to generate the pragma.html file.
#
set rcsid {$Id: pragma.tcl,v 1.5 2004/11/20 06:05:56 danielk1977 Exp $}
source common.tcl
header {Pragma statements supported by SQLite}

proc Section {name {label {}}} {
  puts "\n<hr />"
  if {$label!=""} {
    puts "<a name=\"$label\"></a>"
................................................................................
</ul>
}

Section {Pragmas to debug the library} debug

puts {
<ul>
<a name="pragma_integrity_check"></a>
<li><p><b>PRAGMA integrity_check;</b></p>
    <p>The command does an integrity check of the entire database.  It
    looks for out-of-order records, missing pages, malformed records, and
    corrupt indices.
    If any problems are found, then a single string is returned which is
    a description of all problems.  If everything is in order, "ok" is
    returned.</p></li>

<a name="pragma_parser_trace"></a>
<li><p><b>PRAGMA parser_trace = ON; </b>(1)<b>
    <br>PRAGMA parser_trace = OFF;</b> (0)</p>
    <p>Turn tracing of the SQL parser inside of the
    SQLite library on and off.  This is used for debugging.
    This only works if the library is compiled without the NDEBUG macro.
    </p></li>