Tcl Dev Kit User Guide

Package Editor
The Package Editor is a graphical application used to define Tcl packages in TEApot format (.zip and .tm files) or TclApp Package format (.tap files). Both types of packages can be used by TclApp. Creating package definitions simplifies the creation of applications in TclApp as included files do not have to be specified individually. Packages can be modified and re-used by multiple applications built with TclApp. TEApot packages can also be hosted in a TEApot repository and made available to ActiveTcl TEAcup clients. Numerous predefined packages in .tap format are included with ActiveTcl 8.4 and earlier. Many more packages are available from ActiveState's TEApot repository. These packages can be installed using ActiveTcl's TEAcup client. The Package Editor can be used to modify existing packages, regardless of whether they are custom packages or predefined packages included with ActiveTcl. Multiple packages can be configured within the same Package Editor project. Each package will be displayed as an individual entity in the TclApp Package Picker dialog; however, by grouping multiple packages together into one project, you can easily maintain file sets in related packages.

Starting the Package Editor

To launch the Package Editor in Windows, select Tcl Dev Kit Package Editor from the Tcl Dev Kit program group on the Windows Start menu. Alternatively, you can invoke the Package Editor from the command line. On Windows, enter tclpe.exe at the command prompt. On Unix, enter tclpe at the shell prompt. Project files can be specified at the command line. For example:
tclpe -gui myproject.tap

Types of files that can be loaded as projects include:

teapot.txt files (TEApot package descriptors) .tap files (TclApp packages) starkits and starpacks zip archives tcl modules

Use 'Ctrl-plus' and 'Ctrl-minus' to increase or decrease the displayed font size. Alternatively, use 'Ctrl-mouse wheel'.

Teapot Packages
1

To create a project for packages in TEApot format, select New Project (Teapot) from the File menu. A new TEApot package project is created by default when the Package Editor is started.

Creating a New TEApot Package

Packages can be added to a project individually by clicking the Create a New Package button, or imported automatically by clicking the Scan Directory button. In most situations where the Tcl files you want to package exist in a particular directory (and nested sub-directories), the Scan Directory is the simplest way to begin.

Scanning Directories
Scan Directory opens a dialog box for choosing a source directory. Enter the directory to scan in the Destination field, or click the Browse button on the right. The Package Editor scans the source directory for a pkgIndex.tcl file. If present, it will use this as a starting point for a heuristic scan for packages and files to be included in the project. If it is not present, the path displayed in the Destination field will be highlighted, indicating that scanning is not possible. Click Run to initiate the scan. The output pane below displays information on the scanning progress. Warnings are highlighted in yellow, errors are highlighted in red. Packages discovered in the scan are added to the project and appear in the left pane where they can be reviewed. Note: TEApot projects generate a file called teapot.txt in the source directory when the project is saved, so the source directory must be writable.

Basic TEApot Package Information

The Basic tab is used to record general information about the package. This information is for package administration purposes; a subset of the information is displayed in TclApp's Package Picker dialog, and can be used with the -pkg option in the command-line version of TclApp.

This tab includes the following fields:

Type: A drop-down list with options for specifying what kind of TEApot entity is being created: o Application: An Tcl based application with meta data. o Package (default): A Tcl package. o Profile: A named collection of references to other entities (i.e. meta data only). Name: The entity name. Version: A version number for the entity. Platform: The target platform for the package. By default, this field shows the platform the Package Editor is currently running on. Summary: A short summary of what the package is or does. Description: A longer description of the package.

TEApot Package Files

The Files tab is for specifying files for inclusion and exclusion for the package. Scan Directory will populate the Included Files list with the relevant files discovered in the scan. The Included Files and Excluded Files fields accept glob style wildcards (e.g. "*" and "?") for specifying multiple files with a particular extension or text string in the name. To exclude files, use the Remove button to take files out of the list, or if glob style matching is being used in Included Files, by adding specific files to the Excluded Files list.

TEApot Package Requirements

3

The Requirements tab is for specifying the package requirements (Tcl version, module dependencies, etc.). To add a requirement, enter the package name or version in the entry field and click the Add button. Requirements must be entered in TEApot's entity reference syntax. If the syntax is incorrect, the text in the entry field is highlighted, and a tooltip provides information on the error.

TEApot Package Recommendations

The Recommendations tab is for specifying packages which are beneficial to, but absolutely necessary for the functioning of the module. The interface is the same as the Requirements tab.

TEApot Package Indexing

