prowrap(1)

NAME
prowrap - TclPro Wrapper

SYNOPSIS
prowrap ?options ...? ?fileNamePattern ...? ?options? fileNamePatterns ...

OPTIONS

-help
    Displays usage information, then exits without doing anything.

-nologo
    Hides the copyright and version information.

-verbose
    Produces detailed output during the wrapping process.

-uses usesSpec
    This flag selects one of several predefined configurations for wrapping. Each configuration causes a particular base application to be included in the wrapped application along with any auxiliary files needed by the base application, such as script library files. UsesSpec may be one of the built-in specifications from the following list:

    tclsh
        Uses tclsh as the base application (Tcl 8.0.5).

    wish
        Uses wish as the base application (Tcl 8.0.5 and Tk 8.0.5).

    bigtclsh
        Uses tclsh as the base application; includes Tcl 8.0.5 plus [incr Tcl] 3.0, TclX 8.0.5, and Expect 5.29 (on UNIX only).

    bigwish
        Uses wish as the base application; includes Tcl 8.0.5 and Tk 8.0.5, plus [incr Tcl] 3.0, [incr Tk] 3.0, [incr Widgets] 2.2, [incr Widgets] 3.0, TclX 8.0.5, TkX 8.0.5, and Expect 5.29 (on UNIX only).

    itclsh (deprecated)
        Uses tclsh as the base application; includes Tcl 8.0.3 plus [incr Tcl] 3.0. This flag uses the same base application as bigtclsh, but appropriate initialization is performed to maintain backward compatibility. Support for this uses specification will be removed in future versions of TclPro.

    iwish (deprecated)
        Uses wish as the base application; includes Tcl 8.0.3 and Tk 8.0.3, plus [incr Tcl] 3.0, [incr Tk] 3.0, [incr Widgets] 2.2, and [incr Widgets] 3.0. This flag uses the same base application as bigwish, but appropriate initialization is performed to maintain backward compatibility. Support for this uses specfication will be removed in future versions of TclPro.

    tclsh-dynamic
        Same as tclsh except doesn't include the Tcl shared library or Tcl library scripts; TclPro must be installed on any machine where the wrapped application executes.

    wish-dynamic
        Same as wish except doesn't include the Tcl and Tk shared libraries or the Tcl and Tk script libraries; TclPro must be installed on any machine where the wrapped application executes.

    The default value for this flag is bigwish. A usesSpec of an empty string (e.g., "") directs prowrap to not use any settings for the -uses flag. See the section CUSTOM -USES CONFIGURATIONS below for information on how a site may define new usesSpec values.

-startup initialScriptFileName
    By default, prowrap uses the first file from the command line as the startup script file for the wrapped application. This flag allows you to override the default and direct prowrap to instead use initialScriptFileName as the name of the file that is to be sourced when the wrapped application is started. This flag does not cause TclPro Wrapper to actually include the file; the file must also be specified as one of the fileNamePattern arguments. If you want to create an interactive Tcl shell (e.g., one that does not have a specific startup script file) with wrapped files, specify initialScriptFileName as the empty string (e.g., ""); this empty string specification may also be used if the executable named by the -executable flag internally handles initialization and boot-strapping on its own (see prowrap(3)).

-arguments arguments
    Specifies additional arguments to your wrapped applications, just as if they were submitted to your unwrapped application on the command line. The given arguments are inserted before any command line arguments entered by your end-user and will appear in the Tcl argv variable. If -startup is called with the empty string, then the first element of arguments is taken as the startup file. The arguments must be passed to prowrap as one string; use proper quoting convention for your command shell to preserve an argument string that may contain spaces.

-out fileName
    FileName specifies the name of the output file in which to create the wrapped application. Without the specification of this flag, prowrap creates a wrapped executable with the name prowrapout (with a .exe extension on Windows) in the working directory where TclPro Wrapper was invoked. Use this flag to produce a file with a different name. If the named file already exists, it is overwritten.

