doc/tcl-extension-testing.md
The SQLite TCL extension logic (in the "tclsqlite.c" source file) is statically linked into "textfixture" executable 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 procedures below are designed to test the loadable extension aspect of the SQLite TCL extension, and in particular to verify that the "make tclextension-install" build target works and that an ordinary tclsh can subsequently run "package require sqlite3".
This procedure can also be used as a template for how to set up a local TCL+SQLite development environment. In other words, it can be be used as a guide on how to compile per-user copies of Tcl that are used to develop, test, and debug SQLite. In that case, perhaps make minor changes to the procedure such as:
<a id="unix"></a>
See also the document which provides another perspective on how to compile SQLite on unix-like systems.
From a checked-out copy of the core Tcl tree
<ol type="1"> <li value="3">`TCLVERSION=8.6` ↑ A version of your choice. This process has been tested with
values of 8.6, 9.0, and 9.1 (as of 2025-04-16). The out-of-life
version 8.5 fails some of `make devtest` for undetermined reasons.
↑ Ensure that no stale Tcl installation is laying around.
↑ The branch corresponding to `$TCLVERSION`, e.g.
`core-9-0-branch` or `trunk`.
↑ The `--disable-shared` is to avoid the need to set `LD_LIBRARY_PATH`
when using this Tcl build.
↑ Verify extension installed at
`$TCLHOME/lib/tcl${TCLVERSION}/sqlite<SQLITE_VERSION>`.
↑ Verify TCL extension correctly installed.
↑ Verify that the correct version is installed.
↑ Verify thousands of lines of output with no errors. Or
consider running "devtest" without --explain instead of "release".
<a id="windows"></a>
See also the document which provides another perspective on how to compile SQLite on Windows.
(These docs are not as up-to-date as the Unix docs, above.)
<ol type="1"> <li value="1"> [Fossil][] installed. <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> Check out source code and set environment variables. <ol type="a"> <li> **TCLSOURCE** → The top-level directory of a Fossil check-out of the TCL source tree. <li> **SQLITESOURCE** → A Fossil check-out of the SQLite source tree. <li> **TCLBUILD** → 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** → The original value of %PATH%. In other words, set as follows: `set ORIGINALPATH %PATH%` </ol> </ol> ↑ Or some other version of Tcl8.6.
⇅ You *must* invoke the "release" and "install" targets
using separate "nmake" commands or tclsh86t.exe won't be
installed.
↑ Verify extension installed at %TCLBUILD%\\tcl86\\lib\\tcl8.6\\sqlite3.*
↑ Verify thousands of lines of output with no errors. Or
consider running "devtest" without --explain instead of "release".
↑ Or some other version of Tcl9
⇅ You *must* invoke the "release" and "install" targets
using separate "nmake" commands or tclsh90.exe won't be
installed.
↑ Verify extension installed at %TCLBUILD%\\tcl90\\lib\\sqlite3.*
↑ Verify thousands of lines of output with no errors. Or
consider running "devtest" without --explain instead of "release".
This part requires following the setup instructions for Unix systems, at the top of this document.
The former TEA, now TEA(ish), build of this extension uses the same code as the builds described above but is provided in a form more convenient for downstream Tcl users.
It lives in autoconf/tea and, as part of the autoconf bundle,
cannot be tested directly from the canonical tree. Instead it has to
be packaged.
Follow the same Tcl- and environment-related related setup described in the first section of this document, up to and including the installation of Tcl (unless, of course, it was already installed using those same instructions).
↑ Should run to completion without any errors.
↑ Will uninstall the extension. This _can_ be run
in the same invocation as the `install` target, but only
if the `-j#` make flag is _not_ used. If it is, the
install/uninstall steps will race and make a mess of things.
Parallel builds do not help in this build, anyway, as there's
only a single C file to compile.
When actively developing and testing the teaish build, which requires
going through the tarball generation, there's a caveat about the
mkpkg_tmp_dir dir: it will be deleted every time a tarball is
built, the shell console which is parked in that
directory for testing needs to add cd $PWD && to the start of the
build commands, like:
[user@host:.../mkpkg_tmp_dir/tea]$ \
cd $PWD && ./configure CFLAGS=-O0 --with-tcl=$TCLHOME \
&& make test install uninstall