release/src/router/usbmodeswitch/jim/README

   1 The Jim Interpreter
   2
   3 A small-footprint implementation of the Tcl programming language.
   4
   5 --------------------------------------------------------------------------------
   6 WHAT IS JIM?
   7 --------------------------------------------------------------------------------
   8
   9 Jim is a small footprint implementation of the Tcl programming language
  10 written from scratch. Currently Jim Tcl is very feature complete with
  11 an extensive test suite (see the tests directory).
  12 There are some Tcl commands and features which are not implemented
  13 (and likely never will be), including namespaces, traces and Tk. However
  14 Jim Tcl offers a number of both Tcl8.5 and Tcl8.6 features ({*}, dict, lassign,
  15 tailcall and optional UTF-8 support) and some unique features.
  16 These unique features include [lambda] with garbage collection, a general GC/references
  17 system, arrays as syntax sugar for [dict]tionaries, object-based I/O and more.
  18
  19 Other common features of the Tcl programming language are present, like
  20 the "everything is a string" behaviour, implemented internally as
  21 dual ported objects to ensure that the execution time does not reflect
  22 the semantic of the language :)
  23
  24 --------------------------------------------------------------------------------
  25 WHEN JIM CAN BE USEFUL?
  26 --------------------------------------------------------------------------------
  27
  28 1) If you are writing an application, and want to make it scriptable, with
  29 Jim you have a way to do it that does not require to link your application
  30 with a big system. You can include the Jim source directly in your project
  31 and use the Jim API to write the glue code that makes your application
  32 scriptable in Jim, with the following advantages:
  33
  34 - Jim is not the next "little language", but it's a Tcl implementation.
  35   You can reuse your knowledge if you already Tcl skills, or enjoy
  36   the availability of documentation, books, web resources, ...
  37   (for example check my online Tcl book at http://www.invece.org/tclwise)
  38
  39 - Jim is simple, 14k lines of core code. If you want to adapt it you can hack
  40   the source code to meet the needs of your application. It makes you
  41   able to have scripting for default, and avoid external dependences.
  42
  43   Having scripting support *inside*, and in a way that a given version
  44   of your program always gets shipped a given version of Jim, you can
  45   write part of your application in Jim itself. Like it happens for
  46   Emacs/Elisp, or Gimp/Scheme, both this applications have the interpreter
  47   inside.
  48
  49 - Jim is Tcl, and Tcl looks like a configuration file if you want. So
  50   if you use Jim you have also a flexible syntax for your config file.
  51   This is a valid Tcl script:
  52
  53      set MyFeature on
  54      ifssl {
  55        set SslPort 45000
  56        use compression
  57      }
  58
  59   It looks like a configuration file, but if you implement the [ifssl]
  60   and [use] commands, it's a valid Tcl script.
  61
  62 - Tcl scales with the user. Not all know it, but Tcl is so powerful that
  63   you can reprogram the language in itself. Jim support this features
  64   of the Tcl programming language. You can write new control structures,
  65   use the flexible data types it offers (Lists are a central data structure,
  66   with Dictionaries that are also lists). Still Tcl is simpler for the
  67   casual programmer, especially if compared to other languages offering
  68   small footprint implementations (like Scheme and FORTH).
  69
  70 - Because of the Tcl semantic (pass by value, everything is a command
  71   since there are no reserved words), there is a nice API to glue
  72   your application with Jim. See under the Jim Tcl manual for more detail.
  73
  74 - Jim is supported. If you need commercial software, contact the original author
  75   at 'antirez@gmail.com' or the current maintainer at 'steveb@workware.net.au'.
  76
  77 2) The other "field" where Jim can be useful is obviously embedded systems.
  78
  79 3) We are working to make Jim as feature-complete as possible, thanks to
  80    dynamically loaded extensions it may stay as little as it is today
  81    but able to do interesting things for you. So it's not excluded that
  82    in the future Jim will be an option as general purpose language.
  83    But don't mind, for this there is already the mainstream Tcl
  84    implementation ;).
  85
  86 --------------------------------------------------------------------------------
  87 HOW BIG IS IT?
  88 --------------------------------------------------------------------------------
  89
  90 Jim with the default extensions configured and compiled with -Os is about 130k.
  91 Without any extensions, it is about 85k.
  92
  93 --------------------------------------------------------------------------------
  94 HOW FAST IS IT?
  95 --------------------------------------------------------------------------------
  96
  97 Jim is in most code faster than Tcl7.6p2 (latest 7.x version),
  98 and slower than Tcl 8.4.x. You can expect pretty decent performance
  99 for such a little interpreter.
 100
 101 If you want a more precise measure, there is 'bench.tcl' inside this
 102 distribution that will run both under Jim and Tcl, so just execute
 103 it with both the interpreters and see what you get :)
 104
 105 --------------------------------------------------------------------------------
 106 HOW TO COMPILE
 107 --------------------------------------------------------------------------------
 108
 109 Jim was tested under Linux, FreeBSD, MacosX, eCos, QNX, Windows XP (mingw, MVC).
 110
 111 To compile jim itself try:
 112
 113   ./configure
 114   make
 115
 116 --------------------------------------------------------------------------------
 117 EXTENSIONS
 118 --------------------------------------------------------------------------------
 119
 120 Many optional extensions are included. Some are C extensions and others are pure Tcl.
 121 Form more information, try:
 122
 123   ./configure --help
 124
 125 --------------------------------------------------------------------------------
 126 HOW TO EMBED JIM INTO APPLICATIONS
 127 --------------------------------------------------------------------------------
 128
 129 See the "examples.api" directory
 130
 131 --------------------------------------------------------------------------------
 132 HOW TO WRITE EXTENSIONS FOR JIM
 133 --------------------------------------------------------------------------------
 134
 135 See the extensions shipped with Jim, jim-readline.c, jim-clock.c, glob.tcl and oo.tcl
 136
 137 --------------------------------------------------------------------------------
 138 COPYRIGHT and LICENSE
 139 --------------------------------------------------------------------------------
 140
 141 Unless explicitly stated, all files within Jim repository are released
 142 under following license:
 143
 144 /* Jim - A small embeddable Tcl interpreter
 145  *
 146  * Copyright 2005 Salvatore Sanfilippo <antirez@invece.org>
 147  * Copyright 2005 Clemens Hintze <c.hintze@gmx.net>
 148  * Copyright 2005 patthoyts - Pat Thoyts <patthoyts@users.sf.net>
 149  * Copyright 2008 oharboe - Øyvind Harboe - oyvind.harboe@zylin.com
 150  * Copyright 2008 Andrew Lunn <andrew@lunn.ch>
 151  * Copyright 2008 Duane Ellis <openocd@duaneellis.com>
 152  * Copyright 2008 Uwe Klein <uklein@klein-messgeraete.de>
 153  * Copyright 2008 Steve Bennett <steveb@workware.net.au>
 154  * Copyright 2009 Nico Coesel <ncoesel@dealogic.nl>
 155  * Copyright 2009 Zachary T Welch zw@superlucidity.net
 156  * Copyright 2009 David Brownell
 157  *
 158  * Redistribution and use in source and binary forms, with or without
 159  * modification, are permitted provided that the following conditions
 160  * are met:
 161  *
 162  * 1. Redistributions of source code must retain the above copyright
 163  *    notice, this list of conditions and the following disclaimer.
 164  * 2. Redistributions in binary form must reproduce the above
 165  *    copyright notice, this list of conditions and the following
 166  *    disclaimer in the documentation and/or other materials
 167  *    provided with the distribution.
 168  *
 169  * THIS SOFTWARE IS PROVIDED BY THE JIM TCL PROJECT ``AS IS'' AND ANY
 170  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 171  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
 172  * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
 173  * JIM TCL PROJECT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
 174  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 175  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 176  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 177  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 178  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 179  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 180  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 181  *
 182  * The views and conclusions contained in the software and documentation
 183  * are those of the authors and should not be interpreted as representing
 184  * official policies, either expressed or implied, of the Jim Tcl Project.
 185  */
 186 --------------------------------------------------------------------------------
 187 HISTORY
 188 --------------------------------------------------------------------------------
 189
 190 "first Jim goal: to vent my need to hack on Tcl."
 191
 192 And actually this is exactly why I started Jim, in the first days
 193 of Jenuary 2005. After a month of hacking Jim was able to run
 194 simple scripts, now, after two months it started to be clear to
 195 me that it was not just the next toy to throw away but something
 196 that may evolve into a real interpreter. In the same time
 197 Pat Thoyts and Clemens Hintze started to contribute code, so that
 198 the development of new core commands was faster, and also more
 199 people hacking on the same code had as result fixes in the API,
 200 C macros, and so on.
 201
 202 Currently we are at the point that the core interpreter is almost finished
 203 and it is entering the Beta stage. There is to add some other core command,
 204 to do a code review to ensure quality of all the parts and to write
 205 documentation.
 206
 207 We already started to work on extensions like OOP, event loop,
 208 I/O, networking, regexp. Some extensions are already ready for
 209 prime time, like the Sqlite extension and the ANSI I/O.
 210
 211 ------------------------------------------------------------------------------
 212 Thanks to...
 213 ------------------------------------------------------------------------------
 214
 215 - First of all, thanks to every guy that are listed in the AUTHORS file,
 216   that directly helped with code and ideas. Also check the ChangeLog
 217   file for additional credits about patches or bug reports.
 218 - Elisa Manara that helped me to select this ill conceived name for
 219   an interpreter.
 220 - Many people on the Tclers Chat that helped me to explore issues
 221   about the use and the implementation of the Tcl programming language.
 222 - David Welton for the tech info sharing and our chats about
 223   programming languages design and the ability of software to "scale down".
 224 - Martin S. Weber for the great help with Solaris issues, debugging of
 225   problems with [load] on this arch, 64bit tests.
 226 - The authors of "valgrind", for this wonderful tool, that helped me a
 227   lot to fix bugs in minutes instead of hours.
 228
 229
 230 ----
 231 Enjoy!
 232 Salvatore Sanfilippo
 233 10 Mar 2005
 234
 235