Skip to content

feat(debian): Armbian-ize Debian docs for all platforms #341

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
StaticRocket merged 1 commit into from
Jul 14, 2025
Merged

feat(debian): Armbian-ize Debian docs for all platforms #341

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .github/styles/config/vocabularies/PSDK/accept.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,3 +25,6 @@ balenaEtcher
Armbian
Debian
Weston
Trixie
mmdebstrap
bdebstrap
2 changes: 1 addition & 1 deletion configs/AM62LX/AM62LX_debian_toc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ devices/AM62LX/debian/index

debian/Overview
devices/AM62LX/debian/Getting_Started_Guide
devices/AM62LX/debian/Building_Debian_Image
debian/Building_Debian_Image
debian/Building_Debian_Packages
debian/How_to_Guides/index_How_to_Guides
linux/How_to_Guides/Target/How_To_Enable_M2CC3301_in_linux
Expand Down
254 changes: 62 additions & 192 deletions source/debian/Building_Debian_Image.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,236 +1,106 @@
======================
Building Debian Images
======================
====================================

Check warning on line 1 in source/debian/Building_Debian_Image.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.ReadabilityGrade] Simplify your language. The calculated Flesch–Kincaid grade level of 9.59 is above the recommended reading grade level of 9.

Raw Output:
{"message": "[RedHat.ReadabilityGrade] Simplify your language. The calculated Flesch–Kincaid grade level of 9.59 is above the recommended reading grade level of 9.", "location": {"path": "source/debian/Building_Debian_Image.rst", "range": {"start": {"line": 1, "column": 1}}}, "severity": "INFO"}
Building Debian Images Using Armbian

Check warning on line 2 in source/debian/Building_Debian_Image.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Headings] Use sentence-style capitalization in 'Building Debian Images Using Armbian'.

Raw Output:
{"message": "[RedHat.Headings] Use sentence-style capitalization in 'Building Debian Images Using Armbian'.", "location": {"path": "source/debian/Building_Debian_Image.rst", "range": {"start": {"line": 2, "column": 1}}}, "severity": "INFO"}
====================================

Introduction
============

Building a Debian Image requires:
Texas Instruments uses the **Armbian** build framework to generate Debian images for its platforms.
*Armbian* describes itself to be a "base operating system"; that is, a build framework used to build
Linux images optimized for Single-Board Computers.

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
|__SDK_DOWNLOAD_URL__| provides Debian images, but users can also build these, especially if users
require something custom (such as different kernel configurations or default desktop environments).

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).
Armbian Usage

Check warning on line 15 in source/debian/Building_Debian_Image.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Headings] Use sentence-style capitalization in 'Armbian Usage'.

Raw Output:
{"message": "[RedHat.Headings] Use sentence-style capitalization in 'Armbian Usage'.", "location": {"path": "source/debian/Building_Debian_Image.rst", "range": {"start": {"line": 15, "column": 1}}}, "severity": "INFO"}
=============

`ti-bdebstrap <https://github.com/TexasInstruments/ti-debpkgs>`__ 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.
This document provides high-level information about how to build Debian images for TI platforms,
using Armbian. For a full list of options available for users to configure these images at build
time, see `Armbian Documentation <https://docs.armbian.com/>`__.

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 images for AM62Lx, AM62Px, AM62x and AM64x platforms.

Usage
=====

Get Scripts
Get Armbian
-----------

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

To clone the repository, run:
For the time being, TI's fork of Armbian maintains support for TI platforms. Therefore, the first
step is to fetch TI's fork:

.. code-block:: console
git clone https://github.com/TexasInstruments/ti-bdebstrap.git
git clone https://github.com/TexasInstruments/armbian-build.git
Repository Structure
--------------------

.. code-block:: text
tibdebstrap/
├── 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
│   ├── 09.02.00.010.toml
│   └── 11.00.05.02.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).

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 :file:`configs/machines.toml`, :file:`configs/bdebstrap_configs/<distro>/<distro>-<machine>.yaml` and :file:`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.

Building Images
---------------

All valid builds are listed in the :file:`builds.toml` file. To build an image, one of these must be chosen and supplied to the :file:`build.sh` command. :file:`build.sh` commences the build process.
The images are finally stored in the :file:`build/` directory. Each build also produces a log file inside :file:`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 :file:`build.sh` script and with required build config as argument.
5. creating a wic image using :file:`create-wic.sh`.
6. flashing the image into a SD card

Install Pre-requisite Packages
------------------------------

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

.. code-block:: console
sudo apt update
Then, install packages as follows:

.. code-block:: console
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:

.. code-block:: console
sudo apt install --fix-broken
Finally, install ``toml-cli`` and ``yamllint``:

.. code-block:: console
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.

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:

.. code-block:: console
git tag
Then, select a release tag and checkout to it:

.. code-block:: console
git checkout <tag-name>
There are 4 files and directories of relevance to this high-level overview:

For example, to checkout to the `10.01.10.04-release` tag, use the following command:
- :file:`configs/`: This directory has configurations for boards, families, kernel configurations,
desktop or CLI environments and so on. To find configuration files relevant to TI, see:

