Add a documentation page for compilation options. Still some work to go. (CVS 2117)

FossilOrigin-Name: 5efa2d2a602c3b7249c4e6701e97b16b5ad0280d
2025-08-01 06:27:03 +03:00 · 2004-11-20 06:05:56 +00:00
parent cd45ab2d6f
commit 2097e949f6
7 changed files with 255 additions and 16 deletions
--- a/main.mk
+++ b/main.mk
@ -484,6 +484,9 @@ vdbe.html:	$(TOP)/www/vdbe.tcl
 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.
 #
@ -521,7 +524,8 @@ DOC = \
  support.html \
  tclsqlite.html \
  vdbe.html \
-  version3.html
+  version3.html \
+  compile.html

 doc:	common.tcl $(DOC)
 	mkdir -p doc
--- a/19
+++ b/19
@ -1,5 +1,5 @@
-C Split\sup\sthe\slang.html\spage\sinto\sa\sseperate\spage\sfor\seach\scommand.\s(CVS\s2116)
-D 2004-11-19T11:59:24
+C Add\sa\sdocumentation\spage\sfor\scompilation\soptions.\sStill\ssome\swork\sto\sgo.\s(CVS\s2117)
+D 2004-11-20T06:05:56
 F Makefile.in e747bb5ba34ccbdd81f79dcf1b2b33c02817c21d
 F Makefile.linux-gcc a9e5a0d309fa7c38e7c14d3ecf7690879d3a5457
 F README a01693e454a00cc117967e3f9fdab2d4d52e9bc1
@ -16,7 +16,7 @@ F doc/lemon.html f0f682f50210928c07e562621c3b7e8ab912a538
 F doc/report1.txt a031aaf37b185e4fa540223cb516d3bccec7eeac
 F install-sh 9d4de14ab9fb0facae2f48780b874848cbf2f895
 F ltmain.sh f6b283068efa69f06eb8aa1fe4bddfdbdeb35826
-F main.mk 57bb8fa04bc426a72b4c9cd8593049754acdf454
+F main.mk 088758a26c59b5bb60c1d8d3185b219fe7944796
 F mkdll.sh 468d4f41d3ea98221371df4825cfbffbaac4d7e4
 F mkopcodec.awk 14a794f7b206976afc416b30fe8e0fc97f3434e9
 F mkopcodeh.awk 4090944e4de0a2ccb99aa0083290f73bce4db406
@ -60,7 +60,7 @@ F src/printf.c 3d20b21cfecadacecac3fb7274e746cb81d3d357
 F src/random.c eff68e3f257e05e81eae6c4d50a51eb88beb4ff3
 F src/select.c cf4b7952d6d214931c52636ee726f19ee2a275c5
 F src/shell.c 55adda3cf3c1cc2f6c1919aac17b2318f9c2a96f
-F src/sqlite.h.in a44eac0716bf4751447160d5c8ed049ece66d45a
+F src/sqlite.h.in 6d0e82c24ef3f84a10b468119f3943a5dfc806c7
 F src/sqliteInt.h dd26056a172a5d488a78846b5ed8db6953db4e5d
 F src/table.c 25b3ff2b39b7d87e8d4a5da0713d68dfc06cbee9
 F src/tclsqlite.c 7f1a1a678140e6901c8954590ca2aabe50b48f71
@ -230,13 +230,14 @@ F www/capi3.tcl 5c1cb163f4d2a54e2d0e22dcc399dd71245c8b89
 F www/capi3ref.tcl 28e70284fb1a833dbc513b9972cb0a245d4a7d60
 F www/changes.tcl f2b34859843d9f06a0611eb6d44af767891b09ef
 F www/common.tcl de758130d54d95d151ea0d17a2ae5b92e1bb01de
