Skip to content

building.md

Latest commit

 

History

History
182 lines (133 loc) · 5.81 KB

building.md

File metadata and controls

182 lines (133 loc) · 5.81 KB

Building a SeedSigner SD card image

Assemble the SeedSigner OS along with the SeedSigner application code into an image file that can be flashed to an SD card and run in your SeedSigner.


🔥🔥🔥🛠 Quickstart: SeedSigner Reproducible Build! 🛠🔥🔥🔥

Install Dependencies

Clone the SeedSigner OS repo

In a terminal window:

# Copy the SeedSigner OS repo to your local machine
git clone --recursive https://github.com/SeedSigner/seedsigner-os.git

# Move into the repo directory
cd seedsigner-os

Configure and begin the build

macOS / Linux instructions:

Configure environment variables

Force Docker to build on a container meant to run on amd64 in order to get an identical result, even if your actual cpu is different:

export DOCKER_DEFAULT_PLATFORM=linux/amd64

Select your board type from the Board configs list below.

If you're unsure, most people should specify pi0.

export BOARD_TYPE=pi0

Set your target release version of the SeedSigner code (see: https://github.com/SeedSigner/seedsigner/releases):

# e.g. 0.8.0, 0.7.0, etc
export RELEASE_TAG=x.y.z

Checkout the branch associated to the target release version of the SeedSigner code (e.g. 0.8.5, 0.8.0, etc)

git checkout $RELEASE_TAG

Initialize and update submodules (buildroot) from the seedsigner-os repo

git submodule init
git submodule update

Start the build!

SS_ARGS="--$BOARD_TYPE --app-branch=$RELEASE_TAG" docker compose up --force-recreate --build

Windows PowerShell instructions:

*Note: We recommend running these steps in WSL2 (Windows Subsystem for Linux) instead of PowerShell so that you can just follow the macOS / Linux steps above.*

Windows prerequisites (PowerShell)

These must be set before cloning the repo. If you already cloned, reclone after setting these.

  1. Enable Developer Mode in Windows (Settings → System → For Developers → Developer Mode) so Git can create symlinks.

  2. Configure Git to preserve LF line endings and symlinks:

git config --global core.autocrlf false
git config --global core.eol lf
git config --global core.symlinks true

Optional: verify the GCC hash file is a symlink after submodules are initialized:

Get-Item opt/buildroot/package/gcc/gcc-initial/gcc-initial.hash | Select-Object LinkType,Target

Configure environment variables

Force Docker to build on a container meant to run on amd64 in order to get an identical result, even if your actual cpu is different:

$env:DOCKER_DEFAULT_PLATFORM = 'linux/amd64'

Select your board type from the Board configs list below.

If you're unsure, most people should specify pi0.

$env:BOARD_TYPE = 'pi0'

Set your target release version of the SeedSigner code (see: https://github.com/SeedSigner/seedsigner/releases):

# e.g. "0.8.0", "0.7.0", etc
$env:RELEASE_TAG = "x.y.z"

Checkout the branch associated to the target release version of the SeedSigner code (e.g. 0.8.5, 0.8.0, etc)

git checkout $env:RELEASE_TAG

Initialize and update submodules (buildroot) from the seedsigner-os repo

git submodule init
git submodule update

Start the build!

$env:SS_ARGS = "--$env:BOARD_TYPE --app-branch=$env:RELEASE_TAG"
docker compose up --force-recreate --build


Building can take 25min to 2.5hrs+ depending on your cpu and will require 20-30 GB of disk space.

Build Results

When the build completes you'll see:

seedsigner-os-build-images-1  | /opt/buildroot
seedsigner-os-build-images-1  | {image hash}  /opt/../images/seedsigner_os.{RELEASE_TAG}.{BOARD_TYPE}.img
seedsigner-os-build-images-1 exited with code 0

The second line above will show the SHA256 hash of the image file that was built. This hash should match the hash of the release image published on the main github repo for the chosen RELEASE_TAG + BOARD_TYPE combo. If the hashes match, then you have successfully confirmed the reproducible build!

Windows (PowerShell) note: Even with LF line endings and symlinks enabled, some Windows builds may still produce a different image hash than the published release. WSL2 remains the recommended path for reproducible builds.

The completed image file will be in the images subdirectory.

cd images
ls -l

total 26628
-rw-r--r-- 1 root root       97 Sep 11 02:09 README.md
-rw-r--r-- 1 root root 27262976 Sep 11 18:49 seedsigner_os.{RELEASE_TAG}.{BOARD_TYPE}.img

That image can be burned to an SD card and run in your SeedSigner.



Board configs

Board Image Name Build Script Option
Raspberry Pi Zero seedsigner_os.<tag>.pi0.img --pi0
Raspberry Pi Zero W seedsigner_os.<tag>.pi0.img --pi0
Raspberry Pi 2 Model B seedsigner_os.<tag>.pi2.img --pi2
Raspberry Pi Zero 2 W seedsigner_os.<tag>.pi02w.img --pi02w
Raspberry Pi 3 Model B seedsigner_os.<tag>.pi02w.img --pi02w
Raspberry Pi 4 Model B seedsigner_os.<tag>.pi4.img --pi4
Build all targets (all of the above) --all