Once your (virtual/)machine has been set up you can compile, customize the BSP for your board, write and debug applications, change the file system on-the-fly directly on the board, etc. This chapter will guide you to the basic use of the most important tools you can use to build customize, develop and tune your board.
Bitbake is the most important and powerful tool available inside Yocto/OpenEmbedded. It takes as input configuration files and recipes and produces what it is asked for, that is, it can build a package, the Linux kernel, the bootloader, an entire operating system from scratch, etc.
A recipe (.bb file) is a collection of metadata used by BitBake to set variables or define additional build-time tasks. By means of variables, a recipe can specify, for example, where to get the sources, which build process to use, the license of the package, an so on. There is a set of predefined tasks (the fetch task for example fetches the sources from the network, from a repository or from the local machine, than the sources are cached for later reuses) that executed one after the other get the job done, but a recipe can always add custom ones or override/modify existing ones. The most fine-graned operation that Bitbake can execute is, in fact, a single task.
To properly run Bitbake, the first thing you need to do is setup the shell environment. Luckily, there is a script that takes care of it, all you need to do is:
source /path/to/oe-init-build-env /path/to/build/directory
Inside the virtual machine, you can find oe-init-build-env script inside:
/home/architech/architech_sdk/architech/zedboard/yocto/poky
If you omit the build directory path, a directory named build will be created under your current working directory.
By default, with the SDK, the script is used like this:
source /home/architech/architech_sdk/architech/zedboard/yocto/poky/oe-init-build-env
Your current working directory changes to such a directory and you can customize configurations files (that the environment script put in place for you when creating the directory), run Bitbake to build whatever pops to your mind as well run hob. If you specify a custom directory, the script will setup all you need inside that directory and will change your current working directory to that specific directory.
Important
The build directory contains all the caches, builds output, temporary files, log files, file system images... everything!
The default build directory for ZedBoard is located under:
/home/architech/architech_sdk/architech/zedboard/yocto/build
and the splash screen has a facility (a button located under ZedBoard’s page) that can take you there with the right environment already in place so you are productive right away.
Important
Configuration files are used by Bitbake to define variables value, preferences, etc..., there are a lot of them. At the beginning you should just worry about two of them, both located under conf directory inside your build directory, we are talking about local.conf and bblayers.conf.
local.conf contains your customizations for the build process, the most important variables you should be interested about are: MACHINE, DISTRO, BB_NUMBER_THREADS and PARALLEL_MAKE. MACHINE defines the target machine you want compile against. The proper value for ZedBoard is zedboard:
MACHINE ??= "zedboard"
DISTRO let you choose which distribution to use to build the root file systems for the board. The default distribution to use with the board is:
DISTRO ?= "poky"
BB_NUMBER_THREADS and PARALLEL_MAKE can help you speed up the build process. BB_NUMBER_THREADS is used to tell Bitbake how many tasks can be executed at the same time, while PARALLEL_MAKE contains the -j option to give to make program when issued. Both BB_NUMBER_THREADS and PARALLEL_MAKE are related to the number of processors of your (virtual) machine, and should be set with a number that is two times the number of processors on your (virtual) machine. If for example, your (virtual) machine has/sees four cores, then you should set those variables like this:
BB_NUMBER_THREADS ?= "8"
PARALLEL_MAKE ?= "-j 8"
bblayers.conf is used to tell Bitbake which meta-layers to take into account when parsing/looking for recipes, machine, distributions, configuration files, bbclasses, and so on. The most important variable contained inside bblayers.conf is BBLAYERS, it’s the variable where the actual meta-layers layout get specified.
All the variables value we just spoke about are taken care of by Architech installation scripts.
With your shell setup with the proper environment and your configuration files customized according to your board and your will, you are ready to use Bitbake. The first suggestion is to run:
bitbake -h
Bitbake will show you all the options it can be run with. During normal activity you will need to simply run a command like:
bitbake <recipe name>
for example:
bitbake core-image-minimal-dev
Such a command will build bootloader, Linux kernel and a root file system. core-image-minimal-dev tells Bitbake to execute whatever recipe
/home/architech/architech_sdk/architech/zedboard/yocto/poky/meta/recipes-extended/images/core-image-minimal-dev.bb
you just place the name of the recipe without the extension .bb.
Of course, there are times when you want more control over Bitbake, for example, you want to execute just one task like recompiling the Linux kernel, no matter what. That action can be achieved with:
bitbake -c compile -f virtual/kernel
where -c compile states the you want to execute the do_compile task and -f forces Bitbake to execute the command even if it thinks that there are no modifications and hence there is no need to to execute the same command again.
Another useful option is -e which gets Bitbake to print the environment state for the command you ran.
The last option we want to introduce is -D, which can be in fact repeated more than once and asks Bitbake to emit debug print. The amount of debug output you get depend on many times you repeated the option.
Of course, there are other options, but the ones introduced here should give you an head start.
Hob is a graphical interface for Bitbake. It can be called once Bitbake environment has been setup (see Bitbake) like this:
Host
hob
once open, you are required to select the machine you want to compile against
after that, you can select the image you want to build and, of course, you can customize it.
Note
Eclipse is an integrated development environment (IDE). It contains a base workspace and the Yocto plug-in system to compile and debug a program for ZedBoard. Hereafter, the operating system that runs the IDE/debugger will be named host machine, and the board being debugged will be named target machine. The host machine could be running as a virtual machine guest operating system, anyway, the documentation for the host machine running as a guest operating system and as host operating system is exactly the same.
To write your application you need:
- your board has ip address 192.168.0.10 on interface eth0, and
- your PC has an ip address in the same family of addresses, e.g. 192.168.0.100.
Note
You can create two types of projects: Autotools-based, or Makefile-based. This section describes how to create Autotools-based projects from within the Eclipse IDE. Launch Eclipse using Architech Splashscreen just click on Develop with Eclipse.
To create a project based on a Yocto template and then display the source code, follow these steps:
Note
If the “open perspective” prompt appears, click Yes so that you enter in C/C++ perspective. The left-hand navigation panel shows your project. You can display your source by double clicking on the project source file.
To build the project, select Project→Build Project. The console should update with messages from the cross-compiler. To add more libraries to compile:
Note
All libraries must be located in /home/architech/architech_sdk/architech/zedboard/sysroot subdirectories.
Connect ZedBoard console to your PC and power-on the board. Once you built the project and the board is running the image, use minicom to run tcf-agent program in target board:
zedboard login: root
/etc/init.d/tcf-agent restart
On the Host machine, follow these steps to let Eclipse deploy and debug your application:
/home/architech/architech_sdk/architech/zedboard/toolchain/sysroots/i686-pokysdk-linux/usr/bin/arm-poky-linux-gnueabi/arm-poky-linux-gnueabi-gdb
/home/architech/architech_sdk/architech/zedboard/sysroot/lib
/home/architech/architech_sdk/architech/zedboard/sysroot/usr/lib
Important
If debug does not work, check on the board if tcf-agent is running and gdbserver has been installed.
The Qt Framework used by this SDK is composed of libraries for your host machine and your target. To compile the libraries for x86 you only need your distribution toolchain, while to compile the libraries for ZedBoard board you need the proper cross-toolchain (see Chapter Cross compiler for further information on how to get it).
First of all you need to compile the cross-toolchain with Yocto:
bitbake meta-toolchain-qte
The recipe builds poky-glibc-i686-meta-toolchain-qte-armv7a-vfp-neon-toolchain-qte-1.7.1.sh installation script. You should find the installation script in /home/architech/architech_sdk/architech/zedboard/yocto/build/tmp/deploy/sdk. The cross-toolchain allows to compile a Qt embedded 4.8.5 application.
To install the toolchain run the following commands:
sudo ./poky-glibc-i686-meta-toolchain-qte-armv7a-vfp-neon-toolchain-qte-1.7.1.sh
The installation script will ask to select an installation path.
sudo chown -R architech:architech ~/path/to/toolchain/installed
Before to run Qt creator you must set the environment variables:
source /opt/poky/1.7.1/environment-setup-armv7a-vfp-neon-poky-linux-gnueabi
source /opt/poky/1.7.1/sysroots/i686-pokysdk-linux/environment-setup.d/qtopia.sh
Note
Note
sudo tar -xzf /home/architech/architech_sdk/architech/zedboard/yocto/build/tmp/deploy/images/zedboard/qt4e-demo-image-zedboard.tar.gz -C /home/architech/architech_sdk/architech/zedboard/sysroot/
sudo cp -r /home/architech/architech_sdk/architech/zedboard/toolchain/sysroots/armv7a-vfp-neon-poky-linux-gnueabi/* /home/architech/architech_sdk/architech/zedboard/sysroot
sudo chown -R architech:architech /home/architech/architech_sdk/architech/zedboard/sysroot
sudo cp -r /home/architech/architech_sdk/architech/zedboard/sysroot/* /path/to/sd/card/rootfs
and edit the file /path/to/sd/card/rootfs/etc/passwd, change the line
root:x:0:0:root:/home/root:/bin/sh
to:
root::0:0:root:/home/root:/bin/sh
setenv bootargs "console=ttyPS0,115200 root=/dev/mmcblk0p2 rw earlyprintk rootwait"
fatload mmc 0 0x3000000 uImage
fatload mmc 0 0x2A00000 devicetree_hdmi.dtb
bootm 0x3000000 - 0x2A00000
If you based your root file system on qt4e-demo-image, be sure you execute this command
/etc/init.d/qtdemo stop
to stop the execution of the demo application.
- your board has ip address 192.168.0.10 on interface eth0, and
- your PC has an ip address in the same family of addresses, e.g. 192.168.0.100.
The purpose of this example project is to generate a form with an “Hello World” label in it, at the beginning on the x86 virtual machine and than on ZedBoard board.
To create the project follow these steps:
Note
Now you can edit your application adding labels and more, how to do this is not the purpose of this guide.
In the next section we will debug our Hello World! application directly on ZedBoard.
scp /home/architech/architech_sdk/architech/zedboard/workspace/qt/build-QtHelloWorld-ZedBoard-Debug/QtHelloWorld root@192.168.0.10:/home/root
gdbserver :10000 QtHelloWorld -qws
/home/architech/architech_sdk/architech/zedboard/workspace/qt/build-QtHelloWorld-ZedBoard-Debug/QtHelloWorld
Press OK button to start the debug.
Yocto/OpenEmbedded can be driven to generate the cross-toolchain for your platform. There are two common ways to get that:
bitbake meta-toolchain
or
bitbake <image recipe name> -c populate_sdk
The first method provides you the toolchain, you need to provide the file system to compile against, the second method provides both the toolchain and the file system along with -dev and -dbg packages installed.
Both ways you get an installation script.
The virtual machine has a cross-toolchain installed for each board, each generated with meta-toolchain. To use it just do:
source /home/architech/architech_sdk/architech/zedboard/toolchain/environment
to compile Linux user-space stuff. If you want to compile kernel or bootloader then do:
source /home/architech/architech_sdk/architech/zedboard/toolchain/environment-nofs
and you are ready to go.
Useful commands:
opkg update
opkg list
opkg list-installed
opkg install <package 1> <package 2> ... <package n>
opkg search <file>
opkg info <package>
opkg whatdepends <package>
opkg remove <package 1> <package 2> ... <package n>
With some images, Bitbake (e.g. core-image-minimal) does not install the package management system in the final target. To force Bitbake to include it in the next build, edit your configuration file
/home/architech/architech_sdk/architech/zedboard/yocto/build/conf/local.conf
and add this line to it:
IMAGE_FEATURES_append = " package-management"
opkg reads the list of packages repositories in configuration files located under /etc/opkg/. You can easily setup a new repository for your custom builds:
sudo apt-get install apache2
sudo ln -s /home/architech/architech_sdk/architech/zedboard/yocto/build/tmp/deploy/ipk/ /var/www/html/zedboard-ipk
src/gz zedboard http://192.168.0.100:8000/zedboard-ipk/zedboard
To actually reach the virtual machine we set up a port forwarding mechanism in Chapter Virtual Machine so that every time the board communicates with the workstation on port 8000, VirtualBox actually turns the communication directly to the virtual machine operating system on port 80 where it finds apache waiting for it.
opkg update