--- /dev/null
+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.<glk_library_name> 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/<youros>.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.
projects / projects / chimara / chimara.git / blobdiff