diff options
Diffstat (limited to 'yocto-poky/documentation/dev-manual/dev-manual-model.xml')
| -rw-r--r-- | yocto-poky/documentation/dev-manual/dev-manual-model.xml | 2624 |
1 files changed, 2624 insertions, 0 deletions
diff --git a/yocto-poky/documentation/dev-manual/dev-manual-model.xml b/yocto-poky/documentation/dev-manual/dev-manual-model.xml new file mode 100644 index 000000000..6e0ded2f1 --- /dev/null +++ b/yocto-poky/documentation/dev-manual/dev-manual-model.xml @@ -0,0 +1,2624 @@ +<!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='dev-manual-model'> + +<title>Common Development Models</title> + +<para> + Many development models exist for which you can use the Yocto Project. + This chapter overviews simple methods that use tools provided by the + Yocto Project: + <itemizedlist> + <listitem><para><emphasis>System Development:</emphasis> + System Development covers Board Support Package (BSP) development + and kernel modification or configuration. + For an example on how to create a BSP, see the + "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" + section in the Yocto Project Board Support Package (BSP) + Developer's Guide. + For more complete information on how to work with the kernel, + see the + <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>. + </para></listitem> + <listitem><para><emphasis>User Application Development:</emphasis> + User Application Development covers development of applications + that you intend to run on target hardware. + For information on how to set up your host development system for + user-space application development, see the + <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>. + For a simple example of user-space application development using + the <trademark class='trade'>Eclipse</trademark> IDE, see the + "<link linkend='application-development-workflow'>Application + Development Workflow</link>" section. + </para></listitem> + <listitem><para><emphasis>Temporary Source Code Modification:</emphasis> + Direct modification of temporary source code is a convenient + development model to quickly iterate and develop towards a + solution. + Once you implement the solution, you should of course take + steps to get the changes upstream and applied in the affected + recipes. + </para></listitem> + <listitem><para><emphasis>Image Development using Toaster:</emphasis> + You can use <ulink url='&YOCTO_HOME_URL;/Tools-resources/projects/toaster'>Toaster</ulink> + to build custom operating system images within the build + environment. + Toaster provides an efficient interface to the OpenEmbedded build + that allows you to start builds and examine build statistics. + </para></listitem> + <listitem><para><emphasis>Image Development using Hob:</emphasis> + You can use the <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink> + to build custom operating system images within the build + environment. + Hob provides an efficient interface to the OpenEmbedded build system. + </para></listitem> + <listitem><para><emphasis>Using a Development Shell:</emphasis> + You can use a <filename>devshell</filename> to efficiently debug + commands or simply edit packages. + Working inside a development shell is a quick way to set up the + OpenEmbedded build environment to work on parts of a project. + </para></listitem> + </itemizedlist> +</para> + +<section id='system-development-model'> + <title>System Development Workflow</title> + + <para> + System development involves modification or creation of an image that you want to run on + a specific hardware target. + Usually, when you want to create an image that runs on embedded hardware, the image does + not require the same number of features that a full-fledged Linux distribution provides. + Thus, you can create a much smaller image that is designed to use only the + features for your particular hardware. + </para> + + <para> + To help you understand how system development works in the Yocto Project, this section + covers two types of image development: BSP creation and kernel modification or + configuration. + </para> + + <section id='developing-a-board-support-package-bsp'> + <title>Developing a Board Support Package (BSP)</title> + + <para> + A BSP is a collection of recipes that, when applied during a build, results in + an image that you can run on a particular board. + Thus, the package when compiled into the new image, supports the operation of the board. + </para> + + <note> + For a brief list of terms used when describing the development process in the Yocto Project, + see the "<link linkend='yocto-project-terms'>Yocto Project Terms</link>" section. + </note> + + <para> + The remainder of this section presents the basic + steps used to create a BSP using the Yocto Project's + <ulink url='&YOCTO_DOCS_BSP_URL;#using-the-yocto-projects-bsp-tools'>BSP Tools</ulink>. + Although not required for BSP creation, the + <filename>meta-intel</filename> repository, which contains + many BSPs supported by the Yocto Project, is part of the example. + </para> + + <para> + For an example that shows how to create a new layer using the tools, see the + "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" + section in the Yocto Project Board Support Package (BSP) Developer's Guide. + </para> + + <para> + The following illustration and list summarize the BSP creation general workflow. + </para> + + <para> + <imagedata fileref="figures/bsp-dev-flow.png" width="6in" depth="7in" align="center" scalefit="1" /> + </para> + + <para> + <orderedlist> + <listitem><para><emphasis>Set up your host development system to support + development using the Yocto Project</emphasis>: See the + "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>" + and the + "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>" sections both + in the Yocto Project Quick Start for requirements.</para></listitem> + <listitem><para><emphasis>Establish a local copy of the project files on your + system</emphasis>: You need this <link linkend='source-directory'>Source + Directory</link> available on your host system. + Having these files on your system gives you access to the build + process and to the tools you need. + For information on how to set up the Source Directory, + see the + "<link linkend='getting-setup'>Getting Set Up</link>" section.</para></listitem> + <listitem><para><emphasis>Establish the <filename>meta-intel</filename> + repository on your system</emphasis>: Having local copies + of these supported BSP layers on your system gives you + access to layers you might be able to build on or modify + to create your BSP. + For information on how to get these files, see the + "<link linkend='getting-setup'>Getting Set Up</link>" section.</para></listitem> + <listitem><para><emphasis>Create your own BSP layer using the + <ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'><filename>yocto-bsp</filename></ulink> script</emphasis>: + Layers are ideal for + isolating and storing work for a given piece of hardware. + A layer is really just a location or area in which you place + the recipes and configurations for your BSP. + In fact, a BSP is, in itself, a special type of layer. + The simplest way to create a new BSP layer that is compliant with the + Yocto Project is to use the <filename>yocto-bsp</filename> script. + For information about that script, see the + "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" + section in the Yocto Project Board Support (BSP) Developer's Guide. + </para> + <para> + Another example that illustrates a layer is an application. + Suppose you are creating an application that has library or other dependencies in + order for it to compile and run. + The layer, in this case, would be where all the recipes that define those dependencies + are kept. + The key point for a layer is that it is an isolated area that contains + all the relevant information for the project that the OpenEmbedded build + system knows about. + For more information on layers, see the + "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>" + section. + For more information on BSP layers, see the + "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" section in the + Yocto Project Board Support Package (BSP) Developer's Guide.</para> + <note>Five BSPs exist that are part of the + Yocto Project release: <filename>genericx86</filename>, <filename>genericx86-64</filename>, + <filename>beaglebone</filename> (ARM), + <filename>mpc8315e</filename> (PowerPC), + and <filename>edgerouter</filename> (MIPS). + The recipes and configurations for these five BSPs are located and dispersed + within the <link linkend='source-directory'>Source Directory</link>. + On the other hand, the <filename>meta-intel</filename> layer + contains BSP layers for many supported BSPs (e.g. + Crystal Forest, Emenlow, Fish River Island 2, Haswell, + Jasper Forest, and so forth). + Aside from the BSPs in the <filename>meta-intel</filename> + layer, the + <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> + contain additional BSP layers such as + <filename>meta-minnow</filename> and + <filename>meta-raspberrypi</filename>.</note> + <para>When you set up a layer for a new BSP, you should follow a standard layout. + This layout is described in the + "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout'>Example Filesystem Layout</ulink>" + section of the Board Support Package (BSP) Development Guide. + In the standard layout, you will notice a suggested structure for recipes and + configuration information. + You can see the standard layout for a BSP by examining + any supported BSP found in the <filename>meta-intel</filename> layer inside + the Source Directory.</para></listitem> + <listitem><para><emphasis>Make configuration changes to your new BSP + layer</emphasis>: The standard BSP layer structure organizes the files you need + to edit in <filename>conf</filename> and several <filename>recipes-*</filename> + directories within the BSP layer. + Configuration changes identify where your new layer is on the local system + and identify which kernel you are going to use. + When you run the <filename>yocto-bsp</filename> script, you are able to interactively + configure many things for the BSP (e.g. keyboard, touchscreen, and so forth). + </para></listitem> + <listitem><para><emphasis>Make recipe changes to your new BSP layer</emphasis>: Recipe + changes include altering recipes (<filename>.bb</filename> files), removing + recipes you do not use, and adding new recipes or append files + (<filename>.bbappend</filename>) that you need to support your hardware. + </para></listitem> + <listitem><para><emphasis>Prepare for the build</emphasis>: Once you have made all the + changes to your BSP layer, there remains a few things + you need to do for the OpenEmbedded build system in order for it to create your image. + You need to get the build environment ready by sourcing an environment setup script + (i.e. <filename>oe-init-build-env</filename> or + <filename>oe-init-build-env-memres</filename>) + and you need to be sure two key configuration files are configured appropriately: + the <filename>conf/local.conf</filename> and the + <filename>conf/bblayers.conf</filename> file. + You must make the OpenEmbedded build system aware of your new layer. + See the + "<link linkend='enabling-your-layer'>Enabling Your Layer</link>" section + for information on how to let the build system know about your new layer.</para> + <para>The entire process for building an image is overviewed in the section + "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" section + of the Yocto Project Quick Start. + You might want to reference this information.</para></listitem> + <listitem><para><emphasis>Build the image</emphasis>: The OpenEmbedded build system + uses the BitBake tool to build images based on the type of image you want to create. + You can find more information about BitBake in the + <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. + </para> + <para>The build process supports several types of images to satisfy different needs. + See the + "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter + in the Yocto Project Reference Manual for information on + supported images.</para></listitem> + </orderedlist> + </para> + + <para> + You can view a video presentation on "Building Custom Embedded Images with Yocto" + at <ulink url='http://free-electrons.com/blog/elc-2011-videos'>Free Electrons</ulink>. + After going to the page, just search for "Embedded". + You can also find supplemental information in the + <ulink url='&YOCTO_DOCS_BSP_URL;'> + Yocto Project Board Support Package (BSP) Developer's Guide</ulink>. + Finally, there is helpful material and links on this + <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>wiki page</ulink>. + Although a bit dated, you might find the information on the wiki + helpful. + </para> + </section> + + <section id='modifying-the-kernel'> + <title><anchor id='kernel-spot' />Modifying the Kernel</title> + + <para> + Kernel modification involves changing the Yocto Project kernel, which could involve changing + configuration options as well as adding new kernel recipes. + Configuration changes can be added in the form of configuration fragments, while recipe + modification comes through the kernel's <filename>recipes-kernel</filename> area + in a kernel layer you create. + </para> + + <para> + The remainder of this section presents a high-level overview of the Yocto Project + kernel architecture and the steps to modify the kernel. + You can reference the + "<link linkend='patching-the-kernel'>Patching the Kernel</link>" section + for an example that changes the source code of the kernel. + For information on how to configure the kernel, see the + "<link linkend='configuring-the-kernel'>Configuring the Kernel</link>" section. + For more information on the kernel and on modifying the kernel, see the + <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>. + </para> + + <section id='kernel-overview'> + <title>Kernel Overview</title> + + <para> + Traditionally, when one thinks of a patched kernel, they think of a base kernel + source tree and a fixed structure that contains kernel patches. + The Yocto Project, however, employs mechanisms that, in a sense, result in a kernel source + generator. + By the end of this section, this analogy will become clearer. + </para> + + <para> + You can find a web interface to the Yocto Project kernel source repositories at + <ulink url='&YOCTO_GIT_URL;'></ulink>. + If you look at the interface, you will see to the left a grouping of + Git repositories titled "Yocto Linux Kernel." + Within this group, you will find several kernels supported by + the Yocto Project: + <itemizedlist> + <listitem><para><emphasis> + <filename>linux-yocto-3.8</filename></emphasis> - The + stable Yocto Project kernel to use with the Yocto + Project Release 1.4. This kernel is based on the + Linux 3.8 released kernel. + </para></listitem> + <listitem><para><emphasis> + <filename>linux-yocto-3.10</filename></emphasis> - An + additional, unsupported Yocto Project kernel used with + the Yocto Project Release 1.5. + This kernel is based on the Linux 3.10 released kernel. + </para></listitem> + <listitem><para><emphasis> + <filename>linux-yocto-3.14</filename></emphasis> - The + stable Yocto Project kernel to use with the Yocto + Project Releases 1.6 and 1.7. + This kernel is based on the Linux 3.14 released kernel. + </para></listitem> + <listitem><para><emphasis> + <filename>linux-yocto-3.17</filename></emphasis> - An + additional, unsupported Yocto Project kernel used with + the Yocto Project Release 1.7. + This kernel is based on the Linux 3.17 released kernel. + </para></listitem> + <listitem><para><emphasis> + <filename>linux-yocto-3.19</filename></emphasis> - The + stable Yocto Project kernel to use with the Yocto + Project Release 1.8. + This kernel is based on the Linux 3.19 released kernel. + </para></listitem> + <listitem><para><emphasis> + <filename>linux-yocto-dev</filename></emphasis> - A + development kernel based on the latest upstream release + candidate available. + </para></listitem> + </itemizedlist> + </para> + + <para> + The kernels are maintained using the Git revision control system + that structures them using the familiar "tree", "branch", and "leaf" scheme. + Branches represent diversions from general code to more specific code, while leaves + represent the end-points for a complete and unique kernel whose source files, + when gathered from the root of the tree to the leaf, accumulate to create the files + necessary for a specific piece of hardware and its features. + The following figure displays this concept: + <para> + <imagedata fileref="figures/kernel-overview-1.png" + width="6in" depth="6in" align="center" scale="100" /> + </para> + + <para> + Within the figure, the "Kernel.org Branch Point" represents the point in the tree + where a supported base kernel is modified from the Linux kernel. + For example, this could be the branch point for the <filename>linux-yocto-3.19</filename> + kernel. + Thus, everything further to the right in the structure is based on the + <filename>linux-yocto-3.19</filename> kernel. + Branch points to the right in the figure represent where the + <filename>linux-yocto-3.19</filename> kernel is modified for specific hardware + or types of kernels, such as real-time kernels. + Each leaf thus represents the end-point for a kernel designed to run on a specific + targeted device. + </para> + + <para> + The overall result is a Git-maintained repository from which all the supported + kernel types can be derived for all the supported devices. + A big advantage to this scheme is the sharing of common features by keeping them in + "larger" branches within the tree. + This practice eliminates redundant storage of similar features shared among kernels. + </para> + + <note> + Keep in mind the figure does not take into account all the supported Yocto + Project kernel types, but rather shows a single generic kernel just for conceptual purposes. + Also keep in mind that this structure represents the Yocto Project source repositories + that are either pulled from during the build or established on the host development system + prior to the build by either cloning a particular kernel's Git repository or by + downloading and unpacking a tarball. + </note> + + <para> + Upstream storage of all the available kernel source code is one thing, while + representing and using the code on your host development system is another. + Conceptually, you can think of the kernel source repositories as all the + source files necessary for all the supported kernels. + As a developer, you are just interested in the source files for the kernel on + which you are working. + And, furthermore, you need them available on your host system. + </para> + + <para> + Kernel source code is available on your host system a couple of different + ways. + If you are working in the kernel all the time, you probably would want + to set up your own local Git repository of the kernel tree. + If you just need to make some patches to the kernel, you can access + temporary kernel source files that were extracted and used + during a build. + We will just talk about working with the temporary source code. + For more information on how to get kernel source code onto your + host system, see the + "<link linkend='local-kernel-files'>Yocto Project Kernel</link>" + bulleted item earlier in the manual. + </para> + + <para> + What happens during the build? + When you build the kernel on your development system, all files needed for the build + are taken from the source repositories pointed to by the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> variable + and gathered in a temporary work area + where they are subsequently used to create the unique kernel. + Thus, in a sense, the process constructs a local source tree specific to your + kernel to generate the new kernel image - a source generator if you will. + </para> + The following figure shows the temporary file structure + created on your host system when the build occurs. + This + <link linkend='build-directory'>Build Directory</link> contains all the + source files used during the build. + </para> + + <para> + <imagedata fileref="figures/kernel-overview-2-generic.png" + width="6in" depth="5in" align="center" scale="100" /> + </para> + + <para> + Again, for additional information on the Yocto Project kernel's + architecture and its branching strategy, see the + <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>. + You can also reference the + "<link linkend='patching-the-kernel'>Patching the Kernel</link>" + section for a detailed example that modifies the kernel. + </para> + </section> + + <section id='kernel-modification-workflow'> + <title>Kernel Modification Workflow</title> + + <para> + This illustration and the following list summarizes the kernel modification general workflow. + </para> + + <para> + <imagedata fileref="figures/kernel-dev-flow.png" + width="6in" depth="5in" align="center" scalefit="1" /> + </para> + + <para> + <orderedlist> + <listitem><para><emphasis>Set up your host development system to support + development using the Yocto Project</emphasis>: See + "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>" and + "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>" sections both + in the Yocto Project Quick Start for requirements.</para></listitem> + <listitem><para><emphasis>Establish a local copy of project files on your + system</emphasis>: Having the <link linkend='source-directory'>Source + Directory</link> on your system gives you access to the build process and tools + you need. + For information on how to get these files, see the bulleted item + "<link linkend='local-yp-release'>Yocto Project Release</link>" earlier in this manual. + </para></listitem> + <listitem><para><emphasis>Establish the temporary kernel source files</emphasis>: + Temporary kernel source files are kept in the + <link linkend='build-directory'>Build Directory</link> + created by the + OpenEmbedded build system when you run BitBake. + If you have never built the kernel in which you are + interested, you need to run an initial build to + establish local kernel source files.</para> + <para>If you are building an image for the first time, you need to get the build + environment ready by sourcing an environment setup script + (i.e. <filename>oe-init-build-env</filename> or + <filename>oe-init-build-env-memres</filename>). + You also need to be sure two key configuration files + (<filename>local.conf</filename> and <filename>bblayers.conf</filename>) + are configured appropriately.</para> + <para>The entire process for building an image is overviewed in the + "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" + section of the Yocto Project Quick Start. + You might want to reference this information. + You can find more information on BitBake in the + <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. + </para> + <para>The build process supports several types of images to satisfy different needs. + See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in + the Yocto Project Reference Manual for information on supported images. + </para></listitem> + <listitem><para><emphasis>Make changes to the kernel source code if + applicable</emphasis>: Modifying the kernel does not always mean directly + changing source files. + However, if you have to do this, you make the changes to the files in the + Build Directory.</para></listitem> + <listitem><para><emphasis>Make kernel configuration changes if applicable</emphasis>: + If your situation calls for changing the kernel's + configuration, you can use + <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'><filename>menuconfig</filename></ulink>, + which allows you to interactively develop and test the + configuration changes you are making to the kernel. + Saving changes you make with + <filename>menuconfig</filename> updates + the kernel's <filename>.config</filename> file. + <note><title>Warning</title> + Try to resist the temptation to directly edit an + existing <filename>.config</filename> file, which is + found in the Build Directory at + <filename>tmp/sysroots/<replaceable>machine-name</replaceable>/kernel</filename>. + Doing so, can produce unexpected results when the + OpenEmbedded build system regenerates the configuration + file. + </note> + Once you are satisfied with the configuration + changes made using <filename>menuconfig</filename> + and you have saved them, you can directly compare the + resulting <filename>.config</filename> file against an + existing original and gather those changes into a + <link linkend='creating-config-fragments'>configuration fragment file</link> + to be referenced from within the kernel's + <filename>.bbappend</filename> file.</para> + + <para>Additionally, if you are working in a BSP layer + and need to modify the BSP's kernel's configuration, + you can use the + <ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'><filename>yocto-kernel</filename></ulink> + script as well as <filename>menuconfig</filename>. + The <filename>yocto-kernel</filename> script lets + you interactively set up kernel configurations. + </para></listitem> + <listitem><para><emphasis>Rebuild the kernel image with your changes</emphasis>: + Rebuilding the kernel image applies your changes. + </para></listitem> + </orderedlist> + </para> + </section> + </section> +</section> + +<section id='application-development-workflow'> + <title>Application Development Workflow</title> + + <para> + Application development involves creating an application that you want + to run on your target hardware, which is running a kernel image created using the + OpenEmbedded build system. + The Yocto Project provides an + <ulink url='&YOCTO_DOCS_ADT_URL;#adt-intro'>Application Development Toolkit (ADT)</ulink> + and stand-alone + <ulink url='&YOCTO_DOCS_ADT_URL;#the-cross-development-toolchain'>cross-development toolchains</ulink> + that facilitate quick development and integration of your application into its runtime environment. + Using the ADT and toolchains, you can compile and link your application. + You can then deploy your application to the actual hardware or to the QEMU emulator for testing. + If you are familiar with the popular <trademark class='trade'>Eclipse</trademark> IDE, + you can use an Eclipse Yocto Plug-in to + allow you to develop, deploy, and test your application all from within Eclipse. + </para> + + <para> + While we strongly suggest using the ADT to develop your application, this option might not + be best for you. + If this is the case, you can still use pieces of the Yocto Project for your development process. + However, because the process can vary greatly, this manual does not provide detail on the process. + </para> + + <section id='workflow-using-the-adt-and-eclipse'> + <title>Workflow Using the ADT and <trademark class='trade'>Eclipse</trademark></title> + + <para> + To help you understand how application development works using the ADT, this section + provides an overview of the general development process and a detailed example of the process + as it is used from within the Eclipse IDE. + </para> + + <para> + The following illustration and list summarize the application development general workflow. + </para> + + <para> + <imagedata fileref="figures/app-dev-flow.png" + width="7in" depth="8in" align="center" scale="100" /> + </para> + + <para> + <orderedlist> + <listitem><para><emphasis>Prepare the host system for the Yocto Project</emphasis>: + See + "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" + and + "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" sections both + in the Yocto Project Reference Manual for requirements. + In particular, be sure your host system has the + <filename>xterm</filename> package installed. + </para></listitem> + <listitem><para><emphasis>Secure the Yocto Project kernel target image</emphasis>: + You must have a target kernel image that has been built using the OpenEmbedded + build system.</para> + <para>Depending on whether the Yocto Project has a pre-built image that matches your target + architecture and where you are going to run the image while you develop your application + (QEMU or real hardware), the area from which you get the image differs. + <itemizedlist> + <listitem><para>Download the image from + <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink> + if your target architecture is supported and you are going to develop + and test your application on actual hardware.</para></listitem> + <listitem><para>Download the image from + <ulink url='&YOCTO_QEMU_DL_URL;'> + <filename>machines/qemu</filename></ulink> if your target architecture is supported + and you are going to develop and test your application using the QEMU + emulator.</para></listitem> + <listitem><para>Build your image if you cannot find a pre-built image that matches + your target architecture. + If your target architecture is similar to a supported architecture, you can + modify the kernel image before you build it. + See the + "<link linkend='patching-the-kernel'>Patching the Kernel</link>" + section for an example.</para></listitem> + </itemizedlist></para> + <para>For information on pre-built kernel image naming schemes for images + that can run on the QEMU emulator, see the + "<ulink url='&YOCTO_DOCS_QS_URL;#downloading-the-pre-built-linux-kernel'>Downloading the Pre-Built Linux Kernel</ulink>" + section in the Yocto Project Application Developer's Guide.</para></listitem> + <listitem><para><emphasis>Install the ADT</emphasis>: + The ADT provides a target-specific cross-development toolchain, the root filesystem, + the QEMU emulator, and other tools that can help you develop your application. + While it is possible to get these pieces separately, the ADT Installer provides an + easy, inclusive method. + You can get these pieces by running an ADT installer script, which is configurable. + For information on how to install the ADT, see the + "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Using the ADT Installer</ulink>" + section + in the Yocto Project Application Developer's Guide.</para></listitem> + <listitem><para><emphasis>If applicable, secure the target root filesystem + and the Cross-development toolchain</emphasis>: + If you choose not to install the ADT using the ADT Installer, + you need to find and download the appropriate root filesystem and + the cross-development toolchain.</para> + <para>You can find the tarballs for the root filesystem in the same area used + for the kernel image. + Depending on the type of image you are running, the root filesystem you need differs. + For example, if you are developing an application that runs on an image that + supports Sato, you need to get a root filesystem that supports Sato.</para> + <para>You can find the cross-development toolchains at + <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'><filename>toolchains</filename></ulink>. + Be sure to get the correct toolchain for your development host and your + target architecture. + See the "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" + section in the Yocto Project Application Developer's Guide for information + and the + "<ulink url='&YOCTO_DOCS_QS_URL;#installing-the-toolchain'>Installing the Toolchain</ulink>" + in the Yocto Project Application Developer's Guide for information on finding and installing + the correct toolchain based on your host development system and your target + architecture. + </para></listitem> + <listitem><para><emphasis>Create and build your application</emphasis>: + At this point, you need to have source files for your application. + Once you have the files, you can use the Eclipse IDE to import them and build the + project. + If you are not using Eclipse, you need to use the cross-development tools you have + installed to create the image.</para></listitem> + <listitem><para><emphasis>Deploy the image with the application</emphasis>: + If you are using the Eclipse IDE, you can deploy your image to the hardware or to + QEMU through the project's preferences. + If you are not using the Eclipse IDE, then you need to deploy the application + to the hardware using other methods. + Or, if you are using QEMU, you need to use that tool and + load your image in for testing. + See the + "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>" + chapter for information on using QEMU. + </para></listitem> + <listitem><para><emphasis>Test and debug the application</emphasis>: + Once your application is deployed, you need to test it. + Within the Eclipse IDE, you can use the debugging environment along with the + set of user-space tools installed along with the ADT to debug your application. + Of course, the same user-space tools are available separately if you choose + not to use the Eclipse IDE.</para></listitem> + </orderedlist> + </para> + </section> + + <section id='adt-eclipse'> + <title>Working Within Eclipse</title> + + <para> + The Eclipse IDE is a popular development environment and it fully + supports development using the Yocto Project. + <note> + This release of the Yocto Project supports both the Luna + and Kepler versions of the Eclipse IDE. + Thus, the following information provides setup information for + both versions. + </note> + </para> + + <para> + 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 as well as + actual target hardware. + You can also perform cross-debugging and profiling. + The environment also supports a suite of tools that allows you + to perform remote profiling, tracing, collection of power data, + collection of latency data, and collection of performance data. + </para> + + <para> + This section describes how to install and configure the Eclipse IDE + Yocto Plug-in and how to use it to develop your application. + </para> + + <section id='setting-up-the-eclipse-ide'> + <title>Setting Up the Eclipse IDE</title> + + <para> + To develop within the Eclipse IDE, you need to do the following: + <orderedlist> + <listitem><para>Install the optimal version of the Eclipse + IDE.</para></listitem> + <listitem><para>Configure the Eclipse IDE. + </para></listitem> + <listitem><para>Install the Eclipse Yocto Plug-in. + </para></listitem> + <listitem><para>Configure the Eclipse Yocto Plug-in. + </para></listitem> + </orderedlist> + <note> + Do not install Eclipse from your distribution's package + repository. + Be sure to install Eclipse from the official Eclipse + download site as directed in the next section. + </note> + </para> + + <section id='installing-eclipse-ide'> + <title>Installing the Eclipse IDE</title> + + <para> + It is recommended that you have the Luna SR2 (4.4.2) + version of the Eclipse IDE installed on your development + system. + However, if you currently have the Kepler 4.3.2 version + installed and you do not want to upgrade the IDE, you can + configure Kepler to work with the Yocto Project. + </para> + + <para> + If you do not have the Luna SR2 (4.4.2) Eclipse IDE + installed, you can find the tarball at + <ulink url='&ECLIPSE_MAIN_URL;'></ulink>. + From that site, choose the appropriate download from the + "Eclipse IDE for C/C++ Developers". + This version contains the Eclipse Platform, the Java + Development Tools (JDT), and the Plug-in Development + Environment. + </para> + + <para> + Once you have downloaded the tarball, extract it into a + clean directory. + For example, the following commands unpack and install the + downloaded Eclipse IDE tarball into a clean directory + using the default name <filename>eclipse</filename>: + <literallayout class='monospaced'> + $ cd ~ + $ tar -xzvf ~/Downloads/eclipse-cpp-luna-SR2-linux-gtk-x86_64.tar.gz + </literallayout> + </para> + </section> + + <section id='configuring-the-eclipse-ide'> + <title>Configuring the Eclipse IDE</title> + + <para> + This section presents the steps needed to configure the + Eclipse IDE. + </para> + + <para> + Before installing and configuring the Eclipse Yocto Plug-in, + you need to configure the Eclipse IDE. + Follow these general steps: + <orderedlist> + <listitem><para>Start the Eclipse IDE.</para></listitem> + <listitem><para>Make sure you are in your Workbench and + select "Install New Software" from the "Help" + pull-down menu.</para></listitem> + <listitem><para>Select + <filename>Luna - &ECLIPSE_LUNA_URL;</filename> + from the "Work with:" pull-down menu. + <note> + For Kepler, select + <filename>Kepler - &ECLIPSE_KEPLER_URL;</filename> + </note> + </para></listitem> + <listitem><para>Expand the box next to "Linux Tools" + and select the + <filename>Linux Tools LTTng Tracer Control</filename>, + <filename>Linux Tools LTTng Userspace Analysis</filename>, + and + <filename>LTTng Kernel Analysis</filename> boxes. + If these selections do not appear in the list, + that means the items are already installed. + <note> + For Kepler, select + <filename>LTTng - Linux Tracing Toolkit</filename> + box. + </note> + </para></listitem> + <listitem><para>Expand the box next to "Mobile and + Device Development" and select the following boxes. + Again, if any of the following items are not + available for selection, that means the items are + already installed: + <itemizedlist> + <listitem><para><filename>C/C++ Remote Launch (Requires RSE Remote System Explorer)</filename></para></listitem> + <listitem><para><filename>Remote System Explorer End-user Runtime</filename></para></listitem> + <listitem><para><filename>Remote System Explorer User Actions</filename></para></listitem> + <listitem><para><filename>Target Management Terminal (Core SDK)</filename></para></listitem> + <listitem><para><filename>TCF Remote System Explorer add-in</filename></para></listitem> + <listitem><para><filename>TCF Target Explorer</filename></para></listitem> + </itemizedlist></para></listitem> + <listitem><para>Expand the box next to "Programming + Languages" and select the + <filename>C/C++ Autotools Support</filename> + and <filename>C/C++ Development Tools</filename> + boxes. + For Luna, these items do not appear on the list + as they are already installed. + </para></listitem> + <listitem><para>Complete the installation and restart + the Eclipse IDE.</para></listitem> + </orderedlist> + </para> + </section> + + <section id='installing-the-eclipse-yocto-plug-in'> + <title>Installing or Accessing the Eclipse Yocto Plug-in</title> + + <para> + You can install the Eclipse Yocto Plug-in into the Eclipse + IDE one of two ways: use the Yocto Project's Eclipse + Update site to install the pre-built plug-in or build and + install the plug-in from the latest source code. + </para> + + <section id='new-software'> + <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title> + + <para> + To install the Eclipse Yocto Plug-in from the update + site, follow these steps: + <orderedlist> + <listitem><para>Start up the Eclipse IDE. + </para></listitem> + <listitem><para>In Eclipse, select "Install New + Software" from the "Help" menu. + </para></listitem> + <listitem><para>Click "Add..." in the "Work with:" + area.</para></listitem> + <listitem><para>Enter + <filename>&ECLIPSE_DL_PLUGIN_URL;/luna</filename> + in the URL field and provide a meaningful name + in the "Name" field. + <note> + If you are using Kepler, use + <filename>&ECLIPSE_DL_PLUGIN_URL;/kepler</filename> + in the URL field. + </note></para></listitem> + <listitem><para>Click "OK" to have the entry added + to the "Work with:" drop-down list. + </para></listitem> + <listitem><para>Select the entry for the plug-in + from the "Work with:" drop-down list. + </para></listitem> + <listitem><para>Check the boxes next to + <filename>Yocto Project ADT Plug-in</filename>, + <filename>Yocto Project Bitbake Commander Plug-in</filename>, + and + <filename>Yocto Project Documentation plug-in</filename>. + </para></listitem> + <listitem><para>Complete the remaining software + installation steps and then restart the Eclipse + IDE to finish the installation of the plug-in. + <note> + You can click "OK" when prompted about + installing software that contains unsigned + content. + </note> + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='zip-file-method'> + <title>Installing the Plug-in Using the Latest Source Code</title> + + <para> + To install the Eclipse Yocto Plug-in from the latest + source code, follow these steps: + <orderedlist> + <listitem><para>Be sure your development system + is not using OpenJDK to build the plug-in + by doing the following: + <orderedlist> + <listitem><para>Use the Oracle JDK. + If you don't have that, go to + <ulink url='http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html'></ulink> + and download the latest appropriate + Java SE Development Kit tarball for + your development system and + extract it into your home directory. + </para></listitem> + <listitem><para>In the shell you are going + to do your work, export the location of + the Oracle Java. + The previous step creates a new folder + for the extracted software. + You need to use the following + <filename>export</filename> command + and provide the specific location: + <literallayout class='monospaced'> + export PATH=~/<replaceable>extracted_jdk_location</replaceable>/bin:$PATH + </literallayout> + </para></listitem> + </orderedlist> + </para></listitem> + <listitem><para>In the same shell, create a Git + repository with: + <literallayout class='monospaced'> + $ cd ~ + $ git clone git://git.yoctoproject.org/eclipse-poky + </literallayout> + </para></listitem> + <listitem><para>Be sure to checkout the correct + tag. + For example, if you are using Luna, do the + following: + <literallayout class='monospaced'> + $ git checkout luna/yocto-1.8 + </literallayout> + This puts you in a detached HEAD state, which + is fine since you are only going to be building + and not developing. + <note> + If you are building kepler, checkout the + <filename>kepler/yocto-1.8</filename> + branch. + </note> + </para></listitem> + <listitem><para>Change to the + <filename>scripts</filename> + directory within the Git repository: + <literallayout class='monospaced'> + $ cd scripts + </literallayout> + </para></listitem> + <listitem><para>Set up the local build environment + by running the setup script: + <literallayout class='monospaced'> + $ ./setup.sh + </literallayout> + </para></listitem> + <listitem><para>When the script finishes execution, + it prompts you with instructions on how to run + the <filename>build.sh</filename> script, which + is also in the <filename>scripts</filename> + directory of the Git repository created + earlier. + </para></listitem> + <listitem><para>Run the <filename>build.sh</filename> + script as directed. + Be sure to provide the tag name, documentation + branch, and a release name. + Here is an example that uses the + <filename>luna/yocto-1.8</filename> tag, the + <filename>master</filename> documentation + branch, and + <filename>&DISTRO_NAME;</filename> for the + release name: + <literallayout class='monospaced'> + $ ECLIPSE_HOME=/home/scottrif/eclipse-poky/scripts/eclipse ./build.sh luna/yocto-1.8 master &DISTRO_NAME; 2>&1 | tee -a build.log + </literallayout> + After running the script, the file + <filename>org.yocto.sdk-</filename><replaceable>release</replaceable><filename>-</filename><replaceable>date</replaceable><filename>-archive.zip</filename> + is in the current directory. + </para></listitem> + <listitem><para>If necessary, start the Eclipse IDE + and be sure you are in the Workbench. + </para></listitem> + <listitem><para>Select "Install New Software" from + the "Help" pull-down menu. + </para></listitem> + <listitem><para>Click "Add".</para></listitem> + <listitem><para>Provide anything you want in the + "Name" field. + </para></listitem> + <listitem><para>Click "Archive" and browse to the + ZIP file you built in step eight. + This ZIP file should not be "unzipped", and must + be the <filename>*archive.zip</filename> file + created by running the + <filename>build.sh</filename> script. + </para></listitem> + <listitem><para>Click the "OK" button. + </para></listitem> + <listitem><para>Check the boxes that appear in + the installation window to install the + <filename>Yocto Project ADT Plug-in</filename>, + <filename>Yocto Project Bitbake Commander Plug-in</filename>, + and the + <filename>Yocto Project Documentation plug-in</filename>. + </para></listitem> + <listitem><para>Finish the installation by clicking + through the appropriate buttons. + You can click "OK" when prompted about + installing software that contains unsigned + content. + </para></listitem> + <listitem><para>Restart the Eclipse IDE if + necessary. + </para></listitem> + </orderedlist> + </para> + + <para> + At this point you should be able to configure the + Eclipse Yocto Plug-in as described in the + "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>" + section.</para> + </section> + </section> + + <section id='configuring-the-eclipse-yocto-plug-in'> + <title>Configuring the Eclipse Yocto Plug-in</title> + + <para> + Configuring the Eclipse Yocto Plug-in involves setting the + Cross Compiler options and the Target options. + The configurations you choose become the default settings + for all projects. + You do have opportunities to change them later when + you configure the project (see the following section). + </para> + + <para> + To start, you need to do the following from within the + Eclipse IDE: + <itemizedlist> + <listitem><para>Choose "Preferences" from the + "Window" menu to display the Preferences Dialog. + </para></listitem> + <listitem><para>Click "Yocto Project ADT" to display + the configuration screen. + </para></listitem> + </itemizedlist> + </para> + + <section id='configuring-the-cross-compiler-options'> + <title>Configuring the Cross-Compiler Options</title> + + <para> + To configure the Cross Compiler Options, you must select + the type of toolchain, point to the toolchain, specify + the sysroot location, and select the target + architecture. + <itemizedlist> + <listitem><para><emphasis>Selecting the Toolchain Type:</emphasis> + Choose between + <filename>Standalone pre-built toolchain</filename> + and + <filename>Build system derived toolchain</filename> + for Cross Compiler Options. + <itemizedlist> + <listitem><para><emphasis> + <filename>Standalone Pre-built Toolchain:</filename></emphasis> + Select this mode when you are using + a stand-alone cross-toolchain. + For example, suppose you are an + application developer and do not + need to build a target image. + Instead, you just want to use an + architecture-specific toolchain on + an existing kernel and target root + filesystem.</para></listitem> + <listitem><para><emphasis> + <filename>Build System Derived Toolchain:</filename></emphasis> + Select this mode if the + cross-toolchain has been installed + and built as part of the + <link linkend='build-directory'>Build Directory</link>. + When you select + <filename>Build system derived toolchain</filename>, + you are using the toolchain bundled + inside the Build Directory. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para><emphasis>Point to the Toolchain:</emphasis> + If you are using a stand-alone pre-built + toolchain, you should be pointing to where it is + installed. + If you used the ADT Installer script and + accepted the default installation directory, the + toolchain will be installed in the + <filename>&YOCTO_ADTPATH_DIR;</filename> + directory. + Sections "<ulink url='&YOCTO_DOCS_ADT_URL;#configuring-and-running-the-adt-installer-script'>Configuring and Running the ADT Installer Script</ulink>" + and + "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" + in the Yocto Project Application Developer's + Guide describe how to install a stand-alone + cross-toolchain.</para> + <para>If you are using a system-derived + toolchain, the path you provide for the + <filename>Toolchain Root Location</filename> + field is the + <link linkend='build-directory'>Build Directory</link>. + See the + "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-toolchain-from-within-the-build-tree'>Using BitBake and the Build Directory</ulink>" + section in the Yocto Project Application + Developer's Guide for information on how to + install the toolchain into the Build + Directory.</para></listitem> + <listitem><para><emphasis>Specify the Sysroot Location:</emphasis> + This location is where the root filesystem for + the target hardware resides. + If you used the ADT Installer script and + accepted the default installation directory, + then the location in your home directory + in a folder named + <filename>test-yocto/</filename><replaceable>target_arch</replaceable>. + Additionally, when you use the ADT Installer + script, the + <filename>/opt/poky/&DISTRO;/sysroots</filename> + location is used for the QEMU + user-space tools and the NFS boot process. + </para> + <para>If you used either of the other two + methods to install the toolchain or did not + accept the ADT Installer script's default + installation directory, then the location of + the sysroot filesystem depends on where you + separately extracted and installed the + filesystem.</para> + <para>For information on how to install the + toolchain and on how to extract and install the + sysroot filesystem, see the + "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>" + section in the Yocto Project Application + Developer's Guide. + </para></listitem> + <listitem><para><emphasis>Select the Target Architecture:</emphasis> + The target architecture is the type of hardware + you are going to use or emulate. + Use the pull-down + <filename>Target Architecture</filename> menu + to make your selection. + The pull-down menu should have the supported + architectures. + If the architecture you need is not listed in + the menu, you will need to build the image. + See the + "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" + section of the Yocto Project Quick Start for + more information.</para></listitem> + </itemizedlist> + </para> + </section> + + <section id='configuring-the-target-options'> + <title>Configuring the Target Options</title> + + <para> + You can choose to emulate hardware using the QEMU + emulator, or you can choose to run your image on actual + hardware. + <itemizedlist> + <listitem><para><emphasis>QEMU:</emphasis> + Select this option if you will be using the + QEMU emulator. + If you are using the emulator, you also need to + locate the kernel and specify any custom + options.</para> + <para>If you selected + <filename>Build system derived toolchain</filename>, + the target kernel you built will be located in + the Build Directory in + <filename>tmp/deploy/images/<replaceable>machine</replaceable></filename> + directory. + If you selected + <filename>Standalone pre-built toolchain</filename>, + the pre-built image you downloaded is located + in the directory you specified when you + downloaded the image.</para> + <para>Most custom options are for advanced QEMU + users to further customize their QEMU instance. + These options are specified between paired + angled brackets. + Some options must be specified outside the + brackets. + In particular, the options + <filename>serial</filename>, + <filename>nographic</filename>, and + <filename>kvm</filename> must all be outside the + brackets. + Use the <filename>man qemu</filename> command + to get help on all the options and their use. + The following is an example: + <literallayout class='monospaced'> + serial ‘<-m 256 -full-screen>’ + </literallayout></para> + <para> + Regardless of the mode, Sysroot is already + defined as part of the Cross-Compiler Options + configuration in the + <filename>Sysroot Location:</filename> field. + </para></listitem> + <listitem><para><emphasis>External HW:</emphasis> + Select this option if you will be using actual + hardware.</para></listitem> + </itemizedlist> + </para> + + <para> + Click the "OK" to save your plug-in configurations. + </para> + </section> + </section> + </section> + + <section id='creating-the-project'> + <title>Creating the Project</title> + + <para> + You can create two types of projects: Autotools-based, or + Makefile-based. + This section describes how to create Autotools-based projects + from within the Eclipse IDE. + For information on creating Makefile-based projects in a + terminal window, see the section + "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-command-line'>Using the Command Line</ulink>" + in the Yocto Project Application Developer's Guide. + <note> + Do not use special characters in project names + (e.g. spaces, underscores, etc.). Doing so can + cause configuration to fail. + </note> + </para> + + <para> + To create a project based on a Yocto template and then display + the source code, follow these steps: + <orderedlist> + <listitem><para>Select "Project" from the "File -> New" menu. + </para></listitem> + <listitem><para>Double click <filename>CC++</filename>. + </para></listitem> + <listitem><para>Double click <filename>C Project</filename> + to create the project.</para></listitem> + <listitem><para>Expand <filename>Yocto Project ADT Autotools Project</filename>. + </para></listitem> + <listitem><para>Select <filename>Hello World ANSI C Autotools Project</filename>. + This is an Autotools-based project based on a Yocto + template.</para></listitem> + <listitem><para>Put a name in the <filename>Project name:</filename> + field. + Do not use hyphens as part of the name. + </para></listitem> + <listitem><para>Click "Next".</para></listitem> + <listitem><para>Add information in the + <filename>Author</filename> and + <filename>Copyright notice</filename> fields. + </para></listitem> + <listitem><para>Be sure the <filename>License</filename> + field is correct.</para></listitem> + <listitem><para>Click "Finish".</para></listitem> + <listitem><para>If the "open perspective" prompt appears, + click "Yes" so that you in the C/C++ perspective. + </para></listitem> + <listitem><para>The left-hand navigation pane shows your + project. + You can display your source by double clicking the + project's source file.</para></listitem> + </orderedlist> + </para> + </section> + + <section id='configuring-the-cross-toolchains'> + <title>Configuring the Cross-Toolchains</title> + + <para> + The earlier section, + "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>", + sets up the default project configurations. + You can override these settings for a given project by following + these steps: + <orderedlist> + <listitem><para>Select "Change Yocto Project Settings" from + the "Project" menu. + This selection brings up the Yocto Project Settings + Dialog and allows you to make changes specific to an + individual project.</para> + <para>By default, the Cross Compiler Options and Target + Options for a project are inherited from settings you + provided using the Preferences Dialog as described + earlier in the + "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>" section. + The Yocto Project Settings Dialog allows you to override + those default settings for a given project. + </para></listitem> + <listitem><para>Make your configurations for the project + and click "OK". + </para></listitem> + <listitem><para>Right-click in the navigation pane and + select "Reconfigure Project" from the pop-up menu. + This selection reconfigures the project by running + <filename>autogen.sh</filename> in the workspace for + your project. + The script also runs <filename>libtoolize</filename>, + <filename>aclocal</filename>, + <filename>autoconf</filename>, + <filename>autoheader</filename>, + <filename>automake --a</filename>, and + <filename>./configure</filename>. + Click on the "Console" tab beneath your source code to + see the results of reconfiguring your project. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='building-the-project'> + <title>Building the Project</title> + + <para> + To build the project select "Build Project" from the + "Project" menu. + The console should update and you can note the cross-compiler + you are using. + </para> + </section> + + <section id='starting-qemu-in-user-space-nfs-mode'> + <title>Starting QEMU in User-Space NFS Mode</title> + + <para> + To start the QEMU emulator from within Eclipse, follow these + steps: + <note> + See the + "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>" + chapter for more information on using QEMU. + </note> + <orderedlist> + <listitem><para>Expose and select "External Tools" from + the "Run" menu. + Your image should appear as a selectable menu item. + </para></listitem> + <listitem><para>Select your image from the menu to launch + the emulator in a new window. + </para></listitem> + <listitem><para>If needed, enter your host root password in + the shell window at the prompt. + This sets up a <filename>Tap 0</filename> connection + needed for running in user-space NFS mode. + </para></listitem> + <listitem><para>Wait for QEMU to launch.</para></listitem> + <listitem><para>Once QEMU launches, you can begin operating + within that environment. + One useful task at this point would be to determine the + IP Address for the user-space NFS by using the + <filename>ifconfig</filename> command. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='deploying-and-debugging-the-application'> + <title>Deploying and Debugging the Application</title> + + <para> + Once the QEMU emulator is running the image, you can deploy + your application using the Eclipse IDE and then use + the emulator to perform debugging. + Follow these steps to deploy the application. + <orderedlist> + <listitem><para>Select "Debug Configurations..." from the + "Run" menu.</para></listitem> + <listitem><para>In the left area, expand + <filename>C/C++Remote Application</filename>. + </para></listitem> + <listitem><para>Locate your project and select it to bring + up a new tabbed view in the Debug Configurations Dialog. + </para></listitem> + <listitem><para>Enter the absolute path into which you want + to deploy the application. + Use the "Remote Absolute File Path for + C/C++Application:" field. + For example, enter + <filename>/usr/bin/<replaceable>programname</replaceable></filename>. + </para></listitem> + <listitem><para>Click on the "Debugger" tab to see the + cross-tool debugger you are using.</para></listitem> + <listitem><para>Click on the "Main" tab.</para></listitem> + <listitem><para>Create a new connection to the QEMU instance + by clicking on "new".</para></listitem> + <listitem><para>Select <filename>TCF</filename>, which means + Target Communication Framework.</para></listitem> + <listitem><para>Click "Next".</para></listitem> + <listitem><para>Clear out the "host name" field and enter + the IP Address determined earlier.</para></listitem> + <listitem><para>Click "Finish" to close the + New Connections Dialog.</para></listitem> + <listitem><para>Use the drop-down menu now in the + "Connection" field and pick the IP Address you entered. + </para></listitem> + <listitem><para>Click "Debug" to bring up a login screen + and login.</para></listitem> + <listitem><para>Accept the debug perspective. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='running-user-space-tools'> + <title>Running User-Space Tools</title> + + <para> + As mentioned earlier in the manual, several tools exist that + enhance your development experience. + These tools are aids in developing and debugging applications + and images. + You can run these user-space tools from within the Eclipse + IDE through the "YoctoProjectTools" menu. + </para> + + <para> + Once you pick a tool, you need to configure it for the remote + target. + Every tool needs to have the connection configured. + You must select an existing TCF-based RSE connection to the + remote target. + If one does not exist, click "New" to create one. + </para> + + <para> + Here are some specifics about the remote tools: + <itemizedlist> + <listitem><para><emphasis><filename>OProfile</filename>:</emphasis> + Selecting this tool causes the + <filename>oprofile-server</filename> on the remote + target to launch on the local host machine. + The <filename>oprofile-viewer</filename> must be + installed on the local host machine and the + <filename>oprofile-server</filename> must be installed + on the remote target, respectively, in order to use. + You must compile and install the + <filename>oprofile-viewer</filename> from the source + code on your local host machine. + Furthermore, in order to convert the target's sample + format data into a form that the host can use, you must + have OProfile version 0.9.4 or greater installed on the + host.</para> + <para>You can locate both the viewer and server from + <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/oprofileui/'></ulink>. + You can also find more information on setting up and + using this tool in the + "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-oprofile'>oprofile</ulink>" + section of the Yocto Project Profiling and Tracing + Manual. + <note>The <filename>oprofile-server</filename> is + installed by default on the + <filename>core-image-sato-sdk</filename> image.</note> + </para></listitem> + <listitem><para><emphasis><filename>Lttng2.0 trace import</filename>:</emphasis> + Selecting this tool transfers the remote target's + <filename>Lttng</filename> tracing data back to the + local host machine and uses the Lttng Eclipse plug-in + to graphically display the output. + For information on how to use Lttng to trace an + application, + see <ulink url='http://lttng.org/documentation'></ulink> + and the + "<ulink url='&YOCTO_DOCS_PROF_URL;#lttng-linux-trace-toolkit-next-generation'>LTTng (Linux Trace Toolkit, next generation)</ulink>" + section, which is in the Yocto Project Profiling and + Tracing Manual. + <note>Do not use + <filename>Lttng-user space (legacy)</filename> tool. + This tool no longer has any upstream support.</note> + </para> + <para>Before you use the + <filename>Lttng2.0 trace import</filename> tool, + you need to setup the Lttng Eclipse plug-in and create a + Tracing project. + Do the following: + <orderedlist> + <listitem><para>Select "Open Perspective" from the + "Window" menu and then select "Other..." to + bring up a menu of other perspectives. + Choose "Tracing". + </para></listitem> + <listitem><para>Click "OK" to change the Eclipse + perspective into the Tracing perspective. + </para></listitem> + <listitem><para>Create a new Tracing project by + selecting "Project" from the "File -> New" menu. + </para></listitem> + <listitem><para>Choose "Tracing Project" from the + "Tracing" menu and click "Next". + </para></listitem> + <listitem><para>Provide a name for your tracing + project and click "Finish". + </para></listitem> + <listitem><para>Generate your tracing data on the + remote target.</para></listitem> + <listitem><para>Select "Lttng2.0 trace import" + from the "Yocto Project Tools" menu to + start the data import process.</para></listitem> + <listitem><para>Specify your remote connection name. + </para></listitem> + <listitem><para>For the Ust directory path, specify + the location of your remote tracing data. + Make sure the location ends with + <filename>ust</filename> (e.g. + <filename>/usr/mysession/ust</filename>). + </para></listitem> + <listitem><para>Click "OK" to complete the import + process. + The data is now in the local tracing project + you created.</para></listitem> + <listitem><para>Right click on the data and then use + the menu to Select "Generic CTF Trace" from the + "Trace Type... -> Common Trace Format" menu to + map the tracing type.</para></listitem> + <listitem><para>Right click the mouse and select + "Open" to bring up the Eclipse Lttng Trace + Viewer so you view the tracing data. + </para></listitem> + </orderedlist></para></listitem> + <listitem><para><emphasis><filename>PowerTOP</filename>:</emphasis> + Selecting this tool runs PowerTOP on the remote target + machine and displays the results in a new view called + PowerTOP.</para> + <para>The "Time to gather data(sec):" field is the time + passed in seconds before data is gathered from the + remote target for analysis.</para> + <para>The "show pids in wakeups list:" field corresponds + to the <filename>-p</filename> argument passed to + <filename>PowerTOP</filename>.</para></listitem> + <listitem><para><emphasis><filename>LatencyTOP and Perf</filename>:</emphasis> + LatencyTOP identifies system latency, while + Perf monitors the system's performance counter + registers. + Selecting either of these tools causes an RSE terminal + view to appear from which you can run the tools. + Both tools refresh the entire screen to display results + while they run. + For more information on setting up and using + <filename>perf</filename>, see the + "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-perf'>perf</ulink>" + section in the Yocto Project Profiling and Tracing + Manual. + </para></listitem> + <listitem><para><emphasis><filename>SystemTap</filename>:</emphasis> + Systemtap is a tool that lets you create and reuse + scripts to examine the activities of a live Linux + system. + You can easily extract, filter, and summarize data + that helps you diagnose complex performance or + functional problems. + For more information on setting up and using + <filename>SystemTap</filename>, see the + <ulink url='https://sourceware.org/systemtap/documentation.html'>SystemTap Documentation</ulink>. + </para></listitem> + <listitem><para><emphasis><filename>yocto-bsp</filename>:</emphasis> + The <filename>yocto-bsp</filename> tool lets you + quickly set up a Board Support Package (BSP) layer. + The tool requires a Metadata location, build location, + BSP name, BSP output location, and a kernel + architecture. + For more information on the + <filename>yocto-bsp</filename> tool outside of Eclipse, + see the + "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a new BSP Layer Using the yocto-bsp Script</ulink>" + section in the Yocto Project Board Support Package + (BSP) Developer's Guide. + </para></listitem> + </itemizedlist> + </para> + </section> + </section> + + <section id='workflow-using-stand-alone-cross-development-toolchains'> + <title>Workflow Using Stand-Alone Cross-Development Toolchains</title> + + <para> + If you want to develop an application without prior installation + of the ADT, you still can employ the + <link linkend='cross-development-toolchain'>Cross Development Toolchain</link>, + the QEMU emulator, and a number of supported target image files. + You just need to follow these general steps: + <orderedlist> + <listitem><para><emphasis>Install the cross-development + toolchain for your target hardware:</emphasis> + For information on how to install the toolchain, see the + "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" + section in the Yocto Project Application Developer's + Guide.</para></listitem> + <listitem><para><emphasis>Download 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>In order to use the root filesystem in QEMU, you + need to extract it. + See the + "<ulink url='&YOCTO_DOCS_ADT_URL;#extracting-the-root-filesystem'>Extracting the Root Filesystem</ulink>" + 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. + You can see the + "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>" + chapter for information on using QEMU within the Yocto + Project.</para></listitem> + </orderedlist> + </para> + </section> +</section> + +<section id="dev-modifying-source-code"> + <title>Modifying Source Code</title> + + <para> + A common development workflow consists of modifying project source + files that are external to the Yocto Project and then integrating + that project's build output into an image built using the + OpenEmbedded build system. + Given this scenario, development engineers typically want to stick + to their familiar project development tools and methods, which allows + them to just focus on the project. + </para> + + <para> + Several workflows exist that allow you to develop, build, and test + code that is going to be integrated into an image built using the + OpenEmbedded build system. + This section describes two: + <itemizedlist> + <listitem><para><emphasis><filename>devtool</filename>:</emphasis> + A set of tools to aid in working on the source code built by + the OpenEmbedded build system. + Section + "<link linkend='using-devtool-in-your-workflow'>Using <filename>devtool</filename> in Your Workflow</link>" + describes this workflow. + If you want more information that showcases the workflow, click + <ulink url='https://drive.google.com/a/linaro.org/file/d/0B3KGzY5fW7laTDVxUXo3UDRvd2s/view'>here</ulink> + for an excellent presentation by Trevor Woerner that + provides detailed background information and a complete + working tutorial. + </para></listitem> + <listitem><para><emphasis><ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink>:</emphasis> + A powerful tool that allows you to capture source + code changes without having a clean source tree. + While Quilt is not the preferred workflow of the two, this + section includes it for users that are committed to using + the tool. + See the + "<link linkend='using-a-quilt-workflow'>Using Quilt in Your Workflow</link>" + section for more information. + </para></listitem> + </itemizedlist> + </para> + + <section id='using-devtool-in-your-workflow'> + <title>Using <filename>devtool</filename> in Your Workflow</title> + + <para> + As mentioned earlier, <filename>devtool</filename> helps + you easily develop projects whose build output must be part of + an image built using the OpenEmbedded build system. + The remainder of this section presents the workflow you would + use that includes <filename>devtool</filename>. + <footnote> + <para> + Kudos and thanks to + <ulink url='mailto:twoerner@gmail.com'>Trevor Woerner</ulink> + whose + "<ulink url='https://drive.google.com/file/d/0B3KGzY5fW7laTDVxUXo3UDRvd2s/view'>Yocto Project Developer Workflow Tutorial</ulink>" + paper contributed nicely towards the development of this + section. + </para> + </footnote> + </para> + + <para> + The steps in this section assume you have a previously built + image that is already either running in QEMU or running on actual + hardware. + Also, it is assumed that for deployment of the image to the + target, SSH is installed in the image and if the image is running + on real hardware that you have network access to and from your + development machine. + </para> + + <section id='update-your-external-source'> + <title>Update Your External Source</title> + + <para> + Part of the development flow using + <filename>devtool</filename> of course involves updating + your source files. + Several opportunities exist in the workflow to extract and + work on the files. + For now, just realize that you need to be able to have + access to and edit files. + One obvious solution is to initially extract the code into an + isolated area in preparation for modification. + </para> + + <para> + Another option is to use the + <filename>devtool modify</filename> command. + This command makes use of a "workspace" layer where much of + the transitional work occurs, which is needed for setting up + Metadata used by the OpenEmbedded build system that lets you + build your software. + Options (i.e. "-x") exist using <filename>devtool</filename> + that enable you to use the tool to extract source code. + </para> + </section> + + <section id='use-devtool-to-integrate-your-code-with-the-image'> + <title>Use <filename>devtool add</filename> to Integrate Your Code with the Image</title> + + <para> + The <filename>devtool add</filename> command automatically + generates the needed Metadata that allows the OpenEmbedded + build system to build your code into the image. + <note> + If a package or packages produced by the recipe on which + you are working are not already in + <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink> + for the image, you must add them. + The <filename>devtool add</filename> command does not + add them for you. + </note> + Use the following command form: + <literallayout class='monospaced'> + $ devtool add <replaceable>your-project-name</replaceable> <replaceable>path-to-source</replaceable> + </literallayout> + </para> + + <para> + Running <filename>devtool</filename> for the first time + creates a workspace layer through the + <filename>bblayers.conf</filename> file that + is based on your project's location: + <literallayout class='monospaced'> + <replaceable>path-to-source</replaceable>/<replaceable>build-directory</replaceable>/<replaceable>workspace-layer</replaceable> + </literallayout> + By default, the name of the workspace layer is "workspace". + </para> + + <para> + For details on the workspace layer created in the + <replaceable>build-directory</replaceable>, + see the + "<link linkend='devtool-adding-a-new-recipe-to-the-workspace'>Adding a New Recipe to the Workspace Layer</link>" + section. + </para> + +<!-- + <para> + Of course, each layer must have a + <filename>layer.conf</filename> configuration file. + <filename>devtool</filename> also creates this configuration + file: + <literallayout class='monospaced'> + $ cat workspace/conf/layer.conf + # ### workspace layer autogenerated by devtool ### + BBPATH =. "${LAYERDIR}:" + BBFILES += "${LAYERDIR}/recipes/*/*.bb \ + ${LAYERDIR}/appends/*.bbappend" + BBFILE_COLLECTIONS += "workspacelayer" + BBFILE_PATTERN_workspacelayer = "^${LAYERDIR}/" + BBFILE_PATTERN_IGNORE_EMPTY_workspacelayer = "1" + BBFILE_PRIORITY_workspacelayer = "99" + </literallayout> + </para> +--> + + <para> + Running <filename>devtool add</filename> automatically + generates your recipe: + <literallayout class='monospaced'> + $ cat workspace/recipes/<replaceable>your-project-name</replaceable>/<replaceable>your-project-name</replaceable>.bb + # Recipe created by recipetool + # This is the basis of a recipe and may need further editing in order to be fully functional. + # (Feel free to remove these comments when editing.) + # + # Unable to find any files that looked like license statements. Check the accompanying + # documentation and source headers and set LICENSE and LIC_FILES_CHKSUM accordingly. + LICENSE = "CLOSED" + LIC_FILES_CHKSUM = "" + + # No information for SRC_URI yet (only an external source tree was + # specified) + SRC_URI = "" + + DEPENDS = "libx11" + # NOTE: if this software is not capable of being built in a separate build directory + # from the source, you should replace autotools with autotools-brokensep in the + # inherit line + inherit autotools + + # Specify any options you want to pass to the configure script using EXTRA_OECONF: + EXTRA_OECONF = "" + </literallayout> + </para> + + <para> + Lastly, the <filename>devtool add</filename> command creates the + <filename>.bbappend</filename> file: + <literallayout class='monospaced'> + $ cat workspace/appends/<replaceable>your-project-name</replaceable>.bbappend + inherit externalsrc + EXTERNALSRC = "/<replaceable>path-to-source</replaceable>/<replaceable>your-project-name</replaceable>" + + # initial_rev: <replaceable>commit-ID</replaceable> + </literallayout> + </para> + </section> + + <section id='build-your-project'> + <title>Build Your Project</title> + + <para> + You can use BitBake or <filename>devtool build</filename> to + build your modified project. + </para> + + <para> + To use BitBake, use the following: + <literallayout class='monospaced'> + $ bitbake <replaceable>your-project-name</replaceable> + </literallayout> + Alternatively, you can use + <filename>devtool build</filename>, which is equivalent to + <filename>bitbake -c populate_sysroot</filename>. + For example: + <literallayout class='monospaced'> + $ devtool build <replaceable>your-project-name</replaceable> + </literallayout> + </para> + </section> + +<!-- + <section id='dev-build-the-image'> + <title>Build the Image</title> + + <para> + The final step before testing is to rebuild the base image + with your project changes as part of the image. + Simply run BitBake again on your image. + Here is an example: + <literallayout class='monospaced'> + $ bitbake <replaceable>image</replaceable> + </literallayout> + </para> + </section> + + <section id='dev-testing-the-image'> + <title>Testing the Image</title> + + <para> + Once you have the image, you can test it using QEMU. + Here is an example assuming "qemux86": + <literallayout class='monospaced'> + $ runqemu qemux86 <replaceable>image</replaceable> + </literallayout> + For information on how to test an image using QEMU, see the + "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>" + section. + </para> + </section> +--> + </section> + + <section id='devtool-quick-reference'> + <title><filename>devtool</filename> Quick Reference</title> + + <para> + <filename>devtool</filename> has more functionality than simply + adding a new recipe and the supporting Metadata to a temporary + workspace layer. + This section provides a short reference on + <filename>devtool</filename> for most of the commands. + </para> + + <section id='devtool-getting-help'> + <title>Getting Help</title> + + <para> + The easiest way to get help with the + <filename>devtool</filename> command is using the + <filename>--help</filename> option: + <literallayout class='monospaced'> + $ devtool --help + usage: devtool [-h] [--basepath BASEPATH] [-d] [-q] [--color COLOR] + <subcommand> ... + + OpenEmbedded development tool + + optional arguments: + -h, --help show this help message and exit + --basepath BASEPATH Base directory of SDK / build directory + -d, --debug Enable debug output + -q, --quiet Print only errors + --color COLOR Colorize output (where COLOR is auto, always, never) + + subcommands: + <subcommand> + create-workspace Set up a workspace + deploy-target Deploy recipe output files to live target machine + undeploy-target Undeploy recipe output files in live target machine + add Add a new recipe + modify Modify the source for an existing recipe + extract Extract the source for an existing recipe + update-recipe Apply changes from external source tree to recipe + status Show workspace status + build Build a recipe + reset Remove a recipe from your workspace + + Use devtool <subcommand> --help to get help on a specific command + </literallayout> + </para> + + <para> + As directed in the general help output, you can get more + syntax on a specific command by providing the command + name and using <filename>--help</filename>: + <literallayout class='monospaced'> + $ devtool add --help + usage: devtool add [-h] [--same-dir] [--fetch URI] [--version VERSION] + recipename srctree + + Adds a new recipe + + positional arguments: + recipename Name for new recipe to add + srctree Path to external source tree + + optional arguments: + -h, --help show this help message and exit + --same-dir, -s Build in same directory as source + --fetch URI, -f URI Fetch the specified URI and extract it to create the + source tree + --version VERSION, -V VERSION + Version to use within recipe (PV) + </literallayout> + </para> + </section> + + <section id='devtool-adding-a-new-recipe-to-the-workspace'> + <title>Adding a New Recipe to the Workspace Layer</title> + + <para> + Use the <filename>devtool add</filename> command to add a new recipe + to the workspace layer. + The recipe you add should not exist - + <filename>devtool</filename> creates it for you. + The source files the recipe uses should exist in an external + area. + </para> + + <para> + The following example creates and adds a new recipe named + <filename>jackson</filename> to the workspace layer. + The source code built by the recipes resides in + <filename>/home/scottrif/sources/jackson</filename>: + <literallayout class='monospaced'> + $ devtool add jackson /home/scottrif/sources/jackson + </literallayout> + <note> + For complete syntax, use the + <filename>devtool add --help</filename> command. + </note> + </para> + + <para> + If you add a recipe and the workspace layer does not exist, + the command creates the layer and populates it as follows: + </para> + + <para> + <imagedata fileref="figures/build-workspace-directory.png" + width="6in" depth="4in" align="center" scale="100" /> + </para> + + <para> + <literallayout class='monospaced'> + README - Provides information on what is in workspace layer and how to + manage it. + + appends - A directory that contains *.bbappend files, which point to + external source. + + conf - A configuration directory that contains the layer.conf file. + + recipes - A directory containing recipes. This directory contains a + folder for each directory added whose name matches that of the + added recipe. devtool places the <replaceable>recipe</replaceable>.bb file + within that sub-directory. + </literallayout> + </para> + + <para> + Running <filename>devtool add</filename> when the + workspace layer exists causes the tool to add the recipe + and append files into the existing workspace layer. + The <filename>.bbappend</filename> file is created to point + to the external source tree. + </para> + </section> + + <section id='devtool-modifying-a-recipe'> + <title>Modifying an Existing Recipe</title> + + <para> + Use the <filename>devtool modify</filename> command to begin + modifying the source of an existing recipe. + This command is very similar to the + <link linkend='devtool-adding-a-new-recipe-to-the-workspace'><filename>add</filename></link> + command except that it does not physically create the + recipe in the workspace layer because the recipe already + exists in an another layer. + </para> + + <para> + The <filename>devtool modify</filename> command extracts the + source for a recipe, sets it up as a Git repository if the + source had not already been fetched from Git, checks out a + branch for development, and applies any patches from the recipe + as commits on top. + You can use the following command to checkout the source + files: + <literallayout class='monospaced'> + $ devtool modify -x <replaceable>recipe</replaceable> <replaceable>path-to-source</replaceable> + </literallayout> + Using the above command form, the default development branch + would be "devtool". + <note> + For complete syntax, use the + <filename>devtool modify --help</filename> command. + </note> + </para> + </section> + + <section id='devtool-updating-a-recipe'> + <title>Updating a Recipe</title> + + <para> + Use the <filename>devtool update-recipe</filename> command to + update your recipe with patches that reflect changes you make + to the source files. + For example, if you know you are going to work on some + code, you could first use the + <link linkend='devtool-modifying-a-recipe'><filename>devtool modify</filename></link> + command to extract the code and set up the workspace. + After which, you could modify, compile, and test the code. + </para> + + <para> + When you are satisfied with the results and you have committed + your changes to the Git repository, you can then + run the <filename>devtool update-recipe</filename> to create the + patches and update the recipe: + <literallayout class='monospaced'> + $ devtool update-recipe <replaceable>recipe</replaceable> + </literallayout> + If you run the <filename>devtool update-recipe</filename> + without committing your changes, the command ignores the + changes. + </para> + + <para> + Often, you might want to apply customizations made to your + software in your own layer rather than apply them to the + original recipe. + If so, you can use the + <filename>-a</filename> or <filename>--append</filename> + option with the <filename>devtool update-recipe</filename> + command. + These options allow you to specify the layer into which to + write an append file: + <literallayout class='monospaced'> + $ devtool update-recipe <replaceable>recipe</replaceable> -a <replaceable>base-layer-directory</replaceable> + </literallayout> + The <filename>*.bbappend</filename> file is created at the + appropriate path within the specified layer directory, which + may or may not be in your <filename>bblayers.conf</filename> + file. + If an append file already exists, the command updates it + appropriately. + <note> + For complete syntax, use the + <filename>devtool update-recipe --help</filename> command. + </note> + </para> + </section> + + <section id='devtool-resetting-a-recipe'> + <title>Resetting a Recipe</title> + + <para> + Use the <filename>devtool reset</filename> command to remove a + recipe and its configuration (e.g. the corresponding + <filename>.bbappend</filename> file) from the workspace layer. + Realize that this command deletes the recipe and the + append file. + The command does not physically move them for you. + Consequently, you must be sure to physically relocate your + updated recipe and the append file outside of the workspace + layer before running the <filename>devtool reset</filename> + command. + </para> + + <para> + If the <filename>devtool reset</filename> command detects that + the recipe or the append files have been modified, the + command preserves the modified files in a separate "attic" + subdirectory under the workspace layer. + <note> + For complete syntax, use the + <filename>devtool reset --help</filename> command. + </note> + </para> + </section> + + <section id='devtool-building-your-software'> + <title>Building Your Software</title> + + <para> + Use the <filename>devtool build</filename> command to cause the + OpenEmbedded build system to build your software based + on the recipe file. + The <filename>devtool build</filename> command is equivalent to + <filename>bitbake -c populate_sysroot</filename>. + Here is an example: + <literallayout class='monospaced'> + $ devtool build <replaceable>recipe</replaceable> + </literallayout> + <note> + For complete syntax, use the + <filename>devtool update-recipe --help</filename> command. + </note> + Building your software using <filename>devtool build</filename> + is identical to using BitBake to build the software. + </para> + </section> + + <section id='devtool-deploying-your-software-on-the-target-machine'> + <title>Deploying Your Software on the Target Machine</title> + + <para> + Use the <filename>devtool deploy-target</filename> command to + deploy the recipe's build output to the live target machine: + <literallayout class='monospaced'> + $ devtool deploy-target <replaceable>recipe</replaceable> <replaceable>target</replaceable> + </literallayout> + The <replaceable>target</replaceable> is the address of the + target machine, which must be running an SSH server (i.e. + <filename>user@hostname[:destdir]</filename>). + </para> + + <para> + This command deploys all files installed during the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> + task. + Furthermore, you do not need to have package management enabled + within the target machine. + If you do, the package manager is bypassed. + <note><title>Notes</title> + <para> + The <filename>deploy-target</filename> + functionality is for development only. + You should never use it to update an image that will be + used in production. + </para> + + <para> + For complete syntax, use the + <filename>devtool deploy-target --help</filename> + command. + </para> + </note> + </para> + </section> + + <section id='devtool-removing-your-software-from-the-target-machine'> + <title>Removing Your Software from the Target Machine</title> + + <para> + Use the <filename>devtool undeploy-target</filename> command to + remove deployed build output from the target machine. + For the <filename>devtool undeploy-target</filename> command to + work, you must have previously used the + <link linkend='devtool-deploying-your-software-on-the-target-machine'><filename>devtool deploy-target</filename></link> + command. + <literallayout class='monospaced'> + $ devtool undeploy-target <replaceable>recipe</replaceable> <replaceable>target</replaceable> + </literallayout> + The <replaceable>target</replaceable> is the address of the + target machine, which must be running an SSH server (i.e. + <filename>user@hostname</filename>). + <note> + For complete syntax, use the + <filename>devtool undeploy-target --help</filename> command. + </note> + </para> + </section> + + <section id='devtool-creating-the-workspace'> + <title>Creating the Workspace Layer in an Alternative Location</title> + + <para> + Use the <filename>devtool create-workspace</filename> command to + create a new workspace layer in your + <link linkend='build-directory'>Build Directory</link>. + When you create a new workspace layer, it is populated with the + <filename>README</filename> file and the + <filename>conf</filename> directory only. + </para> + + <para> + The following example creates a new workspace layer in your + current working and by default names the workspace layer + "workspace": + <literallayout class='monospaced'> + $ devtool create-workspace + </literallayout> + <note> + For complete syntax, use the + <filename>devtool create-workspace --help</filename> command. + </note> + </para> + + <para> + You can create a workspace layer anywhere by supplying + a pathname with the command. + The following command creates a new workspace layer named + "new-workspace": + <literallayout class='monospaced'> + $ devtool create-workspace /home/scottrif/new-workspace + </literallayout> + </para> + </section> + </section> + + <section id="using-a-quilt-workflow"> + <title>Using Quilt in Your Workflow</title> + + <para> + <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink> + is a powerful tool that allows you to capture source code changes + without having a clean source tree. + This section outlines the typical workflow you can use to modify + source code, test changes, and then preserve the changes in the + form of a patch all using Quilt. + <note><title>Tip</title> + With regard to preserving changes to source files if you + clean a recipe or have <filename>rm_work</filename> enabled, + the workflow described in the + "<link linkend='using-devtool-in-your-workflow'>Using <filename>devtool</filename> in Your Workflow</link>" + section is a safer development flow than than the flow that + uses Quilt. + </note> + </para> + + <para> + Follow these general steps: + <orderedlist> + <listitem><para><emphasis>Find the Source Code:</emphasis> + Temporary source code used by the OpenEmbedded build system + is kept in the + <link linkend='build-directory'>Build Directory</link>. + See the + "<link linkend='finding-the-temporary-source-code'>Finding Temporary Source Code</link>" + section to learn how to locate the directory that has the + temporary source code for a particular package. + </para></listitem> + <listitem><para><emphasis>Change Your Working Directory:</emphasis> + You need to be in the directory that has the temporary source code. + That directory is defined by the + <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> + variable.</para></listitem> + <listitem><para><emphasis>Create a New Patch:</emphasis> + Before modifying source code, you need to create a new patch. + To create a new patch file, use <filename>quilt new</filename> as below: + <literallayout class='monospaced'> + $ quilt new my_changes.patch + </literallayout></para></listitem> + <listitem><para><emphasis>Notify Quilt and Add Files:</emphasis> + After creating the patch, you need to notify Quilt about the files + you plan to edit. + You notify Quilt by adding the files to the patch you just created: + <literallayout class='monospaced'> + $ quilt add file1.c file2.c file3.c + </literallayout> + </para></listitem> + <listitem><para><emphasis>Edit the Files:</emphasis> + Make your changes in the source code to the files you added + to the patch. + </para></listitem> + <listitem><para><emphasis>Test Your Changes:</emphasis> + Once you have modified the source code, the easiest way to + your changes is by calling the + <filename>do_compile</filename> task as shown in the + following example: + <literallayout class='monospaced'> + $ bitbake -c compile -f <replaceable>package</replaceable> + </literallayout> + The <filename>-f</filename> or <filename>--force</filename> + option forces the specified task to execute. + If you find problems with your code, you can just keep editing and + re-testing iteratively until things work as expected. + <note>All the modifications you make to the temporary source code + disappear once you run the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-clean'><filename>do_clean</filename></ulink> + or + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleanall'><filename>do_cleanall</filename></ulink> + tasks using BitBake (i.e. + <filename>bitbake -c clean <replaceable>package</replaceable></filename> + and + <filename>bitbake -c cleanall <replaceable>package</replaceable></filename>). + Modifications will also disappear if you use the <filename>rm_work</filename> + feature as described in the + "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" + section of the Yocto Project Quick Start. + </note></para></listitem> + <listitem><para><emphasis>Generate the Patch:</emphasis> + Once your changes work as expected, you need to use Quilt to generate the final patch that + contains all your modifications. + <literallayout class='monospaced'> + $ quilt refresh + </literallayout> + At this point, the <filename>my_changes.patch</filename> file has all your edits made + to the <filename>file1.c</filename>, <filename>file2.c</filename>, and + <filename>file3.c</filename> files.</para> + <para>You can find the resulting patch file in the <filename>patches/</filename> + subdirectory of the source (<filename>S</filename>) directory.</para></listitem> + <listitem><para><emphasis>Copy the Patch File:</emphasis> + For simplicity, copy the patch file into a directory named <filename>files</filename>, + which you can create in the same directory that holds the recipe + (<filename>.bb</filename>) file or the + append (<filename>.bbappend</filename>) file. + Placing the patch here guarantees that the OpenEmbedded build system will find + the patch. + Next, add the patch into the + <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> + of the recipe. + Here is an example: + <literallayout class='monospaced'> + SRC_URI += "file://my_changes.patch" + </literallayout></para></listitem> + </orderedlist> + </para> + </section> + + <section id='finding-the-temporary-source-code'> + <title>Finding Temporary Source Code</title> + + <para> + You might find it helpful during development to modify the + temporary source code used by recipes to build packages. + For example, suppose you are developing a patch and you need to + experiment a bit to figure out your solution. + After you have initially built the package, you can iteratively + tweak the source code, which is located in the + <link linkend='build-directory'>Build Directory</link>, and then + you can force a re-compile and quickly test your altered code. + Once you settle on a solution, you can then preserve your changes + in the form of patches. + If you are using Quilt for development, see the + "<link linkend='using-a-quilt-workflow'>Using Quilt in Your Workflow</link>" + section for more information. + </para> + + <para> + During a build, the unpacked temporary source code used by recipes + to build packages is available in the Build Directory as + defined by the + <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> variable. + Below is the default value for the <filename>S</filename> variable as defined in the + <filename>meta/conf/bitbake.conf</filename> configuration file in the + <link linkend='source-directory'>Source Directory</link>: + <literallayout class='monospaced'> + S = "${WORKDIR}/${BP}" + </literallayout> + You should be aware that many recipes override the <filename>S</filename> variable. + For example, recipes that fetch their source from Git usually set + <filename>S</filename> to <filename>${WORKDIR}/git</filename>. + <note> + The + <ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink> + represents the base recipe name, which consists of the name and version: + <literallayout class='monospaced'> + BP = "${BPN}-${PV}" + </literallayout> + </note> + </para> + + <para> + The path to the work directory for the recipe + (<ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>) + is defined as follows: + <literallayout class='monospaced'> + ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR} + </literallayout> + The actual directory depends on several things: + <itemizedlist> + <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>: + The top-level build output directory</listitem> + <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></ulink>: + The target system identifier</listitem> + <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>: + The recipe name</listitem> + <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTENDPE'><filename>EXTENDPE</filename></ulink>: + The epoch - (if + <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink> + is not specified, which is usually the case for most + recipes, then <filename>EXTENDPE</filename> is blank)</listitem> + <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>: + The recipe version</listitem> + <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>: + The recipe revision</listitem> + </itemizedlist> + </para> + + <para> + As an example, assume a Source Directory top-level folder + named <filename>poky</filename>, a default Build Directory at + <filename>poky/build</filename>, and a + <filename>qemux86-poky-linux</filename> machine target + system. + Furthermore, suppose your recipe is named + <filename>foo_1.3.0.bb</filename>. + In this case, the work directory the build system uses to + build the package would be as follows: + <literallayout class='monospaced'> + poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 + </literallayout> + </para> + + <para> + Now that you know where to locate the directory that has the + temporary source code, you can use a Quilt as described in section + "<link linkend='using-a-quilt-workflow'>Using Quilt in Your Workflow</link>" + to make your edits, test the changes, and preserve the changes in + the form of patches. + </para> + </section> +</section> + +<section id='image-development-using-toaster'> + <title>Image Development Using Toaster</title> + + <para> + Toaster is a web interface to the Yocto Project's OpenEmbedded build + system. + You can initiate builds using Toaster as well as examine the results + and statistics of builds. + See the + <ulink url='&YOCTO_DOCS_TOAST_URL;#toaster-manual-intro'>Toaster User Manual</ulink> + for information on how to set up and use Toaster to build images. + </para> +</section> + +<section id='image-development-using-hob'> + <title>Image Development Using Hob</title> + + <para> + The <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink> is a graphical user interface for the + OpenEmbedded build system, which is based on BitBake. + You can use the Hob to build custom operating system images within the Yocto Project build environment. + Hob simply provides a friendly interface over the build system used during development. + In other words, building images with the Hob lets you take care of common build tasks more easily. + </para> + + <para> + For a better understanding of Hob, see the project page at + <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'></ulink> + on the Yocto Project website. + If you follow the "Documentation" link from the Hob page, you will + find a short introductory training video on Hob. + The following lists some features of Hob: + <itemizedlist> + <listitem><para>You can setup and run Hob using these commands: + <literallayout class='monospaced'> + $ source oe-init-build-env + $ hob + </literallayout></para></listitem> + <listitem><para>You can set the + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + for which you are building the image.</para></listitem> + <listitem><para>You can modify various policy settings such as the + package format with which to build, + the parallelism BitBake uses, whether or not to build an + external toolchain, and which host to build against. + </para></listitem> + <listitem><para>You can manage + <link linkend='understanding-and-creating-layers'>layers</link>.</para></listitem> + <listitem><para>You can select a base image and then add extra packages for your custom build. + </para></listitem> + <listitem><para>You can launch and monitor the build from within Hob.</para></listitem> + </itemizedlist> + </para> +</section> + +<section id="platdev-appdev-devshell"> + <title>Using a Development Shell</title> + + <para> + When debugging certain commands or even when just editing packages, + <filename>devshell</filename> can be a useful tool. + When you invoke <filename>devshell</filename>, source files are + extracted into your working directory and patches are applied. + Then, a new terminal is opened and you are placed in the working directory. + In the new terminal, all the OpenEmbedded build-related environment variables are + still defined so you can use commands such as <filename>configure</filename> and + <filename>make</filename>. + The commands execute just as if the OpenEmbedded build system were executing them. + Consequently, working this way can be helpful when debugging a build or preparing + software to be used with the OpenEmbedded build system. + </para> + + <para> + Following is an example that uses <filename>devshell</filename> on a target named + <filename>matchbox-desktop</filename>: + <literallayout class='monospaced'> + $ bitbake matchbox-desktop -c devshell + </literallayout> + </para> + + <para> + This command spawns a terminal with a shell prompt within the OpenEmbedded build environment. + The <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_TERMINAL'><filename>OE_TERMINAL</filename></ulink> + variable controls what type of shell is opened. + </para> + + <para> + For spawned terminals, the following occurs: + <itemizedlist> + <listitem><para>The <filename>PATH</filename> variable includes the + cross-toolchain.</para></listitem> + <listitem><para>The <filename>pkgconfig</filename> variables find the correct + <filename>.pc</filename> files.</para></listitem> + <listitem><para>The <filename>configure</filename> command finds the + Yocto Project site files as well as any other necessary files.</para></listitem> + </itemizedlist> + </para> + + <para> + Within this environment, you can run configure or compile + commands as if they were being run by + the OpenEmbedded build system itself. + As noted earlier, the working directory also automatically changes to the + Source Directory (<ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>). + </para> + + <para> + When you are finished, you just exit the shell or close the terminal window. + </para> + + <note> + <para> + It is worth remembering that when using <filename>devshell</filename> + you need to use the full compiler name such as <filename>arm-poky-linux-gnueabi-gcc</filename> + instead of just using <filename>gcc</filename>. + The same applies to other applications such as <filename>binutils</filename>, + <filename>libtool</filename> and so forth. + BitBake sets up environment variables such as <filename>CC</filename> + to assist applications, such as <filename>make</filename> to find the correct tools. + </para> + + <para> + It is also worth noting that <filename>devshell</filename> still works over + X11 forwarding and similar situations. + </para> + </note> +</section> + +</chapter> |