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