buildenv/README_en.md

<!-- LANGUAGE_LINKS_START -->
[🇩🇪 German](README_de.md) | <span style="color: grey;">🇬🇧 English</span>
<!-- LANGUAGE_LINKS_END -->

@Html_0@
@Html_1@🇩🇪 german@html_2@| [🇬🇧 English](readme_en.md)
@Html_3@

This script serves as a tool to simplify the creation of an environment for development and the build process for images that run with neutrino as a user interface on different hardware platforms. It automates a few steps that are required for the establishment of a consistent and functional development and build environment by adjusting the necessary dependencies and basic configurations as well as meta-layers and enables user-defined settings. The script aims to offer a basis on which you can build and experiment to create, update and maintain your own adapted versions of Tuxbox-Neutrino Images.

[@Image_0@](@url_placeholder_0@)

- [1. Preparation](@anchor_0@)
	- [1.1 Install the required host packages](@anchor_1@)
		- [1.1.1 Recommended additional packages for graphic support and analysis](@anchor_2@)
	- Prepare [1.2 git (if necessary)](@anchor_3@)
	- [1.3 Init script clone](@anchor_4@)
	- [1.4 Run init script](@anchor_5@)
	- [1.5 Structure of the build environment](@anchor_6@)
- [2. Build image](@anchor_7@)
	- Select [2.1 box](@anchor_8@)
	- [2.2 Start ambient script](@anchor_9@)
	- [2.3 Create image](@anchor_10@)
- [3. Update](@anchor_11@)
	- [3.1 Update image](@anchor_12@)
	- [3.2 update package](@anchor_13@)
	-[3.3 Meta-layer repository](@anchor_14@)
- [4. Own adjustments](@anchor_15@)
	- [4.1 configuration](@anchor_16@)
		- [4.1.1 Configuration files](@anchor_17@)
		- [4.1.2 bblayers.conf](@anchor_18@)
		- [4.1.3 Reset configuration](@anchor_19@)
	- [4.3 Recipes](@anchor_20@)
	- [4.4 packages](@anchor_21@)
		- [4.4.1 Edit source code in WorkSpace (example)](@anchor_22@)
- [5. Forced a new building of a single package](@anchor_23@)
- [6. Forced complete image construction](@anchor_24@)
- [7. License](@anchor_25@)
- [8. Further information](@anchor_26@)
## 1. Preparation

At this point, it is recommended to use the Docker container provided for this, as this has already been done with significant steps in order to be able to get started with as few adjustments to your system. [See Docker-Buildenv](@url_placeholder_1@). In this case you can start [with the initialization](@anchor_27@).

** Note: ** [Docker-Buildenv](@url_placeholder_2@) replaces the [Tuxbox-Builder](@url_placeholder_3@)-VM. Their maintenance is no longer continued.

Paths specified here are based on specifications that are generated by the Init script. Some entries are shown as @ Code_Block_0 @, which must be adapted locally. [See scheme](@anchor_28@)
### 1.1 Install the necessary host packages

** Note: ** When using other distributions see: [Yocto Project Quick Build](@url_placeholder_4@)

Debian 11

@Code_Block_1@

Debian 12

@Code_Block_2@
#### 1.1.1 Recommended additional packages for graphic support and analysis

@Code_Block_3@
### Prepare 1.2 git (if necessary)

The Init script uses Git to clone the meta-layer repositors. If there is still no configured GIT, please set your global Git user data, otherwise while the script goes through, unnecessarily indicated this.

@Code_Block_4@
### 1.3 Init script clone

@Code_Block_5@
### 1.4 Execute the init script

@Code_Block_6@
### 1.5 Structure of the build environment

According to [step 1.4](@anchor_29@) this structure should have been created:

@Code_Block_7@
## 2. Building image

Make sure you are shown here as in the [scheme](@anchor_30@):

@Code_Block_8@
### 2.1 Select box

Have list available devices displayed:

@Code_Block_9@
### 2.2 Start ambient script

Perform the surrounding script for the box desired from the list once! You will then automatically get into the right build subdirectory.

@Code_Block_10@

As long as you are now in the desired build subdirectory with the environment generated within the opened shell, you don't have to do this script again and you can build [Step 2.3](@anchor_31@) Images or any packages.

** Note: ** You can also create other shells and thus build environments for further box types in parallel and switch to the corresponding terminal as required and have it built in parallel if your system gives.
### 2.3 Create image

@Code_Block_11@

It can take a while. Some warning messages can be ignored. Error messages that affect the setsCene tasks are not a problem, but errors during the build and package tasks break the process in most cases.  [In this case please report the error or share your solution](@url_placeholder_5@). Help is very welcome.

If everything is done, a message similar to this should appear:

@Code_Block_12@

@Html_4@that's ...@html_5@

You can find results at:

@Code_Block_13@

Or in the release directory:

@Code_Block_14@

If a web server is set up that points to the release directory:

@Code_Block_15@
## 3. Update

Manual updates of the packages are not required. This is carried out automatically with Bitbake for every target. This also applies to possible dependencies. If you want to have full control over certain package sources, you can take them off for each package in the workspace provided for this, see [4.4 packages](@anchor_32@).
If no updates are necessary, the builds will automatically skip.
### 3.1 Update image

@Code_Block_16@
### 3.2 update package

@Code_Block_17@
### 3.3 Update meta-layer repository

The execution of the init script with the @ Code_Block_18 @ parameter updates the contained meta-layer to the status of the remote repository.

@Code_Block_19@

If you have made changes to the meta-layers, the update routines of the init script that did not steady or rebassage are not fixed to the local repository of the init script. Of course, you can manually update your local meta-layer for meta-neutrino and machine-layer repository. However, conflicts must always be dissolved manually.

