diff options
| author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2013-01-10 17:25:18 -0600 |
|---|---|---|
| committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2013-01-27 13:54:08 +0000 |
| commit | 6b7ae329462115ef1d5ec70a212d1728f6c7acc4 (patch) | |
| tree | 10d000c71ff623e2d6d6f372d178c96e0c48d2bf /documentation/profile-manual | |
| parent | bc8c4165859482ae3afd9edce93815dee5d7b6c4 (diff) | |
| download | ast2050-yocto-poky-6b7ae329462115ef1d5ec70a212d1728f6c7acc4.zip ast2050-yocto-poky-6b7ae329462115ef1d5ec70a212d1728f6c7acc4.tar.gz | |
profile-manual: Added basic XML files and updated the .gitignore
Added four chapters to the directory. I based these chapters off
of an existing YP manual. I also updated the .gitignore file
so that it will support ingnoring profile-manual make operations.
(From yocto-docs rev: f9658f627fe9d8d6868ce74e9550ea16d23c4156)
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-arch.xml | 391 | ||||
| -rw-r--r-- | documentation/profile-manual/profile-manual-customization.xsl | 8 | ||||
| -rw-r--r-- | documentation/profile-manual/profile-manual-examples.xml | 1915 | ||||
| -rw-r--r-- | documentation/profile-manual/profile-manual-intro.xml | 190 | ||||
| -rw-r--r-- | documentation/profile-manual/profile-manual-style.css | 979 | ||||
| -rw-r--r-- | documentation/profile-manual/profile-manual-usage.xml | 1218 | ||||
| -rw-r--r-- | documentation/profile-manual/profile-manual.xml | 91 |
7 files changed, 4792 insertions, 0 deletions
diff --git a/documentation/profile-manual/profile-manual-arch.xml b/documentation/profile-manual/profile-manual-arch.xml new file mode 100644 index 0000000..b9401e9 --- /dev/null +++ b/documentation/profile-manual/profile-manual-arch.xml @@ -0,0 +1,391 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<chapter id='dev-manual-start'> + +<title>Getting Started with the Yocto Project</title> + +<para> + This chapter introduces the Yocto Project and gives you an idea of what you need to get started. + You can find enough information to set up your development host and build or use images for + hardware supported by the Yocto Project by reading the + <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>. +</para> + +<para> + The remainder of this chapter summarizes what is in the Yocto Project Quick Start and provides + some higher-level concepts you might want to consider. +</para> + +<section id='introducing-the-yocto-project'> + <title>Introducing the Yocto Project</title> + + <para> + The Yocto Project is an open-source collaboration project focused on embedded Linux development. + The project currently provides a build system, which is + referred to as the OpenEmbedded build system in the Yocto Project documentation. + The Yocto Project provides various ancillary tools suitable for the embedded developer + and also features the Sato reference User Interface, which is optimized for + stylus driven, low-resolution screens. + </para> + + <para> + You can use the OpenEmbedded build system, which uses + BitBake to develop complete Linux + images and associated user-space applications for architectures based on ARM, MIPS, PowerPC, + x86 and x86-64. + While the Yocto Project does not provide a strict testing framework, + it does provide or generate for you artifacts that let you perform target-level and + emulated testing and debugging. + Additionally, if you are an <trademark class='trade'>Eclipse</trademark> + IDE user, you can install an Eclipse Yocto Plug-in to allow you to + develop within that familiar environment. + </para> +</section> + +<section id='getting-setup'> + <title>Getting Set Up</title> + + <para> + Here is what you need to get set up to use the Yocto Project: + <itemizedlist> + <listitem><para><emphasis>Host System:</emphasis> You should have a reasonably current + Linux-based host system. + You will have the best results with a recent release of Fedora, + OpenSUSE, Debian, Ubuntu, or CentOS as these releases are frequently tested against the Yocto Project + and officially supported. + For a list of the distributions under validation and their status, see the + "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" section + in the Yocto Project Reference Manual and the wiki page at + <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink>.</para> + <para> + You should also have about 100 gigabytes of free disk space for building images. + </para></listitem> + <listitem><para><emphasis>Packages:</emphasis> The OpenEmbedded build system + requires certain packages exist on your development system (e.g. Python 2.6 or 2.7). + See "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" + section in the Yocto Project Quick Start for the exact package + requirements and the installation commands to install them + for the supported distributions.</para></listitem> + <listitem id='local-yp-release'><para><emphasis>Yocto Project Release:</emphasis> + You need a release of the Yocto Project. + You set that up with a local <link linkend='source-directory'>Source Directory</link> + one of two ways depending on whether you + are going to contribute back into the Yocto Project or not. + <note> + Regardless of the method you use, this manual refers to the resulting local + hierarchical set of files as the "Source Directory." + </note> + <itemizedlist> + <listitem><para><emphasis>Tarball Extraction:</emphasis> If you are not going to contribute + back into the Yocto Project, you can simply download a Yocto Project release you want + from the website’s <ulink url='&YOCTO_HOME_URL;/download'>download page</ulink>. + Once you have the tarball, just extract it into a directory of your choice.</para> + <para>For example, the following command extracts the Yocto Project &DISTRO; + release tarball + into the current working directory and sets up the local Source Directory + with a top-level folder named <filename>&YOCTO_POKY;</filename>: + <literallayout class='monospaced'> + $ tar xfj &YOCTO_POKY_TARBALL; + </literallayout></para> + <para>This method does not produce a local Git repository. + Instead, you simply end up with a snapshot of the release.</para></listitem> + <listitem><para><emphasis>Git Repository Method:</emphasis> If you are going to be contributing + back into the Yocto Project or you simply want to keep up + with the latest developments, you should use Git commands to set up a local + Git repository of the upstream <filename>poky</filename> source repository. + Doing so creates a repository with a complete history of changes and allows + you to easily submit your changes upstream to the project. + Because you cloned the repository, you have access to all the Yocto Project development + branches and tag names used in the upstream repository.</para> + <para>The following transcript shows how to clone the <filename>poky</filename> + Git repository into the current working directory. + <note>You can view the Yocto Project Source Repositories at + <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink></note> + The command creates the local repository in a directory named <filename>poky</filename>. + For information on Git used within the Yocto Project, see the + "<link linkend='git'>Git</link>" section. + <literallayout class='monospaced'> + $ git clone git://git.yoctoproject.org/poky + Initialized empty Git repository in /home/scottrif/poky/.git/ + remote: Counting objects: 141863, done. + remote: Compressing objects: 100% (38624/38624), done. + remote: Total 141863 (delta 99661), reused 141816 (delta 99614) + Receiving objects: 100% (141863/141863), 76.64 MiB | 126 KiB/s, done. + Resolving deltas: 100% (99661/99661), done. + </literallayout></para> + <para>For another example of how to set up your own local Git repositories, see this + <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'> + wiki page</ulink>, which describes how to create both <filename>poky</filename> + and <filename>meta-intel</filename> Git repositories.</para></listitem> + </itemizedlist></para></listitem> + <listitem id='local-kernel-files'><para><emphasis>Yocto Project Kernel:</emphasis> + If you are going to be making modifications to a supported Yocto Project kernel, you + need to establish local copies of the source. + You can find Git repositories of supported Yocto Project Kernels organized under + "Yocto Linux Kernel" in the Yocto Project Source Repositories at + <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para> + <para>This setup can involve creating a bare clone of the Yocto Project kernel and then + copying that cloned repository. + You can create the bare clone and the copy of the bare clone anywhere you like. + For simplicity, it is recommended that you create these structures outside of the + Source Directory (usually <filename>poky</filename>).</para> + <para>As an example, the following transcript shows how to create the bare clone + of the <filename>linux-yocto-3.4</filename> kernel and then create a copy of + that clone. + <note>When you have a local Yocto Project kernel Git repository, you can + reference that repository rather than the upstream Git repository as + part of the <filename>clone</filename> command. + Doing so can speed up the process.</note></para> + <para>In the following example, the bare clone is named + <filename>linux-yocto-3.4.git</filename>, while the + copy is named <filename>my-linux-yocto-3.4-work</filename>: + <literallayout class='monospaced'> + $ git clone --bare git://git.yoctoproject.org/linux-yocto-3.4 linux-yocto-3.4.git + Initialized empty Git repository in /home/scottrif/linux-yocto-3.4.git/ + remote: Counting objects: 2468027, done. + remote: Compressing objects: 100% (392255/392255), done. + remote: Total 2468027 (delta 2071693), reused 2448773 (delta 2052498) + Receiving objects: 100% (2468027/2468027), 530.46 MiB | 129 KiB/s, done. + Resolving deltas: 100% (2071693/2071693), done. + </literallayout></para> + <para>Now create a clone of the bare clone just created: + <literallayout class='monospaced'> + $ git clone linux-yocto-3.4.git my-linux-yocto-3.4-work + Cloning into 'my-linux-yocto-3.4-work'... + done. + </literallayout></para></listitem> + <listitem id='poky-extras-repo'><para><emphasis> + The <filename>poky-extras</filename> Git Repository</emphasis>: + The <filename>poky-extras</filename> Git repository contains metadata needed + only if you are modifying and building the kernel image. + In particular, it contains the kernel BitBake append (<filename>.bbappend</filename>) + files that you + edit to point to your locally modified kernel source files and to build the kernel + image. + Pointing to these local files is much more efficient than requiring a download of the + kernel's source files from upstream each time you make changes to the kernel.</para> + <para>You can find the <filename>poky-extras</filename> Git Repository in the + "Yocto Metadata Layers" area of the Yocto Project Source Repositories at + <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>. + It is good practice to create this Git repository inside the Source Directory.</para> + <para>Following is an example that creates the <filename>poky-extras</filename> Git + repository inside the Source Directory, which is named <filename>poky</filename> + in this case: + <literallayout class='monospaced'> + $ cd ~/poky + $ git clone git://git.yoctoproject.org/poky-extras poky-extras + Initialized empty Git repository in /home/scottrif/poky/poky-extras/.git/ + remote: Counting objects: 618, done. + remote: Compressing objects: 100% (558/558), done. + remote: Total 618 (delta 192), reused 307 (delta 39) + Receiving objects: 100% (618/618), 526.26 KiB | 111 KiB/s, done. + Resolving deltas: 100% (192/192), done. + </literallayout></para></listitem> + <listitem><para id='supported-board-support-packages-(bsps)'><emphasis>Supported Board + Support Packages (BSPs):</emphasis> + The Yocto Project provides a layer called <filename>meta-intel</filename> and + it is maintained in its own separate Git repository. + The <filename>meta-intel</filename> layer contains many supported + <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>.</para> + <para>Similar considerations exist for setting up the <filename>meta-intel</filename> + layer. + You can get set up for BSP development one of two ways: tarball extraction or + with a local Git repository. + It is a good idea to use the same method that you used to set up the Source Directory. + Regardless of the method you use, the Yocto Project uses the following BSP layer + naming scheme: + <literallayout class='monospaced'> + meta-<BSP_name> + </literallayout> + where <filename><BSP_name></filename> is the recognized BSP name. + Here are some examples: + <literallayout class='monospaced'> + meta-crownbay + meta-emenlow + meta-n450 + </literallayout> + 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 for more + information on BSP Layers. + <itemizedlist> + <listitem><para><emphasis>Tarball Extraction:</emphasis> You can download any released + BSP tarball from the same + <ulink url='&YOCTO_HOME_URL;/download'>download site</ulink> used + to get the Yocto Project release. + Once you have the tarball, just extract it into a directory of your choice. + Again, this method just produces a snapshot of the BSP layer in the form + of a hierarchical directory structure.</para></listitem> + <listitem><para><emphasis>Git Repository Method:</emphasis> If you are working + with a local Git repository for your Source Directory, you should also use this method + to set up the <filename>meta-intel</filename> Git repository. + You can locate the <filename>meta-intel</filename> Git repository in the + "Yocto Metadata Layers" area of the Yocto Project Source Repositories at + <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para> + <para>Typically, you set up the <filename>meta-intel</filename> Git repository inside + the Source Directory. + For example, the following transcript shows the steps to clone the + <filename>meta-intel</filename> + Git repository inside the local <filename>poky</filename> Git repository. + <literallayout class='monospaced'> + $ cd ~/poky + $ git clone git://git.yoctoproject.org/meta-intel.git + Initialized empty Git repository in /home/scottrif/poky/meta-intel/.git/ + remote: Counting objects: 3380, done. + remote: Compressing objects: 100% (2750/2750), done. + remote: Total 3380 (delta 1689), reused 227 (delta 113) + Receiving objects: 100% (3380/3380), 1.77 MiB | 128 KiB/s, done. + Resolving deltas: 100% (1689/1689), done. + </literallayout></para> + <para>The same + <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'> + wiki page</ulink> referenced earlier covers how to + set up the <filename>meta-intel</filename> Git repository.</para></listitem> + </itemizedlist></para></listitem> + <listitem><para><emphasis>Eclipse Yocto Plug-in:</emphasis> If you are developing + applications using the Eclipse Integrated Development Environment (IDE), + you will need this plug-in. + See the + "<link linkend='setting-up-the-eclipse-ide'>Setting up the Eclipse IDE</link>" + section for more information.</para></listitem> + </itemizedlist> + </para> +</section> + +<section id='building-images'> + <title>Building Images</title> + + <para> + The build process creates an entire Linux distribution, including the toolchain, from source. + For more information on this topic, see the + "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" + section in the Yocto Project Quick Start. + </para> + + <para> + The build process is as follows: + <orderedlist> + <listitem><para>Make sure you have set up the Source Directory described in the + previous section.</para></listitem> + <listitem><para>Initialize the build environment by sourcing a build environment + script.</para></listitem> + <listitem><para>Optionally ensure the <filename>conf/local.conf</filename> configuration file, + which is found in the + <link linkend='build-directory'>Build Directory</link>, + is set up how you want it. + This file defines many aspects of the build environment including + the target machine architecture through the + <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'>MACHINE</ulink></filename> variable, + the development machine's processor use through the + <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</ulink></filename> and + <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'>PARALLEL_MAKE</ulink></filename> variables, and + a centralized tarball download directory through the + <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'>DL_DIR</ulink></filename> variable.</para></listitem> + <listitem><para>Build the image using the <filename>bitbake</filename> command. + If you want information on BitBake, see the user manual inculded in the + <filename>bitbake/doc/manual</filename> directory of the + <link linkend='source-directory'>Source Directory</link>.</para></listitem> + <listitem><para>Run the image either on the actual hardware or using the QEMU + emulator.</para></listitem> + </orderedlist> + </para> +</section> + +<section id='using-pre-built-binaries-and-qemu'> + <title>Using Pre-Built Binaries and QEMU</title> + + <para> + Another option you have to get started is to use pre-built binaries. + The Yocto Project provides many types of binaries with each release. + See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" + chapter in the Yocto Project Reference Manual + for descriptions of the types of binaries that ship with a Yocto Project + release. + </para> + + <para> + Using a pre-built binary is ideal for developing software applications to run on your + target hardware. + To do this, you need to be able to access the appropriate cross-toolchain tarball for + the architecture on which you are developing. + If you are using an SDK type image, the image ships with the complete toolchain native to + the architecture. + If you are not using an SDK type image, you need to separately download and + install the stand-alone Yocto Project cross-toolchain tarball. + </para> + + <para> + Regardless of the type of image you are using, you need to download the pre-built kernel + that you will boot in the QEMU emulator and then download and extract the target root + filesystem for your target machine’s architecture. + You can get architecture-specific binaries and filesystems from + <ulink url='&YOCTO_MACHINES_DL_URL;'>machines</ulink>. + You can get installation scripts for stand-alone toolchains from + <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchains</ulink>. + Once you have all your files, you set up the environment to emulate the hardware + by sourcing an environment setup script. + Finally, you start the QEMU emulator. + You can find details on all these steps in the + "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>" + section of the Yocto Project Quick Start. + </para> + + <para> + Using QEMU to emulate your hardware can result in speed issues + depending on the target and host architecture mix. + For example, using the <filename>qemux86</filename> image in the emulator + on an Intel-based 32-bit (x86) host machine is fast because the target and + host architectures match. + On the other hand, using the <filename>qemuarm</filename> image on the same Intel-based + host can be slower. + But, you still achieve faithful emulation of ARM-specific issues. + </para> + + <para> + To speed things up, the QEMU images support using <filename>distcc</filename> + to call a cross-compiler outside the emulated system. + If you used <filename>runqemu</filename> to start QEMU, and the + <filename>distccd</filename> application is present on the host system, any + BitBake cross-compiling toolchain available from the build system is automatically + used from within QEMU simply by calling <filename>distcc</filename>. + You can accomplish this by defining the cross-compiler variable + (e.g. <filename>export CC="distcc"</filename>). + Alternatively, if you are using a suitable SDK image or the appropriate + stand-alone toolchain is present in <filename>/opt/poky</filename>, + the toolchain is also automatically used. + </para> + + <note> + Several mechanisms exist that let you connect to the system running on the + QEMU emulator: + <itemizedlist> + <listitem><para>QEMU provides a framebuffer interface that makes standard + consoles available.</para></listitem> + <listitem><para>Generally, headless embedded devices have a serial port. + If so, you can configure the operating system of the running image + to use that port to run a console. + The connection uses standard IP networking.</para></listitem> + <listitem><para>SSH servers exist in some QEMU images. + The <filename>core-image-sato</filename> QEMU image has a Dropbear secure + shell (ssh) server that runs with the root password disabled. + The <filename>core-image-basic</filename> and <filename>core-image-lsb</filename> QEMU images + have OpenSSH instead of Dropbear. + Including these SSH servers allow you to use standard <filename>ssh</filename> and + <filename>scp</filename> commands. + The <filename>core-image-minimal</filename> QEMU image, however, contains no ssh + server.</para></listitem> + <listitem><para>You can use a provided, user-space NFS server to boot the QEMU session + using a local copy of the root filesystem on the host. + In order to make this connection, you must extract a root filesystem tarball by using the + <filename>runqemu-extract-sdk</filename> command. + After running the command, you must then point the <filename>runqemu</filename> + script to the extracted directory instead of a root filesystem image file.</para></listitem> + </itemizedlist> + </note> +</section> +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/documentation/profile-manual/profile-manual-customization.xsl b/documentation/profile-manual/profile-manual-customization.xsl new file mode 100644 index 0000000..8eb6905 --- /dev/null +++ b/documentation/profile-manual/profile-manual-customization.xsl @@ -0,0 +1,8 @@ +<?xml version='1.0'?> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0"> + + <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" /> + +<!-- <xsl:param name="generate.toc" select="'article nop'"></xsl:param> --> + +</xsl:stylesheet> diff --git a/documentation/profile-manual/profile-manual-examples.xml b/documentation/profile-manual/profile-manual-examples.xml new file mode 100644 index 0000000..442cab3 --- /dev/null +++ b/documentation/profile-manual/profile-manual-examples.xml @@ -0,0 +1,1915 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<chapter id='dev-manual-model'> + +<title>Common Development Models</title> + +<para> + Many development models exist for which you can use the Yocto Project. + This chapter overviews simple methods that use tools provided by the + Yocto Project: + <itemizedlist> + <listitem><para><emphasis>System Development:</emphasis> + System Development covers Board Support Package (BSP) development and kernel + modification or configuration. + For an example on how to create a BSP, see the + "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" + section in the Yocto Project Board Support Package (BSP) Developer's Guide. + </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> +</para> + +<section id='system-development-model'> + <title>System Development Workflow</title> + + <para> + System development involves modification or creation of an image that you want to run on + a specific hardware target. + Usually, when you want to create an image that runs on embedded hardware, the image does + not require the same number of features that a full-fledged Linux distribution provides. + Thus, you can create a much smaller image that is designed to use only the + features for your particular hardware. + </para> + + <para> + To help you understand how system development works in the Yocto Project, this section + covers two types of image development: BSP creation and kernel modification or + configuration. + </para> + + <section id='developing-a-board-support-package-bsp'> + <title>Developing a Board Support Package (BSP)</title> + + <para> + A BSP is a 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. + </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> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/documentation/profile-manual/profile-manual-intro.xml b/documentation/profile-manual/profile-manual-intro.xml new file mode 100644 index 0000000..dca2460 --- /dev/null +++ b/documentation/profile-manual/profile-manual-intro.xml @@ -0,0 +1,190 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<chapter id='dev-manual-intro'> + +<title>The Yocto Project Development Manual</title> + <section id='intro'> + <title>Introduction</title> + + <para> + Welcome to the Yocto Project Development Manual! + This manual gives you an idea of how to use the Yocto Project to develop embedded Linux + images and user-space applications to run on targeted devices. + Reading this manual gives you an overview of image, kernel, and user-space application development + using the Yocto Project. + Because much of the information in this manual is general, it contains many references to other + sources where you can find more detail. + For example, detailed information on Git, repositories and open source in general + can be found in many places. + Another example is how to get set up to use the Yocto Project, which our Yocto Project + Quick Start covers. + </para> + + <para> + The Yocto Project Development Manual, however, does provide detailed examples + on how to change the kernel source code, reconfigure the kernel, and develop + an application using the popular <trademark class='trade'>Eclipse</trademark> IDE. + </para> + </section> + + <section id='what-this-manual-provides'> + <title>What this Manual Provides</title> + + <para> + The following list describes what you can get from this guide: + <itemizedlist> + <listitem><para>Information that lets you get set + up to develop using the Yocto Project.</para></listitem> + <listitem><para>Information to help developers who are new to the open source environment + and to the distributed revision control system Git, which the Yocto Project + uses.</para></listitem> + <listitem><para>An understanding of common end-to-end development models and tasks.</para></listitem> + <listitem><para>Development case overviews for both system development and user-space + applications.</para></listitem> + <listitem><para>An overview and understanding of the emulation environment used with + the Yocto Project - the Quick EMUlator (QEMU).</para></listitem> + <listitem><para>An understanding of basic kernel architecture and concepts.</para></listitem> + <listitem><para>Many references to other sources of related information.</para></listitem> + </itemizedlist> + </para> + </section> + + <section id='what-this-manual-does-not-provide'> + <title>What this Manual Does Not Provide</title> + + <para> + This manual will not give you the following: + <itemizedlist> + <listitem><para>Step-by-step instructions if those instructions exist in other Yocto + Project documentation. + For example, the Yocto Project Application Developer's Guide contains detailed + instruction on how to run the + <ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>, + which is used to set up a cross-development environment.</para></listitem> + <listitem><para>Reference material. + This type of material resides in an appropriate reference manual. + For example, system variables are documented in the + <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>.</para></listitem> + <listitem><para>Detailed public information that is not specific to the Yocto Project. + For example, exhaustive information on how to use Git is covered better through the + Internet than in this manual.</para></listitem> + </itemizedlist> + </para> + </section> + + <section id='other-information'> + <title>Other Information</title> + + <para> + Because this manual presents overview information for many different topics, you will + need to supplement it with other information. + The following list presents other sources of information you might find helpful: + <itemizedlist> + <listitem><para><emphasis>The <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>: + </emphasis> The home page for the Yocto Project provides lots of information on the project + as well as links to software and documentation.</para></listitem> + <listitem><para><emphasis> + <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>:</emphasis> This short document lets you get started + with the Yocto Project quickly and start building an image.</para></listitem> + <listitem><para><emphasis> + <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>:</emphasis> This manual is a reference + guide to the OpenEmbedded build system known as "Poky." + The manual also contains a reference chapter on Board Support Package (BSP) + layout.</para></listitem> + <listitem><para><emphasis> + <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>:</emphasis> + This guide provides information that lets you get going with the Application + Development Toolkit (ADT) and stand-alone cross-development toolchains to + develop projects using the Yocto Project.</para></listitem> + <listitem><para><emphasis> + <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>:</emphasis> + This guide defines the structure for BSP components. + Having a commonly understood structure encourages standardization.</para></listitem> + <listitem><para><emphasis> + <ulink url='&YOCTO_DOCS_KERNEL_URL;'>Yocto Project Kernel Architecture and Use Manual</ulink>:</emphasis> + This manual describes the architecture of the Yocto Project kernel and provides + some work flow examples.</para></listitem> + <listitem><para><emphasis> + <ulink url='http://www.youtube.com/watch?v=3ZlOu-gLsh0'> + Eclipse IDE Yocto Plug-in</ulink>:</emphasis> A step-by-step instructional video that + demonstrates how an application developer uses Yocto Plug-in features within + the Eclipse IDE.</para></listitem> + <listitem><para><emphasis> + <ulink url='&YOCTO_WIKI_URL;/wiki/FAQ'>FAQ</ulink>:</emphasis> + A list of commonly asked questions and their answers.</para></listitem> + <listitem><para><emphasis> + <ulink url='&YOCTO_HOME_URL;/download/yocto/yocto-project-&DISTRO;-release-notes-poky-&POKYVERSION;'> + Release Notes</ulink>:</emphasis> Features, updates and known issues for the current + release of the Yocto Project.</para></listitem> + <listitem><para><emphasis> + <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'> + Hob</ulink>:</emphasis> A graphical user interface for BitBake. + Hob's primary goal is to enable a user to perform common tasks more easily.</para></listitem> + <listitem><para><emphasis> + <ulink url='&YOCTO_HOME_URL;/download/build-appliance-0'> + Build Appliance</ulink>:</emphasis> A bootable custom embedded Linux image you can + either build using a non-Linux development system (VMware applications) or download + from the Yocto Project website. + See the <ulink url='&YOCTO_HOME_URL;/documentation/build-appliance-manual'>Build Appliance</ulink> + page for more information.</para></listitem> + <listitem><para><emphasis> + <ulink url='&YOCTO_BUGZILLA_URL;'>Bugzilla</ulink>:</emphasis> + The bug tracking application the Yocto Project uses. + If you find problems with the Yocto Project, you should report them using this + application.</para></listitem> + <listitem><para><emphasis> + Yocto Project Mailing Lists:</emphasis> To subscribe to the Yocto Project mailing + lists, click on the following URLs and follow the instructions: + <itemizedlist> + <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> for a + Yocto Project Discussions mailing list.</para></listitem> + <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> for a + Yocto Project Discussions mailing list about the Poky build system.</para></listitem> + <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto-announce'></ulink> + for a mailing list to receive official Yocto Project announcements for developments and + as well as Yocto Project milestones.</para></listitem> + <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo'></ulink> for a + listing of all public mailing lists on <filename>lists.yoctoproject.org</filename>. + </para></listitem> + </itemizedlist></para></listitem> + <listitem><para><emphasis>Internet Relay Chat (IRC):</emphasis> + Two IRC channels on freenode are available + for Yocto Project and Poky discussions: <filename>#yocto</filename> and + <filename>#poky</filename>, respectively.</para></listitem> + <listitem><para><emphasis> + <ulink url='&OH_HOME_URL;'>OpenedHand</ulink>:</emphasis> + The company that initially developed the Poky project, which is the basis + for the OpenEmbedded build system used by the Yocto Project. + OpenedHand was acquired by Intel Corporation in 2008.</para></listitem> + <listitem><para><emphasis> + <ulink url='http://www.intel.com/'>Intel Corporation</ulink>:</emphasis> + A multinational semiconductor chip manufacturer company whose Software and + Services Group created and supports the Yocto Project. + Intel acquired OpenedHand in 2008.</para></listitem> + <listitem><para><emphasis> + <ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>:</emphasis> + The build system used by the Yocto Project. + This project is the upstream, generic, embedded distribution from which the Yocto + Project derives its build system (Poky) from and to which it contributes.</para></listitem> + <listitem><para><emphasis> + <ulink url='http://developer.berlios.de/projects/bitbake/'> + BitBake</ulink>:</emphasis> The tool used by the OpenEmbedded build system + to process project metadata.</para></listitem> + <listitem><para><emphasis> + BitBake User Manual:</emphasis> + A comprehensive guide to the BitBake tool. + If you want information on BitBake, see the user manual inculded in the + <filename>bitbake/doc/manual</filename> directory of the + <link linkend='source-directory'>Source Directory</link>.</para></listitem> + <listitem><para><emphasis> + <ulink url='http://wiki.qemu.org/Index.html'>Quick EMUlator (QEMU)</ulink>: + </emphasis> An open-source machine emulator and virtualizer.</para></listitem> + </itemizedlist> + </para> + </section> +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/documentation/profile-manual/profile-manual-style.css b/documentation/profile-manual/profile-manual-style.css new file mode 100644 index 0000000..23c8e74 --- /dev/null +++ b/documentation/profile-manual/profile-manual-style.css @@ -0,0 +1,979 @@ +/* + Generic XHTML / DocBook XHTML CSS Stylesheet. + + Browser wrangling and typographic design by + Oyvind Kolas / pippin@gimp.org + + Customised for Poky by + Matthew Allum / mallum@o-hand.com + + Thanks to: + Liam R. E. Quin + William Skaggs + Jakub Steiner + + Structure + --------- + + The stylesheet is divided into the following sections: + + Positioning + Margins, paddings, width, font-size, clearing. + Decorations + Borders, style + Colors + Colors + Graphics + Graphical backgrounds + Nasty IE tweaks + Workarounds needed to make it work in internet explorer, + currently makes the stylesheet non validating, but up until + this point it is validating. + Mozilla extensions + Transparency for footer + Rounded corners on boxes + +*/ + + + /*************** / + / Positioning / +/ ***************/ + +body { + font-family: Verdana, Sans, sans-serif; + + min-width: 640px; + width: 80%; + margin: 0em auto; + padding: 2em 5em 5em 5em; + color: #333; +} + +h1,h2,h3,h4,h5,h6,h7 { + font-family: Arial, Sans; + color: #00557D; + clear: both; +} + +h1 { + font-size: 2em; + text-align: left; + padding: 0em 0em 0em 0em; + margin: 2em 0em 0em 0em; +} + +h2.subtitle { + margin: 0.10em 0em 3.0em 0em; + padding: 0em 0em 0em 0em; + font-size: 1.8em; + padding-left: 20%; + font-weight: normal; + font-style: italic; +} + +h2 { + margin: 2em 0em 0.66em 0em; + padding: 0.5em 0em 0em 0em; + font-size: 1.5em; + font-weight: bold; +} + +h3.subtitle { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; + font-size: 142.14%; + text-align: right; +} + +h3 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 140%; + font-weight: bold; +} + +h4 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 120%; + font-weight: bold; +} + +h5 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +h6 { + margin: 1em 0em 0em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +.authorgroup { + background-color: transparent; + background-repeat: no-repeat; + padding-top: 256px; + background-image: url("figures/dev-title.png"); + background-position: left top; + margin-top: -256px; + padding-right: 50px; + margin-left: 0px; + text-align: right; + width: 740px; +} + +h3.author { + margin: 0em 0me 0em 0em; + padding: 0em 0em 0em 0em; + font-weight: normal; + font-size: 100%; + color: #333; + clear: both; +} + +.author tt.email { + font-size: 66%; +} + +.titlepage hr { + width: 0em; + clear: both; +} + +.revhistory { + padding-top: 2em; + clear: both; +} + +.toc, +.list-of-tables, +.list-of-examples, +.list-of-figures { + padding: 1.33em 0em 2.5em 0em; + color: #00557D; +} + +.toc p, +.list-of-tables p, +.list-of-figures p, +.list-of-examples p { + padding: 0em 0em 0em 0em; + padding: 0em 0em 0.3em; + margin: 1.5em 0em 0em 0em; +} + +.toc p b, +.list-of-tables p b, +.list-of-figures p b, +.list-of-examples p b{ + font-size: 100.0%; + font-weight: bold; +} + +.toc dl, +.list-of-tables dl, +.list-of-figures dl, +.list-of-examples dl { + margin: 0em 0em 0.5em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dt { + margin: 0em 0em 0em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dd { + margin: 0em 0em 0em 2.6em; + padding: 0em 0em 0em 0em; +} + +div.glossary dl, +div.variablelist dl { +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + font-weight: normal; + width: 20em; + text-align: right; +} + +.variablelist dl dt { + margin-top: 0.5em; +} + +.glossary dl dd, +.variablelist dl dd { + margin-top: -1em; + margin-left: 25.5em; +} + +.glossary dd p, +.variablelist dd p { + margin-top: 0em; + margin-bottom: 1em; +} + + +div.calloutlist table td { + padding: 0em 0em 0em 0em; + margin: 0em 0em 0em 0em; +} + +div.calloutlist table td p { + margin-top: 0em; + margin-bottom: 1em; +} + +div p.copyright { + text-align: left; +} + +div.legalnotice p.legalnotice-title { + margin-bottom: 0em; +} + +p { + line-height: 1.5em; + margin-top: 0em; + +} + +dl { + padding-top: 0em; +} + +hr { + border: solid 1px; +} + + +.mediaobject, +.mediaobjectco { + text-align: center; +} + +img { + border: none; +} + +ul { + padding: 0em 0em 0em 1.5em; +} + +ul li { + padding: 0em 0em 0em 0em; +} + +ul li p { + text-align: left; +} + +table { + width :100%; +} + +th { + padding: 0.25em; + text-align: left; + font-weight: normal; + vertical-align: top; +} + +td { + padding: 0.25em; + vertical-align: top; +} + +p a[id] { + margin: 0px; + padding: 0px; + display: inline; + background-image: none; +} + +a { + text-decoration: underline; + color: #444; +} + +pre { + overflow: auto; +} + +a:hover { + text-decoration: underline; + /*font-weight: bold;*/ +} + + +div.informalfigure, +div.informalexample, +div.informaltable, +div.figure, +div.table, +div.example { + margin: 1em 0em; + padding: 1em; + page-break-inside: avoid; +} + + +div.informalfigure p.title b, +div.informalexample p.title b, +div.informaltable p.title b, +div.figure p.title b, +div.example p.title b, +div.table p.title b{ + padding-top: 0em; + margin-top: 0em; + font-size: 100%; + font-weight: normal; +} + +.mediaobject .caption, +.mediaobject .caption p { + text-align: center; + font-size: 80%; + padding-top: 0.5em; + padding-bottom: 0.5em; +} + +.epigraph { + padding-left: 55%; + margin-bottom: 1em; +} + +.epigraph p { + text-align: left; +} + +.epigraph .quote { + font-style: italic; +} +.epigraph .attribution { + font-style: normal; + text-align: right; +} + +span.application { + font-style: italic; +} + +.programlisting { + font-family: monospace; + font-size: 80%; + white-space: pre; + margin: 1.33em 0em; + padding: 1.33em; +} + +.tip, +.warning, +.caution, +.note { + margin-top: 1em; + margin-bottom: 1em; + +} + +/* force full width of table within div */ +.tip table, +.warning table, +.caution table, +.note table { + border: none; + width: 100%; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + padding: 0.8em 0.0em 0.0em 0.0em; + margin : 0em 0em 0em 0em; +} + +.tip p, +.warning p, +.caution p, +.note p { + margin-top: 0.5em; + margin-bottom: 0.5em; + padding-right: 1em; + text-align: left; +} + +.acronym { + text-transform: uppercase; +} + +b.keycap, +.keycap { + padding: 0.09em 0.3em; + margin: 0em; +} + +.itemizedlist li { + clear: none; +} + +.filename { + font-size: medium; + font-family: Courier, monospace; +} + + +div.navheader, div.heading{ + position: absolute; + left: 0em; + top: 0em; + width: 100%; + background-color: #cdf; + width: 100%; +} + +div.navfooter, div.footing{ + position: fixed; + left: 0em; + bottom: 0em; + background-color: #eee; + width: 100%; +} + + +div.navheader td, +div.navfooter td { + font-size: 66%; +} + +div.navheader table th { + /*font-family: Georgia, Times, serif;*/ + /*font-size: x-large;*/ + font-size: 80%; +} + +div.navheader table { + border-left: 0em; + border-right: 0em; + border-top: 0em; + width: 100%; +} + +div.navfooter table { + border-left: 0em; + border-right: 0em; + border-bottom: 0em; + width: 100%; +} + +div.navheader table td a, +div.navfooter table td a { + color: #777; + text-decoration: none; +} + +/* normal text in the footer */ +div.navfooter table td { + color: black; +} + +div.navheader table td a:visited, +div.navfooter table td a:visited { + color: #444; +} + + +/* links in header and footer */ +div.navheader table td a:hover, +div.navfooter table td a:hover { + text-decoration: underline; + background-color: transparent; + color: #33a; +} + +div.navheader hr, +div.navfooter hr { + display: none; +} + + +.qandaset tr.question td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} + +.qandaset tr.answer td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} +.answer td { + padding-bottom: 1.5em; +} + +.emphasis { + font-weight: bold; +} + + + /************* / + / decorations / +/ *************/ + +.titlepage { +} + +.part .title { +} + +.subtitle { + border: none; +} + +/* +h1 { + border: none; +} + +h2 { + border-top: solid 0.2em; + border-bottom: solid 0.06em; +} + +h3 { + border-top: 0em; + border-bottom: solid 0.06em; +} + +h4 { + border: 0em; + border-bottom: solid 0.06em; +} + +h5 { + border: 0em; +} +*/ + +.programlisting { + border: solid 1px; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example { + border: 1px solid; +} + + + +.tip, +.warning, +.caution, +.note { + border: 1px solid; +} + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom: 1px solid; +} + +.question td { + border-top: 1px solid black; +} + +.answer { +} + + +b.keycap, +.keycap { + border: 1px solid; +} + + +div.navheader, div.heading{ + border-bottom: 1px solid; +} + + +div.navfooter, div.footing{ + border-top: 1px solid; +} + + /********* / + / colors / +/ *********/ + +body { + color: #333; + background: white; +} + +a { + background: transparent; +} + +a:hover { + background-color: #dedede; +} + + +h1, +h2, +h3, +h4, +h5, +h6, +h7, +h8 { + background-color: transparent; +} + +hr { + border-color: #aaa; +} + + +.tip, .warning, .caution, .note { + border-color: #fff; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom-color: #fff; +} + + +.warning { + background-color: #f0f0f2; +} + +.caution { + background-color: #f0f0f2; +} + +.tip { + background-color: #f0f0f2; +} + +.note { + background-color: #f0f0f2; +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + color: #044; +} + +div.figure, +div.table, +div.example, +div.informalfigure, +div.informaltable, +div.informalexample { + border-color: #aaa; +} + +pre.programlisting { + color: black; + background-color: #fff; + border-color: #aaa; + border-width: 2px; +} + +.guimenu, +.guilabel, +.guimenuitem { + background-color: #eee; +} + + +b.keycap, +.keycap { + background-color: #eee; + border-color: #999; +} + + +div.navheader { + border-color: black; +} + + +div.navfooter { + border-color: black; +} + + + /*********** / + / graphics / +/ ***********/ + +/* +body { + background-image: url("images/body_bg.jpg"); + background-attachment: fixed; +} + +.navheader, +.note, +.tip { + background-image: url("images/note_bg.jpg"); + background-attachment: fixed; +} + +.warning, +.caution { + background-image: url("images/warning_bg.jpg"); + background-attachment: fixed; +} + +.figure, +.informalfigure, +.example, +.informalexample, +.table, +.informaltable { + background-image: url("images/figure_bg.jpg"); + background-attachment: fixed; +} + +*/ +h1, +h2, +h3, +h4, +h5, +h6, +h7{ +} + +/* +Example of how to stick an image as part of the title. + +div.article .titlepage .title +{ + background-image: url("figures/white-on-black.png"); + background-position: center; + background-repeat: repeat-x; +} +*/ + +div.preface .titlepage .title, +div.colophon .title, +div.chapter .titlepage .title, +div.article .titlepage .title +{ +} + +div.section div.section .titlepage .title, +div.sect2 .titlepage .title { + background: none; +} + + +h1.title { + background-color: transparent; + background-image: url("figures/yocto-project-bw.png"); + background-repeat: no-repeat; + height: 256px; + text-indent: -9000px; + overflow:hidden; +} + +h2.subtitle { + background-color: transparent; + text-indent: -9000px; + overflow:hidden; + width: 0px; + display: none; +} + + /*************************************** / + / pippin.gimp.org specific alterations / +/ ***************************************/ + +/* +div.heading, div.navheader { + color: #777; + font-size: 80%; + padding: 0; + margin: 0; + text-align: left; + position: absolute; + top: 0px; + left: 0px; + width: 100%; + height: 50px; + background: url('/gfx/heading_bg.png') transparent; + background-repeat: repeat-x; + background-attachment: fixed; + border: none; +} + +div.heading a { + color: #444; +} + +div.footing, div.navfooter { + border: none; + color: #ddd; + font-size: 80%; + text-align:right; + + width: 100%; + padding-top: 10px; + position: absolute; + bottom: 0px; + left: 0px; + + background: url('/gfx/footing_bg.png') transparent; +} +*/ + + + + /****************** / + / nasty ie tweaks / +/ ******************/ + +/* +div.heading, div.navheader { + width:expression(document.body.clientWidth + "px"); +} + +div.footing, div.navfooter { + width:expression(document.body.clientWidth + "px"); + margin-left:expression("-5em"); +} +body { + padding:expression("4em 5em 0em 5em"); +} +*/ + + /**************************************** / + / mozilla vendor specific css extensions / +/ ****************************************/ +/* +div.navfooter, div.footing{ + -moz-opacity: 0.8em; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example, +.tip, +.warning, +.caution, +.note { + -moz-border-radius: 0.5em; +} + +b.keycap, +.keycap { + -moz-border-radius: 0.3em; +} +*/ + +table tr td table tr td { + display: none; +} + + +hr { + display: none; +} + +table { + border: 0em; +} + + .photo { + float: right; + margin-left: 1.5em; + margin-bottom: 1.5em; + margin-top: 0em; + max-width: 17em; + border: 1px solid gray; + padding: 3px; + background: white; +} + .seperator { + padding-top: 2em; + clear: both; + } + + #validators { + margin-top: 5em; + text-align: right; + color: #777; + } + @media print { + body { + font-size: 8pt; + } + .noprint { + display: none; + } + } + + +.tip, +.note { + background: #f0f0f2; + color: #333; + padding: 20px; + margin: 20px; +} + +.tip h3, +.note h3 { + padding: 0em; + margin: 0em; + font-size: 2em; + font-weight: bold; + color: #333; +} + +.tip a, +.note a { + color: #333; + text-decoration: underline; +} + +.footnote { + font-size: small; + color: #333; +} + +/* Changes the announcement text */ +.tip h3, +.warning h3, +.caution h3, +.note h3 { + font-size:large; + color: #00557D; +} + diff --git a/documentation/profile-manual/profile-manual-usage.xml b/documentation/profile-manual/profile-manual-usage.xml new file mode 100644 index 0000000..65e17e2 --- /dev/null +++ b/documentation/profile-manual/profile-manual-usage.xml @@ -0,0 +1,1218 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<chapter id='dev-manual-newbie'> + +<title>The Yocto Project Open Source Development Environment</title> + +<para> + This chapter helps you understand the Yocto Project as an open source development project. + In general, working in an open source environment is very different from working in a + closed, proprietary environment. + Additionally, the Yocto Project uses specific tools and constructs as part of its development + environment. + This chapter specifically addresses open source philosophy, licensing issues, code repositories, + the open source distributed version control system Git, and best practices using the Yocto Project. +</para> + +<section id='open-source-philosophy'> + <title>Open Source Philosophy</title> + + <para> + Open source philosophy is characterized by software development directed by peer production + and collaboration through an active community of developers. + Contrast this to the more standard centralized development models used by commercial software + companies where a finite set of developers produces a product for sale using a defined set + of procedures that ultimately result in an end product whose architecture and source material + are closed to the public. + </para> + + <para> + Open source projects conceptually have differing concurrent agendas, approaches, and production. + These facets of the development process can come from anyone in the public (community) that has a + stake in the software project. + The open source environment contains new copyright, licensing, domain, and consumer issues + that differ from the more traditional development environment. + In an open source environment, the end product, source material, and documentation are + all available to the public at no cost. + </para> + + <para> + A benchmark example of an open source project is the Linux Kernel, which was initially conceived + and created by Finnish computer science student Linus Torvalds in 1991. + Conversely, a good example of a non-open source project is the + <trademark class='registered'>Windows</trademark> family of operating + systems developed by <trademark class='registered'>Microsoft</trademark> Corporation. + </para> + + <para> + Wikipedia has a good historical description of the Open Source Philosophy + <ulink url='http://en.wikipedia.org/wiki/Open_source'>here</ulink>. + You can also find helpful information on how to participate in the Linux Community + <ulink url='http://ldn.linuxfoundation.org/book/how-participate-linux-community'>here</ulink>. + </para> +</section> + +<section id="usingpoky-changes-collaborate"> + <title>Using the Yocto Project in a Team Environment</title> + + <para> + It might not be immediately clear how you can use the Yocto Project in a team environment, + or scale it for a large team of developers. + The specifics of any situation determine the best solution. + Granted that the Yocto Project offers immense flexibility regarding this, practices do exist + that experience has shown work well. + </para> + + <para> + The core component of any development effort with the Yocto Project is often an + automated build and testing framework along with an image generation process. + You can use these core components to check that the metadata can be built, + highlight when commits break the build, and provide up-to-date images that + allow developers to test the end result and use it as a base platform for further + development. + Experience shows that buildbot is a good fit for this role. + What works well is to configure buildbot to make two types of builds: + incremental and full (from scratch). + See "<ulink url='http://autobuilder.yoctoproject.org:8010/'>Welcome to the buildbot for the Yocto Project</ulink>" + for an example implementation that uses buildbot. + </para> + + <para> + You can tie an incremental build to a commit hook that triggers the build + each time a commit is made to the metadata. + This practice results in useful acid tests that determine whether a given commit + breaks the build in some serious way. + Associating a build to a commit can catch a lot of simple errors. + Furthermore, the tests are fast so developers can get quick feedback on changes. + </para> + + <para> + Full builds build and test everything from the ground up. + These types of builds usually happen at predetermined times like during the + night when the machine load is low. + </para> + + <para> + Most teams have many pieces of software undergoing active development at any given time. + You can derive large benefits by putting these pieces under the control of a source + control system that is compatible (i.e. Git or Subversion (SVN)) with the OpenEmbedded + build system that the Yocto Project uses. + You can then set the autobuilder to pull the latest revisions of the packages + and test the latest commits by the builds. + This practice quickly highlights issues. + The build system easily supports testing configurations that use both a + stable known good revision and a floating revision. + The build system can also take just the changes from specific source control branches. + This capability allows you to track and test specific changes. + </para> + + <para> + Perhaps the hardest part of setting this up is defining the software project or + the metadata policies that surround the different source control systems. + Of course circumstances will be different in each case. + However, this situation reveals one of the Yocto Project's advantages - + the system itself does not + force any particular policy on users, unlike a lot of build systems. + The system allows the best policies to be chosen for the given circumstances. + </para> + + <para> + In general, best practices exist that make your work with the Yocto + Project easier in a team environment. + This list presents some of these practices you might consider following. + Of course, you need to understand that you do not have to follow these + practices and your setup can be totally controlled and customized by + your team: + <itemizedlist> + <listitem><para>Use <link linkend='git'>Git</link> + as the source control system.</para></listitem> + <listitem><para>Maintain your metadata in layers that make sense + for your situation. + See the "<link linkend='understanding-and-creating-layers'>Understanding + and Creating Layers</link>" section for more information on + layers.</para></listitem> + <listitem><para>Separate the project's metadata and code by using + separate Git repositories. + See the "<link linkend='yocto-project-repositories'>Yocto Project + Source Repositories</link>" section for information on these + repositories. + See the "<link linkend='getting-setup'>Getting Set Up</link>" section + for information on how to set up various Yocto Project related + Git repositories.</para></listitem> + <listitem><para>Set up the directory for the shared state cache + (<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>) + where they make sense. + For example, set up the sstate cache for developers using the + same office and share source directories on the developer's + machines.</para></listitem> + <listitem><para>Set up an autobuilder and have it populate the + sstate cache and source directories.</para></listitem> + </itemizedlist> + </para> +</section> + +<section id='yocto-project-repositories'> + <title>Yocto Project Source Repositories</title> + + <para> + The Yocto Project team maintains complete source repositories for all Yocto Project files + at <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'></ulink>. + This web-based source code browser is organized into categories by function such as + IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and so forth. + From the interface, you can click on any particular item in the "Name" column and + see the URL at the bottom of the page that you need to set up a Git repository for + that particular item. + Having a local Git repository of the Source Directory (poky) allows you to + make changes, contribute to the history, and ultimately enhance the Yocto Project's + tools, Board Support Packages, and so forth. + </para> + + <para> + Conversely, if you are a developer that is not interested in contributing back to the + Yocto Project, you have the ability to simply download and extract release tarballs + and use them within the Yocto Project environment. + All that is required is a particular release of the Yocto Project and + your application source code. + </para> + + <para> + For any supported release of Yocto Project, you can go to the Yocto Project website’s + <ulink url='&YOCTO_HOME_URL;/download'>download page</ulink> and get a + tarball of the release. + You can also go to this site to download any supported BSP tarballs. + Unpacking the tarball gives you a hierarchical Source Directory that lets you develop + using the Yocto Project. + </para> + + <para> + Once you are set up through either tarball extraction or a checkout of Git repositories, + you are ready to develop. + </para> + + <para> + In summary, here is where you can get the project files needed for development: + <itemizedlist> + <listitem><para id='source-repositories'><emphasis><ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'>Source Repositories:</ulink></emphasis> + This area contains IDE Plugins, Matchbox, Poky, Poky Support, Tools, Yocto Linux Kernel, and Yocto + Metadata Layers. + You can create local copies of Git repositories for each of these areas.</para> + <para> + <imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" /> + </para></listitem> + <listitem><para><anchor id='index-downloads' /><emphasis><ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink></emphasis> + This area contains index releases such as + the <trademark class='trade'>Eclipse</trademark> + Yocto Plug-in, miscellaneous support, poky, pseudo, installers for cross-development toolchains, + and all released versions of Yocto Project in the form of images or tarballs. + Downloading and extracting these files does not produce a local copy of the + Git repository but rather a snapshot of a particular release or image.</para> + <para> + <imagedata fileref="figures/index-downloads.png" align="center" width="6in" depth="4in" /> + </para></listitem> + <listitem><para><emphasis><ulink url='&YOCTO_HOME_URL;/download'>Yocto Project Download Page</ulink></emphasis> + This page on the Yocto Project website allows you to download any Yocto Project + release or Board Support Package (BSP) in tarball form. + The tarballs are similar to those found in the + <ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink> area.</para> + <para> + <imagedata fileref="figures/yp-download.png" align="center" width="6in" depth="4in" /> + </para></listitem> + </itemizedlist> + </para> +</section> + +<section id='yocto-project-terms'> + <title>Yocto Project Terms</title> + + <para> + Following is a list of terms and definitions users new to the Yocto Project development + environment might find helpful. + While some of these terms are universal, the list includes them just in case: + <itemizedlist> + <listitem><para><emphasis>Append Files:</emphasis> Files that append build information to + a recipe file. + Append files are known as BitBake append files and <filename>.bbappend</filename> files. + The OpenEmbedded build system expects every append file to have a corresponding and + underlying recipe (<filename>.bb</filename>) file. + Furthermore, the append file and the underlying recipe must have the same root filename. + The filenames can differ only in the file type suffix used (e.g. + <filename>formfactor_0.0.bb</filename> and <filename>formfactor_0.0.bbappend</filename>). + </para> + <para>Information in append files overrides the information in the similarly-named recipe file. + For an example of an append file in use, see the + "<link linkend='using-bbappend-files'>Using .bbappend Files</link>" section. + </para></listitem> + <listitem><para id='bitbake-term'><emphasis>BitBake:</emphasis> + The task executor and scheduler used by + the OpenEmbedded build system to build images. + For more information on BitBake, see the BitBake documentation + in the <filename>bitbake/doc/manual</filename> directory of the + <link linkend='source-directory'>Source Directory</link>.</para></listitem> + <listitem> + <para id='build-directory'><emphasis>Build Directory:</emphasis> + This term refers to the area used by the OpenEmbedded build system for builds. + The area is created when you <filename>source</filename> the setup + environment script that is found in the Source Directory + (i.e. <filename>&OE_INIT_FILE;</filename>). + The <ulink url='&YOCTO_DOCS_REF_URL;#var-TOPDIR'><filename>TOPDIR</filename></ulink> + variable points to the Build Directory.</para> + + <para>You have a lot of flexibility when creating the Build Directory. + Following are some examples that show how to create the directory: + <itemizedlist> + <listitem><para>Create the Build Directory in your current working directory + and name it <filename>build</filename>. + This is the default behavior. + <literallayout class='monospaced'> + $ source &OE_INIT_PATH; + </literallayout></para></listitem> + <listitem><para>Provide a directory path and specifically name the build + directory. + This next example creates a Build Directory named <filename>YP-&POKYVERSION;</filename> + in your home directory within the directory <filename>mybuilds</filename>. + If <filename>mybuilds</filename> does not exist, the directory is created for you: + <literallayout class='monospaced'> + $ source &OE_INIT_PATH; $HOME/mybuilds/YP-&POKYVERSION; + </literallayout></para></listitem> + <listitem><para>Provide an existing directory to use as the Build Directory. + This example uses the existing <filename>mybuilds</filename> directory + as the Build Directory. + <literallayout class='monospaced'> + $ source &OE_INIT_PATH; $HOME/mybuilds/ + </literallayout></para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para><emphasis>Build System:</emphasis> In the context of the Yocto Project + this term refers to the OpenEmbedded build system used by the project. + This build system is based on the project known as "Poky." + For some historical information about Poky, see the + <link linkend='poky'>Poky</link> term further along in this section. + </para></listitem> + <listitem><para><emphasis>Classes:</emphasis> Files that provide for logic encapsulation + and inheritance allowing commonly used patterns to be defined once and easily used + in multiple recipes. + Class files end with the <filename>.bbclass</filename> filename extension. + </para></listitem> + <listitem><para><emphasis>Configuration File:</emphasis> Configuration information in various + <filename>.conf</filename> files provides global definitions of variables. + The <filename>conf/local.conf</filename> configuration file in the + <link linkend='build-directory'>Build Directory</link> + contains user-defined variables that affect each build. + The <filename>meta-yocto/conf/distro/poky.conf</filename> configuration file + defines Yocto ‘distro’ configuration + variables used only when building with this policy. + Machine configuration files, which + are located throughout the + <link linkend='source-directory'>Source Directory</link>, define + variables for specific hardware and are only used when building for that target + (e.g. the <filename>machine/beagleboard.conf</filename> configuration file defines + variables for the Texas Instruments ARM Cortex-A8 development board). + Configuration files end with a <filename>.conf</filename> filename extension. + </para></listitem> + <listitem><para><emphasis>Cross-Development Toolchain:</emphasis> + A collection of software development + tools and utilities that allow you to develop software for targeted architectures. + This toolchain contains cross-compilers, linkers, and debuggers that are specific to + an architecture. + You can use the OpenEmbedded build system to build a cross-development toolchain + installer that when run installs the toolchain that contains the development tools you + need to cross-compile and test your software. + The Yocto Project ships with images that contain installers for + toolchains for supported architectures as well. + Sometimes this toolchain is referred to as the meta-toolchain.</para></listitem> + <listitem><para><emphasis>Image:</emphasis> An image is the result produced when + BitBake processes a given collection of recipes and related metadata. + Images are the binary output that run on specific hardware or QEMU + and for specific use cases. + For a list of the supported image types that the Yocto Project provides, see the + "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" + chapter in the Yocto Project Reference Manual.</para></listitem> + <listitem><para id='layer'><emphasis>Layer:</emphasis> A collection of recipes representing the core, + a BSP, or an application stack. + For a discussion on BSP Layers, see the + "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" + section in the Yocto Project Board Support Packages (BSP) Developer's Guide.</para></listitem> + <listitem><para id='metadata'><emphasis>Metadata:</emphasis> The files that BitBake parses when + building an image. + Metadata includes recipes, classes, and configuration files.</para></listitem> + <listitem><para id='oe-core'><emphasis>OE-Core:</emphasis> A core set of metadata originating + with OpenEmbedded (OE) that is shared between OE and the Yocto Project. + This metadata is found in the <filename>meta</filename> directory of the source + directory.</para></listitem> + <listitem><para><emphasis>Package:</emphasis> In the context of the Yocto Project, + this term refers to the packaged output from a baked recipe. + A package is generally the compiled binaries produced from the recipe's sources. + You ‘bake’ something by running it through BitBake.</para> + <para>It is worth noting that the term "package" can, in general, have subtle + meanings. For example, the packages refered to in the + "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" section are + compiled binaries that when installed add functionality to your Linux + distribution.</para> + <para>Another point worth noting is that historically within the Yocto Project, + recipes were referred to as packages - thus, the existence of several BitBake + variables that are seemingly mis-named, + (e.g. <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-PRINC'><filename>PRINC</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, and + <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>). + </para></listitem> + <listitem><para id='poky'><emphasis>Poky:</emphasis> The term "poky" can mean several things. + In its most general sense, it is an open-source project that was initially developed + by OpenedHand. With OpenedHand, poky was developed off of the existing OpenEmbedded + build system becoming a build system for embedded images. + After Intel Corporation acquired OpenedHand, the project poky became the basis for + the Yocto Project's build system. + Within the Yocto Project source repositories, poky exists as a separate Git repository + that can be cloned to yield a local copy on the host system. + Thus, "poky" can refer to the local copy of the Source Directory used to develop within + the Yocto Project.</para></listitem> + <listitem><para><emphasis>Recipe:</emphasis> A set of instructions for building packages. + A recipe describes where you get source code and which patches to apply. + Recipes describe dependencies for libraries or for other recipes, and they + also contain configuration and compilation options. + Recipes contain the logical unit of execution, the software/images to build, and + use the <filename>.bb</filename> file extension.</para></listitem> + <listitem> + <para id='source-directory'><emphasis>Source Directory:</emphasis> + This term refers to the directory structure created as a result of either downloading + and unpacking a Yocto Project release tarball or creating a local copy of + the <filename>poky</filename> Git repository + <filename>git://git.yoctoproject.org/poky</filename>. + Sometimes you might hear the term "poky directory" used to refer to this + directory structure. + <note> + The OpenEmbedded build system does not support file or directory names that + contain spaces. + Be sure that the Source Directory you use does not contain these types + of names. + </note></para> + <para>The Source Directory contains BitBake, Documentation, metadata and + other files that all support the Yocto Project. + Consequently, you must have the Source Directory in place on your development + system in order to do any development using the Yocto Project.</para> + + <para>For tarball expansion, the name of the top-level directory of the Source Directory + is derived from the Yocto Project release tarball. + For example, downloading and unpacking <filename>&YOCTO_POKY_TARBALL;</filename> + results in a Source Directory whose top-level folder is named + <filename>&YOCTO_POKY;</filename>. + If you create a local copy of the Git repository, then you can name the repository + anything you like. + Throughout much of the documentation, <filename>poky</filename> is used as the name of + the top-level folder of the local copy of the poky Git repository. + So, for example, cloning the <filename>poky</filename> Git repository results in a + local Git repository whose top-level folder is also named <filename>poky</filename>.</para> + + <para>It is important to understand the differences between the Source Directory created + by unpacking a released tarball as compared to cloning + <filename>git://git.yoctoproject.org/poky</filename>. + When you unpack a tarball, you have an exact copy of the files based on the time of + release - a fixed release point. + Any changes you make to your local files in the Source Directory are on top of the release. + On the other hand, when you clone the <filename>poky</filename> Git repository, you have an + active development repository. + In this case, any local changes you make to the Source Directory can be later applied + to active development branches of the upstream <filename>poky</filename> Git + repository.</para> + + <para>Finally, if you want to track a set of local changes while starting from the same point + as a release tarball, you can create a local Git branch that + reflects the exact copy of the files at the time of their release. + You do this by using Git tags that are part of the repository.</para> + + <para>For more information on concepts related to Git repositories, branches, and tags, + see the + "<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>" + section.</para></listitem> + <listitem><para><emphasis>Tasks:</emphasis> Arbitrary groups of software Recipes. + You simply use Tasks to hold recipes that, when built, usually accomplish a single task. + For example, a task could contain the recipes for a company’s proprietary or value-add software. + Or, the task could contain the recipes that enable graphics. + A task is really just another recipe. + Because task files are recipes, they end with the <filename>.bb</filename> filename + extension.</para></listitem> + <listitem><para><emphasis>Upstream:</emphasis> A reference to source code or repositories + that are not local to the development system but located in a master area that is controlled + by the maintainer of the source code. + For example, in order for a developer to work on a particular piece of code, they need to + first get a copy of it from an "upstream" source.</para></listitem> + </itemizedlist> + </para> +</section> + +<section id='licensing'> + <title>Licensing</title> + + <para> + Because open source projects are open to the public, they have different licensing structures in place. + License evolution for both Open Source and Free Software has an interesting history. + If you are interested in this history, you can find basic information here: + <itemizedlist> + <listitem><para><ulink url='http://en.wikipedia.org/wiki/Open-source_license'>Open source license history</ulink> + </para></listitem> + <listitem><para><ulink url='http://en.wikipedia.org/wiki/Free_software_license'>Free software license + history</ulink></para></listitem> + </itemizedlist> + </para> + + <para> + In general, the Yocto Project is broadly licensed under the Massachusetts Institute of Technology + (MIT) License. + MIT licensing permits the reuse of software within proprietary software as long as the + license is distributed with that software. + MIT is also compatible with the GNU General Public License (GPL). + Patches to the Yocto Project follow the upstream licensing scheme. + You can find information on the MIT license at + <ulink url='http://www.opensource.org/licenses/mit-license.php'>here</ulink>. + You can find information on the GNU GPL <ulink url='http://www.opensource.org/licenses/LGPL-3.0'> + here</ulink>. + </para> + + <para> + When you build an image using the Yocto Project, the build process uses a + known list of licenses to ensure compliance. + You can find this list in the Yocto Project files directory at + <filename>meta/files/common-licenses</filename>. + Once the build completes, the list of all licenses found and used during that build are + kept in the + <link linkend='build-directory'>Build Directory</link> at + <filename>tmp/deploy/images/licenses</filename>. + </para> + + <para> + If a module requires a license that is not in the base list, the build process + generates a warning during the build. + These tools make it easier for a developer to be certain of the licenses with which + their shipped products must comply. + However, even with these tools it is still up to the developer to resolve potential licensing issues. + </para> + + <para> + The base list of licenses used by the build process is a combination of the Software Package + Data Exchange (SPDX) list and the Open Source Initiative (OSI) projects. + <ulink url='http://spdx.org'>SPDX Group</ulink> is a working group of the Linux Foundation + that maintains a specification + for a standard format for communicating the components, licenses, and copyrights + associated with a software package. + <ulink url='http://opensource.org'>OSI</ulink> is a corporation dedicated to the Open Source + Definition and the effort for reviewing and approving licenses that are OSD-conformant. + </para> + + <para> + You can find a list of the combined SPDX and OSI licenses that the Yocto Project uses + <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/files/common-licenses'>here</ulink>. + This wiki page discusses the license infrastructure used by the Yocto Project. + </para> + + <para> + For information that can help you to maintain compliance with various open source licensing + during the lifecycle of a product created using the Yocto Project, see the + "<link linkend='maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</link>" section. + </para> +</section> + +<section id='git'> + <title>Git</title> + + <para> + The Yocto Project uses Git, which is a free, open source distributed version control system. + Git supports distributed development, non-linear development, and can handle large projects. + It is best that you have some fundamental understanding of how Git tracks projects and + how to work with Git if you are going to use Yocto Project for development. + This section provides a quick overview of how Git works and provides you with a summary + of some essential Git commands. + </para> + + <para> + For more information on Git, see + <ulink url='http://git-scm.com/documentation'></ulink>. + If you need to download Git, go to <ulink url='http://git-scm.com/download'></ulink>. + </para> + + <section id='repositories-tags-and-branches'> + <title>Repositories, Tags, and Branches</title> + + <para> + As mentioned earlier in section + "<link linkend='yocto-project-repositories'>Yocto Project Source Repositories</link>", + the Yocto Project maintains source repositories at + <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>. + If you look at this web-interface of the repositories, each item is a separate + Git repository. + </para> + + <para> + Git repositories use branching techniques that track content change (not files) + within a project (e.g. a new feature or updated documentation). + Creating a tree-like structure based on project divergence allows for excellent historical + information over the life of a project. + This methodology also allows for an environment in which you can do lots of + local experimentation on a project as you develop changes or new features. + </para> + + <para> + A Git repository represents all development efforts for a given project. + For example, the Git repository <filename>poky</filename> contains all changes + and developments for Poky over the course of its entire life. + That means that all changes that make up all releases are captured. + The repository maintains a complete history of changes. + </para> + + <para> + You can create a local copy of any repository by "cloning" it with the Git + <filename>clone</filename> command. + When you clone a Git repository, you end up with an identical copy of the + repository on your development system. + Once you have a local copy of a repository, you can take steps to develop locally. + For examples on how to clone Git repositories, see the section + "<link linkend='getting-setup'>Getting Set Up</link>" earlier in this manual. + </para> + + <para> + It is important to understand that Git tracks content change and not files. + Git uses "branches" to organize different development efforts. + For example, the <filename>poky</filename> repository has + <filename>bernard</filename>, + <filename>edison</filename>, <filename>denzil</filename>, <filename>danny</filename> + and <filename>master</filename> branches among others. + You can see all the branches by going to + <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and + clicking on the + <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/heads'>[...]</ulink></filename> + link beneath the "Branch" heading. + </para> + + <para> + Each of these branches represents a specific area of development. + The <filename>master</filename> branch represents the current or most recent + development. + All other branches represent off-shoots of the <filename>master</filename> + branch. + </para> + + <para> + When you create a local copy of a Git repository, the copy has the same set + of branches as the original. + This means you can use Git to create a local working area (also called a branch) + that tracks a specific development branch from the source Git repository. + in other words, you can define your local Git environment to work on any development + branch in the repository. + To help illustrate, here is a set of commands that creates a local copy of the + <filename>poky</filename> Git repository and then creates and checks out a local + Git branch that tracks the Yocto Project &DISTRO; Release (&DISTRO_NAME;) development: + <literallayout class='monospaced'> + $ cd ~ + $ git clone git://git.yoctoproject.org/poky + $ cd poky + $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME; + </literallayout> + In this example, the name of the top-level directory of your local Yocto Project + Files Git repository is <filename>poky</filename>, + and the name of the local working area (or local branch) you have created and checked + out is <filename>&DISTRO_NAME;</filename>. + The files in your repository now reflect the same files that are in the + <filename>&DISTRO_NAME;</filename> development branch of the Yocto Project's + <filename>poky</filename> repository. + It is important to understand that when you create and checkout a + local working branch based on a branch name, + your local environment matches the "tip" of that development branch + at the time you created your local branch, which could be + different than the files at the time of a similarly named release. + In other words, creating and checking out a local branch based on the + <filename>&DISTRO_NAME;</filename> branch name is not the same as + cloning and checking out the <filename>master</filename> branch. + Keep reading to see how you create a local snapshot of a Yocto Project Release. + </para> + + <para> + Git uses "tags" to mark specific changes in a repository. + Typically, a tag is used to mark a special point such as the final change + before a project is released. + You can see the tags used with the <filename>poky</filename> Git repository + by going to <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and + clicking on the + <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/tags'>[...]</ulink></filename> + link beneath the "Tag" heading. + </para> + + <para> + Some key tags are <filename>bernard-5.0</filename>, <filename>denzil-7.0</filename>, + and <filename>&DISTRO_NAME;-&POKYVERSION;</filename>. + These tags represent Yocto Project releases. + </para> + + <para> + When you create a local copy of the Git repository, you also have access to all the + tags. + Similar to branches, you can create and checkout a local working Git branch based + on a tag name. + When you do this, you get a snapshot of the Git repository that reflects + the state of the files when the change was made associated with that tag. + The most common use is to checkout a working branch that matches a specific + Yocto Project release. + Here is an example: + <literallayout class='monospaced'> + $ cd ~ + $ git clone git://git.yoctoproject.org/poky + $ cd poky + $ git checkout -b my-&DISTRO_NAME;-&POKYVERSION; &DISTRO_NAME;-&POKYVERSION; + </literallayout> + In this example, the name of the top-level directory of your local Yocto Project + Files Git repository is <filename>poky</filename>. + And, the name of the local branch you have created and checked out is + <filename>my-&DISTRO_NAME;-&POKYVERSION;</filename>. + The files in your repository now exactly match the Yocto Project &DISTRO; + Release tag (<filename>&DISTRO_NAME;-&POKYVERSION;</filename>). + It is important to understand that when you create and checkout a local + working branch based on a tag, your environment matches a specific point + in time and not a development branch. + </para> + </section> + + <section id='basic-commands'> + <title>Basic Commands</title> + + <para> + Git has an extensive set of commands that lets you manage changes and perform + collaboration over the life of a project. + Conveniently though, you can manage with a small set of basic operations and workflows + once you understand the basic philosophy behind Git. + You do not have to be an expert in Git to be functional. + A good place to look for instruction on a minimal set of Git commands is + <ulink url='http://git-scm.com/documentation'>here</ulink>. + If you need to download Git, you can do so + <ulink url='http://git-scm.com/download'>here</ulink>. + </para> + + <para> + If you don’t know much about Git, we suggest you educate + yourself by visiting the links previously mentioned. + </para> + + <para> + The following list briefly describes some basic Git operations as a way to get started. + As with any set of commands, this list (in most cases) simply shows the base command and + omits the many arguments they support. + See the Git documentation for complete descriptions and strategies on how to use these commands: + <itemizedlist> + <listitem><para><emphasis><filename>git init</filename>:</emphasis> Initializes an empty Git repository. + You cannot use Git commands unless you have a <filename>.git</filename> repository.</para></listitem> + <listitem><para><emphasis><filename>git clone</filename>:</emphasis> Creates a clone of a repository. + During collaboration, this command allows you to create a local repository that is on + equal footing with a fellow developer’s repository.</para></listitem> + <listitem><para><emphasis><filename>git add</filename>:</emphasis> Adds updated file contents + to the index that + Git uses to track changes. + You must add all files that have changed before you can commit them.</para></listitem> + <listitem><para><emphasis><filename>git commit</filename>:</emphasis> Creates a “commit” that documents + the changes you made. + Commits are used for historical purposes, for determining if a maintainer of a project + will allow the change, and for ultimately pushing the change from your local Git repository + into the project’s upstream (or master) repository.</para></listitem> + <listitem><para><emphasis><filename>git status</filename>:</emphasis> Reports any modified files that + possibly need to be added and committed.</para></listitem> + <listitem><para><emphasis><filename>git checkout <branch-name></filename>:</emphasis> Changes + your working branch. + This command is analogous to “cd”.</para></listitem> + <listitem><para><emphasis><filename>git checkout –b <working-branch></filename>:</emphasis> Creates + a working branch on your local machine where you can isolate work. + It is a good idea to use local branches when adding specific features or changes. + This way if you don’t like what you have done you can easily get rid of the work.</para></listitem> + <listitem><para><emphasis><filename>git branch</filename>:</emphasis> Reports + existing local branches and + tells you the branch in which you are currently working.</para></listitem> + <listitem><para><emphasis><filename>git branch -D <branch-name></filename>:</emphasis> + Deletes an existing local branch. + You need to be in a local branch other than the one you are deleting + in order to delete <filename><branch-name></filename>.</para></listitem> + <listitem><para><emphasis><filename>git pull</filename>:</emphasis> Retrieves information + from an upstream Git + repository and places it in your local Git repository. + You use this command to make sure you are synchronized with the repository + from which you are basing changes (.e.g. the master branch).</para></listitem> + <listitem><para><emphasis><filename>git push</filename>:</emphasis> Sends all your local changes you + have committed to an upstream Git repository (e.g. a contribution repository). + The maintainer of the project draws from these repositories when adding your changes to the + project’s master repository.</para></listitem> + <listitem><para><emphasis><filename>git merge</filename>:</emphasis> Combines or adds changes from one + local branch of your repository with another branch. + When you create a local Git repository, the default branch is named “master”. + A typical workflow is to create a temporary branch for isolated work, make and commit your + changes, switch to your local master branch, merge the changes from the temporary branch into the + local master branch, and then delete the temporary branch.</para></listitem> + <listitem><para><emphasis><filename>git cherry-pick</filename>:</emphasis> Choose and apply specific + commits from one branch into another branch. + There are times when you might not be able to merge all the changes in one branch with + another but need to pick out certain ones.</para></listitem> + <listitem><para><emphasis><filename>gitk</filename>:</emphasis> Provides a GUI view of the branches + and changes in your local Git repository. + This command is a good way to graphically see where things have diverged in your + local repository.</para></listitem> + <listitem><para><emphasis><filename>git log</filename>:</emphasis> Reports a history of your changes to the + repository.</para></listitem> + <listitem><para><emphasis><filename>git diff</filename>:</emphasis> Displays line-by-line differences + between your local working files and the same files in the upstream Git repository that your + branch currently tracks.</para></listitem> + </itemizedlist> + </para> + </section> +</section> + +<section id='workflows'> + <title>Workflows</title> + + <para> + This section provides some overview on workflows using Git. + In particular, the information covers basic practices that describe roles and actions in a + collaborative development environment. + Again, if you are familiar with this type of development environment, you might want to just + skip this section. + </para> + + <para> + The Yocto Project files are maintained using Git in a "master" branch whose Git history + tracks every change and whose structure provides branches for all diverging functionality. + Although there is no need to use Git, many open source projects do so. + For the Yocto Project, a key individual called the "maintainer" is responsible for the "master" + branch of the Git repository. + The "master" branch is the “upstream” repository where the final builds of the project occur. + The maintainer is responsible for allowing changes in from other developers and for + organizing the underlying branch structure to reflect release strategies and so forth. + <note>You can see who is the maintainer for Yocto Project files by examining the + <filename>maintainers.inc</filename> file in the Yocto Project + <filename>meta-yocto/conf/distro/include</filename> directory.</note> + </para> + + <para> + The project also has contribution repositories known as “contrib” areas. + These areas temporarily hold changes to the project that have been submitted or committed + by the Yocto Project development team and by community members that contribute to the project. + The maintainer determines if the changes are qualified to be moved from the "contrib" areas + into the "master" branch of the Git repository. + </para> + + <para> + Developers (including contributing community members) create and maintain cloned repositories + of the upstream "master" branch. + These repositories are local to their development platforms and are used to develop changes. + When a developer is satisfied with a particular feature or change, they “push” the changes + to the appropriate "contrib" repository. + </para> + + <para> + Developers are responsible for keeping their local repository up-to-date with "master". + They are also responsible for straightening out any conflicts that might arise within files + that are being worked on simultaneously by more than one person. + All this work is done locally on the developer’s machine before anything is pushed to a + "contrib" area and examined at the maintainer’s level. + </para> + + <para> + A somewhat formal method exists by which developers commit changes and push them into the + "contrib" area and subsequently request that the maintainer include them into "master" + This process is called “submitting a patch” or “submitting a change.” + For information on submitting patches and changes, see the + "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" section. + </para> + + <para> + To summarize the environment: we have a single point of entry for changes into the project’s + "master" branch of the Git repository, which is controlled by the project’s maintainer. + And, we have a set of developers who independently develop, test, and submit changes + to "contrib" areas for the maintainer to examine. + The maintainer then chooses which changes are going to become a permanent part of the project. + </para> + + <para> + <imagedata fileref="figures/git-workflow.png" width="6in" depth="3in" align="left" scalefit="1" /> + </para> + + <para> + While each development environment is unique, there are some best practices or methods + that help development run smoothly. + The following list describes some of these practices. + For more information about Git workflows, see the workflow topics in the + <ulink url='http://book.git-scm.com'>Git Community Book</ulink>. + <itemizedlist> + <listitem><para><emphasis>Make Small Changes:</emphasis> It is best to keep the changes you commit + small as compared to bundling many disparate changes into a single commit. + This practice not only keeps things manageable but also allows the maintainer + to more easily include or refuse changes.</para> + <para>It is also good practice to leave the repository in a state that allows you to + still successfully build your project. In other words, do not commit half of a feature, + then add the other half in a separate, later commit. + Each commit should take you from one buildable project state to another + buildable state.</para></listitem> + <listitem><para><emphasis>Use Branches Liberally:</emphasis> It is very easy to create, use, and + delete local branches in your working Git repository. + You can name these branches anything you like. + It is helpful to give them names associated with the particular feature or change + on which you are working. + Once you are done with a feature or change, simply discard the branch.</para></listitem> + <listitem><para><emphasis>Merge Changes:</emphasis> The <filename>git merge</filename> + command allows you to take the + changes from one branch and fold them into another branch. + This process is especially helpful when more than a single developer might be working + on different parts of the same feature. + Merging changes also automatically identifies any collisions or “conflicts” + that might happen as a result of the same lines of code being altered by two different + developers.</para></listitem> + <listitem><para><emphasis>Manage Branches:</emphasis> Because branches are easy to use, you should + use a system where branches indicate varying levels of code readiness. + For example, you can have a “work” branch to develop in, a “test” branch where the code or + change is tested, a “stage” branch where changes are ready to be committed, and so forth. + As your project develops, you can merge code across the branches to reflect ever-increasing + stable states of the development.</para></listitem> + <listitem><para><emphasis>Use Push and Pull:</emphasis> The push-pull workflow is based on the + concept of developers “pushing” local commits to a remote repository, which is + usually a contribution repository. + This workflow is also based on developers “pulling” known states of the project down into their + local development repositories. + The workflow easily allows you to pull changes submitted by other developers from the + upstream repository into your work area ensuring that you have the most recent software + on which to develop. + The Yocto Project has two scripts named <filename>create-pull-request</filename> and + <filename>send-pull-request</filename> that ship with the release to facilitate this + workflow. + You can find these scripts in the local Yocto Project files Git repository in + the <filename>scripts</filename> directory.</para> + <para>You can find more information on these scripts in the + "<link linkend='pushing-a-change-upstream'>Using + Scripts to Push a Change Upstream and Request a Pull</link>" section. + </para></listitem> + <listitem><para><emphasis>Patch Workflow:</emphasis> This workflow allows you to notify the + maintainer through an email that you have a change (or patch) you would like considered + for the "master" branch of the Git repository. + To send this type of change you format the patch and then send the email using the Git commands + <filename>git format-patch</filename> and <filename>git send-email</filename>. + You can find information on how to submit changes + later in this chapter.</para></listitem> + </itemizedlist> + </para> +</section> + +<section id='tracking-bugs'> + <title>Tracking Bugs</title> + + <para> + The Yocto Project uses its own implementation of + <ulink url='http://www.bugzilla.org/about/'>Bugzilla</ulink> to track bugs. + Implementations of Bugzilla work well for group development because they track bugs and code + changes, can be used to communicate changes and problems with developers, can be used to + submit and review patches, and can be used to manage quality assurance. + The home page for the Yocto Project implementation of Bugzilla is + <ulink url='&YOCTO_BUGZILLA_URL;'>&YOCTO_BUGZILLA_URL;</ulink>. + </para> + + <para> + Sometimes it is helpful to submit, investigate, or track a bug against the Yocto Project itself + such as when discovering an issue with some component of the build system that acts contrary + to the documentation or your expectations. + Following is the general procedure for submitting a new bug using the Yocto Project + Bugzilla. + You can find more information on defect management, bug tracking, and feature request + processes all accomplished through the Yocto Project Bugzilla on the wiki page + <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>here</ulink>. + <orderedlist> + <listitem><para>Always use the Yocto Project implementation of Bugzilla to submit + a bug.</para></listitem> + <listitem><para>When submitting a new bug, be sure to choose the appropriate + Classification, Product, and Component for which the issue was found. + Defects for Yocto Project fall into one of six classifications: Yocto Project + Components, Infrastructure, Build System & Metadata, Documentation, + QA/Testing, and Runtime. + Each of these Classifications break down into multiple Products and, in some + cases, multiple Components.</para></listitem> + <listitem><para>Use the bug form to choose the correct Hardware and Architecture + for which the bug applies.</para></listitem> + <listitem><para>Indicate the Yocto Project version you were using when the issue + occurred.</para></listitem> + <listitem><para>Be sure to indicate the Severity of the bug. + Severity communicates how the bug impacted your work.</para></listitem> + <listitem><para>Provide a brief summary of the issue. + Try to limit your summary to just a line or two and be sure to capture the + essence of the issue.</para></listitem> + <listitem><para>Provide a detailed description of the issue. + You should provide as much detail as you can about the context, behavior, output, + and so forth that surround the issue. + You can even attach supporting files for output or log by using the "Add an attachment" + button.</para></listitem> + <listitem><para>Submit the bug by clicking the "Submit Bug" button.</para></listitem> + </orderedlist> + </para> +</section> + +<section id='how-to-submit-a-change'> + <title>How to Submit a Change</title> + + <para> + Contributions to the Yocto Project and OpenEmbedded are very welcome. + Because the system is extremely configurable and flexible, we recognize that developers + will want to extend, configure or optimize it for their specific uses. + You should send patches to the appropriate mailing list so that they + can be reviewed and merged by the appropriate maintainer. + For a list of the Yocto Project and related mailing lists, see the + "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" section in + the Yocto Project Reference Manual. + </para> + + <para> + The following is some guidance on which mailing list to use for what type of change: + <itemizedlist> + <listitem><para>For changes to the core metadata, send your patch to the + <ulink url='&OE_LISTS_URL;/listinfo/openembedded-core'>openembedded-core</ulink> mailing list. + For example, a change to anything under the <filename>meta</filename> or + <filename>scripts</filename> directories + should be sent to this mailing list.</para></listitem> + <listitem><para>For changes to BitBake (anything under the <filename>bitbake</filename> + directory), send your patch to the + <ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'>bitbake-devel</ulink> mailing list.</para></listitem> + <listitem><para>For changes to <filename>meta-yocto</filename>, send your patch to the + <ulink url='&YOCTO_LISTS_URL;/listinfo/poky'>poky</ulink> mailing list.</para></listitem> + <listitem><para>For changes to other layers hosted on + <filename>yoctoproject.org</filename> (unless the + layer's documentation specifies otherwise), tools, and Yocto Project + documentation, use the + <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> mailing list.</para></listitem> + <listitem><para>For additional recipes that do not fit into the core metadata, + you should determine which layer the recipe should go into and submit the + change in the manner recommended by the documentation (e.g. README) supplied + with the layer. If in doubt, please ask on the + <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> or + <ulink url='&OE_LISTS_URL;/listinfo/openembedded-devel'>openembedded-devel</ulink> + mailing lists.</para></listitem> + </itemizedlist> + </para> + + <para> + When you send a patch, be sure to include a "Signed-off-by:" + line in the same style as required by the Linux kernel. + Adding this line signifies that you, the submitter, have agreed to the Developer's Certificate of Origin 1.1 + as follows: + <literallayout class='monospaced'> + Developer's Certificate of Origin 1.1 + + By making a contribution to this project, I certify that: + + (a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + + (b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + + (c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + + (d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. + </literallayout> + </para> + + <para> + In a collaborative environment, it is necessary to have some sort of standard + or method through which you submit changes. + Otherwise, things could get quite chaotic. + One general practice to follow is to make small, controlled changes. + Keeping changes small and isolated aids review, makes merging/rebasing easier + and keeps the change history clean when anyone needs to refer to it in future. + </para> + + <para> + When you make a commit, you must follow certain standards established by the + OpenEmbedded and Yocto Project development teams. + For each commit, you must provide a single-line summary of the change and you + should almost always provide a more detailed description of what you did (i.e. + the body of the commit message). + The only exceptions for not providing a detailed description would be if your + change is a simple, self-explanatory change that needs no further description + beyond the summary. + Here are the guidelines for composing a commit message: + <itemizedlist> + <listitem><para>Provide a single-line, short summary of the change. + This summary is typically viewable in the "shortlist" of changes. + Thus, providing something short and descriptive that gives the reader + a summary of the change is useful when viewing a list of many commits. + This should be prefixed by the recipe name (if changing a recipe), or + else the short form path to the file being changed. + </para></listitem> + <listitem><para>For the body of the commit message, provide detailed information + that describes what you changed, why you made the change, and the approach + you used. It may also be helpful if you mention how you tested the change. + Provide as much detail as you can in the body of the commit message. + </para></listitem> + <listitem><para>If the change addresses a specific bug or issue that is + associated with a bug-tracking ID, include a reference to that ID in + your detailed description. + For example, the Yocto Project uses a specific convention for bug + references - any commit that addresses a specific bug should include the + bug ID in the description (typically at the beginning) as follows: + <literallayout class='monospaced'> + [YOCTO #<bug-id>] + + <detailed description of change> + </literallayout></para></listitem> + Where <bug-id> is replaced with the specific bug ID from the + Yocto Project Bugzilla instance. + </itemizedlist> + </para> + + <para> + You can find more guidance on creating well-formed commit messages at this OpenEmbedded + wiki page: + <ulink url='&OE_HOME_URL;/wiki/Commit_Patch_Message_Guidelines'></ulink>. + </para> + + <para> + Following are general instructions for both pushing changes upstream and for submitting + changes as patches. + </para> + + <section id='pushing-a-change-upstream'> + <title>Using Scripts to Push a Change Upstream and Request a Pull</title> + + <para> + The basic flow for pushing a change to an upstream "contrib" Git repository is as follows: + <itemizedlist> + <listitem><para>Make your changes in your local Git repository.</para></listitem> + <listitem><para>Stage your changes by using the <filename>git add</filename> + command on each file you changed.</para></listitem> + <listitem><para>Commit the change by using the <filename>git commit</filename> + command and push it to the "contrib" repository. + Be sure to provide a commit message that follows the project’s commit message standards + as described earlier.</para></listitem> + <listitem><para>Notify the maintainer that you have pushed a change by making a pull + request. + The Yocto Project provides two scripts that conveniently let you generate and send + pull requests to the Yocto Project. + These scripts are <filename>create-pull-request</filename> and + <filename>send-pull-request</filename>. + You can find these scripts in the <filename>scripts</filename> directory + within the <link linkend='source-directory'>Source Directory</link>.</para> + <para>Using these scripts correctly formats the requests without introducing any + whitespace or HTML formatting. + The maintainer that receives your patches needs to be able to save and apply them + directly from your emails. + Using these scripts is the preferred method for sending patches.</para> + <para>For help on using these scripts, simply provide the + <filename>-h</filename> argument as follows: + <literallayout class='monospaced'> + $ ~/poky/scripts/create-pull-request -h + $ ~/poky/scripts/send-pull-request -h + </literallayout></para></listitem> + </itemizedlist> + </para> + + <para> + You can find general Git information on how to push a change upstream in the + <ulink url='http://book.git-scm.com/3_distributed_workflows.html'>Git Community Book</ulink>. + </para> + </section> + + <section id='submitting-a-patch'> + <title>Using Email to Submit a Patch</title> + + <para> + You can submit patches without using the <filename>create-pull-request</filename> and + <filename>send-pull-request</filename> scripts described in the previous section. + Keep in mind, the preferred method is to use the scripts, however. + </para> + + <para> + Depending on the components changed, you need to submit the email to a specific + mailing list. + For some guidance on which mailing list to use, see the list in the + "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" section + earlier in this manual. + For a description of the available mailing lists, see + "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>" + section in the Yocto Project Reference Manual. + </para> + + <para> + Here is the general procedure on how to submit a patch through email without using the + scripts: + <itemizedlist> + <listitem><para>Make your changes in your local Git repository.</para></listitem> + <listitem><para>Stage your changes by using the <filename>git add</filename> + command on each file you changed.</para></listitem> + <listitem><para>Commit the change by using the + <filename>git commit --signoff</filename> command. + Using the <filename>--signoff</filename> option identifies you as the person + making the change and also satisfies the Developer's Certificate of + Origin (DCO) shown earlier.</para> + <para>When you form a commit you must follow certain standards established by the + Yocto Project development team. + See the earlier section + "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" + for Yocto Project commit message standards.</para></listitem> + <listitem><para>Format the commit into an email message. + To format commits, use the <filename>git format-patch</filename> command. + When you provide the command, you must include a revision list or a number of patches + as part of the command. + For example, these two commands each take the most recent single commit and + format it as an email message in the current directory: + <literallayout class='monospaced'> + $ git format-patch -1 + $ git format-patch HEAD~ + </literallayout></para> + <para>After the command is run, the current directory contains a + numbered <filename>.patch</filename> file for the commit.</para> + <para>If you provide several commits as part of the command, + the <filename>git format-patch</filename> command produces a numbered + series of files in the current directory – one for each commit. + If you have more than one patch, you should also use the + <filename>--cover</filename> option with the command, which generates a + cover letter as the first "patch" in the series. + You can then edit the cover letter to provide a description for + the series of patches. + For information on the <filename>git format-patch</filename> command, + see <filename>GIT_FORMAT_PATCH(1)</filename> displayed using the + <filename>man git-format-patch</filename> command.</para> + <note>If you are or will be a frequent contributor to the Yocto Project + or to OpenEmbedded, you might consider requesting a contrib area and the + necessary associated rights.</note></listitem> + <listitem><para>Import the files into your mail client by using the + <filename>git send-email</filename> command. + <note>In order to use <filename>git send-email</filename>, you must have the + the proper Git packages installed. + For Ubuntu and Fedora the package is <filename>git-email</filename>.</note></para> + <para>The <filename>git send-email</filename> command sends email by using a local + or remote Mail Transport Agent (MTA) such as + <filename>msmtp</filename>, <filename>sendmail</filename>, or through a direct + <filename>smtp</filename> configuration in your Git <filename>config</filename> + file. + If you are submitting patches through email only, it is very important + that you submit them without any whitespace or HTML formatting that + either you or your mailer introduces. + The maintainer that receives your patches needs to be able to save and + apply them directly from your emails. + A good way to verify that what you are sending will be applicable by the + maintainer is to do a dry run and send them to yourself and then + save and apply them as the maintainer would.</para> + <para>The <filename>git send-email</filename> command is the preferred method + for sending your patches since there is no risk of compromising whitespace + in the body of the message, which can occur when you use your own mail client. + The command also has several options that let you + specify recipients and perform further editing of the email message. + For information on how to use the <filename>git send-email</filename> command, + use the <filename>man git-send-email</filename> command.</para></listitem> + </itemizedlist> + </para> + </section> +</section> +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/documentation/profile-manual/profile-manual.xml b/documentation/profile-manual/profile-manual.xml new file mode 100644 index 0000000..5eea2e2 --- /dev/null +++ b/documentation/profile-manual/profile-manual.xml @@ -0,0 +1,91 @@ +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<book id='dev-manual' lang='en' + xmlns:xi="http://www.w3.org/2003/XInclude" + xmlns="http://docbook.org/ns/docbook" + > + <bookinfo> + + <mediaobject> + <imageobject> + <imagedata fileref='figures/dev-title.png' + format='SVG' + align='left' scalefit='1' width='100%'/> + </imageobject> + </mediaobject> + + <title></title> + + <authorgroup> + <author> + <firstname>Scott</firstname> <surname>Rifenbark</surname> + <affiliation> + <orgname>Intel Corporation</orgname> + </affiliation> + <email>scott.m.rifenbark@intel.com</email> + </author> + </authorgroup> + + <revhistory> + <revision> + <revnumber>1.1</revnumber> + <date>6 October 2011</date> + <revremark>The initial document released with the Yocto Project 1.1 Release.</revremark> + </revision> + <revision> + <revnumber>1.2</revnumber> + <date>April 2012</date> + <revremark>Released with the Yocto Project 1.2 Release.</revremark> + </revision> + <revision> + <revnumber>1.3</revnumber> + <date>October 2012</date> + <revremark>Released with the Yocto Project 1.3 Release.</revremark> + </revision> + <revision> + <revnumber>1.4</revnumber> + <date>Sometime in 2013</date> + <revremark>Released with the Yocto Project 1.4 Release.</revremark> + </revision> + </revhistory> + + <copyright> + <year>©RIGHT_YEAR;</year> + <holder>Linux Foundation</holder> + </copyright> + + <legalnotice> + <para> + Permission is granted to copy, distribute and/or modify this document under + the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/"> + Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by + Creative Commons. + </para> + + <note> + Due to production processes, there could be differences between the Yocto Project + documentation bundled in the release tarball and the + <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink> on + the <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website. + For the latest version of this manual, see the manual on the website. + </note> + </legalnotice> + + </bookinfo> + + <xi:include href="dev-manual-intro.xml"/> + + <xi:include href="dev-manual-start.xml"/> + + <xi:include href="dev-manual-newbie.xml"/> + + <xi:include href="dev-manual-model.xml"/> + + <xi:include href="dev-manual-common-tasks.xml"/> + +</book> +<!-- +vim: expandtab tw=80 ts=4 +--> |
