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).

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.

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

Back to the documentation index To the Mipmip home page	Feel free to leave a comment! Mike Arnautov (06 May 2025)