-relativeto directory
    If this flag is specified, each of the fileNamePattern arguments that follow must have directory as its leading characters. The name used for the file in the wrapped application will consist of fileNamePattern with the leading directory characters removed. If this switch is not specified, or is specified as an empty string, then the name of each file in the wrapped application is the same as its fileNamePattern. Multiple -relativeto flags may appear on the command line and each instance applies to the file names between it and the next -relativeto flag. See the section RELATIVE PATHS for more details.

-executable exeName
    Specifies the file name for the base application that will be used for the wrapped application. This executable must include the TclPro wrapper library (see prowrap(3). This flag is not required if you use the -uses flag.

-code script
    This switch is not normally needed; it is used primarily to specify the locations of library directories in the definitions of custom -uses configurations. Script contains a Tcl script that is evaluated when the wrapped application starts up. The script is invoked very early in application initialization, before Tcl_Init or any package-specific initialization procedures have been invoked. Multiple -code scripts may be specified and prowrap arranges for these scripts to be evaluated in the order they appear on the command line.

-temp directory
    Use the specified directory to temporarily hold files created during the wrapping process. By default, TclPro Wrapper uses the directory given by either TEMP, TMP, or TMPDIR environment variables (checked in that order); if no such environment variable exists, on UNIX the temporary directory falls through to the /tmp directory and on Windows an error is generated.

-@  Get additional command line specifications from standard input. Flags from standard input are processed after all other flags on the actual command line. This flag is useful if the command line becomes too large to be submitted to the current command processor (e.g. sh, CMD.EXE, etc.) or can be used as a more convenient way to specify command line arguments to prowrap.

Except for the -relativeto and -code flags, all other flags may appear more than once, but only their last occurrence is used as the actual value for the respective flag. Multiple -relativeto flags may appear on the command line and each instance applies directory to all fileNamePatterns that follow it. Multiple -code options may be specified and prowrap arranges for these scripts to be evaluated in the order they appear on the command line.

DESCRIPTION
The command prowrap invokes TclPro Wrapper. TclPro Wrapper is a utility for bundling together a collection of Tcl scripts and other files along with a Tcl interpreter into one executable file. The resulting executable is a self-contained Tcl application that can be run like any other executable.

TclPro Wrapper works by appending the collection of Tcl scripts and other files to the end of a base application containing a Tcl interpreter. The base application includes a special package that allows it to access the wrapped files as if they were actually separate files on disk. The result is that your existing Tcl scripts can be wrapped with very few changes to your source code.

You may wrap any type of file that your application would otherwise access from disk. Here are some examples of the types of files that TclPro Wrapper can include:

    • Tcl scripts (either text files or compiled .tbc files)
     that are accessed via the source command.
    • Data files that are accessed via the open command.
    • Image files that are accessed via the -file option to the image command.
    • Bitmap files that are specified with the ``@'' syntax of the -bitmap option.
    • The standard library files for Tcl, Tk, and extensions such as [incr Tcl].

The various command-line flags to TclPro Wrapper define the locations of the above Tcl application components. Deciding how to craft the prowrap command line with its various flags, file name, and directory patterns is closely connected with the current working directory from which the tool is invoked. Another detail to keep in mind when wrapping your application is how your Tcl source performs file referencing during its runtime.

A typical use of TclPro Wrapper will be to create a stand-alone application using one of the various built-in -uses configurations. A more complex use of TclPro Wrapper is to create a stand-alone application using a custom Tcl shell. You will need to compile and link your own custom Tcl shell to include the TclPro Wrapper library (see prowrap(3)). Once built, this executable is specified to prowrap via the -executable flag or through a custom -uses option.

ACCESSING FILES IN THE WRAPPED APPLICATION
An application created by TclPro Wrapper has the files it needs during runtime wrapped together with the application itself. The Tcl scripts that run within the application access the files as if they were on disk. However, those files really only exist within the application itself. This leads to some subtle issues users should be aware of when using TclPro Wrapper. Fortunately, by following some simple guidelines users can easily wrap complex applications.

The wrapped files appear to your application's Tcl code as a file hierarchy accessible from your current working directory. (This is true no matter what directory your application has as its working directory.) For example, if you had a file wrapped as util/io.tcl you will be able to source that file with source util/io.tcl no matter what your current directory is when the wrapped application runs.

When designing an application that will be wrapped, you should organize your file usage so that the application will work equally well unwrapped and wrapped. This way you can test your application in unwrapped form, then wrap it for delivery to your customers without having to change anything in the application.

If your application reads files that will be part of the wrapped application, always use relative names to read those files. For example, suppose the directory where you develop the application has a subdirectory util and that the application needs to source a file io.tcl in that directory. Then you should use the following command in your application to read the file:
           source [file join util io.tcl] When you are testing the application, your working directory needs to be the directory containing util so this command will work. If you then wrap the file with the name util/io.tcl, the same command will work in the wrapped application.

If your application doesn't currently use relative file names like this, you will need to modify the application before you can wrap it with TclPro Wrapper. For example, some applications reference files that are part of the application with absolute names in a library directory. For example, the file io.tcl above might be read with the following command:
            source [file join $libDir util io.tcl] In this case $libDir might refer to the place where the application is installed, such as C:\Program Files\MyApp. In examples like this, you will need to modify the code to behave differently depending on whether the application is wrapped. TclPro Wrapper arranges for the variable tcl_platform(isWrapped) to have the value 1 if an application is wrapped. If the application isn't wrapped then this variable will not exist. The following code sample shows how to use the variable to make your application behave correctly whether it is wrapped or not:
             if {[info exists tcl_platform(isWrapped)]} {
                 source[file join util io.tcl]
             } else {
                 source [file join $libDir util io.tcl]
             }

ACCESSING THE FILE SYSTEM FROM WRAPPED APPLICATIONS

The second issue related to file names is how to ensure that your wrapped application uses a disk file instead of a wrapped file, when that is needed. For example, suppose your application allows its user to enter a file name for the application to manipulate. In this case you will always want to use the file from disk. However, if the user enters a relative name like util/io.tcl and the application uses this name to open the file, and there is also a file by that name wrapped with the application, then the application will access the wrong file!

Fortunately, there is an easy workaround for this issue. Whenever your code gets a file name from a user, you must convert the file name to an absolute name before opening the file. This guarantees that a wrapped file will not be used. If the variable $path contains a file name typed by a user, the following code will convert it to an absolute path name:
            set path [file join [pwd] $path]

FILE PATTERN SPECIFICATION

The fileNamePatterns arguments to prowrap identify files to be wrapped. There must be at least one file name specified to be wrapped. They may include relative paths as well as fully-qualified absolute file paths. On UNIX, wild cards can be used to allow the shell (e.g. sh, csh, etc.) to expand the fileNamePatterns into lists of matching file names. On Windows, prowrap uses the Tcl's glob command to expand fileNamePatterns into lists of matching names.

For example, a file name pattern specification of: /myApp/*.tcl would include all .tcl files in the ``/myApp'' directory.

If the -startup flag is not used, then the first file name on the prowrap command line is used as the startup file for the wrapped application. (Care should be taken to ensure that if the first fileNamePattern contains wild cards, the first file name in resulting expansions is the desired startup file.)

TclPro Wrapper keeps only relative file information within the wrapped application. The leading directory character (e.g. '/') of any absolute path is automatically stripped off. For example, the file path specification /home/joe/tclApp/app.tcl is stored as home/joe/tclApp/app.tcl. To locate this file at runtime, the Tcl script must access the file by the name home/joe/tclApp/app.tcl.

RELATIVE PATHS

The -relativeto flag is used to remove leading directories from the file names stored in the wrapped application. The value following the -relativeto flag specifies the part of the file name that is to be omitted. Consider the following options specified on a prowrap command line: -relativeto /home/joe /home/joe/tclApp/app.tcl The file /home/joe/tclApp/app.tcl will be wrapped under the name tclApp/app.tcl instead of /home/joe/tclApp/app.tcl and must be accessed by the wrapped application using the shorter name.

A -relativeto flag applies to all of the files following it up to the next -relativeto flag. If no -relativeto flag has been specified, or if the most recent -relativeto flag was specified with an empty string argument, then files are stored under the same names used to specify them on the command line.

CUSTOM -USES CONFIGURATIONS

You can extend the set of configurations understood by the -uses option by creating a directory with the name prowrapuses in the lib directory of your TclPro installation tree (e.g., adjacent to the lib/tcl8.0 directory). Files in this directory that end with the .uses extension are recognized by prowrap to provide additional -uses configurations. For example, a file new.uses in the prowrapuses directory will define a configuration named new, which may be used in -uses options. Prowrap will also find and use .uses files in the current working directory. The builtin configurations have highest priority, followed by those in the prowrapuses directory, followed by those in the current working directory.

The contents of a .uses file is a Tcl script that is evaluated in a special Tcl interpreter during the execution of prowrap. Prior to the script evaluation, prowrap changes the working directory to the directory where the .uses file is located. This gives the script a point of reference from which to locate other files relative to itself. The working directory is restored once the script returns. The evaluated script must return a Tcl list that contains additional prowrap command line arguments. The script may include the -relativeto flag, but the specified directory will only apply to files that appear in the returned list of additional command line arguments.

For example, suppose you were to create your own Tcl shell with the name siteTclSh10 and place it in the directory /usr/local/siteTclSh/solaris-sparc/bin. If this shell requires library script files that have been placed in the lib/site1.0 directory, adjacent to the prowrapuses directory, you should list them within the script. The -code flag can be used to set a Tcl variable that will specify the location of the wrapped library script files; the siteTclSh10 executable can use this Tcl variable to locate and source one of the library script files in its Tcl_AppInit routine. To provide this shell to your site, create the file siteTclSh10.uses and place it in the lib/prowrapuses directory. The contents of the file would look something like: # lib/prowrapuses/siteTclSh10.uses return [list -executable /usr/local/siteTclSh/siteTclSh10 -relativeto ../../ \
    ../../lib/site1.0/site.tcl ../../lib/site1.0/siteApp.tcl ../../lib/site1.0/site.gif \
    -code "set site_library lib/site1.0"] The following prowrap command line is used to create a wrapped application based on siteTclSh10, with file1.tcl as the startup script file: prowrap -uses siteTclSh10 file1.tcl file2.tcl

EXAMPLES
The simplest command is to wrap a set of Tcl files. The result of the command below is a wrapped application that includes wish, including Tcl, Tk, [incr Tcl], [incr Tk], [incr Widget], any auxiliary files needed by these packages, plus the files file1.tcl and file2.tcl: prowrap file1.tcl file2.tcl The next example wraps a single Tcl script up with the tclsh application: prowrap -uses tcl myScript.tcl

The following command wraps the HiQ demo application using wish. The resulting application is completely stand-alone and will not require any install step for itself or Tcl/Tk. Assuming the current working directory is demos/HiQ: prowrap -uses wish -out hiq -startup hiq.tcl hiq.tcl hiqGUI.tcl hiqState.tcl

The final example wraps the familiar widget demo included as part of the standard Tk distribution. This example uses a dynamically linked wish and thus expects TclPro to be installed on the system where the resulting executable is run (furthermore, TclPro must be installed in the same place where it was installed when the application was wrapped). Assuming the current working directory is the location of the file widget.tcl: prowrap -out widgetDemo -uses wish-dynamic -startup widget.tcl *.* images/*.*

INFO-ZIP COPYRIGHT INFORMATION
TclPro Wrapper incorporates compression code from the Info-ZIP group. There are no extra charges or costs in TclPro due to the use of this code, and the original compression sources are freely available from http://www.cdrom.com/pub/infozip/ or ftp://ftp.cdrom.com/pub/infozip/ on the Internet. We thank the Info-ZIP group for an outstanding piece of open source software.

SEE ALSO
prowrap(3)

KEYWORDS
prodebug procomp procheck prowrap