Documentation Source Text

Check-in [ff45f132a6]
Login

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

Overview
Comment:Clarification of rules regarding SQLITE_OMIT_ compile-time options. Other minor documentation fixes.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: ff45f132a63ed5bb01274222a6b909acf6cc5832
User & Date: drh 2015-11-09 21:21:50.574
Context
2015-11-11
00:22
Clarification of the checkpoint algorithm in the file format document. (check-in: 4f85463d41 user: drh tags: trunk)
2015-11-09
21:21
Clarification of rules regarding SQLITE_OMIT_ compile-time options. Other minor documentation fixes. (check-in: ff45f132a6 user: drh tags: trunk)
2015-11-03
14:58
Fix closing tag mismatch in fileformat.html. (check-in: b4a002ba34 user: dan tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to pages/compile.in.
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
  to the built-in [date and time functions].
}

COMPILE_OPTION {HAVE_MALLOC_USABLE_SIZE} {
  If the HAVE_MALLOC_USABLE_SIZE option is true, then SQLite tries uses the
  malloc_usable_size() interface to find the size of a memory allocation obtained
  from the standard-library malloc() or realloc() routines.  This option is only
  applicable if the standard-library malloc() is used.  On Apply systems,
  "zone malloc" is used instead, and so this option is not applicable.  And, of
  course, if the application supplies its own malloc implementation using
  [SQLITE_CONFIG_MALLOC] then this option has no effect.
  <p>
  If the HAVE_MALLOC_USABLE_SIZE option is omitted or is false, then SQLite 
  uses a wrapper around system malloc() and realloc() that enlarges each allocation
  by 8 bytes and writes the size of the allocation in the initial 8 bytes, and







|







84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
  to the built-in [date and time functions].
}

