6. Toolchain

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.

6.1. Bitbake

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.

6.1.1. Environment

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:

  Host    select
source /path/to/oe-init-build-env /path/to/build/directory

Inside the virtual machine, you can find oe-init-build-env script inside:

  Host    select
/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:

  Host    select
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:

  Host    select
/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

If you don’t use the default build directory you need setup the local.conf file. See the paragraph below.

6.1.2. Configuration files

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-zynq7:

  Host    select
MACHINE ??= "zedboard-zynq7"

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:

  Host    select
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:

  Host    select
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.

6.1.3. Command line

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:

  Host    select
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:

  Host    select
bitbake <recipe name>

for example:

  Host    select
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

  Host    select
/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:

  Host    select
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.

6.2. Hob

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

_images/hob-select-machine.png

after that, you can select the image you want to build and, of course, you can customize it.

6.3. Eclipse

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:

  • a root file system filesystem (you can use bitbake/hob to build your preferred filesystem) with development support (that is, it must include all the necessary libraries, header files, the tcf-agent program and gdbserver) included
  • a media with the root filesystem installed and, if necessary, the bootloader
  • ZedBoard powered up with the aforementioned root file system
  • a working serial console terminal
  • a working network connection between your workstation and the board (connector J11), so, be sure that:
  1. your board has ip address 192.168.0.10 on interface eth0, and
  2. your PC has an ip address in the same family of addresses, e.g. 192.168.0.100.

6.3.1. Creating the Project

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.

_images/run_eclipse.jpg

To create a project based on a Yocto template and then display the source code, follow these steps:

  • Select File→New→Project...
  • Under C/C++, double click on C Project to create the project.
  • Click on “Next” button
  • Expand Yocto Project ADT Autotools Project.
  • Select Hello World ANSI C Autotools Project. This is an Autotools-based project based on a Yocto Project template.
_images/eclipse-new-project.jpg
  • Put a name in the Project name: field. Do not use hyphens as part of the name.
  • Click Next.
  • Add information in the Author and Copyright notice fields.
  • Be sure the License field is correct.
  • Click Finish.

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.

_images/projectexplorer.jpg
  • Select Project→Properties→Yocto Project Settings and check Use project specific settings
_images/projectsetting.jpg

6.3.2. Building the Project

To build the project, select Project→Build Project. The console should update with messages from the cross-compiler. To add more libraries to compile:

  • Click on Project→Properties.
  • Expand the box next to Autotools.
  • Select Configure Settings.
  • In CFLAGS field, you can add the path of includes with -Ipath_include
  • In LDFLAGS field, you can specify the libraries you use with -lname_library and you can also specify the path where to look for libraries with -Lpath_library
  • Click on Project→Build All to compile the project

Note

All libraries must be located in /home/architech/architech_sdk/architech/zedboard/sysroot subdirectories.

_images/autotools.jpg

6.3.3. Deploying and Debugging the Application

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:

  Board    select
zedboard login: root
/etc/init.d/tcf-agent restart

On the Host machine, follow these steps to let Eclipse deploy and debug your application:

  • Select Run→Debug Configurations...
  • In the left area, expand C/C++ Remote Application.
  • Locate your project and select it to bring up a new tabbed view in the Debug Configurations Dialog.
_images/debugform.jpg
  • Insert in C/C++ Application the filepath of your application binary on your host machine.
  • Click on “New” button near the drop-down menu in the Connection field.
  • Select TCF icon.
_images/tcf1.jpg
  • Insert in Host Name and Connection Name fields the IP address of the target board. (e.g. 192.168.0.10)
_images/tcf2.jpg
  • Press Finish.
  • Use the drop-down menu now in the Connection field and pick the IP Address you entered earlier.
  • Enter the absolute path on the target into which you want to deploy the application. Use Browse button near Remote Absolute File Path for C/C++Application: field. No password is needed.
_images/remotepath.jpg
  • Enter also in the target path the name of the application you want to debug. (e.g. HelloWorld)
_images/debug2.jpg
  • Select Debugger tab
_images/gdb.jpg
  • In GDB Debugger field, insert the filepath of gdb for your toolchain
  Host    select
/home/architech/architech_sdk/architech/zedboard/toolchain/sysroots/i686-pokysdk-linux/usr/bin/arm-poky-linux-gnueabi/arm-poky-linux-gnueabi-gdb
  • In Debugger window there is a tab named Shared Library, click on it.
  • Add the libraries paths lib and usr/lib of the rootfs (which must be the same used in the target board)
  Host    select
/home/architech/architech_sdk/architech/zedboard/sysroot/lib
/home/architech/architech_sdk/architech/zedboard/sysroot/usr/lib
  • Click Debug to bring up a login screen and login.
  • Accept the debug perspective.

Important

If debug does not work, check on the board if tcf-agent is running and gdbserver has been installed.

6.4. Qt Framework

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).

This section just wants to show you how the framework has been generated.

Before to begin, keep in mind you might need to install the following package to compile yourself the libraries under Ubuntu

:.. host:

| sudo apt-get install libxrender-dev

