Common Use-cases/tasksCreating a new DistributionCreating a new distribution is not complicated, however we urge you
to try existing distributions first, because it's also very easy to do
wrong. The config needs to be created in $OEBASE/openembedded/conf/distro
directory. So what has to be inside?
DISTRO_VERSION so users will know which
version of the distribution they are using.DISTRO_TYPE (release/debug) variable is
used in some recipes to enable/disable some features - for example
kernel output on screen for "debug" builds.Type of libc used: will it be glibc
(TARGET_OS = "linux") or uclibc
(TARGET_OS = "linux-uclibc")?Toolchain versions - for example gcc 3.4.4 based distro will
have:
PREFERRED_PROVIDERS += " virtual/${TARGET_PREFIX}gcc-initial:gcc-cross-initial"
PREFERRED_PROVIDERS += " virtual/${TARGET_PREFIX}gcc:gcc-cross"
PREFERRED_PROVIDERS += " virtual/${TARGET_PREFIX}g++:gcc-cross"
PREFERRED_VERSION_binutils = "2.16"
PREFERRED_VERSION_binutils-cross = "2.16"
PREFERRED_VERSION_gcc = "3.4.4"
PREFERRED_VERSION_gcc-cross = "3.4.4"
PREFERRED_VERSION_gcc-initial-cross = "3.4.4"
DISTRO_FEATURES which describe which
features distro has. More about it in task-base section.Versions of kernels used for supported devices:
PREFERRED_VERSION_linux-omap1_omap5912osk ?= "2.6.18+git"
PREFERRED_VERSION_linux-openzaurus ?= "2.6.17"
To get more stable build it is good to make use of
sane-srcdates.inc file which contain working SRCDATE for many of
floating recipes.
require conf/distro/include/sane-srcdates.inc
It also should have global SRCDATE
value set (format is ISO date: YYYYMMDD):
SRCDATE = "20061014"
Adding a new MachineTo be able to build for a device OpenEmbedded has to know about it,
so a machine config file needs to be written. All of the machine
configs are stored in $OEBASE/openembedded/conf/machine/ directory.As usual some variables are required: TARGET_ARCH describes which CPU
architecture the machine uses.MACHINE_FEATURES which describes which
features the device has. More about it in task-base section.PREFERRED_PROVIDER_virtual/kernel has to
point to the proper kernel recipe for this machine.There are also some optional variables that can be defined:
MACHINE_OVERRIDES lists additional items to add to
the OVERRIDES variable, between the
DISTRO and the MACHINE. This is
utilized to add overrides which are less specific than the machine,
but are nonetheless related to it, allowing us to define variables a
certain way for a group of machines, rather than for each individual
one. As an example, this variable may be used by the distribution to
add SOC_FAMILY or MACHINE_CLASS.
Note that this variable is space separated, and should always be
manipulated with +=, to ensure it's built up incrementally, and no
additions are lost.
SOC_FAMILY describes a family of processors
that all share common features such as kernel versions,
bootloaders, etc. This is used to allow overrides for a whole
set of devices rather than per machine overrides being used.
The use of SOC_FAMILY as an override is currently a distribution
or local setting.
NOTE: SOC_FAMILY is different than MACHINE_CLASS in that
MACHINE_CLASS is intended to specify a grouping of devices
that may have different processors but share common features.
For example all OMAP3 devices can be described using the SOC_FAMILY
"omap3" and this value can be used in overrides to prevent
requiring multiple machine specific overrides. MACHINE_CLASS
might be used to describe a class of devices such as a cell
phone in which the processor may be different but the
features such as touchscreen, GPS, modem, etc are the same.
Next the kernel recipe needs to be added if it doesn't already exist.
Adding a new PackageThis section is a stub, help us by expanding it. Learn by example, go through the
recipes that are already there and mimic them to do what you want.building from unstable source codeBuilding against the latest, bleeding-edge source has some intricacies of its own.
For one, it is desirable to pin down a code revision that is known to build to
prevent random breakage in OE at the most inopportune time for all OE users. Here is
how to do that properly.
for svn: add 'PV = "1.1+svnr${SRCREV}"' to your bb file.for cvs: add 'PV = "1.1+cvs${SRCREV}"' to your bb file.
Accompany either with an entry to conf/distro/include/sane-srcrevs.inc for a revision that you know
builds successfully. It is also common to define the stable SRCREV
for your package directly in the package recipe.
If you really absolutely have to follow the latest commits, you can do that by adding
'SRCREV_pn-linux-davinci ?= ${AUTOREV}' to your local.conf, for example. In this case,
you'd build against the most recent and unstable source for the pn-linux-davinci package.
Creating your own imageCreating own image is easy - only few variables need to be set:
IMAGE_BASENAME to give a name for your own
imagePACKAGE_INSTALL to give a list of packages
to install into the imageRDEPENDS to give a list of recipes which
are needed to be built to create this imageIMAGE_LINGUAS is an optional list of
languages which has to be installed into the image Then add the image class using:
inherit image
And the image recipe is ready for usage.Using a prebuilt toolchain to create your packagesTODO: You want to use external-toolchain. Setting PREFERRED_PROVIDER
for the toolchain to that + environment variables + toolchain layout. Please
someone write the documentation for that.Using a new package formatThis section is a stub, help us by expanding itCreating Software Development Kits (SDKs)What is provided by a SDKThe Software Development Kit (SDK) should be easy to install and
enable your user-base to create binaries and libraries that work on the
target hardware.
To accomplish this goal OpenEmbedded SDKs contain tools for the
host and tools for the target hardware. Among these tools is a cross
compiler, libraries and header files for additional dependencies, pkg-config
files to allow buildsystems to easily find the dependencies, a file with
results for autoconf and a script that can be sourced to setup the
environment.
Creating a SDK with your libraries pre-installedPreparing the host sideYour SDK might need utilities that will run on the
host. These could include scripts, buildsystem software like
cmake, or an emulator like qemu. For these dependencies it is
imported that they inherit sdk and by
convention end with -sdk in the
PN.
A new task should be created that will assure that all
host utilities will be installed. Place a file called
task-YOUR-toolchain-host.bb in the
recipes/tasks directory and place the
following content in it:
require task-sdk-host.bb
DESCRIPTION = "Host packages for YOUR SDK"
LICENSE = "MIT"
ALLOW_EMPTY = "1"
RDEPENDS_${PN} += "YOUR-DEPENDENCY-sdk"
Preparing the target sideYour SDK should provide your user with header files and libraries
he will need when doing application development. In OpenEmbedded the
${PN}-dev is providing the header files, pkg-config
files and symbolic links to libraries to allow using the library. The SDK
should install these development packages to the SDK.
To install the development packages you will need to create a
new task. Create a new file task-YOUR-toolchain-target.bb
in the recipes/tasks directory and place the
following content in it:
DESCRIPTION = "Target package for YOUR SDK"
LICENSE = "MIT"
ALLOW_EMPTY = "1"
PR = "r0"
RDEPENDS_${PN} += "\
task-sdk-bare \
your-lib-dev \
your-data
"
Putting it togetherIn the previous two sections we have prepared the host and
target side. One thing that is missing is combining the two newly
created tasks and actually creating the SDK. This is what we are
going to do now.Create meta-toolchain-YOU.bb in the
recipes/meta directory and place the following
content in it:
PR = "r0"
TOOLCHAIN_TARGET_TASK = "task-YOUR-toolchain-target"
TOOLCHAIN_HOST_TASK = "task-YOUR-toolchain-host"
require meta-toolchain.bb
SDK_SUFFIX = "toolchain-YOUR"
Using bitbake meta-toolchain-YOU the SDK
creation should be started and you should find a sdk
directory inside your deploy directory with a SDK waiting for you. With
the above command you still need to have OE configured with your
conf/local.conf to select the machine and
distribution you are targeting.
SDK creation currently does not work with the DISTRO
set to micro.If the environment-setup script packaged in the SDK should
require more environment look at the meta-toolchain-qte.bb
to accomplish this.Creating and Using a Qt Embedded SDKCreating the SDKThe SDK should contain a build of Qt Embedded, but also
optional dependencies like directFB, glib-2.0, gstreamer-0.10, tslib
and more esoteric dependencies like mysql and postgres. This allows
developers to simply start developing using Qt and enables system
integrators to easily recompile Qt and base libraries without tracking
down extra dependencies.
OpenEmbedded provides an easy way to create a Qt Embedded
SDK. In
recipes/tasks/task-qte-toolchain-host.bb host
tools like moc, uic, rcc, qmake will get installed and in
recipes/tasks/task-qte-toolchain-target.bb the Qt4 header
files and libraries will be installed.
To build the SDK, setup OpenEmbedded in the usual way by picking
a DISTRO and MACHINE. Issue
the below command and after the operation finished you should find
a SDK in the deployment directory.
$ bitbake meta-toolchain-qte
The deployment directory depends on the distribution
and used C library. In the case of Angstrom and glibc it is
located in tmp/deploy/glibc/sdk.Change qt4-embedded.inc and
qt4.inc for using different Qt configuration
flags. This might include a custom qconfig.h to produce a reduced
size build.When distributing the SDK make sure to include a written offer
to provide the sourcecode of GPL licensed applications or provide
parts of the sources folder. The
sources folder is located right next to the sdk
one.Using the Qt Embedded SDKIn this example we are assuming that the target hardware
is an armv5t system and the SDK targets the Angstrom Distribution. You
should start by downloading the SDK and untar it to the root folder
(/). Once this operation is finished you will
find a new directory /usr/local/angstrom/arm/ and
it contains the environment-setup file to setup the
QMAKESPEC and various other paths.
Untar the SDK once
$ tar -C / -xjf angstrom-armv5te-linux-gnueabi-toolchain-qte.tar.bz2
Before using it source the environment
$ . /usr/local/angstrom/arm/environment-setup
Use qmake2 to build software for the target
$ qmake2Creating and building a simple example. We will create a simple
Qt Embedded application and use qmake2 and
make to cross compile.
$ . /usr/local/angstrom/arm/environment-setup
$ cd $HOME
$ mkdir qte-example
$ cd qte-example
$ echo "TEMPLATE=app
SOURCES=main.cpp
" > qte-example.pro
$ echo '#include <QApplication>
#include <QPushButton>
int main(int argc, char** argv) {
QApplication app(argc, argv);
QPushButton btn("Hello World");
btn.show();
btn.showMaximized();
return app.exec();
}
' > main.cpp
$ qmake2
$ make