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