10 KiB
| title | x-toc-enable |
|---|---|
| Build from source | true |
Any sensible Linux distribution will do. Canoeboot's build system is regularly testing on all the major distros. Please do report bugs if you encounter issues.
Host CPU
At least an Intel Core 2 Duo, though we recommend much faster CPUs if building entire release archives, e.g. quad-core Haswell CPU or better.
NOTE: x86 boards require an x86_64 host CPU with appropriate host toolchains and libraries. We don't yet cross-compile x86 payloads.
NOTE2: ARM64 mainboards are cross compiled, so you can build for AArch64 machines quite easily, from x86 or ARM64 machines.
NOTE3: 32-bit x86 (i686) machines can be used to compile Canoeboot, but MemTest86+ is only compiled for 64-bit, and not cross compiled, so builds are disabled when cbmk detects a 32-bit host CPU.
Memory
At least 2GB per CPU core, ideally 4GB; for example, 16GB RAM is recommended if you're compiling an a quad-core CPU.
NOTE: XBMK_THREADS environmental variable defaults to 1 if unset. This sets
the number of build threads, which you should match to the number of cores.
For example, when you're building on a quad-core, do this prior to building:
export XBMK_THREADS=4
Disk space
About 20GB bare minimum, if only compiling for 1 board. The sources take up a lot of space. However, Canoeboot is always expanding as it's developed.
At least 50GB of free disk space is therefor recommended.
We actually recommend 100GB, because Canoeboot will also have a Linux distro in flash on a future release. On our testing, disk I/O does not seem to be a major bottleneck, so any HDD or SSD will do, but we obviously recommend a fast NVMe (PCI-E) SSD if you can.
Multi-threaded builds
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.
Environmental variables
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).
Sources
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.
Git
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
Python
You should ensure that the python command runs python 3, on your system.
Python2 is unused by cbmk or anything that it pulls down as modules.
If building on Debian/Ubuntu based systems, you can achieve that via:
sudo apt install python-is-python3
On Fedora, you can use the following
sudo dnf install python-unversioned-command
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:
Zero..st, check time/date
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.
First, install build dependencies
Check config/dependencies/ for list of supported distros.
Canoeboot includes a script that automatically installs build dependencies according to the selected GNU+Linux distro.
For example:
./mk dependencies ubuntu
or
./mk dependencies debian
or
./mk dependencies fedora41
or
./mk dependencies arch
NOTE: For versioned files, such as fedora41, typically other versions will
be available too, e.g. fedora38. Make sure to check config/dependencies/,
so that you know whether or not a file is available for your distro.
NOTE: In case of Ubuntu 20.04 LTS or derived distros for that specific release, use the dedicated configuration file (the Trisquel 11 config symlinks to this):
./mk dependencies ubuntu2004
Technically, any GNU+Linux distribution can be used to build canoeboot. However, you will have to write your own script for installing build dependencies.
Debian Trixie/Sid
Debian Trixie, the testing release as of 3 January 2025, and Debian Sid,
provide gnat and gcc as you expect, but gnat resolves to gnat-13 and
installs gcc-13 as a dependency, while gcc resolves to gcc-14 and other
toolchain components correspond to this version.
The GCC/GNAT versions need to match during build time, so Canoeboot's build
system hacks the PATH environmental variable, setting up symlinks, matching
GNAT to GCC or GNAT to GCC. When you run ./mk dependencies debian, you get
GNAT 13 and GCC 14. This seems to make most boards compile; in our testing, the
KGPE-D16 board failed to compile in this configuration. This PATH hack is only
done for compiling the coreboot crossgcc toolchain, and nothing else; after that,
coreboot's toolchain is used.
GNAT is used by coreboot, because some of the Intel graphics devices are
initialised natively, with code written in Ada spark (called libgfxinit).
When updating from Debian stable to Debian Trixie(testing) or Sid, you should
also check for orphaned packages, using aptitude search '~o'. Do this,
removing what was leftover from the old release, and make sure to re-run the
Debian dependencies script, but do it like this:
./mk dependencies debian --reinstall
For better reliability, you should, after running the dependencies script,
remove gnat and install gnat-14 instead, which is available on this day
of 3 December 2025, but currently marked experimental. When you install
GNAT 14, GNAT 13 is removed but gnat (in PATH) still won't resolve to
anything. Canoeboot still accomodates this, detecting and matching the GCC
and GNAT versions, which would in this instance match version 14 between them,
so that gnat and gcc are both in PATH at build time, resolving to v14.x.
When we tested with this configuration, the KGPE-D16 images also compiled.
NOTE: Ubuntu 24.10 also has the issue described above. Some other distros may also have it, if they're based on Debian Testing/Sid or Ubuntu 24.10.
MIPS cross compiler
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.
Arch-based systems have a mipsel cross compiler available from AUR, and most Debian-based systems have a mipsel cross compiler in apt; for these, the normal dependencies installation command will provide them. We know Void Linux and Fedora don't have a MIPS compiler, for instance.
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.
Next, build ROM images
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
or even just build specific ROM images, e.g.:
./mk -b coreboot x60
or get a list of supported build targets:
./mk -b coreboot list
Or maybe just build payloads?
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.
Want to modify Canoeboot?
Check the cbmk maintenance manual for guidance. You may for example want to modify a config, e.g.:
./mk -m coreboot x200_8mb
Or perhaps add a new board! The maintenance manual will teach you how the Canoeboot build system (cbmk) works!
Post-compilation steps
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.