|
1 | | -====================== |
2 | | -Building Debian Images |
3 | | -====================== |
| 1 | +==================================== |
| 2 | +Building Debian Images Using Armbian |
| 3 | +==================================== |
4 | 4 |
|
5 | 5 | Introduction |
6 | 6 | ============ |
7 | 7 |
|
8 | | -Building a Debian Image requires: |
| 8 | +Texas Instruments uses the **Armbian** build framework to generate Debian images for its platforms. |
| 9 | +*Armbian* describes itself to be a "base operating system"; that is, a build framework used to build |
| 10 | +Linux images optimized for Single-Board Computers. |
9 | 11 |
|
10 | | - 1. Generating a chroot environment for the target architecture (Arm), if the host environment is on x86. |
11 | | - 2. Installing all the necessary packages |
12 | | - 3. Customizing configuration scripts if needed |
13 | | - 4. Building Bootloader |
14 | | - 5. Flashing the generated RootFS and Boot binaries to SD Card |
| 12 | +|__SDK_DOWNLOAD_URL__| provides Debian images, but users can also build these, especially if users |
| 13 | +require something custom (such as different kernel configurations or default desktop environments). |
15 | 14 |
|
16 | | -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). |
| 15 | +Armbian Usage |
| 16 | +============= |
17 | 17 |
|
18 | | -`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. |
| 18 | +This document provides high-level information about how to build Debian images for TI platforms, |
| 19 | +using Armbian. For a full list of options available for users to configure these images at build |
| 20 | +time, see `Armbian Documentation <https://docs.armbian.com/>`__. |
19 | 21 |
|
20 | | -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. |
21 | | - |
22 | | -TI currently supports building Debian images for AM62Lx, AM62Px, AM62x and AM64x platforms. |
23 | | - |
24 | | -Usage |
25 | | -===== |
26 | | - |
27 | | -Get Scripts |
| 22 | +Get Armbian |
28 | 23 | ----------- |
29 | 24 |
|
30 | | -The scripts are hosted at https://github.com/TexasInstruments/ti-bdebstrap |
31 | | - |
32 | | -To clone the repository, run: |
| 25 | +For the time being, TI's fork of Armbian maintains support for TI platforms. Therefore, the first |
| 26 | +step is to fetch TI's fork: |
33 | 27 |
|
34 | 28 | .. code-block:: console |
35 | 29 |
|
36 | | - git clone https://github.com/TexasInstruments/ti-bdebstrap.git |
37 | | -
|
| 30 | + git clone https://github.com/TexasInstruments/armbian-build.git |
38 | 31 |
|
39 | 32 | Repository Structure |
40 | 33 | -------------------- |
41 | 34 |
|
42 | | -.. code-block:: text |
43 | | -
|
44 | | - tibdebstrap/ |
45 | | - ├── build.sh |
46 | | - ├── builds.toml |
47 | | - ├── configs |
48 | | - │ ├── bdebstrap_configs |
49 | | - │ │ ├── bookworm |
50 | | - │ │ │ ├── bookworm-<machine>.yaml |
51 | | - │ │ │ └── bookworm-rt-<machine>.yaml |
52 | | - │ │ └── trixie |
53 | | - │ │ ├── trixie-<machine>.yaml |
54 | | - │ │ └── trixie-rt-<machine>.yaml |
55 | | - │ ├── bsp_sources.toml |
56 | | - │ └── machines |
57 | | - │ ├── 09.02.00.010.toml |
58 | | - │ └── 11.00.05.02.toml |
59 | | - ├── create-sdcard.sh |
60 | | - ├── create-wic.sh |
61 | | - ├── LICENSE |
62 | | - ├── README.md |
63 | | - ├── scripts |
64 | | - │ ├── build_bsp.sh |
65 | | - │ ├── build_distro.sh |
66 | | - │ ├── common.sh |
67 | | - │ └── setup.sh |
68 | | - └── target --> Custom files to deploy in target. |
69 | | -
|
70 | | -``build.sh``: the "main" script that the user should run to generate Debian images. |
71 | | - |
72 | | -``configs/``: contains details, configuration options and values for machines, bsp_sources and distro-variants (see below for details). |
73 | | - |
74 | | -``scripts/``: contains helper scripts for ``build.sh``. |
75 | | - |
76 | | -``target/``: contains files for target configs, like ``weston.service`` for the **weston** target. |
77 | | - |
78 | | -``builds.toml``: contains list of all valid builds along with their definitions (see below for details). |
79 | | - |
80 | | -Build Configurations |
81 | | --------------------- |
82 | | - |
83 | | -A ``build config`` represents an image with certain values for the ``machine``, ``rt_linux`` and ``distro_codename`` parameters. |
84 | | - |
85 | | -The ``builds.toml`` file contains a list of all valid builds in the ``builds[]`` list. Each ``build`` is then defined underneath. |
86 | | - |
87 | | -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. |
88 | | - |
89 | | -So long as you conform to the rule above, you may also define your own builds. |
90 | | - |
91 | | -Building Images |
92 | | ---------------- |
93 | | - |
94 | | -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. |
95 | | -The images are finally stored in the :file:`build/` directory. Each build also produces a log file inside :file:`log/`. |
96 | | - |
97 | | -Building images using ``ti-bdebstrap`` involves the following steps: |
98 | | - |
99 | | - 1. install the pre-requisite packages |
100 | | - 2. get the scripts using ``git clone`` |
101 | | - 3. checkout to the SDK release version tag that you want to build |
102 | | - 4. run the :file:`build.sh` script and with required build config as argument. |
103 | | - 5. creating a wic image using :file:`create-wic.sh`. |
104 | | - 6. flashing the image into a SD card |
105 | | - |
106 | | -Install Pre-requisite Packages |
107 | | ------------------------------- |
| 35 | +There are 4 files and directories of relevance to this high-level overview: |
108 | 36 |
|
109 | | -First, ensure that your repositories are up-to-date: |
| 37 | +- ``configs/``: This directory has configurations for boards, families, kernel configurations, |
| 38 | + desktop or CLI environments and so on. To find configuration files relevant to TI, see: |
110 | 39 |
|
111 | | -.. code-block:: console |
112 | | -
|
113 | | - sudo apt update |
| 40 | + - ``configs/sources/families/k3.conf`` |
| 41 | + - ``configs/kernel/linux-k3-current.conf`` |
| 42 | + - ``configs/kernel/linux-k3-rt-current.conf`` |
114 | 43 |
|
115 | | -Then, install packages as follows: |
| 44 | +- ``compile.sh``: This is the script that the user should run for building Armbian images. |
116 | 45 |
|
117 | | -.. code-block:: console |
| 46 | +- ``lib/``: This directory stores the scripts that do most of the work in building Armbian images. |
118 | 47 |
|
119 | | - sudo apt install -y \ |
120 | | - pigz expect pv \ |
121 | | - binfmtc binfmt-support \ |
122 | | - qemu-user qemu-user-static qemu-system-arm \ |
123 | | - debian-archive-keyring bdebstrap \ |
124 | | - build-essential autoconf automake \ |
125 | | - bison flex libssl-dev \ |
126 | | - bc u-boot-tools swig python3-pyelftools |
| 48 | +- ``extensions/``: This directory has files that define **extension hooks**. In Armbian, *extension |
| 49 | + hooks* are function signatures, which the build framework calls in the process of building an |
| 50 | + image. However, the build framework does not define these in ``lib/``. Users can define these |
| 51 | + functions and integrate custom steps in the build process. TI has ``extensions/ti-debpkgs.sh`` |
| 52 | + extension file. To customize the build process, create a new file in this directory, and define |
| 53 | + your extension hooks there. Once the file is created, be sure to add the following line to |
| 54 | + board/family config file: |
127 | 55 |
|
| 56 | + .. code-block:: console |
128 | 57 |
|
129 | | -Ensure that all packages were correctly installed using: |
130 | | - |
131 | | -.. code-block:: console |
132 | | -
|
133 | | - sudo apt install --fix-broken |
134 | | -
|
135 | | -Finally, install ``toml-cli`` and ``yamllint``: |
136 | | - |
137 | | -.. code-block:: console |
| 58 | + enable_extension <extension_name> |
138 | 59 |
|
139 | | - pip3 install toml-cli |
140 | | - pip3 install yamllint |
| 60 | +- ``userpatches/``: This directory stores files that define build parameters, user patches and so on. |
141 | 61 |
|
142 | | -.. note:: |
143 | | - |
144 | | - 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. |
145 | | - |
146 | | -.. note:: |
147 | | - |
148 | | - The scripts internally handle toolchain downloads based on Host architecture. So the same steps can be followed on both ``arm`` and ``x86_64`` hosts. |
149 | | - |
150 | | -Checkout to the Correct Release Tag |
151 | | ------------------------------------ |
152 | | - |
153 | | -ti-bdebstrap repository has tags corresponding to each release. |
154 | | - |
155 | | -Before building the image, it is important to ensure that you are on the correct release tag. First, view all the tags |
156 | | -using: |
157 | | - |
158 | | -.. code-block:: console |
159 | | -
|
160 | | - git tag |
161 | | -
|
162 | | -Then, select a release tag and checkout to it: |
163 | | - |
164 | | -.. code-block:: console |
165 | | -
|
166 | | - git checkout <tag-name> |
167 | | -
|
168 | | -For example, to checkout to the `10.01.10.04-release` tag, use the following command: |
169 | | - |
170 | | -.. code-block:: console |
171 | | -
|
172 | | - git checkout 10.01.10.04-release |
173 | | -
|
174 | | -The :file:`builds.toml` and other config files will now support building images corresponding to the `10.01.10.04` release. |
175 | | - |
176 | | -Building the Image |
177 | | -------------------- |
178 | | - |
179 | | -.. note:: |
180 | | - |
181 | | - 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`). |
182 | | - |
183 | | -To build an image, you need to run the :file:`build.sh` script: |
184 | | - |
185 | | -.. code-block:: console |
186 | | -
|
187 | | - sudo ./build.sh <build-name> |
188 | | -
|
189 | | -The ``<build-name>`` must be one present inside :file:`builds.toml` file. |
190 | | - |
191 | | -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`. |
| 62 | +Building Images |
| 63 | +--------------- |
192 | 64 |
|
193 | | -Example: to build for ``trixie-am62pxx-evm``, run: |
| 65 | +Armbian supports an interactive build process. To build interactively, go to TI's Armbian fork you |
| 66 | +cloned, and use the following command: |
194 | 67 |
|
195 | 68 | .. code-block:: console |
196 | 69 |
|
197 | | - sudo ./build.sh trixie-am62pxx-evm |
198 | | -
|
199 | | -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`. |
200 | | - |
201 | | -Generate an SD Card Image |
202 | | -------------------------- |
203 | | - |
204 | | -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. |
205 | | - |
206 | | -To generate an SD Card Image with the generated RootFS and Boot partition files, run: |
| 70 | + ./compile.sh |
207 | 71 |
|
208 | | -.. code-block:: console |
209 | | -
|
210 | | - ./create-wic.sh <build-name> |
| 72 | +The build framework will then display dialog boxes. The user can use this to select the board, CLI |
| 73 | +or desktop environment, kernel configurations and so on. |
211 | 74 |
|
212 | | -Example: to build for ``trixie-am62pxx-evm``, run: |
| 75 | +To build the image non-interactively, specify all required **Build Switches** in the command: |
213 | 76 |
|
214 | 77 | .. code-block:: console |
215 | 78 |
|
216 | | - ./create-wic.sh trixie-am62pxx-evm |
217 | | -
|
218 | | -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. |
219 | | - |
220 | | -Flash Image to SD Card using Script |
221 | | ------------------------------------ |
| 79 | + ./compile.sh [command] [switch...] [command...] |
222 | 80 |
|
223 | | -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. |
| 81 | +A full list of build switches is available at `Build Switches <https://docs.armbian.com/Developer-Guide_Build-Switches/>`__. |
224 | 82 |
|
225 | | -.. code-block:: console |
226 | | -
|
227 | | - sudo ./create-sdcard.sh <build-name> |
228 | | -
|
229 | | -For example, if the image is ``trixie-am62pxx-evm``, type: |
| 83 | +For example, the following command builds the minimal non-RT Trixie image: |
230 | 84 |
|
231 | 85 | .. code-block:: console |
232 | 86 |
|
233 | | - sudo ./create-sdcard.sh trixie-am62pxx-evm |
234 | | -
|
235 | | -This script will partition the SD Card and copy the contents of RootFS and Boot partitions that are generated to the SD Card. |
| 87 | + ./compile.sh build BOARD=<board-name> BRANCH=current BUILD_MINIMAL=yes KERNEL_CONFIGURE=no RELEASE=trixie SKIP_ARMBIAN_REPO=yes |
236 | 88 |
|
| 89 | +``output/images/`` stores the built images. These images have a ``.img`` extension. |
0 commit comments