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.


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

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

advmake adv770

and

advmake adv770-2.19

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 hierarchy:


                        acode-12.76
                             │
      ┌────────┬─────────┬───┴─────┬─────────────┐    ...
      │        │         │         │             │
     bin      doc    acdc-12.39  kernel-12.76  <game> ...
                                                 │
                                                 C

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.

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

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

Build mode options
  -B or -Hcreate combined console/browser (HTTP) executable
  -Cdefault; create a console-only executable (no HTTP)
  -A or -Lcreate a test executable using the library mode
  -J or -HTMLcreate an HTML/JavaScript version
  -T or -Screate a single turn (cloud) mode executable
  -Winclude opt/debug.acd if it exists
Other script options
  -suse the latest stable versions of acdc and kernel
  -a <version>use the specified version of acdc
  -k <version>use the specified version of kernel
  -m32force building 32 bit executable, if possible
  -m64force building 64 bit executable, if possible
  -gcreate a gdb-instrumented executable
  -gglike -g plus gcc macro storing
  -D<symbol>add a symbol to the C compilation command
Options modifying acdc behaviour
  -tequivalent to -g -DDEBUG -DLOG
  -p(plain) don't encrypt game data
  -dacdc's -debug – adds A-code lines as comments in derived C
  -oUse <dir> for creating derived C sources
  -ctranslate A-code to C but do not build executable
  -ncdon't translate A-code to C but do build executable
  -wshow acdc warnings, which are suppressed by default
  -vshow progress info
  -ucreate and use uglified C sources
  -dkmif uglifying, dump keyword mappings list in
Deprecated game data options
  -fruse .dat file and read from it as necessary (deprecated)
  -fmuse .dat file and read it into memory on start (deprecated)
  -fpuse .dat file and page from it (deprecated)
  -lif paging (-fp), enable locate request stats reporting
Script display options
  -xecho commands being executed
  -hshow 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 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.
   -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
   -g
Create a gdb-instrumented executable
   -gg
As -g but forces use of gcc and makes macro definitions available to the gdb debugger.
   -D<symbol>
Define an additional compilation symbol
NB: there is no space between -D and the symbol name.
   -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.
   -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.
   -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

Back to the A-code page

To the Mipmip home page
Feel free to leave a comment!
Mike Arnautov (28 April 2019)