DESCRIPTION

pkgtools is a small Tcl extension that bundles some commands that are useful when working with packages, mostly from a developers point of view. Several Tcl extensions/packages use and require pkgtools. If you just want to use one of these extensions, you only need to put a pkgtools "binary" somewhere Tcl can find it, and not care about the rest of this page.

PACKAGE INIT COMMANDS

A number of commands in pkgtools is used in the initializing of an extension

pkgtools::init dir name ?testcmd? ?noc_file? ?packagename?
This command will intialise an extension. It starts by searching the appropriate architecture specific compiled code for the current architecture in a number of possible directories starting from dir: e.g. an architecture subdirectory of dir, dir itself, the parent of dir (old convention). It uses name as a base of the file to be found, adding the correct sharedlibextension, etc. It then tries to dynamically load the library. If testcmd is given and not empty, it is used to check whether the library is already loaded: this is if the command testcmd already exists. If no compiled library could be found, the file given by noc_file is sourced for a Tcl-only fallback. A specific packagename can be given if needed to load the library.
pkgtools::architecture
Returns the architecture Tcl on which is currently running in the form platform-machine
pkgtools::findlib dir name
find the appropriate architecture specific compiled code for the current architecture in a number of possible directories starting from dir. It uses name as a base of the file to be found, adding the correct sharedlibextension, etc.

PACKAGE BUILD COMMANDS

A number of commands in pkgtools is useful in building and installing a package

pkgtools::install installdir
pkgtools::install pkglibdir pkglibdir pkgtcllibdir pkgtcllibdir pkgdatadir pkgdatadir pkgincludedir pkgincludedir bindir bindir mandir mandir
This command makes it easy to create an installation script by providing a number of variables and calling the command:
#!/bin/sh
# the next line restarts using tclsh \
exec tclsh "$0" "$@"

package require pkgtools
cd [pkgtools::startdir]

# settings
# --------

set libfiles {lib README pkgIndex.tcl init.tcl DESCRIPTION.txt}
set shareddatafiles README
set headers {}
set libbinaries [::pkgtools::findlib [file dir [pkgtools::startdir]] Extral]
set binaries {}

# standard
# --------
pkgtools::install $argv

PACKAGE TEST COMMANDS

A number of commands in pkgtools is useful in testing comands in a package

pkgtools::test group description script expected args
Execute a test identified by group and description. The piece of code given in script is run. It should return expected. If the code contains an error or does not return the expected result, the error is displayed and the test flagged. If args contains "error", the script should cause an error, with expected as error message. If the script does not cause an error in this case, the test is flagged as failed. script is actually run within a proc, so if access to global variables is needed, they must be defined as such.
test pkgtools::test {basic} {
    set a 1
} {1}
args can also contain {skipon 1} or {skipon 0} that will skip or not skip the test respectively. The 1 or 0 is generated by code checking for e.g. the existance of a command, etc.:
test pkgtools::test {dict test} {
    dict set a a 1
} {a 1} [list skipon [catch {dict size {a 1}}]]
pkgtools::testsummarize
Summarizes the results of all tests done. This command is usually put at the end of the testfile. It prints out all failed tests, or "All tests ok" if everything went well. It also shows the number of tests skipped.
pkgtools::teststart
pkgtools::testfile file
You usually make several test files, testing specific features. You sometimes want to run all of them. You can easily do this by making a file like this:
package require pkgtools
namespace import pkgtools::*
teststart
testfile test1.tcl
testfile test2.tcl
testsummarize

KEYWORDS