3. Building Debian Images

3.1. Introduction

Building a Debian Image requires:

  1. Generating a chroot environment for the target architecture (Arm), if the host environment is on x86.

  2. Installing all the necessary packages

  3. Customizing configuration scripts if needed

  4. Building Bootloader

  5. Flashing the generated RootFS and Boot binaries to SD Card

There are several opensource tools available for generating the RootFS in a chroot environment. Such as debootstrap (now deprecated), mmdebstrap (complex), bdebstrap (simple wrapper on top of mmdebstrap).

ti-bdebstrap is a set of scripts that builds upon the bdebstrap tool to create custom Debian images for TI platforms. This includes creating the bdebstrap chroot environment itself, installing essential and useful TI and non-TI packages, setting up the configuations, Building the U-Boot etc.

In other words, ti-bdebstrap offers users an easy way to create a full-fledged Debian image for supported TI platforms, using a single command. Once the image is built, the user can directly flash it onto a SD card.

TI currently supports building Debian Bookworm Images for AM62Px, AM62x and AM64x platforms.

3.2. Usage

3.2.1. Get Scripts

The scripts are hosted at https://github.com/TexasInstruments/ti-bdebstrap

To clone the repository, run:

git clone https://github.com/TexasInstruments/ti-bdebstrap.git

3.2.2. Repository Structure

ti-bdebstrap
├── build.sh
├── builds.toml
├── configs
│   ├── bdebstrap_configs
│   │   ├── bookworm
│   │   │   ├── bookworm-<machine>.yaml
│   │   │   └── bookworm-rt-<machine>.yaml
│   │   └── trixie
│   │       ├── trixie-<machine>.yaml
│   │       └── trixie-rt-<machine>.yaml
│   ├── bsp_sources.toml
│   └── machines --> Machine configurations for each BSP version
│       ├── 09.02.00.010.toml
│       └── 10.00.05.toml
├── create-sdcard.sh
├── create-wic.sh
├── LICENSE
├── README.md
├── scripts
│   ├── build_bsp.sh
│   ├── build_distro.sh
│   ├── common.sh
│   └── setup.sh
└── target --> Custom files to deploy in target.

build.sh: the “main” script that the user should run to generate Debian images.

configs/: contains details, configuration options and values for machines, bsp_sources and distro-variants (see below for details).

scripts/: contains helper scripts for build.sh.

target/: contains files for target configs, like weston.service for the weston target.

builds.toml: contains list of all valid builds along with their definitions (see below for details).

3.2.3. Build Configurations

A build config represents an image with certain values for the machine, rt_linux and distro_codename parameters.

The builds.toml file contains a list of all valid builds in the builds[] list. Each build is then defined underneath.

Values of machine and distro_codename must be defined in configs/machines.toml, configs/bdebstrap_configs/<distro>/<distro>-<machine>.yaml and configs/bsp_sources.toml files. If any of these is missing, the build will fail.

So long as you conform to the rule above, you may also define your own builds.

3.2.4. Building Images

All valid builds are listed in the builds.toml file. To build an image, one of these must be chosen and supplied to the build.sh command. build.sh commences the build process. The images are finally stored in the build/ directory. Each build also produces a log file inside log/.

Building images using ti-bdebstrap involves the following steps:

  1. install the pre-requisite packages

  2. get the scripts using git clone

  3. checkout to the SDK release version tag that you want to build

  4. run the build.sh script and with required build config as argument.

  5. creating a wic image using create-wic.sh.

  6. flashing the image into a SD card

3.2.5. Install Pre-requisite Packages

First, ensure that your repositories are up-to-date:

sudo apt update

Then, install packages as follows:

sudo apt install -y \
    pigz expect pv \
    binfmtc binfmt-support \
    qemu-user qemu-user-static qemu-system-arm \
    debian-archive-keyring bdebstrap \
    build-essential autoconf automake \
    bison flex libssl-dev \
    bc u-boot-tools swig python3-pyelftools

Ensure that all packages were correctly installed using:

sudo apt install --fix-broken

Finally, install toml-cli and yamllint:

pip3 install toml-cli
pip3 install yamllint

Note

Since the build script is run as root user, toml-cli and yamllint should also be installed with sudo for root user to be able to access it.

Note

The scripts internally handle toolchain downloads based on Host architecture. So the same steps can be followed on both arm and x86_64 hosts.

3.2.6. Checkout to the Correct Release Tag

ti-bdebstrap repository has tags corresponding to each release.

Before building the image, it is important to ensure that you are on the correct release tag. First, view all the tags using:

git tag

Then, select a release tag and checkout to it:

git checkout <tag-name>

For example, to checkout to the 10.00.07-release tag, use the following command:

git checkout 10.00.07-release

The builds.toml and other config files will now support building images corresponding to the 10.00.07 release.

3.2.7. Building the Image

Note

If you are behind a proxy, since the build is run with sudo, make sure to set the proxy for root user (preferably in /etc/environment).

To build an image, you need to run the build.sh script:

sudo ./build.sh <build-name>

The <build-name> must be one present inside builds.toml file.

After the build, the RootFS, Boot partition and bsp_sources are stored in build/<build-name>. The logs will be stored in logs/<build-name>.log.

Example: to build for trixie-am62pxx-evm, run:

sudo ./build.sh trixie-am62pxx-evm

The RootFS, Boot partition and bsp_sources are then stored in build/trixie-am62pxx-evm. The build log is saved as logs/trixie-am62pxx-evm.log.

3.2.8. Generate an SD Card Image

This step can be skipped if you do not want to share the generated Image with anyone and want to proceed with testing with an SD card.

To generate an SD Card Image with the generated RootFS and Boot partition files, run:

./create-wic.sh <build-name>

Example: to build for trixie-am62pxx-evm, run:

./create-wic.sh trixie-am62pxx-evm

The wic image is generated under build/trixie-am62pxx-evm. This can be used to flash an SD card using standard tools like balena-etcher.

3.2.9. Flash Image to SD Card using Script

To flash the SD card without generating a wic image, use the create-sdcard.sh script. Run it using the below command and follow with the prompts.

sudo ./create-sdcard.sh <build-name>

For example, if the image is trixie-am62pxx-evm, type:

sudo ./create-sdcard.sh trixie-am62pxx-evm

This script will partition the SD Card and copy the contents of RootFS and Boot partitions that are generated to the SD Card.