Using the advmake script
My main tool for building A-code games is advmake – 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 A-code tarball.
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 and MacOS. It requires an ANSI C compiler (such as gcc or
clang) invokable as cc. Initially at least, it also needs GNU
(or compatible) make in order to build the acdc translator from
the supplied C sources. A couple of other helper executable may also get built
if special executable types are to be built. If make is absent, you
will need to build those executables manually, basing on the very simple
If GNU readline and ncurses libraries are present, these will
be automatically used if necessary. Without them, the console mode of games
will lack command editing functionality.
The script assumes that it is located in the binsub-directory within the
directory hierarchy as supplied in the A-code tarball, only the top level directory
of the hierarchy may be renamed as desired. Thus you should either
invoke advmake by its pathname, or add its bin directory to the
command search path.
Basic use of advmake
The default type of game executablle (the console-only one) can be builf
simply by invoking the advmake script and giving it the game name (with
or without the version number) as the sole argument. The executable will be
created in the game's source directory. For example, if adv770 is supplied
as adv770-2.19 then both
will build a console-only executable of adv770.
Alternatively, if you are in the game's source directory, just running
advmake with no arguments will be sufficient – the name of the
game will be inferred from your current working directory.
To buid an executable, which uses a browser for its display, just add as an
option -B to the advmake invocation command line. The resulting
executable will by default invoke your normal browser and communicate with it.
The same executable can be still run in the plain console mode by adding the
-C option to its invocation line.
Advanced use of advmake
As supplied, the A-code sources tarball has the following directory
| | | | |
bin doc acdc-12.39 kernel-12.76 <game> ...
The C sub-directories of supplied games contain C sources derived from the
game's A-code source. Thus if you cannot or do not wish to use advmake,
you can simply use these C sources with an ANSI C compiler to create game
executables. See separate document explaining
how to do this.
The acdc, kernel and any game sub-directories can be versioned
(e.g. acdc-12.39) or non-versioned (just acdc in this
example). By convention, in these cases directories without version numbers contain
"unstable" code – still under development. Versioned
directories contain stable code of the appropriate version.
By default, the advmake 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.
mode, you will also need to install and configure Emscripten (http://kripken.github.io/emscripten-site/).
The advmake 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 advmake to work. The tools tarball does
not contain any executables. If advmake needs any helper executables
(e.g. the acdc translator) it will build them automatically from
sources included in the tarball, using GNU make.
Usage: advmake [options] [game]
To build a game, advmake 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 advmake 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
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, advmake 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 advmake options ( see
below for more detailed explanations). Please note that all these
options behave like GNU's long options and, indeed, may be prefixed with
-- rather than just -. In other words, they cannot be amalgamated
Unix-style into multiple options. So e.g. -C -W cannot be replaced
|Build mode options|
| -B or -H||create combined console/browser (HTTP) executable|
| -C||default; create a console-only executable (no HTTP)|
| -A or -L||create a test executable using the library mode|
| -T or -S||create a single turn (cloud) mode executable|
| -W||include opt/debug.acd if it exists|
|Other script options|
| -s||use the latest stable versions of acdc and kernel|
| -a <version>||use the specified version of acdc|
| -k <version>||use the specified version of kernel|
| -m32||force building 32 bit executable, if possible|
| -m64||force building 64 bit executable, if possible|
| -g||create a gdb-instrumented executable|
| -gg||like -g plus gcc macro storing|
| -D<symbol>||add a symbol to the C compilation command|
|Options modifying acdc behaviour|
| -t||equivalent to -g -DDEBUG -DLOG|
| -p||(plain) don't encrypt game data|
| -d||acdc's -debug – adds A-code lines as comments in derived C|
| -o||Use <dir> for creating derived C sources|
| -c||translate A-code to C but do not build executable|
| -nc||don't translate A-code to C but do build executable|
| -w||show acdc warnings, which are suppressed by default|
| -v||show progress info|
| -u||create and use uglified C sources|
| -dkm||if uglifying, dump keyword mappings list in|
|Deprecated game data options|
| -fr||use .dat file and read from it as necessary (deprecated)|
| -fm||use .dat file and read it into memory on start (deprecated)|
| -fp||use .dat file and page from it (deprecated)|
| -l||if paging (-fp), enable locate request stats reporting|
|Script display options|
| -x||echo commands being executed|
| -h||show available options|
Now for some more details...
Build mode options
- -B or -H
- Browser mode build
This option instructs advmake 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
- Console mode build
This is the default build mode – console
- -A or -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 a
separate document on details of the call interface.
- -J or -HTML
the emscripten home
page for installation instructions). This option causes advmake
in any HTML5-compliant browser.
- -T or -S
- 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>.
Other script options
- 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.
- Force use of stable kernel version
Stable kernel versions live in directories named kernel-<version>.
If the directory kernel without a version number is present, this is
assumed to contain the unstable (i.e. under development) version of the kernel
and this version is used by default. In the absence of this directory, or if the
-s keyword is supplied, the highest version kernel directory is used
instead. There is no mechanism to force use of any other kernel directories.
- -a <version>
- You may have older versions of acdc in directories called
acdc-<version>. This option instructs advmake 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 advmake to use the
specified kernel version, instead of searching for the most recent one.
Options passed through to the C compiler
- -m32, -m64
- Force 32 or 64 build
- Create a gdb-instrumented executable
- As -g but forces use of gcc and makes macro definitions
available to the gdb debugger.
- Define an additional compilation symbol
NB: there is no space between -D and the symbol name.
- Pass to the compiler -g -DDEBUG
The DEBUG symbos casuses the executable to display some diagnostic messages.
Options modifying acdc behaviour
- (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.
- 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.
- -o <dir>
- Specify the directory to place the derived C sources
By default, the derived C sources are placed either in the same directory as
the games A-code source, or (to keep down the clatter) in the sub-directory C
thereof, if present. The -o option allows some arbitrary
target directory to be nominated instead.
- Translate A-code to C but do not build executable
Just invokes acdc to translate game's A-code to C.
- 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.
- Show acdc warnings
Warnings about unused symbols in the A-code source are suppressed
- Request more verbose output from acdc
- Create and use uglified C sources
With this option, C sources emitted by acdc are ran through
an uglifier. This creates "uglified" (i.e. maximally unreadable)
versions the directory called U (alongside the C one, which holds non-uglified
sources). The uglified lot can be distributed as derived C-sources.
- If uglifying, dump keyword mappings list in
This may be useful if attempting to debug uglified C course (not
recommended!). This option is ignored, unless -u is given as well.
Deprecated game data options
In the old days, when computer memories were minuscule, game data was
emitted by acdc as a separate .dat file, instead of being pre-loaded
into the executable. This option is still retained, mainly for building
DOS versions of games (used by some people under DOS emulators).
- Use .dat file and read from it as necessary
- Use .dat file and read it into memory on start
- Use .dat file and page from it
- If paging (-fp), enable locate request stats reporting
Script display options
- Echo commands being executed by the advmake script
- Show available options of the advmake script