Using the advbld script
My main tool for building A-code games is advbld – a
bash script for building various modes of A-code games from their
A-code sources (or from derived C ones). It can be found in the bin
sub-directory of the directory tree supplied in the stand-alone A-code source
tarball A-code source
tarball and also bundled with A-code sources of individual games.
Requirements
The script should be usable on any Unix-like system which supports the GNU
bash shell (version 3 or later) – i.e. Linux, various versions of
Unix, MacOS and these days, perhaps even Windows under LSW.
For its simplest functionality, the script requires nothing more than the
presence of an ANSI C compiler (e.g. gcc or clang) invokable as
cc. The JavaScript/HTML build also requires Emscripten, while a Qt5
build needs Qt5WebKit and Qt5WebKitWidgets libraries, usually not installed by
default with Qt5.
If GNU readline and ncurses libraries are present, these will
be automatically used if necessary. Without them, the console build of games
will lack command editing functionality.
Assumptions
The script makes some important assumptions.
The script needs to use the acdc translator and kernel files.
Directories containing these are assumed to be found alongside the script's
directory, as supplied in the tarball. It follows that the script
should be invoked where it is, in its bin/ directory. You can invoke it
by its pathname, of you can add that bin/ directory to the command
search path.
The acdc translator demands that all A-code source files have
the .acd suffix. If a file name is specified (be it on the command
line or by the INCLUDE directive in the code) without this suffix, it will be
automatically appended before any attempt to open the file.
Unless the script is given the pathname of the game's source, it needs to be
able to make a reasonable guess as to what source file should be used. To
do so, it assumes that game source file(s) live in a directory of the same
name as the name of the game, possibly tagged with the game version number.
So for example, the main source file of adv770 is assumed to be
adv770.acd to be found in the directory called adv770 or
e.g. adv770-2.19.
By convention, sources found in a directory without a version
number tag are deemed to be "unstable" – i.e. under
development, whereas directories tagged by a version number are assumed to
hold stable game versions. This distinction is only of use to game
developers.
Basic use of advbld
The most straightforward, though not always the most convenient, way
to use the script is to supply it with the pathname of a game's source
file.
$ advbld ~/games/adv770/adv770.acd
or alternatively
$ cd ~/games/adv770
$ advbld adv770.acd
The .acd suffix can be dropped – if absent, it will be
automatically appended by acdc.
Perhaps more conveniently, the script can infer the name of the main source
file from the name of the current directory. So for example
$ cd ~/games/adv770-2.19
$ advbld
works too. The script will take the name of the current directory,
stripping off the version number if necessary, and then look for a file named
adv770.acd or main.acd or game.acd.
If a game is specified just by name and there is no game file of the
corresponding name in the current directory, it will be searched for –
the directory specified by the environment variable $ADVDIR, if this is
set, and then in the likely places relative to the location of the
advbld script itself. The upshot is that in most cases you can just
type e.g. "advbld adv770" and let the script do the finding. For
more details, see the next section on advanced uses of the script.
In all cases, the executable will be built in the same directory in which
the game source is located.
By default, the script builds the combined browser/console executable.
By default the executable will invoke your default browser and use that
as the game interface. Alternatively, if invoked with the -C command
line option, it will run simply as a console mode program. See the next
section for other build modes.
Advanced use of advbld
As supplied, the A-code sources tarball has the following directory
hierarchy:
acode-12.91
│
┌────────────────────┼───────────────────┐
│ │ │
acdc-12.49 bin kernel-12.91
|
The advbld script can be found in the bin sub-directory of the
directory tree supplied in the A-code tools tarball.
You can change the name of the top directory of that tree, but the rest of it must
stay as supplied in order for advbld to work. The tarball does
not contain an executable of the acdc translator. It will be
build by the script automatically the first time it is required using
an ANSI C compiler invokable as cc.
The acdc and kernel sub-directories can be versioned
(e.g. acdc-12.49) or non-versioned (e.g. just acdc).
By convention, directories without version numbers contain
"unstable" code – still under development. Versioned
directories contain stable code of the appropriate version.
By default, the advbld script will use either non-versioned
directories for acdc, kernel and whatever game is being built, or failing
that, the directory of the right name with the highest version number
available. This default behaviour can be modified by invocation options used.
For example, one can supply a game name with its version number, to force the
particular version of the game code to be built. Or one can use the -s
option, to ignore non-stable code.
When searching for a game specified just by its name, which is not found in
either in the current directory or in an appropriately named sub-directory of
$ADVDIR (if this is set), the script will look first alongside its bin
directory or alongside its parent (acode-12.91 in the above diagram).
If you wish to build a game in the HTML/JavaScript
mode, you will also need to install and configure Emscripten (https://kripken.github.io/emscripten-site/).
A QT5 build requires Qt5 installed and dev versions of these libraries:
Qt5Core, Qt5Widgets, Qt5 Gui, Qt5WebKit and Qt5WebKitWidgets.
If you have Perl installed, the script can generate sorted cross-reference
lists of game A-code sources.
Usage: advbld [options] [game]
To build a game, advbld needs: game source(s), the acdc translator
and the A-code kernel files. All of these are expected to be found in sub-directories
of the parent directory of the one containing the advbld script.
The directory containing game source(s) is assumed to bear the name of the game
itself, possibly suffixed with a version number (e.g. adv770 or
adv770-2.19).
The acdc translator is expected to be found in the directory called
'acdc'. If this is absent, directories named 'acdc-<version>' (e.g.
'acdc-12.36') are examined and the one with the highest version number is
used. (The non-versioned directory is assumed to contain unstable sources and is
ignored if a stable build is requested.)
Similarly, the kernel files are assumed to be either in the directory called
'kernel', or (if this is absent or if a stable build is requested) in the
highest version number directory named 'kernel-<version>'.
By default, advbld assumes the name of your current directory to be the
name of the game to be built. If a game name is given, it will be assumed to
live in a directory of that name alongside the directory containing the script itself.
This is why game sources available from my mipmip.org are supplied in a directory tree of the
same name as the A-code tools one. The A-code tools and any game sources
tarballs are guaranteed to co-exist peacefully within that top level directory
with no clashes.
For explanation of build modes available, please see
a separate page.
Here's a quick summary of advbld options ( see
below for more detailed explanations).
Main build options |
-B | default; build a combined console/browser (HTTP) executable |
-C | build a console-only executable (no HTTP) |
-J | build an HTML/JavaScript version |
-L | build a test executable using the library mode |
-Q | build a QT5 executable |
-T | build a single turn (cloud) mode executable |
-W | include opt/debug.acd if it exists.
This option is compatible with all of the above build types. |
Script display options |
-v | show more progress info |
-q | less progress info |
-x | echo commands being executed |
-h | show available options |
The rest of options are of use only to an A-code game developer.
Versions of acdc, kernel and game are deemed "unstable" if the relevant
directories lack a version number. The script defaults to using unstable
versions, if present, and the latest (highest version number) versions
otherwise.
Version-related options |
-s | use the latest stable versions of acdc and kernel (and game) |
-u | insist on using unstable versions of acdc and kernel (and game) |
-a <version> | use the specified version of acdc |
-k <version> | use the specified version of kernel |
Options passed through to the C compiler |
-g | create a gdb-instrumented executable |
-gg | like -g plus gcc macro storing |
-D<symbol> | add a symbol to the C compilation command |
--m32 | force building 32 bit executable, if possible |
Options modifying acdc behaviour |
-p | (plain) don't encrypt game data |
-d | acdc's -debug – adds A-code lines as comments in derived C |
-c | translate A-code to C but do not build executable |
-b | don't translate A-code to C but do build executable |
-w | show acdc warnings, which are suppressed by default |
-X | generate A-code source cross-reference lists |
Now for some more details... Please note that the script
may also understand some deprecated options not listed here. Those will
simply disappear in due time.
Main build options
- -B (default)
- Browser/Console build
This option instructs advbld to build a
browser-capable executable. By default such an executable uses a local browser
for interacting with the players. The executable itself acts as a very simple
HTTP server, passing player commands to the game, and game's responses to the
player. The default browser is invoked for this purpose (in a manner
appropriate to supported platforms), but a different browser can be nominated
on the command line following this option, or by editing the .acode/acode.conf
file. This build can be also used to play in a console (terminal) window
by invoking the executable with the -C option.
- -C
- Console mode build
The game executable expects to run in a
console (or terminal) window. It offers the unique opportunity of adventuring
the way it was on old slow output devices. The output speed in baud can
be specified by adding "-o <baud>" to the invocation command line,
where "<baud> is a number such as 300 (old teletypes), 1200
(DECwriters) etc...
- -L
- Library mode build
By default, A-code games are in control of
the command/response loop, but this is not possible in some cases (e.g on
IOs). This "library" option converts kernel's main() into
advturn(), which returns every time the player is prompted for input.
It is up to the calling program to obtain player command and to supply it in
the next call to advturn(). Please see
the section on details of the call interface.
- -J
- JavaScript/HTML build
Building a JavaScript version requires presence of emscripten (see
the emscripten home
page for installation instructions). This option causes advbld
to create a self-contained HTML/JavaScript page, which will run the game
in any HTML5-compliant browser.
- -Q
- QT5 build
This build puts a QT5 wrapper around the library mode build. It requires
dev versions of the following QT libraries: Qt5Core, Qt5Widgets, Qt5Gui,
Qt5WebKit and Qt5WebKitWidgets.
- -T
- Single turn (cloud) build
The resulting executable is suitable for cloud use with a suitable front-end.
It restores game in progress, takes player command as command line arguments,
executes a single game turn, outputs the result on standard output as
HTML-formatted text, saves game in progress and exits. A new game can be
forced by using the -n command line keyword instead of player command. A save
game can be loaded by starting the executable with -l <saved_game>.
- -W
- Debug (wizard mode) build
If the file opt/debug.acd exists, it gets copied to the current directory
before building the game. The copy is deleted after the build is complete.
This mechanism presupposes debug.acd being conditionally included
by the game's A-code source.
Script display options
- -v
- Requests more progress info
Adds acdc's report to the information being displayed.
- -q
- Requests less progress info
Only the final success (or error report) is produced.
- -x
- Echo commands being executed by the advbld script
- -h
- Show available options of the advbld script
Version-related options
- -s
- Force use of the latest stable acdc and kernel (and game) versions
Stable kernel versions live in directories named
kernel-<version>. Similarly for the acdc translator and
individual games. This option overrides the default behaviour of preferring
unstable versions of acdc, kernel and game code. Forces the use of the highest
version number ones. Only of use to game developers.
- -u
- Forces use of the unstable acdc and kernel (and game)
versions
Only of use to game developers.
- -a <version>
- You may have older versions of acdc in directories called
acdc-<version>. This option instructs advbld to use the
specified acdc version, instead of searching for the most recent one.
- -k <version>
- You may have older versions of the kernel in directories called
kernel-<version>. This option instructs advbld to use the
specified kernel version, instead of searching for the most recent one.
Options passed through to the C compiler
- -g
- Create a gdb-instrumented executable
- -gg
- As -g but forces use of gcc and makes macro definitions
available to the gdb debugger. Note that this is not
a GNU-style long option. It is in fact interpreted as -g -g.
- -D<symbol>
- Define an additional compilation symbol
NB: you can (but need not) add a space between -D and the symbol name.
- --m32
- Force 32 build
Only of use on 64 bit machines.
Options modifying acdc behaviour
- -p
- (Plain) don't encrypt game data
By default game data (mostly text) is encrypted in order to make it harder
to cheat by examining core dumps. The disadvantage of this is that executables
are less compressible.
- -d
- acdc's -debug – adds A-code lines as comments in derived C
In the absence of an A-code debugger, this is a moderately convenient way
of debugging games on the A-code source level.
- -c
- Translate A-code to C but do not build executable
Just invokes acdc to translate game's A-code to C.
- -b
- Don't translate A-code to C but do build executable
This option omits running acdc – useful if temporarily
tweaking translated C sources while debugging.
- -w
- Show acdc warnings
Warnings about unused symbols in the A-code source are suppressed
by default.
- -X
- Generate A-code cross-reference
Requests the acdc translator to construct sorted cross-reference
lists of the A-code source
|