Building Revs from the source

If you would like to build a fully working version of Revs on a modern computer, from the exact same source code as on this site, then you will find everything you need in the accompanying GitHub repository, including full instructions. Here we take a look at how the source files are structured and how the build process works.

The Revs build pipeline
-----------------------

The modern build process uses a multi-stage pipeline, using the BeebAsm assembler and Python.

There are five main folders in each repository, which reflect the progress of the build process (the links will take you to the relevant folders on GitHub):

• 1-source-files contains all the different source files, such as the main assembler source files, image binaries, boot files and so on.
• 2-build-files contains build-related scripts, such as the checksum and crc32 verification scripts.
• 3-assembled-output contains the output from the assembly process, when the source files are assembled and the results processed by the build files.
• 4-reference-binaries contains the correct binaries for the released game, so we can verify that our assembled output matches the reference.
• 5-compiled-game-discs contains the final output of the build process: an SSD disc image that contains the compiled game and which can be run on real hardware or in an emulator.

These folders are used in the multi-stage build process in the following manner: the 1-source-files are assembled, then checksummed by the 2-build-files to create the 3-assembled-output, which is optionally verified against the 4-reference-binaries before being compiled into the final 5-compiled-game-discs.

This build process is configured via the project's Makefile. The specific build steps are as follows (the links will take you to the relevant source files on GitHub):

1. Assemble the loader with revs-loader.asm
2. Assemble the Silverstone track data with revs-silverstone.asm
3. Assemble the main game with revs-source.asm
4. Calculate checksums with revs-checksum.py
5. Verify the assembled output with crc32.py
6. Assemble a bootable disc image with revs-disc.asm

Let's take a look at each of the pipeline stages in more detail.

1. Assemble the loader with revs-loader.asm
-------------------------------------------

BeebAsm loads revs-loader.asm and creates the following file:

• Revs1.bin

revs-loader.asm contains the source code for the game loader.

2. Assemble the main game with revs-silverstone.asm
---------------------------------------------------

BeebAsm loads revs-silverstone.asm and creates the following file:

• Silvers.bin

revs-silverstone.asm contains the track data for Silverstone, the track that came with the original 1985 version of Revs.

3. Assemble the main game with revs-source.asm
----------------------------------------------

BeebAsm loads revs-source.asm and creates the following file:

• Revs.bin

revs-source.asm contains the main source code for Revs.

4. Calculate checksums with revs-checksum.py
--------------------------------------------

Next, the pipeline runs the Python script revs-checksum.py, which reads all the track data files:

• Silvers.bin

and inserts correct checksums into the four bytes at trackChecksum. The checksum algorithm is quite simple:

• trackChecksum+0 counts the number of data bytes ending in %00
• trackChecksum+1 counts the number of data bytes ending in %01
• trackChecksum+2 counts the number of data bytes ending in %10
• trackChecksum+3 counts the number of data bytes ending in %11

Without the correct checksum values, the game will hang.

5. Verify the assembled output with crc32.py
--------------------------------------------

By default the crc32.py script is run on the results, which compares the assembled output with the binaries from the original build process. This enables us to confirm that our output is correct.

The verification output for the Acornsoft variant is as follows:

  Results for release: acornsoft
  [--originals--]  [---output----]
  Checksum   Size  Checksum   Size  Match  Filename
  -----------------------------------------------------------
  b367ef0f   2000  b367ef0f   2000   Yes   BrandsHatch.bin
  18d57479   2000  18d57479   2000   Yes   DoningtonPark.bin
  0f2aa17c   2000  0f2aa17c   2000   Yes   OultonPark.bin
  e22a0a93  24064  e22a0a93  24064   Yes   Revs.bin
  d37f9cba   1455  d37f9cba   1455   Yes   Revs1.bin
  0b090b15   1849  0b090b15   1849   Yes   Silverstone.bin
  9dcd008c   2000  9dcd008c   2000   Yes   Snetterton.bin
  -             -  75798a13   2000    -    Nurburgring.bin

In this case the assembled binaries match the original binaries, so our build process has worked.

6. Assemble a bootable disc image with revs-disc.asm
----------------------------------------------------

Finally, BeebAsm loads revs-disc.asm, which reads the following files:

• boot-files/$.!BOOT.bin
• basic-programs/$.REVS.bin
• Revs.bin
• Revs1.bin
• Silvers.bin

and creates the following:

• revs-acornsoft.ssd

This script builds the final disc image, to match the released version of the game. Note that the name of the disc image depends on the release that's being built - the name shown above is the default build, which builds the Acornsoft version that doesn't have steering assist.

The disc image can be loaded into an emulator, or into a real BBC Micro using a device like a Gotek.