.. code-block:: console
git checkout 10.01.10.04-release
The :file:`builds.toml` and other config files will now support building images corresponding to the `10.01.10.04` release.

Building the Image
-------------------
- :file:`configs/sources/families/k3.conf`
- :file:`configs/kernel/linux-k3-current.conf`

Check warning on line 41 in source/debian/Building_Debian_Image.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.CaseSensitiveTerms] Use 'Linux' rather than 'linux'.

Raw Output:
{"message": "[RedHat.CaseSensitiveTerms] Use 'Linux' rather than 'linux'.", "location": {"path": "source/debian/Building_Debian_Image.rst", "range": {"start": {"line": 41, "column": 28}}}, "severity": "WARNING"}
- :file:`configs/kernel/linux-k3-rt-current.conf`

Check warning on line 42 in source/debian/Building_Debian_Image.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.CaseSensitiveTerms] Use 'Linux' rather than 'linux'.

Raw Output:
{"message": "[RedHat.CaseSensitiveTerms] Use 'Linux' rather than 'linux'.", "location": {"path": "source/debian/Building_Debian_Image.rst", "range": {"start": {"line": 42, "column": 28}}}, "severity": "WARNING"}

.. note::
- :file:`compile.sh`: This is the script that the user should run for building Armbian images.

If you are behind a proxy, since the build is run with sudo, make sure to set the proxy for root user (preferably in :file:`/etc/environment`).
- :file:`lib/`: This directory stores the scripts that do most of the work in building Armbian images.

To build an image, you need to run the :file:`build.sh` script:
- :file:`extensions/`: This directory has files that define **extension hooks**. In Armbian, *extension
hooks* are function signatures, which the build framework calls in the process of building an
image. However, the build framework does not define these in ``lib/``. Users can define these
functions and integrate custom steps in the build process. TI has ``extensions/ti-debpkgs.sh``
extension file. To customize the build process, create a new file in this directory, and define
your extension hooks there. Once the file is created, be sure to add the following line to
board/family config file:

.. code-block:: console
.. code-block:: console
sudo ./build.sh <build-name>
enable_extension <extension_name>
The ``<build-name>`` must be one present inside :file:`builds.toml` file.
- :file:`userpatches/`: This directory stores files that define build parameters, user patches and so on.

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

Check warning on line 62 in source/debian/Building_Debian_Image.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Headings] Use sentence-style capitalization in 'Building Images'.

Raw Output:
{"message": "[RedHat.Headings] Use sentence-style capitalization in 'Building Images'.", "location": {"path": "source/debian/Building_Debian_Image.rst", "range": {"start": {"line": 62, "column": 1}}}, "severity": "INFO"}
---------------

Example: to build for ``trixie-am62pxx-evm``, run:
Armbian supports an interactive build process. To build interactively, go to TI's Armbian fork you
cloned, and use the following command:

.. code-block:: console
sudo ./build.sh trixie-am62pxx-evm
The RootFS, Boot partition and bsp_sources are then stored in :file:`build/trixie-am62pxx-evm`. The build log is saved as :file:`logs/trixie-am62pxx-evm.log`.
./compile.sh
Generate an SD Card Image
-------------------------
The build framework will then display dialog boxes. The user can use this to select the board, CLI
or desktop environment, kernel configurations and so on.

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:

.. code-block:: console
./create-wic.sh <build-name>
Example: to build for ``trixie-am62pxx-evm``, run:
To build the image non-interactively, specify all required **Build Switches** in the command:

.. code-block:: console
./create-wic.sh trixie-am62pxx-evm
The wic image is generated under :file:`build/trixie-am62pxx-evm`. This can be used to flash an SD card using standard tools like balena-etcher.
./compile.sh [command] [switch...] [command...]
Flash Image to SD Card using Script
-----------------------------------
A full list of build switches is available at `Build Switches <https://docs.armbian.com/Developer-Guide_Build-Switches/>`__.

To flash the SD card without generating a wic image, use the :file:`create-sdcard.sh` script. Run it using the below command and follow with the prompts.
For example, the following command builds the minimal non-RT Trixie image:

.. code-block:: console
sudo ./create-sdcard.sh <build-name>
./compile.sh build BOARD=<target> BRANCH=current BUILD_MINIMAL=yes KERNEL_CONFIGURE=no RELEASE=trixie SKIP_ARMBIAN_REPO=yes
For example, if the image is ``trixie-am62pxx-evm``, type:

.. code-block:: console
For a list of targets corresponding to each board, refer:

sudo ./create-sdcard.sh trixie-am62pxx-evm
+------------------------------+--------------+
| Board | Target |
+==============================+==============+
| AM62P | sk-am62p |
+------------------------------+--------------+
| AM62x | sk-am62b |
+------------------------------+--------------+
| AM62-LP | sk-am62-lp |
+------------------------------+--------------+
| AM62SIP | sk-am62-sip |
+------------------------------+--------------+
| AM64x | sk-am64b |
+------------------------------+--------------+

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

