 |
 |
Tutorial: Building TclApps
- Introduction
- Step One: The BWidgets Package
- Step Two: Creating an Application Without an Interpreter (Starkit)
- Step Three: Creating an Application With an Interpreter (Starpack)
- Step Four: Wrapping Extensions and External DLLs
Introduction
This tutorial shows how to use the Tcl Dev Kit's TclApp to generate a standalone application that contains all necessary components (the Tcl script, libraries and supporting files, a base kit containing an interpreter, extensions and non-Tcl DLLs) to run the application.
The first part of this tutorial makes use of the BWidget demo included with the Tcl Dev Kit. In the first section, we'll analyze the package containing the files to be wrapped. In the second section, we'll create a single file that contains the files listed in the package, and a script (and supporting files) that uses them. In the third section, we'll create a standalone executable that contains the files listed in the package, the script and supporting files, and Tcl interpreter. In the fourth section, we'll create an application that includes external DLLs.
Step One: The BWidgets Package
The Tcl Dev Kit's Package Editor is used to create lists of files that will be included in applications generated by TclApp. In this tutorial, we will be creating an application containing the BWidgets demo. The Tcl Dev Kit contains a corresponding package definition file for the BWidgets demo.
To open the Package Editor, select Programs | ActiveState
Tcl Dev Kit | Tcl Dev Kit Package Editor from the Windows Start menu.
Alternatively, you can run the Package Editor from the command line. On Windows,
enter tclpe.tcl at the command prompt. On Unix, enter
tclpe at the shell prompt. (The Package Editor is only available
as a graphical application; there is no corresponding command-line interface.)
To open the BWidgets package definition file, select File | Load Project,
and open the file bwidget.tap, located by default in the directory
Tcl/lib/BWidget1.6.
The @TAP_DIR@ placeholder is used in place of an absolute path
to make the package definition portable. When TclApp processes a package
definition containing the @TAP_DIR@ placeholder, it substitutes
the path to the directory where the package definition file was located. See
"Using Placeholders for Portability" in the
Creating a New Package section of
the Package Editor documentation.
Step Two: Creating an Application without an Interpreter (Starkit)
A "starkit" is a single file that contains Tcl scripts, platform-specific compiled code and application data. It requires an external interpreter to run. In this step, we'll use TclApp to create a starkit that contains the files listed in the package definition we viewed in step one and additional supporting files.
Select Programs | ActiveState Tcl Dev Kit | Tcl Dev Kit Demos | Wrapping | BWidget Demo | Create Starkit from the Windows Start menu. Alternatively, run TclApp from the command line.
On the Windows command line enter:
tclapp.tcl -gui C:\Tcl\demos\TclDevKit\TclApp\BWidgets\demo_starkit.tpj
On the Unix command line enter:
tclapp -gui /demos/TclDevKit/TclApp/BWidgets/demo_starkit.tpj
The BWidget package is shown at the top of the list. In addition, the
C:/Tcl/demos/BWidgets base directory is specified, with the
demo.tcl file explicitly added, and all files with the
extensions .tcl and .xbm added via wildcards.
On the Run tab, click Wrap. This will
generate a starkit. The name of the output file is specified in
the Output File field on the Wrapping tab,
in this case C:/Tcl/bwdemo.tcl.
To run the application, double-click the output file in Windows Explorer,
or enter bwdemo.tcl on the command line in the directory where
the output file was created. The application will use the tclsh
interpreter specified in the system's path.
Step Three: Creating an Application with an Interpreter (Starpack)
A "starpack" is a single executable file that contains both a starkit and an interpreter. In this step, we'll use TclApp to create a starpack that contains the files listed in the package definition we viewed in step one, additional supporting files, and a base kit that contains an interpreter.
Select Programs | ActiveState Tcl Dev Kit | Tcl Dev Kit Demos | Wrapping | BWidget Demo | Create Starpack from the Windows Start menu. Alternatively, you can run TclApp from the command line.
On the Windows command line enter:
tclapp.tcl -gui C:\Tcl\demos\TclDevKit\TclApp\BWidgets\demo_starpack.tpj
On the Unix command line enter:
tclapp -gui /demos/TclDevKit/TclApp/BWidgets/demo_starpack.tpj
The Files tab shows the same list of files and packages as in the project used to create the starkit. However, on the Wrapping tab, a Windows base kit is specified in the Prefix file field, and the Output file name indicates a Windows executable.
On the Run tab, click Wrap. This will
generate a starpack named bwdemo.exe. To run the application,
double-click the output file in Windows Explorer, or enter
bwdemo.exe on the command line in the directory where the output
file was created.
Step Four: Wrapping Extensions and External DLLs
While TclApp can wrap extensions that rely on external DLLs, be sure that the DLLs are included and initialized in the wrapped output. Otherwise, the application will rely on finding the DLLs in a location declared in the target system's PATH variable. At runtime, you should find the wrapped DLLs in the installation directory of the wrapped application.
Select Start | ActiveState Tcl Dev Kit | Tcl Dev Kit Demos | Wrapping | Advanced | TclDom -- Incorrect wrap from the Windows menu. Alternatively, run TclApp from the command line.
On the Windows command line enter:
tclapp -gui C:\Tcl\demos\TclDevKit\TclApp\Tcldom\snoop-dom.tpj
On the Unix command line enter:
tclapp -gui /demos/TclDevKit/TclApp/Tcldom/snoop-dom.tpj
On the Files tab, notice that the package
dom::libxml2 is included. This package is a C implementation of
TclDom, and relies on external DLLs, namely
libxml2.dll and iconv.dll. Click on the
Run tab, and click Wrap. Run the resulting
application (called snoop-dom.exe).
The application runs without error because the external
DLLs mentioned above are located in the Tcl/bin directory,
which is added to the system path during the installation.
On a system without the Tcl Dev Kit, the application
would generate an error (as can be demonstrated by renaming
or moving one of the required DLLs).
The proper method for wrapping this application involves wrapping the required DLLs. Select Start | ActiveState Tcl Dev Kit | Tcl Dev Kit Demos | Wrapping | Advanced | TclDom -- Correct complete wrap from the Windows Start menu. Alternatively, run TclApp from the command line.
On the Windows command line enter:
tclapp -gui C:\Tcl\demos\TclDevKit\TclApp\Tcldom\snoop-dom-complete.tpj
On the Unix command line enter:
tclapp -gui /demos/TclDevKit/TclApp/Tcldom/snoop-dom-complete.tpj
Notice that, on the Files tab, the required DLLs are specified for inclusion in the output file. Also, on the Advanced tab, the Initialization field contains code for copying the DLLs to a location where they can be found by the system's dynamic loader. (In this case, when the application is run, these DLLs will be copied to the same location as the output file.)
