mirrors/buildenv
1
0
Fork 0
mirror of https://github.com/tuxbox-neutrino/buildenv.git synced 2025-08-26 15:02:58 +02:00
Code Issues Packages Projects Releases Wiki Activity

Update readme

Browse Source
This commit is contained in:
Thilo Graf
2025-07-13 17:00:58 +02:00
parent b8c0feefda
commit ef4dbbcaae
2 changed files with 138 additions and 135 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
README_de.md
View File

@@ -10,7 +10,7 @@ Dieses Skript dient als Werkzeug zur Vereinfachung der Erstellung einer Umgebung
- [1.2 Git vorbereiten (falls erforderlich)](#12-git-vorbereiten-falls-erforderlich) - [1.2 Git vorbereiten (falls erforderlich)](#12-git-vorbereiten-falls-erforderlich)
- [1.3 Init-Skript klonen](#13-init-skript-klonen) - [1.3 Init-Skript klonen](#13-init-skript-klonen)
- [1.4 Init-Skript ausführen](#14-init-skript-ausführen) - [1.4 Init-Skript ausführen](#14-init-skript-ausführen)
- [1.5 Struktur der Buildumgebung](#15-struktur-der-buildumgebung) - [1.4.1 Struktur der Buildumgebung](#141-struktur-der-buildumgebung)
- [2. Image bauen](#2-image-bauen) - [2. Image bauen](#2-image-bauen)
- [2.1 Box wählen](#21-box-wählen) - [2.1 Box wählen](#21-box-wählen)
- [2.2 Starte Umgebungsskript](#22-starte-umgebungsskript) - [2.2 Starte Umgebungsskript](#22-starte-umgebungsskript)
@@ -89,7 +89,7 @@ git clone https://github.com/tuxbox-neutrino/buildenv.git && cd buildenv
./init && cd poky-3.2.4 ./init && cd poky-3.2.4
``` ```
### 1.5 Struktur der Buildumgebung ### 1.4.1 Struktur der Buildumgebung
Nach [Schritt 1.4](#14-init-skript-ausführen) sollte etwa diese Struktur angelegt worden sein: Nach [Schritt 1.4](#14-init-skript-ausführen) sollte etwa diese Struktur angelegt worden sein:
@@ -106,21 +106,21 @@ Nach [Schritt 1.4](#14-init-skript-ausführen) sollte etwa diese Struktur angele
└── poky-{DISTRO_VERSION} <-- Nach Schritt 1.4 befindest Du dich hier. Hier befindet sich der Buildsystem-Kern und die Meta-Layer └── poky-{DISTRO_VERSION} <-- Nach Schritt 1.4 befindest Du dich hier. Hier befindet sich der Buildsystem-Kern und die Meta-Layer
│ │
: :
└── build <-- Hier liegen die Build-Unterverzeichnisse, nach Schritt 2.2 befindest Du dich in einem dieser Build-Unterverzeichnisse └── build <-- Hier liegen die Build-Unterverzeichnisse, nach Schritt 2.2 befindest Du dich in einem der Maschinen- Build-Unterverzeichnisse
├── <machine x> <-- Build-Unterverzeichnis für Maschinentyp x ├── <machine x> <-- Build-Unterverzeichnis für Maschinentyp x
│ ├── conf <-- Ordner für Layer und benutzerdefinierte Konfiguration │ ├── conf <-- Ordner für Layer und benutzerdefinierte Konfiguration
│ │ └── bblayers.conf <-- Konfigurationsdatei für eingebundene Meta-Layer │ │ └── bblayers.conf <-- Konfigurationsdatei für eingebundene Meta-Layer
│ │ └── local.conf <-- benutzerdefinierte Konfiguration für einen Maschinentyp │ │ └── local.conf <-- benutzerdefinierte Konfiguration für einen Maschinentyp
│ : │ :
│ ├── (tmp) <-- Arbeitsverzeichnis, wird beim Bauen automatisch angelegt │ ├── (tmp) <-- Arbeitsverzeichnis, wird beim Bauen von Targets von Bitbake automatisch angelegt
│ └── (workspace) <-- Workspace, wird beim Ausführen von devtool angelegt │ └── (workspace) <-- Workspace, wird automatisch beim Ausführen von ```devtool modify``` angelegt
: :
└── <machine y> <-- weiteres Build-Unterverzeichnis für Maschinentyp y └── <machine y> <-- weiteres Build-Unterverzeichnis für Maschinentyp y
``` ```
## 2. Image bauen ## 2. Image bauen
Stelle sicher, dass Du dich wie im [Schema](#15-struktur-der-buildumgebung) gezeigt hier befindest: Stelle sicher, dass Du dich wie im [Schema](#141-struktur-der-buildumgebung) gezeigt im ```poky```-Verzeichnis befindest:
``` ```
poky-{DISTRO_VERSION} poky-{DISTRO_VERSION}
@@ -132,17 +132,20 @@ Liste verfügbarer Geräte anzeigen lassen:
```bash ```bash
ls build ls build
<machine> <machine1> <machine2> <machine3>...
``` ```
**Hinweis:** Die hier ausgegebenen Typen können gebaut werden und müssen bei den folgenden Schritten genauso angegeben werden, also möglichts nicht vertippen!
### 2.2 Starte Umgebungsskript ### 2.2 Starte Umgebungsskript
Führe das Umgebungsskript für die aus der Liste gewünschte Box einmalig aus! Du gelangst dann automatisch in das passende Build-Unterverzeichnis. Führe das Umgebungsskript für genau **eine** aus der Liste gewünschte Box einmalig aus! Du gelangst dann automatisch in das passende Build-Unterverzeichnis.
```bash ```bash
. ./oe-init-build-env build/<machine> . ./oe-init-build-env build/<machine>
``` ```
Solange man sich ab jetzt mit der erzeugten Umgebung innerhalb der geöffneten Shell im gewünschten Build-Unterverzeichnis befindet, muss man dieses Script nicht noch einmal ausführen und kannst [Schritt 2.3 ](#23-image-erstellen) Images oder beliebige Pakete bauen. Solange man sich ab jetzt mit der erzeugten Umgebung innerhalb der geöffneten Shell im gewünschten Build-Unterverzeichnis befindet, muss man dieses Script nicht noch einmal ausführen und kannst mit [Schritt 2.3 ](#23-image-erstellen) Images oder beliebige Pakete bauen.
**Hinweis:** Du kannst auch weitere Shells und damit Buildumgebungen für weitere Boxtypen parallel dazu anlegen und je nach Bedarf auf das entsprechende Terminal wechseln und auch parallel bauen lassen, sofern es dein System hergibt. **Hinweis:** Du kannst auch weitere Shells und damit Buildumgebungen für weitere Boxtypen parallel dazu anlegen und je nach Bedarf auf das entsprechende Terminal wechseln und auch parallel bauen lassen, sofern es dein System hergibt.
@@ -152,7 +155,7 @@ Solange man sich ab jetzt mit der erzeugten Umgebung innerhalb der geöffneten S
bitbake neutrino-image bitbake neutrino-image
``` ```
Das kann eine Weile dauern. Einige Warnmeldungen können ignoriert werden. Fehlermeldungen, welche die Setscene-Tasks betreffen, sind kein Problem, aber Fehler während der Build- und Package-Tasks brechen den Prozess in den meisten Fällen ab. [Bitte melde in diesem Fall den Fehler oder teile Deine Lösung](https://forum.tuxbox-neutrino.org/forum/viewforum.php?f=77). Hilfe ist sehr willkommen. Dieser Befehl baut nun das komplette Image mit allen dazu gehörenden Paketen und auch den Paketen, die je nach Konfiguration extra gebaut werden oder nur gabaut aber nicht ins Image installiert werden sollen. Das kann eine Weile dauern. Einige Warnmeldungen können ignoriert werden. Fehlermeldungen, welche die Setscene-Tasks betreffen, sind kein Problem, aber Fehler während der Build- und Package-Tasks brechen den Prozess in den meisten Fällen ab. [Bitte melde in diesem Fall den Fehler oder teile Deine Lösung](https://forum.tuxbox-neutrino.org/forum/viewforum.php?f=77). Hilfe ist sehr willkommen.
Wenn alles erledigt ist, sollte eine ähnliche Meldung wie diese erscheinen: Wenn alles erledigt ist, sollte eine ähnliche Meldung wie diese erscheinen:

238
README_en.md
View File

@@ -2,56 +2,56 @@
[🇩🇪 German](README_de.md) | <span style="color: grey;">🇬🇧 English</span> [🇩🇪 German](README_de.md) | <span style="color: grey;">🇬🇧 English</span>
<!-- LANGUAGE_LINKS_END --> <!-- LANGUAGE_LINKS_END -->
This script serves as a tool to simplify setting up a development environment and the build process for images that run with Neutrino as the user interface on various hardware platforms. It automates several steps required to establish a consistent and functional development and build environment by preconfiguring necessary dependencies, basic configurations, and meta-layers, while allowing for custom settings. The script aims to provide a foundation on which you can build and experiment to create, update, and maintain your own customized versions of Tuxbox-Neutrino images. This script serves as a tool to simplify setting up a development environment and the build process for images that use Neutrino as their user interface on different hardware platforms. It automates several of the steps needed to create a consistent, functional development and build environment by pre‑installing the necessary dependencies, basic configurations, and meta‑layers, while still letting you add custom settings. The script aims to give you a solid base on which you can build and experiment in order to create, update, and maintain your own customised versions of Tuxbox‑Neutrino images.
* [1. Preparation](#1-preparation) * [1. Preparation](#1-preparation)
* [1.1 Install Required Host Packages](#11-install-required-host-packages) * [1.1 Install required host packages](#11-install-required-host-packages)
* [1.1.1 Recommended Additional Packages for Graphical Support and Analysis](#111-recommended-additional-packages-for-graphical-support-and-analysis) * [1.1.1 Recommended additional packages for GUI support and analysis](#111-recommended-additional-packages-for-gui-support-and-analysis)
* [1.2 Prepare Git (if necessary)](#12-prepare-git-if-necessary) * [1.2 Prepare Git (if necessary)](#12-prepare-git-if-necessary)
* [1.3 Clone Init Script](#13-clone-init-script) * [1.3 Clone the init script](#13-clone-the-init-script)
* [1.4 Run Init Script](#14-run-init-script) * [1.4 Run the init script](#14-run-the-init-script)
* [1.5 Build Environment Structure](#15-build-environment-structure) * [1.4.1 Structure of the build environment](#141-structure-of-the-build-environment)
* [2. Building an Image](#2-building-an-image) * [2. Build an image](#2-build-an-image)
* [2.1 Choose a Box](#21-choose-a-box) * [2.1 Choose a box](#21-choose-a-box)
* [2.2 Start the Environment Script](#22-start-the-environment-script) * [2.2 Start the environment script](#22-start-the-environment-script)
* [2.3 Create the Image](#23-create-the-image) * [2.3 Create the image](#23-create-the-image)
* [3. Updates](#3-updates) * [3. Updating](#3-updating)
* [3.1 Update Image](#31-update-image) * [3.1 Update an image](#31-update-an-image)
* [3.2 Update Package](#32-update-package) * [3.2 Update a package](#32-update-a-package)
* [3.3 Update Meta-Layer Repositories](#33-update-meta-layer-repositories) * [3.3 Update meta‑layer repositories](#33-update-meta-layer-repositories)
* [4. Customizations](#4-customizations) * [4. Customisation](#4-customisation)
* [4.1 Configuration](#41-configuration) * [4.1 Configuration](#41-configuration)
* [4.1.1 Configuration Files](#411-configuration-files) * [4.1.1 Configuration files](#411-configuration-files)
* [4.1.2 bblayers.conf](#412-bblayersconf) * [4.1.2 bblayers.conf](#412-bblayersconf)
* [4.1.3 Resetting Configuration](#413-resetting-configuration) * [4.1.3 Reset configuration](#413-reset-configuration)
* [4.3 Recipes](#43-recipes) * [4.3 Recipes](#43-recipes)
* [4.4 Packages](#44-packages) * [4.4 Packages](#44-packages)
* [4.4.1 Editing Source Code in the Workspace (Example)](#441-editing-source-code-in-the-workspace-example) * [4.4.1 Edit source code in the workspace (example)](#441-edit-source-code-in-the-workspace-example)
* [5. Forcing a Rebuild of a Single Package](#5-forcing-a-rebuild-of-a-single-package) * [5. Force a rebuild of a single package](#5-force-a-rebuild-of-a-single-package)
* [6. Forcing a Full Image Rebuild](#6-forcing-a-full-image-rebuild) * [6. Force a complete image build](#6-force-a-complete-image-build)
* [7. License](#7-license) * [7. Licence](#7-licence)
* [8. Further Information](#8-further-information) * [8. Further information](#8-further-information)
## 1. Preparation ## 1. Preparation
At this point, it is recommended to use the provided Docker container, as it already covers essential steps needed to get started with minimal changes to your system. [See docker-buildenv](https://github.com/tuxbox-neutrino/docker-buildenv). In this case, you can jump straight to [running the initialization](#14-run-init-script). It is recommended to use the dedicated Docker container, because it already covers the essential steps so that you can start with as few adjustments to your host system as possible. See [docker-buildenv](https://github.com/tuxbox-neutrino/docker-buildenv). In that case you can jump straight to [initialisation](#14-run-the-init-script).
**NOTE:** [docker-buildenv](https://github.com/tuxbox-neutrino/docker-buildenv) fully replaces the [Tuxbox-Builder](https://sourceforge.net/projects/n4k/files/Tuxbox-Builder) VM, which is no longer maintained. **NOTE:** [docker-buildenv](https://github.com/tuxbox-neutrino/docker-buildenv) completely replaces the [Tuxbox‑Builder](https://sourceforge.net/projects/n4k/files/Tuxbox-Builder) VM, which is no longer maintained.
The paths shown here are based on those generated by the init script. Some entries appear as `<placeholder>` and need to be adjusted locally. [See schema](#14-run-init-script). The paths given here are based on defaults created by the init script. Some entries are shown as `<placeholder>` and have to be adapted locally. See [schema](#14-run-the-init-script).
### 1.1 Install Required Host Packages ### 1.1 Install required host packages
**Note:** If you are using other distributions, see: [Yocto Project Quick Build](https://docs.yoctoproject.org/3.2.4/ref-manual/ref-system-requirements.html#supported-linux-distributions) **Note:** When using other distributions see: [Yocto Project Quick Build](https://docs.yoctoproject.org/3.2.4/ref-manual/ref-system-requirements.html#supported-linux-distributions)
**Debian 11** Debian 11
```bash ```bash
sudo apt-get install -y gawk wget git-core diffstat unzip texinfo gcc-multilib build-essential \ sudo apt-get install -y gawk wget git-core diffstat unzip texinfo gcc-multilib build-essential \
@@ -60,7 +60,7 @@ sudo apt-get install -y gawk wget git-core diffstat unzip texinfo gcc-multilib b
libxml2-utils ninja-build default-jre clisp libcapstone4 libsdl2-dev doxygen libxml2-utils ninja-build default-jre clisp libcapstone4 libsdl2-dev doxygen
``` ```
**Debian 12** Debian 12
```bash ```bash
sudo apt-get install -y gawk wget git diffstat unzip texinfo gcc-multilib build-essential \ sudo apt-get install -y gawk wget git diffstat unzip texinfo gcc-multilib build-essential \
@@ -69,7 +69,7 @@ sudo apt-get install -y gawk wget git diffstat unzip texinfo gcc-multilib build-
ninja-build default-jre clisp libcapstone4 libsdl2-dev doxygen ninja-build default-jre clisp libcapstone4 libsdl2-dev doxygen
``` ```
#### 1.1.1 Recommended Additional Packages for Graphical Support and Analysis #### 1.1.1 Recommended additional packages for GUI support and analysis
```bash ```bash
sudo apt-get install -y gitk git-gui meld cppcheck clazy kdevelop sudo apt-get install -y gitk git-gui meld cppcheck clazy kdevelop
@@ -77,203 +77,203 @@ sudo apt-get install -y gitk git-gui meld cppcheck clazy kdevelop
### 1.2 Prepare Git (if necessary) ### 1.2 Prepare Git (if necessary)
The init script uses Git to clone the meta-layer repositories. If you don’t have Git configured yet, please set up your global Git user data; otherwise, you’ll get unnecessary warnings while the script runs. The init script uses Git to clone the meta‑layer repositories. If you do not yet have a configured Git installation, please set up your global Git user data, otherwise you will repeatedly see warnings while the script is running.
```bash ```bash
git config --global user.email "you@example.com" git config --global user.email "you@example.com"
git config --global user.name "Your Name" git config --global user.name "Your Name"
``` ```
### 1.3 Clone Init Script ### 1.3 Clone the init script
```bash ```bash
git clone https://github.com/tuxbox-neutrino/buildenv.git && cd buildenv git clone https://github.com/tuxbox-neutrino/buildenv.git && cd buildenv
``` ```
### 1.4 Run Init Script ### 1.4 Run the init script
```bash ```bash
./init && cd poky-3.2.4 ./init && cd poky-3.2.4
``` ```
### 1.5 Build Environment Structure ### 1.4.1 Structure of the build environment
After [step 1.4](#14-run-init-script), you should see a structure similar to this: After [step 1.4](#14-run-the-init-script) your directory tree should look roughly like this:
``` ````
.buildenv .buildenv
├── dist <-- Shared folder for HTTP server (if set up) http://localhost, http://localhost:8080, needed for IPK feeds and images ├── dist <-- Public folder for your HTTP server (if configured) http://localhost or http://localhost:8080; required for IPK feeds and images
│ └── {DISTRO_VERSION} <-- Contains generated images and packages (symlinks to the deploy dirs inside build subdirectories) │ └── {DISTRO_VERSION} <-- generated images and packages live here (symlinks point to the deploy directories inside the build sub‑directories)
: :
├── init.sh <-- init script ├── init.sh <-- the init script
├── local.conf.common.inc <-- global user configuration, included in custom config ├── local.conf.common.inc <-- global user configuration, included by the per‑machine configuration
: :
├── log <-- folder for logs, contains logs for each init script run ├── log <-- log folder, contains a log for every run of the init script
: :
└── poky-{DISTRO_VERSION} <-- After step 1.4 you’ll be here. Contains the build system core and meta-layers └── poky-{DISTRO_VERSION} <-- after step 1.4 you are here. This contains the build system core and the meta‑layers
│ │
: :
└── build <-- Build subdirectories; after step 2.2 you’ll be inside one of these └── build <-- build sub‑directories live here; after step 2.2 you are inside one of the machine build sub‑directories
├── <machine x> <-- Build dir for machine type x ├── <machine x> <-- build sub‑directory for machine type x
│ ├── conf <-- Folder for layers and custom config │ ├── conf <-- configuration folder for layers and user settings
│ │ └── bblayers.conf <-- Config for included meta-layers │ │ ├── bblayers.conf <-- configuration file for the meta‑layers
│ │ └── local.conf <-- Custom config for one machine type │ │ └── local.conf <-- user configuration for this machine type
│ : │ :
│ ├── (tmp) <-- Work dir, auto-created during build │ ├── (tmp) <-- working directory automatically created by BitBake when building targets
│ └── (workspace) <-- Workspace, created when running devtool │ └── (workspace) <-- workspace automatically created by ```devtool modify```
: :
└── <machine y> <-- Another build dir for machine type y └── <machine y> <-- another build sub‑directory for machine type y
``` ````
## 2. Building an Image ## 2. Build an image
Make sure you are in the directory shown in the [schema](#15-build-environment-structure): Make sure you are inside the `poky` directory as shown in the [schema](#141-structure-of-the-build-environment):
``` ```
poky-{DISTRO_VERSION} poky-{DISTRO_VERSION}
``` ```
### 2.1 Choose a Box ### 2.1 Choose a box
List available devices: Show list of available devices:
```bash ```bash
ls build ls build
<machine> <machine1> <machine2> <machine3>...
``` ```
### 2.2 Start the Environment Script **Note:** Only the machine types shown here can be built. Use exactly the names printed here in the following steps—typos will break things!
Run the environment script for the desired box from the list once! You will be placed into the corresponding build subdirectory. ### 2.2 Start the environment script
Run the environment script **once** for exactly **one** box from the list. You will automatically end up in the corresponding build sub‑directory.
```bash ```bash
. ./oe-init-build-env build/<machine> . ./oe-init-build-env build/<machine>
``` ```
From now on, as long as you remain in the generated environment within the open shell in the chosen build subdirectory, you don’t need to re-run this script and can go straight to [step 2.3](#23-create-the-image) to build images or any packages. As long as you stay inside the created environment within the open shell and inside the desired build sub‑directory, you do not have to run this script again and can build images or any packages via [step 2.3](#23-create-the-image).
**Note:** You can also open additional shells and thus create parallel build environments for other box types, switching to the appropriate terminal as needed and even building in parallel, provided your system can handle it. **Note:** You can open additional shells and therefore additional build environments for other box types in parallel. Simply switch to the terminal you need; parallel builds are possible if your system is powerful enough.
### 2.3 Create the Image ### 2.3 Create the image
```bash ```bash
bitbake neutrino-image bitbake neutrino-image
``` ```
This can take a while. Some warnings can be ignored. Errors related to setscene tasks are usually harmless, but build and package task errors typically abort the process. [Please report the error or share your solution](https://forum.tuxbox-neutrino.org/forum/viewforum.php?f=77). Help is always welcome. This command builds the complete image with all the packages belonging to it, including packages that, depending on your configuration, are built but not installed into the image. This can take a while. Some warnings can be ignored. Errors in the setscene tasks are no problem, but any errors during build or package tasks usually abort the process. [Please report errors or share your solution](https://forum.tuxbox-neutrino.org/forum/viewforum.php?f=77). Help is always welcome.
When done, you should see a message like this: If everything finishes, you should see a message similar to:
```bash ```bash
NOTE: Tasks Summary: Attempted 4568 tasks of which 4198 didn't need to be rerun and all succeeded. "NOTE: Tasks Summary: Attempted 4568 tasks of which 4198 didn't need to be rerun and all succeeded."
``` ```
<span style="color: green;">That’s it...</span> <span style="color: green;">That's it …</span>
Results can be found under: You will find the results under:
```bash ```bash
buildenv/poky-{DISTRO_VERSION}/build/<machine>/tmp/deploy buildenv/poky-{DISTRO_VERSION}/build/<machine>/tmp/deploy
``` ```
or in the shared directory: or in the public directory:
```bash ```bash
buildenv/dist/<Image-Version>/<machine>/ buildenv/dist/<Image-Version>/<machine>/
``` ```
If you have a web server pointing to the shared directory: If a web server is configured that points to the public directory:
```bash ```bash
http://localhost/{DISTRO_VERSION} or with port number http://localhost:8080/{DISTRO_VERSION} http://localhost/{DISTRO_VERSION} or, with port number, http://localhost:8080/{DISTRO_VERSION}
``` ```
## 3. Updates ## 3. Updating
Manual package updates are not required. These are handled automatically on every bitbake invocation, including dependencies. If you want full control over certain package sources, you can place them in the workspace for each package; see [4.4 Packages](#44-packages). You do not need to update packages manually. BitBake does this automatically whenever a target is built, including its dependencies. If you want full control over certain package sources, you can place them in the workspace for each package, see [4.4 Packages](#44-packages). If no updates are necessary, BitBake will simply skip the builds.
If no updates are needed, builds are skipped automatically. ### 3.1 Update an image
### 3.1 Update Image
```bash ```bash
bitbake neutrino-image bitbake neutrino-image
``` ```
### 3.2 Update Package ### 3.2 Update a package
```bash ```bash
bitbake <package> bitbake <package>
``` ```
### 3.3 Update Meta-Layer Repositories ### 3.3 Update meta‑layer repositories
Running the init script with the `--update` parameter updates the included meta-layers to the state of their remote repositories. Running the init script with the `--update` parameter upgrades the included meta‑layers to the state of their remote repositories.
```bash ```bash
./init --update ./init --update
``` ```
If you have made changes to the meta-layers, the init script’s update routines should temporarily stash or rebase unstashed changes on the local repositories. Of course, you can manually update your local meta-layers for meta-neutrino and machine-layer repos, but you must resolve any conflicts manually. If you have modified the meta‑layers, the update routines invoked by the init script should temporarily stash or rebase your uncommitted changes onto the local repository. Of course you can update your local meta‑layers (meta‑neutrino and machine layers) manually. Conflicts must always be resolved manually.
**Note:** Configuration files remain mostly untouched, but variable names may be migrated. New or changed settings are not auto-updated. Please review your configuration if necessary. **Note:** Configuration files remain largely untouched, but variable names may be migrated. New or changed settings are not altered. Please check your configuration if necessary.
## 4. Customizations ## 4. Customisation
### 4.1 Configuration ### 4.1 Configuration
It is recommended to build for the first time without modified configuration files to get a feel for the build process and see results quickly. The configuration options are extensive and not easy for beginners to grasp. However, OpenEmbedded and the Yocto Project are thoroughly documented and provide the best information source. It is recommended to do the first build without modified configuration files so you get a feel for the build process and can see results quickly.
The number of possible settings is huge and not really easy to grasp for beginners. OpenEmbedded, and especially the Yocto Project, is however very well documented and is the best source of information.
#### 4.1.1 Configuration Files #### 4.1.1 Configuration files
> \~/buildenv/poky-3.2.4/build/`<machine>`/conf/local.conf > \~/buildenv/poky-3.2.4/build/`<machine>`/conf/local.conf
This file, located in the build directory for each machine type, is the actual user configuration file intended by the build system. In this environment, it contains only a few lines and includes a global configuration. This file is **only** valid for its specific machine type. You can add entries here that apply only to that machine type. [See schema](#14-run-init-script) This file resides in the build directory of each machine type and is the actual user configuration file originally intended by the build system. In this environment, however, this `local.conf` contains only a few lines and includes a global configuration. This file is **only** valid for the machine type it belongs to. Therefore you can add entries here that should apply only to that machine type. See the [schema](#14-run-the-init-script).
> \~/buildenv/local.conf.common.inc > \~/buildenv/local.conf.common.inc
This file holds settings that apply to all machine types and is generated from the template `~/buildenv/local.conf.common.inc.sample` on the first run of the init script. This file contains settings that apply to all machine types and is generated on the first run of the init script from the template `~/buildenv/local.conf.common.inc.sample`.
Although you could use the build system’s intended `./build/<machine>/conf/local.conf` as the primary config file for each machine separately, this would increase maintenance overhead. Hence, `~/buildenv/local.conf.common.inc` is only included in `./build/<machine>/conf/local.conf`. You *could* use the build‑system‑provided `./build/<machine>/conf/local.conf` as the primary configuration file for every machine type separately, but that would increase maintenance effort. Therefore `~/buildenv/local.conf.common.inc` is just included by `./build/<machine>/conf/local.conf`.
**Note on** `~/buildenv/local.conf.common.inc.sample`**:** This is a template and should remain untouched to avoid conflicts when updating the build-script repository and to see what has changed. **Note on** `~/buildenv/local.conf.common.inc.sample`**:** This is only a template and should remain untouched to avoid conflicts when updating the build‑script repository and to see what might have changed.
After updating the build-script repository, new or changed options may have been added or removed and not merged into your included config file. You should consider these cases and review and adjust your configuration if necessary. After an update of the build‑script repository, new or changed options may have been added or removed that are not present in the included configuration file. Keep this in mind and check and adjust your configuration if needed.
#### 4.1.2 bblayers.conf #### 4.1.2 bblayers.conf
> \~/buildenv/poky-3.2.4/build/`<machine>`/conf/bblayers.conf > \~/buildenv/poky-3.2.4/build/`<machine>`/conf/bblayers.conf
This file is usually adjusted on the first run of the init script and typically only needs changes when you want to add, remove, or replace layers. This file is normally adjusted on the first run of the init script and usually needs to be changed only if you want to add, remove or replace layers.
#### 4.1.3 Resetting Configuration #### 4.1.3 Reset configuration
If you want to reset your machine configurations, rename (rather than delete) the conf directory and rerun the init script. If you want to reset your machine configurations, rename the `conf` directory (deleting is not recommended) and run the init script again.
```bash ```bash
mv ~/buildenv/poky-3.2.4/build/<machine>/conf ~/buildenv/poky-3.2.4/build/<machine>/conf.backup mv ~/buildenv/poky-3.2.4/build/<machine>/conf ~/buildenv/poky-3.2.4/build/<machine>/conf.01
cd ~/buildenv cd ~/buildenv
./init ./init
``` ```
### 4.3 Recipes ### 4.3 Recipes
**Unless you are directly contributing to Poky layers, do not modify the official Poky layers (meta-layers)!** The Yocto Project strongly discourages this practice, as you risk losing your work during updates and creating hard-to-maintain conflicts. **Unless you are directly involved in developing the Poky layers, do not modify the official Poky meta‑layers! The Yocto Project explicitly advises against this, because you risk losing all your work during updates and creating incompatibilities or conflicts that are hard to maintain. The usual approach to complete, extend or override existing official recipes is the use of [.bbappend files](https://docs.yoctoproject.org/3.2.4/dev-manual/dev-manual-common-tasks.html#using-bbappend-files-in-your-layer).**
The usual way to extend or override existing recipes is with `.bbappend` files. [Learn more](https://docs.yoctoproject.org/3.2.4/dev-manual/dev-manual-common-tasks.html#using-bbappend-files-in-your-layer). Alternatively—although also not really recommended—you could copy official recipes into your own meta‑layers and adjust them; the build system will typically prefer these copies. In that case, however, you are responsible for keeping those recipes up to date, which can unnecessarily increase maintenance effort.
Alternatively (though also not recommended), you could copy official recipes into your own meta-layers and modify them, in which case you are responsible for keeping them up to date, increasing maintenance overhead. The same principle applies to recipes from your own meta‑layers such as `meta-neutrino` or the machine layers. Anyone who [actively wants to work on the recipes](https://docs.yoctoproject.org/current/ref-manual/devtool-reference.html#modifying-an-existing-recipe) is of course welcome to do so.
The same principle applies to your own meta-layers like meta-neutrino or machine layers. If you want to actively work on recipes, feel free to [contribute](https://docs.yoctoproject.org/current/ref-manual/devtool-reference.html#modifying-an-existing-recipe).
### 4.4 Packages ### 4.4 Packages
If you want full control over a package’s source code (e.g., to fix or actively develop something), move the source you want to work on into the workspace. See the Neutrino example below. If you want full control over a package’s source code—e.g. to fix something or to develop actively—you should move the source you want to work on into the workspace. See the [Neutrino example](#441-edit-source-code-in-the-workspace-example).
See [devtool](https://docs.yoctoproject.org/current/ref-manual/devtool-reference.html) and especially [devtool modify](https://docs.yoctoproject.org/current/ref-manual/devtool-reference.html#modifying-an-existing-recipe). In the workspace, you’re guaranteed that the build system won’t touch the source. If you ignore this, you might find your changes repeatedly cleaned or overridden, losing or rendering them incompatible. In the default local config, [rm\_work](https://docs.yoctoproject.org/ref-manual/classes.html#ref-classes-rm-work) is enabled, which cleans each package’s work directory after build, leaving only logs. See [devtool](https://docs.yoctoproject.org/current/ref-manual/devtool-reference.html) and especially [devtool modify](https://docs.yoctoproject.org/current/ref-manual/devtool-reference.html#modifying-an-existing-recipe). In the workspace you are guaranteed that the build system will not touch the source code. If you ignore this, modified source code might be deleted or overwritten over and over again. Your changes could therefore be lost or become incompatible. In the default local configuration, [rm\_work](https://docs.yoctoproject.org/ref-manual/classes.html#ref-classes-rm-work) is enabled, which cleans up each package’s work directory after every successful build, so that nothing but a few logs remains.
#### 4.4.1 Editing Source Code in the Workspace (Example) #### 4.4.1 Edit source code in the workspace (example)
This example uses Neutrino, but the procedure applies to most packages. Neutrino is used as an example here, but the workflow is essentially the same for any other package.
```bash ```bash
~/buildenv/poky-3.2.4/build/hd61$ devtool modify neutrino ~/buildenv/poky-3.2.4/build/hd61$ devtool modify neutrino
@@ -281,7 +281,7 @@ NOTE: Starting bitbake server...54cf81d24c147d888c"
... ...
workspace = "3.2.4:13143ea85a1ab7703825c0673128c05845b96cb5" workspace = "3.2.4:13143ea85a1ab7703825c0673128c05845b96cb5"
Initialising tasks: 100% |########################################################################################################| Time: 0:00:01 Initialising tasks: 100% |###################################################################################################################################################################################################| Time: 0:00:01
Sstate summary: Wanted 0 Found 0 Missed 0 Current 10 (0% match, 100% complete) Sstate summary: Wanted 0 Found 0 Missed 0 Current 10 (0% match, 100% complete)
NOTE: Executing Tasks NOTE: Executing Tasks
NOTE: Tasks Summary: Attempted 83 tasks of which 80 didn't need to be rerun and all succeeded. NOTE: Tasks Summary: Attempted 83 tasks of which 80 didn't need to be rerun and all succeeded.
@@ -290,84 +290,84 @@ INFO: Source tree extracted to /home/<user>/buildenv/poky-3.2.4/build/hd61/works
INFO: Recipe neutrino-mp now set up to build from /home/<user>/buildenv/poky-3.2.4/build/hd61/workspace/sources/neutrino INFO: Recipe neutrino-mp now set up to build from /home/<user>/buildenv/poky-3.2.4/build/hd61/workspace/sources/neutrino
``` ```
The Neutrino source code is now in `/buildenv/poky-3.2.4/build/hd61/workspace/sources/neutrino`. You can work on it there. From now on, the build system will not clone Neutrino from the remote Git repo but will use only your local workspace sources, managed by you. You will now find the Neutrino source code under `/buildenv/poky-3.2.4/build/hd61/workspace/sources/neutrino`. You can work on it there. This means that the build system will no longer clone or automatically update the Neutrino sources from the remote Git repo on its own, but will from now on only use the local sources inside the workspace, which you maintain yourself. It is a Git repo created by devtool; you can link it to the original remote repository if that has not already been done.
When you run: If you now run:
```bash ```bash
bitbake neutrino bitbake neutrino
``` ```
... Neutrino will build from the local workspace repo: …Neutrino will from now on be built only from the local repo in the workspace:
```bash ```bash
NOTE: Started PRServer with DBfile: /home/<user>/buildenv/poky-3.2.4/build/hd61/cache/prserv.sqlite3, IP: 127.0.0.1, PORT: 34211, PID: 56838 NOTE: Started PRServer with DBfile: /home/<user>/buildenv/poky-3.2.4/build/hd61/cache/prserv.sqlite3, IP: 127.0.0.1, PORT: 34211, PID: 56838
... ...
workspace = "3.2.4:13143ea85a1ab7703825c0673128c05845b96cb5" workspace = "3.2.4:13143ea85a1ab7703825c0673128c05845b96cb5"
Initialising tasks: 100% |########################################################################################################| Time: 0:00:01 Initialising tasks: 100% |###################################################################################################################################################################################################| Time: 0:00:01
Sstate summary: Wanted 122 Found 116 Missed 6 Current 818 (95% match, 99% complete) Sstate summary: Wanted 122 Found 116 Missed 6 Current 818 (95% match, 99% complete)
NOTE: Executing Tasks NOTE: Executing Tasks
NOTE: neutrino-mp: compiling from external source tree /home/<user>/buildenv/poky-3.2.4/build/hd61/workspace/sources/neutrino NOTE: neutrino-mp: compiling from external source tree /home/<user>/buildenv/poky-3.2.4/build/hd61/workspace/sources/neutrino
NOTE: Tasks Summary: Attempted 2756 tasks of which 2741 didn't need to be rerun and all succeeded. NOTE: Tasks Summary: Attempted 2756 tasks of which 2741 didn't need to be rerun and all succeeded.
``` ```
**Tip:** For Neutrino, it’s also recommended to transfer the associated `libstb-hal` to the workspace: **Note!** In the specific case of Neutrino it is advisable to move not only its source code but also the associated `libstb-hal` into the workspace.
```bash ```bash
devtool modify libstb-hal devtool modify libstb-hal
``` ```
## 5. Forcing a Rebuild of a Single Package ## 5. Force a rebuild of a single package
Sometimes a target fails for unknown reasons. Avoid panicking and wiping your workspace or sstate cache. You can clean up a specific target without breaking everything else. In some cases a target may abort for whatever reason. There is no need to panic and wipe your working directory and the expensive sstate‑cache. You can perform clean‑ups for every target individually without destroying an otherwise working system.
Broken archive URLs often cause failures. These errors are shown, and you can verify the URL. They often resolve after a few minutes. Broken archive URLs in particular can lead to aborts. These errors are always displayed and you can check the URLs. Often it is just temporary server issues and works again after a few minutes.
To ensure a recipe actually has an issue, clean and rebuild the entire target’s data: To make sure that the recipe in question actually has a problem it is sensible to clean the target completely and build it again. To do this you must clean all package, build and cached data belonging to that target.
```bash ```bash
bitbake -c cleansstate <target> bitbake -c cleansstate <target>
``` ```
Then rebuild: then rebuild:
```bash ```bash
bitbake <target> bitbake <target>
``` ```
## 6. Forcing a Full Image Rebuild ## 6. Force a complete image build
The init script provides the `--reset` option: The init script provides the `--reset` option for this.
```bash ```bash
./init --reset ./init --reset
# Follow instructions # Follow instructions
``` ```
Manually, rename the tmp directory in the respective build subdirectory. You can delete it later to free space if you’re sure you don’t need it: You can achieve the same manually by renaming the `tmp` directory in the respective build sub‑directory. You can delete it later if you want to free disk space or are sure you no longer need it:
```bash ```bash
mv tmp tmp.backup mv tmp tmp.01
``` ```
Then rebuild the image: Then build the image again:
```bash ```bash
bitbake neutrino-image bitbake neutrino-image
``` ```
If you haven’t deleted the cache, the image should finish relatively quickly. That’s why retaining the cache is recommended. The cache directory is defined by `${SSTATE_DIR}` and can be customized in the configuration. If you did **not** delete the cache, the image should be built in a relatively short time. For that reason you are encouraged to keep the cache. The directory where the cache is located is controlled by the variable `${SSTATE_DIR}` and can be changed in the configuration.
This directory is valuable, and deleting it is rarely needed. Note that builds take much longer after deleting the cache. This directory is quite valuable and it is rarely necessary to delete it. Please bear in mind that the build process will take significantly longer after deleting the cache.
## 7. License ## 7. Licence
``` ```
MIT License MIT License
``` ```
## 8. Further Information ## 8. Further information
More information on the Yocto build system: More information on the Yocto build system: