SQLite

1.0 Background

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:

• Make TCLBUILD directory is permanent.
• Enable debugging symbols on the Tcl library build.
• Reduce the optimization level to -O0 for easier debugging.
• Also compile "wish" to go with each "tclsh".

2.0 Testing On Unix-like Systems (Including Mac)

See also the ./compile-for-unix.md document which provides another perspective on how to compile SQLite on unix-like systems.

2.1 Setup

1. Fossil installed.
2. Check out source code and set environment variables:
   1. TCLSOURCE → The top-level directory of a Fossil check-out of the TCL source tree.
   2. SQLITESOURCE → A Fossil check-out of the SQLite source tree.
   3. 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.

2.2 Testing TCL 8.6 on unix

3. mkdir -p $TCLBUILD/tcl86
4. cd $TCLSOURCE/unix
5. fossil up core-8-6-16
   ↑ Or some other version of Tcl8.6.
6. fossil clean -x
7. ./configure --prefix=$TCLBUILD/tcl86 --disable-shared
   ↑ The --disable-shared is to avoid the need to set LD_LIBRARY_PATH when using this Tcl build.
8. make install
9. cd $SQLITESOURCE
10. fossil clean -x
11. ./configure --with-tclsh=$TCLBUILD/tcl86/bin/tclsh8.6 --all
12. make tclextension-install
    ↑ Verify extension installed at $TCLBUILD/tcl86/lib/tcl8.6/sqlite3.*
13. make tclextension-list
    ↑ Verify TCL extension correctly installed.
14. make tclextension-verify
    ↑ Verify that the correct version is installed.
15. $TCLBUILD/tcl86/bin/tclsh8.6 test/testrunner.tcl release --explain
    ↑ Verify thousands of lines of output with no errors. Or consider running "devtest" without --explain instead of "release".

2.3 Testing TCL 9.0 on unix

16. mkdir -p $TCLBUILD/tcl90
17. fossil up core-9-0-0
    ↑ Or some other version of Tcl9
18. fossil clean -x
19. ./configure --prefix=$TCLBUILD/tcl90 --disable-shared
    ↑ The --disable-shared is to avoid the need to set LD_LIBRARY_PATH when using this Tcl build.
20. make install
21. cp -r ../library $TCLBUILD/tcl90/lib/tcl9.0
    ↑ The Tcl library is not installed by "make install" for Tcl9.0 unless you also include the --disable-zipfs to ./configure. But if you do that then the generated tclsh9.0 is no longer stand-alone. On the other hand, if you don't install the Tcl library, other programs like testfixture won't be able to find the Tcl library and hence won't work. This extra installation step resolves the dilemma. This step is not required when building Tcl8.6, which lacks support for zipfs and hence always installs its Tcl library.
22. cd $SQLITESOURCE
23. fossil clean -x
24. ./configure --with-tclsh=$TCLBUILD/tcl90/bin/tclsh9.0 --all
25. make tclextension-install
    ↑ Verify extension installed at $TCLBUILD/tcl90/lib/sqlite3.*
26. make tclextension-list
    ↑ Verify TCL extension correctly installed.
27. make tclextension-verify
28. $TCLBUILD/tcl90/bin/tclsh9.0 test/testrunner.tcl release --explain
    ↑ Verify thousands of lines of output with no errors. Or consider running "devtest" without --explain instead of "release".

2.4 Cleanup

29. rm -rf $TCLBUILD

3.0 Testing On Windows

See also the ./compile-for-windows.md document which provides another perspective on how to compile SQLite on Windows.

3.1 Setup for Windows

1. Fossil installed.
2. Unix-like command-line tools installed. Example: unxutils
3. Visual Studio installed. VS2015 or later required.
4. Check out source code and set environment variables.
   1. TCLSOURCE → The top-level directory of a Fossil check-out of the TCL source tree.
   2. SQLITESOURCE → A Fossil check-out of the SQLite source tree.
   3. 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.
   4. ORIGINALPATH → The original value of %PATH%. In other words, set as follows: set ORIGINALPATH %PATH%

3.2 Testing TCL 8.6 on Windows

5. mkdir %TCLBUILD%\tcl86
6. cd %TCLSOURCE%\win
7. fossil up core-8-6-16
   ↑ Or some other version of Tcl8.6.
8. fossil clean -x
9. set INSTALLDIR=%TCLBUILD%\tcl86
10. nmake /f makefile.vc release
    ⇅ You must invoke the "release" and "install" targets using separate "nmake" commands or tclsh86t.exe won't be installed.
11. nmake /f makefile.vc install
12. cd %SQLITESOURCE%
13. fossil clean -x
14. set TCLDIR=%TCLBUILD%\tcl86
15. set PATH=%TCLBUILD%\tcl86\bin;%ORIGINALPATH%
16. set TCLSH_CMD=%TCLBUILD%\tcl86\bin\tclsh86t.exe
17. nmake /f Makefile.msc tclextension-install
    ↑ Verify extension installed at %TCLBUILD%\tcl86\lib\tcl8.6\sqlite3.*
18. nmake /f Makefile.msc tclextension-verify
19. tclsh86t test/testrunner.tcl release --explain
    ↑ Verify thousands of lines of output with no errors. Or consider running "devtest" without --explain instead of "release".

3.3 Testing TCL 9.0 on Windows

20. mkdir %TCLBUILD%\tcl90
21. cd %TCLSOURCE%\win
22. fossil up core-9-0-0
    ↑ Or some other version of Tcl9
23. fossil clean -x
24. set INSTALLDIR=%TCLBUILD%\tcl90
25. nmake /f makefile.vc release
    ⇅ You must invoke the "release" and "install" targets using separate "nmake" commands or tclsh90.exe won't be installed.
26. nmake /f makefile.vc install
27. cd %SQLITESOURCE%
28. fossil clean -x
29. set TCLDIR=%TCLBUILD%\tcl90
30. set PATH=%TCLBUILD%\tcl90\bin;%ORIGINALPATH%
31. set TCLSH_CMD=%TCLBUILD%\tcl90\bin\tclsh90.exe
32. nmake /f Makefile.msc tclextension-install
    ↑ Verify extension installed at %TCLBUILD%\tcl90\lib\sqlite3.*
33. nmake /f Makefile.msc tclextension-verify
34. tclsh90 test/testrunner.tcl release --explain
    ↑ Verify thousands of lines of output with no errors. Or consider running "devtest" without --explain instead of "release".

3.4 Cleanup

35. rm -rf %TCLBUILD%