README

Quick start
===========

This project contains the files required to build TclKit versions. You
must provide a version of tcl and optionally tk to be used but
everything else is provided.

1. Fetch your chosen release tarballs of tcl and tk from
   http://prdownloads.sourceforge.net/tcl/

2. Create a build directory to hold these sources and the build files
   for these versions. For instance, if you intend to build 8.6 and
   8.5 tclkits, use mkdir 8.5 8.6

3. Configure the build target using config.sh and provide the target
   build directory.

For instance:
    wget http://prdownloads.sourceforge.net/tcl/tcl8.5.8-src.tar.gz
    wget http://prdownloads.sourceforge.net/tcl/tk8.5.8-src.tar.gz
    mkdir 8.5
    tar -C 8.5 -xzvf tcl8.5.8-src.tar.gz
    tar -C 8.5 -xzvf tk8.5.8-src.tar.gz
    mv 8.5/tcl8.5.8 8.5/tcl
    mv 8.5/tk8.5.8 8.5/tk
    sh config.sh 8.5/linux-ix86 thread mk cli dyn
    cd 8.5/linux-ix86
    make

On Windows you can follow the above using msys-gcc or you can
construct the proper directory tree but instead of running config.sh
you can just create 8.5/win32-ix86 and create a Makefile containing
just:
   !include ../../Makefile.vc
   all: lite heavy
Then build using nmake. This has been tested with msvc6 (for 32 bit
compilation) and the 64 bit msvc8 that comes with the platform sdk for
server 2003.


Tcl/Tk builds
-------------

Kitgen can also be used to build Tcl/Tk binaries in various configurations.
There is a make target called "base" which builds just `tclsh` and `wish` and
installs them in the `build/{bin,include,lib}` directories. The Tcl/Tk headers
are included so that these areas can be used as basis for building extensions.

In the top-level makefile, `make base` rebuilds all areas matching `8.*/base-*`.
This can be used to rebuild all build variants you have set up in one step,
after a source change to Tcl and/or Tk.

If you've set up the `8.4/` and `8.5/` directories as described above, then a
`base-std` configuration will already have been set up, with symbols enabled.
So after the quick-start, you can do the following to build 8.4 and 8.5 versions
of `tclsh` and `wish` and clean up all intermediate files with one command:

    make base tidy

The `make tidy` command removes all intermediate build files, but is careful to
keep the `8.*/base-*/build/{bin,include,lib}` directories.


In detail
---------

The makefile in kitgen/ is only a convenience wrapper to make the above
possible. The real work is carried out by two other scripts:

  * `config.sh` is a script to set up specific build configurations
  * `setupvfs.tcl` is the script used internally to construct the final app

Kitgen is designed to proceed in several phases, so many variants can be built:

  1. place all necessary source code in directories named `8.4` or `8.5`
  2. configure one or more build directories using the config.sh script
  3. go to any of these build directories and type `make`
  4. remove intermediate build results with `make clean`
  5. copy and rename the final tclkit-* files to your ~/bin/ or some such
  6. remove the generated executables as well with `make distclean`
  7. forget about kitgen, until you need to update your builds

Note: after updating any of the sources, you can do a `make all` in the kitgen/
directory to rebuild all executables (assuming you did `make clean` before).


Directory structure
-------------------

The key trick is to get the directory structure right so that `sh config.sh` and
`make` will do the right thing. Both assume the following structure exists:

    kitgen/
        8.4/
            base-*/
            kit-*/
            tcl/
            tk/
        8.5/
            base-*/
            kit-*/
            tcl/
            tk/
        8.x/
            tclvfs/
            thread/
            vqtcl/
            zlib/
        config.sh
        files/
        ...

The 8.x/ directory contains the source code which works with both 8.4 and 8.5.

You do not have to have both 8.4/ and 8.5/, nor do you have to give them exactly
these names, but they must start with "8". There can be multiple sets of code
sources co-existing next to each other even, if needed. Symlinks should work.


config.sh
---------

The config.sh script creates a Makefile with settings that specify exactly what
type of executable(s) are to be generated. All these makefiles end up in sub-
directories of 8.4/, 8.5/, or whatever other 8-prefixed name you work with.

The `make small` example given in the quick start uses default settings:

    sh config.sh 8.4/kit-small cli dyn

The result is a makefile called "8.4/kit-small/Makefile". To build that setup,
just do `cd 8.4/kit-small && make` . Since cli & dyn were specified, only those
two executables will be built, but you can do an explicit `make tclkit-gui` .

The `make large` example in the quick start uses these more elaborate settings:

    sh config.sh 8.5/kit-large aqua univ thread allenc allmsgs tzdata
    
Again, `cd 8.5/kit-large && make` is all it takes to build that configuation.

The first argument of config.sh is the build name. It must be a two-part name,
and the first part must be one of your existing "8*/" directory areas. The
second part could be any name, but the suggested name is "kit-something".

The remaining arguments of config.sh specify one or more build options:

  * `allenc` - include all encodings, not just the usual set of 7
  * `allmsgs` - include all localized message catalogs _(8.5 only)_
  * `aqua` - build Tk for Aqua i.s.o. X11 _(Mac OS X only)_
  * `b64` - generate 64-bit binaries
  * `cli` - build the "tclkit-cli" command-line version
  * `dyn` - build the "tclkit-dyn" version which loads Tk dynamically
  * `gcov` - enable code coverage _(implies `sym`)_
  * `gprof` - enable profiling _(implies `sym`)_
  * `gui` - build the "tclkit-gui" version which has Tk linked-in statically
  * `ppc` - build for PowerPC _(Mac OS X only)_
  * `sym` - enable & keep debugger symbols in the executable
  * `thread` - build with threading and include the Thread extension
  * `tzdata` - include the complete set of timezone data files _(8.5 only)_
  * `univ` - build for both PowerPC and Intel _(Mac OS X only)_
  * `x86` - build for Intel _(Mac OS X only)_
  * `mk` - build executables using Metakit instead of vlerq
  
