Creating ANSI C sources from the A-code source

(A-code acdc version 12.85)

Contents

A-code source

Logically, an A-code source is a single file, usually with the .acd suffix. The suffix is optional; if present, it can be omitted when nominating to acdc the A-code file to be processed.

In practice, A-code source can be split into a number of files, which are incorporated in the "main" one by means of the A-code include major directive. Again, such include files are conventionally suffixed with .acd, which suffix may be omitted in include statements.

A-code framework

To build a working executable out of A-code source, you need A-code kernel files, available as a part of the acode system source tarball https://mipmip.org/acode/acode-12.85.html. This tarball contains C sources of the latest releases of the acdc translator and of the A-code kernel, as well as some useful bash scripts. See that page for details.

If you are using Linux, Unix or OSX, the simplest thing to do is to use the advbld script supplied as a part of the acode source tarball – please see the README file contained therein. However, if you are using some other platform, you will probably need to build and use acdc yourself. The rest of this document explains how to do that.

Building and using the acdc translator

To build the acdc executable you need only an ANSI C compiler. Simply compile and link the relevant C sources – no libraries or special compilation or linking options required.

The acdc translator takes the following command line arguments (in any order):

<sourcefile>
The name or pathname of the main A-code source file; if omitted, it is prompted for. Any include statements are taken to be relative to the directory in which the main source file is located.

-plain abbreviable to -p
Causes the game text data not to be encrypted.

-xref abbreviable to -x
Requests that a cross-reference file of the A-code source be created. For technical reasons (meaning I am being lazy), this file is called game.xrf. It is not sorted and can be processed further with the sortref Perl utility, supplied as a part of the acode package.

-no-warnings abbreviable to -nw
Suppresses warnings about unused symbols in the A-code source.

-quiet abbreviable to -q
Suppresses most of the standard info messages generated by acdc in translating the A-code source.

-debug abbreviable to -d
Causes A-code source to be added as comment lines to the translated C source files. Also adds trace message showing individual A-code code chunks being entered during play. Also causes the DEBUG symbol to be defined in the kernel source.

-help abbreviable to -h
Lists available command line arguments.

By default, the game's text data is preloaded into the executable. These days only very old and/or small machines are unhappy with the size of the resulting executable. However, if the default behaviour is for any reason not the suitable one, there are three further deprecated command line options that can be used.

-file-memory abbreviable to -fm
Requests a separate .dat text data file to be created and to be read in full into the game's memory on startup. Useful only if the OS objects to large executables.

-file-read abbreviable to -fr
Requests a separate .dat text data file to be created and to be accessed by the game by direct file reads as required. Only useful for really small, slow machines.

-file-page [<npage>] abbreviable to -fp
Requests a separate .dat text data file to be created and to be accessed by the game using its own internal paging mechanism. The optional <npage> argument defaults to 32 and specifies the number of 1KB paging buffers. Only useful for really small, slow machines.

Derived ANSI C sources are created in the directory from which acdc is run, except that if a sub-directory called C is found in the directory in which the A-code source is located, the derived sources are placed there.

Adding kernel source files

The A-code kernel consists of source files adv00.c, adv01.h and adv0.h. All three can be found in the A-code source tarball. Copy them alongside the C sources created by acdc, and you will have the complete C source required to build an executable.

Building an executable

Building a simple adventure executable from the derived C sources is simplicity itself: just compile and link the lot together with any ANSI C compiler. The resulting executable will default to using a local browser for its display (except for DOS builds). But it will lack command history and editing in the console mode. If that's good enough for you, fine, but if you hit problems, or want a more sophisticated version, read the guide to building A-code games from intermediate C sources.