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 tools tarball. The script should be usable on any Unix-like system which supports the GNU bash shell, e.g. 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 Makefiles supplied.

Provided bash, cc and make are all present, and provided you have installed the A-code tools and an A-code game source as supplied by the tools and source tarballs respectively, the game default type of game executable (the combined browser/console one) is built simply by invoking the advmake script and giving it the game name as the sole argument. The executable will be created in the game's source directory.

The tools tarball has the following directory hierarchy:

                        acode-src
                            |
      ------------------------------------------------
      |           |      |           |               |
acdc-<version>   bin    doc    kernel-<version>   (<game>)
      |                                              |
    tools                                           (C)

If you wish to build a game in the HTML/JavaScript mode, you will also need to install and configure Emscripten (http://kripken.github.io/emscripten-site/).

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

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 with -CW.

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

   -C

Console mode build
This is the default build mode – console only.

   -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

JavaScript/HTML build
Creating a JavaScript version requires presence of emscripten (see the emscripten home page for installation instructions). This option causes advmake to create a self-contained HTML/JavaScript page, which will run the game 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

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

   -s

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.

Options passed through to the C compiler

   -m32, -m64

Force 32 or 64 build

   -g

Create a gdb-instrumented executable

   -D<symbol>

Define an additional compilation symbol
NB: there is no space between -D and the symbol name.

   -L<pathname>

Add a library search pathname to the C compilation command
NB: there is no space between -L and the library pathname.

   -t

Pass to the compiler -g -DDEBUG

The DEBUG symbos casuses the executable to display some diagnostic messages.

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.

   -nc

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.

   -v

Request more verbose output from acdc

   -u

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.

   -dkm

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

   -fr

Use .dat file and read from it as necessary

   -fm

Use .dat file and read it into memory on start

   -fp

Use .dat file and page from it

   -l

If paging (-fp), enable locate request stats reporting

Script display options

   -x

Echo commands being executed by the advmake script

   -h

Show available options of the advmake script