developer buildroot - YIO-Remote/documentation GitHub Wiki
Buildroot
The YIO Remote uses a custom Linux OS for the Raspberry Pi Zero board built with Buildroot. See remote-os repository for details.
At the moment Buildroot is only working on Linux. Our attempts to get it running on macOS have been unsuccessful and on Windows we don't have any expertise. Please contact us if you have a working solution.
The easiest way to use Buildroot on any system is with the provided Docker YIO build image. See Docker Build Image for YIO-Remote for more information.
This documentation is about installing and using Buildroot on Linux.
Build Environment Variables
The following optional environment variables control where build artifacts are stored:
Variable | Description |
---|---|
BR2_DL_DIR |
Buildroot download directory. Default: $HOME/buildroot/dl |
BR2_CCACHE_DIR |
Buildroot ccache directory. Default: $HOME/buildroot/ccache |
Variables prefixed with BR2_
are official Buildroot variables. See environment variables in the Buildroot user manual.
Initial Checkout and Toolchain Build
The YIO remote-os project builds the complete SD card image for the RPi Zero device in the remote. Furthermore, an external toolchain can be built with Buildroot for cross compilation in Qt Creator and the command line. See "External toolchain backend" in the Buildroot documentation for more information.
Notes:
- The most up-to-date version is in the master branch.
- Releases are created from the master branch through a version tag.
- All other branches in remote-os are either upcoming pull requests from the core development team, or the "next big feature" we are working on.
Consider them experimental: they might not work and removed or rebased at any time! - The
Makefile
in the root directory is a build helper for commonly used Buildroot make commands.
Checkout project (if not yet done) and build external cross compiler toolchain:
# define root directory for project checkout
SRC_DIR=~/projects/yio
mkdir -p $SRC_DIR
cd $SRC_DIR
git clone https://github.com/YIO-Remote/remote-os.git
cd $SRC_DIR/remote-os
# build external toolchain
make remote-sdk
This will take at least an hour or much longer on a slower system.
A successful build will end with the following messages:
>>> Rendering the SDK relocatable
PER_PACKAGE_DIR=~/projects/yio/remote-os/buildroot/output/per-package ~/projects/yio/remote-os/buildroot/support/scripts/fix-rpath host
PER_PACKAGE_DIR=~/projects/yio/remote-os/buildroot/output/per-package ~/projects/yio/remote-os/buildroot/support/scripts/fix-rpath staging
/usr/bin/install -m 755 ~/projects/yio/remote-os/buildroot/support/misc/relocate-sdk.sh ~/projects/yio/remote-os/buildroot/output/host/relocate-sdk.sh
mkdir -p ~/projects/yio/remote-os/buildroot/output/host/share/buildroot
echo ~/projects/yio/remote-os/buildroot/output/host > ~/projects/yio/remote-os/buildroot/output/host/share/buildroot/sdk-location
>>> Generating SDK tarball
~/projects/yio/remote-os/buildroot/output/host/bin/tar czf "~/projects/yio/remote-os/buildroot/output/images/arm-buildroot-linux-gnueabihf_sdk-buildroot.tar.gz" \
--owner=0 --group=0 --numeric-owner \
--transform='s#^home/mzehnder/projects/yio/remote-os/buildroot/output/host#arm-buildroot-linux-gnueabihf_sdk-buildroot#' \
-C / home/mzehnder/projects/yio/remote-os/buildroot/output/host
make[1]: Leaving directory '~/projects/yio/remote-os/buildroot'
The SDK will be written to: ./buildroot/output/images/arm-buildroot-linux-gnueabihf_sdk-buildroot.tar.gz
Build SD Card Image
cd $SRC_DIR/remote-os
make remote
A successful build will end with the following messages:
Cleaning up partition image files ...
make[1]: Leaving directory '/home/yio/projects/yio/remote-os/buildroot'
cp -f /home/yio/projects/yio/remote-os/buildroot/output/images/yio-* /home/yio/projects/yio/remote-os/release/
# Do not clean when building for one target
Finished building board: remote
Hint: redirect the make
output log into a logfile to easy find an error during building or when using screen
without scrollback capability:
make 2>&1 | tee remote-os_build_$(date +"%Y%m%d_%H%M%S").log
The final SD card image will be written to:
- Buildroot output:
./buildroot/output/images/yio-remote-sdcard-$VERSION.img
Attention:make clean
will remove the Buildroot output folder. - Release folder:
./release/yio-remote-sdcard-$VERSION.img
The $VERSION
information consists of: VersionTag[-CommitCountSinceVersionTag-LastGitHash[-dirty]]
Examples:
yio-remote-sdcard-v1.1.0.img
:- Image relates to version
v1.1.0
, which isgit checkout v1.1.0
- Image relates to version
yio-remote-sdcard-v1.1.0-19-g07e61834.img
:- 19 commits after last release v1.1.0
- last git commit is g07e61834
yio-remote-sdcard-v1.1.0-20-gdbca8b7c-dirty.img
:- 20 commits after last release v1.1.0
- last git commit is gdbca8b7c
- dirty: uncommitted changes in the file system during build
Buildroot Commands
The main makefile wraps the most important Buildroot make commands and takes care of configuration handling and output directories:
Command | Description |
---|---|
make remote |
Update configuration from the board's defconfig and start build. |
make clean |
Deletes all of the generated files, including build files and the generated toolchain! |
make remote-menuconfig |
Shows the configuration menu with the board's defconfig. All changes will be written back to the project configuration. |
make remote-config |
Update configuration from the board's defconfig. |
make help |
Shows all options. |
The project configuration in buildroot-extenal/configs/remote_defconfig
is automatically loaded and saved back with make remote-menuconfig
. Manual make savedefconfig BR2_DEFCONFIG=...
and make defconfig BR2_DEFCONFIG=...
commands are no longer required and automatically taken care of!
Specific Buildroot make commands can still be run in the ./buildroot subdirectory after applying the board configuration.
For example configuring the Linux kernel with make linux-menuconfig
.
Attention: all configuration commands run within the ./buildroot directory will not be persisted to the configuration files stored under ./buildroot-external. This must be done manually!
Write SD Card Image
Use balenaEtcher - available for Linux, macOS and Windows - or your favorite tool.