Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Miscellaneous documentation updates, including updates to the testing document and updates to the changes for version 3.7.14. |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA1: |
8fa9629e001515c56da0b66176197594 |
User & Date: | drh 2012-08-27 16:37:38.966 |
Context
2012-08-29
| ||
18:17 | Fix a few minor typos. (check-in: ac94eb8835 user: drh tags: trunk) | |
2012-08-27
| ||
16:37 | Miscellaneous documentation updates, including updates to the testing document and updates to the changes for version 3.7.14. (check-in: 8fa9629e00 user: drh tags: trunk) | |
2012-08-25
| ||
01:56 | Update the change log for 3.7.14 to reflect the latest additions. (check-in: c98f1a5ff9 user: drh tags: trunk) | |
Changes
Changes to pages/about.in.
︙ | ︙ | |||
60 61 62 63 64 65 66 | <p>SQLite is a compact library. With all features enabled, the [library size] can be less than 350KiB, depending on the target platform and compiler optimization settings. (64-bit code is larger. And some compiler optimizations such as aggressive function inlining and loop unrolling can cause the object code to be much larger.) If optional features are omitted, the | | | 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 | <p>SQLite is a compact library. With all features enabled, the [library size] can be less than 350KiB, depending on the target platform and compiler optimization settings. (64-bit code is larger. And some compiler optimizations such as aggressive function inlining and loop unrolling can cause the object code to be much larger.) If optional features are omitted, the size of the SQLite library can be reduced below 300KiB. SQLite can also be made to run in minimal stack space (4KiB) and very little heap (100KiB), making SQLite a popular database engine choice on memory constrained gadgets such as cellphones, PDAs, and MP3 players. There is a tradeoff between memory usage and speed. SQLite generally runs faster the more memory you give it. Nevertheless, performance is usually quite good even in low-memory environments.</p> |
︙ | ︙ |
Changes to pages/changes.in.
︙ | ︙ | |||
39 40 41 42 43 44 45 | } hd_close_aux hd_enable_main 1 } } chng {2012-09-05 (3.7.14)} { | | > > > > | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 | } hd_close_aux hd_enable_main 1 } } chng {2012-09-05 (3.7.14)} { <li>Drop built-in support for OS/2. If you need to upgrade an OS/2 application to use this or a later version of SQLite, then add an application-defined [VFS] using the [sqlite3_vfs_register()] interface. The code removed in this release can serve as a baseline for the application-defined VFS. <li>Ensure that floating point values are preserved exactly when reconstructing a database from the output of the ".dump" command of the [command-line shell]. <li>Added the [sqlite3_close_v2()] interface. <li>Updated the [command-line shell] so that it can be built using [SQLITE_OMIT_FLOATING_POINT] and [SQLITE_OMIT_AUTOINIT]. <li>Improvements to the windows makefiles and build processes. |
︙ | ︙ |
Changes to pages/features.in.
︙ | ︙ | |||
12 13 14 15 16 17 18 | (<a href="omitted.html">Features not supported</a>)</li> <li>A complete database is stored in a <a href="onefile.html">single cross-platform disk file</a>.</li> <li>Supports terabyte-sized databases and gigabyte-sized strings and blobs. (See <a href="limits.html">limits.html</a>.) <li>Small code [footprint]: less than 350KiB fully configured or less | | | 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | (<a href="omitted.html">Features not supported</a>)</li> <li>A complete database is stored in a <a href="onefile.html">single cross-platform disk file</a>.</li> <li>Supports terabyte-sized databases and gigabyte-sized strings and blobs. (See <a href="limits.html">limits.html</a>.) <li>Small code [footprint]: less than 350KiB fully configured or less than 300KiB with optional features omitted.</li> <li><a href="speed.html">Faster</a> than popular client/server database engines for most common operations.</li> <li>Simple, easy to use <a href="c3ref/intro.html">API</a>.</li> <li>Written in ANSI-C. <a href="tclsqlite.html">TCL bindings</a> included. Bindings for dozens of other languages <a href="http://www.sqlite.org/cvstrac/wiki?p=SqliteWrappers"> available separately.</a></li> |
︙ | ︙ |
Changes to pages/lockingv3.in.
1 2 3 4 5 6 7 8 9 | <title>File Locking And Concurrency In SQLite Version 3</title> <tcl> hd_keywords {file locking and concurrency control} proc HEADING {level title args} { global pnum incr pnum($level) foreach i [array names pnum] { if {$i>$level} {set pnum($i) 0} | > > > > > > > > > > > > > > > | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | <title>File Locking And Concurrency In SQLite Version 3</title> <font color="#7f001f"><p> <p>This document was originally created in early 2004 when SQLite version 2 was still in widespread use and was written to introduce the new concepts of SQLite version 3 to readers who were already familiar with SQLite version 2. But these days, most readers of this document have probably never seen SQLite version 2 and are only familiar with SQLite version 3. Nevertheless, this document continues to serve as an authoritative reference to how database file locking works in SQLite version 3.</p> <p>The document only describes locking for the older rollback-mode transaction mechanism. Locking for the newer [write-ahead log] or [WAL mode] is described separately.</p> </font> <tcl> hd_keywords {file locking and concurrency control} proc HEADING {level title args} { global pnum incr pnum($level) foreach i [array names pnum] { if {$i>$level} {set pnum($i) 0} |
︙ | ︙ | |||
38 39 40 41 42 43 44 | involving multiple database files. This document describes the new locking mechanism. The intended audience is programmers who want to understand and/or modify the pager code and reviewers working to verify the design of SQLite version 3. </p> | < < < < < < < < < | 53 54 55 56 57 58 59 60 61 62 63 64 65 66 | involving multiple database files. This document describes the new locking mechanism. The intended audience is programmers who want to understand and/or modify the pager code and reviewers working to verify the design of SQLite version 3. </p> <tcl>HEADING 1 {Overview} overview</tcl> <p> Locking and concurrency control are handled by the <a href="http://www.sqlite.org/src/finfo?name=src/pager.c"> pager module</a>. The pager module is responsible for making SQLite "ACID" (Atomic, |
︙ | ︙ |
Changes to pages/testing.in.
1 2 3 4 5 6 7 8 9 10 11 12 13 | <title>How SQLite Is Tested</title> <tcl>hd_keywords testing *tested {test suite}</tcl> <tcl> # This document contains many size statistics about SQLite, statistics # that change frequently. We want the document to be up-to-date. To # facilitate that, all the size values are defined by variables here # which are then used as needed through the document. # # NOTE: Also update the version number in the text!!! # # sloc sqlite3.c | | | | | | | | | | | | | | | | | | | | 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 | <title>How SQLite Is Tested</title> <tcl>hd_keywords testing *tested {test suite}</tcl> <tcl> # This document contains many size statistics about SQLite, statistics # that change frequently. We want the document to be up-to-date. To # facilitate that, all the size values are defined by variables here # which are then used as needed through the document. # # NOTE: Also update the version number in the text!!! # # sloc sqlite3.c set stat(coreSLOC) 81272 ;# Non-comment lines of amalgamation code # sloc test*.c set stat(tclcSLOC) 25111 ;# Non-comment lines of test C code # ls test*.c tclsqlite.c | wc set stat(tclcNfile) 44 ;# Number of files of TCL C testcode + tclsqlite.c # ls -l test*.c tclsqlite.c | awk '{sum+=$5}END{print sum}' set stat(tclcNByte) 1171344 ;# Number of bytes of TCL C testcode + tclsqlite.c # sloc *.test *.tcl set stat(tclsSLOC) 238184 ;# Non-comment lines of TCL test script # ls *.test *.tcl | wc set stat(tclsNFile) 711 ;# Number of files of TCL test script # ls -l *.test *.tcl | awk '{sum+=$5}END{print sum}' set stat(tclsNByte) 10497097 ;# Number of bytes of TCL test script # grep do_test *.test | wc; grep do_execsql_test *.test | wc set stat(tclNTest) 29226 ;# Number of test cases in the TCL test suite set stat(tclNEval) 3115385 ;# Number of test case evaluations set stat(nSqlFuzz) 126327 ;# Number of SQL fuzz tests set stat(vqNEval) 129072 ;# Number of test evaluations for veryquick.test # set stat(vqStmtCov) 97.23 ;# veryquick statement coverage # set stat(vqBrCov) 92.57 ;# veryquick branch coverage # set stat(allStmtCov) 99.50 ;# all.test statement coverage # set stat(allBrCov) 97.41 ;# all.test condition/decision coverage # tclsh mkth3.tcl cfg/*.cfg */*.test >th3.c; sloc th3.c set stat(th3SLOC) 666907 ;# Non-comment lines in full th3.c # ls -l th3.c set stat(th3NByte) 50050842 ;# Number of bytes in full th3.c # grep th3testBegin */*.test # grep th3oomBegin */*.test # grep th3ioerrBegin */*.test # grep '^--testcase' */*.test set stat(th3NTest) 34229 ;# Number of test cases # from output of a min.rc test run. set stat(th3NECov) 836678 ;# Number of test case evals for coverage #set stat(th3NETest) 1504866 ;# Number of test case evaluations #set stat(th3NEExt) 589175483 ;# Number of test case evals extended #set stat(th3NERel) 2500000000 ;# Number of test case evals release set stat(th3StmtCov) 100.00 ;# TH3 statement coverage set stat(th3BrCov) 100.00 ;# TH3 branch coverage # wc `find . -name '*.test'` | awk '{x+=$1}END{print x}' set stat(sltsSLOC) 90489494 ;# Non-comment lines of SLT test script # ls -l `find . -name '*.test'` | awk '{sum+=$5}END{print sum}' set stat(sltsNByte) 1120693457 ;# Bytes of SLT test script # find . -name '*.test' | wc set stat(sltsNFile) 629 ;# Files of SLT test script # sloc md5.c slt_*.c sqllogictest.c set stat(sltcSLOC) 1403 ;# Non-comment lines of SLT C code # grep '^query' `fossil ls | awk '/\.test$/{print $2}'` | wc set stat(sltNTest) 7200478 ;# Number of test cases in SLT # grep 'assert(' sqlite3.c | wc set stat(nAssert) 3531 ;# Number of assert statements # grep 'testcase(' sqlite3.c | grep -v define | wc set stat(nTestcase) 667 ;# Number of testcase statements set stat(totalSLOC) [expr {$stat(tclcSLOC)+$stat(tclsSLOC)+ $stat(th3SLOC)+$stat(sltcSLOC)+$stat(sltsSLOC)}] proc GB {expr} { set n [uplevel #0 expr $expr] hd_puts [format %.2f [expr {$n/(1000.0*1000.0*1000.0)}]] |
︙ | ︙ | |||
99 100 101 102 103 104 105 | <h1 align="center">How SQLite Is Tested</h1> <h2>1.0 Introduction</h2> <p>The reliability and robustness of SQLite is achieved in part by thorough and careful testing.</p> | | | 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 | <h1 align="center">How SQLite Is Tested</h1> <h2>1.0 Introduction</h2> <p>The reliability and robustness of SQLite is achieved in part by thorough and careful testing.</p> <p>As of [version 3.7.14], the SQLite library consists of approximately <tcl>KB {$stat(coreSLOC)}</tcl> KSLOC of C code. (KSLOC means thousands of "Source Lines Of Code" or, in other words, lines of code excluding blank lines and comments.) By comparison, the project has <tcl> hd_puts "[expr {int($stat(totalSLOC)/$stat(coreSLOC))}] times as much" |
︙ | ︙ |
Changes to pages/th3.in.
︙ | ︙ | |||
22 23 24 25 26 27 28 | <li><p> TH3 checks SQLite's response to out-of-memory errors, disk I/O errors, and power loss during transaction commit. </p></li> <li><p> TH3 exercises SQLite in a variety of run-time configurations (UTF8 vs UTF16, different pages sizes, varying journal modes, etc.) </p></li> | | > | | > | | 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 | <li><p> TH3 checks SQLite's response to out-of-memory errors, disk I/O errors, and power loss during transaction commit. </p></li> <li><p> TH3 exercises SQLite in a variety of run-time configurations (UTF8 vs UTF16, different pages sizes, varying journal modes, etc.) </p></li> <li><p> TH3 achieves 100% branch test coverage (and 100% MC/DC) over the SQLite core. (Test coverage of the operating-system specific [VFSes] and extensions such as FTS and RTREE is less than 100%). </p></li> </ul> <p>TH3 was originally written for validation testing only, but has subsequently been used for development testing and debugging as well, and has proven very helpful in those roles. A full-coverage test run for TH3 takes less than 4 minutes on a workstation and hence serves as a fast but effect regression test during day-to-day maintenance of the SQLite code base.</p> <h2>2.0 Operation</h2> <p>TH3 is a test program generator. The output of TH3 is a program written in ANSI-C and intended to be linked against the SQLite library under test. The generated test program is compiled and run on the target platform in order to verify correct operation of SQLite on that platform.</p> <p>The inputs to TH3 are test modules written in C or SQL and small configuration files that determine how to initialize SQLite. The TH3 package includes approximately one thousand test modules and several dozens configuration files. New modules and configurations can be added to customize TH3 for specialized applications. Each time TH3 is run, it reads a subset of the available test modules and configuration files to generate a custom C program that performs all of the specified tests under all configurations. A complete test of SQLite normally involves running TH3 multiple times to generate multiple test programs covering different aspects of SQLite's operation, then linking all test programs against |
︙ | ︙ | |||
84 85 86 87 88 89 90 | modules that are compatible with the configuration are run. </p> <h2>3.0 Generating A Test Program</h2> <p>The TH3 program generator is a TCL script named "<tt>mkth3.tcl</tt>". To generate a test program, one has merely to run this script and supply the names of files containing test modules and configurations on the | | < | | | 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 | modules that are compatible with the configuration are run. </p> <h2>3.0 Generating A Test Program</h2> <p>The TH3 program generator is a TCL script named "<tt>mkth3.tcl</tt>". To generate a test program, one has merely to run this script and supply the names of files containing test modules and configurations on the command line. Test modules are files that use the "<tt>.test</tt>" suffix and configurations are files that use the "<tt>.cfg</tt>" suffix. A typical invocation of mkth3.tcl might look something like the following:</p> <blockquote><pre> tclsh mkth3.tcl *.test *.cfg >testprog1.c </pre></blockquote> <p>The output from the mkth3.tcl script is a C program that contains everything needed to run the tests - everything that is except for |
︙ | ︙ | |||
114 115 116 117 118 119 120 121 122 123 124 125 126 127 | to specify optimization parameters and compile-time switches on the compiler command line.</p> <p>Once the test program is generated, it is run with no arguments to perform the tests. Progress information as well as error diagnostics appear on standard output. The program returns zero if there are no errors and non-zero if any problems were detected.</p> <h2>4.0 Test Coverage</h2> <p>Using one particular subset of the available TH3 test modules (the "cov1" tests) SQLite obtained [test coverage | 100% branch test coverage] and 100% [MC/DC] as measured by [http://gcc.gnu.org/onlinedocs/gcc/Gcov.html | gcov] | > > > > > > > > | | 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 | to specify optimization parameters and compile-time switches on the compiler command line.</p> <p>Once the test program is generated, it is run with no arguments to perform the tests. Progress information as well as error diagnostics appear on standard output. The program returns zero if there are no errors and non-zero if any problems were detected.</p> <p>TH3 comes with additional TCL scripts (for example: "th3make" and "fulltest.tcl") which help to automate the process of running mkth3.tcl, compiling th3.c and sqlite3.c, running the resulting test programs, and analyzing the results. These other scripts are for convenience only and are not required in order to make use of TH3. <h2>4.0 Test Coverage</h2> <p>Using one particular subset of the available TH3 test modules (the "cov1" tests) SQLite obtained [test coverage | 100% branch test coverage] and 100% [MC/DC] as measured by [http://gcc.gnu.org/onlinedocs/gcc/Gcov.html | gcov] on Linux x86 and x86_64 hardware. All releases of SQLite since [version 3.6.17] have been tested to this standard. The SQLite developers are committed to maintaining 100% branch coverage and MC/DC for all future releases of SQLite.</p> <p>The cov1 test set used to obtain 100% branch test coverage are only a subset of the tests currently implemented using TH3. New test modules are added on a regular basis.</p> |
︙ | ︙ |