COMPILE_OPTION {HAVE_MALLOC_USABLE_SIZE} {
  If the HAVE_MALLOC_USABLE_SIZE option is true, then SQLite tries uses the
  malloc_usable_size() interface to find the size of a memory allocation obtained
  from the standard-library malloc() or realloc() routines.  This option is only
  applicable if the standard-library malloc() is used.  On Apple systems,
  "zone malloc" is used instead, and so this option is not applicable.  And, of
  course, if the application supplies its own malloc implementation using
  [SQLITE_CONFIG_MALLOC] then this option has no effect.
  <p>
  If the HAVE_MALLOC_USABLE_SIZE option is omitted or is false, then SQLite 
  uses a wrapper around system malloc() and realloc() that enlarges each allocation
  by 8 bytes and writes the size of the allocation in the initial 8 bytes, and
896
897
898
899
900
901
902
903
904
905

906
907
908
909
910
911
912

913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928






929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
</p>

<p>If any of these options are defined, then the same set of SQLITE_OMIT_*
options must also be defined when using the 'lemon' tool to generate the
parse.c file and when compiling the 'mkkeywordhash' tool which generates 
the keywordhash.h file.
Because of this, these options may only be used when the library is built
from canonical source, not from the [amalgamation] or from the collection of
pre-packaged C files provided for non-Unix like platforms on the website.
Any SQLITE_OMIT_* options which can be used directly with the [amalgamation] 

are listed below, however, the warnings in the following paragraph should be noted.
</p>

<blockquote>
<i><b>Important Note:</b> The SQLITE_OMIT_* options do not work with the
[amalgamation] or with pre-packaged C code files.  SQLITE_OMIT_* compile-time
options only work correctly when SQLite is built from canonical source files.

</i>
</blockquote>


<p>Special versions of the SQLite amalgamation that do work with a
predetermined set of SQLITE_OMIT_* options can be generated.  To do so,
make a copy of the Makefile.linux-gcc makefile template in the canonical
source code distribution.  Change the name of your copy to simply "Makefile".
Then edit "Makefile" to set up appropriate compile-time options.  Then
type:
<blockquote><tt>make clean; make sqlite3.c</tt></blockquote>
The resulting "sqlite3.c" amalgamation code file (and its associated
header file "sqlite3.h") can then be moved to a non-unix platform
for final compilation using a native compiler.</p>

<p>All of the SQLITE_OMIT_* options are unsupported.</p>







<blockquote>
<i><b>Important Note:</b>
The SQLITE_OMIT_* compile-time options are unsupported.
</i></blockquote>

<p>
The SQLITE_OMIT_* compile-time options are usually untested and
are almost certainly untested in combination.
Any or all of these options may be removed from the code in future releases
and without warning.  For any particular release, some of these
options may cause compile-time or run-time failures, particularly
when used in combination with other options.</p>

<tcl>
COMPILE_OPTION {SQLITE_OMIT_ALTERTABLE} {
  When this option is defined, the 
  [ALTER TABLE] command is not included in the 
  library. Executing an [ALTER TABLE] statement causes a parse error.
}








|
<
|
>
|



|
|
|
>















|
>
>
>
>
>
>






<
<
<
<
<
<
<
<







896
897
898
899
900
901
902
903

904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941








942
943
944
945
946
947
948
</p>

<p>If any of these options are defined, then the same set of SQLITE_OMIT_*
options must also be defined when using the 'lemon' tool to generate the
parse.c file and when compiling the 'mkkeywordhash' tool which generates 
the keywordhash.h file.
Because of this, these options may only be used when the library is built
from canonical source, not from the [amalgamation].

Some SQLITE_OMIT_* options might work, or appear to work, when used with
the [amalgamation].  But this is not guaranteed.  In general, always compile
from canonical sources in order to take advantage of SQLITE_OMIT_* options.
</p>

<blockquote>
<i><b>Important Note:</b> The SQLITE_OMIT_* options may not work with the
[amalgamation].  SQLITE_OMIT_* compile-time
options usually work correctly only when SQLite is built from canonical 
source files.
</i>
</blockquote>


<p>Special versions of the SQLite amalgamation that do work with a
predetermined set of SQLITE_OMIT_* options can be generated.  To do so,
make a copy of the Makefile.linux-gcc makefile template in the canonical
source code distribution.  Change the name of your copy to simply "Makefile".
Then edit "Makefile" to set up appropriate compile-time options.  Then
type:
<blockquote><tt>make clean; make sqlite3.c</tt></blockquote>
The resulting "sqlite3.c" amalgamation code file (and its associated
header file "sqlite3.h") can then be moved to a non-unix platform
for final compilation using a native compiler.</p>

<p>The SQLITE_OMIT_* options are unsupported.  By this we mean that
an SQLITE_OMIT_* option that omits code from the build in the current
release might become a no-op in the next release.  Or the other way around:
an SQLITE_OMIT_* that is a no-op in the current release might cause code
to be excluded in the next release.  Also, not all SQLITE_OMIT_* options
are tested.  Some SQLITE_OMIT_* options might cause SQLite to malfunction
and/or provide incorrect answers.

<blockquote>
<i><b>Important Note:</b>
The SQLITE_OMIT_* compile-time options are unsupported.
</i></blockquote>









<tcl>
COMPILE_OPTION {SQLITE_OMIT_ALTERTABLE} {
  When this option is defined, the 
  [ALTER TABLE] command is not included in the 
  library. Executing an [ALTER TABLE] statement causes a parse error.
}

Changes to pages/docs.in.
141
142
143
144
145
146
147




148
149
150
151
152
153
154
}
doc {Foreign Key Support} {foreignkeys.html} {
  This document describes the support for foreign key constraints introduced
  in version 3.6.19.
}
doc {Full Text Search} {fts3.html} {
  A description of the SQLite Full Text Search (FTS3) extension.




}
doc {Internal versus External Blob Storage} {intern-v-extern-blob.html} {
  Should you store large BLOBs directly in the database, or store them
  in files and just record the filename in the database?  This document
  seeks to shed light on that question.
}
doc {Limits In SQLite} {limits.html} {







>
>
>
>







141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
}
doc {Foreign Key Support} {foreignkeys.html} {
  This document describes the support for foreign key constraints introduced
  in version 3.6.19.
}
doc {Full Text Search} {fts3.html} {
  A description of the SQLite Full Text Search (FTS3) extension.
}
doc {Indexes On Expressions} {expridx.html} {
  Notes on how to create indexes on expressions instead of just
  individual columns.
}
doc {Internal versus External Blob Storage} {intern-v-extern-blob.html} {
  Should you store large BLOBs directly in the database, or store them
  in files and just record the filename in the database?  This document
  seeks to shed light on that question.
}
doc {Limits In SQLite} {limits.html} {