-
Notifications
You must be signed in to change notification settings - Fork 0
/
BUILDING
129 lines (103 loc) · 6.57 KB
/
BUILDING
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
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 C++14 compiler is required to build Bocfel.
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 C++14) 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 .cpp 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 64K 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 C++14 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.
Due to the structure of the program, building with link-time optimization
enabled is highly recommended. With both g++ and clang++, link-time optimization
results in a binary that runs around 40% faster than one built without it. See
config.mk and the OPT variable for information on link-time optimization.
-------------------------------------------------------------------------------
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 implemented, but the disadvantage of missing important features. Non-Glk
builds are generally not useful apart from testing; a non-Glk build will read
from standard input and write to standard output, so can be used for regression
testing such as with Andrew Plotkin's RegTest
(http://eblong.com/zarf/plotex/regtest.html).
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. Gargoyle already includes Bocfel, so
the easiest way to obtain Gargoyle support is to simply download Gargoyle; see
https://github.com/garglk/garglk. 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.
First, get a copy of the Gargoyle source code from
https://github.com/garglk/garlk. Extract it somewhere (it need not be in the
current directory) and build it with something like:
mkdir build
cd build
cmake ..
make
When this is done, copy the files libgarglk.so and libgarglkmain.a from the
directory build/garglk into 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 (2022.1) release of Gargoyle should work, but the only
officially supported version is whatever was current as of this version of
Bocfel's release.