So, to install qt-everywhere for x86 from sources, the usual drill of download, uncompress, configure, make and make install is required:

  Host    select
wget http://download.qt-project.org/official_releases/qt/4.8/4.8.6/qt-everywhere-opensource-src-4.8.6.zip
unzip qt-everywhere-opensource-src-4.8.6.zip
cd qt-everywhere-opensource-src-4.8.6
./configure /*Choose Open source Edition when asked, and accept the license*/
make
make install

The installation of the libraries for ZedBoard from sources is sligthly more complicated. Once you downloaded and uncompressed the sources

  Host    select
wget http://download.qt-project.org/official_releases/qt/4.8/4.8.6/qt-everywhere-opensource-src-4.8.6.zip
unzip qt-everywhere-opensource-src-4.8.6.zip
cd qt-everywhere-opensource-src-4.8.6
cp -r mkspecs/qws/linux-arm-g++/ mkspecs/qws/linux-zedboard-g++
cd mkspecs/qws/linux-zedboard-g++/
gedit qmake.conf

you need to customize qmake configuration

  Host    select
#
# qmake configuration for building with arm-linux-g++
#

include(../../common/linux.conf)
include(../../common/gcc-base-unix.conf)
include(../../common/g++-unix.conf)
include(../../common/qws.conf)

# modifications to g++.conf
QMAKE_CC                = arm-poky-linux-gnueabi-gcc --sysroot=/home/architech/architech_sdk/architech/zedboard/toolchain/sysroots/armv7a-vfp-neon-poky-linux-gnueabi
QMAKE_CXX               = arm-poky-linux-gnueabi-g++ --sysroot=/home/architech/architech_sdk/architech/zedboard/toolchain/sysroots/armv7a-vfp-neon-poky-linux-gnueabi
QMAKE_LINK              = arm-poky-linux-gnueabi-g++ --sysroot=/home/architech/architech_sdk/architech/zedboard/toolchain/sysroots/armv7a-vfp-neon-poky-linux-gnueabi
QMAKE_LINK_SHLIB        = arm-poky-linux-gnueabi-g++ --sysroot=/home/architech/architech_sdk/architech/zedboard/toolchain/sysroots/armv7a-vfp-neon-poky-linux-gnueabi

# modifications to linux.conf
QMAKE_AR                = arm-poky-linux-gnueabi-ar cqs
QMAKE_OBJCOPY           = arm-poky-linux-gnueabi-objcopy
QMAKE_STRIP             = arm-poky-linux-gnueabi-strip

load(qt_config)

save the file and exit from gedit, then configure, make and make install

  Host    select
cd ../../../
./configure -no-pch -opensource -confirm-license -prefix /usr/local/Trolltech/Zedboard -no-qt3support -embedded arm -nomake examples -nomake demo -little-endian -xplatform qws/linux-zedboard-g++ -qtlibinfix E
make
make install

A comfortable tool to get your job done with Qt is Qt Creator, which its use will be introduced in Section Qt Creator. You can download it from here:

6.5. Qt Creator

_images/qt-0.png
Qt is a cross-platform application framework that is used to build applications. One of the best features of Qt is its capability of generating Graphical User Interfaces (GUIs).
Qt Creator is a cross-platform C++ IDE which includes a visual debugger, an integrated GUI layout and form designer. It makes possible to compile and debug applications on both x86 (host) and ARM (target) machines.
This SDK relies on version 4.8.5 of Qt and version 2.8.1 of Qt Creator.


Before getting our hands dirty, make sure all these steps have been followed:
  1. Use Hob or Bitbake to build an image which includes: openssh, support for C++, tcf-agent and gdbserver.

Note

To follow this guide build qt4e-demo-image image. Remember to complete its file system with tcf-agent, gdbserver and openssh.

  1. Deploy the root file system just generated on the final media used to boot the board
  2. Replicate the same root file system into directory
  Host    select
/home/architech/architech_sdk/architech/zedboard/sysroot
  1. Copy the Qt Libraries to the board media used to boot
  Host    select
