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.