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

readme: Automatically translated README to English

Browse Source
This commit is contained in:
GitHub Actions
2023-09-16 19:58:40 +00:00
parent 1fab14c1b1
commit cdc0a66024
1 changed files with 214 additions and 209 deletions
Download Patch File Download Diff File Expand all files Collapse all files

423
README-en.md
View File

@@ -1,209 +1,214 @@
# Quick start image build #
- [Preparation](#Preparation)
- [Build Image](#Build-Image)
- [Updating](#Updating)
- [Working on target sources](#Working-on-target-sources)
- [Overview of global configuration files](#Overview-of-global-configuration-files)
## Preparation
### Install required host packages (Debian 11)
For usage with other distributions see: [Yocto Project Quick Build](https://docs.yoctoproject.org/3.2.4/ref-manual/ref-system-requirements.html#supported-linux-distributions)
> :memo: **NOTE:** If you are using the Tuxbox-Builder VM (this is not mandatory) please jump to [step 1](#1-Clone-init-script). The Tuxbox-Builder VM already contains required packages. For details and download of Tuxbox-Builder VM see: [Tuxbox-Builder](https://sourceforge.net/projects/n4k/files/Tuxbox-Builder)
```bash
apt-get install -y gawk wget git-core diffstat unzip texinfo gcc-multilib build-essential \
chrpath socat cpio python python3 python3-pip python3-pexpect xz-utils debianutils \
iputils-ping python3-git python3-jinja2 libegl1-mesa pylint3 xterm subversion locales-all \
libxml2-utils ninja-build default-jre clisp libcapstone4 libsdl2-dev doxygen
```
#### Recommended additional packages for graphical support and analyzing (e.g. with Kdevelop, Meld):
```bash
apt-get install -y gitk git-gui meld cppcheck clazy kdevelop
```
### Optional: In case of no configured git, please set your global git user data:
```bash
git config --global user.email "you@example.com"
git config --global user.user "Your Name"
```
## Build Image:
> :memo: **Note:** Some paths are based on the defaults generated by the init script. Some entries are given as ```<placeholders>```, which must be adjusted accordingly.
> ### 1. Clone init script.
```bash
git clone https://github.com/dbt1/buildenv.git
cd buildenv
```
> ### 2. Execute init script
```bash
./init.sh
cd poky-3.2.4
```
> ### 3. Show possible machine types
```bash
ls build
```
> ### 4. Execute environment script
```bash
. ./oe-init-build-env build/<enter required machine type from list taken from step 3>
```
> ### 5. Build
```bash
bitbake neutrino-image
```
This may take a while. Some warn messages can be ignored. Error messages during setscene tasks are no problem but errors during build and package tasks will abort the process. [In this case please report the error or send us your solution](https://forum.tuxbox-neutrino.org/forum/viewforum.php?f=77). Help is very welcome.
If all done, such a similar message should appear:
```bash
...
NOTE: Tasks Summary: Attempted 4568 tasks of which 4198 didn't need to be rerun and all succeeded.
...
```
**That's it ...**
Built images and packages to find under:
```
~/build/poky-3.2.4/build/<machine>/tmp/deploy
```
or in the dist directory:
```
~/build/dist/<image-version/<machine>/
```
## Updating
> :memo: Manually updates for any target sources are not required. This is done automatically for each called target with Bitbake. This also updates any required dependencies. If you want to have full control for a target source, see "[Working on target sources](#working-on-target-sources)"!
If [steps 1 to 4](#3-Show-possible-machine-types) have already been performed, only step 5 is required:
### Update image
```bash
bitbake neutrino-image
```
### Update a target
```bash
bitbake <target>
```
### Update meta layer repositories
Execution of init script (see: [step 2](#2-Execute-init-script)) will update the required meta-layer repositories.
```bash
cd $HOME/build
./init.sh
```
The update routines will stash uncommitted changes or will rebase your local commits to new remote changes, but conflicts are possible. In this case you must solve manually. Of corse you can update and modiify local meta-layer for meta-neutrino and machine layers repositories manually.
> :memo: **Note: Your config files will be untouched. New or modified config options are not considered. Please check your configuration if required.**
## Working on target sources
If you want to have the full control about any target source, you should transfer the desiered target source into the workspace. For more details about this workflow 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).
## Reset configuration if required
If you want to reset your configs, please rename (delete is not recommended) the conf directory and execute the init script again. See [step 2](#2-Execute-init-script).
```bash
mv $HOME/build/poky-3.2.4/build/<machine>/conf $HOME/build/poky-3.2.4/build/<machine>/conf.01
cd $HOME/build
./init.sh
```
## Rebuild of a single target
In some cases, a target may abort for whatever reason. You should not panic and delete the whole tmp folder and the sstate-cache. You can also do this for each target individually.
> :memo: In particular, broken archive URLs could terminate the build. However, these errors are always displayed and the URL can be checked accordingly. Often only the servers are down and will work again after a few minutes.
To ensure that the recipe has really a problem, it makes sense to clean up completely and rebuild the target. To enforce this, all generated package, build and cache data must be cleaned.
```bash
bitbake -c cleansstate <target>
```
rebuild again
```bash
bitbake <target>
```
## Force complete image rebuild
If you want to force a rebuild, you can delete (or rename) the tmp directory:
```bash
mv tmp tmp.01
bitbake neutrino-image
```
If you didn't delete the sstate-cache, the image should be built in relatively short time. Therefore it is recommended to keep the sstate-cache. The directory where the sstate-cache is located is defined by the variable ```${SSTATE_DIR}``` and can be adjusted in the configuration.
This directory is quite valuable especially when using slow computers and only in rare cases it is necessary to delete this directory as well. Please note in case of deleted sstate-cache, the build will take much more time.
> :bulb: You can tell bitbake not to use sstate-cache.
```bash
bitbake --no-setscene neutrino-image
```
or
```bash
bitbake --skip-setscene neutrino-image
```
## Customize if required
It's recommended to build for first time without any changes on config files to get an impression how the build process is working and see the results.
The possibilities for adjustments are very extensive and not really manageable for beginners. However, the Yoctoproject is very
extensively documented and provides the best source of information.
**Important for developers**: "[Working on target sources](#working-on-target-sources)"!
> :warning: **Please do not modify the Yocto-recipes! This is not recommended by the Yocto-Team, but you can use [.bbappend](https://docs.yoctoproject.org/3.2.4/dev-manual/dev-manual-common-tasks.html#using-bbappend-files-in-your-layer) files to complete, expand or override meta core Yocto recipes.**
## Overview of global configuration files
These configuration files are required within the build directories for local configuration:
> $HOME/build/poky-3.2.4/build/```<machine>```/conf/local.conf
This generated local.conf contains only a few lines, but has a line that points to a common configuration file that is valid for all images and supported machine types and can be fed with your own options.
> $HOME/build/local.conf.common.inc
This **.inc** file was derived from the cloned example configuration file when the init script was run for the first time.
> local.conf.common.inc.sample
This sample file should be untouched to avoid possible conflicts when updating the build repository and to see what might have changed.
After updating the build repository, some new or changed options may have been added or removed that are not reflected in the included configuration file. This case should be taken into account in your own configuration and adjusted if necessary.
Of course you can modify ```$HOME/Build/poky-3.2.4/build/<machine>/conf/local.conf``` with your own requirements and use it as a separate configuration file for a machine type.
#### Pattern configuration for bblayers.conf:
> $HOME/build/poky-3.2.4/build/```<machine>```/conf/bblayers.conf
```bitbake
# POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf
# changes incompatibly
POKY_BBLAYERS_CONF_VERSION = "2"
BBPATH = "${TOPDIR}"
BBFILES ?= ""
BBLAYERS ?= " \
/home/<username>/build/poky-3.2.4/meta \
/home/<username>/build/poky-3.2.4/meta-poky \
/home/<username>/build/poky-3.2.4/meta-yocto-bsp \
"
BBLAYERS += " \
/home/<username>/build/poky-3.2.4/meta-neutrino \
/home/<username>/build/poky-3.2.4/meta-<machine-brand-or-bsp-name> \
/home/<username>/build/poky-3.2.4/meta-openembedded/meta-oe \
"
BBLAYERS += " \
/home/<username>/build/poky-3.2.4/meta-python2 \
"
BBLAYERS += " \
/home/<username>/build/poky-3.2.4/meta-qt5 \
"
```
## More informations
Further informations about yocto buildsystem:
* https://docs.yoctoproject.org/3.2.4/index.html
This is an automatically translated file. Original content in [German](https://github.com/tuxbox-neutrino/buildenv/blob/3.2.4/README-de.md):
# Quick start image creation #
- [Preparation](#Preparation)
- [Build Image](#build-image)
- [Update](#Update)
- [Working on Target Sources](#Working-on-Target-Sources)
- [Overview of global configuration files](#overview-of-global-configuration-files)
## Preparation
### Install required host packages (Debian 11)
For use with other distributions see: [Yocto Project Quick Build](https://docs.yoctoproject.org/3.2.4/ref-manual/ref-system-requirements.html#supported-linux-distributions)
> :memo: **NOTE:** If using the Tuxbox Builder VM (which is not mandatory), please skip to [Step 1](Clone #1-Init-Script). The Tuxbox Builder VM already contains required packages. Details and download of Tuxbox-Builder VM see: [Tuxbox-Builder](https://sourceforge.net/projects/n4k/files/Tuxbox-Builder)
```bash
apt-get install -y gawk wget git-core diffstat unzip texinfo gcc-multilib build-essential \
chrpath socat cpio python python3 python3-pip python3-pexpect xz-utils debianutils \
iputils-ping python3-git python3-jinja2 libegl1-mesa pylint3 xterm subversion locales-all \
libxml2-utils ninja-build default-jre clisp libcapstone4 libsdl2-dev doxygen
```
#### Recommended additional packages for graphical support and analysis (e.g. with Kdevelop, Meld):
```bash
apt-get install -y gitk git-gui meld cppcheck clazy kdevelop
```
### Optional: If there is no configured Git, please enter your global Git user data:
```bash
git config --global user.email "you@example.com"
git config --global user.user "Your name"
```
## Build image
> :memo: **Note:** Some paths are based on defaults generated by the init script. Some entries are displayed as ```<placeholder>```, which need to be adjusted accordingly.
> ### 1. Clone init script.
```bash
git clone https://github.com/tuxbox-neutrino/buildenv.git
cd buildenv
```
> ### 2. Run init script
```bash
./init.sh
cd poky-3.2.4
```
> ### 3. Show list of possible machine types
```bash
ls build
```
> ### 4. Run environment script
```bash
. ./oe-init-build-env build/<enter machine type from the list from step 3 here>
```
> ### 5. Build
```bash
bitbake neutrino image
```
This could take a while. Some warning messages can be ignored. Error messages affecting the setscene tasks are not a problem, but errors during the build and package tasks terminate the process in most cases. [In this case, please report the error or send your solution to us](https://forum.tuxbox-neutrino.org/forum/viewforum.php?f=77). Help is very welcome.
When everything is done, you should see a message similar to this:
```bash
...
NOTE: Tasks Summary: Attempted 4568 tasks of which 4198 didn't need to be rerun and all succeeded.
...
```
**That's it...**
Created images and packages can be found at:
```
~/build/poky-3.2.4/build/<machine>/tmp/deploy
```
or in the dist directory:
```
~/build/dist/<image version>/<machine>/
```
## Update
> :memo: Manual updates for arbitrary target sources are not required. This is done automatically for every target accessed using Bitbake. This means that required dependencies are always updated. If you want full control over specific target sources, see [Working on Target Sources](#Working-on-Target-Sources)!
If [Steps 1 to 4](View #3-list-of-possible-machine-types) have already been completed, only step 5 is required:
### Update image
```bash
bitbake neutrino image
```
### Update target
```bash
bitbake <target>
```
### Update meta layer repositories
Re-executing the init script updates the included meta layers to the status of the remote repositories.
```bash
cd $HOME/build
./init.sh
```
The triggered update routines of the init script should temporarily stash uncommitted changes or rebase local commits to the remote changes. However, conflicts must be resolved manually. Of course, you can manually update and modify your local meta layers for meta neutrino and machine layer repositories.
> :memo: **Note:** Configuration files remain untouched. New or changed configuration options are not taken into account. Please check the configuration if necessary.
## Working on target sources
If you want to have full control over the target sources, the source codes should be moved to the workspace. Please refer
[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).
## Reset configuration
If you want to reset your machine configurations, please rename the conf directory (deletion is not recommended) and run the init script again.
```bash
mv $HOME/build/poky-3.2.4/build/<machine>/conf $HOME/build/poky-3.2.4/build/<machine>/conf.01
cd $HOME/build
./init.sh
```
## Force rebuild of a single target
In some cases it can happen that a target breaks off for whatever reason. You shouldn't panic and delete the tmp folder and the sstate cache. You can also do this for each target individually.
> :memo: In particular, broken archive URLs can lead to termination. However, these errors are always displayed and you can check the URL. Often it's just the servers and they even work again after a few minutes.
To make sure whether the recipe in question actually has a problem, it makes sense to completely clean up the target in question and rebuild it. To enforce this, all generated package, build and cache data must be cleaned up.
```bash
bitbake -c cleansstate <target>
```
then rebuild:
```bash
bitbake <target>
```
## Force full image build
If you want to force a complete image build, you can delete (or rename) the tmp directory:
```bash
mv tmp tmp.01
bitbake neutrino image
```
If you have **not** cleared the sstate cache, the image should be built in a relatively short time. Therefore, it is recommended to keep the sstate cache. The directory where the sstate cache is located is determined via the variable ```${SSTATE_DIR}``` and can be adjusted in the configuration.
This directory is quite valuable and only in rare cases is it necessary to delete this directory. Please note that the build will take much longer in this case.
> :bulb: You can tell Bitbake not to use sstate cache.
```bash
bitbake --no-setscene neutrino-image
```
or
```bash
bitbake --skip-setscene neutrino-image
```
## Adjust if necessary
It is recommended to build for the first time without making any changes to the configuration files to get an idea of ​​how the build process works and to see the results.
The setting options are very extensive and not really manageable for beginners. However, the Yoctoproject is very
comprehensively documented and provides the best source of information.
**Important for developers**: "[Working on Target Sources](#Working-on-Target-Sources)"!
> :memo: **Please do not change the Yocto recipes! This is not recommended by the Yocto team, but you can use [.bbappend](https://docs.yoctoproject.org/3.2.4/dev-manual/dev-manual-common-tasks.html#using-bbappend-files-in-your-layer) files.**
### Overview of global configuration files
For local configuration, these configuration files are required within the build directories:
> $HOME/build/poky-3.2.4/build/```<machine>```/conf/local.conf
This generated local.conf only contains a few lines, but has a line that points to a common configuration file that is valid for all images and supported machine types and can be fed with your own options.
> $HOME/build/local.conf.common.inc
This **.inc** file was created from the cloned example file when running the init script for the first time.
> local.conf.common.inc.sample
This example file should be left untouched to avoid possible conflicts when updating the build repository and to see what might have changed.
After an update to the build repository, some new or changed options may have been added or removed that are not reflected in the included configuration file. You should take this case into account in your own configuration and adapt it if necessary.
Of course, you can modify ```$HOME/Build/poky-3.2.4/build/<machine>/conf/local.conf``` with your own requirements and use it as a separate configuration file for a machine type.
#### Sample configuration for bblayers.conf:
> $HOME/build/poky-3.2.4/build/```<machine>```/conf/bblayers.conf
```bitbake
# POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf
# changes incompatibly
POKY_BBLAYERS_CONF_VERSION = "2"
BBPATH = "${TOPDIR}"
BBFILES ?= ""
BBLAYERS ?= " \
/home/<username>build/poky-3.2.4/meta \
/home/<username>/build/poky-3.2.4/meta-poky \
/home/<username>/build/poky-3.2.4/meta-yocto-bsp \
"
BBLAYERS += "\
/home/<username>/build/poky-3.2.4/meta-neutrino \
/home/<username>/build/poky-3.2.4/meta-<machine-brand-or-bsp-name> \
/home/<username>/build/poky-3.2.4/meta-openembedded/meta-oe \
"
BBLAYERS += "\
/home/<username>/build/poky-3.2.4/meta-python2 \
"
BBLAYERS += "\
/home/<username>/build/poky-3.2.4/meta-qt5 \
"
```
## More information
Further information about the Yocto build system:
* https://docs.yoctoproject.org/3.2.4/index.html