sudo mkdir -p /path/to/target/usr/local/Trolltech/
sudo cp -r /usr/local/Trolltech/Zedboard/* /path/to/target/usr/local/Trolltech/
  1. Copy the Qt Libraries and cpp libraries to your sdk sysroot directory
  Host    select
sudo mkdir -p ~/architech_sdk/architech/zedboard/sysroot/usr/local/Trolltech/
sudo cp -r /usr/local/Trolltech/Zedboard/* ~/architech_sdk/architech/zedboard/sysroot/usr/local/Trolltech
sudo cp -r /home/architech/architech_sdk/architech/zedboard/toolchain/sysroots/armv7a-vfp-neon-poky-linux-gnueabi/* /home/architech/architech_sdk/architech/zedboard/sysroot/
  1. Unmount the media used to boot the board from your computer and insert it into the board
  2. Power-On the board
  3. Open up the serial console.

If you based your root file system on qt4e-demo-image, be sure you execute this command

  Board    select
/etc/init.d/qtdemo stop

to stop the execution of the demo application.

  1. Provide a working network connection between your workstation and the board (connector J11), so, be sure that:
  1. your board has ip address 192.168.0.10 on interface eth0, and
  2. your PC has an ip address in the same family of addresses, e.g. 192.168.0.100.

6.5.1. Hello World!

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:

  1. Use the Welcome Screen to run Qt Creator by selecting Architech→ZedBoard→Develop with Qt Creator
_images/qtCreatorStart.jpg
  1. Go to File -> New File or Project. In the new window select Applications as project and Qt Gui Application. Click on Choose... button.
_images/qt-project-gui.jpg
  1. Select a name for your project for example QtHelloWorld and press next button.
_images/qt-project-name.jpg
  1. Check also pengwyn kit and continue to press next button to finish the creation of the project.
_images/qt-project-kits.jpg

Note

Now you can edit your application adding labels and more, how to do this is not the purpose of this guide.

  1. To compile the project click on “QtHelloWorld” icon to open project menu.
_images/qt-1.png
  1. Select the build configuration: Desktop - Debug.
_images/qt-2.jpg
  1. To build the project, click on the bottom-left icon.
_images/qt-3.png
  1. Once you built the project, click on the green triangle to run it.
_images/qt-4.png
  1. Congratulations! You just built your first Qt application for x86.
_images/qt-5.png

In the next section we will debug our Hello World! application directly on ZedBoard.

6.5.2. Debug Hello World project

  1. Select build configuration: zedboard - Debug and build the project.
_images/qt-10.jpg
  1. Copy the generated executable to the target board (e.g /home/root/).
  Host    select
scp /home/architech/architech_sdk/architech/zedboard/workspace/qt/build-QtHelloWorld-ZedBoard-Debug/QtHelloWorld root@192.168.0.10:/home/root
  1. Use minicom to launch gdbserver application on the target board:
  Board    select
gdbserver :10000 QtHelloWorld -qws
  1. In Qt Creator, open the source file main.cpp and set a breakpoint at line 6. | To do this go with the mouse at line 6 and click with the right button to open the menu, select Set brackpoint at line 6
_images/qt-6.png
  1. Go to Debug→Start Debugging→Attach To Remote Debug Server, a form named “Start Debugger” will appear, insert the following data:
_images/qt-7.jpg
  • Kit: zedboard
  • Local executable:
  Host    select
/home/architech/architech_sdk/architech/zedboard/workspace/qt/build-QtHelloWorld-zedboard-Debug/QtHelloWorld

Press OK button to start the debug.

_images/qt-8.png
  1. The hotkeys to debug the application are:
  • F10: Step over
  • F11: Step into
  • Shift + F11: Step out
  • F5: Continue, or press this icon:
_images/qt-9.png
  1. To successfully exit from the debug it is better to close the graphical application from the target board with the mouse by clicking on the ‘X’ symbol.

6.6. Cross compiler

Yocto/OpenEmbedded can be driven to generate the cross-toolchain for your platform. There are two common ways to get that:

  Host    select
bitbake meta-toolchain

or

  Host    select
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:

  Host    select
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:

  Host    select
source /home/architech/architech_sdk/architech/zedboard/toolchain/environment-nofs

and you are ready to go.

6.7. Opkg

_images/opkg.png

Opkg (Open PacKaGe Management) is a lightweight package management system. It is written in C and resembles apt/dpkg in operation. It is intended for use on embedded Linux devices and is used in this capacity in the OpenEmbedded and OpenWrt projects.


Useful commands:

  • update the list of available packages:
  Board    select
opkg update
  • list available packages:
  Board    select
opkg list
  • list installed packages:
  Board    select
opkg list-installed
  • install packages:
  Board    select
opkg install <package 1> <package 2> ... <package n>
  • list package providing <file>
  Board    select
opkg search <file>
  • Show package information
  Board    select
opkg info <package>
  • show package dependencies:
  Board    select
opkg whatdepends <package>
  • remove packages:
  Board    select
opkg remove <package 1> <package 2> ... <package n>

6.7.1. Force Bitbake to install Opkg in the final image

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

  Host    select
/home/architech/architech_sdk/architech/zedboard/yocto/build/conf/local.conf

and add this line to it:

  Host    select
IMAGE_FEATURES_append = " package-management"

6.7.2. Create a repository

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:

  1. Install a web server on your machine, for example apache2:
  Host    select
sudo apt-get install apache2
  1. Configure apache web server to “see” the packages you built, for example:
  Host    select
sudo ln -s /home/architech/architech_sdk/architech/zedboard/yocto/build/tmp/deploy/ipk/ /var/www/zedboard-ipk
  1. Create a new configuration file on the target (for example /etc/opkg/my_packages.conf) containing lines like this one to index the packages related to a particular machine:
  Board    select
src/gz zedboard-zynq7 http://192.168.0.100:8000/zedboard-ipk/zedboard-zynq7

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.

  1. Connect the board and the personal computer you are developing on by means of an ethernet cable
  2. Update the list of available packages on the target
  Board    select
opkg update

6.7.3. Update repository index

Sometimes, you need to force bitbake to rebuild the index of packages by means of:

  Host    select
bitbake package-index