README:  TclPro Sample Applications

Copyright (c) 1998-2000 by Ajuba Solutions
All rights reserved
-------------------

This directory contains a sample Makefiles that demonstrate how to
build Tcl, Tk, [incr Tcl], [incr Tk], Expect (on UNIX only), and Tclx
shells using the libraries provided in the TclPro installation.  

Note: The Windows distribution will only include the Windows specific
files and the UNIX distributions will only include the UNIX specific
files.  To use this demo, you must have both TclPro and the C
development libraries installed for your platform.

The files in this directory are:

sampleApp.mak -     Visual C++ compatible Makefile for building the
                    sample application.
Makefile.in -       UNIX template Makefile used by "configure".
configure -         UNIX configure script, generated by "autoconf".
configure.in -      UNIX configure template used by "autoconf".
startup.tcl -       Startup script for the sample wrapped application.
factorial.tcl -     The factorial package used by the sample wrapped
                    application.

Additionally, the makefile use the following TclPro template source
files:

From lib/tcl8.3:
proTclWinMain.c -   Sample main file for Windows.
proTclUnixMain.c -  Sample main file for UNIX.
proWrapTclMain.c -  Sample implementation of Pro_WrapTclMain.

From lib/tk8.3:
proTkWinMain.c -    Sample main file for Windows.
proTkUnixMain.c -   Sample main file for UNIX.
proWrapTkMain.c -   Sample implementation of Pro_WrapTkMain.

The sample makefiles given here support building on both UNIX
and Windows (Windows NT and Windows 95).  For both classes
of platforms, the libraries in TclPro support two sets of builds:

1) Statically linked Tcl, Tk, [incr Tcl], [incr Tk], Expect (on UNIX
   only), and TclX; these executables include the respective binary
   code for Tcl, Tk, [incr Tcl], [incr Tk], Expect (on UNIX only), and Tclx
   as well as the TclPro wrapper extensions and the TclPro byte code loader
   package.

2) Dynamically linked Tcl and Tk; these two executables include the
   respective binary code for Tcl and Tk; the wrapper extensions are
   staically linked to the base exectuable; the byte code loader,
   [incr Tcl], [incr Tk], Expect (on UNIX only), and TclX are each
   provided in the form of dynamic link libraries (DLLs or shared
   objects), 

Additionally, the makefiles contain targets that build the following
compiled and wrapped Tcl/Tk applications:

fac-static      (from the factorial target) is a wrapped application,
                based on the static tclsh built by this makefile, that
                calculates and prints the factorial of a number.
fac-dynamic     (from the factorial target) is a wrapped application,
                based on the dynamic tclsh wrapper input provided with
                the TclPro distribution, that calculates and prints
                the factorial of a number.

These two targets show how to build your own application from scratch
(fac-static), or from the TclPro .in files (fac-dynamic).

See below for details on building the sample applications.

When building your application, you will need to select either static
or dynamic based on the runtime needs of your final application.
Build statically if you are not concerned about the size of your final
applicaion or do not expect your end-user to have TclPro installed;
build dynamically if you are concerned about the size of your final
application or may expect that your end-user will have TclPro
installed.

Additionally on Windows, the above list of binaries can also be built
for debugging.  You will need to use the debug libraries provided in
TclPro if you want to be able to debug your code as well as the Visual
C++ C Runtime library.

For more information see Chapter 7 of the TclPro User's Guide.

--------------------------------
Building the sample applications
--------------------------------

By default, the makefiles build all the sample applications; you may
use the following targets to build selected applications:

tclsh-static            statically linked, Tcl only
tclsh-dynamic           dynamically linked, Tcl only
wish-static             statically linked, Tcl and Tk
wish-dynamic            dynamically linked, Tcl and Tk
bigtclsh-static         statically linked, Tcl, [incr Tcl], TclX, and Expect
bigwish-static          statically linked, Tcl, [incr Tcl], Tk, [incr Tk],
			    TclX, TkX, and Expect

UNIX Builds
-----------

UNIX builds use the autoconf-generated configure script to create a
Makefile from the template Makefile.in.  The individual targets
generate executables with the same names as the targets (for example,
tclsh-static creates an executable called tclsh-static).
You may need to modify the Makefile.in to reflect your local development
environment.

To create the applications, follow these steps:

- Run the configure script:
        ./configure --enable-gcc
  You may specify the "--enable-symbols" switches to build with
  debugging turned on. The "--x-libraries" and "--x-includes" can be
  used to point to your X libraries and include files, if configure
  can't find them.  To use a native C compiler, omit the "--enable-gcc"
  flag.

- Run the makefile. The default target creates all the samples, or you
  can specify any of the targets listed above.

Windows Builds
--------------

Windows builds use a VC++ compatible makefile, sampleApp.mak. The
default target creates all the samples, or you can specify any of the
targets listed above. The makefile creates two directories, one for
statically linked executables, and one for dynamically linked
ones. The directory names vary depending on whether or not the
executable were created with debugging information (specify NODEBUG=0
on the nmake command line to generate debugging info).

The generated executable names are:

tclsh-static            Static-Release/sampleAppTclshs.exe
tclsh-dynamic           Dynamic-Release/sampleAppTclsh.exe
wish-static             Static-Release/sampleAppWishs.exe
wish-dynamic            Dynamic-Release/sampleAppWish.exe
bigtclsh-static         Static-Release/sampleAppBigTclhs.exe
bigwish-static          Static-Release/sampleAppBigWishs.exe

for NODEBUG=0 or not specified, and

tclsh-static            Static-Debug/sampleAppTclshsd.exe
tclsh-dynamic           Dynamic-Debug/sampleAppTclshd.exe
wish-static             Static-Debug/sampleAppWishsd.exe
wish-dynamic            Dynamic-Debug/sampleAppWishd.exe
bigtclsh-static         Static-Debug/sampleAppBigTclhsd.exe
bigwish-static          Static-Debug/sampleAppBigWishsd.exe

To generate the first set of executable, type

        nmake -f sampleApp.mak

and the second set

        nmake -f sampleApp.mak NODEBUG=0
