Saturday, March 25, 2017

The ADOM build system


this week I'll cover the ADOM build system - something I've started working on shortly after I got more involved with ADOM development.

As you know we provide ADOM for many different operating systems (e.g. Windows, macOS, Linux, NetBSD, OpenBSD, FreeBSD, Raspbian and AmigaOS). It would take (too) much time to manually build an ADOM executable for each operating system, so we decided to fully automate this task.

What were the requirements?

We wanted to be able to build all executables on a single computer. This would make it possible to build a new ADOM release everywhere without having to carry around a lot of hardware. We also wanted it to be fully automated without having to do manual steps.

What is the ADOM build system?

The ADOM build system (that's what we call it) is a combination of virtual machines and shell scripts that automates the creation of all the ADOM executables/packages.

We use 14 virtual machines (one for each operating system) and utilize VirtualBox for virtualization. 

How does the build system work?

Since ADOM is programmed in C we use makefiles to build the ADOM executable.
  1. everything starts with a single "make" command in the shell
  2. this make command then calls other shell scripts that each create a single executable
  3. these shell scripts execute the following steps (4-8)
  4. start the virtual machine
  5. get the specified revision of source code from the repository
  6. execute another makefile that compiles the source code
  7. download the resulting executable from the virtual machine to the current computer
  8. stop the virtual machine
We can build all or a single executable depending on the parameters. Since the Git migration we can also specify the revision(s) of source codes for each repository (ADOM source code, NotEye source code and Steam SDK), so we can build every version we once built again without much hassle.

How long does it take?

To speed up the creation process we start 4 virtual machines in parallel. This reduces the time required to build all 28 executables/packages to around 20 minutes.

The executables for AmigaOS and Raspbian are cross compiled to make the compilation faster (it takes around 15 minutes to compile ADOM on a RaspberryPi 1).

What are the benefits?

Automatic building of executables is less error prone than building manually. Since we can build all executables on a single computer we don't need a "server farm" with lots of different computers.

What are the drawbacks?

Keeping all the virtual machines up to date can be a time consuming task.

What about continuous integration?

In theory we could use the build system for continuous integration. But since automated testing of ADOM is not really possible (it's not a technical problem but caused by the randomness of the game) we don't use it that way.

Will you add other operating systems?

If the demand is high enough we might consider adding more operating systems.

Until next time!


  1. and what about a version who can work on Android?

    it can be wonderful to found a way to play on our smart-phone/tablet.

    1. The problem with ADOM and mobile devices is the high number of keyboard shortcuts (> 80) you need to play the game. We've developed a prototype for the iPad (ASCII mode only) a long time ago, so it basically works, but we are not quite satisfied with the gaming experience.

    2. @JT, You should definitely look into existing implementations. So far angband and nethack were ported at least. As a best one for UI I would recommend looking into Pixel Dungeon and it's forks. It's far from ADOM in many aspects but it still have many nice details.
      Basically you're on the way, you got a UI which must be mostly operable with a mouse, you got tabs for some screens which are perfect for swipes, got action menus which cover at least some shortcuts and you do have RFEs to enrich all this. I hope to get early access for ADOM on Android in several years. I would surely donate it if there was another crowd funding! ;)

  2. What's the operating system (the one running virtualbox and all the VMs)? Is it a Mac because of the OS X VM, or something else?

    1. Yes, it's a Macbook Pro. We also use an additional OSX virtual machine with an older Xcode version to build for PPC Macs.

  3. How do you trigger windows builds in a VM through sh scripts? Would you share a sample with us unless it's secret? :)

    1. Every VM we use has a SSH server installed. This way we can log into each VM with the ssh command and execute scripts "remotely" in the VM. That's the basic idea, I can describe this in more detail in another blog post.

    2. Got the basic idea but would surely happy to read more in the next blog post!
      For me x-platform way is a Java-like or any kind of a scripting language which can't perform as good as C / C++ in a lot of cases

  4. I just wanted to say that to have a 'real' full screen ASCII option I'm using the DOS version of ADOM via DosBox. Please do not remove that in future versions ;)

  5. Isn't SCons a better option than Makefiles ?

  6. I wanted to mention that I play the DOS build via MagicDosbox on android. This app allows me to play at full speed, and allows you to make your own custom widgets and keyboard. I can play the game on my tablet without any external hardware. So please keep the DOS build!!