** Note: ** Configuration files are essentially unaffected, but possible variables are migrated. New or changed settings are not changed. Please check the configuration.
## 4. Own adjustments

### 4.1 Configuration

It is recommended to build for the first time without changed configuration files to get an impression of how the build process works and to see the results as quickly as possible.
The setting options are very extensive and not really manageable for beginners. Openembedded in particular the Yocto-Project is very
Comprehensively documented and offers the best source of information.
#### 4.1.1 Configuration files

> ~/BUILDENV/POKY-3.2.4/Build/@Code_Block_20@/Conf/Local.conf

This file is located in the building directory of the respective machine type and is the actual custom configuration file, which is originally intended for this. However, this local.conf contains only a few lines in this environment and includes a global configuration. This file is only valid ** for the machine type it supported. Here you can therefore add supplementary entries in front, which are only intended for the machine type. [See also scheme](@anchor_33@)

> ~/buildenv/local.conf.common.inc

This file contains settings that apply to all machine types and is generated when the Init scripts from the template @ Code_Block_21 @

The @ Code_Block_22 @ provided by the build system could be used as the primary configuration file for each machine type, as it is provided to by the build system, but that would unnecessarily increase the maintenance effort. That's why @ Code_Block_23 @ is only in @ Code_Block_24 @ included,

** Note on ** @Code_Block_25 @**: ** This is just a template and should remain unaffected to avoid possible conflicts when updating the build script repositors and to see what could have changed.

After an updating of the Build Script repository, new or changed options could have been added or removed that are not transferred to the included configuration file. This case should be taken into account in your own configuration and check and adapt if necessary.
#### 4.1.2 Bblayers.conf

> ~/Builddenv/Poky-3.2.4/Build/@Code_Block_26@/conflayers.conf

This file is usually adjusted when the Init script is carried out for the first time and usually only needs to be adjusted if you want to add, remove or replace layers.
#### 4.1.3 Reset configuration

If you want to reset your machine configurations, please name the CONF directory (delete is not recommended) and carry out the Init script again.

@Code_Block_27@
### 4.3 Recipes

** Unless you are directly involved in the development of the Poky levels, do not change the official Poky levels (meta-layer)! This is expressly not recommended by the Yocto project, since you run the risk of losing your entire work with updates and creating incompatibilities or conflicts that are difficult to wait. The usual procedure to complete, expand or overwrite existing official recipes is the [Use of .bbappend](@url_placeholder_6@)-files. **

Alternatively, but not really recommended, you could take copies of official reciepes into your own meta-layer and adapt, since these are usually preferred by the build system. In such a case, however, one is responsible for keeping these recipes up -to -date, but this can unnecessarily increase the maintenance effort.

In principle, the same applies to recipes from your own meta-layers such as Meta-Neutrino or machine layers. But if you want to work actively on the recipes](@url_placeholder_7@), you are welcome to do so.
### 4.4 packages

If you want to have full control over a package source code, e.g. to develop something or actively develop, the source code you want to work should be moved to the workspace. See: [Example for Neutrino](@anchor_34@)

See [Devtool](@url_placeholder_8@) and in particular [Devtool modify](@url_placeholder_9@). In the workspace you have the guarantee that the source code will not be touched by the build system. If you do not pay attention to this, it can happen, for example, that changed source code is repeatedly deleted or modified. Own adjustments can therefore be lost or become incompatible. In the local standard configuration [RM_Work](@url_placeholder_10@) is activated, which ensures that after each completed construction of a package, the respective working directory is tidied up, so that nothing will be left except for some logs.
#### 4.4.1 Edit source code in WorkSpace (example)

Neutrino is used here, but this procedure essentially applies to all other packages.

@Code_Block_28@

The source code for Neutrino is now located at @ Code_Block_29 @. You can then work on it. This means that the build system no longer clits the neutrino sources on its own from the remote git repo, but from now on only uses the local sources within the workspace that you have to manage yourself. This is a GIT repo created by Devtool, in which you can integrate to the original remote repository, unless this is the case.

If you now go out ...

@Code_Block_30@

... from now on will only be built by the local repo in the workspace:

@Code_Block_31@

** Note! ** In the special case of Neutrino, it is advisable not only to transfer its source code, but also the associated @ Code_Block_32 @ to the WorkSpace.

@Code_Block_33@
## 5. Forced a new construction of a single package

In some cases it can happen that a target, for whatever reason. So you should never panic and therefore delete the work folder and the expensive Sstate cache. Realization can be made individually for each target without flattening an otherwise functioning system.

Defective archive URLs in particular can lead to demolition. However, these errors are always displayed and the URL can be checked. Often it is only due to the servers and even work again after a few minutes.

In order to ensure whether the relevant recipe actually has a problem, it makes sense to completely clean up and rebuild the Target in question. To achieve this, all associated package, build and cached data must be adjusted.

@Code_Block_34@
Then build again:

@Code_Block_35@
## 6. Forced complete image construction

The Init script provides the option @ inline_code_0 @.

@Code_Block_36@

You can also manually achieve this by manually renamed the TMP directory in the respective build subdirectory. You can extinguish it afterwards if you want to release storage space or are sure that you no longer need the directory:

@Code_Block_37@

Then have the image rebuilt:

@Code_Block_38@

If you have not deleted the cache ** **, the image should be finished in a relatively short time. This is precisely why it is recommended to maintain the cache. The directory where the cache is located is determined via the variable @ Code_Block_39 @ and can be adjusted in the configuration.

This directory is quite valuable and only in rare cases it is necessary to delete this directory. Please note that the build process takes a lot more time after deleting the cache.
## 7. License

@Code_Block_40@
## 8. Further information

Further information on the Yocto Build system:

* https://docs.yoctroject.org