Installation and Usage
Installation requirements and usage instructions
The 32-bit builds of the TWAPI
- Windows 2000 or later,
- Tcl version 8.4 or later.
The 64-bit builds of TWAPI
- Windows 2003 Server or later,
- Tcl version 8.5 or later.
For Windows NT 4.0 (SP3 or later), use TWAPI 1.1.5 or earlier
The software is distributed in multiple forms (PLATFORM may be x86 or
x64 for the 32- and 64-bit builds
- A ZIP archive, "twapi-VERSION.zip", that includes the Tcl scripts in
source form and is platform independent, containing both 32- and
64-bit DLLs. This is best suited for developers who might want
access to the Tcl scripts during development.
- A ZIP archive, "twapi-VERSION-bin.zip", in which the Tcl scripts are
embedded within the DLL. This is also platform independent and
simultaneuosly supports both 32- and 64-bit Tcl.
- A single file Tcl module, "twapi-PLATFORM-VERSION.tm", for Tcl
8.5 and above. This is platform-specific. Note the file must be
renamed to "twapi-VERSION.tm" else the packaging system will not
- A standalone DLL, "twapi-PLATFORM-VERSION.dll", that can
be directly loaded into Tcl. This is also platform specific.
Some factors to consider in choosing the distribution:
- The "twapi-VERSION.zip" distribution is the most complete,
including a test suite for testing the installation using Tcl's
tcltest command. It also makes it easy to look
through or adapt the Tcl script level code if required. It is
however the bulkiest on disk, and has a somewhat longer load time.
It simultaneously supports both 32- and 64-bit Tcl.
- The "twapi-VERSION-bin.zip" distribution is intended for
deployment into standard Tcl installations where the script source
is not required or desired. It simultaneously supports both 32- and
- The standalone DLL and the Tcl module distributions provide the
convenience of single file deployment. The standalone DLL has the
advantage of working with Tcl 8.4 as well unlike the Tcl module
which is only supported by Tcl 8.5 or later. On the other hand, the
Tcl module is compatible with Tcl's package
require command while the standalone DLL must be loaded using
an explicit path to the DLL. This makes it most suitable for
customized applications. However, both these are specific to 32- or
- The Tcl module distributions write the TWAPI DLL component to a
temporary directory before calling the OS loader. They therefore
cannot be used in read-only disk environments. However, this
writing is done only the first time a specific TWAPI build is
loaded. The written DLL is identified by a build id that is
specific to every TWAPI build and not rewritten if it already
- The standalone DLL replaces the Starkit distribution that was
present in earlier versions of TWAPI. It has the advantage over the
Starkit distribution in that it does not require starkit and vfs
support in the core Tcl and in addition loads significantly faster
than the Starkit.
To install either ZIP distribution, unzip it into a directory
that is included in the path contained in your Tcl auto_path variable. The ZIP distributions can be used by
both 32-bit and 64-bit Tcl from the same location.
The Tcl module distributions can be used with Tcl 8.5 or later.
To install, copy the file into one of the directories returned by
Tcl's ::tcl::tm::path list command and rename it
to twapi-VERSION.tm (i.e. remove the PLATFORM string).
The standalone DLL distributions are self-contained and may be
placed anywhere. However, they are not discoverable by Tcl's
package mechanism and must be explicitly loaded through Tcl's
Once installed, all distributions, except the standalone DLL,
can be loaded into an interpreter using the command
package require twapi
In the case of the ZIP distributions, the 32- or 64-bit DLL will
be loaded as appropriate. In case of the TM module, however,
co-location of 32- and 64-bit modules is not possible.
The standalone DLL must be loaded using the command
load PATH_TO_TWAPIDLL Twapi
where the path must point to the 32- or 64-bit DLL as
All commands installed by this extension fall under the
twapi:: namespace. The commands are not exported
from the namespace by default. To import the commands, they must
first be exported by calling ::twapi::export_public_commands. Alternatively, you can
call ::twapi::import_commands to import all
Copyright © 2003-2010 Ashok P. Nadkarni