Compile Canoeboot from source

English | українська

Return to previous index

If you need to build Canoeboot from source, this guide is for you.

Canoeboot’s build system is named cbmk, short for CanoeBoot MaKe, and this document describes how to use it. With this guide, you can know how to compile canoeboot from the available source code.

The following document describes how cbmk works, and how you can make changes to it: canoeboot maintenance manual

Do not run the build system on a eCryptfs file system, because it has very short file name limits and Canoeboot’s build system deals with very long file names.

You must ensure that you have the correct operating system, CPU, RAM, disk space and so on.

System requirements are documented in the cbmk maintenance manual.

Canoeboot’s build system defaults to a single build thread, but you can change it by doing e.g.

export XBMK_THREADS=4

This would make cbmk run on 4 threads.

More specifically: when compiling source trees via script/trees, -jTHREADS is passed, where THREADS is the number of threads. This is also set when running xz commands for compression, using the -t option.

Please read about environmental variables in the build instructions, before running cbmk. You should set your variables accordingly, though you do not technically need to; some of them may be useful, e.g. XBMK_THREADS (sets the number of build threads).

This version, if hosted live on canoeboot.org, assumes that you are using the cbmk git repository, which you can download using the instructions on the code review page.

Canoeboot’s build system uses Git, extensively. You should perform the steps below, even if you’re using a release archive.

Before you use the build system, please know: the build system itself uses Git extensively, 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

How to compile Canoeboot

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

Make sure date/hwclock report the correct time and date on your system, because parts of the build process download from HTTPS servers and wrong time or date can cause connections to be dropped during negotiation.

Check config/dependencies/ for list of supported distros.

Some examples (run them as root, use e.g. sudo, doas):

./mk dependencies parabola

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

Canoeboot has support for the Sony PlayStation (PS1/PSX), based on the PCSX-Redux Open BIOS. If you’re doing a full release build, and/or specifically building the PSX BIOS, you need a MIPS cross compiler.

If your distro doesn’t have the MIPS compiler available, the PlayStation page provides instructions for manual installation; please do this in addition to the normal dependencies.

Canoeboot MaKe (cbmk) automatically runs all necessary commands; for example, ./mk -b coreboot will automatically build the required payloads if not already compiled.

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

./mk -b coreboot

To get a list of targets, do:

./mk -b coreboot list

Then from the target list, you can pick one, for example:

./mk -b coreboot lenovo_thinkpad_x60_2mb_bios

If you wish to build payloads, you can also do that. For example:

./mk -b grub

./mk -b seabios

./mk -b u-boot

Previous steps will be performed automatically. However, you can still run individual parts of the build system manually, if you choose. This may be beneficial when you’re making changes, and you wish to test a specific part of cbmk.

Check the cbmk maintenance manual for guidance. You may for example want to modify a config, e.g.:

./mk -m coreboot lenovo_thinkpad_x200_8mb_bios

Or perhaps add a new board! The maintenance manual will teach you how the Canoeboot build system (cbmk) works!

So you compiled your Canoeboot image? Congratulations!

Before you flash, please make sure that you dumped two copies of the original firmware just in case (verifying the hashes of each dump, to ensure that they match), using the -r option in flashprog.

NOTE: Canoeboot standardises on flashprog now, as of 3 May 2024, which is a fork of flashrom.

SPDX-License-Identifier: GFDL-1.3-or-later

Markdown file for this page: https://canoeboot.org/docs/build/index.md

Site map

This HTML page was generated by the Canoeboot Static Site Generator.