retroboot/docs/git/index.md

---

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

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.