3 Compiling

3.1 Configuration

FreeWPC can be compiled in many different ways with lots of optional features. You cannot just type make at the top of the directory tree without first specifying what you want to build. This is done by creating a file named .config. The file config.example is provided as an example of the kinds of things that can be tuned.

.config is written in standard Makefile syntax. (The top-level Makefile includes this file.) You set various options by writing variable assignments, such as:

     MACHINE := wcs

You must specify at least a MACHINE. All other configuration variables are optional; suitable defaults will be used.

Here is a list of the most important build options.

MACHINE

Names the machine that you want to build for. This corresponds to the name of the subdirectory in the machine directory that has the machine specific files.

MAKEFLAGS

This is a feature of the make utility, not FreeWPC per se, but it can be useful: if you want to pass special flags to make, include them here. In particular, the -j option can be used to run multiple commands in parallel, which can speed up the build significantly.

FREEWPC_DEBUGGER

Set to y if you want to include debug messages in the build.

CONFIG_BPT

Set to y if you want to enable the breakpoint module.

GCC_VERSION

Used only when building for the 6809 target, this lets you specify the version of the GCC6809 compiler.

EXTRA_CFLAGS

Used to pass arbitrary options to the C compiler. If you add special logic to the code under an #ifdef, you can enable those flags by including them in EXTRA_CFLAGS.

DEBUG_COMPILER

Set to y if you are debugging the 6809 compiler. This causes many temporary files to be saved for later analysis.

SAVE_ASM

Set to y if you just want to see the assembly language code that GCC6809 generates. This is similar to DEBUG_COMPILER but produces much less GCC internals. If you understand 6809 assembly language, this can be useful.

NATIVE

Set to y to enable native mode, or simulation.

CONFIG_UI

In native mode, this option controls the user-interface that is used. The default is curses, which works within most internals and is fairly easy to understand. Use console for a much more raw, printf style output. gtk support is in progress.

PINMAME

Set to the pathname where your PinMAME executable is, if you plan to use that for testing.

EXTRA_PINMAME_FLAGS

Set to flags that you want to pass to PinMAME when testing; for example, sound driver options or DMD color schemes.

TARGET_ROMPATH

Set to the directory where PinMAME ROM files are kept.

3.2 Building

After configuring, type make. This will build a ROM and optionally install it into your PinMAME ROM directory if you have said where that is.

The exact commands are not printed, but you can force the details to be shown by setting the environment variable Q to the empty string, like this:

     make Q=""

The build procedure is complicated, but it can be broken down into the following steps:

1. Create Blank File

   If the size of the ROM is larger than the number of pages that the compiler generates, then the final ROM image must be padded with blank sections. The dd command is used to generate a file named blankxxx.bin, where xxx is the size of the file in kilobytes (KB). This file is later concatenated with the linker output to produce a final ROM of the required size.

2. Create Linker Command Files

   The linker is invoked several times, once per page or bank of ROM. Different options are passed each time to place the correct object files into that section, and to resolve references correctly. All of these options are written to linker command files, which have the .lnk extension and are placed in the build directory. They are lists of command-line options to the linker, but placed into a file because of the huge number of them.

3. Setting the Machine Symbolic Links

   The symbol link mach is set to point to the correct machine code directory, based on the value of the MACHINE make variable. Likewise, include/mach is pointed to the machine includes.

4. Generating Defines

   Some #defines are generated automatically by scanning the code for their uses. These include files begin with the prefix gendefine and are created by a script also named gendefine in the tools directory.

   At present this is only used to autogenerate the task group IDs.

5. Generating Callsets

   Callsets are a mechanism for implementing a simple event subscription/invocation mechanism that is fully described at compile-time. Event handling code is emitted in a C file named callset.c.

6. Compiling and Assembling Source Code

   Source code is compiled using the GCC6809 compiler. The compiler generates assembler code with the .s extension. These files are then assembled using the asxxxx asembler tools into object files with the .o extension.

7. Compiling Page Headers

   Because the linker requires each section to contain at least one object file, a dummy file is assembly per section to ensure that this doesn't happen. The page header is 1 byte long and contains the page number.

8. Linking Pages

   The aslink utility is used to create one S-record file, with the .s19 extension, for each page of ROM.

9. Converting Pages to Binary

   The tools/srec2bin utility included with FreeWPC is run to convert the S-records into raw binary files.

10. Concatenating Pages

    The binary files are concatenated, along with any blank files, to form the final ROM image.

3.3 Build Results

If successful, build/var.rom will contain the ready-to-burn ROM image. var is a string composed of the machine's short name and the version number.

Warnings and errors during the build are display on the console as they occur; they are also log to a file named err.

In native mode, instead of a ROM, a file named freewpc_var is generated.