interpreters/bocfel/BUILDING

   1 GNU make is required, and all of the examples herein assume that GNU make is
   2 being used.  If your native make is not GNU, substitute gmake for make.
   3
   4 A C99 compiler is required to build Bocfel; or at least a compiler that supports
   5 the C99 features that are used.  These include, but are probably not limited to,
   6 VLAs, snprintf(), mixed declarations and code, fixed-width integers, and
   7 compound literals.
   8
   9 Officially supported compilers are handled in compiler.mk.  If you get Bocfel
  10 working with another compiler, I would be happy to add it to compiler.mk.  Note
  11 that Bocfel has a few requirements (beyond C99) from its compilers.  Compilers
  12 are expected to support the following rather standard Unix command-line
  13 arguments, and are expected to work as linkers, as well:
  14 -D - define a macro
  15 -L - define a library search path
  16 -l - specify a library to link
  17 -o - specify the output file name
  18 -g - build with debugging symbols
  19 -c - compile but don't link, producing a .o file from a .c file
  20 -O - Optimize (but this can be changed via the $OPT variable)
  21
  22 Compilers are also expected to understand optimization flags while they are
  23 linking; modern compilers can do link-time optimization, and generally require
  24 the same flags when compiling and linking (the system linker is usually not
  25 smart enough to handle the link-time optimized object files).
  26
  27 The character set used is required to be compatible with ASCII.  This is not a
  28 particularly onerous requirement; but if I ever have access to a system that
  29 supports a wildly different character set, I would be willing to think about
  30 extending support beyond ASCII.  For now, though, it is much easier to assume
  31 ASCII, because almost everybody uses a character set that is compatible with it,
  32 including the Z-machine.
  33
  34 A 32-bit (or greater) system is probably a requirement.  I have tried to avoid
  35 the assumption that "int" is 32 bits, and it is entirely possible that I have
  36 succeeded and a system with 16-bit ints would work properly.  However, there are
  37 some lookup tables that are 65K each, which would probably cause fits for 16-bit
  38 systems.  As with the ASCII requirement, if I ever happen upon a 16-bit system
  39 with a C99 compiler, I will probably try to get Bocfel working with it.
  40
  41 I make use of fixed-width types such as uint8_t and uint16_t.  As a practical
  42 side-effect, Bocfel requires a system with 8-, 16-, and 32-bit 2's complement
  43 integers.  This is likely not a problem.
  44
  45 -------------------------------------------------------------------------------
  46
  47 There are two main types of build: Glk and non-Glk.  Glk builds use libraries
  48 based on Andrew Plotkin's Glk standard for I/O.  Glk builds can be full-
  49 featured, including timed input and cursor control, allowing games like Border
  50 Zone and Seastalker to run as intended.  Non-Glk builds use nothing but standard
  51 C functions.  This has the advantage of running on systems where Glk has not
  52 been ported, but the disadvantage of missing important features.  Non-Glk builds
  53 are generally not useful.
  54
  55 The first thing to do is edit config.mk and set $PLATFORM to the proper value.
  56 See the comments in that file for an explanation.  There are other variables
  57 that may be set through config.mk, each of which has comments explaining its
  58 use.
  59
  60 To build a non-Glk interpreter, simply run:
  61 make GLK=
  62
  63 The $GLK variable may also be set through config.mk.
  64
  65 Glk builds are slightly more involved.  For most Glk libraries (e.g. glkterm(w),
  66 xglk, cheapglk, Windows Glk), you will want to unpack the source distribution
  67 into the current directory (the one containing Bocfel's source), and then build
  68 it.  After this is done, simply run
  69 make GLK=glktermw
  70
  71 to build a Glk-enabled interpreter (where glktermw is the name of the directory
  72 into which the Glk library was unpacked).  Note that the Windows Glk
  73 distribution does not unpack into its own directory, so you will want to change
  74 into the winglk directory before unpacking it.
  75
  76 The presence of a file called Make.<glk_library_name> in the Glk library
  77 directory is required.  Most Glk libraries will include this, but at least
  78 Windows Glk does not.  I have included a Make.winglk that should be sufficient
  79 to build a Windows Glk-enabled interpreter, at least with MinGW.
  80
  81 Bocfel can also be built against Gargoyle's Glk implementation, taking full
  82 advantage of extra features it provides.  Ben Cressey, Gargoyle's maintainer,
  83 has imported Bocfel into the Gargoyle source repository, so the easiest way to
  84 obtain Gargoyle support is to check out the latest version of Gargoyle's source
  85 code; see http://code.google.com/p/garglk/source/checkout.  If you would prefer
  86 to use Bocfel's build system to build against Gargoyle as you would any other
  87 Glk library, read on.
  88
  89 The build process for Gargoyle is slightly more involved.  Gargoyle includes a
  90 full-featured Glk library, but it is not designed for external use.  However,
  91 getting a Gargoyle- (or rather, a garglk-) enabled build is not too difficult.
  92
  93 The first step is to get and install the Jam build tool from
  94 http://www.perforce.com/jam/jam.html.  Your vendor may provide a jam package or
  95 port; consult its documentation.
  96
  97 Next, get a copy of the Gargoyle source code from http://garglk.googlecode.com/.
  98 Extract it somewhere (it need not be in the current directory).  Enter the
  99 directory and run jam.  From the build/<youros>.release/garglk directory, copy
 100 the files libgarglk.so and libgarglkmain.a to the directory "gargoyle" (which
 101 contains a Make.gargoyle file) in the Bocfel source distribution.  Then copy the
 102 files garglk/glk.h, garglk/glkstart.h, and garglk/gi_blorb.h from Gargoyle to
 103 Bocfel's gargoyle directory.  You can now build a garglk-enabled interpreter:
 104 make GLK=gargoyle
 105
 106 If you do not already have Gargoyle installed, you will need to install the
 107 library libgarglk.so somewhere in your library search path.  I would, however,
 108 recommend just installing Gargoyle.  If you do this, you will want to build the
 109 source code of the same version that you install.  If you don't, it's possible
 110 (although unlikely) that ABI or API changes in Gargoyle will cause problems.
 111
 112 Bocfel is built and tested against the development version of Gargoyle, so
 113 ideally this would be the version to build against.  However, Gargoyle does, by
 114 and large, implement a standard API, so the version should not make a large
 115 difference.  There are a few Gargoyle-specific extensions that can possibly
 116 change, but they have been stable apart from one change over the past couple of
 117 years.  The current (2010.1) release of Gargoyle should work, but the only
 118 officially supported version is whatever was current as of this version of
 119 Bocfel's release.
 120
 121 -------------------------------------------------------------------------------
 122
 123 Glk is very portable, and there is very little system-specific code that is
 124 needed.  However, there is a small amount.  Some libraries are, conventionally,
 125 considered to be Unix (cheapglk, xglk, and glkterm(w)); one Windows (Windows
 126 Glk, naturally).  Bocfel needs to know what kind of platform it is running on in
 127 order to provide a few system-specific functions, and it uses this information
 128 to decide what kind of Glk library is in use.  While it is theoretically
 129 possible (for example) for a Unix-based Glk library to use a non Unix-style Glk
 130 startup, I have no desire to require users to set both their OS and Glk
 131 platforms.  Thus a Windows user who desires to use cheapglk (assuming it builds
 132 on Windows) is out of luck, for example.  I consider this to be acceptable
 133 because I expect garglk to be the preferred Glk implementation, and even if it's
 134 not, most Glk uses will work.  When building with garglk, Unix-style Glk startup
 135 is forced, because this is what garglk uses, regardless of platform.