Using advmake

## 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.
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
-J or -HTML | create an HTML/JavaScript version
-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
-m32 | force building 32 bit executable, if possible
-m64 | force building 64 bit executable, if possible
-g | create a gdb-instrumented executable
-D<symbol> | add a symbol to the C compilation command
-L<pathname> | add a library search pathname 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
-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 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