Further refactoring of the TCL extension test procedure document, for

improved clarity and usability.

FossilOrigin-Name: bcdaef434142973a0805117495e561b2dcd1ec1465cacc9b944a3707291afc0d
This commit is contained in:
drh
2025-01-05 19:58:30 +00:00
parent 15e388d910
commit f19d7b4de1
3 changed files with 68 additions and 67 deletions
+61 -60
View File
@@ -5,7 +5,7 @@
The SQLite TCL extension logic (in the
"[tclsqlite.c](/file/src/tclsqlite.c)" source
file) is statically linked into "textfixture" executable
which is the program used to do more of the testing
which is the program used to do most of the testing
associated with "make test", "make devtest", and/or
"make releasetest". So the functionality of the SQLite
TCL extension is thoroughly vetted during normal testing. The
@@ -21,39 +21,39 @@ an ordinary tclsh can subsequently run "package require sqlite3".
<ol type="1">
<li value="1">
[Fossil](https://fossil-scm.org/) installed.
<li>
A Fossil check-out of the TCL source tree. Let the directory
of this check-out be called **$TCLCO** (mnemonic: "TCL Check-Out").
<li>
A Fossil check-out of the SQLite source tree. Let the directory
of this check-out be called **$SRCCO** (mnemonic: "SouRCe Check-Out").
<li>
Let **$TCLTD** (mnemonic: "TCL Test Directory") be the name of a directory
that does not exist at the start of the test, and which will be
deleted at the end of the test, that will contain the test builds
of the TCL libraries and the SQLite TCL Extensions.
<li> Check out source code and set environment variables:
<ol type="a">
<li> **TCLSOURCE** &rarr;
The top-level directory of a Fossil check-out of the TCL source tree.
<li> **SQLITESOURCE** &rarr;
A Fossil check-out of the SQLite source tree.
<li> **TCLBUILD** &rarr;
A directory that does not exist at the start of the test and which
will be deleted at the end of the test, and that will contain the
test builds of the TCL libraries and the SQLite TCL Extensions.
</ol>
</ol>
### 2.2 Testing TCL 8.6 on unix
<ol type="1">
<li value="5"> `mkdir $TCLTD/tcl86`
<li> `cd $TCLCO/unix`
<li value="3"> `mkdir -p $TCLBUILD/tcl86`
<li> `cd $TCLSOURCE/unix`
<li> `fossil up core-8-6-16` <br>
&uarr; Or some other version of Tcl8.6.
<li> `fossil clean -x`
<li> `./configure --prefix=$TCLTD/tcl86`
<li> `./configure --prefix=$TCLBUILD/tcl86`
<li> `make install`
<li> `cd $SRCCO`
<li> `cd $SQLITESOURCE`
<li> `fossil clean -x`
<li> `./configure --with-tclsh=$TCLTD/tcl86/bin/tclsh8.6`
<li> `./configure --with-tclsh=$TCLBUILD/tcl86/bin/tclsh8.6`
<li> `make tclextension-install` <br>
&uarr; Verify extension installed at $TCLTD/tcl86/lib/tcl8.6/sqlite3.*
<li> `makek tclextension-list` <br>
&uarr; Verify extension installed at $TCLBUILD/tcl86/lib/tcl8.6/sqlite3.*
<li> `make tclextension-list` <br>
&uarr; Verify TCL extension correctly installed.
<li> `make tclextension-verify` <br>
&uarr; Verify that the correct version is installed.
<li> `$TCLTD/tcl86/bin/tclsh8.6 test/testrunner.tcl release --explain` <br>
<li> `$TCLBUILD/tcl86/bin/tclsh8.6 test/testrunner.tcl release --explain` <br>
&uarr; Verify thousands of lines of output with no errors. Or
consider running "devtest" without --explain instead of "release".
</ol>
@@ -61,21 +61,21 @@ an ordinary tclsh can subsequently run "package require sqlite3".
### 2.3 Testing TCL 9.0 on unix
<ol>
<li value="18"> `mkdir $TCLTD/tcl90`
<li value="16"> `mkdir -p $TCLBUILD/tcl90`
<li> `fossil up core-9-0-0` <br>
&uarr; Or some other version of Tcl9
<li> `fossil clean -x`
<li> `./configure --prefix=$TCLTD/tcl90`
<li> `./configure --prefix=$TCLBUILD/tcl90`
<li> `make install`
<li> `cd $SRCCO`
<li> `cd $SQLITESOURCE`
<li> `fossil clean -x`
<li> `./configure --with-tclsh=$TCLTD/tcl90/bin/tclsh9.0`
<li> `./configure --with-tclsh=$TCLBUILD/tcl90/bin/tclsh9.0`
<li> `make tclextension-install` <br>
&uarr; Verify extension installed at $TCLTD/tcl90/lib/sqlite3.*
<li> `makek tclextension-list` <br>
&uarr; Verify extension installed at $TCLBUILD/tcl90/lib/sqlite3.*
<li> `make tclextension-list` <br>
&uarr; Verify TCL extension correctly installed.
<li> `make tclextension-verify`
<li> `$TCLTD/tcl90/bin/tclsh9.0 test/testrunner.tcl release --explain` <br>
<li> `$TCLBUILD/tcl90/bin/tclsh9.0 test/testrunner.tcl release --explain` <br>
&uarr; Verify thousands of lines of output with no errors. Or
consider running "devtest" without --explain instead of "release".
</ol>
@@ -83,7 +83,7 @@ an ordinary tclsh can subsequently run "package require sqlite3".
### 2.4 Cleanup
<ol type="1">
<li value="30"> `rm -rf $TCLTD`
<li value="28"> `rm -rf $TCLBUILD`
</ol>
## 3.0 Testing On Windows
@@ -93,47 +93,48 @@ an ordinary tclsh can subsequently run "package require sqlite3".
<ol type="1">
<li value="1">
[Fossil](https://fossil-scm.org/) installed.
<li>
A Fossil check-out of the TCL source tree. Let the directory
of this check-out be called **%TCLCO%** (mnemonic: "TCL Check-Out").
<li>
A Fossil check-out of the SQLite source tree. Let the directory
of this check-out be called **%SRCCO%** (mnemonic: "SouRCe Check-Out").
<li>
Let **%TCLTD%** (mnemonic: "TCL Test Directory") be the name of a directory
that does not exist at the start of the test, and which will be
deleted at the end of the test, that will contain the test builds
of the TCL libraries and the SQLite TCL Extensions.
<li>
Unix-like command-line tools installed. Example:
[unxutils](https://unxutils.sourceforge.net/)
<li> [Visual Studio](https://visualstudio.microsoft.com/vs/community/)
installed. VS2015 or later required.
<li> `set ORIGINALPATH=%PATH%` <br>
&uarr; remember the original %PATH% value
<li> Check out source code and set environment variables.
<ol type="a">
<li> **TCLSOURCE** &rarr;
The top-level directory of a Fossil check-out of the TCL source tree.
<li> **SQLITESOURCE** &rarr;
A Fossil check-out of the SQLite source tree.
<li> **TCLBUILD** &rarr;
A directory that does not exist at the start of the test and which
will be deleted at the end of the test, and that will contain the
test builds of the TCL libraries and the SQLite TCL Extensions.
<li> **ORIGINALPATH** &rarr;
The original value of %PATH%. In other words, set as follows:
`set ORIGINALPATH %PATH%`
</ol>
</ol>
### 3.2 Testing TCL 8.6 on Windows
<ol type="1">
<li value="8"> `mkdir %TCLTD%\tcl86`
<li> `cd %TCLCO%\win`
<li value="5"> `mkdir %TCLBUILD%\tcl86`
<li> `cd %TCLSOURCE%\win`
<li> `fossil up core-8-6-16` <br>
&uarr; Or some other version of Tcl8.6.
<li> `fossil clean -x`
<li> `set INSTALLDIR=%TCLTD%\tcl86`
<li> `set INSTALLDIR=%TCLBUILD%\tcl86`
<li> `nmake /f makefile.vc release` <br>
&udarr; You *must* invoke the "release" and "install" targets
using separate invocations of "nmake" or tclsh86t.exe won't be
using separate "nmake" commands or tclsh86t.exe won't be
installed.
<li> `nmake /f makefile.vc install`
<li> `cd %SRCCO%`
<li> `cd %SQLITESOURCE%`
<li> `fossil clean -x`
<li> `set TCLDIR=%TCLTD%\tcl86`
<li> `set PATH=%TCLTD%\tcl86\bin;%ORIGINALPATH%`
<li> `set TCLSH_CMD=%TCLTD%\tcl86\bin\tclsh86t.exe`
<li> `set TCLDIR=%TCLBUILD%\tcl86`
<li> `set PATH=%TCLBUILD%\tcl86\bin;%ORIGINALPATH%`
<li> `set TCLSH_CMD=%TCLBUILD%\tcl86\bin\tclsh86t.exe`
<li> `nmake /f Makefile.msc tclextension-install` <br>
&uarr; Verify extension installed at %TCLTD%\\tcl86\\lib\\tcl8.6\\sqlite3.*
&uarr; Verify extension installed at %TCLBUILD%\\tcl86\\lib\\tcl8.6\\sqlite3.*
<li> `nmake /f Makefile.msc tclextension-verify`
<li>`tclsh86t test/testrunner.tcl release --explain` <br>
&uarr; Verify thousands of lines of output with no errors. Or
@@ -143,24 +144,24 @@ an ordinary tclsh can subsequently run "package require sqlite3".
### 3.3 Testing TCL 9.0 on Windows
<ol>
<li value="23"> `mkdir %TCLTD%\tcl90`
<li> `cd %TCLCO%\win`
<li value="20"> `mkdir %TCLBUILD%\tcl90`
<li> `cd %TCLSOURCE%\win`
<li> `fossil up core-9-0-0` <br>
&uarr; Or some other version of Tcl9
<li> `fossil clean -x`
<li> `set INSTALLDIR=%TCLTD%\tcl90`
<li> `set INSTALLDIR=%TCLBUILD%\tcl90`
<li> `nmake /f makefile.vc release` <br>
&udarr; You *must* invoke the "release" and "install" targets
using separate invocations of "nmake" or tclsh90.exe won't be
using separate "nmake" commands or tclsh90.exe won't be
installed.
<li> `nmake /f makefile.vc install`
<li> `cd %SRCCO%`
<li> `cd %SQLITESOURCE%`
<li> `fossil clean -x`
<li> `set TCLDIR=%TCLTD%\tcl90`
<li> `set PATH=%TCLTD%\tcl90\bin;%ORIGINALPATH%`
<li> `set TCLSH_CMD=%TCLTD%\tcl90\bin\tclsh90.exe`
<li> `set TCLDIR=%TCLBUILD%\tcl90`
<li> `set PATH=%TCLBUILD%\tcl90\bin;%ORIGINALPATH%`
<li> `set TCLSH_CMD=%TCLBUILD%\tcl90\bin\tclsh90.exe`
<li> `nmake /f Makefile.msc tclextension-install` <br>
&uarr; Verify extension installed at %TCLTD%\\tcl90\\lib\\sqlite3.*
&uarr; Verify extension installed at %TCLBUILD%\\tcl90\\lib\\sqlite3.*
<li> `nmake /f Makefile.msc tclextension-verify`
<li> `tclsh90 test/testrunner.tcl release --explain` <br>
&uarr; Verify thousands of lines of output with no errors. Or
@@ -170,5 +171,5 @@ an ordinary tclsh can subsequently run "package require sqlite3".
### 3.4 Cleanup
<ol type="1">
<li value="38"> `rm -rf %TCLTD%`
<li value="35"> `rm -rf %TCLBUILD%`
</ol>
+6 -6
View File
@@ -1,5 +1,5 @@
C Refactor\sthe\sTCL\sextension\stest\sprocedure\sto\sdeal\swith\sTCL8.6\sand\sTCL9.0\nseparately,\sto\ssimplify\sthe\sprocedures\sand\sreduce\scognative\sstress\son\sthe\ntester.
D 2025-01-05T17:16:33.231
C Further\srefactoring\sof\sthe\sTCL\sextension\stest\sprocedure\sdocument,\sfor\nimproved\sclarity\sand\susability.
D 2025-01-05T19:58:30.967
F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
F LICENSE.md e108e1e69ae8e8a59e93c455654b8ac9356a11720d3345df2a4743e9590fb20d
@@ -61,7 +61,7 @@ F doc/json-enhancements.md e356fc834781f1f1aa22ee300027a270b2c960122468499bf347b
F doc/jsonb.md 5fab4b8613aa9153fbeb6259297bd4697988af8b3d23900deba588fa7841456b
F doc/lemon.html 8b266ff711d2ec7f867c3dca37634963f48a630329908cc282beebfa8c708706
F doc/pager-invariants.txt 27fed9a70ddad2088750c4a2b493b63853da2710
F doc/tcl-extension-testing.md 37722ac070d15ed687fbde2c444b97fd1b423b631a89897142f708594aafba47
F doc/tcl-extension-testing.md fca7b123e6f6c94f87c5e9285342fa08d17f118d47bea22c0b045485755fe9c3
F doc/testrunner.md 15583cf8c7d8a1c3378fd5d4319ca769a14c4d950a5df9b015d01d5be290dc69
F doc/trusted-schema.md 33625008620e879c7bcfbbfa079587612c434fa094d338b08242288d358c3e8a
F doc/vdbesort-memory.md 4da2639c14cd24a31e0af694b1a8dd37eaf277aff3867e9a8cc14046bc49df56
@@ -2205,8 +2205,8 @@ F tool/version-info.c 3b36468a90faf1bbd59c65fd0eb66522d9f941eedd364fabccd7227350
F tool/warnings-clang.sh bbf6a1e685e534c92ec2bfba5b1745f34fb6f0bc2a362850723a9ee87c1b31a7
F tool/warnings.sh 49a486c5069de041aedcbde4de178293e0463ae9918ecad7539eedf0ec77a139
F tool/win/sqlite.vsix deb315d026cc8400325c5863eef847784a219a2f
P 28150c615cb601dfc9e4f660627228d6a8a715d64c65f7bc77931c9daf8a0dd7
R 866ce61f7bd1663ef897c7b2791f707c
P 5281536327d244ba9507548f7ed607e86e59b98a003e63f6da767471411c8ffc
R 789a42abc3bc046ab3689d41ea48cbbd
U drh
Z c10b13ae5e892d2f5ddbaa1f9222567d
Z a57fb295edbde74d3aaadaf4afebbd36
# Remove this line to create a well-formed Fossil manifest.
+1 -1
View File
@@ -1 +1 @@
5281536327d244ba9507548f7ed607e86e59b98a003e63f6da767471411c8ffc
bcdaef434142973a0805117495e561b2dcd1ec1465cacc9b944a3707291afc0d