diff options
| author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2013-01-10 18:55:01 -0600 |
|---|---|---|
| committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2013-01-27 13:54:09 +0000 |
| commit | cdacd8764b26b945253c7a94941806ce34a44da6 (patch) | |
| tree | 508ebed09bf8c7e1425207236d808963ff16b1f1 /documentation/profile-manual | |
| parent | 982637f27ae86d83a7ef425c84ab70345e269451 (diff) | |
| download | ast2050-yocto-poky-cdacd8764b26b945253c7a94941806ce34a44da6.zip ast2050-yocto-poky-cdacd8764b26b945253c7a94941806ce34a44da6.tar.gz | |
profile-manual: Copied in raw "Examples" chapter.
I put the raw text is for chapter 4. No editing.
(From yocto-docs rev: e4a017624595394f86f469e15c1c8ad13e82206d)
Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/profile-manual')
| -rw-r--r-- | documentation/profile-manual/profile-manual-examples.xml | 1906 |
1 files changed, 15 insertions, 1891 deletions
diff --git a/documentation/profile-manual/profile-manual-examples.xml b/documentation/profile-manual/profile-manual-examples.xml index 442cab3..e4363ca 100644 --- a/documentation/profile-manual/profile-manual-examples.xml +++ b/documentation/profile-manual/profile-manual-examples.xml @@ -2,1911 +2,35 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > -<chapter id='dev-manual-model'> +<chapter id='profile-manual-examples'> -<title>Common Development Models</title> +<title>Real-World Examples</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. - </para></listitem> - <listitem><para><emphasis>User Application Development:</emphasis> - User Application Development covers development of applications that you intend - to run on some 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 the solution has been implemented, 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 Hob:</emphasis> - You can use the <ulink url='&YOCTO_HOME_URL;/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> + This chapter contains real-world examples. </para> -<section id='system-development-model'> - <title>System Development Workflow</title> +<section id='slow-write-speed-on-live-images'> + <title>Slow Write Speed on Line Images</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. + In one of our previous releases (denzil), users noticed that booting + off of a live image and writing to disk was noticeably slower. + This included the boot itself, especially the first one, since first + boots tend to do a significant amount of writing due to certain + post-install scripts. </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. + The problem (and solution) was discovered by using the Yocto tracing + tools, in this case 'perf stat', 'perf script', 'perf record' + and 'perf report'. </para> - <section id='developing-a-board-support-package-bsp'> - <title>Developing a Board Support Package (BSP)</title> - - <para> - A BSP is a package 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>. - 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 Distributions</ulink>" - and the - "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The 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 - <link linkend='source-directory'>Source Directory</link>, see the - "<link linkend='getting-setup'>Getting Setup</link>" section.</para></listitem> - <listitem><para><emphasis>Establish the <filename>meta-intel</filename> - repository on your system</emphasis>: Having local copies of the - supported BSP layers on your system gives you access to the build - process and to the tools you need for creating a BSP. - For information on how to get these files, see the - "<link linkend='getting-setup'>Getting Setup</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 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>Four BSPs exist that are part of the - Yocto Project release: <filename>atom-pc</filename>, <filename>beagleboard</filename>, - <filename>mpc8315e</filename>, and <filename>routerstationpro</filename>. - The recipes and configurations for these four BSPs are located and dispersed - within the <link linkend='source-directory'>Source Directory</link>. - On the other hand, BSP layers for Cedar Trail, Chief River, Crown Bay, - Crystal Forest, Emenlow, Fish River, Fish River 2, Jasper Forest, N450, - Romley, sys940x, Sugar Bay, and tlk exist in their own separate layers - within the larger <filename>meta-intel</filename> layer.</note> - <para>When you set up a layer for a new BSP, you should follow a standard layout. - This layout is described in the section - "<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 don't 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 - 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;#building-image'>Building an Image</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 user manual, which is found in the - <filename>bitbake/doc/manual</filename> directory of the - <link linkend='source-directory'>Source Directory</link>.</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>. - You can also find supplemental information in - <ulink url='&YOCTO_DOCS_BSP_URL;'> - The Board Support Package (BSP) Development Guide</ulink>. - Finally, there is wiki page write up of the example also located - <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'> - here</ulink> that you might find 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. - For a complete discussion of the kernel, see the - <ulink url='&YOCTO_DOCS_KERNEL_URL;'>Yocto Project Kernel Architecture and Use Manual</ulink>. - 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. - </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-2.6.34</filename></emphasis> - The - stable Yocto Project kernel that is based on the Linux 2.6.34 released kernel.</para></listitem> - <listitem><para><emphasis><filename>linux-yocto-2.6.37</filename></emphasis> - The - stable Yocto Project kernel that is based on the Linux 2.6.37 released kernel.</para></listitem> - <listitem><para><emphasis><filename>linux-yocto-3.0</filename></emphasis> - The stable - Yocto Project kernel that is based on the Linux 3.0 released kernel.</para></listitem> - <listitem><para><emphasis><filename>linux-yocto-3.0-1.1.x</filename></emphasis> - The - stable Yocto Project kernel to use with the Yocto Project Release 1.1.x. This kernel - is based on the Linux 3.0 released kernel.</para></listitem> - <listitem><para><emphasis><filename>linux-yocto-3.2</filename></emphasis> - The - stable Yocto Project kernel to use with the Yocto Project Release 1.2. This kernel - is based on the Linux 3.2 released kernel.</para></listitem> - <listitem><para><emphasis><filename>linux-yocto-3.4</filename></emphasis> - The - stable Yocto Project kernel to use with the Yocto Project Release 1.3. This kernel - is based on the Linux 3.4 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.0</filename> - kernel. - Thus, everything further to the right in the structure is based on the - <filename>linux-yocto-3.0</filename> kernel. - Branch points to right in the figure represent where the - <filename>linux-yocto-3.0</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 - 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 get at - temporary kernel source files extracted and used during the OpenEmbedded - build system. - We will just talk about working with the temporary source code. - </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 a complete discussion of the Yocto Project kernel's architecture and its - branching strategy, see the - <ulink url='&YOCTO_DOCS_KERNEL_URL;'>Yocto Project Kernel Architecture and Use 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 Distributions</ulink>" and - "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The 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 Build Directory created by the - OpenEmbedded build system when you run BitBake. - If you have never built the kernel you are interested in, 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 - the environment setup script. - 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;#building-image'>Building an Image</ulink>" - section of the Yocto Project Quick Start. - You might want to reference this information. - You can find more information on BitBake in the user manual, which is found in the - <filename>bitbake/doc/manual</filename> directory of the - <link linkend='source-directory'>Source Directory</link>.</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 the <filename>yocto-kernel</filename> script or <filename>menuconfig</filename> - to enable and disable kernel configurations. - Using the script lets you interactively set up kernel configurations. - Using <filename>menuconfig</filename> allows you to interactively develop and test the - configuration changes you are making to the kernel. - When saved, changes using <filename>menuconfig</filename> update the kernel's - <filename>.config</filename>. - Try to resist the temptation of directly editing the <filename>.config</filename> - file found in the - <link linkend='build-directory'>Build Directory</link> at - <filename>tmp/sysroots/<machine-name>/kernel</filename>. - Doing so, can produce unexpected results when the OpenEmbedded build system - regenerates the configuration file.</para> - <para>Once you are satisfied with the configuration changes made using - <filename>menuconfig</filename>, you can directly examine the - <filename>.config</filename> file against a saved original and gather those - changes into a config fragment to be referenced from within the kernel's - <filename>.bbappend</filename> file.</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 Application Development Toolkit (ADT) and - stand-alone cross-development toolchains that - facilitate quick development and integration of your application into its run-time 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. + See all the unvarnished details of how this bug was diagnosed and + solved here: Yocto Bug #3049 </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_QS_URL;#the-linux-distro'>The Linux Distributions</ulink>" and - "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both - in the Yocto Project Quick Start for requirements.</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 OpenEmbeded - 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 the - <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 Quick Start.</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 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 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 Quick Start 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. - </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 Juno and Indigo 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. - 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 Juno 4.2 version of the - Eclipse IDE installed on your development system. - However, if you currently have the Indigo 3.7.2 version installed and you do - not want to upgrade the IDE, you can configure Indigo to work with the - Yocto Project. - See the - "<link linkend='configuring-the-eclipse-ide-indigo'>Configuring the Eclipse IDE (Indigo)</link>" - section. - </para> - - <para> - If you don’t have the Juno 4.2 Eclipse IDE installed, you can find the tarball at - <ulink url='&ECLIPSE_MAIN_URL;'></ulink>. - From that site, choose the Eclipse Classic version particular to your development - host. - 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-SDK-4.2-linux-gtk-x86_64.tar.gz - </literallayout> - </para> - - <para> - If you have the Indigo 3.7.2 Eclipse IDE already installed and you want to use that - version, one issue exists that you need to be aware of regarding the Java - Virtual machine’s garbage collection (GC) process. - The GC process does not clean up the permanent generation - space (PermGen). - This space stores metadata descriptions of classes. - The default value is set too small and it could trigger an - out-of-memory error such as the following: - <literallayout class='monospaced'> - Java.lang.OutOfMemoryError: PermGen space - </literallayout> - </para> - - <para> - This error causes the application to hang. - </para> - - <para> - To fix this issue, you can use the <filename>--vmargs</filename> - option when you start the Indigo 3.7.2 Eclipse IDE - to increase the size of the permanent generation space: - <literallayout class='monospaced'> - eclipse --vmargs --XX:PermSize=256M - </literallayout> - </para> - </section> - - <section id='configuring-the-eclipse-ide-juno'> - <title>Configuring the Eclipse IDE (Juno)</title> - - <para> - This section presents the steps needed to configure the Juno 4.2 Eclipse IDE. - If you are using Indigo 3.7.2, see the - "<link linkend='configuring-the-eclipse-ide-indigo'>Configuring the Eclipse IDE (Indigo)</link>". - </para> - - <para> - Before installing and configuring the Eclipse Yocto Plug-in, you need to configure - the Juno 4.2 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>Juno - &ECLIPSE_JUNO_URL;</filename> - from the "Work with:" pull-down menu.</para></listitem> - <listitem><para>Expand the box next to "Linux Tools" and select the - "LTTng - Linux Tracing Toolkit" boxes.</para></listitem> - <listitem><para>Expand the box next to "Mobile and Device Development" and select the - following boxes: - <itemizedlist> - <listitem><para><filename>C/C++ Remote Launch</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</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 <filename>Programming Languages</filename> - and select the <filename>Autotools Support for CDT</filename> - and <filename>C/C++ Development Tools</filename> boxes.</para></listitem> - <listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem> - </orderedlist> - </para> - </section> - - <section id='configuring-the-eclipse-ide-indigo'> - <title>Configuring the Eclipse IDE (Indigo)</title> - - <para> - This section presents the steps needed to configure the Indigo 3.7.2 Eclipse IDE. - If you are using Juno 4.2, see the - "<link linkend='configuring-the-eclipse-ide-juno'>Configuring the Eclipse IDE (Juno)</link>". - </para> - - <para> - Before installing and configuring the Eclipse Yocto Plug-in, you need to configure - the Indigo 3.7.2 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>indigo - &ECLIPSE_INDIGO_URL;</filename> - from the "Work with:" pull-down menu.</para></listitem> - <listitem><para>Expand the box next to <filename>Programming Languages</filename> - and select the <filename>Autotools Support for CDT (incubation)</filename> - and <filename>C/C++ Development Tools</filename> boxes.</para></listitem> - <listitem><para>Expand the box next to "Linux Tools" and select the - "LTTng - Linux Tracing Toolkit(incubation)" boxes.</para></listitem> - <listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem> - <listitem><para>After the Eclipse IDE restarts and from the Workbench, select - "Install New Software" from the "Help" pull-down menu.</para></listitem> - <listitem><para>Click the - "Available Software Sites" link.</para></listitem> - <listitem><para>Check the box next to - <filename>&ECLIPSE_UPDATES_URL;</filename> - and click "OK".</para></listitem> - <listitem><para>Select <filename>&ECLIPSE_UPDATES_URL;</filename> - from the "Work with:" pull-down menu.</para></listitem> - <listitem><para>Check the box next to <filename>TM and RSE Main Features</filename>. - </para></listitem> - <listitem><para>Expand the box next to <filename>TM and RSE Optional Add-ons</filename> - and select every item except <filename>RSE Unit Tests</filename> and - <filename>RSE WinCE Services (incubation)</filename>.</para></listitem> - <listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem> - <listitem><para>If necessary, select - "Install New Software" from the "Help" pull-down menu so you can click the - "Available Software Sites" link again.</para></listitem> - <listitem><para>After clicking "Available Software Sites", check the box next to - <filename>http://download.eclipse.org/tools/cdt/releases/indigo</filename> - and click "OK".</para></listitem> - <listitem><para>Select <filename>&ECLIPSE_INDIGO_CDT_URL;</filename> - from the "Work with:" pull-down menu.</para></listitem> - <listitem><para>Check the box next to <filename>CDT Main Features</filename>. - </para></listitem> - <listitem><para>Expand the box next to <filename>CDT Optional Features</filename> - and select <filename>C/C++ Remote Launch</filename> and - <filename>Target Communication Framework (incubation)</filename>.</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. - If you don't want to permanently install the plug-in but just want to try it out - within the Eclipse environment, you can import the plug-in project from the - Yocto Project's Source Repositories. - </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;</filename> - in the URL field and provide a meaningful name in the "Name" field.</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 box next to <filename>Development tools and SDKs for Yocto Linux</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. - </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>Open a shell and create a Git repository with: - <literallayout class='monospaced'> - $ git clone git://git.yoctoproject.org/eclipse-poky yocto-eclipse - </literallayout> - For this example, the repository is named - <filename>~/yocto-eclipse</filename>.</para></listitem> - <listitem><para>Change to the directory where you set up - the Git repository: - <literallayout class='monospaced'> - $ cd ~/yocto-eclipse - </literallayout></para></listitem> - <listitem><para>Be sure you are in the right branch for your Git repository. - For this release set the branch to <filename>&DISTRO_NAME;</filename>: - <literallayout class='monospaced'> - $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME; - </literallayout></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> of the - Git repository created earlier. - </para></listitem> - <listitem><para>Run the <filename>build.sh</filename> script - as directed. - Be sure to provide the name of the Git branch along with the - Yocto Project release you are using. - Here is an example that uses the <filename>&DISTRO_NAME;</filename> branches: - <literallayout class='monospaced'> - $ ECLIPSE_HOME=/home/scottrif/yocto-eclipse/scripts/eclipse ./build.sh &DISTRO_NAME; &DISTRO_NAME; - </literallayout> - After running the script, the file - <filename>org.yocto.sdk-<release>-<date>-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 seven. - 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 through the "Okay" buttons.</para></listitem> - <listitem><para>Check the box next to the new entry in the installation window and complete - the installation.</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 id='yocto-project-source'> - <title>Importing the Plug-in Project into the Eclipse Environment</title> - - <para> - Importing the Eclipse Yocto Plug-in project from the Yocto Project source repositories - is useful when you want to try out the latest plug-in from the tip of plug-in's - development tree. - It is important to understand when you import the plug-in you are not installing - it into the Eclipse application. - Rather, you are importing the project and just using it. - To import the plug-in project, follow these steps: - <orderedlist> - <listitem><para>Open a shell and create a Git repository with: - <literallayout class='monospaced'> - $ git clone git://git.yoctoproject.org/eclipse-poky yocto-eclipse - </literallayout> - For this example, the repository is named - <filename>~/yocto-eclipse</filename>.</para></listitem> - <listitem><para>In Eclipse, select "Import" from the "File" menu.</para></listitem> - <listitem><para>Expand the "General" box and select "existing projects into workspace" - and then click "Next".</para></listitem> - <listitem><para>Select the root directory and browse to - <filename>~/yocto-eclipse/plugins</filename>.</para></listitem> - <listitem><para>Three plug-ins exist: "org.yocto.bc.ui", "org.yocto.sdk.ide", and - "org.yocto.sdk.remotetools". - Select and import all of them.</para></listitem> - </orderedlist> - </para> - - <para> - The left navigation pane in the Eclipse application shows the default projects. - Right-click on one of these projects and run it as an Eclipse application. - This brings up a second instance of Eclipse IDE that has the Yocto Plug-in. - </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 <filename>Windows -> Preferences</filename> to display - the <filename>Preferences</filename> Dialog</para></listitem> - <listitem><para>Click <filename>Yocto Project ADT</filename></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 Build Directory. - 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 the - <filename>&YOCTO_ADTPATH_DIR;</filename> directory. - This is the location for toolchains installed by the ADT Installer or by hand. - 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 two ways to install a stand-alone cross-toolchain in the - <filename>/opt/poky</filename> directory. - <note>It is possible to install a stand-alone cross-toolchain in a directory - other than <filename>/opt/poky</filename>. - However, doing so is discouraged.</note></para> - <para>If you are using a system-derived toolchain, the path you provide - for the <filename>Toolchain Root Location</filename> - field is the Build Directory. - 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, then the location is - <filename>/opt/poky/<release></filename>. - Additionally, when you use the ADT Installer, the same 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, then the - location of the sysroot filesystem depends on where you separately - extracted and intalled 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. - </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;#building-image'>Building an Image</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><filename>QEMU:</filename></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</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><filename>External HW:</filename></emphasis> Select this option - if you will be using actual hardware.</para></listitem> - </itemizedlist> - </para> - - <para> - Click the <filename>OK</filename> button 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. - </para> - - <para> - To create a project based on a Yocto template and then display the source code, - follow these steps: - <orderedlist> - <listitem><para>Select <filename>File -> New -> Project</filename>.</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 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 <filename>Next</filename>.</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 <filename>Finish</filename>.</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 <filename>Project -> Change Yocto Project Settings</filename>: - This selection brings up the <filename>Yocot Project Settings</filename> 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 provide using the <filename>Preferences</filename> - Dialog as described earlier - in the "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse - Yocto Plug-in</link>" section. - The <filename>Yocto Project Settings</filename> - 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". - If you are running the Juno version of Eclipse, you can skip down to the next - section where you build the project. - If you are not working with Juno, you need to reconfigure the project as - described in the next step.</para></listitem> - <listitem><para>Select <filename>Project -> Reconfigure Project</filename>: - 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 <filename>Console</filename> 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 in Juno, right click on the project in the navigator pane and select - <filename>Build Project</filename>. - If you are not running Juno, select <filename>Project -> Build Project</filename>. - 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: - <orderedlist> - <listitem><para>Expose the <filename>Run -> External Tools</filename> 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. - For example, you could 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, using the Eclipse IDE - you can deploy your application and use the emulator to perform debugging. - Follow these steps to deploy the application. - <orderedlist> - <listitem><para>Select <filename>Run -> Debug Configurations...</filename></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 <filename>Debug Configurations</filename> Dialog.</para></listitem> - <listitem><para>Enter the absolute path into which you want to deploy - the application. - Use the <filename>Remote Absolute File Path for C/C++Application:</filename> field. - For example, enter <filename>/usr/bin/<programname></filename>.</para></listitem> - <listitem><para>Click on the <filename>Debugger</filename> tab to see the cross-tool debugger - you are using.</para></listitem> - <listitem><para>Click on the <filename>Main</filename> tab.</para></listitem> - <listitem><para>Create a new connection to the QEMU instance - by clicking on <filename>new</filename>.</para></listitem> - <listitem><para>Select <filename>TCF</filename>, which means Target Communication - Framework.</para></listitem> - <listitem><para>Click <filename>Next</filename>.</para></listitem> - <listitem><para>Clear out the <filename>host name</filename> field and enter the IP Address - determined earlier.</para></listitem> - <listitem><para>Click <filename>Finish</filename> to close the - <filename>New Connections</filename> Dialog.</para></listitem> - <listitem><para>Use the drop-down menu now in the <filename>Connection</filename> field and pick - the IP Address you entered.</para></listitem> - <listitem><para>Click <filename>Run</filename> 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 - <filename>YoctoTools</filename> 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 <filename>New</filename> 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 <filename>oprofile</filename> 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>. - <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 ust 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 <filename>Lttng</filename> Eclipse plug-in to graphically - display the output. - For information on how to use <filename>Lttng</filename> to trace an application, - see <ulink url='http://lttng.org/documentation'></ulink>. - <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 ust trace import</filename> tool, - you need to setup the <filename>Lttng</filename> Eclipse plug-in and create a - <filename>Tracing</filename> project. - Do the following: - <orderedlist> - <listitem><para>Select <filename>Window -> Open Perspective -> Other</filename> - and then select <filename>Tracing</filename>.</para></listitem> - <listitem><para>Click <filename>OK</filename> to change the Eclipse perspective - into the <filename>Tracing</filename> perspective.</para></listitem> - <listitem><para>Create a new <filename>Tracing</filename> project by selecting - <filename>File -> New -> Project</filename>.</para></listitem> - <listitem><para>Choose <filename>Tracing -> Tracing Project</filename>. - </para></listitem> - <listitem><para>Generate your tracing data on the remote target. - </para></listitem> - <listitem><para>Click - <filename>Yocto Project Tools -> Lttng2.0 ust trace import</filename> - 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 <filename>OK</filename> 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 - <filename>Select Trace Type... -> Common Trace Format -> Generic CTF Trace</filename> - to map the tracing type.</para></listitem> - <listitem><para>Right click the mouse and select <filename>Open</filename> - to bring up the Eclipse <filename>Lttng</filename> Trace Viewer so you - view the tracing data.</para></listitem> - </orderedlist></para></listitem> - <listitem><para><emphasis><filename>PowerTOP</filename>:</emphasis> Selecting this tool runs - <filename>powertop</filename> on the remote target machine and displays the results in a - new view called <filename>powertop</filename>.</para> - <para><filename>Time to gather data(sec):</filename> is the time passed in seconds before data - is gathered from the remote target for analysis.</para> - <para><filename>show pids in wakeups list:</filename> corresponds to the - <filename>-p</filename> argument - passed to <filename>powertop</filename>.</para></listitem> - <listitem><para><emphasis><filename>LatencyTOP and Perf</filename>:</emphasis> - <filename>latencytop</filename> identifies system latency, while - <filename>perf</filename> 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.</para></listitem> - </itemizedlist> - </para> - </section> - - <section id='customizing-an-image-using-a-bitbake-commander-project-and-hob'> - <title>Customizing an Image Using a BitBake Commander Project and Hob</title> - - <para> - Within Eclipse, you can create a Yocto BitBake Commander project, - edit the metadata, and then use the - <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink> to build a customized - image all within one IDE. - </para> - - <section id='creating-the-yocto-bitbake-commander-project'> - <title>Creating the Yocto BitBake Commander Project</title> - - <para> - To create a Yocto BitBake Commander project, follow these steps: - <orderedlist> - <listitem><para>Select <filename>Window -> Open Perspective -> Other</filename> - and then choose <filename>Bitbake Commander</filename>.</para></listitem> - <listitem><para>Click <filename>OK</filename> to change the Eclipse perspective into the - Bitbake Commander perspective.</para></listitem> - <listitem><para>Select <filename>File -> New -> Project</filename> to create a new Yocto - Bitbake Commander project.</para></listitem> - <listitem><para>Choose <filename>Yocto Project Bitbake Commander -> New Yocto Project</filename> - and click <filename>Next</filename>.</para></listitem> - <listitem><para>Enter the Project Name and choose the Project Location. - The Yocto project's metadata files will be put under the directory - <filename><project_location>/<project_name></filename>. - If that directory does not exist, you need to check - the "Clone from Yocto Git Repository" box, which would execute a - <filename>git clone</filename> command to get the project's metadata files. - </para></listitem> - <listitem><para>Select <filename>Finish</filename> to create the project.</para></listitem> - </orderedlist> - </para> - </section> - - <section id='editing-the-metadata-files'> - <title>Editing the Metadata Files</title> - - <para> - After you create the Yocto Bitbake Commander project, you can modify the metadata files - by opening them in the project. - When editing recipe files (<filename>.bb</filename> files), you can view BitBake - variable values and information by hovering the mouse pointer over the variable name and - waiting a few seconds. - </para> - - <para> - To edit the metadata, follow these steps: - <orderedlist> - <listitem><para>Select your Yocto Bitbake Commander project.</para></listitem> - <listitem><para>Select <filename>File -> New -> Yocto BitBake Commander -> BitBake Recipe</filename> - to open a new recipe wizard.</para></listitem> - <listitem><para>Point to your source by filling in the "SRC_URL" field. - For example, you can add a recipe to your - <link linkend='source-directory'>Source Directory</link> - by defining "SRC_URL" as follows: - <literallayout class='monospaced'> - ftp://ftp.gnu.org/gnu/m4/m4-1.4.9.tar.gz - </literallayout></para></listitem> - <listitem><para>Click "Populate" to calculate the archive md5, sha256, - license checksum values and to auto-generate the recipe filename.</para></listitem> - <listitem><para>Fill in the "Description" field.</para></listitem> - <listitem><para>Be sure values for all required fields exist.</para></listitem> - <listitem><para>Click <filename>Finish</filename>.</para></listitem> - </orderedlist> - </para> - </section> - - <section id='buiding-and-customizing-the-image'> - <title>Building and Customizing the Image</title> - - <para> - To build and customize the image in Eclipse, follow these steps: - <orderedlist> - <listitem><para>Select your Yocto Bitbake Commander project.</para></listitem> - <listitem><para>Select <filename>Project -> Launch HOB</filename>.</para></listitem> - <listitem><para>Enter the Build Directory where you want to put your final images.</para></listitem> - <listitem><para>Click <filename>OK</filename> to launch Hob.</para></listitem> - <listitem><para>Use Hob to customize and build your own images. - For information on Hob, see the - <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob Project Page</ulink> on the - Yocto Project website.</para></listitem> - </orderedlist> - </para> - </section> - </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 cross-development toolchain, 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, etc. - 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://www.qemu.org'>QEMU Home Page</ulink> to download and learn about the - emulator.</para></listitem> - </orderedlist> - </para> - </section> -</section> - -<section id="modifying-temporary-source-code"> - <title>Modifying 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. - You can accomplish these steps all within either a - <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink> or - <link linkend='git'>Git</link> workflow. - </para> - - <section id='finding-the-temporary-source-code'> - <title>Finding the Temporary Source Code</title> - - <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>) depends - on the recipe name and the architecture of the target device. - For example, here is the work directory for recipes and resulting packages that are - not device-dependent: - <literallayout class='monospaced'> - ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR} - </literallayout> - Let's look at an example without variables. - Assuming a top-level <link linkend='source-directory'>Source Directory</link> - named <filename>poky</filename> - and a default Build Directory of <filename>poky/build</filename>, - the following is the work directory for the <filename>acl</filename> recipe that - creates the <filename>acl</filename> package: - <literallayout class='monospaced'> - ~/poky/build/tmp/work/i586-poky-linux/acl-2.2.51-r3 - </literallayout> - </para> - - <para> - If your resulting package is dependent on the target device, - the work directory varies slightly: - <literallayout class='monospaced'> - ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR} - </literallayout> - Again, assuming top-level Source Directory named <filename>poky</filename> - and a default Build Directory of <filename>poky/build</filename>, the - following are the work and temporary source directories, respectively, - for the <filename>acl</filename> package that is being - built for a MIPS-based device: - <literallayout class='monospaced'> - ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2 - ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2/acl-2.2.51 - </literallayout> - </para> - - <note> - To better understand how the OpenEmbedded build system resolves directories during the - build process, see the glossary entries for the - <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>, - <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>, - <ulink url='&YOCTO_DOCS_REF_URL;#var-TOPDIR'><filename>TOPDIR</filename></ulink>, - <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>, - <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_OS'><filename>TARGET_OS</filename></ulink>, - <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>, - <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, - and - <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> - variables in the Yocto Project Reference Manual. - </note> - - <para> - Now that you know where to locate the directory that has the temporary source code, - you can use a Quilt or Git workflow to make your edits, test the changes, - and preserve the changes in the form of patches. - </para> - </section> - - <section id="using-a-quilt-workflow"> - <title>Using a Quilt 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 temporary source code, - test changes, and then preserve the changes in the form of a patch all using Quilt. - </para> - - <para> - Follow these general steps: - <orderedlist> - <listitem><para><emphasis>Find the Source Code:</emphasis> - The temporary source code used by the OpenEmbedded build system is kept in the - Build Directory. - See the - "<link linkend='finding-the-temporary-source-code'>Finding the 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 temporary 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 test your changes - is by calling the <filename>compile</filename> task as shown in the following example: - <literallayout class='monospaced'> - $ bitbake -c compile -f <name_of_package> - </literallayout> - The <filename>-f</filename> or <filename>--force</filename> - option forces re-execution of the specified task. - 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 <filename>-c clean</filename> or - <filename>-c cleanall</filename> with BitBake for the package. - Modifications will also disappear if you use the <filename>rm_work</filename> - feature as described in the - "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</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> - <listitem><para><emphasis>Increment the Recipe Revision Number:</emphasis> - Finally, don't forget to 'bump' the - <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename> - value in the recipe since the resulting packages have changed.</para></listitem> - </orderedlist> - </para> </section> - - <section id='using-a-git-workflow'> - <title>Using a Git Workflow</title> - <para> - Git is an even more 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 temporary source code, - test changes, and then preserve the changes in the form of a patch all using Git. - For general information on Git as it is used in the Yocto Project, see the - "<link linkend='git'>Git</link>" section. - </para> - - <note> - This workflow uses Git only for its ability to manage local changes to the source code - and produce patches independent of any version control system used with the Yocto Project. - </note> - - <para> - Follow these general steps: - <orderedlist> - <listitem><para><emphasis>Find the Source Code:</emphasis> - The temporary source code used by the OpenEmbedded build system is kept in the - Build Directory. - See the - "<link linkend='finding-the-temporary-source-code'>Finding the 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>If needed, initialize a Git Repository:</emphasis> - If the recipe you are working with does not use a Git fetcher, - you need to set up a Git repository as follows: - <literallayout class='monospaced'> - $ git init - $ git add * - $ git commit -m "initial revision" - </literallayout> - The above Git commands initialize a Git repository that is based on the - files in your current working directory, stage all the files, and commit - the files. - At this point, your Git repository is aware of all the source code files. - Any edits you now make to files can be committed later and will be tracked by - Git.</para></listitem> - <listitem><para><emphasis>Edit the Files:</emphasis> - Make your changes to the temporary source code.</para></listitem> - <listitem><para><emphasis>Test Your Changes:</emphasis> - Once you have modified the source code, the easiest way to test your changes - is by calling the <filename>compile</filename> task as shown in the following example: - <literallayout class='monospaced'> - $ bitbake -c compile -f <name_of_package> - </literallayout> - The <filename>-f</filename> or <filename>--force</filename> - option forces re-execution of the specified task. - 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 <filename>-c clean</filename>, <filename>-c cleansstate</filename>, - or <filename>-c cleanall</filename> with BitBake for the package. - Modifications will also disappear if you use the <filename>rm_work</filename> - feature as described in the - "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" - section of the Yocto Project Quick Start. - </note></para></listitem> - <listitem><para><emphasis>See the List of Files You Changed:</emphasis> - Use the <filename>git status</filename> command to see what files you have actually edited. - The ability to have Git track the files you have changed is an advantage that this - workflow has over the Quilt workflow. - Here is the Git command to list your changed files: - <literallayout class='monospaced'> - $ git status - </literallayout></para></listitem> - <listitem><para><emphasis>Stage the Modified Files:</emphasis> - Use the <filename>git add</filename> command to stage the changed files so they - can be committed as follows: - <literallayout class='monospaced'> - $ git add file1.c file2.c file3.c - </literallayout></para></listitem> - <listitem><para><emphasis>Commit the Staged Files and View Your Changes:</emphasis> - Use the <filename>git commit</filename> command to commit the changes to the - local repository. - Once you have committed the files, you can use the <filename>git log</filename> - command to see your changes: - <literallayout class='monospaced'> - $ git commit -m "<commit-summary-message>" - $ git log - </literallayout> - <note>The name of the patch file created in the next step is based on your - <filename>commit-summary-message</filename>.</note></para></listitem> - <listitem><para><emphasis>Generate the Patch:</emphasis> - Once the changes are committed, use the <filename>git format-patch</filename> - command to generate a patch file: - <literallayout class='monospaced'> - $ git format-patch -1 - </literallayout> - Specifying "-1" causes Git to generate the - patch file for the most recent commit.</para> - <para>At this point, the patch file has all your edits made - to the <filename>file1.c</filename>, <filename>file2.c</filename>, and - <filename>file3.c</filename> files. - You can find the resulting patch file in the current directory and it - is named according to the <filename>git commit</filename> summary line. - The patch file ends with <filename>.patch</filename>.</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://0001-<commit-summary-message>.patch" - </literallayout></para></listitem> - <listitem><para><emphasis>Increment the Recipe Revision Number:</emphasis> - Finally, don't forget to 'bump' the - <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename> - value in the recipe since the resulting packages have changed.</para></listitem> - </orderedlist> - </para> - </section> -</section> - -<section id='image-development-using-hob'> - <title>Image Development Using Hob</title> - - <para> - The <ulink url='&YOCTO_HOME_URL;/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 system 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;/projects/hob'></ulink> on the Yocto Project website. - The page has 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 used to build with, - the parrallelism 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> - 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> |