TEApot packages can contain Category and Subject meta data to make it easier to find them in a TEApot repository (i.e. using teacup search ...). The Category field is for a one line sentence, and the Subject / Key Phrases is for a list of words and phrases. Add a Category value by entering it in the Category text field. Add items to the Subject list by entering words or phrases in the Subject / Key phrases text field, then clicking the Add button.

TEApot Package Other Metadata

In addition to the Category and Subject meta data, other arbitrary and predefined meta data can be added to TEApot packages as key/value pairs. See Keywords with predefined semantics for more information on TEApot's "reserved" keywords. Enter key/value pairs in the Keyword and Value columns respectively. Hitting 'Enter' adds the current pair, clicking the Remove button deletes the adjacent entry.

Saving a TEApot Project

After configuring a TEApot package, select File | Save Project As to save the package definition in a file called teapot.txt in the source directory. This directory must be writable.

Generating a TEApot Archive

Once a project has been configured with all the necessary files and data, a TEApot package archive can be created. The Generate TEApot Archives button brings up a dialog box with the following options:

Destination: The directory to save the archive to. Archive format: Choose from tm (Tcl module), zip, or auto (default). Compile to bytecode: Invokes the Tcl compiler on the files in the package. Timestamp the version: Adds a date/time-stamp to the version metadata.

Once these options have been set, click the Run

TclApp Packages
4

To create a project for packages in TclApp (.tap) format, select New Project (Tap) from the File menu. The Scan Directory feature works essentially the same in a Tap project as in a TEApot project, but does not generate a teapot.txt file in the scanned directory. See Scanning Directories above for more information.

Creating a New TclApp Package

To add a package to a project, click Create new package. These packages can be added to a new project or added to a project that has already been populated by Scan Directory. By default, new packages within the project are named "New Package n", where n is an incrementing number. This can be modifed in the Name field on the Basic tab.

Basic TclApp Package Information

The Basic tab is used to record general information about the package. This information is for package administration purposes; a subset of the information is displayed in the TclApp Package Picker dialog, and can be used with the -pkg option in the command-line version of TclApp.

This tab includes the following fields:

Name: The contents of this field will be displayed in TclApp's Package Picker dialog. It is also the value specified when using the -pkg switch with the command-line version of TclApp. Version: The contents of this field will be displayed in TclApp's Package Picker dialog. It can also be part of the value specified when using the -pkg switch with the command-line version of TclApp (specified in the form of PKGNAME-VERSION).
5

Platform: The contents of this field will be displayed in TclApp's Package Picker dialog. Hidden: If this box is checked, the package will not be visible in the TclApp Package Picker dialog. Same files as: This field is used to assign a file set definition from an existing package to the new package. See Copying File Lists from One Package to Another below. Description: The contents of this field will be displayed in TclApp's Package Picker dialog.

Copying File Lists from Another Package To copy a list of files from an existing package to a new package, first open the existing package using the File | Load Project menu option. Then click the New Package button. While the new package is selected in the package list (on the left side of the Package Editor), check the Same files as box, and select the desired package from the drop-down list. If you are creating multiple new packages at the same time, note that only the packages that were opened before the current package will be available in the Same files as drop-down list. For example, if you create a new package called "foo", and then create a new package called "bar", the "foo" files will be available to the "bar" package, but the "bar" files will not be available to the "foo" package.

Adding Files to the TclApp Package

Use the Files tab to add files to the package. Files can be specified individually (beneath a "base" directory), or can be specified as a subset of files under a directory (for example, using wildcards).

Use the arrow buttons on the left side of the file display to move files and directories up and down the list. For example, files can be moved from one directory to another using these buttons.

Adding Base Directories and Files Before adding individual files, you must specify a base directory. The base directory can be any directory that is above the desired file(s). To add a base directory, enter the name of the directory in the field at the top of the form, or click the Folder button and browse to the desired directory. Files can be added by either manually entering the name in the field at the top of the form, or by browsing for the file using the Files button. When manually entering the file name, you may use wildcards to select groups of files with similar name characteristics. You will not be able to add a file unless a base directory (that exists above the location of the file in the filesystem hierarchy) is selected in the file list. Adding Multiple Files in a Directory Use the "Files in Directory" button to select both a base directory and all the files and directories beneath it. Setting an Alias Path or File Name The alias button is used to specify an alternate name and / or location for a file. This corresponds to TclApp's -alias command-line switch. It can be used in conjunction with the TclApp -relativeto and -anchor switches to configure the destination filesystem. Including or Excluding Files or Directories Use the Toggle Incl/Excl button to exclude files or directories from the TclApp application without removing from the package definition. Using Placeholders for Portability By default, only absolute paths can be specified as the base directory. This reduces the portability of package definition files, as absolute paths are dependent on the configuration of the system where the package definition file was created. By replacing absolute paths with "placeholders", package definition files can be used on systems that do not necessarily share the same configuration. For example, the image above shows the use of the @TCL_LIBDIR@ placeholder. When TclApp builds an application based on this package definition, it will substitute the lib directory beneath the installation directory of the Tcl Dev Kit on the system where TclApp is run. The following placeholders can be used in place of an absolute directory specification:

