path: root/docs/usermanual/chapters/common_use_cases.xml

<?xml version="1.0" encoding="UTF-8"?>
<chapter id="chapter_common_use_cases">
  <title>Common Use-cases/tasks</title>

  <section id="commonuse_new_distro">
    <title>Creating a new Distribution</title>

    <para>Creating 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?
      <itemizedlist>
        <listitem>
          <para><command>DISTRO_VERSION</command> so users will know which
          version of the distribution they are using.</para>
        </listitem>

        <listitem>
          <para><command>DISTRO_TYPE</command> (release/debug) variable is
          used in some recipes to enable/disable some features - for example
          kernel output on screen for "debug" builds.</para>
        </listitem>

        <listitem>
          <para>Type of libc used: will it be glibc
          (<command>TARGET_OS</command> = "linux") or uclibc
          (<command>TARGET_OS</command> = "linux-uclibc")?</para>
        </listitem>

        <listitem>
          <para>Toolchain versions - for example gcc 3.4.4 based distro will
          have: <screen>
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"
            </screen></para>
        </listitem>

        <listitem>
          <para><command>DISTRO_FEATURES</command> which describe which
          features distro has. More about it in <link
          linkend="task-base">task-base</link> section.</para>
        </listitem>

        <listitem>
          <para>Versions of kernels used for supported devices: <screen>
PREFERRED_VERSION_linux-omap1_omap5912osk ?= "2.6.18+git"
PREFERRED_VERSION_linux-openzaurus ?= "2.6.17"
            </screen></para>
        </listitem>
      </itemizedlist></para>
  </section>

  <section id="commonuse_new_machine">
    <title>Adding a new Machine</title>

    <para>To 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.</para>

    <para>As usual some variables are required: <itemizedlist>
        <listitem>
          <para><command>TARGET_ARCH</command> describes which CPU
          architecture the machine uses.</para>
        </listitem>

        <listitem>
          <para><command>MACHINE_FEATURES</command> which describes which
          features the device has. More about it in <link
          linkend="task-base">task-base</link> section.</para>
        </listitem>

        <listitem>
          <para><command>PREFERRED_PROVIDER_virtual/kernel</command> has to
          point to the proper kernel recipe for this machine.</para>
        </listitem>
      </itemizedlist></para>

    <para>There are also some optional variables that can be defined:
    <itemizedlist>
    <listitem>
      <para>
        <command>MACHINE_OVERRIDES</command> lists additional items to add to
        the <command>OVERRIDES</command> variable, between the
        <command>DISTRO</command> and the <command>MACHINE</command>.  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 <command>SOC_FAMILY</command> or <command>MACHINE_CLASS</command>.
      </para>
      <para>
        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.
      </para>
    </listitem>
    <listitem>
          <para><command>SOC_FAMILY</command> 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.
          </para>
          <para>
            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.
          </para>
        </listitem>
    </itemizedlist></para>

    <para>Next the kernel recipe needs to be added if it doesn't already exist.
    </para>
  </section>

  <section id="commonuse_new_package">
    <title>Adding a new Package</title>

    <para>This 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.</para>

    <section>
        <title>building from unstable source code</title>
        <para>Building 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.
          <itemizedlist>
            <listitem><para>for svn: add 'PV = "1.1+svnr${SRCPV}"' to your bb file.</para></listitem>
            <listitem><para>for git: add 'PV = "1.1+gitr${SRCPV}"' to your bb file.</para></listitem>
            <listitem><para>for cvs: add 'PV = "1.1+cvs${SRCPV}"' to your bb file.</para></listitem>
          </itemizedlist>
        Accompany with stable SRCREV for your package directly in the package recipe.
        </para>
        <para>
        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.
        </para>
    </section>
  </section>

  <section id="commonuse_new_image">
    <title>Creating your own image</title>

    <para>Creating own image is easy - only few variables need to be set:
    <itemizedlist>
        <listitem>
          <para><command>IMAGE_BASENAME</command> to give a name for your own
          image</para>
        </listitem>

        <listitem>
          <para><command>PACKAGE_INSTALL</command> to give a list of packages
          to install into the image</para>
        </listitem>

        <listitem>
          <para><command>RDEPENDS</command> to give a list of recipes which
          are needed to be built to create this image</para>
        </listitem>

        <listitem>
          <para><command>IMAGE_LINGUAS</command> is an optional list of
          languages which has to be installed into the image</para>
        </listitem>
      </itemizedlist> Then add the <emphasis>image</emphasis> class using:
    <screen>
inherit image
</screen> And the image recipe is ready for usage.</para>
  </section>

  <section id="commonuse_prebuilt_toolchain">
    <title>Using a prebuilt toolchain to create your packages</title>

    <para>TODO: 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.</para>

  </section>

  <section id="commonuse_new_package_format">
    <title>Using a new package format</title>

    <para>This section is a stub, help us by expanding it</para>
  </section>

  <section id="commonuse_qte_sdk">
    <title>Creating Software Development Kits (SDKs)</title>

    <section>
        <title>What is provided by a SDK</title>

        <para>The 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.
        </para>

        <para>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.
        </para>
    </section>

    <section>
        <title>Creating a SDK with your libraries pre-installed</title>

        <section>
            <title>Preparing the host side</title>
            <para>Your 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 <emphasis>inherit sdk</emphasis> and by
            convention end with <emphasis>-sdk</emphasis> in the
            <command>PN</command>.
            </para>

            <para>A new task should be created that will assure that all
            host utilities will be installed. Place a file called
            <filename>task-YOUR-toolchain-host.bb</filename> in the
            <filename>recipes/tasks</filename> directory and place the
            following content in it:
