X-Git-Url: https://git.stderr.nl/gitweb?p=projects%2Fchimara%2Fchimara.git;a=blobdiff_plain;f=interpreters%2Fbocfel%2FBUILDING;fp=interpreters%2Fbocfel%2FBUILDING;h=30411e802b8f156c5823088d51ae3037c118cf7f;hp=0000000000000000000000000000000000000000;hb=aa30979369091c96bca34499c28cb01bc16efb1d;hpb=61180dab8f5c29f5a29b83fcb7d62942f7a741d1 diff --git a/interpreters/bocfel/BUILDING b/interpreters/bocfel/BUILDING new file mode 100644 index 0000000..30411e8 --- /dev/null +++ b/interpreters/bocfel/BUILDING @@ -0,0 +1,135 @@ +GNU make is required, and all of the examples herein assume that GNU make is +being used. If your native make is not GNU, substitute gmake for make. + +A C99 compiler is required to build Bocfel; or at least a compiler that supports +the C99 features that are used. These include, but are probably not limited to, +VLAs, snprintf(), mixed declarations and code, fixed-width integers, and +compound literals. + +Officially supported compilers are handled in compiler.mk. If you get Bocfel +working with another compiler, I would be happy to add it to compiler.mk. Note +that Bocfel has a few requirements (beyond C99) from its compilers. Compilers +are expected to support the following rather standard Unix command-line +arguments, and are expected to work as linkers, as well: +-D - define a macro +-L - define a library search path +-l - specify a library to link +-o - specify the output file name +-g - build with debugging symbols +-c - compile but don't link, producing a .o file from a .c file +-O - Optimize (but this can be changed via the $OPT variable) + +Compilers are also expected to understand optimization flags while they are +linking; modern compilers can do link-time optimization, and generally require +the same flags when compiling and linking (the system linker is usually not +smart enough to handle the link-time optimized object files). + +The character set used is required to be compatible with ASCII. This is not a +particularly onerous requirement; but if I ever have access to a system that +supports a wildly different character set, I would be willing to think about +extending support beyond ASCII. For now, though, it is much easier to assume +ASCII, because almost everybody uses a character set that is compatible with it, +including the Z-machine. + +A 32-bit (or greater) system is probably a requirement. I have tried to avoid +the assumption that "int" is 32 bits, and it is entirely possible that I have +succeeded and a system with 16-bit ints would work properly. However, there are +some lookup tables that are 65K each, which would probably cause fits for 16-bit +systems. As with the ASCII requirement, if I ever happen upon a 16-bit system +with a C99 compiler, I will probably try to get Bocfel working with it. + +I make use of fixed-width types such as uint8_t and uint16_t. As a practical +side-effect, Bocfel requires a system with 8-, 16-, and 32-bit 2's complement +integers. This is likely not a problem. + +------------------------------------------------------------------------------- + +There are two main types of build: Glk and non-Glk. Glk builds use libraries +based on Andrew Plotkin's Glk standard for I/O. Glk builds can be full- +featured, including timed input and cursor control, allowing games like Border +Zone and Seastalker to run as intended. Non-Glk builds use nothing but standard +C functions. This has the advantage of running on systems where Glk has not +been ported, but the disadvantage of missing important features. Non-Glk builds +are generally not useful. + +The first thing to do is edit config.mk and set $PLATFORM to the proper value. +See the comments in that file for an explanation. There are other variables +that may be set through config.mk, each of which has comments explaining its +use. + +To build a non-Glk interpreter, simply run: +make GLK= + +The $GLK variable may also be set through config.mk. + +Glk builds are slightly more involved. For most Glk libraries (e.g. glkterm(w), +xglk, cheapglk, Windows Glk), you will want to unpack the source distribution +into the current directory (the one containing Bocfel's source), and then build +it. After this is done, simply run +make GLK=glktermw + +to build a Glk-enabled interpreter (where glktermw is the name of the directory +into which the Glk library was unpacked). Note that the Windows Glk +distribution does not unpack into its own directory, so you will want to change +into the winglk directory before unpacking it. + +The presence of a file called Make. in the Glk library +directory is required. Most Glk libraries will include this, but at least +Windows Glk does not. I have included a Make.winglk that should be sufficient +to build a Windows Glk-enabled interpreter, at least with MinGW. + +Bocfel can also be built against Gargoyle's Glk implementation, taking full +advantage of extra features it provides. Ben Cressey, Gargoyle's maintainer, +has imported Bocfel into the Gargoyle source repository, so the easiest way to +obtain Gargoyle support is to check out the latest version of Gargoyle's source +code; see http://code.google.com/p/garglk/source/checkout. If you would prefer +to use Bocfel's build system to build against Gargoyle as you would any other +Glk library, read on. + +The build process for Gargoyle is slightly more involved. Gargoyle includes a +full-featured Glk library, but it is not designed for external use. However, +getting a Gargoyle- (or rather, a garglk-) enabled build is not too difficult. + +The first step is to get and install the Jam build tool from +http://www.perforce.com/jam/jam.html. Your vendor may provide a jam package or +port; consult its documentation. + +Next, get a copy of the Gargoyle source code from http://garglk.googlecode.com/. +Extract it somewhere (it need not be in the current directory). Enter the +directory and run jam. From the build/.release/garglk directory, copy +the files libgarglk.so and libgarglkmain.a to the directory "gargoyle" (which +contains a Make.gargoyle file) in the Bocfel source distribution. Then copy the +files garglk/glk.h, garglk/glkstart.h, and garglk/gi_blorb.h from Gargoyle to +Bocfel's gargoyle directory. You can now build a garglk-enabled interpreter: +make GLK=gargoyle + +If you do not already have Gargoyle installed, you will need to install the +library libgarglk.so somewhere in your library search path. I would, however, +recommend just installing Gargoyle. If you do this, you will want to build the +source code of the same version that you install. If you don't, it's possible +(although unlikely) that ABI or API changes in Gargoyle will cause problems. + +Bocfel is built and tested against the development version of Gargoyle, so +ideally this would be the version to build against. However, Gargoyle does, by +and large, implement a standard API, so the version should not make a large +difference. There are a few Gargoyle-specific extensions that can possibly +change, but they have been stable apart from one change over the past couple of +years. The current (2010.1) release of Gargoyle should work, but the only +officially supported version is whatever was current as of this version of +Bocfel's release. + +------------------------------------------------------------------------------- + +Glk is very portable, and there is very little system-specific code that is +needed. However, there is a small amount. Some libraries are, conventionally, +considered to be Unix (cheapglk, xglk, and glkterm(w)); one Windows (Windows +Glk, naturally). Bocfel needs to know what kind of platform it is running on in +order to provide a few system-specific functions, and it uses this information +to decide what kind of Glk library is in use. While it is theoretically +possible (for example) for a Unix-based Glk library to use a non Unix-style Glk +startup, I have no desire to require users to set both their OS and Glk +platforms. Thus a Windows user who desires to use cheapglk (assuming it builds +on Windows) is out of luck, for example. I consider this to be acceptable +because I expect garglk to be the preferred Glk implementation, and even if it's +not, most Glk uses will work. When building with garglk, Unix-style Glk startup +is forced, because this is what garglk uses, regardless of platform.