Product Documentation

TDK 3.2 Documentation

Table of Contents
ActiveState, a division of Sophos

Package Editor

The Package Editor is a graphical application used to define packages containing groups of files. Packages can be used in TclApp. By creating package definitions, it is not necessary to specify individual files when creating applications in TclApp; also, packages can be modified and re-used by multiple applications built with TclApp.

Numerous predefined packages are included with ActiveTcl. Package definition files have the extension ".tap". The Package Editor is 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.

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.tcl at the command prompt. On Unix, enter tclpe at the shell prompt. Some Package Editor features are available as command-line switches, including -pkg, -alias, -relativeto and -anchor. These switches are described in the sections below.

To change the font size displayed in Package Editor, press Ctrl-plus to increase the font size displayed or Ctrl-minus to decrease the displayed font size. If you are using Windows with a mouse wheel, you can alternatively press the Ctrl key and then rotate the mouse wheel to increase or decrease the font size displayed in Package Editor.

Creating a New Package

Packages are created within projects. When the Package Editor opens, a new project is created by default. To manually create a new project, select File | New. To create a new package, click the New Package button. By default, the package will be named "New Package n", where n is an incrementing number.

Describing the Package

The Description tab of the Package Editor 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.

  • 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).
  • 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 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.

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.

Top

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.

Top

Create a New Package and Scan the Directory

The Tcl Package Editor Create New Package, Scan Directory functionality scans and extends the current project with all provided packages and files. A single .tap file for the package directory is then generated. To create a new package and scan the directory:

  • Click Create a New Package and Scan the Directory.
  • Select the desired directory.
  • Click OK.
  • The scan locates all required packages and files. A single .tap file for the package directory is created.

To manually create a new project, see Creating a New Package for more information.

Top

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.

Top