source: trunk/kitgen/README@ 201

Last change on this file since 201 was 175, checked in by demin, 12 years ago

initial commit

File size: 13.3 KB
Line 
1Kitgen
2======
3
4[Kitgen][1] consists of a makefile, scripts, and C source code to generate
5variations of [Tclkit Lite][2], a version of [Tclkit][3] based on [Vlerq][4].
6
7 [1]: http://www.equi4.com/kitgen.html
8 [2]: http://www.equi4.com/tclkitlite.html
9 [3]: http://www.equi4.com/tclkit.html
10 [4]: http://www.vlerq.org/
11
12Kitgen is pronounced "kit-chen".
13
14
15News
16----
17
18 * 2007-05-03 : changes in cvs & build structure
19 * 2007-04-04 : added kbs.tcl, the Kitgen Build System - see README.kbs
20 * 2007-01-11 : fixed a vfs thread issue in boot.tcl, by Jeff Hobbs
21 * 2006-12-20 : fixed typo, mention the FFF feedback forum below
22 * 2006-12-15 : added *BSD support (use gmake i.s.o. make)
23 * 2006-12-12 : doc tweaks, added "cvs" target, support vlerq safe interps
24 * 2006-12-06 : updated to vlerq 4.1 and vfs::m2m 1.8
25 * 2006-12-05 : added "base" & "tidy" targets for Tcl/Tk-only builds
26 * 2006-12-04 : added "gcov" and "gprof" options, keep symbols with "sym" opt
27 * 2006-12-01 : added "b64" option to enable 64-bit compiles
28 * 2006-11-21 : simpler makefile, tweaked to work with Mingw on Win32
29 * 2006-11-19 : first release, tested on Mac OS X and Linux x86 only so far
30
31----
32
33**UPDATE, MAY 2007:** _The build notes below are no longer working. The CVS repository at equi4.com has been closed and will be replaced by an SVN mirror, hopefully by the end of May 2007. For now, you can get copies of all the important pieces at [www.equi4.com](http://www.equi4.com/pub/tk/tars/) - the latest source for the "Vlerq" extension is in "vqtcl.tgz" and the latest kitgen source is in "kitgen.tgz". See also the new [mailing list](http://groups.google.com/group/starkit) for more details._
34
35----
36
37Overview
38--------
39
40To build Tclkit Lite, you need to bring several pieces together:
41
42 * sources for Tcl and Tk
43 * sources for the Thread, TclVFS, and Vlerq extensions
44 * sources for Zlib
45 * the files in this Kitgen package
46
47There are several ways to go about this, depending on whether you want to use
48the latest sources in cvs, or tarfile releases, or your own custom versions.
49
50
51Quick start
52-----------
53
54These instructions are for a Unix-type system and do a build using CVS sources:
55
56 cvs -d :pserver:anonymous@equi4.com:/home/cvs co kitgen
57 cd kitgen
58 make tars
59 make small
60
61That's it. This produces two executables in `8.4/kit-small/`:
62
63 * `tclkit-cli` - a tclsh-like console app
64 * `tclkit-dyn` - wish-like, after a `package require Tk`
65
66Or, to build a threaded Tcl/Tk 8.5 build with all encodings and more included:
67
68 cvs -d :pserver:anonymous@equi4.com:/home/cvs co kitgen
69 cd kitgen
70 make tars
71 make large
72
73In this case a third executable is also produced:
74
75 * `tclkit-gui` - same as "tclkit-dyn", but with Tk linked-in statically
76
77On **Mac OS X**, "make large" builds a universal binary for PowerPC and Intel.
78
79On **Windows** you can use this approach if you download `msys_mingw 0.8` from
80<http://tcl.sourceforge.net/> (make sure you extract to a path without spaces).
81Then launch `msys.bat` to get a bash shell and proceed further as above.
82The binaries will end up as "tclkit-{cli,dyn,gui}.exe" in this case.
83
84You can use `make cvs` to update all cvs areas under `8.4/` and `8.5/`.
85
86
87Tcl/Tk builds
88-------------
89
90Kitgen can also be used to build Tcl/Tk binaries in various configurations.
91There is a make target called "base" which builds just `tclsh` and `wish` and
92installs them in the `build/{bin,include,lib}` directories. The Tcl/Tk headers
93are included so that these areas can be used as basis for building extensions.
94
95In the top-level makefile, `make base` rebuilds all areas matching `8.*/base-*`.
96This can be used to rebuild all build variants you have set up in one step,
97after a source change to Tcl and/or Tk.
98
99If you've set up the `8.4/` and `8.5/` directories as described above, then a
100`base-std` configuration will already have been set up, with symbols enabled.
101So after the quick-start, you can do the following to build 8.4 and 8.5 versions
102of `tclsh` and `wish` and clean up all intermediate files with one command:
103
104 make base tidy
105
106The `make tidy` command removes all intermediate build files, but is careful to
107keep the `8.*/base-*/build/{bin,include,lib}` directories.
108
109
110In detail
111---------
112
113The makefile in kitgen/ is only a convenience wrapper to make the above
114possible. The real work is carried out by two other scripts:
115
116 * `config.sh` is a script to set up specific build configurations
117 * `setupvfs.tcl` is the script used internally to construct the final app
118
119Kitgen is designed to proceed in several phases, so many variants can be built:
120
121 1. place all necessary source code in directories named `8.4` or `8.5`
122 2. configure one or more build directories using the config.sh script
123 3. go to any of these build directories and type `make`
124 4. remove intermediate build results with `make clean`
125 5. copy and rename the final tclkit-* files to your ~/bin/ or some such
126 6. remove the generated executables as well with `make distclean`
127 7. forget about kitgen, until you need to update your builds
128
129Note: after updating any of the sources, you can do a `make all` in the kitgen/
130directory to rebuild all executables (assuming you did `make clean` before).
131
132
133Directory structure
134-------------------
135
136The key trick is to get the directory structure right so that `sh config.sh` and
137`make` will do the right thing. Both assume the following structure exists:
138
139 kitgen/
140 8.4/
141 base-*/
142 kit-*/
143 tcl/
144 tk/
145 8.5/
146 base-*/
147 kit-*/
148 tcl/
149 tk/
150 8.x/
151 tclvfs/
152 thread/
153 vqtcl/
154 zlib/
155 config.sh
156 files/
157 ...
158
159The 8.x/ directory contains the source code which works with both 8.4 and 8.5.
160
161You do not have to have both 8.4/ and 8.5/, nor do you have to give them exactly
162these names, but they must start with "8". There can be multiple sets of code
163sources co-existing next to each other even, if needed. Symlinks should work.
164
165
166config.sh
167---------
168
169The config.sh script creates a Makefile with settings that specify exactly what
170type of executable(s) are to be generated. All these makefiles end up in sub-
171directories of 8.4/, 8.5/, or whatever other 8-prefixed name you work with.
172
173The `make small` example given in the quick start uses default settings:
174
175 sh config.sh 8.4/kit-small cli dyn
176
177The result is a makefile called "8.4/kit-small/Makefile". To build that setup,
178just do `cd 8.4/kit-small && make` . Since cli & dyn were specified, only those
179two executables will be built, but you can do an explicit `make tclkit-gui` .
180
181The `make large` example in the quick start uses these more elaborate settings:
182
183 sh config.sh 8.5/kit-large aqua univ thread allenc allmsgs tzdata
184
185Again, `cd 8.5/kit-large && make` is all it takes to build that configuation.
186
187The first argument of config.sh is the build name. It must be a two-part name,
188and the first part must be one of your existing "8*/" directory areas. The
189second part could be any name, but the suggested name is "kit-something".
190
191The remaining arguments of config.sh specify one or more build options:
192
193 * `allenc` - include all encodings, not just the usual set of 7
194 * `allmsgs` - include all localized message catalogs _(8.5 only)_
195 * `aqua` - build Tk for Aqua i.s.o. X11 _(Mac OS X only)_
196 * `b64` - generate 64-bit binaries
197 * `cli` - build the "tclkit-cli" command-line version
198 * `dyn` - build the "tclkit-dyn" version which loads Tk dynamically
199 * `gcov` - enable code coverage _(implies `sym`)_
200 * `gprof` - enable profiling _(implies `sym`)_
201 * `gui` - build the "tclkit-gui" version which has Tk linked-in statically
202 * `ppc` - build for PowerPC _(Mac OS X only)_
203 * `sym` - enable & keep debugger symbols in the executable
204 * `thread` - build with threading and include the Thread extension
205 * `tzdata` - include the complete set of timezone data files _(8.5 only)_
206 * `univ` - build for both PowerPC and Intel _(Mac OS X only)_
207 * `x86` - build for Intel _(Mac OS X only)_
208
209When not specified, the default is to build all `cli`, `dyn`, `gui` variants.
210
211
212Makefile
213--------
214
215All makefiles created by config.sh or manually need to reside in subdirectories
216of some 8*/ source directory. That location determines which source code will
217be used, since all builds are done relative to their parent dirs.
218
219To generate a Makefile with config and then do a build, proceed as follows:
220
221 sh config.sh 8.4/kit-mybuild <config options ...>
222 cd 8.4/kit-mybuild
223 make
224
225Often, that's all you'll need. However, to debug or tweak things, read on...
226
227The common parts of these makefiles is read in during use, through the
228
229 include ../../makefile.include
230
231line at the end of each makefile. It defines the following main targets:
232
233 * `all` - builds all targets given to config.sh (default is cli + dyn + gui)
234 * `tclkit-cli` - builds just that executable (same for -dyn and -gui)
235 * `clean` - removes all intermediate build results
236 * `distclean` - removes the tclkit-* executables as well
237
238Note that these same build targets also exist in the top-level makefile in
239kitgen/ - when used there, the corresponding target in *all* subdirectory
240makefiles will be invoked. To prevent a specific makefile from being run that
241way, give it some other name than "Makefile".
242
243The individual make's are configured mostly by setting make variables:
244
245 * `GUI_OPTS` - options needed to build with Tk
246 * `KIT_OPTS` - flags used by the setupvfs.tcl script
247 * `PLAT` - either "unix" or "win" to select the proper source directory
248 * `PRIV` - normally "install-private-headers", but omitted on Windows
249 * `TCL_OPTS` - flags for configuring the build of Tcl
250 * `TK_OPTS` - flags for configuring the build of Tk
251 * `TKDYN_OPTS` - flags for configuring the build of Tk as shared lib
252 * `THREADDYN_OPTS` - flags for configuring the build of Thread as shared lib
253 * `VFS_OPTS` - flags for configuring the build of the TclVFS extension
254 * `VLERQ_OPTS` - flags for configuring the build of the Vlerq extension
255
256Other variables such as CFLAGS and LDFLAGS also affect the build settings.
257
258Doing `make` will build the executables. This only does a full build when there
259are no build/* directories present. One way to force this is `make clean`
260which does a `rm -rf build` . Otherwise, for directories which already exist,
261the rebuild is skipped. To force a rebuild of only the vlerq extension, do:
262
263 rm -rf build/vqtcl && make
264
265The sub-directories of build/ are the areas where each call to the respective
266"configure" script places its results. When debugging either a build or the
267extension itself, it may be more convenient to work in that specific subdir:
268
269 cd builds/vqtcl && make
270
271After that, you can do `cd ../.. && make` to complete the tclkit builds.
272
273
274setupvfs.tcl
275------------
276
277This is an internal script used as last step by the makefiles to construct the
278virtual file system (VFS) containing runtime scripts at the end of every tclkit.
279See the makefile.include file for exact details.
280
281The setupvfs.tcl script is special in that it can only be used by a "raw" kit,
282i.o.w. a tclkit executable which does not yet have the VFS part appended to it.
283It is essentially a way for tclkit to bootstrap itself into becoming usable.
284
285The reason things are done this way is that it avoids the need to have a working
286tclkit around to construct a new one, which'd be a chicken-and-egg situation.
287So this approach makes it possible to build a tclkit totally from scratch
288without requiring any binary data files (as "genkit" did).
289
290Some variations in generating the VFS data are configured via the command line:
291
292 * `-d` - output some debugging info from this setup script
293 * `-e` - include all encodings i.s.o. 7 basic ones (encodings/)
294 * `-m` - include all localized message files (tcl 8.5, msgs/)
295 * `-t` - include the thread extension as shared lib in vfs
296 * `-z` - include timezone data files (tcl 8.5, tzdata/)
297
298As with the makefiles, most of these details are dealt with automatically if you
299use the config.sh script to create your configurations.
300
301
302License & support
303-----------------
304
305The Tclkit-specific sources are license free, they just have a copyright. Hold
306the author(s) harmless and any lawful use is permitted.
307
308This does *not* apply to any of the sources of the other major Open Source
309Software used in Tclkit, which each have very liberal BSD/MIT-like licenses:
310
311 * Tcl/Tk, TclVFS, Thread, Vlerq, Zlib
312
313If 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.
314
315 [5]: http://www.equi4.com/mailman/listinfo/starkit
316 [6]: http://www.equi4.com/fff/Home
317
318
319Acknowledgements
320----------------
321
322With thanks to John Ousterhout for creating Tcl/Tk, Matt Newman and Vince Darley
323for developing the virtual file system, and the members of the Tcl Core Team for
324diligently maintaining and taking forward the Tcl/Tk code base plus extensions.
325
326A special thanks to Daniel Steffen for making Tcl/Tk work so well on Mac OS X.
327
328Thanks also to Eolas Technologies Inc for sponsoring the Vlerq project on which
329Tclkit Lite is based. There'd not be a Tclkit Lite, nor kitgen, without them.
330
331Contributors & testers:
332
333 * Brian Theado (mingw/win32)
334 * Pat Thoyts (more mingw/win32 fixes)
335
336Lastly, many thanks to all those who have contributed to the evolution of Tclkit
337over the years, with suggestions, bug reports, encouragement, and enthusiasm.
Note: See TracBrowser for help on using the repository browser.