usermanual: Start a chapter on how to build your own SDK.

1 files changed, 113 insertions, 0 deletions

diff --git a/docs/usermanual/chapters/common_use_cases.xml b/docs/usermanual/chapters/common_use_cases.xml
index 241eb5318b..2c693c681c 100644
--- a/docs/usermanual/chapters/common_use_cases.xml
+++ b/docs/usermanual/chapters/common_use_cases.xml
@@ -402,4 +402,117 @@ ASSUME_SHLIBS = "libqtopia2.so.2:qtopia2_2.4 libc.so.6:libc"
 
     <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 userbase 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>Preapring 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> isi 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 create 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 targetting.
+            </para>
+
+            <note>SDK creation currently does not work with the <emphasis>DISTRO</emphasis>
+            set to <emphasis>micro</emphasis>.</note>
+        </section>
+    </section>
+
+  </section>
 </chapter>