``output/images/`` stores the built images. These images have a ``.img`` extension.
50 changes: 22 additions & 28 deletions source/debian/Overview.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,43 +2,37 @@
Overview
########

.. ifconfig:: CONFIG_part_variant in ('AM62LX')
Debian, also known as Debian GNU/Linux, is a Linux distribution composed of free and open source

Check warning on line 5 in source/debian/Overview.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Slash] Use either 'or' or 'and' in 'GNU/Linux'

Raw Output:
{"message": "[RedHat.Slash] Use either 'or' or 'and' in 'GNU/Linux'", "location": {"path": "source/debian/Overview.rst", "range": {"start": {"line": 5, "column": 30}}}, "severity": "WARNING"}
software. Community-supported Debian Project develops and maintains it. It offers a vast repository
of software packages, which the ``apt`` package manager can install.

Armbian is a highly-optimized **base operating system** (i.e. an extensive build framework) for building Debian-based images for Single-Board Computers (SBCs).
TI creates Debian images by using the popular project called **Armbian**. Armbian is a highly-optimized
**base operating system** (i.e. an extensive build framework) for building Debian-based images for

Check warning on line 10 in source/debian/Overview.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.TermsWarnings] Consider using 'you' rather than 'i' unless updating existing content that uses the term.

Raw Output:
{"message": "[RedHat.TermsWarnings] Consider using 'you' rather than 'i' unless updating existing content that uses the term.", "location": {"path": "source/debian/Overview.rst", "range": {"start": {"line": 10, "column": 28}}}, "severity": "WARNING"}
Single-Board Computers. Unlike other tools, such as mmdebstrap and bdebstrap, which are often
used for creating Debian images, Armbian focuses on creating images for Single-Board Computers.

TI's AM62LX, AM62Px, AM62x and AM64x platforms offer the Debian distribution. Few key highlights of
this project are:

Debian, also known as Debian GNU/Linux, is a Linux distribution composed of free and open-source software, developed by the community-supported Debian Project.
- The Debian filesystem image requires standard packages from debian.org and TI's customizations as
``.deb`` packages. TI's package build infrastructure uses public sources of git repositories to build
deb packages. TI's official repository maintained on `Github/TexasInstruments/ti-debpkgs
<https://github.com/TexasInstruments/ti-debpkgs>`__ hosts these packages.

.. ifconfig:: CONFIG_part_variant in ('AM62LX')

The Linux Debian distribution, built using Armbian, is enabled for TI's AM62Lx platform. Few key highlights of this project are:

.. ifconfig:: CONFIG_part_variant not in ('AM62LX')

The Linux Debian distribution is enabled for TI's AM62Px, AM62x and AM64x platforms. Few key highlights of this project are:

- The Debian filesystem image requires standard packages from debian.org and TI's customizations as .deb packages. The deb packages for the components owned by TI are built using the public sources hosted on respective git repositories and the deb packages are hosted on TI's official PPA repository maintained on `Github/TexasInstruments <https://github.com/TexasInstruments/ti-debpkgs>`__.

.. ifconfig:: CONFIG_part_variant not in ('AM62LX')

- The entire Debian build process is made easy with a build script, the script "ti-bdebstrap" is hosted on `TI Debian Github <https://github.com/TexasInstruments/ti-bdebstrap>`__.

- This document also provides the required steps and instructions to customize the TI's components for AM62Lx, AM62Px, AM62x and AM64x SOCs and create the corresponding deb packages.

- The entire project is made public and we accept community contributions as pull requests to github repositories.

.. ifconfig:: CONFIG_part_variant not in ('AM62LX')

- Github actions are enabled for the buildscripts workflow. So, any change in the config files, package additions or modifications in build scripts will result in auto generation of a new debian filesystem that reflects these changes. The new builds will store the filesystem image as an artifact hosted on the same repo, allowing other users to test the change without making a new build. These images are available via github for 90 days after which they may be purged to save disk space.
- This document also provides the required steps and instructions to customize the TI's components
for AM62Lx, AM62Px, AM62x and AM64x Systems-on-Chip and create the corresponding deb packages.

- The entire project is public and we accept community contributions as pull requests to GitHub
repositories.

Debian vs Yocto
===============

TI provides both Debian and OpenEmbedded/Yocto based images as their Linux offering. Here's a quick comparision between both to let you choose which one to get started with.
TI provides both Debian and OpenEmbedded/Yocto based images as their Linux offering. Here's a quick
comparison between both to decide the one to start with:

Comparision
-----------
Comparison
----------

+-------------------+--------------------------------------+---------------------------------------+
| **File System** | **Debian** | **OpenEmbedded/Yocto (Arago)** |
Expand All @@ -65,7 +59,7 @@
Acknowledgements
================

- `beagleboard/image-builder <https://github.com/beagleboard/image-builder.git>`__
- `armbian/build <https://github.com/armbian/build/>`__
- `beagleboard/repos-arm64 <https://git.beagleboard.org/beagleboard/repos-arm64>`__


Expand Down
Loading
Loading