search

patthoyts / kitgen

Tclkit build system
http://tclkit.googlecode.com/
31 stars 19 forks source link

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:

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:

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:

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:

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:

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:

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

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:

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