| <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
| [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
| |
| <chapter id='sdk-intro'> |
| <title>Introduction</title> |
| |
| <section id='sdk-manual-intro'> |
| <title>Introduction</title> |
| |
| <para> |
| Welcome to the Yocto Project Software Development Kit (SDK) |
| Developer's Guide. |
| This manual provides information that explains how to use both the |
| Yocto Project extensible and standard SDKs to develop |
| applications and images. |
| Additionally, the manual also provides information on how to use |
| the popular <trademark class='trade'>Eclipse</trademark> IDE as part |
| of your application development workflow within the SDK environment. |
| <note> |
| Prior to the 2.0 Release of the Yocto Project, application |
| development was primarily accomplished through the use of the |
| Application Development Toolkit (ADT) and the availability |
| of stand-alone cross-development toolchains and other tools. |
| With the 2.1 Release of the Yocto Project, application development |
| has transitioned to within a tool-rich extensible SDK and the more |
| traditional standard SDK. |
| </note> |
| </para> |
| |
| <para> |
| All SDKs consist of the following: |
| <itemizedlist> |
| <listitem><para><emphasis>Cross-Development Toolchain</emphasis>: |
| This toolchain contains a compiler, debugger, and various |
| miscellaneous tools. |
| </para></listitem> |
| <listitem><para><emphasis>Libraries, Headers, and Symbols</emphasis>: |
| The libraries, headers, and symbols are specific to the image |
| (i.e. they match the image). |
| </para></listitem> |
| <listitem><para><emphasis>Environment Setup Script</emphasis>: |
| This <filename>*.sh</filename> file, once run, sets up the |
| cross-development environment by defining variables and |
| preparing for SDK use. |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| |
| <para> |
| Additionally an extensible SDK has tools that allow you to easily add |
| new applications and libraries to an image, modify the source of an |
| existing component, test changes on the target hardware, and easily |
| integrate an application into the |
| <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>. |
| </para> |
| |
| <para> |
| You can use an SDK to independently develop and test code |
| that is destined to run on some target machine. |
| SDKs are completely self-contained. |
| The binaries are linked against their own copy of |
| <filename>libc</filename>, which results in no dependencies |
| on the target system. |
| To achieve this, the pointer to the dynamic loader is |
| configured at install time since that path cannot be dynamically |
| altered. |
| This is the reason for a wrapper around the |
| <filename>populate_sdk</filename> and |
| <filename>populate_sdk_ext</filename> archives. |
| </para> |
| |
| <para> |
| Another feature for the SDKs is that only one set of cross-compiler |
| toolchain binaries are produced for any given architecture. |
| This feature takes advantage of the fact that the target hardware can |
| be passed to <filename>gcc</filename> as a set of compiler options. |
| Those options are set up by the environment script and contained in |
| variables such as |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> |
| and |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>. |
| This reduces the space needed for the tools. |
| Understand, however, that a sysroot is still needed for every target |
| since those binaries are target-specific. |
| </para> |
| |
| <para> |
| The SDK development environment consists of the following: |
| <itemizedlist> |
| <listitem><para>The self-contained SDK, which is an |
| architecture-specific cross-toolchain and |
| matching sysroots (target and native) all built by the |
| OpenEmbedded build system (e.g. the SDK). |
| The toolchain and sysroots are based on a |
| <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> |
| configuration and extensions, |
| which allows you to cross-develop on the host machine for the |
| target hardware. |
| Additionally, the extensible SDK contains the |
| <filename>devtool</filename> functionality. |
| </para></listitem> |
| <listitem><para>The Quick EMUlator (QEMU), which lets you simulate |
| target hardware. |
| QEMU is not literally part of the SDK. |
| You must build and include this emulator separately. |
| However, QEMU plays an important role in the development |
| process that revolves around use of the SDK. |
| </para></listitem> |
| <listitem><para>The Eclipse IDE Yocto Plug-in. |
| This plug-in is available for you if you are an Eclipse |
| user. |
| In the same manner as QEMU, the plug-in is not literally part |
| of the SDK but is rather available for use as part of the |
| development process. |
| </para></listitem> |
| <listitem><para>Various performance-related |
| <ulink url='http://www.eclipse.org/linuxtools/index.php'>tools</ulink> |
| that can enhance your development experience. |
| These tools are also separate from the actual SDK but can be |
| independently obtained and used in the development process. |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| |
| <para> |
| In summary, the extensible and standard SDK share many features. |
| However, the extensible SDK has powerful development tools to help you |
| more quickly develop applications. |
| Following is a table that summarizes the primary differences between |
| the standard and extensible SDK types when considering which to |
| build: |
| <informaltable frame='none'> |
| <tgroup cols='3' align='left' colsep='1' rowsep='1'> |
| <colspec colname='c1' colwidth='1*'/> |
| <colspec colname='c2' colwidth='1*'/> |
| <colspec colname='c3' colwidth='1*'/> |
| <thead> |
| <row> |
| <entry align="left"><emphasis>Feature</emphasis></entry> |
| <entry align="left"><emphasis>Standard SDK</emphasis></entry> |
| <entry align="left"><emphasis>Extensible SDK</emphasis></entry> |
| </row> |
| </thead> |
| <tbody> |
| <row> |
| <entry align="left">Toolchain</entry> |
| <entry align="left">Yes</entry> |
| <entry align="left">Yes*</entry> |
| </row> |
| <row> |
| <entry align="left">Debugger</entry> |
| <entry align="left">Yes</entry> |
| <entry align="left">Yes*</entry> |
| </row> |
| <row> |
| <entry align="left">Size</entry> |
| <entry align="left">100+ MBytes</entry> |
| <entry align="left">1+ GBytes (or 300+ MBytes for minimal w/toolchain)</entry> |
| </row> |
| <row> |
| <entry align="left"><filename>devtool</filename></entry> |
| <entry align="left">No</entry> |
| <entry align="left">Yes</entry> |
| </row> |
| <row> |
| <entry align="left">Build Images</entry> |
| <entry align="left">No</entry> |
| <entry align="left">Yes</entry> |
| </row> |
| <row> |
| <entry align="left">Updateable</entry> |
| <entry align="left">No</entry> |
| <entry align="left">Yes</entry> |
| </row> |
| <row> |
| <entry align="left">Managed Sysroot**</entry> |
| <entry align="left">No</entry> |
| <entry align="left">Yes</entry> |
| </row> |
| <row> |
| <entry align="left">Installed Packages</entry> |
| <entry align="left">No***</entry> |
| <entry align="left">Yes****</entry> |
| </row> |
| <row> |
| <entry align="left">Construction</entry> |
| <entry align="left">Packages</entry> |
| <entry align="left">Shared State</entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| <literallayout class='monospaced'> |
| * Extensible SDK will contain the toolchain and debugger if <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink> is "full" or <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink> is "1", which is the default. |
| |
| ** Sysroot is managed through use of <filename>devtool</filename>. Thus, it is less likely that you will corrupt your SDK sysroot when you try to add additional libraries. |
| |
| *** Runtime package management can be added to the standard SDK but it is not supported by default. |
| |
| **** You must build and make the shared state available to extensible SDK users for "packages" you want to enable users to install. |
| </literallayout> |
| </para> |
| |
| <section id='the-cross-development-toolchain'> |
| <title>The Cross-Development Toolchain</title> |
| |
| <para> |
| The |
| <ulink url='&YOCTO_DOCS_DEV_URL;#cross-development-toolchain'>Cross-Development Toolchain</ulink> |
| consists of a cross-compiler, cross-linker, and cross-debugger |
| that are used to develop user-space applications for targeted |
| hardware. |
| Additionally, for an extensible SDK, the toolchain also has |
| built-in <filename>devtool</filename> functionality. |
| This toolchain is created by running a SDK installer script |
| or through a |
| <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> |
| that is based on your Metadata configuration or extension for |
| your targeted device. |
| The cross-toolchain works with a matching target sysroot. |
| </para> |
| </section> |
| |
| <section id='sysroot'> |
| <title>Sysroots</title> |
| |
| <para> |
| The native and target sysroots contain needed headers and libraries |
| for generating binaries that run on the target architecture. |
| The target sysroot is based on the target root filesystem image |
| that is built by the OpenEmbedded build system and uses the same |
| Metadata configuration used to build the cross-toolchain. |
| </para> |
| </section> |
| |
| <section id='the-qemu-emulator'> |
| <title>The QEMU Emulator</title> |
| |
| <para> |
| The QEMU emulator allows you to simulate your hardware while |
| running your application or image. |
| QEMU is not part of the SDK but is made available a number of ways: |
| <itemizedlist> |
| <listitem><para> |
| If you have cloned the <filename>poky</filename> Git |
| repository to create a |
| <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> |
| and you have sourced the environment setup script, QEMU is |
| installed and automatically available. |
| </para></listitem> |
| <listitem><para> |
| If you have downloaded a Yocto Project release and unpacked |
| it to create a |
| <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> |
| and you have sourced the environment setup script, QEMU is |
| installed and automatically available. |
| </para></listitem> |
| <listitem><para> |
| If you have installed the cross-toolchain tarball and you |
| have sourced the toolchain's setup environment script, QEMU |
| is also installed and automatically available. |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| </section> |
| |
| <section id='eclipse-overview'> |
| <title>Eclipse Yocto Plug-in</title> |
| |
| <para> |
| The Eclipse IDE is a popular development environment and it fully |
| supports development using the Yocto Project. |
| When you install and configure the Eclipse Yocto Project Plug-in |
| into the Eclipse IDE, you maximize your Yocto Project experience. |
| Installing and configuring the Plug-in results in an environment |
| that has extensions specifically designed to let you more easily |
| develop software. |
| These extensions allow for cross-compilation, deployment, and |
| execution of your output into a QEMU emulation session. |
| You can also perform cross-debugging and profiling. |
| The environment also supports many performance-related |
| <ulink url='http://www.eclipse.org/linuxtools/index.php'>tools</ulink> |
| that enhance your development experience. |
| <note> |
| Previous releases of the Eclipse Yocto Plug-in supported |
| "user-space tools" (i.e. LatencyTOP, PowerTOP, Perf, SystemTap, |
| and Lttng-ust) that also added to the development experience. |
| These tools have been deprecated beginning with this release |
| of the plug-in. |
| </note> |
| </para> |
| |
| <para> |
| For information about the application development workflow that |
| uses the Eclipse IDE and for a detailed example of how to install |
| and configure the Eclipse Yocto Project Plug-in, see the |
| "<link linkend='sdk-developing-applications-using-eclipse'>Developing Applications Using <trademark class='trade'>Eclipse</trademark></link>" |
| section. |
| </para> |
| </section> |
| |
| <section id='performance-enhancing-tools'> |
| <title>Performance Enhancing Tools</title> |
| |
| <para> |
| Supported performance enhancing tools are available that let you |
| profile, debug, and perform tracing on your projects developed |
| using Eclipse. |
| For information on these tools see |
| <ulink url='http://www.eclipse.org/linuxtools/'>http://www.eclipse.org/linuxtools/</ulink>. |
| </para> |
| </section> |
| </section> |
| |
| <section id='sdk-development-model'> |
| <title>SDK Development Model</title> |
| |
| <para> |
| Fundamentally, the SDK fits into the development process as follows: |
| <imagedata fileref="figures/sdk-environment.png" align="center" width="6in" depth="5in" scalefit="100" /> |
| The SDK is installed on any machine and can be used to develop |
| applications, images, and kernels. |
| An SDK can even be used by a QA Engineer or Release Engineer. |
| The fundamental concept is that the machine that has the SDK installed |
| does not have to be associated with the machine that has the |
| Yocto Project installed. |
| A developer can independently compile and test an object on their |
| machine and then, when the object is ready for integration into an |
| image, they can simply make it available to the machine that has the |
| Yocto Project. |
| Once the object is available, the image can be rebuilt using the |
| Yocto Project to produce the modified image. |
| </para> |
| |
| <para> |
| You just need to follow these general steps: |
| <orderedlist> |
| <listitem><para><emphasis>Install the SDK for your target hardware:</emphasis> |
| For information on how to install the SDK, see the |
| "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>" |
| section.</para></listitem> |
| <listitem><para><emphasis>Download or Build the Target Image:</emphasis> |
| The Yocto Project supports several target architectures |
| and has many pre-built kernel images and root filesystem |
| images.</para> |
| <para>If you are going to develop your application on |
| hardware, go to the |
| <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink> |
| download area and choose a target machine area |
| from which to download the kernel image and root filesystem. |
| This download area could have several files in it that |
| support development using actual hardware. |
| For example, the area might contain |
| <filename>.hddimg</filename> files that combine the |
| kernel image with the filesystem, boot loaders, and |
| so forth. |
| Be sure to get the files you need for your particular |
| development process.</para> |
| <para>If you are going to develop your application and |
| then run and test it using the QEMU emulator, go to the |
| <ulink url='&YOCTO_QEMU_DL_URL;'><filename>machines/qemu</filename></ulink> |
| download area. |
| From this area, go down into the directory for your |
| target architecture (e.g. <filename>qemux86_64</filename> |
| for an <trademark class='registered'>Intel</trademark>-based |
| 64-bit architecture). |
| Download kernel, root filesystem, and any other files you |
| need for your process. |
| <note> |
| To use the root filesystem in QEMU, you |
| need to extract it. |
| See the |
| "<link linkend='sdk-extracting-the-root-filesystem'>Extracting the Root Filesystem</link>" |
| section for information on how to extract the root |
| filesystem. |
| </note> |
| </para></listitem> |
| <listitem><para><emphasis>Develop and Test your |
| Application:</emphasis> At this point, you have the tools |
| to develop your application. |
| If you need to separately install and use the QEMU |
| emulator, you can go to |
| <ulink url='http://wiki.qemu.org/Main_Page'>QEMU Home Page</ulink> |
| to download and learn about the emulator. |
| See the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>" |
| chapter in the Yocto Project Development Manual |
| for information on using QEMU within the Yocto |
| Project.</para></listitem> |
| </orderedlist> |
| </para> |
| |
| <para> |
| The remainder of this manual describes how to use both the standard |
| SDK and the extensible SDK. |
| Information also exists in appendix form that describes how you can |
| build, install, and modify an SDK. |
| </para> |
| </section> |
| |
| </chapter> |
| <!-- |
| vim: expandtab tw=80 ts=4 |
| --> |