usermanual: Provide a section on Qt Embedded SDK

Explain how to configure, build and use a Qt Embedded SDK
generated with OpenEmbedded.

1 files changed, 110 insertions, 0 deletions

diff --git a/docs/usermanual/chapters/common_use_cases.xml b/docs/usermanual/chapters/common_use_cases.xml
index 2c693c681c..1407304ec9 100644
--- a/docs/usermanual/chapters/common_use_cases.xml
+++ b/docs/usermanual/chapters/common_use_cases.xml
@@ -511,8 +511,118 @@ SDK_SUFFIX = "toolchain-YOUR"
 
             <note>SDK creation currently does not work with the <emphasis>DISTRO</emphasis>
             set to <emphasis>micro</emphasis>.</note>
+
+            <note>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.</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 depedencies like directFB, glib-2.0, gstreamer-0.10, tslib
+            and more esoteric depedencies 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 depedencies.
+            </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>
+# bitbake meta-toolchain-qte
+</screen>
+            </para>
+
+            <note>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>.</note>
+
+            <note>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.</note>
+
+            <note>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.</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> to setup the
+            <emphasis>QMAKESPEC</emphasis> and various other paths.
+            </para>
+
+<screen>
+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
+# qmake2
+</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>
+# . /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 &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
+
+# qmake2
+# make
+</screen>
+            </para>
+
+        </section>
   </section>
 </chapter>