How to build osboot from source

Edit this page -- Back to previous index

osboot’s build system is named osbmk, short for osboot Make, and this document describes how to use it. This document assumes that you are using the osboot git repository, which you can download here: https://notabug.org/osboot/osbmk

If you’re using a release archive of osboot, 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 osbmk, especially how you can make changes to it, please read this document instead: osboot 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

Python 2 and 3 are used by different parts of the build system, not directly but because certain projects osboot depends upon uses it.

You should have this configuration on your OS:

python

python2

python3

Running python should give you python 3.x.

Running python2 should give you python 2.x.

Running python3 should give you python 3.x.

Therefore, you should install both python2 and python3 in your distro.

GNU Make

osboot now, as of 5 January 2021, includes a Makefile. You can still use the osbmk build system directly, or you can use GNU Make. The Makefile simply runs osbmk 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 osboot. If you only wish to build a limited set, you can use osbmk directly:

./build boot roms x200_8mb

You can specify more than one argument:

./build boot 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 osbmk 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 osbmk 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 osboot 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 osbmk directly, and this includes when building from source. Here are some instructions to get you started:

First, install build dependencies

osboot 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 osboot. However, you will have to write your own script for installing build dependencies.

As of January 5th, 2021, osboot’s build system (osbmk, short for osboot 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 boot roms

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

./build boot 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 boot 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 osboot 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 osboot 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 osboot.org, is written in Markdown (for use with Pandoc). A separate build system is included in osboot, which uses a static site generator to:

The website/docs has its own build system, not integrated into the main osboot 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.

Edit this pageLicenseTemplateAuthorsDonateBuy preinstalled

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License Version 1.3 or any later version published by the Free Software Foundation with no Invariant Sections, no Front Cover Texts, and no Back Cover Texts. A copy of this license is found in /docs/fdl-1.3.html