---
title: How to build Retroboot from source
x-toc-enable: true
...

Retroboot's build system is named `rbmk`, short for `Retroboot Make`, and this
document describes how to use it.
**This document assumes that you are using the Retroboot git repository, which
you can download here:
<https://notabug.org/retroboot/retroboot>**

If you're using a release archive of Retroboot, please refer to the
documentation included with *that* release. It will be an older version of the
document that you're now reading.

To know more about `rbmk`, especially how you can make *changes* to it, please
read this document instead:
[Retroboot maintenance manual](../maintain/)

Git
===

Before you use the build system, please know: the build system itself uses
Git extensively, like when downloading software like coreboot and patching it.

You should make sure to initialize your Git properly, before you begin or else
the build system will not work properly. Do this:

    git config --global user.name "John Doe"
    git config --global user.email johndoe@example.com

Change the name and email address to whatever you want, when doing this.

You may also want to follow more of the steps here:
<https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup>

Python
------

Parts of the build process uses Python 2, but some distros will not
have `python` in PATH for running python.

Check what python version you have, by running `python --version`

It should be 2.x.x

If not, make sure `python2` command works and do this:

    which python2

If not, and `python` is in your PATH, do this:

    which python

Now do this:

    ls -l $(which python)

If it's a symlink, just remove it. If it's not, rename it to `python3` if it's
a python3 executable.

The which command will tell you what path for python. Let's assume it's in `/usr/bin/`

As root, do this:

    cd /usr/bin
    ln -s python2 python

Now then you run `python --version` it should say 2.x.x, assuming you have
python2 installed.

GNU Make
--------

Retroboot now, as of 5 January 2021, includes a `Makefile`. You can still use
the `rbmk` build system directly, or you can use GNU Make. The `Makefile`
simply runs `rbmk` commands.

You must ensure that all build dependencies are installed. If you're running
Ubuntu or similar distribution (Debian, Trisquel, etc) you can do this:

    sudo make install-dependencies-ubuntu

Now, simply build the coreboot images like so:

    make

This single command will build ROM images for *every* board integrated in
Retroboot. If you only wish to build a limited set, you can use `rbmk` directly:

    ./build retroboot roms x200_8mb

You can specify more than one argument:

    ./build retroboot roms x200_8mb x230_7mb x60

ROM images appear under `bin/` in the build system.

For other commands, simply read the `Makefile` in your favourite text editor.
The `Makefile` is simple, because it merely runs `rbmk` commands, so it's very
easy to know what commands are available by simply reading it.

Standard `clean` command available (cleans all modules except `crossgcc`):

    make clean

To clean your `crossgcc` builds:

    make crossgcc-clean

Do not run this command except in emergency, like if you're making changes to
`rbmk` and screwed something up. This deletes *everything*, except the
core build system and scripts (in other words, what you would normally find
in the Git repository):

    make nuke

To build the *website* (markdown to HTML conversion handled by pandoc):

    make docs

Point your web server to the `www` directory as document root. The compiled
website will be visible to you. Please note: the static site generator
currently relies on a much older version of Pandoc, so it needs to be
modified for newer Pandoc versions.

To clean the docs:

    make docs-clean

To build release archives:

    make release

It is advisible to add a `tag` before generating release archives. The tag
should be in the format of `YYYYMMDD` for stable releases, with `rc` added
for release candidate or `beta` added for *experimental* releases.
For example, a beta release on January 1st, 2023 would be `20230101beta`. This
is the version numbering scheme that Retroboot uses.

Building without using GNU Make
===============================

The `Makefile` is included just for *compatibility*, so that someone who
instictively types `make` will get a result.

Actual development/testing is always done using `rbmk` directly, and this
includes when building from source. Here are some instructions to get you
started:

First, install build dependencies
---------------------------------

Retroboot includes a script that automatically installs apt-get dependencies
in Ubuntu 20.04. It may work in other similar GNU+Linux distributions.
    
    sudo ./build dependencies ubuntu2004

Technically, any GNU+Linux distribution can be used to build Retroboot.
However, you will have to write your own script for installing build
dependencies. 

As of January 5th, 2021, Retroboot's build system (`rbmk`, short for `Retroboot
Make`) will automatically run all necessary commands; for example
`./build payload grub` will automatically run `./build module grub` if the
required utilities for GRUB are not built, to produce payloads.

As a result, you can now (after installing the correct build dependencies) run
just a single command, from a fresh Git clone, to build the ROM images:

    ./build retroboot roms

or even just build specific ROM images, e.g.:

    ./build retroboot roms x60

Previous steps will be performed automatically. However, you can *still* run
individual parts of the build system manually, if you choose.

Therefore, if you only want to build ROM images, just do the above. Otherwise,
please continue reading!

Second, download all of the required software components
--------------------------------------------------------

If you didn't simply run `./build retroboot roms` (with or without extra
arguments), you can still perform the rest of the build process manually. Read
on!

It's as simple as that:

    ./download all

The above command downloads all modules defined in the Retroboot build system.
However, you can download modules individually.

This command shows you the list of available modules:

    ./download list

Example of downloading an individual module:

    ./download coreboot

    ./download flashrom

Third, build all of the modules:
--------------------------------

Building a module means that it needs to have already been downloaded.
Currently, the build system does not automatically do pre-requisite steps
such as this, so you must verify this yourself.

Again, very simple:

    ./build module all

This builds every module defined in the Retroboot build system, but you can
build modules individually.

The following command lists available modules:

    ./build module list

Example of building specific modules:

    ./build module grub

    ./build module flashrom

Commands are available to *clean* a module, which basically runs make-clean.
You can list these commands:

    ./build clean list

Clean all modules like so:

    ./build clean all

Example of cleaning specific modules:

    ./build clean grub

    ./build clean cbutils

Fourth, build all of the payloads:
---------------------------------

Very straight forward:

    ./build payload all

You can list available payloads like so:

    ./build payload list

Example of building specific payloads:

    ./build payload grub

    ./build payload seabios

The build-payload command is is a prerequsite for building ROM images.

Fifth, build the ROMs!
----------------------

With GRUB (SeaBIOS selectable from menu):

    ./build roms withgrub

With just SeaBIOS:

    ./build roms withseabios

NOTE: each of these commands will build *every* board that has configs for
the given payload as specified by the command. You can add a board name to
the end of the command. These board names can be determined per the directory
name of each board under `resources/coreboot/`

For example, if you only wanted to build SeaBIOS ROMs for X230 with 4MiB CBFS:

    ./build roms withseabios x230_4mb

For example, if you only wanted to build GRUB+SeaBIOS ROMs for X230 with 4MiB
CBFS:

    ./build roms withgrub x230_4mb

You *can* list available commands using `./build roms list` and you can run
`./build roms all` but this is not recommended. You should individually
specify the payload in a separate command.

That's it!

If all went well, ROM images should be available to you under bin/

Build the documentation and website
-----------------------------------

The entire website, hosted on retroboot.org, is written in Markdown (for use
with Pandoc). A separate build system is included in Retroboot, which uses
a *static site generator* to:

- Compile all Markdown files (file name ending in .md) into HTML
- Compile the news/blog section of the website

The website/docs has its own build system, not integrated into the main
Retroboot build system. Go into the www/ directory (which has a symlink inside
to the docs/ directory) and type `make`. It uses pandoc to compile the website.

NOTE: it currently relies on a much older version of Pandoc, around version 1.17
or so and it needs to be updated.

You can run `make clean` in www/ to un-build the website if you want to.
