===== Customize Yocto =====

==== Prerequisites ====

In preparation for this guide, the @mod_name_head@ BSP default image @mtq_image@ was built according to the [[@lang@:@mod_arch@:@mod_name@:linux:yocto:quickstart_yocto|Quickstart BSP]] instructions.\\  \\  
  

==== Without the creation of a custom yocto layer ====

<panel type="default" title="Add a package">
<alert type="warning">The changes described here will affect your local build space only. They will not remain whenever your build space is lost or needs to be recreated.\\  This method is recommended for testing/evaluation purposes only.</alert>

During the evaluation of @stk_name@ the odds are you will face a package missing from the default image @mtq_image@.   
In the Yocto build system, package recipies are organized in so called //Yocto layers//. To find specific recipes or layers, the OpenEmbedded layer index is a good place to start looking. It lists existing layers and corresponding recipes.

[[https://layers.openembedded.org/layerindex/branch/@yocto_rel_name@/layers/|@yocto_rel_name@ Layers]] \\     
[[https://layers.openembedded.org/layerindex/branch/@yocto_rel_name@/recipes/|@yocto_rel_name@ Recipes]] 

<callout type="info">Adding a package to the build may require adding additional layer(s)</callout>

The easiest approach to add a package recipe to the image, is the usage of the ''IMAGE_INSTALL_append'' variable in **conf/local.conf** file which is located in the build space.

At first, open a new terminal on the development host and to move into the build directory. Continue to initialize the build environment as described in [[.:..:quickstart_yocto|Quickstart BSP]]

<code>
cd ~/workspace/ci-meta-tq 
source setup-environment @mod_name_code@_build
</code>

The example below demonstrates how to add the editor //nano// to your build. Open **conf/local.conf** with an editor of your choice and insert the following lines at the end of file:
<code>
IMAGE_INSTALL_append = " nano"
</code>

You may want add multiple packages using the ''IMAGE_INSTALL_append'' variable. This can be done in one line or multiple lines, demonstrated by the following two code-examples.\\  
Multiple packages are always separated by spaces.
<code>
IMAGE_INSTALL_append = " <recipe-name_1> <recipe-name_2>" 
</code>
<code>
IMAGE_INSTALL_append = " \
                       <recipe-name_1> \
                       <recipe-name_2> \
                       "
</code>
<callout type="warning" icon="true">**CAUTION**: The leading space in front of the first package is important.\\ 
''IMAGE_INSTALL_append'' will extend ''IMAGE_INSTALL'', therefore a space separating the contents of both character strings is required.</callout>

You have added your desired package(s) and may repeat building your image now:

<code>
bitbake @mtq_image@
</code>

<callout type="info" icon="true">Note here again, that changes to the **local.conf** only affect your current build space. They will get lost when your buildspace is resetted.\\  
Create a custom yocto layer for a proper implementation.\\  \\  
The next section shows how to create a new custom layer on the example of **meta-custom**, which will be created in **ci-meta-tq/sources**.</callout>

</panel>

==== Creating and adding a new yocto layer ====

<panel type="default" title="Creating a new yocto layer">

Bitbake provides a script for simplyfying the process of creating new layers. It creates a template layer with the following basic structure:
<code>
├── conf
│   └── layer.conf
├── COPYING.MIT
├── README
└── recipes-example
    └── example
        └── example_0.1.bb
</code>

To add a template layer to **/ci-meta-tq/sources**, like **meta-custom** in this example, use the ''bitbake-layers create-layer'' script:
<code>
bitbake-layers create-layer <path/to/your_layer>
</code>
for example...
<code>
bitbake-layers create-layer ../sources/meta-custom
</code>

Before making changes to the new layer, it's recommended to perform the following actions: 
  
  * Initialize the new layer as git repository 
  * Editing the README template 
  * Check and if necessary adjust the license of the layer
  * Configuring the layer priority in layer.conf 

== Create a git repository for the new layer ==

Revision control is good practice in modern software development, therefore we recommend to initialize a git-repository for the new yocto layer.

Move into the directory of the new custom layer:
<code>
cd ~/workspace/ci-meta-tq/sources/meta-custom
</code>

Initialize the directory as git repository and make an initial commit:
<code>
git init
git add .
git commit -m "Initial Commit"
</code> 

== Editing README ==

The README file should give a brief overview of the layer.\\  
Among other things the README should contain:

  * Description of the layer content 
  * Dependencies to other layers e.g. meta-tq
  * A description how to use the layer 

The [[https://github.com/tq-systems/meta-tq/blob/@yocto_branch_name@/README.md|README]] of the meta-tq layer can be taken as an example.  


== Layer license ==
<callout type="info" icon="true">
By default the layer is licensed with the MIT license, the licensing must be updated according to the requirements.
</callout>


== Configure layer priority ==


The **bitbake-layers create-layer** script sets a layer priority of **6** by default, which is defined in the conf/layer.conf file. 
In this example the layer priority is set to a value of "10" to ensure that the meta-custom example layer has the highest priority.

<code>
BBFILE_PRIORITY_meta-custom = "10"
</code>

<callout type="primary">
Ensure that priority of the new layer has a higher priorty than the layer that is used to build upon.
</callout>
</panel>

<panel type="default" title="Adding the new layer to build">

Before the new layer can be used for the build, it must be added to the conf/bblayers.conf file in your build directory. 

<code>
echo 'BBLAYERS += "${BSPDIR}/sources/meta-custom"' >> conf/bblayers.conf
</code>
</panel>

<panel type="default" title="Adding a package to an existing image recipe">
As previously described, it is possible to add packages in a //quick and dirty// like manner by modifying the **local.conf**.\\  
The more sensible approach is, to add a packages by creating *.bbappend files to expand the original image recipe.      
For the @stk_name@ evaluation, the default image recipes are provided by the [[https://github.com/tq-systems/meta-dumpling|meta-dumpling]] layer.\\  

For the @mod_name@ module it's recommended to build a @mtq_image@. Its recipe is located in **.../ci-meta-tq/sources/meta-tq/meta-dumpling/recipe-images/images/@mtq_image@.bb**.

The corresponding **@mtq_image@.bbappend** in the custom layer has to be located in the same path as the orginal **@mtq_image@.bb** in the meta-dumpling layer.\\  
The commands below demonstrate, how to create an empty **@mtq_image@.bbappend** file for the default image recipe **@mtq_image@.bb**:

<code>
cd ci-meta-tq/sources/meta-custom
mkdir - p ./recipes-images/images
cd recipes-images/images
nano @mtq_image@.bbappend
</code>

Now continue to add the following lines to the new **@mtq_image@.bbappend** file.\\  
This will extend the search path and add the desired package(s). Make sure the meta-layer, from which the recipe originates, already exists in the sources directory. It also needs to be listed in **bblayers.conf**.

<code>
IMAGE_INSTALL_append = " <recipe-name>"
</code>

For example the nano editor will be added:

<code>
 IMAGE_INSTALL_append = " nano"
</code>

<callout type="info">For your .bbappend file to work properly, please keep in mind that you should remove the package from the local.conf file if it was added to the build there before.</callout>

You may repeat building your image now:

<code>
bitbake @mtq_image@
</code>
</panel>

==== Customize Linux kernel configuration ====


<panel type="default" title="Configuring the kernel">

The Linux kernel configuration is provided by the linux kernel sources and is located in the source tree at **/arch/arm64/configs/@defconfig_name@**.\\  
The meta-tq layer expands the kernel configuration @defconfig_name@ by so-called kernel configuration fragments. These fragments are located in **.../ci-meta-tq/sources/meta-tq/meta-tq/recipes-kernel/linux/@kernel_dir@/@platform_name@**.

[[https://docs.yoctoproject.org/@yocto_rel_ver_major@.@yocto_rel_ver_minor@/kernel-dev/common.html#creating-configuration-fragments]]

Before creating the new configuration fragment, the path that holds the configuration fragments has to be recreated in meta-custom.

<code>
cd ci-meta-tq/sources/meta-custom
mkdir -p ./recipes-kernel/linux/@kernel_dir@/@platform_name@
</code>

Continue to navigate back to the build directory. To begin creating a new configuration fragment, enter the Linux kernel menuconfig with the the following command: 

<code>
bitbake -c menuconfig virtual/kernel
</code>

Select/deselect the required/desired kernel options, then save and exit the menuconfig. The new configuration fragment can now be created by:

<code>
bitbake -c diffconfig virtual/kernel 
</code>

After applying the ''diffconfig'' command, the path of the new config fragment is printed to the shell. This should look like so:

<code>
Config fragment has been dumped into:
/home/embedded/workspace/@yocto_rel_name@-@mod_name_code@/ci-meta-tq/@mod_name_code@_build/tmp/work/@fragment_dir@
</code>

Move the configuration fragment to the example layer meta-custom. Here it is good practice, to give the fragment a unique name with reference to the options it activates/deactivates.\\  
For this example, it will simply be named **example.cfg**:

<code>
mv ~/workspace/@yocto_rel_name@-@mod_name_code@/ci-meta-tq/@mod_name_code@_build/tmp/work/@fragment_dir@ ~/workspace/zeus-tqma8xx/ci-meta-tq/sources/meta-custom/recipes-kernel/linux/@kernel_dir@/@platform_name@/example.cfg
</code>

The next step is to create a **@kernel_name@.bbappend** file for the kernel recipe located in **recipes-kernel/linux/**

<code>
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
SRC_URI@src_uri_extension@ += "file://example.cfg"
</code>

The ''FILESEXTRAPATHS_prepend'' variable extends the search path of BitBake to include a directory named after the package that is being processed.\\  
In this case, the package name (PN) is "@kernel_dir@". The PN describes the package name under the current directory **THISDIR**. 

Finally the Linux kernel has to be cleaned and the image rebuilt:
<code>
bitbake -c cleansstate virtual/kernel 
</code>

<code>
bitbake @mtq_image@
</code>
</panel>

==== Creating and adding Linux kernel patch ====

<panel type="default" title="Creating and adding Linux kernel patch">

The Linux kernel source is provided as a git repository and available in the following path after building tq-image-weston with the [[.:..:quickstart_yocto|Quickstart BSP]]
 
<code>
~/workspace/zeus-tqma8xx/ci-meta-tq/tqma8xx_build/tmp/work-shared/@mtq_machine_default@/kernel-source
</code>

Open a new terminal and navigate  to the kernel sources used for the build

<code>
cd ~/workspace/ci-meta-tq/tqma8xx_build/tmp/work-shared/@mtq_machine_default@/kernel-source
</code>

Make your changes in the source code, e.g. in the device tree file **@example_dts_path@**

<code>
nano @example_dts_path@
</code>

Check the status of the repository with ''git status'' command

<code>
git log 
</code>

Take the latest commit from the output and execute ''git diff <latest commit>'' to see all changes.

Redirect the output to a patch file in the example layer **.../ci-meta-tq/sources/meta-custom/recipes-kernel/<label kernel_dir></label>/example.patch**.\\  \\  

== Add patch to the build ==

Now expand the ''SRC_URI@src_uri_extension@'' variable in the Linux kernel recipe by the .patch file created before.\\  
For this purpose, the **@kernel_name@.bbappend** file from the [[.:yocto_build_system#customize_linux_kernel_configuration|Customize linux kernel configuration]] section can be reused.\\  If the file wasn't created yet, do so now.

++++You created the file just now -> add this:|

<code>
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
SRC_URI@src_uri_extension@ += "\
    file://example.patch \
    "
</code>
++++
++++You created the file before, following this guide -> add only the example.patch to the ''SRC_URI'' variable:|

<code>
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
SRC_URI@src_uri_extension@ += "\
    file://example.cfg \
    file://example.patch \
    "
</code>
++++
Now, finally the kernel has to be cleaned and rebuilt:

<code>
bitbake -c cleansstate virtual/kernel 
</code> 

<code>
bitbake @mtq_image@
</code>

</panel>

<panel type="default" title="Creating and using a local kernel repository">

The best way to develope using your own mainboard, is to create a new repository with kernel sources. 

Follow the first five steps from the [[.:..:quickstart_yocto|Quickstart BSP]] guide and navigate to the build directory.\\  
Now clone the kernel sources to a local git repository:
<code>
mkdir -p ../local_repos/
https://github.com/tq-systems/linux-tqmaxx.git
cd ../local_repos/linux-tqmaxx
git reset --hard
git clean -fdx
git checkout @git_checkout@ 
</code>

Make your own branch in the git repository
<code>
git checkout -b custom-branch
</code>

Make your changes in the source code and make a commit:
<code>
e.g. nano @example_dts_path@
edit and save
git commit -a -m "my changes"
</code>

Save the commit ID, you can print them using one of the following commands:

<code>
To list all of the commits:
git log 
Get the latest commit id:
git rev-parse HEAD
</code>

Create a new yocto layer by following the steps [[.:yocto_build_system#creating_and_adding_a_new_yocto_layer|previously]] described.\\  

Navigate into the new layer and recreate the path structure of meta-tq.
<code>
cd ci-meta-tq/sources/meta-custom
mkdir -p ./recipes-kernel/linux/@kernel_dir@/@platform_name@
</code>
Now create the **@kernel_name@.bbappend** file for the kernel recipe located in **meta-custom/recipes-kernel/linux/**
<code>
SRC_URI_remove@src_uri_extension@ = "${TQ_GIT_BASEURL}/linux-tqmaxx.git;protocol=${TQ_GIT_PROTOCOL};branch=${SRCBRANCH}"
SRC_URI_append@src_uri_extension@ = "git://${BSPDIR}/local_repos/linux-tqmaxx;protocol=file;branch=${SRCBRANCH}"
SRCBRANCH = "custom-branch"
SRCREV = "Your commit ID of the changes"
</code>

Finally rebuild your kernel using the following command:
<code>
bitbake -c build virtual/kernel
</code>

You may repeat building your image now
<code>
bitbake @mtq_image@
</code>
</panel>

<WRAP hide>

==== Customize U-Boot configuration ====
=== Creating and adding U-Boot patch ===

after building the default image @mtq_image@ the u-boot sources are located at .../tqma8xx_build/tmp/work/tqma8xqp_mba8xx-poky-linux/u-boot-imx-tq/2019.04-r0/git


==== Creating a hello world recipe ====

 







==== Customize busybox configuration ====

Busybox can be configured by the following command: 

<code>
bitbake -c menuconfig busybox 
</code>

After saving and exiting the menuconfig a new diffconfig has to generated 


==== Adding and Creating an own image recipe ====




==== Creating and using a local u-boot repository ====

==== Creating and using a local u-boot repository ====
</WRAP>