Git is an interpreter for the Glulx virtual machine. Its homepage is here: http://diden.net/if/git Git's main goal in life is to be fast. It's about five times faster than Glulxe, and about twice as fast as Frotz (using the same Inform source compiled for the Z-machine). It also tries to be reasonably careful with memory: it's possible to trade speed off against memory by changing the sizes of Git's internal buffers. I wrote Git because I want people to be able to write huge games or try out complicated algorithms without worrying about how fast their games are going to run. I want to play City of Secrets on a Palm without having to wait ten seconds between each prompt. Have fun, and let me know what you think! Iain Merrick iain@diden.net -------------------------------------------------------------------------------- * Building and installing Git This is just source code, not a usable application. You'll have to do a bit of work before you can start playing games with it. If you're not confident about compiling stuff yourself, you probably want to wait until somebody uploads a compiled version of Git for your own platform. Git needs to be linked with a Glk library in order to run. This can be easy or hard, depending on what kind of computer you're using and whether you want Git to be able to display graphics and play sounds. To find a suitable Glk library, look here: http://eblong.com/zarf/glk Exactly how you build and link everything depends on what platform you're on and which Glk library you're using. The supplied Makefile should work on any Unix machine (including Macs with OS X), but you'll probably want to tweak it to account for your particular setup. If you're not using Unix, I'm afraid you'll have to play it by ear. If the Glk library you chose comes with instructions, that's probably a good place to start. On Unix, git_unix.c contains the startup code required by the Glk library. git_mac.c and git_windows.c contain startup code for MacGlk and WinGlk respectively, but I can't guarantee that they're fully up-to-date. It should be possible to build Git with any C compiler, but it works best with GCC, because that has a non-standard extension that Git can use for a big speed boost. GCC 2.95 actually generates faster code than GCC 3, so if you have a choice, use the former. (On OS X, this means compiling with 'gcc2'.) -------------------------------------------------------------------------------- * Configuring Git There are several configuration options you can use when compiling Git. Have a look at config.h and see which ones look applicable to your platform. The Makefile includes settings to configure Git for maximum speed on Mac OS X; the best settings for other Unix platforms should be similar. The most important setting is USE_DIRECT_THREADING, which makes the interpreter engine use GCC's labels-as-values extension, but this only works with GCC 2.95. -------------------------------------------------------------------------------- * Porting to a new platform To do a new port, you first need to find a suitable Glk library, or write a new one. Then you need to write the startup code. Start with a copy of git_unix.c, git_mac.c or git_windows.c and modify it appropriately. The startup code needs to implement the following functions: void glk_main() // Standard Glk entrypoint void fatalError(const char* s) // Display error message and quit In glk_main(), you need to locate the game file somehow. Then you have two options. You can open the game as a Glk stream and pass it to this function: extern void gitWithStream (strid_t stream, git_uint32 cacheSize, git_uint32 undoSize); Or you can load the game yourself, and just pass Git a pointer to your buffer: extern void git (const git_uint8 * game, git_uint32 gameSize, git_uint32 cacheSize, git_uint32 undoSize); If the operating system provides some way of memory-mapping files (such as Unix's mmap() system call), you should do that and call git(), because it will allow the game to start up much more quickly. If you can't do memory-mapping, you should just open the game as a file stream and call gitWithStream(). Note that some Glk libraries, such as xglk, aren't compatible with memory-mapped files. "cacheSize" and "undoSize" tell Git what size to use for its two main internal buffers. Both sizes are in bytes. You may want to make these values user-configurable, or you may just want to pick values that make sense for your platform and use those. (My Unix version currently uses fixed values, but I'm going to add some optional command-line parameters to override these defaults.) "cacheSize" is the size of the buffer used to store Glulx code that Git has recompiled into its internal format. Git will run faster with a larger buffer, but using a huge buffer is just a waste of memory; 256KB is plenty. "undoSize" is the maximum amount of memory used to remember previous moves. The larger you make it, the more levels of undo will be available. The amount of memory required to remember one undo position varies from a few KB up to tens of KB. 256KB is usually enough to store dozens of moves. -------------------------------------------------------------------------------- * Known problems GCC 3 has bigger problems than I thought. On PowerPC, the direct threading option results in much slower code; and on x86, terp.c crashes GCC itself if direct threading is used. Therefore, I recommend that you use GCC 2.95 if possible. If you only have GCC 3, don't define USE_DIRECT_THREADING, at least until the compiler bug is fixed. Since the previous update, GCC 4 has been released, but I haven't evaluated it yet. If you want to give it a try, let me know how you get on! Some Glk libraries, such as xglk, can't deal with memory-mapped files. You can tell that this is happening if Git can open .ulx files, but complains that .blb files are invalid. The solution is to use gitWithStream() rather than git() in your startup file, and make sure you're giving it a file stream rather than a memory stream. If you're using the git_unix.c startup file, just make sure USE_MMAP isn't defined. 1-byte and 2-byte local variables are not implemented yet. This means git can't currently play games created with the Superglus system. This will be fixed at some point. In the search opcodes, direct keys don't work unless they're exactly 4 bytes long. -------------------------------------------------------------------------------- * Copyright information Note: previous versions of Git used an informal freeware license, but I've decided it's worth formalising. As of version 1.2.3, I've switched to the MIT license. Copyright (c) 2003 Iain Merrick Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -------------------------------------------------------------------------------- * Credits Andrew Plotkin invented Glulx, so obviously Git wouldn't exist without him. I also reused some code from his Glulxe interpreter (glkop.c and search.c), which saved me a lot of time and let me concentrate on the more interesting stuff. Many thanks are due to John Cater, who not only persuaded me to use source control, but let me use his own CVS server. John also provided lots of useful advice and encouragement, as did Sean Barrett. Thanks also to Joe Mason, Adam Thornton, Simon Baldwin and Joonas Pihlaja who were among the first to try it out and complain that it wasn't working. Joonas also gets special brownie points for trying out more bizarre boundary cases than I realised existed in the first place. Tor Andersson was apparently the first person to use setmemsize, since he also explained why it didn't work and contributed a fix. Thanks, Tor! David Kinder has done a stellar job of maintaining the code recently. Thanks also to Eliuk Blau for tracking down bugs in the memory management opcodes. -------------------------------------------------------------------------------- * Version History 1.2.4 2009-04-02 More David Kinder! Accelerated opcode support (VM spec 3.1.1). 1.2.3 2009-02-22 David Kinder and Eliuk Blau fixed some memory management bugs. Added a regression test (thanks to Emily Short for assistance) Switched to MIT-style license (see above). 1.2.2 2009-01-21 malloc & mfree contributed by the most excellent David Kinder. 1.2.1 2008-09-14 Support for 64-bit machines, contributed by Alexander Beels. Fix for crashing bug in RESTORE, contributed by David Kinder. Non-Unicode display bug fix, contributed by Jeremy Bernstein. 1.2 2008-01-06 Minor version increment for VM spec 3.1. Implemented mzero and mcopy, but not malloc and mfree (yet). 1.1.3 2006-10-04 Fixed a bug in the cache logic that broke the game Floatpoint. Added some other caching tweaks and put in a few more asserts. 1.1.2 2006-08-22 streamnum in filter I/O mode no longer prints a garbage char. Merged in David Kinder's updated Windows startup code. 1.1.1 2006-08-17 Wow, over a year since the last update. Rolled in Tor Andersson's fix for setmemsize. 1.1 2004-12-22 Minor version increment because we now implement VM spec 3.0. Implemented new Unicode opcodes and string types. 1.0.6 2004-12-10 Random number generator now handles random(0) correctly. Code cache now tracks the number of function calls properly. Fixed a bug that could hang the terp when the cache filled up. 1.0.5 2004-05-31 Random number generator is now initialised properly. Some source files had Mac line-endings, now fixed. Version number is now set in the Makefile, not in git.h. Merged David Kinder's Windows Git code into main distribution. 1.0.4 2004-03-13 Fixed a silly bug in direct threading mode that broke stkroll. Memory access bounds checking has been tightened up slightly. aload and astore now work correctly with negative offsets. Rewrote the shift opcodes a bit more defensively. Implemented the "verify" opcode. Code in RAM is no longer cached by default. Adding some special opcodes to control the code cache. Bad instructions are now caught in the terp, not the compiler. Now passes all of Joonas' indirect string decoding tests. 1.0.3 2004-01-22 No longer hangs when using streamnum in the "filter" I/O mode. setstringtbl opcode now works correctly. 1.0.2 2003-10-25 Stupid bug in 1.0.1 -- gitWithStream() was broken and wasn't able to load Blorb files. Now it's *really* fixed. 1.0.1 2003-10-23 Fixed a bug where strings were printed as "[string]" Fixed a bug in tailcall Implemented setmemsize Implemented protect Moved git_init_dispatch() call out of startup code, into git.c Added divide-by-zero check Compiler now stops when it finds a 'quit' or 'restart' Added gitWithStream() as a workaround for xglk 1.0 2003-10-18 First public release