<screen>
require task-sdk-host.bb
DESCRIPTION = "Host packages for YOUR SDK"
LICENSE = "MIT"
ALLOW_EMPTY = "1"
RDEPENDS_${PN} += "YOUR-DEPENDENCY-sdk"
</screen>
            </para>
        </section>

        <section>
            <title>Preparing the target side</title>
            <para>Your SDK should provide your user with header files and libraries
            he will need when doing application development. In OpenEmbedded the
            <command>${PN}-dev</command> 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.
            </para>

            <para>To install the development packages you will need to create a
            new task. Create a new file <filename>task-YOUR-toolchain-target.bb</filename>
            in the <filename>recipes/tasks</filename> directory and place the
            following content in it:
<screen>
DESCRIPTION = "Target package for YOUR SDK"
LICENSE = "MIT"
ALLOW_EMPTY = "1"

PR = "r0"

RDEPENDS_${PN} += "\
        task-sdk-bare \
        your-lib-dev \
        your-data
        "
</screen>
            </para>
        </section>

        <section>
            <title>Putting it together</title>
            <para>In 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.</para>

            <para>Create <filename>meta-toolchain-YOU.bb</filename> in the
            <filename>recipes/meta</filename> directory and place the following
            content in it:
<screen>
PR = "r0"
TOOLCHAIN_TARGET_TASK = "task-YOUR-toolchain-target"
TOOLCHAIN_HOST_TASK = "task-YOUR-toolchain-host"

require meta-toolchain.bb
SDK_SUFFIX = "toolchain-YOUR"
</screen>

            </para>

            <para>Using <command>bitbake meta-toolchain-YOU</command> the SDK
            creation should be started and you should find a <filename>sdk</filename>
            directory inside your deploy directory with a SDK waiting for you. With
            the above command you still need to have OE configured with your
            <filename>conf/local.conf</filename> to select the machine and
            distribution you are targeting.
            </para>

            <note><para>SDK creation currently does not work with the <emphasis>DISTRO</emphasis>
            set to <emphasis>micro</emphasis>.</para></note>

            <note><para>If the environment-setup script packaged in the SDK should
            require more environment look at the <filename>meta-toolchain-qte.bb</filename>
            to accomplish this.</para></note>
        </section>
    </section>
  </section>

  <section>
    <title>Creating and Using a Qt Embedded SDK</title>

        <section>
            <title>Creating the SDK</title>

            <para>The 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.
            </para>

            <para>OpenEmbedded provides an easy way to create a Qt Embedded
            SDK. In
            <filename>recipes/tasks/task-qte-toolchain-host.bb</filename> host
            tools like moc, uic, rcc, qmake will get installed and in <filename>
            recipes/tasks/task-qte-toolchain-target.bb</filename> the Qt4 header
            files and libraries will be installed.
            </para>

            <para>To build the SDK, setup OpenEmbedded in the usual way by picking
            a <emphasis>DISTRO</emphasis> and <emphasis>MACHINE</emphasis>. Issue
            the below command and after the operation finished you should find
            a SDK in the deployment directory.
<screen>
$ <command>bitbake</command> meta-toolchain-qte
</screen>
            </para>

            <note><para>The deployment directory depends on the distribution
            and used C library. In the case of Angstrom and glibc it is
            located in <filename>tmp/deploy/glibc/sdk</filename>.</para></note>

            <note><para>Change <filename>qt4-embedded.inc</filename> and
            <filename>qt4.inc</filename> for using different Qt configuration
            flags. This might include a custom qconfig.h to produce a reduced
            size build.</para></note>

            <note><para>When distributing the SDK make sure to include a written offer
            to provide the sourcecode of GPL licensed applications or provide
            parts of the <filename>sources</filename> folder. The <filename>
            sources</filename> folder is located right next to the <filename>sdk</filename>
            one.</para></note>
        </section>


        <section>
            <title>Using the Qt Embedded SDK</title>

            <para>In 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
            (<filename>/</filename>). Once this operation is finished you will
            find a new directory <filename>/usr/local/angstrom/arm/</filename> and
            it contains the <filename>environment-setup</filename> file to setup the
            <emphasis>QMAKESPEC</emphasis> and various other paths.
            </para>

<screen>
Untar the SDK once
$ <command>tar</command> -C / -xjf angstrom-armv5te-linux-gnueabi-toolchain-qte.tar.bz2

Before using it source the environment
$ <command>.</command> /usr/local/angstrom/arm/environment-setup

Use qmake2 to build software for the target
$ <command>qmake2</command>
</screen>

            <para>Creating and building a simple example. We will create a simple
            Qt Embedded application and use <command>qmake2</command> and
            <command>make</command> to cross compile.

<screen>
$ <command>.</command> /usr/local/angstrom/arm/environment-setup
$ <command>cd</command> $HOME
$ <command>mkdir</command> qte-example
$ <command>cd</command> qte-example

$ <command>echo</command> "TEMPLATE=app
SOURCES=main.cpp
" > qte-example.pro

$ <command>echo</command> '#include &lt;QApplication&gt;
#include &lt;QPushButton&gt;

int main(int argc, char** argv) {
    QApplication app(argc, argv);

    QPushButton btn("Hello World");
    btn.show();
    btn.showMaximized();

    return app.exec();
}
' > main.cpp

$ <command>qmake2</command>
$ <command>make</command>
</screen>
            </para>

        </section>
  </section>
</chapter>