@TDK_INSTALLDIR@: The directory where the Tcl Dev Kit is installed on the system where TclApp is run. @TDK_LIBDIR@: The main TAP search path under which a .tap file was found. For example: If we have the TAP search paths FOO/lib and BAR/lib, then @TDK_LIBDIR@ is set to FOO/lib for a tap file named FOO/lib/sub/sub.tap, and set to BAR/lib for a file named BAR/lib/pkg/pkg.tap @TAP_DIR@: The directory where the package definition file is located on the system where TclApp is run.
7

To substitute a placeholder for an absolute path, click on the desired folder in the list, then click Edit and enter the desired placeholder.

Saving a Package Definition

After configuring a package, select File | Save Project As to save the package definition in a project file with a .tap extension.

Using a Package Definition in TclApp

Packages are added to TclApp projects using the Package Picker button on the Files tab of the graphical TclApp. If you are using the command-line version of TclApp, use the -pkg switch followed by the package name.

Editing or Deleting Package Definitions and Files

To edit an existing package, select File | Load Project, and open the desired package file. The package descriptions and associated files will be displayed on the relevant tabs. Make the desired changes to the package(s), and then click File | Save Project to save the changes. To edit or delete files from a package, select the Files tab. Click on the desired files or directories in the list, then click Edit (to change the file or directory name or location) or Delete (to delete the file from the package). To delete an existing package, select File | Load Project, and open the desired package file. Click the Delete button. 2012 ActiveState Software Inc. All rights reserved. ActiveState, Komodo, ActivePerl, ActivePython, ActiveTcl, and Stackato are trademarks or registered trademarks of ActiveState. All other marks are property of their respective owners.

Tcl Dev Kit (TDK) Overview

Tcl Dev Kit (TDK) provides essential tools for Tcl programmers, making it easy to create, build and deploy applications. Rapidly deploy Tcl applications to a broad range of platforms*, as ready-to-run executables, starkits or starpacks. Simplify development with tools for finding and fixing bugs, managing complex code bases, and optimizing your programs. Take control and work the way you want with a choice of GUIs or command line interfaces for most tools. TDK 5 supports ActiveTcl 8.4 through 8.6.

Deploy

Deliver your Tcl programs as executables, starkits or starpacks. Tamper-proof your applications, and protect your code from prying eyes. Run and manage your Tcl code as Windows services. Create, manage, export and use TEApot package repositories.

Fix

Kill bugs fast with the cross-platform graphical debugger. Quickly find errors before running your scripts. Uncover tricky problems by inspecting Tcl programs while they run.

Improve

Improve code performance and reliability through coverage and hotspot analysis. Understand complex code at a glance with a visual guide to component relationships.

* TclApp cross-platform wrapping targeting Solaris, HP-UX and AIX may require an ActiveState Business Edition license.

Licensing
Licenses are user-based, so a single license covers you across all the languages, platforms, and systems you useat home, at work, or at the coffee shop. And licenses include all point release updates (such as from Tcl Dev Kit 5.0 to 5.1, 5.2 etc), so you're always up to date. Nice, huh? Read the license agreement for details.

Pricing
TDK starts at $295 US for all the languages, platforms, and systems you use. Licenses include all point release updates (such as from TDK 5.1 to TDK 5.2). TDK team pricing: Save 20% on licenses when you buy a 5-pack.
9

Upgrade to TDK 5

Upgrades from TDK 4.x start at $168 US Upgrade to ActiveTcl Pro Studio o ActiveTcl Pro Studio includes TDK, Komodo IDE, and Safari Books Online, plus all upgrades for one year, in a single value-priced bundle. With current TDK or Komodo IDE: starting at $268 US As a new purchase: $595 US

Please email [email protected] for a custom quote if you require 30 or more subscriptions.

Additional Resources
Download the Tcl Dev Kit Datasheet Read the Tcl Dev Kit Documentation "The quality of ActiveState's Tcl Dev Kit really shows. It has a really intuitive user interface." Joe Mistachkin, Principal Software Engineer, TclBridge. Read more testimonials.

10