interpreters/git/README.txt

   1 Git is an interpreter for the Glulx virtual machine. Its homepage is here:
   2
   3 http://ifarchive.org/indexes/if-archiveXprogrammingXglulxXinterpretersXgit.html
   4
   5 Git's main goal in life is to be fast. It's about five times faster than Glulxe,
   6 and about twice as fast as Frotz (using the same Inform source compiled for the
   7 Z-machine). It also tries to be reasonably careful with memory: it's possible to
   8 trade speed off against memory by changing the sizes of Git's internal buffers.
   9
  10 I wrote Git because I want people to be able to write huge games or try out
  11 complicated algorithms without worrying about how fast their games are going to
  12 run. I want to play City of Secrets on a Palm without having to wait ten seconds
  13 between each prompt.
  14
  15 Have fun, and let me know what you think!
  16
  17   Iain Merrick (Original author)
  18   iain@diden.net
  19
  20   David Kinder (Current maintainer)
  21   davidk.kinder@virgin.net
  22
  23 --------------------------------------------------------------------------------
  24
  25 * Building and installing Git
  26
  27 This is just source code, not a usable application. You'll have to do a bit of
  28 work before you can start playing games with it. If you're not confident about
  29 compiling stuff yourself, you probably want to wait until somebody uploads a
  30 compiled version of Git for your own platform.
  31
  32 Git needs to be linked with a Glk library in order to run. This can be easy or
  33 hard, depending on what kind of computer you're using and whether you want Git
  34 to be able to display graphics and play sounds. To find a suitable Glk library,
  35 look here:
  36
  37 http://eblong.com/zarf/glk/
  38 http://ifarchive.org/indexes/if-archiveXprogrammingXglkXimplementations.html
  39
  40 Exactly how you build and link everything depends on what platform you're on and
  41 which Glk library you're using. The supplied Makefile should work on any Unix
  42 machine (including Macs with OS X), but you'll probably want to tweak it to
  43 account for your particular setup. If you're not using Unix, I'm afraid you'll
  44 have to play it by ear. If the Glk library you chose comes with instructions,
  45 that's probably a good place to start.
  46
  47 On Unix, git_unix.c contains the startup code required by the Glk library.
  48 git_mac.c and git_windows.c contain startup code for MacGlk and WinGlk
  49 respectively, but I can't guarantee that they're fully up-to-date.
  50
  51 It should be possible to build Git with any C compiler, but it works best with
  52 GCC, because that has a non-standard extension that Git can use for a big speed
  53 boost. GCC 2.95 actually generates faster code than later versions, so if you
  54 have a choice, use the former. (On OS X, this means compiling with 'gcc2'.)
  55
  56 --------------------------------------------------------------------------------
  57
  58 * Configuring Git
  59
  60 There are several configuration options you can use when compiling Git. Have a
  61 look at config.h and see which ones look applicable to your platform. The
  62 Makefile includes settings to configure Git for maximum speed on Mac OS X; the
  63 best settings for other Unix platforms should be similar.
  64
  65 The most important setting is USE_DIRECT_THREADING, which makes the interpreter
  66 engine use GCC's labels-as-values extension, but this only works with GCC 2.95.
  67
  68 --------------------------------------------------------------------------------
  69
  70 * Porting to a new platform
  71
  72 To do a new port, you first need to find a suitable Glk library, or write a new
  73 one. Then you need to write the startup code. Start with a copy of git_unix.c,
  74 git_mac.c or git_windows.c and modify it appropriately.
  75
  76 The startup code needs to implement the following functions:
  77
  78   void glk_main()                 // Standard Glk entrypoint
  79   void fatalError(const char* s)  // Display error message and quit
  80
  81 In glk_main(), you need to locate the game file somehow. Then you have two
  82 options. You can open the game as a Glk stream and pass it to this function:
  83
  84   extern void gitWithStream (strid_t stream,
  85                              git_uint32 cacheSize,
  86                              git_uint32 undoSize);
  87
  88 Or you can load the game yourself, and just pass Git a pointer to your buffer:
  89
  90   extern void git (const git_uint8 * game,
  91                    git_uint32 gameSize,
  92                    git_uint32 cacheSize,
  93                    git_uint32 undoSize);
  94
  95 If the operating system provides some way of memory-mapping files (such as
  96 Unix's mmap() system call), you should do that and call git(), because it will
  97 allow the game to start up much more quickly. If you can't do memory-mapping,
  98 you should just open the game as a file stream and call gitWithStream(). Note
  99 that some Glk libraries, such as xglk, aren't compatible with memory-mapped
 100 files.
 101
 102 "cacheSize" and "undoSize" tell Git what size to use for its two main internal
 103 buffers. Both sizes are in bytes. You may want to make these values
 104 user-configurable, or you may just want to pick values that make sense for your
 105 platform and use those. (My Unix version currently uses fixed values, but I'm
 106 going to add some optional command-line parameters to override these defaults.)
 107
 108 "cacheSize" is the size of the buffer used to store Glulx code that Git has
 109 recompiled into its internal format. Git will run faster with a larger buffer,
 110 but using a huge buffer is just a waste of memory; 256KB is plenty.
 111
 112 "undoSize" is the maximum amount of memory used to remember previous moves. The
 113 larger you make it, the more levels of undo will be available. The amount of
 114 memory required to remember one undo position varies from a few KB up to tens of
 115 KB. 256KB is usually enough to store dozens of moves.
 116
 117 --------------------------------------------------------------------------------
 118
 119 * Known problems
 120
 121 GCC 3 has bigger problems than I thought. On PowerPC, the direct threading
 122 option results in much slower code; and on x86, terp.c crashes GCC itself if
 123 direct threading is used. GCC 4 seems to work, given some very limited testing,
 124 but still results in slow code. Therefore, I recommend that you use GCC 2.95 if
 125 possible. If you only have GCC 3, don't define USE_DIRECT_THREADING.
 126
 127 Some Glk libraries, such as xglk, can't deal with memory-mapped files. You can
 128 tell that this is happening if Git can open .ulx files, but complains that .blb
 129 files are invalid. The solution is to use gitWithStream() rather than git() in
 130 your startup file, and make sure you're giving it a file stream rather than a
 131 memory stream. If you're using the git_unix.c startup file, just make sure
 132 USE_MMAP isn't defined.
 133
 134 1-byte and 2-byte local variables are not implemented. This means git can't
 135 play games created with old versions of the Superglus system. As these small
 136 local variables now deprecated, it is unlikely that this will be fixed.
 137
 138 In the search opcodes, direct keys don't work unless they're exactly 4 bytes
 139 long.
 140
 141 --------------------------------------------------------------------------------
 142
 143 * Copyright information
 144
 145 Note: previous versions of Git used an informal freeware license, but I've
 146 decided it's worth formalising. As of version 1.2.3, I've switched to the
 147 MIT license.
 148
 149 Copyright (c) 2003 Iain Merrick
 150
 151 Permission is hereby granted, free of charge, to any person obtaining a copy of
 152 this software and associated documentation files (the "Software"), to deal in
 153 the Software without restriction, including without limitation the rights to
 154 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 155 the Software, and to permit persons to whom the Software is furnished to do so,
 156 subject to the following conditions:
 157
 158 The above copyright notice and this permission notice shall be included in all
 159 copies or substantial portions of the Software.
 160
 161 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 162 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 163 FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 164 COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 165 IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 166 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 167
 168 --------------------------------------------------------------------------------
 169
 170 * Credits
 171
 172 Andrew Plotkin invented Glulx, so obviously Git wouldn't exist without him. I
 173 also reused some code from his Glulxe interpreter (glkop.c and search.c), which
 174 saved me a lot of time and let me concentrate on the more interesting stuff.
 175
 176 Many thanks are due to John Cater, who not only persuaded me to use source
 177 control, but let me use his own CVS server. John also provided lots of useful
 178 advice and encouragement, as did Sean Barrett.
 179
 180 Thanks also to Joe Mason, Adam Thornton, Simon Baldwin and Joonas Pihlaja who
 181 were among the first to try it out and complain that it wasn't working. Joonas
 182 also gets special brownie points for trying out more bizarre boundary cases than
 183 I realised existed in the first place.
 184
 185 Tor Andersson was apparently the first person to use setmemsize, since he also
 186 explained why it didn't work and contributed a fix. Thanks, Tor!
 187
 188 David Kinder has done a stellar job of maintaining the code recently. Thanks
 189 also to Eliuk Blau for tracking down bugs in the memory management opcodes.
 190
 191 --------------------------------------------------------------------------------
 192
 193 * Version History
 194
 195 1.2.9 2011-08-28  Fixed a bug in glkop.c dispatching, to do with optional
 196                   array arguments, following a similar fix in Glulxe.
 197                   Glk array and string operations are now checked for memory
 198                   overflows (though not for ROM writing), following a similar
 199                   fix in Glulxe.
 200
 201 1.2.8 2010-08-25  Fixed a problem with 'undo' when compiled as 64 bit,
 202                   contributed by Ben Cressey.
 203                   Fixed a sign problem for the @fceil opcode, following a
 204                   similar fix in Glulxe.
 205
 206 1.2.7 2010-08-20  Floating point opcode support (VM spec 3.1.2).
 207                   Restart does not now discard undo information, so that a
 208                   restart can be undone.
 209
 210 1.2.6 2010-02-09  Imported fix for retained Glk array handling from Glulxe.
 211
 212 1.2.5 2009-11-21  Fixes for problems shown by Andrew Plotkin's glulxercise test
 213                   cases, from David Kinder.
 214
 215 1.2.4 2009-04-02  More David Kinder! Accelerated opcode support (VM spec 3.1.1).
 216
 217 1.2.3 2009-02-22  David Kinder and Eliuk Blau fixed some memory management bugs.
 218                   Added a regression test (thanks to Emily Short for assistance)
 219                   Switched to MIT-style license (see above).
 220
 221 1.2.2 2009-01-21  malloc & mfree contributed by the most excellent David Kinder.
 222
 223 1.2.1 2008-09-14  Support for 64-bit machines, contributed by Alexander Beels.
 224                   Fix for crashing bug in RESTORE, contributed by David Kinder.
 225                   Non-Unicode display bug fix, contributed by Jeremy Bernstein.
 226
 227 1.2   2008-01-06  Minor version increment for VM spec 3.1.
 228                   Implemented mzero and mcopy, but not malloc and mfree (yet).
 229
 230 1.1.3 2006-10-04  Fixed a bug in the cache logic that broke the game Floatpoint.
 231                   Added some other caching tweaks and put in a few more asserts.
 232
 233 1.1.2 2006-08-22  streamnum in filter I/O mode no longer prints a garbage char.
 234                   Merged in David Kinder's updated Windows startup code.
 235
 236 1.1.1 2006-08-17  Wow, over a year since the last update.
 237                   Rolled in Tor Andersson's fix for setmemsize.
 238
 239 1.1   2004-12-22  Minor version increment because we now implement VM spec 3.0.
 240                   Implemented new Unicode opcodes and string types.
 241
 242 1.0.6 2004-12-10  Random number generator now handles random(0) correctly.
 243                   Code cache now tracks the number of function calls properly.
 244                   Fixed a bug that could hang the terp when the cache filled up.
 245
 246 1.0.5 2004-05-31  Random number generator is now initialised properly.
 247                   Some source files had Mac line-endings, now fixed.
 248                   Version number is now set in the Makefile, not in git.h.
 249                   Merged David Kinder's Windows Git code into main distribution.
 250
 251 1.0.4 2004-03-13  Fixed a silly bug in direct threading mode that broke stkroll.
 252                   Memory access bounds checking has been tightened up slightly.
 253                   aload and astore now work correctly with negative offsets.
 254                   Rewrote the shift opcodes a bit more defensively.
 255                   Implemented the "verify" opcode.
 256                   Code in RAM is no longer cached by default.
 257                   Adding some special opcodes to control the code cache.
 258                   Bad instructions are now caught in the terp, not the compiler.
 259                   Now passes all of Joonas' indirect string decoding tests.
 260
 261 1.0.3 2004-01-22  No longer hangs when using streamnum in the "filter" I/O mode.
 262                   setstringtbl opcode now works correctly.
 263
 264 1.0.2 2003-10-25  Stupid bug in 1.0.1 -- gitWithStream() was broken and wasn't
 265                   able to load Blorb files. Now it's *really* fixed.
 266
 267 1.0.1 2003-10-23  Fixed a bug where strings were printed as "[string]"
 268                   Fixed a bug in tailcall
 269                   Implemented setmemsize
 270                   Implemented protect
 271                   Moved git_init_dispatch() call out of startup code, into git.c
 272                   Added divide-by-zero check
 273                   Compiler now stops when it finds a 'quit' or 'restart'
 274                   Added gitWithStream() as a workaround for xglk
 275
 276 1.0   2003-10-18  First public release
 277