===== Preface =====


The //meta-tq// layer extends the //Yocto Project's// reference system //Poky// to provide support for a selection of TQ Embedded CPU Modules, including the @mod_name_a@.

<callout type="primary" icon="true">
Because of the dependencies to the other yocto layers we recommend to use [[https://github.com/tq-systems/ci-meta-tq|ci-meta-tq]] which already provides all required yocto layers as git submodules instead of [[https://github.com/tq-systems/meta-tq|meta-tq]] to  build this BSP release. 
</callout>
The instructions on this page refer to the BSP and ancillary tools listed in the following table:
<grid>
<col sm="6">

^ BSP Revision  ^  @bsp_rev@  ^
^ meta-tq release\\  [[https://github.com/tq-systems/ci-meta-tq/releases|all releases]]  |  [[https://github.com/tq-systems/ci-meta-tq/releases/tag/@git_tag@|@git_tag@]]  |
^ Yocto Project / Poky Release  |  @poky_rel@  |
^ Target machine |  @machine@  |
^ U-Boot  |  @uboot_ver@  |
^ Linux Kernel  |  @linux_ver@  |
</col>
</grid>
\\
<alert type="warning" icon="fa fa-warning">It's strongly recommended to use git for downloading both the Yocto Project / Poky release as well as ci-meta-tq (instead of downloading archives and extracting them)</alert>

<callout type="info" icon="true">
The goal of these wiki pages is to get you started using //ci-meta-tq// with the @stk_name@, so instead of reinventing the wheel we will adhere to the very compact [[https://www.yoctoproject.org/docs/@poky_rel@/brief-yoctoprojectqs/index.html|Yocto Project Quick Build]] and supply details specific to the @stk_name@ where necessary.\\
\\
For further details regarding //Yocto Project// @poky_rel@ - @distro@ please refer to its [[https://www.yoctoproject.org/docs/@poky_rel@/ref-manual/index.html|official documentation]].
</callout>

===== Prerequisites  =====

<panel type="primary" title="Build Host">

//Yocto Project / Poky// requires a Linux build host, so first of all you need a development workstation (or a virtual machine) 
with a Linux distribution installed.

Please refer to section [[https://www.yoctoproject.org/docs/@poky_rel@/ref-manual/system-requirements.html#supported-linux-distributions|Supported Linux Distribution]] of the //Yocto Project Quick Start// for supported linux distributions and section [[https://www.yoctoproject.org/docs/@poky_rel@/ref-manual/system-requirements.html#required-packages-for-the-build-host|Required Packages for the Build Host]] for required build host packages for those distributions.

<callout type="info" icon="true">
The instructions on this page have been tested on Ubuntu 20.04 (64 bit) in a VMWare virtual machine.
</callout>
Although not required by //Yocto Project / Poky//, we also recommend to configure and run a [[en:tftp|tftp server]] (for image download / update) and an [[en:nfs|nfs server]] (for network mounted root filesystem) on your development host.
</panel>

===== Yocto BSP Build Instructions =====

<panel type="primary" title="Yocto BSP">
<alert type="warning" icon="fa fa-warning">Please setup the build host as described in the [[.:quickstart_yocto#Prerequisites]] section above .</alert>

1. Open a new terminal and create a directory for the BSP build e.g. in the home directory and navigate to that directory.

<code>
mkdir -p ~/workspace/@git_tag@
cd ~/workspace/@git_tag@
</code>

2. Create a local copy of //ci-metatq//
<code>
git clone --recurse-submodules https://github.com/tq-systems/ci-meta-tq.git
</code>
3. Checkout BSP release on new local branch.
<code>
cd ci-meta-tq
git checkout @git_tag@ -b @yocto_rel@-@mod_name_b@
</code>
4. Update git submodules:
<code>
git submodule sync
git submodule update --init
</code>
5. Setup local branch to track the remote branch.
<code>
git branch -u origin/@yocto_rel@
</code>
6. Export the environment DISTRO and MACHINE environment variable:
<code>
export DISTRO=@distro@
export MACHINE=@machine@
</code>
7. Configure the Build:
<code>
source setup-environment @mod_name_b@_build imx
</code>
<callout type="info" icon="true">Each time a new terminal is opened, the build environment must be reinitialised. The command described above is intended for the initial build space initialisation.  
To return to an existing buildspace open up a new terminal and navigate to the ci-meta-tq folder and execute the following command: 

<code>source setup-environment @mod_name_b@_build  </code>
</callout>
8. Build an Image for @stk_name@:
<accordion collapsed="true">
<panel title="Image with debug features/root login">
<code>
bitbake @bitbake_a@
</code>

Image with IMAGE_FEATURES ''debug'' and ''debug-tweaks'' enabled to have an open root login for console and ssh for ease of development and testing.    
</panel>
<panel title="Image without debug features/root login">
<code>
bitbake @bitbake_b@
</code>
Image without IMAGE_FEATURES ''debug'' and ''debug-tweaks'' enabled. A user login is not allowed with this image, if a login is required, please see poky documentation for extrausers.bbclass  
</panel>
For further information to the TQ image recipes, please refer to the section **Image recipes** from the meta-dumpling Yocto layer documentation.\\
[[https://github.com/tq-systems/meta-tq/blob/@yocto_rel@/meta-dumpling\README.md#image-recipes |meta-dumpling documentation]]  

</accordion>
<alert type="info" icon="fa fa-info">The resulting image is ''tmp/deploy/images/@machine@.wic''</alert>\\ 
9. Write the Image to an SD-Card
<code>
sudo dd if=tmp/deploy/images/@machine@/@bitbake_b@-@machine@.wic of=/dev/<TARGET_DEVICE>
</code>
<alert type="info" icon="fa fa-info">Please see [[./deployment_yocto#create_sd_card_with_bsp_image|Create SD Card with BSP Image]] for detailed instructions.</alert>
10. Boot the @stk_name@ from SD card (cf. [[en:arm:@mod_name_a@:@mb_name_a@:dip_switches|@mb_name_a@ DIP switch settings]])  |
</panel>