Installation and Usage

Installation requirements and usage instructions

DESCRIPTION

System Requirements

The 32-bit builds of the TWAPI extension require

• Windows XP or later,
• Tcl version 8.5 or later.

The 64-bit builds of TWAPI require

• Windows 2003 Server or later,
• Tcl version 8.5 or later.

For Windows 2000, use TWAPI 3.0 or earlier. For Windows NT 4.0 (SP3 or later), use TWAPI 1.1.5 or earlier releases.

Distribution formats

The software is distributed in multiple forms (PLATFORM may be x86 or x64 for the 32- and 64-bit builds respectively):

• 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 find it.
• 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 64-bit Tcl.
• The standalone DLL and the Tcl module distributions provide the convenience of single file deployment. 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. The standalone DLL has the advantage that it does not rely on creation of temporary files during loading. Note both these have 32- and 64-bit platform-specific versions.
• 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 exists.
• 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.

Installing TWAPI

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 load command.

Loading TWAPI

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 appropriate.

Commands

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 TWAPI commands.

COPYRIGHT

Copyright © 2003-2011 Ashok P. Nadkarni