Creating ANSI C sources from the A-code source

(A-code acdc version 12.91)

Contents

• A-code source
• A-code framework
• Building the acdc translator
• Using the acdc translator
• Adding kernel source files
• Building an executable

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.91.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, OSX/MacOS or Microsoft's LSW, the simplest thing to do is to use the advbld bash 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 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:

cc *.c -o acdc

Using the acdc translator

By default, any resulting C sources (adv.c and adv.h) are generated alongside the A-code source file being translated, unless the sub-directory C (that's capital C!) us found there, in which case that's where the sources go.

The acdc translator needs no command line arguments. If some are supplied, they can be given in any order. If the game source-file is omitted, it is prompted for. All other command line listed below are optional – default behaviour covers all usual cases.

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

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 not complicated: just compile and link the lot together with any ANSI C compiler, adding -DNO_READLINE to the command line. 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 you cannot use a browser or prefer not to, you can also run such default build from a console window by adding -C (or /C on DOS and Windows) to the invocation command line.

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.