Defining New uses Options

Defining New uses Options

TclPro Wrapper recognizes files with the .uses extension as providing additional uses configurations. For example, a file new.uses directory defines a configuration named "new" that you can use as a uses option.

When you specify a uses option, TclPro Wrapper checks to see if it is a built-in configuration first. If not, if looks for a .uses file with the proper name in the lib/prowrapuses directory of the TclPro installation (that is, lib/prowrapuses should be at the same level as the lib/tcl8.3 directory). If TclPro Wrapper doesn't find the proper file there, it finally checks the directory from which you execute prowrap.

You can also specify an absolute or relative path as an argument to the uses option. For example, specifying uses C:\Tcl\Wrapper\custom causes TclPro Wrapper to use the configuration file C:\Tcl\Wrapper\custom.uses.

The lib/prowrapuses directory of the TclPro installation contains Tcl scripts showing the definitions of the built-in uses options. You can use these files as templates for creating your own -uses configurations.

Note: Modifying these files does not change the behavior of the built-in -uses configurations; they are only sample files. To use them, you can copy them, rename them, and modify them as needed.

TclPro Wrapper evaluates the contents of a .uses file when it prepares to wrap an application with that configuration. The .uses file must contain a Tcl script that returns a Tcl list providing additional TclPro Wrapper command-line arguments. These arguments should typically specify the following:

an executable option specifying a Tcl or interpreter
if this option produces statically-wrapped applications, all initialization and support files required by the interpreter (for example, the contents of the Tcl and Tk lib directories and their subdirectories)
a tcllibrary option specifying the location Tcl initialization library files (that is, the value of the Tcl tcl_library variable)
if the option includes a Tk interpreter, a code option setting the value of the tk_library variable
if this option provides built-in support for additional Tcl libraries or packages, the script and index files for these packages as discussed in "Wrapping Libraries and Packages"
optionally, one or more code options to perform any other required initialization of a wrapped application (for example, setting any required values for an included package)
optionally, any other desired script or data files

Note: As with any other file reference in a wrapped application, the file references you provide to the tcllibrary and code options can refer to either a file on the disk or a file in the internal file archive. In other words, if you provide an absolute pathname, your application looks for the initialization files on the disk when it runs. On the other hand, if you specify a relative pathname, your application first looks in its internal file archive for the initialization files, and looks on the disk only if the files don't exist in the archive. Also remember that TclPro Wrapper strips the initial "/" from absolute pathnames when wrapping files, and therefore wrapped initialization files have relative pathnames in the archive. For more information on file access in a wrapped application, see "How the Internal File Archive Works in a Wrapped Application".

For example, suppose you create a custom, statically-linked Tcl interpreter with the name siteTclsh1.0 and place it in the directory /usr/local/tcl/site1.0/bin. In addition to the standard Tcl script library files, located in /usr/local/tcl/lib/tcl8.3, your custom interpreter requires the custom initialization and support files site.tcl, siteApp.tcl, and help.txt, which you place in the directory /usr/local/tcl/site1.0/lib. Your custom interpreter uses a custom Tcl variable, site_library, to locate its initialization and support files. To define this interpreter and support files as a custom uses option named "siteTclsh", create the file siteTclsh.uses and place it in the lib/prowrapuses directory. The siteTclsh.uses file would contain:

# siteTclsh.uses
return [list \
    -executable /usr/local/tcl/site1.0/bin/siteTclsh1.0 \
    -relativeto /usr/local/tcl \
    /usr/local/tcl/lib/tcl8.3/*.tcl \
    /usr/local/tcl/lib/tcl8.3/tclIndex \
    /usr/local/tcl/lib/tcl8.3/encoding/*.enc \
    /usr/local/tcl/site1.0/lib/site.tcl \
    /usr/local/tcl/site1.0/lib/siteApp.tcl \
    /usr/local/tcl/site1.0/lib/help.txt \
    -tcllibrary lib/tcl8.3 \
    -code "set site_library [file join site1.0 lib]" ]

You could then wrap applications using this custom shell by specifying the uses siteTclsh option. For example, the following TclPro Wrapper command would create a wrapped application based on siteTclsh1.0 with file1.tcl as the startup script:

% prowrap -uses siteTclsh file1.tcl file2.tcl

http://www.ajubasolutions.com
Voice: (650) 210-0100
Fax: (650) 210-0101
support@ajubasolutions.com