user/tinytcl/README.txt

   1
   2 README file for procplace Tiny Tcl 6.8
   3
   4 $Id: README.txt,v 1.1 2001/04/29 20:58:32 karll Exp $
   5
   6 Tiny Tcl 6.8 is a rommable, minimal Tcl for embedded applications.
   7
   8 Derived from the venerable Tcl 6.7 release, Tiny Tcl 6.8 has a solid Tcl
   9 feature set, excluding newer capabilities of Tcl 7 and 8 such as the
  10 bytecode compiler, namespaces, sockets, and async event handling, among others.
  11
  12 Still, major applications have been written in Tcl 6.
  13
  14 Excluding C library functions, Tiny Tcl compiles down to less than 60 Kbytes
  15 on most machines, far smaller than any Tcl 7 or Tcl 8 derivatives.
  16
  17 This version of Tiny Tcl includes support for MS-DOS and DOS workalikes.
  18 The code for interfacing to DOS can be found in the files that have DOS
  19 in the filename, like tcldosaz.c, tcldosgl.c, tcldosut.c and dos.c.
  20
  21 COMPILER AND BUILD ENVIRONMENT
  22
  23 The compiler is assumed to be Borland C 5.0.  Earlier versions should work.
  24 More recent Borland and Microsoft compilers can no longer create DOS
  25 executables, and are thus pretty much Windows-only tools.
  26
  27 All filenames in the Tiny Tcl source tree are DOS "8.3" compliant.
  28
  29 The build environment is assumed to be DOS or Windows.  You can run tiny
  30 tcl in a DOS window under Windows while developing, if you like.
  31
  32 DOS INTERFACE FUNCTIONS
  33
  34 dos.c adds the following commands
  35
  36     bios_memsize
  37     bios_equiplist
  38     com
  39     kbhit
  40     getkey
  41     sound
  42     rawclock
  43     getdate
  44     setdate
  45     gettime
  46     settime
  47     diskfree
  48     getfat
  49     getdfree
  50     drive
  51     memfree
  52     stackfree
  53     wait
  54     gotoxy
  55     cls
  56     getverify
  57     heapcheck
  58     mkdir
  59     unlink
  60     execvp
  61     video
  62
  63 To remove these, remove the call to Tcl_InitDos from tinytcl.c and
  64 take dos.c out of the makefile and tlib.rsp file.
  65
  66
  67 BUILDING GENERIC ONLY
  68
  69 If you build with TCL_GENERIC_ONLY defined, you'll get a Tcl without
  70 any I/O commands -- open, close, gets, puts, etc.
  71
  72 This will generate the smallest possible executable.
  73
  74 TCLX FUNCTIONS
  75
  76 MEMORY DEBUGGING
  77
  78 Finding memory overwrites and related problems can be very tricky, even on
  79 a modern protected mode operating system such as Unix/Linux.  It can be
  80 particularly difficult in an embedded environment.  Compiling Tiny Tcl
  81 with TCL_MEM_DEBUG defined will greatly improve Tcl's chances of finding
  82 any memory overwrite problems that your C extensions might use, at some
  83 cost in performance.
  84
  85 Note also that memory debugging adds significant memory overhead as well.
  86 On a 640K target system application that was close to the memory limit, we
  87 found that turning off memory debugging freed about 120K of RAM... a major
  88 impact.
  89
  90 TRACING TCL EXECUTION
  91
  92 TclX's cmdtrace command is included.  You can trace execution by executing
  93 "cmdtrace on" and stop it with "cmdtrace off"
  94
  95 STACK SIZE
  96
  97 In typical embedded applications, there is no bounds protection to insure
  98 that the stack is not overflowed.  You can usually turn on overflow checking
  99 in your compiler.  That is not a complete solution because usually the overflow
 100 is determined after the fact.
 101
 102 The file borland.c defines the stack size for the Borland compiler.  It
 103 is set by default to 65,400 bytes, which is the highest we could set it to.
 104 This gives you the maximum Tcl execution depth... We find that each call of
 105 one Tcl routine from another typically adds about 1100 bytes on an Intel 8086
 106 target.  If you are extrememly memory limited and are not using most of the
 107 stack, you can lower the number defined in borland.c.
 108
 109 Note that the default amount of stack, 4K, is barely enough to get Tcl off the
 110 ground, with little or no application execution capability.
 111
 112 If you have mystery crashes, there's a good chance you've got the stack size
 113 set too small.
 114
 115 RUNTIME ENVIRONMENT
 116
 117 The startup code is in tinytcl.c.  It is a char array called initCmd.
 118
 119 By default this is defined as
 120
 121 char initCmd[] =
 122     "puts stdout \"\nEmbedded Tcl 6.8.0\n\"; source tcl_sys/autoinit.tcl";
 123
 124 You can replace it with whatever Tcl initialization you want to occur for
 125 your application.  Note that in the tcl_sys directory are files devel.tcl,
 126 containing a few handy procs to have around while compiling, and system.tcl,
 127 an undocumented file that contains procs to beep the speaker and make a list
 128 of currently defined procs and globals (snapshot) and then revert to the
 129 snapshot by unloading all procs and globals defined after snapshot was run.