When not specified, the default is to build all `cli`, `dyn`, `gui` variants.
If you ask for Metakit executables then these are in addition to the vlerq
binaries. That is you will get both tclkit-cli and tclkitsh.


Makefile
--------

All makefiles created by config.sh or manually need to reside in subdirectories
of some 8*/ source directory. That location determines which source code will
be used, since all builds are done relative to their parent dirs.

To generate a Makefile with config and then do a build, proceed as follows:

    sh config.sh 8.4/kit-mybuild <config options ...>
    cd 8.4/kit-mybuild
    make

Often, that's all you'll need.  However, to debug or tweak things, read on...

The common parts of these makefiles is read in during use, through the

    include ../../makefile.include
    
line at the end of each makefile.  It defines the following main targets:

  * `all` - builds all targets given to config.sh (default is cli + dyn + gui)
  * `tclkit-cli` - builds just that executable (same for -dyn and -gui)
  * `clean` - removes all intermediate build results
  * `distclean` - removes the tclkit-* executables as well

Note that these same build targets also exist in the top-level makefile in
kitgen/ - when used there, the corresponding target in *all* subdirectory
makefiles will be invoked. To prevent a specific makefile from being run that
way, give it some other name than "Makefile".

The individual make's are configured mostly by setting make variables:

  * `GUI_OPTS` - options needed to build with Tk
  * `KIT_OPTS` - flags used by the setupvfs.tcl script
  * `PLAT` - either "unix" or "win" to select the proper source directory
  * `PRIV` - normally "install-private-headers", but omitted on Windows
  * `TCL_OPTS` - flags for configuring the build of Tcl
  * `TK_OPTS` - flags for configuring the build of Tk
  * `TKDYN_OPTS` - flags for configuring the build of Tk as shared lib
  * `THREADDYN_OPTS` - flags for configuring the build of Thread as shared lib
  * `VFS_OPTS` - flags for configuring the build of the TclVFS extension
  * `VLERQ_OPTS` - flags for configuring the build of the Vlerq extension

Other variables such as CFLAGS and LDFLAGS also affect the build settings.

Doing `make` will build the executables.  This only does a full build when there
are no build/* directories present.  One way to force this is `make clean` 
which does a `rm -rf build` .  Otherwise, for directories which already exist,
the rebuild is skipped.  To force a rebuild of only the vlerq extension, do:

    rm -rf build/vqtcl && make
    
The sub-directories of build/ are the areas where each call to the respective
"configure" script places its results.  When debugging either a build or the
extension itself, it may be more convenient to work in that specific subdir:

    cd builds/vqtcl && make
    
After that, you can do `cd ../.. && make` to complete the tclkit builds.


setupvfs.tcl
------------

This is an internal script used as last step by the makefiles to construct the
virtual file system (VFS) containing runtime scripts at the end of every tclkit.
See the makefile.include file for exact details.

The setupvfs.tcl script is special in that it can only be used by a "raw" kit,
i.o.w. a tclkit executable which does not yet have the VFS part appended to it.
It is essentially a way for tclkit to bootstrap itself into becoming usable.

The reason things are done this way is that it avoids the need to have a working
tclkit around to construct a new one, which'd be a chicken-and-egg situation.
So this approach makes it possible to build a tclkit totally from scratch
without requiring any binary data files (as "genkit" did).

Some variations in generating the VFS data are configured via the command line:

  * `-d` - output some debugging info from this setup script
  * `-e` - include all encodings i.s.o. 7 basic ones (encodings/)
  * `-m` - include all localized message files (tcl 8.5, msgs/)
  * `-t` - include the thread extension as shared lib in vfs
  * `-z` - include timezone data files (tcl 8.5, tzdata/)

As with the makefiles, most of these details are dealt with automatically if you
use the config.sh script to create your configurations.


License & support
-----------------

The Tclkit-specific sources are license free, they just have a copyright. Hold
the author(s) harmless and any lawful use is permitted.

This does *not* apply to any of the sources of the other major Open Source
Software used in Tclkit, which each have very liberal BSD/MIT-like licenses:

  * Tcl/Tk, TclVFS, Thread, Vlerq, Zlib

If kitgen does not work right on your platform, please post to the [Starkit][5] mailing list. Or you can use the feedback forum at [FFF][6] to report bugs.

  [5]: http://www.equi4.com/mailman/listinfo/starkit
  [6]: http://www.equi4.com/fff/Home


Acknowledgements
----------------

With thanks to John Ousterhout for creating Tcl/Tk, Matt Newman and Vince Darley
for developing the virtual file system, and the members of the Tcl Core Team for
diligently maintaining and taking forward the Tcl/Tk code base plus extensions.

A special thanks to Daniel Steffen for making Tcl/Tk work so well on Mac OS X.

Thanks also to Eolas Technologies Inc for sponsoring the Vlerq project on which
Tclkit Lite is based. There'd not be a Tclkit Lite, nor kitgen, without them.

Contributors & testers:

  * Brian Theado (mingw/win32)
  * Pat Thoyts (more mingw/win32 fixes)

Lastly, many thanks to all those who have contributed to the evolution of Tclkit
over the years, with suggestions, bug reports, encouragement, and enthusiasm.