+F www/compile.tcl b13d9a7a138ca9dae738140b777c5485521c4275
 F www/conflict.tcl cdd0f4b59b0ba6d61f67e6a38f3ae45853bacb30
 F www/copyright-release.html 294e011760c439c44951a6bfecd4c81a1ae359e8
 F www/copyright-release.pdf cfca3558fc97095e57c6117d08f1f5b80d95125a
 F www/copyright.tcl 82c9670c7ddb0311912ab7fe24703f33c531066c
 F www/datatype3.tcl 1d14f70ab73075556b95e76a5c13e5b03f7f6c47
 F www/datatypes.tcl 7c786d2e8ff434346764534ec015966d17efce60
-F www/docs.tcl 90de269f52212eb15534553faf6f1588ad77cd45
+F www/docs.tcl 95ec3aac01fe0ff514509a6478b239973eb10c8e
 F www/download.tcl 4d8ff8c882063b864d004c524e4e7456858f09a5
 F www/dynload.tcl 02eb8273aa78cfa9070dd4501dca937fb22b466c
 F www/faq.tcl abe360e630d8134bc6242c5e3664969c397eac6e
@ -250,7 +251,7 @@ F www/nulls.tcl ec35193f92485b87b90a994a01d0171b58823fcf
 F www/oldnews.tcl 7aa4478e64631859770a5fe4b413919ba6ee8a08
 F www/omitted.tcl 7bd62b6f0f53b60c5360895b16b3af8407bbca03
 F www/opcode.tcl dafa030a5a3cc24a2f9fd4cfbfb7d7323d2151b0
-F www/pragma.tcl ac3b063e1d5469a3340e2ec9c78002f2b0689e11
+F www/pragma.tcl 9e22b9d8954677a2fa842997095aea2b430fd2d3
 F www/quickstart.tcl 6f6f694b6139be2d967b1492eb9a6bdf7058aa60
 F www/speed.tcl de99c82c4729a10b6733463636f15473c4ec95bc
 F www/sqlite.tcl b51fd15f0531a54874de785a9efba323eecd5975
@ -259,7 +260,7 @@ F www/tclsqlite.tcl 560ecd6a916b320e59f2917317398f3d59b7cc25
 F www/vdbe.tcl 095f106d93875c94b47367384ebc870517431618
 F www/version3.tcl 092a01f5ef430d2c4acc0ae558d74c4bb89638a0
 F www/whentouse.tcl fdacb0ba2d39831e8a6240d05a490026ad4c4e4c
-P f635b6aae661ac85eec49b197f3bb4b85172a457
-R 5e048ff91d520585e56ae5397d6a90ed
+P ea315668e5833befe296fc94c67f914061d2ffb2
+R b7737c068e16cb857c9f3b56f1cad115
 U danielk1977
-Z 4105e9c21de5f7abe6dd222e25dd8c5e
+Z c876a87c3a381106862832380625540a
--- a/manifest.uuid
+++ b/manifest.uuid
@ -1 +1 @@
-ea315668e5833befe296fc94c67f914061d2ffb2
+5efa2d2a602c3b7249c4e6701e97b16b5ad0280d
--- a/src/sqlite.h.in
+++ b/src/sqlite.h.in
@ -12,7 +12,7 @@
 ** 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 $
+** @(#) $Id: sqlite.h.in,v 1.123 2004/11/20 06:05:56 danielk1977 Exp $
 */
 #ifndef _SQLITE3_H_
 #define _SQLITE3_H_
@ -449,8 +449,8 @@ 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.
+** 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
--- a/www/compile.tcl
+++ b/www/compile.tcl
@ -0,0 +1,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
+
--- a/www/docs.tcl
+++ b/www/docs.tcl
@ -1,7 +1,7 @@
 # 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 $}
+set rcsid {$Id: docs.tcl,v 1.8 2004/11/20 06:05:56 danielk1977 Exp $}
 source common.tcl
 header {SQLite Documentation}
 puts {
@ -110,5 +110,11 @@ doc {VDBE Opcodes} {opcode.html} {
  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
--- a/www/pragma.tcl
+++ b/www/pragma.tcl
@ -1,7 +1,7 @@
 #
 # 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 $}
+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}

@ -293,6 +293,7 @@ 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
@ -301,6 +302,7 @@ puts {
    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