sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

documentation/dev-manual: Scrub for Yocto Project term 

I have replaced the term "Yocto Project" with more appropriate terms
where possible.

(From yocto-docs rev: 622ef9a2b4897ecd151b641b43d7706ab673c989)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark 2012-07-02 09:59:11 -07:00 committed by Richard Purdie
parent 7606c30c19
commit 85673e5466
6 changed files with 331 additions and 399 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

173
documentation/dev-manual/dev-manual-common-tasks.xml
View File

@ -7,7 +7,7 @@
<title>Common Tasks</title> <title>Common Tasks</title>
<para> <para>
This chapter describes standard tasks such as adding new This chapter describes standard tasks such as adding new
software packages, extending or customizing images, and porting the Yocto Project to software packages, extending or customizing images, and porting work to
new hardware (adding a new machine). new hardware (adding a new machine).
The chapter also describes how to combine multiple The chapter also describes how to combine multiple
versions of library files into a single image, how to handle a package name alias, and versions of library files into a single image, how to handle a package name alias, and
@ -18,7 +18,7 @@
<title>Understanding and Creating Layers</title> <title>Understanding and Creating Layers</title>
<para> <para>
The Yocto Project build system supports organizing <link linkend='metadata'>metadata</link> The OpenEmbedded build system supports organizing <link linkend='metadata'>metadata</link>
into multiple layers. into multiple layers.
Layers allow you to isolate different types of customizations from each other. Layers allow you to isolate different types of customizations from each other.
You might find it tempting to keep everything in one layer when working on a single project. You might find it tempting to keep everything in one layer when working on a single project.
@ -43,13 +43,13 @@
</para> </para>
<section id='yocto-project-layers'> <section id='yocto-project-layers'>
<title>Yocto Project Layers</title> <title>Layers</title>
<para> <para>
The Yocto Project contains several layers right out of the box. The source directory contains several layers right out of the box.
You can easily identify a layer in the Yocto Project by the name of its folder. You can easily identify a layer in the source directory by its folder name.
Folders that are layers begin with the string <filename>meta</filename>. Folders that are layers begin with the string <filename>meta</filename>.
For example, when you set up the <link linkend='yocto-project-files'>Yocto Project Files</link> For example, when you set up the <link linkend='source-directory'>source directory</link>
structure, you will see several layers: <filename>meta</filename>, <filename>meta-demoapps</filename>, structure, you will see several layers: <filename>meta</filename>, <filename>meta-demoapps</filename>,
<filename>meta-skeleton</filename>, and <filename>meta-yocto</filename>. <filename>meta-skeleton</filename>, and <filename>meta-yocto</filename>.
Each of these folders is a layer. Each of these folders is a layer.
@ -69,7 +69,7 @@
<title>Creating Your Own Layer</title> <title>Creating Your Own Layer</title>
<para> <para>
It is very easy to create your own layer to use with the Yocto Project. It is very easy to create your own layer to use with the OpenEmbedded build system.
Follow these general steps to create your layer: Follow these general steps to create your layer:
<orderedlist> <orderedlist>
<listitem><para><emphasis>Check Existing Layers:</emphasis> Before creating a new layer, <listitem><para><emphasis>Check Existing Layers:</emphasis> Before creating a new layer,
@ -170,13 +170,14 @@
If this is the case, you need to address that deficiency instead of overlaying If this is the case, you need to address that deficiency instead of overlaying
the include file. the include file.
For example, consider how Qt 4 database support plugins are configured. For example, consider how Qt 4 database support plugins are configured.
The Yocto Project does not have MySQL or PostgreSQL, however OpenEmbedded's The source directory does not have
MySQL or PostgreSQL, however OpenEmbedded's
layer <filename>meta-oe</filename> does. layer <filename>meta-oe</filename> does.
Consequently, <filename>meta-oe</filename> uses <filename>.bbappend</filename> Consequently, <filename>meta-oe</filename> uses <filename>.bbappend</filename>
files to modify the <filename>QT_SQL_DRIVER_FLAGS</filename> variable to enable files to modify the <filename>QT_SQL_DRIVER_FLAGS</filename> variable to enable
the appropriate plugins. the appropriate plugins.
This variable was added to the <filename>qt4.inc</filename> include file in This variable was added to the <filename>qt4.inc</filename> include file in
The Yocto Project specifically to allow the <filename>meta-oe</filename> layer the source directory specifically to allow the <filename>meta-oe</filename> layer
to be able to control which plugins are built.</para></listitem> to be able to control which plugins are built.</para></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
@ -187,10 +188,10 @@
<listitem><para>Store custom layers in a Git repository that uses the <listitem><para>Store custom layers in a Git repository that uses the
<filename>meta-&lt;layer_name&gt;</filename> format.</para></listitem> <filename>meta-&lt;layer_name&gt;</filename> format.</para></listitem>
<listitem><para>Clone the repository alongside other <filename>meta</filename> <listitem><para>Clone the repository alongside other <filename>meta</filename>
directories in directories in the
<link linkend='yocto-project-files'>Yocto Project Files</link>.</para></listitem> <link linkend='source-directory'>source directory</link>.</para></listitem>
</itemizedlist> </itemizedlist>
Following these recommendations keeps your Yocto Project files area and Following these recommendations keeps your source directory and
its configuration entirely inside the Yocto Project's core base. its configuration entirely inside the Yocto Project's core base.
</para> </para>
</section> </section>
@ -199,11 +200,11 @@
<title>Enabling Your Layer</title> <title>Enabling Your Layer</title>
<para> <para>
Before the Yocto Project build system can use your new layer, you need to enable it. Before the OpenEmbedded build system can use your new layer, you need to enable it.
To enable your layer, simply add your layer's path to the To enable your layer, simply add your layer's path to the
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'>BBLAYERS</ulink></filename> <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'>BBLAYERS</ulink></filename>
variable in your <filename>conf/bblayers.conf</filename> file, which is found in the variable in your <filename>conf/bblayers.conf</filename> file, which is found in the
<link linkend='yocto-project-build-directory'>Yocto Project Build Directory</link>. <link linkend='build-directory'>build directory</link>.
The following example shows how to enable a layer named <filename>meta-mylayer</filename>: The following example shows how to enable a layer named <filename>meta-mylayer</filename>:
<literallayout class='monospaced'> <literallayout class='monospaced'>
LCONF_VERSION = "1" LCONF_VERSION = "1"
@ -222,8 +223,8 @@
<filename>BBLAYERS</filename> variable within the <filename>conf/bblayers.conf</filename> <filename>BBLAYERS</filename> variable within the <filename>conf/bblayers.conf</filename>
file. file.
During the processing of each <filename>conf/layer.conf</filename> file, BitBake adds the During the processing of each <filename>conf/layer.conf</filename> file, BitBake adds the
recipes, classes and configurations contained within the particular layer to the Yocto recipes, classes and configurations contained within the particular layer to the source
Project. directory.
</para> </para>
</section> </section>
@ -267,7 +268,7 @@
<para> <para>
As an example, consider the main formfactor recipe and a corresponding formfactor As an example, consider the main formfactor recipe and a corresponding formfactor
append file both from the append file both from the
<link linkend='yocto-project-files'>Yocto Project Files</link>. <link linkend='source-directory'>source directory</link>.
Here is the main formfactor recipe, which is named <filename>formfactor_0.0.bb</filename> and Here is the main formfactor recipe, which is named <filename>formfactor_0.0.bb</filename> and
located in the meta layer at <filename>meta/recipes-bsp/formfactor</filename>: located in the meta layer at <filename>meta/recipes-bsp/formfactor</filename>:
<literallayout class='monospaced'> <literallayout class='monospaced'>
@ -450,7 +451,7 @@
<title>Customizing Images</title> <title>Customizing Images</title>
<para> <para>
You can customize Yocto Project images to satisfy particular requirements. You can customize images to satisfy particular requirements.
This section describes several methods and provides guidelines for each. This section describes several methods and provides guidelines for each.
</para> </para>
@ -552,13 +553,11 @@
<filename>EXTRA_IMAGE_FEATURES</filename></title> <filename>EXTRA_IMAGE_FEATURES</filename></title>
<para> <para>
Ultimately users might want to add extra image features to the set used by Ultimately users might want to add extra image features to the set by using the
Yocto Project with the
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'>IMAGE_FEATURES</ulink></filename> <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'>IMAGE_FEATURES</ulink></filename>
variable. variable.
To create these features, the best reference is To create these features, the best reference is
<filename>meta/classes/core-image.bbclass</filename>, which shows how the <filename>meta/classes/core-image.bbclass</filename>, which shows how to achieve this.
Yocto Project achieves this.
In summary, the file looks at the contents of the In summary, the file looks at the contents of the
<filename>IMAGE_FEATURES</filename> <filename>IMAGE_FEATURES</filename>
variable and then maps that into a set of tasks or packages. variable and then maps that into a set of tasks or packages.
@ -569,8 +568,8 @@
with specialized image <filename>.bb</filename> files. with specialized image <filename>.bb</filename> files.
You can also add more features by configuring the You can also add more features by configuring the
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</ulink></filename> <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</ulink></filename>
variable in the <filename>local.conf</filename> file found in the Yocto Project variable in the <filename>local.conf</filename> file found in the source directory
files located in the build directory. located in the build directory.
</para> </para>
<para> <para>
@ -648,7 +647,7 @@
<title>Adding a Package</title> <title>Adding a Package</title>
<para> <para>
To add a package into the Yocto Project you need to write a recipe for it. To add a package you need to write a recipe for it.
Writing a recipe means creating a <filename>.bb</filename> file that sets some Writing a recipe means creating a <filename>.bb</filename> file that sets some
variables. variables.
For information on variables that are useful for recipes and for information about recipe naming For information on variables that are useful for recipes and for information about recipe naming
@ -662,7 +661,7 @@
whether someone else has written one already. whether someone else has written one already.
OpenEmbedded is a good place to look as it has a wider scope and range of packages. OpenEmbedded is a good place to look as it has a wider scope and range of packages.
Because the Yocto Project aims to be compatible with OpenEmbedded, most recipes Because the Yocto Project aims to be compatible with OpenEmbedded, most recipes
you find there should work in Yocto Project. you find there should work for you.
</para> </para>
<para> <para>
@ -1001,53 +1000,7 @@
</section> </section>
<section id="platdev-newmachine"> <section id="platdev-newmachine">
<title>Porting the Yocto Project to a New Machine</title> <title>Adding a New Machine</title>
<!--
WRITER NOTES:
I had this chat with Richard:
scottrif: Terminology question: We speak of "New Machines" or "Adding a New Machine"
in YP. Are "Machines" restricted to architectures? In poky/meta/conf/machine we have .conf
files for the five architectures. What exactly does the term "Machine" mean?
RP: no, each architecture has multiple different machines. A "machine" can correspond
to a particular reference board or hardware product
we just have one reference machine per architecture
We're a little vague sometimes as "machine" can refer to either an individual platform,
or in some cases a set of different platforms with common structure
(e.g. netbooks)
scottrif: So our reference machines we supply are the five qemu* machines?
RP: in oe-core, plus one "real" target in meta-yocto
(per arch)
scottrif: I see four in meta-yocto/conf/machine. Shouldn't there be five if there is one
"real" target per architecture?
RP: yes, we don't have one for x86_64 :/
scottrif: I think it is a bit difficult to map our four poky/meta-yocto/conf/machines to one of our
five architectures. Some have key words in there that identify the architecture but
beagleboard and atom-pc don't.
We have a section that describes adding a Machine Configuration file to Yocto and
it states that TARGET_ARCH is one of the most important variables that need to be
set in the .conf file. The four I am looking at don't have that variable.
RP: That has changed a little now. You need to include the appropriate tune file
which will set it for you
People had a tendency not to set all the right pieces so it got abstracted
scottrif: Got it. I see them in poky/meta/conf/machine/include.
SOME CONCLUSIONS:
I need to define the term machine. It is confusing. Then, this section needs to be cleared up
so that there are some definite steps on how to do this. I need more detail here.
-->
<para> <para>
Adding a new machine to the Yocto Project is a straightforward process. Adding a new machine to the Yocto Project is a straightforward process.
@ -1060,7 +1013,7 @@ so that there are some definite steps on how to do this. I need more detail her
</para> </para>
<para> <para>
For a complete example that shows how to add a new machine to the Yocto Project, For a complete example that shows how to add a new machine,
see the see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-bsp-appendix'>BSP Development Example</ulink>" "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-bsp-appendix'>BSP Development Example</ulink>"
in Appendix A. in Appendix A.
@ -1072,7 +1025,8 @@ so that there are some definite steps on how to do this. I need more detail her
<para> <para>
To add a machine configuration you need to add a <filename>.conf</filename> file To add a machine configuration you need to add a <filename>.conf</filename> file
with details of the device being added to the <filename>conf/machine/</filename> file. with details of the device being added to the <filename>conf/machine/</filename> file.
The name of the file determines the name the Yocto Project uses to reference the new machine. The name of the file determines the name the OpenEmbedded build system
uses to reference the new machine.
</para> </para>
<para> <para>
@ -1110,12 +1064,12 @@ so that there are some definite steps on how to do this. I need more detail her
<title>Adding a Kernel for the Machine</title> <title>Adding a Kernel for the Machine</title>
<para> <para>
The Yocto Project needs to be able to build a kernel for the machine. The OpenEmbedded build system needs to be able to build a kernel for the machine.
You need to either create a new kernel recipe for this machine, or extend an You need to either create a new kernel recipe for this machine, or extend an
existing recipe. existing recipe.
You can find several kernel examples in the You can find several kernel examples in the
Yocto Project file's <filename>meta/recipes-kernel/linux</filename> source directory at <filename>meta/recipes-kernel/linux</filename>
directory that you can use as references. that you can use as references.
</para> </para>
<para> <para>
@ -1153,8 +1107,8 @@ so that there are some definite steps on how to do this. I need more detail her
<para> <para>
A formfactor configuration file provides information about the A formfactor configuration file provides information about the
target hardware for which the Yocto Project is building and information that target hardware for which the image is being built and information that
the Yocto Project cannot obtain from other sources such as the kernel. the build system cannot obtain from other sources such as the kernel.
Some examples of information contained in a formfactor configuration file include Some examples of information contained in a formfactor configuration file include
framebuffer orientation, whether or not the system has a keyboard, framebuffer orientation, whether or not the system has a keyboard,
the positioning of the keyboard in relation to the screen, and the positioning of the keyboard in relation to the screen, and
@ -1162,9 +1116,9 @@ so that there are some definite steps on how to do this. I need more detail her
</para> </para>
<para> <para>
The Yocto Project uses reasonable defaults in most cases, but if customization is The build system uses reasonable defaults in most cases, but if customization is
necessary you need to create a <filename>machconfig</filename> file necessary you need to create a <filename>machconfig</filename> file
in the Yocto Project file's <filename>meta/recipes-bsp/formfactor/files</filename> in the <filename>meta/recipes-bsp/formfactor/files</filename>
directory. directory.
This directory contains directories for specific machines such as This directory contains directories for specific machines such as
<filename>qemuarm</filename> and <filename>qemux86</filename>. <filename>qemuarm</filename> and <filename>qemux86</filename>.
@ -1237,7 +1191,7 @@ so that there are some definite steps on how to do this. I need more detail her
extended to support multiple libraries. extended to support multiple libraries.
Many standard recipes are already extended and support multiple libraries. Many standard recipes are already extended and support multiple libraries.
You can check in the <filename>meta/conf/multilib.conf</filename> You can check in the <filename>meta/conf/multilib.conf</filename>
configuration file in the Yocto Project files directory to see how this is configuration file in the source directory to see how this is
done using the <filename>BBCLASSEXTEND</filename> variable. done using the <filename>BBCLASSEXTEND</filename> variable.
Eventually, all recipes will be covered and this list will be unneeded. Eventually, all recipes will be covered and this list will be unneeded.
</para> </para>
@ -1266,7 +1220,7 @@ so that there are some definite steps on how to do this. I need more detail her
combination of multiple libraries you want to build. combination of multiple libraries you want to build.
You accomplish this through your <filename>local.conf</filename> You accomplish this through your <filename>local.conf</filename>
configuration file in the configuration file in the
<link linkend='yocto-project-build-directory'>Yocto Project Build Directory</link>. <link linkend='build-directory'>build directory</link>.
An example configuration would be as follows: An example configuration would be as follows:
<literallayout class='monospaced'> <literallayout class='monospaced'>
MACHINE = "qemux86-64" MACHINE = "qemux86-64"
@ -1311,7 +1265,7 @@ so that there are some definite steps on how to do this. I need more detail her
<listitem><para>A unique architecture is defined for the Multilib packages, <listitem><para>A unique architecture is defined for the Multilib packages,
along with creating a unique deploy folder under along with creating a unique deploy folder under
<filename>tmp/deploy/rpm</filename> in the <filename>tmp/deploy/rpm</filename> in the
<link linkend='yocto-project-build-directory'>Yocto Project Build Directory</link>. <link linkend='build-directory'>build directory</link>.
For example, consider <filename>lib32</filename> in a For example, consider <filename>lib32</filename> in a
<filename>qemux86-64</filename> image. <filename>qemux86-64</filename> image.
The possible architectures in the system are "all", "qemux86_64", The possible architectures in the system are "all", "qemux86_64",
@ -1386,7 +1340,7 @@ so that there are some definite steps on how to do this. I need more detail her
To use the <filename>menuconfig</filename> tool in the Yocto Project development To use the <filename>menuconfig</filename> tool in the Yocto Project development
environment, you must build the tool using BitBake. environment, you must build the tool using BitBake.
The following commands build and invoke <filename>menuconfig</filename> assuming the The following commands build and invoke <filename>menuconfig</filename> assuming the
Yocto Project files top-level directory is <filename>~/poky</filename>: source directory top-level folder is <filename>~/poky</filename>:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ cd ~/poky $ cd ~/poky
$ source oe-init-build-env $ source oe-init-build-env
@ -1426,7 +1380,7 @@ so that there are some definite steps on how to do this. I need more detail her
Where do you put your configuration files? Where do you put your configuration files?
You can place these configuration files in the same area pointed to by You can place these configuration files in the same area pointed to by
<filename>SRC_URI</filename>. <filename>SRC_URI</filename>.
The Yocto Project build process will pick up the configuration and add it to the The OpenEmbedded build system will pick up the configuration and add it to the
kernel's configuration. kernel's configuration.
For example, assume you add the following to your For example, assume you add the following to your
<filename>linux-yocto_3.0.bbappend</filename> file: <filename>linux-yocto_3.0.bbappend</filename> file:
@ -1608,7 +1562,7 @@ so that there are some definite steps on how to do this. I need more detail her
<para> <para>
Sometimes a package name you are using might exist under an alias or as a similarly named Sometimes a package name you are using might exist under an alias or as a similarly named
package in a different distribution. package in a different distribution.
The Yocto Project implements a <filename>distro_check</filename> The OpenEmbedded build system implements a <filename>distro_check</filename>
task that automatically connects to major distributions task that automatically connects to major distributions
and checks for these situations. and checks for these situations.
If the package exists under a different name in a different distribution, you get a If the package exists under a different name in a different distribution, you get a
@ -1631,17 +1585,17 @@ so that there are some definite steps on how to do this. I need more detail her
<para> <para>
If you have more than one distribution alias, separate them with a space. If you have more than one distribution alias, separate them with a space.
Note that the Yocto Project currently automatically checks the Note that the build system currently automatically checks the
Fedora, OpenSuSE, Debian, Ubuntu, Fedora, OpenSuSE, Debian, Ubuntu,
and Mandriva distributions for source package recipes without having to specify them and Mandriva distributions for source package recipes without having to specify them
using the <filename>DISTRO_PN_ALIAS</filename> variable. using the <filename>DISTRO_PN_ALIAS</filename> variable.
For example, the following command generates a report that lists the Linux distributions For example, the following command generates a report that lists the Linux distributions
that include the sources for each of the Yocto Project recipes. that include the sources for each of the recipes.
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ bitbake world -f -c distro_check $ bitbake world -f -c distro_check
</literallayout> </literallayout>
The results are stored in the <filename>build/tmp/log/distro_check-${DATETIME}.results</filename> The results are stored in the <filename>build/tmp/log/distro_check-${DATETIME}.results</filename>
file found in the Yocto Project files area. file found in the source directory.
</para> </para>
</section> </section>
@ -1649,18 +1603,18 @@ so that there are some definite steps on how to do this. I need more detail her
<title>Building Software from an External Source</title> <title>Building Software from an External Source</title>
<para> <para>
By default, the Yocto Project build system does its work from within the By default, the OpenEmbedded build system does its work from within the
<link linkend='yocto-project-build-directory'>Yocto Project Build Directory</link>. <link linkend='build-directory'>build directory</link>.
The build process involves fetching the source files, unpacking them, and then patching them The build process involves fetching the source files, unpacking them, and then patching them
if necessary before the build takes place. if necessary before the build takes place.
</para> </para>
<para> <para>
Situations exist where you might want to build software from source files that are external to Situations exist where you might want to build software from source files that are external to
and thus outside of the <link linkend='yocto-project-files'>Yocto Project Files</link>. and thus outside of the <link linkend='source-directory'>source directory</link>.
For example, suppose you have a project that includes a new BSP with a heavily customized For example, suppose you have a project that includes a new BSP with a heavily customized
kernel, a very minimal image, and some new user-space recipes. kernel, a very minimal image, and some new user-space recipes.
And, you want to minimize the exposure to the Yocto Project build system to the And, you want to minimize the exposure to the build system to the
development team so that they can focus on their project and maintain everyone's workflow development team so that they can focus on their project and maintain everyone's workflow
as much as possible. as much as possible.
In this case, you want a kernel source directory on the development machine where the In this case, you want a kernel source directory on the development machine where the
@ -1829,7 +1783,7 @@ so that there are some definite steps on how to do this. I need more detail her
<para> <para>
A suitable GDB cross-binary is required that runs on your host computer but A suitable GDB cross-binary is required that runs on your host computer but
also knows about the the ABI of the remote target. also knows about the the ABI of the remote target.
You can get this binary from the the Yocto Project meta-toolchain. You can get this binary from the meta-toolchain.
Here is an example: Here is an example:
<literallayout class='monospaced'> <literallayout class='monospaced'>
/usr/local/poky/eabi-glibc/arm/bin/arm-poky-linux-gnueabi-gdb /usr/local/poky/eabi-glibc/arm/bin/arm-poky-linux-gnueabi-gdb
@ -1839,7 +1793,7 @@ so that there are some definite steps on how to do this. I need more detail her
</para> </para>
<para> <para>
Alternatively, the Yocto Project can build the <filename>gdb-cross</filename> binary. Alternatively, you can use BitBake to build the <filename>gdb-cross</filename> binary.
Here is an example: Here is an example:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ bitbake gdb-cross $ bitbake gdb-cross
@ -1871,13 +1825,14 @@ so that there are some definite steps on how to do this. I need more detail her
</para> </para>
<para> <para>
Alternatively, Yocto Project can build a custom directory of files for a specific Alternatively, the OpenEmbedded build system can build a custom directory of files
for a specific
debugging purpose by reusing its <filename>tmp/rootfs</filename> directory. debugging purpose by reusing its <filename>tmp/rootfs</filename> directory.
This directory contains the contents of the last built image. This directory contains the contents of the last built image.
This process assumes two things: This process assumes two things:
<itemizedlist> <itemizedlist>
<listitem><para>The image running on the target was the last image to <listitem><para>The image running on the target was the last image to
be built by the Yocto Project.</para></listitem> be built.</para></listitem>
<listitem><para>The package (<filename>foo</filename> in the following <listitem><para>The package (<filename>foo</filename> in the following
example) that contains the inferior binary to be debugged has been built example) that contains the inferior binary to be debugged has been built
without optimization and has debugging information available.</para></listitem> without optimization and has debugging information available.</para></listitem>
@ -1975,8 +1930,8 @@ so that there are some definite steps on how to do this. I need more detail her
bottlenecks in both userspace software and in the kernel. bottlenecks in both userspace software and in the kernel.
This profiler provides answers to questions like "Which functions does my application spend This profiler provides answers to questions like "Which functions does my application spend
the most time in when doing X?" the most time in when doing X?"
Because the Yocto Project is well integrated with OProfile, it makes profiling applications on target Because the OpenEmbedded build system is well integrated with OProfile, it makes profiling
hardware straightforward. applications on target hardware straightforward.
</para> </para>
<para> <para>
@ -1994,7 +1949,7 @@ so that there are some definite steps on how to do this. I need more detail her
For successful call graph analysis, the binaries must preserve the frame For successful call graph analysis, the binaries must preserve the frame
pointer register and should also be compiled with the pointer register and should also be compiled with the
<filename>-fno-omit-framepointer</filename> flag. <filename>-fno-omit-framepointer</filename> flag.
In the Yocto Project you can achieve this by setting the You can achieve this by setting the
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</ulink></filename> <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</ulink></filename>
variable to variable to
<filename>-fexpensive-optimizations -fno-omit-framepointer -frename-registers -O2</filename>. <filename>-fexpensive-optimizations -fno-omit-framepointer -frename-registers -O2</filename>.
@ -2036,7 +1991,7 @@ so that there are some definite steps on how to do this. I need more detail her
<note> <note>
To profile the kernel, you would specify the To profile the kernel, you would specify the
<filename>--vmlinux=/path/to/vmlinux</filename> option. <filename>--vmlinux=/path/to/vmlinux</filename> option.
The <filename>vmlinux</filename> file is usually in the Yocto Project file's The <filename>vmlinux</filename> file is usually in the source directory in the
<filename>/boot/</filename> directory and must match the running kernel. <filename>/boot/</filename> directory and must match the running kernel.
</note> </note>
</para> </para>
@ -2079,7 +2034,7 @@ so that there are some definite steps on how to do this. I need more detail her
</para> </para>
<para> <para>
Even though the Yocto Project usually includes all needed patches on the target device, you Even though the source directory usually includes all needed patches on the target device, you
might find you need other OProfile patches for recent OProfileUI features. might find you need other OProfile patches for recent OProfileUI features.
If so, see the <ulink url='&YOCTO_GIT_URL;/cgit.cgi/oprofileui/tree/README'> If so, see the <ulink url='&YOCTO_GIT_URL;/cgit.cgi/oprofileui/tree/README'>
OProfileUI README</ulink> for the most recent information. OProfileUI README</ulink> for the most recent information.
@ -2142,18 +2097,18 @@ so that there are some definite steps on how to do this. I need more detail her
</para> </para>
<para> <para>
Downloaded archives reside in the Yocto Project's build directory in Downloaded archives reside in the build directory in
<filename>/tmp</filename> and are cleared up when they are no longer in use. <filename>/tmp</filename> and are cleared up when they are no longer in use.
</para> </para>
<para> <para>
If you wish to perform kernel profiling, you need to be sure If you wish to perform kernel profiling, you need to be sure
a <filename>vmlinux</filename> file that matches the running kernel is available. a <filename>vmlinux</filename> file that matches the running kernel is available.
In the Yocto Project, that file is usually located in In the source directory, that file is usually located in
<filename>/boot/vmlinux-KERNELVERSION</filename>, where <filename>/boot/vmlinux-KERNELVERSION</filename>, where
<filename>KERNEL-version</filename> is the version of the kernel. <filename>KERNEL-version</filename> is the version of the kernel.
The Yocto Project generates separate <filename>vmlinux</filename> packages for each kernel The OpenEmbedded build system generates separate <filename>vmlinux</filename>
it builds. packages for each kernel it builds.
Thus, it should just be a question of making sure a matching package is Thus, it should just be a question of making sure a matching package is
installed (e.g. <filename>opkg install kernel-vmlinux</filename>. installed (e.g. <filename>opkg install kernel-vmlinux</filename>.
The files are automatically installed into development and profiling images The files are automatically installed into development and profiling images
@ -2169,7 +2124,7 @@ so that there are some definite steps on how to do this. I need more detail her
on the viewer system. on the viewer system.
The "<link linkend='platdev-gdb-remotedebug-launch-gdb'>Launching GDB on the Host Computer</link>" The "<link linkend='platdev-gdb-remotedebug-launch-gdb'>Launching GDB on the Host Computer</link>"
section covers how to create such a directory with section covers how to create such a directory with
the Yocto Project and how to use the OProfileUI Settings dialog to specify the location. the source directory and how to use the OProfileUI Settings dialog to specify the location.
If you specify the directory, it will be used when the file checksums If you specify the directory, it will be used when the file checksums
match those on the system you are profiling. match those on the system you are profiling.
</para> </para>

35
documentation/dev-manual/dev-manual-intro.xml
View File

@ -18,7 +18,8 @@
sources where you can find more detail. sources where you can find more detail.
For example, detailed information on Git, repositories and open source in general For example, detailed information on Git, repositories and open source in general
can be found in many places. 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. Another example is how to get set up to use the Yocto Project, which our Yocto Project
Quick Start covers.
</para> </para>
<para> <para>
@ -44,13 +45,7 @@
applications.</para></listitem> applications.</para></listitem>
<listitem><para>An overview and understanding of the emulation environment used with <listitem><para>An overview and understanding of the emulation environment used with
the Yocto Project (QEMU).</para></listitem> the Yocto Project (QEMU).</para></listitem>
<!-- <listitem><para>A discussion of target-level analysis techniques, tools, tips, <listitem><para>An understanding of basic kernel architecture and concepts.</para></listitem>
and tricks.</para></listitem>
<listitem><para>Considerations for deploying your final product.</para></listitem> -->
<listitem><para>An understanding of basic kernel architecture and
concepts.</para></listitem>
<!-- <listitem><para>Information that will help you migrate an existing project to the
Yocto Project development environment.</para></listitem> -->
<listitem><para>Many references to other sources of related information.</para></listitem> <listitem><para>Many references to other sources of related information.</para></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
@ -97,7 +92,7 @@
<listitem><para><emphasis> <listitem><para><emphasis>
<ulink url='&YOCTO_DOCS_REF_URL;'> <ulink url='&YOCTO_DOCS_REF_URL;'>
The Yocto Project Reference Manual</ulink>:</emphasis> This manual is a reference The Yocto Project Reference Manual</ulink>:</emphasis> This manual is a reference
guide to the Yocto Project build component known as "Poky." guide to the OpenEmbedded build system known as "Poky."
The manual also contains a reference chapter on Board Support Package (BSP) The manual also contains a reference chapter on Board Support Package (BSP)
layout.</para></listitem> layout.</para></listitem>
<listitem><para><emphasis> <listitem><para><emphasis>
@ -117,7 +112,7 @@
some work flow examples.</para></listitem> some work flow examples.</para></listitem>
<listitem><para><emphasis> <listitem><para><emphasis>
<ulink url='http://www.youtube.com/watch?v=3ZlOu-gLsh0'> <ulink url='http://www.youtube.com/watch?v=3ZlOu-gLsh0'>
Yocto Eclipse Plug-in</ulink>:</emphasis> A step-by-step instructional video that 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 demonstrates how an application developer uses Yocto Plug-in features within
the Eclipse IDE.</para></listitem> the Eclipse IDE.</para></listitem>
<listitem><para><emphasis> <listitem><para><emphasis>
@ -158,22 +153,26 @@
<listitem><para><emphasis>Internet Relay Chat (IRC):</emphasis> <listitem><para><emphasis>Internet Relay Chat (IRC):</emphasis>
Two IRC channels on freenode are available Two IRC channels on freenode are available
for Yocto Project and Poky discussions: <filename>#yocto</filename> and for Yocto Project and Poky discussions: <filename>#yocto</filename> and
<filename>#poky</filename>.</para></listitem> <filename>#poky</filename>, respectively.</para></listitem>
<listitem><para><emphasis> <listitem><para><emphasis>
<ulink url='&OH_HOME_URL;'>OpenedHand</ulink>:</emphasis> <ulink url='&OH_HOME_URL;'>OpenedHand</ulink>:</emphasis>
The company where the Yocto Project build system Poky was first developed. The company that initially developed the Poky project, which is the basis
OpenedHand has since been acquired by Intel Corporation.</para></listitem> for the OpenEmbedded build system used by the Yocto Project.
OpenedHand was acquired by Intel Corporation in 2008.</para></listitem>
<listitem><para><emphasis> <listitem><para><emphasis>
<ulink url='http://www.intel.com/'>Intel Corporation</ulink>:</emphasis> <ulink url='http://www.intel.com/'>Intel Corporation</ulink>:</emphasis>
The company that acquired OpenedHand in 2008 and continues development on the A multinational semiconductor chip manufacturer company whose Software and
Yocto Project.</para></listitem> Services Group created and supports the Yocto Project.
Intel acquired OpenedHand in 2008.</para></listitem>
<listitem><para><emphasis> <listitem><para><emphasis>
<ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>:</emphasis> <ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>:</emphasis>
The upstream, generic, embedded distribution the Yocto Project build system (Poky) derives The build system used by the Yocto Project.
from and to which it contributes.</para></listitem> 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> <listitem><para><emphasis>
<ulink url='http://developer.berlios.de/projects/bitbake/'> <ulink url='http://developer.berlios.de/projects/bitbake/'>
BitBake</ulink>:</emphasis> The tool used to process Yocto Project metadata.</para></listitem> BitBake</ulink>:</emphasis> The tool used by the OpenEmbedded build systm
to process project metadata.</para></listitem>
<listitem><para><emphasis> <listitem><para><emphasis>
<ulink url='http://bitbake.berlios.de/manual/'> <ulink url='http://bitbake.berlios.de/manual/'>
BitBake User Manual</ulink>:</emphasis> A comprehensive guide to the BitBake tool. BitBake User Manual</ulink>:</emphasis> A comprehensive guide to the BitBake tool.

92
documentation/dev-manual/dev-manual-kernel-appendix.xml
View File

@ -12,17 +12,6 @@
or even altering the source code itself. or even altering the source code itself.
This appendix presents simple examples that modify the kernel source code, This appendix presents simple examples that modify the kernel source code,
change the kernel configuration, and add a kernel source recipe. change the kernel configuration, and add a kernel source recipe.
<!-- [WRITER'S NOTE: I might want to work in information about applying a local
change to a kernel layer and also pushing a change upstream into the tree]
<orderedlist>
<listitem><para>Iteratively determine and set kernel configurations and make
kernel recipe changes.</para></listitem>
<listitem><para>Apply your configuration changes to your local kernel layer.
</para></listitem>
<listitem><para>Push your configuration and recipe changes upstream into the
Yocto Project source repositories to make them available to the community.
</para></listitem>
</orderedlist> -->
</para> </para>
<section id='modifying-the-kernel-source-code'> <section id='modifying-the-kernel-source-code'>
@ -45,18 +34,17 @@
Briefly, you need the following: Briefly, you need the following:
<itemizedlist> <itemizedlist>
<listitem><para>A local <listitem><para>A local
<link linkend='yocto-project-files'>Yocto Project Files</link> <link linkend='source-directory'>source directory</link> for the
Git repository</para></listitem> poky Git repository</para></listitem>
<listitem><para>The <listitem><para>Local copies of the
<link linkend='poky-extras-repo'><filename>poky-extras</filename></link> <link linkend='poky-extras-repo'><filename>poky-extras</filename></link>
Git repository placed within the local Yocto Project files Git Git repository placed within the source directory.</para></listitem>
repository</para></listitem>
<listitem><para>A bare clone of the <listitem><para>A bare clone of the
<link linkend='local-kernel-files'>Linux Yocto Kernel</link> upstream Git <link linkend='local-kernel-files'>Linux Yocto Kernel</link> upstream Git
repository to which you want to push your modifications. repository to which you want to push your modifications.
</para></listitem> </para></listitem>
<listitem><para>A copy of that bare clone in which you make your source <listitem><para>A copy of that bare clone in which you make your source
modifcations</para></listitem> modifications</para></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
@ -78,18 +66,19 @@
<para> <para>
Here is a brief description of the four areas: Here is a brief description of the four areas:
<itemizedlist> <itemizedlist>
<listitem><para><emphasis>Local Yocto Project Files Git Repository:</emphasis> <listitem><para><emphasis>Local Source Directory:</emphasis>
This area contains all the metadata that supports building images in the This area contains all the metadata that supports building images
Yocto Project build environment - the local Yocto Project files. using the OpenEmbedded build system.
In this example, the local Yocto Project files Git repository also In this example, the source directory also
contains the build directory, which contains the configuration directory contains the build directory, which contains the configuration directory
that lets you control the build. that lets you control the build.
In this example, the repository also contains the Also in this example, the source directory contains local copies of the
<filename>poky-extras</filename> Git repository.</para> <filename>poky-extras</filename> Git repository.</para>
<para>See the bulleted item <para>See the bulleted item
"<link linkend='local-yp-release'>Yocto Project Release</link>" "<link linkend='local-yp-release'>Yocto Project Release</link>"
for information on how to get these files.</para></listitem> for information on how to get these files on your local system.</para></listitem>
<listitem><para><emphasis><filename>poky-extras</filename> Git Repository:</emphasis> <listitem><para><emphasis>Local copies of the<filename>poky-extras</filename>
Git Repository:</emphasis>
This area contains the <filename>meta-kernel-dev</filename> layer, This area contains the <filename>meta-kernel-dev</filename> layer,
which is where you make changes that append the kernel build recipes. which is where you make changes that append the kernel build recipes.
You edit <filename>.bbappend</filename> files to locate your You edit <filename>.bbappend</filename> files to locate your
@ -133,23 +122,23 @@
</section> </section>
<section id='setting-up-the-local-yocto-project-files-git-repository'> <section id='setting-up-the-local-yocto-project-files-git-repository'>
<title>Setting Up the Local Yocto Project Files Git Repository</title> <title>Setting Up the Local Source Directory</title>
<para> <para>
You can get the local Yocto Project files through tarball extraction or by You can set up the source directory through tarball extraction or by
cloning the <filename>poky</filename> Git repository. cloning the <filename>poky</filename> Git repository.
This example uses <filename>poky</filename> as the root directory of the This example uses <filename>poky</filename> as the root directory of the
local Yocto Project files Git repository. local source directory.
See the bulleted item See the bulleted item
"<link linkend='local-yp-release'>Yocto Project Release</link>" "<link linkend='local-yp-release'>Yocto Project Release</link>"
for information on how to get these files. for information on how to get these files.
</para> </para>
<para> <para>
Once you have the repository set up, Once you have source directory set up,
you have many development branches from which you can work. you have many development branches from which you can work.
From inside the repository you can see the branch names and the tag names used From inside the local repository you can see the branch names and the tag names used
in the Git repository using either of the following two commands: in the upstream Git repository by using either of the following commands:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ cd poky $ cd poky
$ git branch -a $ git branch -a
@ -168,15 +157,15 @@
</section> </section>
<section id='setting-up-the-poky-extras-git-repository'> <section id='setting-up-the-poky-extras-git-repository'>
<title>Setting Up the poky-extras Git Repository</title> <title>Setting Up the Local poky-extras Git Repository</title>
<para> <para>
This example places the <filename>poky-extras</filename> Git repository inside This example creates a local copy of the <filename>poky-extras</filename> Git
of <filename>poky</filename>. repository inside the <filename>poky</filename> source directory.
See the bulleted item See the bulleted item "<link linkend='poky-extras-repo'>The
"<link linkend='poky-extras-repo'>The
<filename>poky-extras</filename> Git Repository</link>" <filename>poky-extras</filename> Git Repository</link>"
for information on how to get the <filename>poky-extras</filename> repository. for information on how to set up a local copy of the
<filename>poky-extras</filename> repository.
</para> </para>
<para> <para>
@ -369,7 +358,7 @@
<para> <para>
Once the source code has been modified, you need to use Git to push the changes to Once the source code has been modified, you need to use Git to push the changes to
the bare clone. the bare clone.
If you do not push the changes, then the Yocto Project build system will not pick If you do not push the changes, then the OpenEmbedded build system will not pick
up the changed source files. up the changed source files.
</para> </para>
@ -386,7 +375,7 @@
<para> <para>
At this point, the source has been changed and pushed. At this point, the source has been changed and pushed.
The example now defines some variables used by the Yocto Project build system The example now defines some variables used by the OpenEmbedded build system
to locate your kernel source. to locate your kernel source.
You essentially need to identify where to find the kernel recipe and the changed source code. You essentially need to identify where to find the kernel recipe and the changed source code.
You also need to be sure some basic configurations are in place that identify the You also need to be sure some basic configurations are in place that identify the
@ -447,12 +436,6 @@
<literallayout class='monospaced'> <literallayout class='monospaced'>
KSRC_linux_yocto_3_2 ?= "/home/scottrif/linux-yocto-3.2.git" KSRC_linux_yocto_3_2 ?= "/home/scottrif/linux-yocto-3.2.git"
</literallayout></para></listitem> </literallayout></para></listitem>
<!-- <listitem><para><emphasis>Specify the Kernel Machine:</emphasis> Also in the
<filename>linux-yocto_3.2.bbappend</filename> file, you need to specify
the kernel machine with the following statement:
<literallayout class='monospaced'>
KMACHINE_qemux86 = "standard/default/common-pc/base"
</literallayout></para></listitem> -->
</itemizedlist> </itemizedlist>
</para> </para>
@ -494,7 +477,7 @@
$ bitbake -c cleanall linux-yocto $ bitbake -c cleanall linux-yocto
</literallayout></para> </literallayout></para>
<para><note>Never remove any files by hand from the <filename>tmp/deploy</filename> <para><note>Never remove any files by hand from the <filename>tmp/deploy</filename>
directory insided the local Yocto Project files build directory. directory insided the build directory.
Always use the BitBake <filename>cleanall</filename> task to clear Always use the BitBake <filename>cleanall</filename> task to clear
out previous builds.</note></para></listitem> out previous builds.</note></para></listitem>
<listitem><para>Next, build the kernel image using this command: <listitem><para>Next, build the kernel image using this command:
@ -539,7 +522,7 @@
<para> <para>
If you took the time to work through the example that modifies the kernel source code If you took the time to work through the example that modifies the kernel source code
in "<link linkend='modifying-the-kernel-source-code'>Modifying the Kernel Source in "<link linkend='modifying-the-kernel-source-code'>Modifying the Kernel Source
Code</link>" you should already have the Yocto Project files set up on your Code</link>" you should already have the source directory set up on your
host machine. host machine.
If this is the case, go to the next section, which is titled If this is the case, go to the next section, which is titled
"<link linkend='examining-the-default-config-smp-behavior'>Examining the Default "<link linkend='examining-the-default-config-smp-behavior'>Examining the Default
@ -548,21 +531,21 @@
</para> </para>
<para> <para>
If you don't have the Yocto Project files established on your system, If you don't have the source directory established on your system,
you can get them through tarball extraction or by you can get them through tarball extraction or by
cloning the <filename>poky</filename> Git repository. cloning the <filename>poky</filename> Git repository.
This example uses <filename>poky</filename> as the root directory of the This example uses <filename>poky</filename> as the root directory of the
local <link linkend='yocto-project-files'>Yocto Project Files</link> Git repository. <link linkend='source-directory'>source directory</link>.
See the bulleted item See the bulleted item
"<link linkend='local-yp-release'>Yocto Project Release</link>" "<link linkend='local-yp-release'>Yocto Project Release</link>"
for information on how to get these files. for information on how to get these files.
</para> </para>
<para> <para>
Once you have the repository set up, Once you have the local copy of the repository set up,
you have many development branches from which you can work. you have many development branches from which you can work.
From inside the repository you can see the branch names and the tag names used From inside the repository you can see the branch names and the tag names used
in the Git repository using either of the following two commands: in the upstream Git repository using either of the following commands:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ cd poky $ cd poky
$ git branch -a $ git branch -a
@ -680,7 +663,7 @@
to set kernel configurations. to set kernel configurations.
You need to run <filename>menuconfig</filename> inside the Yocto BitBake environment. You need to run <filename>menuconfig</filename> inside the Yocto BitBake environment.
Thus, the environment must be set up using the <filename>oe-init-build-env</filename> Thus, the environment must be set up using the <filename>oe-init-build-env</filename>
script found in the Yocto Project files Git repository build directory. script found in the build directory.
If you have not sourced this script do so with the following commands: If you have not sourced this script do so with the following commands:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ cd ~/poky $ cd ~/poky
@ -693,7 +676,7 @@
to use the tool to interactively change the kernel configuration. to use the tool to interactively change the kernel configuration.
In this example, we are basing our changes on the <filename>linux-yocto-3.2</filename> In this example, we are basing our changes on the <filename>linux-yocto-3.2</filename>
kernel. kernel.
The Yocto Project build environment recognizes this kernel as The OpenEmbedded build system recognizes this kernel as
<filename>linux-yocto</filename>. <filename>linux-yocto</filename>.
Thus, the following commands from the shell in which you previously sourced the Thus, the following commands from the shell in which you previously sourced the
environment initialization script cleans the shared state memory and the environment initialization script cleans the shared state memory and the
@ -727,8 +710,7 @@
is updated. is updated.
This is the file that the build system uses to configure the Linux Yocto kernel This is the file that the build system uses to configure the Linux Yocto kernel
when it is built. when it is built.
You can find and examine this file in the Yocto Project Files Git repository in You can find and examine this file in the build directory.
the build directory.
This example uses the following: This example uses the following:
<literallayout class='monospaced'> <literallayout class='monospaced'>
~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.2.11+git1+84f... ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.2.11+git1+84f...
@ -762,7 +744,7 @@
<note> <note>
Be sure to make a copy of the <filename>.config</filename> and don't just Be sure to make a copy of the <filename>.config</filename> and don't just
rename it. rename it.
The Yocto Project build system needs an existing <filename>.config</filename> The build system needs an existing <filename>.config</filename>
from which to work. from which to work.
</note> </note>
</para> </para>

137
documentation/dev-manual/dev-manual-model.xml
View File

@ -34,8 +34,8 @@
get the changes upstream and applied in the affected recipes.</para></listitem> get the changes upstream and applied in the affected recipes.</para></listitem>
<listitem><para><emphasis>Image Development using Hob:</emphasis> <listitem><para><emphasis>Image Development using Hob:</emphasis>
You can use the <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink> to build You can use the <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink> to build
custom operating system images within the Yocto Project build environment. custom operating system images within the build environment.
Hob provides an efficient interface to the Yocto Project build system.</para></listitem> Hob provides an efficient interface to the OpenEmbedded build system.</para></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
@ -94,18 +94,20 @@
and the and the
"<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both
in the Yocto Project Quick Start for requirements.</para></listitem> in the Yocto Project Quick Start for requirements.</para></listitem>
<listitem><para><emphasis>Establish a local copy of the Yocto Project files on your <listitem><para><emphasis>Establish a local copy of the project files on your
system</emphasis>: You need to have the Yocto Project files available on your host system. system</emphasis>: You need this <link linkend='source-directory'>source
Having the Yocto Project files on your system gives you access to the build 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. process and to the tools you need.
For information on how to get these files, see the For information on how to set up the source directory, see the
"<link linkend='getting-setup'>Getting Setup</link>" section.</para></listitem> "<link linkend='getting-setup'>Getting Setup</link>" section.</para></listitem>
<listitem><para><emphasis>Establish a local copy of the base BSP files</emphasis>: Having <listitem><para><emphasis>Establish a local copy of the base BSP files</emphasis>: Having
the BSP files on your system gives you access to the build the BSP files on your system gives you access to the build
process and to the tools you need for creating a BSP. process and to the tools you need for creating a BSP.
For information on how to get these files, see the For information on how to get these files, see the
"<link linkend='getting-setup'>Getting Setup</link>" section.</para></listitem> "<link linkend='getting-setup'>Getting Setup</link>" section.</para></listitem>
<listitem><para><emphasis>Choose a Yocto Project-supported BSP as your base BSP</emphasis>: <listitem><para><emphasis>Choose a BSP that is supported by the Yocto Project
as your base BSP</emphasis>:
The Yocto Project ships with several BSPs that support various hardware. The Yocto Project ships with several BSPs that support various hardware.
It is best to base your new BSP on an existing BSP rather than create all the It is best to base your new BSP on an existing BSP rather than create all the
recipes and configuration files from scratch. recipes and configuration files from scratch.
@ -138,7 +140,7 @@
The layer, in this case, would be where all the recipes that define those dependencies The layer, in this case, would be where all the recipes that define those dependencies
are kept. are kept.
The key point for a layer is that it is an isolated area that contains The key point for a layer is that it is an isolated area that contains
all the relevant information for the project that the Yocto Project build all the relevant information for the project that the OpenEmbedded build
system knows about. system knows about.
For more information on layers, see the For more information on layers, see the
"<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>" "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>"
@ -146,11 +148,11 @@
For more information on BSP layers, see the For more information on BSP layers, see the
"<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" section in 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> Yocto Project Board Support Package (BSP) Developer's Guide.</para>
<note>The Yocto Project supports four BSPs that are part of the <note>Four BSPs exist that are part of the
Yocto Project release: <filename>atom-pc</filename>, <filename>beagleboard</filename>, Yocto Project release: <filename>atom-pc</filename>, <filename>beagleboard</filename>,
<filename>mpc8315e</filename>, and <filename>routerstationpro</filename>. <filename>mpc8315e</filename>, and <filename>routerstationpro</filename>.
The recipes and configurations for these four BSPs are located and dispersed The recipes and configurations for these four BSPs are located and dispersed
within the <link linkend='yocto-project-files'>Yocto Project Files</link>. within the <link linkend='source-directory'>source directory</link>.
On the other hand, BSP layers for Crown Bay, Emenlow, Jasper Forest, On the other hand, BSP layers for Crown Bay, Emenlow, Jasper Forest,
N450, Cedar Trail, Fish River, Fish River Island II, Romley, sys940x, tlk, N450, Cedar Trail, Fish River, Fish River Island II, Romley, sys940x, tlk,
and Sugar Bay exist in their own separate layers within the larger and Sugar Bay exist in their own separate layers within the larger
@ -163,7 +165,7 @@
configuration information. configuration information.
You can see the standard layout for the Crown Bay BSP in this example by examining the You can see the standard layout for the Crown Bay BSP in this example by examining the
directory structure of the <filename>meta-crownbay</filename> layer inside the directory structure of the <filename>meta-crownbay</filename> layer inside the
local Yocto Project files.</para></listitem> source directory.</para></listitem>
<listitem><para><emphasis>Make configuration changes to your new BSP <listitem><para><emphasis>Make configuration changes to your new BSP
layer</emphasis>: The standard BSP layer structure organizes the files you need layer</emphasis>: The standard BSP layer structure organizes the files you need
to edit in <filename>conf</filename> and several <filename>recipes-*</filename> to edit in <filename>conf</filename> and several <filename>recipes-*</filename>
@ -177,15 +179,15 @@
</para></listitem> </para></listitem>
<listitem><para><emphasis>Prepare for the build</emphasis>: Once you have made all the <listitem><para><emphasis>Prepare for the build</emphasis>: Once you have made all the
changes to your BSP layer, there remains a few things changes to your BSP layer, there remains a few things
you need to do for the Yocto Project build system in order for it to create your image. 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 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.</para> and you need to be sure two key configuration files are configured appropriately.</para>
<para>The entire process for building an image is overviewed in the section <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 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section
of the Yocto Project Quick Start. of the Yocto Project Quick Start.
You might want to reference this information.</para></listitem> You might want to reference this information.</para></listitem>
<listitem><para><emphasis>Build the image</emphasis>: The Yocto Project uses the BitBake <listitem><para><emphasis>Build the image</emphasis>: The OpenEmbedded build system
tool to build images based on the type of image you want to create. uses the BitBake tool to build images based on the type of image you want to create.
You can find more information on BitBake You can find more information on BitBake
<ulink url='http://bitbake.berlios.de/manual/'>here</ulink>.</para> <ulink url='http://bitbake.berlios.de/manual/'>here</ulink>.</para>
<para>The build process supports several types of images to satisfy different needs. <para>The build process supports several types of images to satisfy different needs.
@ -295,7 +297,7 @@
<para> <para>
The overall result is a Git-maintained repository from which all the supported The overall result is a Git-maintained repository from which all the supported
Yocto Project kernel types can be derived for all the supported Yocto Project devices. 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 A big advantage to this scheme is the sharing of common features by keeping them in
"larger" branches within the tree. "larger" branches within the tree.
This practice eliminates redundant storage of similar features shared among kernels. This practice eliminates redundant storage of similar features shared among kernels.
@ -313,7 +315,7 @@
<para> <para>
Storage of all the available kernel source code is one thing, while representing the Storage of all the available kernel source code is one thing, while representing the
code on your host development system is another. code on your host development system is another.
Conceptually, you can think of the Yocto Project kernel source repositories as all the Conceptually, you can think of the kernel source repositories as all the
source files necessary for all the supported kernels. source files necessary for all the supported kernels.
As a developer, you are just interested in the source files for the kernel on As a developer, you are just interested in the source files for the kernel on
on which you are working. on which you are working.
@ -358,7 +360,7 @@
<para> <para>
What happens during the build? What happens during the build?
When you build the kernel on your development system all files needed for the build When you build the kernel on your development system all files needed for the build
are taken from the Yocto Project source repositories pointed to by the are taken from the source repositories pointed to by the
<filename>SRC_URI</filename> variable and gathered in a temporary work area <filename>SRC_URI</filename> variable and gathered in a temporary work area
where they are subsequently used to create the unique kernel. where they are subsequently used to create the unique kernel.
Thus, in a sense, the process constructs a local source tree specific to your Thus, in a sense, the process constructs a local source tree specific to your
@ -375,7 +377,7 @@
</para> </para>
<para> <para>
Again, for a complete discussion of the Yocto Project kernel's architcture and its Again, for a complete discussion of the Yocto Project kernel's architecture and its
branching strategy, branching strategy,
see <ulink url='&YOCTO_DOCS_KERNEL_URL;'> see <ulink url='&YOCTO_DOCS_KERNEL_URL;'>
The Yocto Project Kernel Architecture and Use Manual</ulink>. The Yocto Project Kernel Architecture and Use Manual</ulink>.
@ -404,18 +406,19 @@
"<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distributions</ulink>" and "<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 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both
in the Yocto Project Quick Start for requirements.</para></listitem> in the Yocto Project Quick Start for requirements.</para></listitem>
<listitem><para><emphasis>Establish a local copy of the Yocto Project files on your <listitem><para><emphasis>Establish a local copy of project files on your
system</emphasis>: Having the Yocto Project files on your system gives you access to system</emphasis>: Having the <link linkend='source-directory'>source
the build process and tools you need. 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 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. "<link linkend='local-yp-release'>Yocto Project Release</link>" earlier in this manual.
</para></listitem> </para></listitem>
<listitem><para><emphasis>Set up the <filename>poky-extras</filename> Git <listitem><para><emphasis>Set up a local copy of the <filename>poky-extras</filename> Git
repository</emphasis>: This repository is the area for your configuration repository</emphasis>: This local repository is the area for your configuration
fragments, new kernel recipes, and the kernel <filename>.bbappend</filename> fragments, new kernel recipes, and the kernel <filename>.bbappend</filename>
file used during the build. file used during the build.
It is good practice to set this repository up inside the local Yocto It is good practice to set this repository up inside your local
Project files Git repository. source directory.
For information on how to get these files, see the bulleted item For information on how to get these files, see the bulleted item
"<link linkend='poky-extras-repo'>The <filename>poky-extras</filename> Git Repository</link>" "<link linkend='poky-extras-repo'>The <filename>poky-extras</filename> Git Repository</link>"
earlier in this manual. earlier in this manual.
@ -453,9 +456,9 @@
<filename>.config</filename>. <filename>.config</filename>.
Try to resist the temptation of directly editing the <filename>.config</filename> Try to resist the temptation of directly editing the <filename>.config</filename>
file found in the file found in the
<link linkend='yocto-project-build-directory'>Yocto Project Build Directory</link> at <link linkend='build-directory'>build directory</link> at
<filename>tmp/sysroots/&lt;machine-name&gt;/kernel</filename>. <filename>tmp/sysroots/&lt;machine-name&gt;/kernel</filename>.
Doing so, can produce unexpected results when the Yocto Project build system Doing so, can produce unexpected results when the OpenEmbedded build system
regenerates the configuration file.</para> regenerates the configuration file.</para>
<para>Once you are satisfied with the configuration changes made using <para>Once you are satisfied with the configuration changes made using
<filename>menuconfig</filename>, you can directly examine the <filename>menuconfig</filename>, you can directly examine the
@ -465,7 +468,7 @@
<listitem><para><emphasis>Add or extend kernel recipes if applicable</emphasis>: <listitem><para><emphasis>Add or extend kernel recipes if applicable</emphasis>:
The standard The standard
layer structure organizes recipe files inside the layer structure organizes recipe files inside the
<filename>meta-kernel-dev</filename> layer that is within the <filename>meta-kernel-dev</filename> layer that is within the local
<filename>poky-extras</filename> Git repository. <filename>poky-extras</filename> Git repository.
If you need to add new kernel recipes, you add them within this layer. If you need to add new kernel recipes, you add them within this layer.
Also within this area, you will find the <filename>.bbappend</filename> Also within this area, you will find the <filename>.bbappend</filename>
@ -475,7 +478,7 @@
<listitem><para><emphasis>Prepare for the build</emphasis>: Once you have made all the <listitem><para><emphasis>Prepare for the build</emphasis>: Once you have made all the
changes to your kernel (configurations, source code changes, recipe additions, changes to your kernel (configurations, source code changes, recipe additions,
or recipe changes), there remains a few things or recipe changes), there remains a few things
you need to do in order for the Yocto Project build system (BitBake) to create your image. you need to do in order for the build system to create your image.
If you have not done so, you need to get the build environment ready by sourcing If you have not done so, you need to get the build environment ready by sourcing
the environment setup script described earlier. the environment setup script described earlier.
You also need to be sure two key configuration files You also need to be sure two key configuration files
@ -487,8 +490,8 @@
You might want to reference this information. You might want to reference this information.
Also, you should look at the detailed examples found in the appendices at Also, you should look at the detailed examples found in the appendices at
at the end of this manual.</para></listitem> at the end of this manual.</para></listitem>
<listitem><para><emphasis>Build the image</emphasis>: The Yocto Project <listitem><para><emphasis>Build the image</emphasis>: The OpenEmbedded
build system Poky uses the BitBake build system uses the BitBake
tool to build images based on the type of image you want to create. tool to build images based on the type of image you want to create.
You can find more information on BitBake You can find more information on BitBake
<ulink url='http://bitbake.berlios.de/manual/'>here</ulink>.</para> <ulink url='http://bitbake.berlios.de/manual/'>here</ulink>.</para>
@ -514,7 +517,7 @@
</section> </section>
</section> </section>
<section id='place-holder-section-two'> <section id='application-development-workflow'>
<title>Application Development Workflow</title> <title>Application Development Workflow</title>
<para> <para>
@ -530,7 +533,7 @@
</para> </para>
<para> <para>
While we strongly suggest using the Yocto Project ADT to develop your application, you might While we strongly suggest using the ADT to develop your application, you might
not want to. not want to.
If this is the case, you can still use pieces of the Yocto Project for your development process. 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. However, because the process can vary greatly, this manual does not provide detail on the process.
@ -540,8 +543,7 @@
<title>Workflow Using the ADT and <trademark class='trade'>Eclipse</trademark></title> <title>Workflow Using the ADT and <trademark class='trade'>Eclipse</trademark></title>
<para> <para>
To help you understand how application development works in the Yocto Project ADT To help you understand how application development works using the ADT, this section
environment, this section
provides an overview of the general development process. provides an overview of the general development process.
If you want to see a detailed example of the process as it is used from within the Eclipse If you want to see a detailed example of the process as it is used from within the Eclipse
IDE, see IDE, see
@ -550,7 +552,7 @@
</para> </para>
<para> <para>
This illustration and the following list summarizes the application development general workflow. The following illustration and list summarize the application development general workflow.
</para> </para>
<para> <para>
@ -565,27 +567,9 @@
"<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distributions</ulink>" and "<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 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both
in the Yocto Project Quick Start for requirements.</para></listitem> in the Yocto Project Quick Start for requirements.</para></listitem>
<!--
WRITER NOTE: The areas to get the kernel and root filesystem are located in the Index of
downloads. There are many forms of each. The files that have "rootfs" are just the
target root filesystems. The file that is very small and starts with bzImage is just
the kernel image isolated so that it can be written to a special on-board area of
flash memory. Some systems require this. In the machines directory there are
files that combine the kernel image and the root filesystem. These files are the ISO
and HDDIMG files. ISO images are designed to be deployed on a DVD or CD. The ISO
images are designed to be deployed on a USB stick. There might be some relics in
the machine directory. For example, there is the "emenlow-bernard-5.0.0.tar.bz2"
file. Nobody seems to know what this is. If a developer needs the image and the
root filesystem I think that they want the small kernel image and a matching root
filesystem. Although, Paul Eggleton says that the HDDIMG types could be used to
develop on. I am not sure that we can use one of those in the ADT though as they
want you to point to the kernel image and the target root filesystem. Maybe you
could just point to the same spot. I am not sure.
-->
<listitem><para><emphasis>Secure the Linux Yocto Kernel Target Image</emphasis>: <listitem><para><emphasis>Secure the Linux Yocto Kernel Target Image</emphasis>:
You must have a target kernel image that has been built using the Yocto Project.</para> 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 <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 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. (QEMU or real hardware), the area from which you get the image differs.
@ -616,7 +600,7 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the
<listitem><para><emphasis>Install the ADT</emphasis>: <listitem><para><emphasis>Install the ADT</emphasis>:
The ADT provides a target-specific cross-development toolchain, the root filesystem, 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. the QEMU emulator, and other tools that can help you develop your application.
While it is possible to get these pieces separately, the Yocto Project provides an While it is possible to get these pieces separately, the ADT Installer provides an
easy method. easy method.
You can get these pieces by running an ADT installer script, which is configurable. You can get these pieces by running an ADT installer script, which is configurable.
For information on how to install the ADT, see the For information on how to install the ADT, see the
@ -707,14 +691,14 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the
<title>Modifying Temporary Source Code</title> <title>Modifying Temporary Source Code</title>
<para> <para>
Although the Yocto Project is typically used to build software, you might You might
find it helpful during development to modify the temporary source code used by recipes find it helpful during development to modify the temporary source code used by recipes
to build packages. to build packages.
For example, suppose you are developing a patch and you need to experiment a bit For example, suppose you are developing a patch and you need to experiment a bit
to figure out your solution. to figure out your solution.
After you have initially built the package, you can iteratively tweak the After you have initially built the package, you can iteratively tweak the
source code, which is located in the source code, which is located in the
<link linkend='yocto-project-build-directory'>Yocto Project's Build Directory</link>, and then <link linkend='build-directory'>build directory</link>, and then
you can force a re-compile and quickly test your altered code. 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 Once you settle on a solution, you can then preserve your changes in the form of
patches. patches.
@ -728,12 +712,12 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the
<para> <para>
During a build, the unpacked temporary source code used by recipes During a build, the unpacked temporary source code used by recipes
to build packages is available in the Yocto Project Build Directory as to build packages is available in the build directory as
defined by the defined by the
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> variable. <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 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 <filename>meta/conf/bitbake.conf</filename> configuration file in the
<link linkend='yocto-project-files'>Yocto Project Files</link>: <link linkend='source-directory'>source directory</link>:
<literallayout class='monospaced'> <literallayout class='monospaced'>
S = ${WORKDIR}/${BP} S = ${WORKDIR}/${BP}
</literallayout> </literallayout>
@ -758,8 +742,8 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the
${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR} ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
</literallayout> </literallayout>
Let's look at an example without variables. Let's look at an example without variables.
Assuming a Yocto Project Files top-level directory named <filename>poky</filename> Assuming a top-level source directory named <filename>poky</filename>
and a default Yocto Project Build Directory of <filename>poky/build</filename>, and a default build directory of <filename>poky/build</filename>,
the following is the work directory for the <filename>acl</filename> package: the following is the work directory for the <filename>acl</filename> package:
<literallayout class='monospaced'> <literallayout class='monospaced'>
~/poky/build/tmp/work/i586-poky-linux/acl-2.2.51-r3 ~/poky/build/tmp/work/i586-poky-linux/acl-2.2.51-r3
@ -771,8 +755,8 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the
<literallayout class='monospaced'> <literallayout class='monospaced'>
${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR} ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
</literallayout> </literallayout>
Again, assuming a Yocto Project Files top-level directory named <filename>poky</filename> Again, assuming top-level source directory named <filename>poky</filename>
and a default Yocto Project Build Directory of <filename>poky/build</filename>, the and a default build directory of <filename>poky/build</filename>, the
following is the work directory for the <filename>acl</filename> package that is being following is the work directory for the <filename>acl</filename> package that is being
built for a MIPS-based device: built for a MIPS-based device:
<literallayout class='monospaced'> <literallayout class='monospaced'>
@ -781,7 +765,7 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the
</para> </para>
<note> <note>
To better understand how the Yocto Project build system resolves directories during the To better understand how the OpenEmbedded build system resolves directories during the
build process, see the glossary entries for 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-WORKDIR'><filename>WORKDIR</filename></ulink>,
<ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>, <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>,
@ -817,8 +801,8 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the
Follow these general steps: Follow these general steps:
<orderedlist> <orderedlist>
<listitem><para><emphasis>Find the Source Code:</emphasis> <listitem><para><emphasis>Find the Source Code:</emphasis>
The temporary source code used by the Yocto Project build system is kept in the The temporary source code used by the OpenEmbedded build system is kept in the
Yocto Project Build Directory. build directory.
See the See the
"<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>" "<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 section to learn how to locate the directory that has the temporary source code for a
@ -875,7 +859,7 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the
<listitem><para><emphasis>Copy the Patch File:</emphasis> <listitem><para><emphasis>Copy the Patch File:</emphasis>
For simplicity, copy the patch file into a directory named <filename>files</filename>, For simplicity, copy the patch file into a directory named <filename>files</filename>,
which you can create in the same directory as the recipe. which you can create in the same directory as the recipe.
Placing the patch here guarantees that the Yocto Project build system will find Placing the patch here guarantees that the OpenEmbedded build system will find
the patch. the patch.
Next, add the patch into the Next, add the patch into the
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
@ -904,16 +888,15 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the
<note> <note>
This workflow uses Git only for its ability to manage local changes to the source code This workflow uses Git only for its ability to manage local changes to the source code
and produce patches independent of any version control used on the Yocto Project and produce patches independent of any version control system used with the Yocto Project.
Files.
</note> </note>
<para> <para>
Follow these general steps: Follow these general steps:
<orderedlist> <orderedlist>
<listitem><para><emphasis>Find the Source Code:</emphasis> <listitem><para><emphasis>Find the Source Code:</emphasis>
The temporary source code used by the Yocto Project build system is kept in the The temporary source code used by the OpenEmbedded build system is kept in the
Yocto Project Build Directory. build directory.
See the See the
"<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>" "<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 section to learn how to locate the directory that has the temporary source code for a
@ -1002,7 +985,7 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the
<listitem><para><emphasis>Copy the Patch File:</emphasis> <listitem><para><emphasis>Copy the Patch File:</emphasis>
For simplicity, copy the patch file into a directory named <filename>files</filename>, For simplicity, copy the patch file into a directory named <filename>files</filename>,
which you can create in the same directory as the recipe. which you can create in the same directory as the recipe.
Placing the patch here guarantees that the Yocto Project build system will find Placing the patch here guarantees that the OpenEmbedded build system will find
the patch. the patch.
Next, add the patch into the Next, add the patch into the
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
@ -1024,11 +1007,11 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the
<title>Image Development Using Hob</title> <title>Image Development Using Hob</title>
<para> <para>
The <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink> is a graphical user interface for the Yocto The <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink> is a graphical user interface for the
Project build system based on BitBake. 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. 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. 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 Yocto Project build tasks more easily. In other words, building images with the Hob lets you take care of common build tasks more easily.
</para> </para>
<para> <para>

221
documentation/dev-manual/dev-manual-newbie.xml
View File

@ -55,7 +55,7 @@
</section> </section>
<section id="usingpoky-changes-collaborate"> <section id="usingpoky-changes-collaborate">
<title>Using The Yocto Project in a Team Environment</title> <title>Using the Yocto Project in a Team Environment</title>
<para> <para>
It might not be immediately clear how you can use the Yocto Project in a team environment, It might not be immediately clear how you can use the Yocto Project in a team environment,
@ -97,19 +97,20 @@
<para> <para>
Most teams have many pieces of software undergoing active development at any given time. 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 You can derive large benefits by putting these pieces under the control of a source
control system that is compatible with the Yocto Project (i.e. Git or Subversion (SVN)). control system that is compatible (i.e. Git or Subversion (SVN)) with the OpenEmbeded
build system that the Yocto Project uses.
You can then set the autobuilder to pull the latest revisions of the packages You can then set the autobuilder to pull the latest revisions of the packages
and test the latest commits by the builds. and test the latest commits by the builds.
This practice quickly highlights issues. This practice quickly highlights issues.
The Yocto Project easily supports testing configurations that use both a The build system easily supports testing configurations that use both a
stable known good revision and a floating revision. stable known good revision and a floating revision.
The Yocto Project can also take just the changes from specific source control branches. The build system can also take just the changes from specific source control branches.
This capability allows you to track and test specific changes. This capability allows you to track and test specific changes.
</para> </para>
<para> <para>
Perhaps the hardest part of setting this up is defining the software project or Perhaps the hardest part of setting this up is defining the software project or
the Yocto Project metadata policies that surround the different source control systems. the metadata policies that surround the different source control systems.
Of course circumstances will be different in each case. Of course circumstances will be different in each case.
However, this situation reveals one of the Yocto Project's advantages - However, this situation reveals one of the Yocto Project's advantages -
the system itself does not the system itself does not
@ -129,7 +130,7 @@
From the interface, you can click on any particular item in the "Name" column and 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 see the URL at the bottom of the page that you need to set up a Git repository for
that particular item. that particular item.
Having a local Git repository of the Yocto Project files allows you to 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 make changes, contribute to the history, and ultimately enhance the Yocto Project's
tools, Board Support Packages, and so forth. tools, Board Support Packages, and so forth.
</para> </para>
@ -147,8 +148,8 @@
<ulink url='&YOCTO_HOME_URL;/download'>download page</ulink> and get a <ulink url='&YOCTO_HOME_URL;/download'>download page</ulink> and get a
tarball of the release. tarball of the release.
You can also go to this site to download any supported BSP tarballs. You can also go to this site to download any supported BSP tarballs.
Unpacking the tarball gives you a hierarchical directory structure of Yocto Project Unpacking the tarball gives you a hierarchical source directory that lets you develop
files that lets you develop using the Yocto Project. using the Yocto Project.
</para> </para>
<para> <para>
@ -157,22 +158,22 @@
</para> </para>
<para> <para>
In summary, here is where you can get the Yocto Project files needed for development: In summary, here is where you can get the project files needed for development:
<itemizedlist> <itemizedlist>
<listitem><para id='source-repositories'><emphasis><ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'>Source Repositories:</ulink></emphasis> <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 This area contains IDE Plugins, Matchbox, Poky, Poky Support, Tools, Yocto Linux Kernel, and Yocto
Metadata Layers. Metadata Layers.
You can create Git repositories for each of these areas.</para> You can create local copies of Git repositories for each of these areas.</para>
<para> <para>
<imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" /> <imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" />
</para></listitem> </para></listitem>
<listitem><para><anchor id='index-downloads' /><emphasis><ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink></emphasis> <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 This area contains index releases such as
the <trademark class='trade'>Eclipse</trademark> the <trademark class='trade'>Eclipse</trademark>
Yocto Plug-in, miscellaneous support, Poky, pseudo, cross-development toolchains, Yocto Plug-in, miscellaneous support, poky, pseudo, cross-development toolchains,
and all released versions of Yocto Project in the form of images or tarballs. and all released versions of Yocto Project in the form of images or tarballs.
Downloading and extracting these files does not produce a Git repository but rather Downloading and extracting these files does not produce a local copy of the
a snapshot of a particular release or image.</para> Git repository but rather a snapshot of a particular release or image.</para>
<para> <para>
<imagedata fileref="figures/index-downloads.png" align="center" width="6in" depth="4in" /> <imagedata fileref="figures/index-downloads.png" align="center" width="6in" depth="4in" />
</para></listitem> </para></listitem>
@ -199,7 +200,7 @@
<listitem><para><emphasis>Append Files:</emphasis> Files that append build information to <listitem><para><emphasis>Append Files:</emphasis> Files that append build information to
a recipe file. a recipe file.
Append files are known as BitBake append files and <filename>.bbappend</filename> files. Append files are known as BitBake append files and <filename>.bbappend</filename> files.
The Yocto Project build system expects every append file to have a corresponding and The OpenEmbedded build system expects every append file to have a corresponding and
underlying recipe (<filename>.bb</filename>) file. underlying recipe (<filename>.bb</filename>) file.
Furthermore, the append file and the underlying recipe must have the same root filename. 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. The filenames can differ only in the file type suffix used (e.g.
@ -211,9 +212,49 @@
"<link linkend='changing-recipes-kernel'>Changing <filename>recipes-kernel</filename></link>" "<link linkend='changing-recipes-kernel'>Changing <filename>recipes-kernel</filename></link>"
sections.</para></listitem> sections.</para></listitem>
<listitem><para><emphasis>BitBake:</emphasis> The task executor and scheduler used by <listitem><para><emphasis>BitBake:</emphasis> The task executor and scheduler used by
the Yocto Project to build images. the OpenEmbedded build system to build images.
For more information on BitBake, see the <ulink url='http://bitbake.berlios.de/manual/'> For more information on BitBake, see the <ulink url='http://bitbake.berlios.de/manual/'>
BitBake documentation</ulink>.</para></listitem> BitBake documentation</ulink>.</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-build-env</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-build-env
</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 <listitem><para><emphasis>Classes:</emphasis> Files that provide for logic encapsulation
and inheritance allowing commonly used patterns to be defined once and easily used and inheritance allowing commonly used patterns to be defined once and easily used
in multiple recipes. in multiple recipes.
@ -222,13 +263,14 @@
<listitem><para><emphasis>Configuration File:</emphasis> Configuration information in various <listitem><para><emphasis>Configuration File:</emphasis> Configuration information in various
<filename>.conf</filename> files provides global definitions of variables. <filename>.conf</filename> files provides global definitions of variables.
The <filename>conf/local.conf</filename> configuration file in the The <filename>conf/local.conf</filename> configuration file in the
<link linkend='yocto-project-build-directory'>Yocto Project Build Directory</link> <link linkend='build-directory'>build directory</link>
contains user-defined variables that affect each build. contains user-defined variables that affect each build.
The <filename>meta-yocto/conf/distro/poky.conf</filename> configuration file The <filename>meta-yocto/conf/distro/poky.conf</filename> configuration file
defines Yocto ‘distro’ configuration defines Yocto ‘distro’ configuration
variables used only when building with this policy. variables used only when building with this policy.
Machine configuration files, which Machine configuration files, which
are located throughout the Yocto Project file structure, define 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 variables for specific hardware and are only used when building for that target
(e.g. the <filename>machine/beagleboard.conf</filename> configuration file defines (e.g. the <filename>machine/beagleboard.conf</filename> configuration file defines
variables for the Texas Instruments ARM Cortex-A8 development board). variables for the Texas Instruments ARM Cortex-A8 development board).
@ -239,7 +281,8 @@
tools and utilities that allow you to develop software for targeted architectures. tools and utilities that allow you to develop software for targeted architectures.
This toolchain contains cross-compilers, linkers, and debuggers that are specific to This toolchain contains cross-compilers, linkers, and debuggers that are specific to
an architecture. an architecture.
You can use the Yocto Project to build cross-development toolchains in tarball form that, when You can use the OpenEmbedded build system to build cross-development toolchains in tarball
form that, when
unpacked, contain the development tools you need to cross-compile and test your software. unpacked, contain the development tools you need to cross-compile and test your software.
The Yocto Project ships with images that contain toolchains for supported architectures The Yocto Project ships with images that contain toolchains for supported architectures
as well. as well.
@ -261,19 +304,73 @@
Metadata includes recipes, classes, and configuration files.</para></listitem> Metadata includes recipes, classes, and configuration files.</para></listitem>
<listitem><para><emphasis>OE-Core:</emphasis> A core set of metadata originating <listitem><para><emphasis>OE-Core:</emphasis> A core set of metadata originating
with OpenEmbedded (OE) that is shared between OE and the Yocto Project. with OpenEmbedded (OE) that is shared between OE and the Yocto Project.
This metadata is found in the <filename>meta</filename> directory of the Yocto Project This metadata is found in the <filename>meta</filename> directory of the source
files.</para></listitem> directory.</para></listitem>
<listitem><para><emphasis>Package:</emphasis> The packaged output from a baked recipe. <listitem><para><emphasis>Package:</emphasis> The packaged output from a baked recipe.
A package is generally the compiled binaries produced from the recipe's sources. A package is generally the compiled binaries produced from the recipe's sources.
You ‘bake’ something by running it through BitBake.</para></listitem> You ‘bake’ something by running it through BitBake.</para></listitem>
<listitem><para><emphasis>Poky:</emphasis> The build tool that the Yocto Project <listitem><para id='poky'><emphasis>Poky:</emphasis> The term "poky" can mean several things.
uses to create images.</para></listitem> In its most general sence, 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 aquired 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. <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. A recipe describes where you get source code and which patches to apply.
Recipes describe dependencies for libraries or for other recipes, and they Recipes describe dependencies for libraries or for other recipes, and they
also contain configuration and compilation options. also contain configuration and compilation options.
Recipes contain the logical unit of execution, the software/images to build, and Recipes contain the logical unit of execution, the software/images to build, and
use the <filename>.bb</filename> file extension.</para></listitem> 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
<filename>poky</filename> Git repository <filename>git://git.yoctoproject.org/poky</filename>.
Sometimes you might here the term "poky directory" used to refer to this
directory structure.</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 using Git tags that are part of the repository.</para>
<para>For more information on concepts around 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. <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. 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. For example, a task could contain the recipes for a company’s proprietary or value-add software.
@ -286,84 +383,6 @@
by the maintainer of the source code. 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 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> first get a copy of it from an "upstream" source.</para></listitem>
<listitem>
<para id='yocto-project-files'><emphasis>Yocto Project Files:</emphasis>
This term refers to the directory structure created as a result of either downloading
and unpacking a Yocto Project release tarball or setting up a Git repository
by cloning <filename>git://git.yoctoproject.org/poky</filename>.
Sometimes the term "the Yocto Project Files structure" is used as well.</para>
<para>The Yocto Project Files contain BitBake, Documentation, metadata and
other files that all support the development environment.
Consequently, you must have the Yocto Project Files in place on your development
system in order to do any development using the Yocto Project.</para>
<para>The name of the top-level directory of the Yocto Project Files structure
is derived from the Yocto Project release tarball.
For example, downloading and unpacking <filename>&YOCTO_POKY_TARBALL;</filename>
results in a Yocto Project file structure whose Yocto Project source directory is named
<filename>&YOCTO_POKY;</filename>.
If you create a Git repository, then you can name the repository anything you like.
Throughout much of the documentation, the name of the Git repository is used as the
name for the local folder.
So, for example, cloning the <filename>poky</filename> Git repository results in a
local Git repository also named <filename>poky</filename>.</para>
<para>It is important to understand the differences between Yocto Project Files created
by unpacking a release 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 Yocto Project Files are on top of the release.
On the other hand, when you clone the Yocto Project Git repository, you have an
active development repository.
In this case, any local changes you make to the Yocto Project can be later applied
to active development branches of the upstream Yocto Project 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 using Git tags that are part of the repository.</para>
<para>For more information on concepts around Git repositories, branches, and tags,
see the
"<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>"
section.</para></listitem>
<listitem>
<para id='yocto-project-build-directory'><emphasis>Yocto Project Build Directory:</emphasis>
This term refers to the area used by the Yocto Project for builds.
The area is created when you <filename>source</filename> the Yocto Project setup
environment script that is found in the Yocto Project files area
(i.e. <filename>oe-init-build-env</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 Yocto Project 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'>
$ cd ~/poky
$ source oe-init-build-env
</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>
</itemizedlist> </itemizedlist>
</para> </para>
</section> </section>
@ -403,7 +422,7 @@
<filename>meta/files/common-licenses</filename>. <filename>meta/files/common-licenses</filename>.
Once the build completes, the list of all licenses found and used during that build are Once the build completes, the list of all licenses found and used during that build are
kept in the kept in the
<link linkend='yocto-project-build-directory'>Yocto Project Build Directory</link> at <link linkend='build-directory'>build directory</link> at
<filename>tmp/deploy/images/licenses</filename>. <filename>tmp/deploy/images/licenses</filename>.
</para> </para>

72
documentation/dev-manual/dev-manual-start.xml
View File

@ -24,14 +24,15 @@
<para> <para>
The Yocto Project is an open-source collaboration project focused on embedded Linux development. The Yocto Project is an open-source collaboration project focused on embedded Linux development.
The project currently provides a build system, which is sometimes referred to as "Poky", The project currently provides a build system, which is
and provides various ancillary tools suitable for the embedded developer. referred to as the OpenEmbedded build system in the Yocto Project documentation.
The Yocto Project also features the Sato reference User Interface, which is optimized for 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. stylus driven, low-resolution screens.
</para> </para>
<para> <para>
You can use the Yocto Project build system, which uses You can use the OpenEmbedded build system, which uses
<ulink url='http://bitbake.berlios.de/manual/'>BitBake</ulink>, to develop complete Linux <ulink url='http://bitbake.berlios.de/manual/'>BitBake</ulink>, to develop complete Linux
images and associated user-space applications for architectures based on ARM, MIPS, PowerPC, images and associated user-space applications for architectures based on ARM, MIPS, PowerPC,
x86 and x86-64. x86 and x86-64.
@ -53,56 +54,50 @@
<listitem><para><emphasis>Host System:</emphasis> You should have a reasonably current <listitem><para><emphasis>Host System:</emphasis> You should have a reasonably current
Linux-based host system. Linux-based host system.
You will have the best results with a recent release of Fedora, You will have the best results with a recent release of Fedora,
OpenSUSE, or Ubuntu as these releases are frequently tested against the Yocto Project OpenSUSE, Ubuntu, or CentOS as these releases are frequently tested against the Yocto Project
and officially supported. and officially supported.
You should also have about 100 gigabytes of free disk space for building images. You should also have about 100 gigabytes of free disk space for building images.
</para></listitem> </para></listitem>
<listitem><para><emphasis>Packages:</emphasis> The Yocto Project requires certain packages <listitem><para><emphasis>Packages:</emphasis> The OpenEmbedded build system
exist on your development system (e.g. Python 2.6 or 2.7). 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>" See "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>"
section in the Yocto Project Quick Start for the exact package section in the Yocto Project Quick Start for the exact package
requirements and the installation commands to install them requirements and the installation commands to install them
for the supported distributions.</para></listitem> for the supported distributions.</para></listitem>
<listitem id='local-yp-release'><para><emphasis>Yocto Project Release:</emphasis> <listitem id='local-yp-release'><para><emphasis>Yocto Project Release:</emphasis>
You need a release of the Yocto Project. You need a release of the Yocto Project.
You can get set up with local You set up a with local <link linkend='source-directory'>source directory</link>
<link linkend='yocto-project-files'>Yocto Project Files</link> one of two ways one of two ways depending on whether you
depending on whether you are going to contribute back into the Yocto Project or not.
are going to be contributing back into the Yocto Project source repository or not.
<note> <note>
Regardless of the method you use, this manual refers to the resulting Regardless of the method you use, this manual refers to the resulting local
hierarchical set of files as the "Yocto Project Files" or the "Yocto Project File hierarchical set of files as the "source directory."
Structure."
</note> </note>
<itemizedlist> <itemizedlist>
<listitem><para><emphasis>Tarball Extraction:</emphasis> If you are not going to contribute <listitem><para><emphasis>Tarball Extraction:</emphasis> If you are not going to contribute
back into the Yocto Project, you can simply download the Yocto Project release you want 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>. 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> 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; <para>For example, the following command extracts the Yocto Project &DISTRO;
release tarball release tarball
into the current working directory and sets up the Yocto Project file structure into the current working directory and sets up the local source directory
with a top-level directory named <filename>&YOCTO_POKY;</filename>: with a top-level folder named <filename>&YOCTO_POKY;</filename>:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ tar xfj &YOCTO_POKY_TARBALL; $ tar xfj &YOCTO_POKY_TARBALL;
</literallayout></para> </literallayout></para>
<para>This method does not produce a Git repository. <para>This method does not produce a local Git repository.
Instead, you simply end up with a local snapshot of the Instead, you simply end up with a snapshot of the release.</para></listitem>
Yocto Project files that are based on the particular release in the
tarball.</para></listitem>
<listitem><para><emphasis>Git Repository Method:</emphasis> If you are going to be contributing <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 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 with the latest developments, you should use Git commands to set up a local
Git repository of the Yocto Project Files. Git repository of the upstream <filename>poky</filename> source repository.
Doing so creates a Git repository with a complete history of changes and allows Doing so creates a repository with a complete history of changes and allows
you to easily submit your changes upstream to the project. you to easily submit your changes upstream to the project.
Because you cloned the repository, you have access to all the Yocto Project development Because you cloned the repository, you have access to all the Yocto Project development
branches and tag names used in the upstream repository.</para> branches and tag names used in the upstream repository.</para>
<para>The following transcript shows how to clone the Yocto Project Files' <para>The following transcript shows how to clone the <filename>poky</filename>
Git repository into the current working directory. Git repository into the current working directory.
<note>The name of the Yocto Project Files Git repository in the Yocto Project Files <note>You can view the Yocto Project Source Repositories at
Source Repositories is <filename>poky</filename>.
You can view the Yocto Project Source Repositories at
<ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink></note> <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink></note>
The command creates the local repository in a directory named <filename>poky</filename>. The command creates the local repository in a directory named <filename>poky</filename>.
For information on Git used within the Yocto Project, see the For information on Git used within the Yocto Project, see the
@ -131,7 +126,7 @@
copying that cloned repository. copying that cloned repository.
You can create the bare clone and the copy of the bare clone anywhere you like. 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 For simplicity, it is recommended that you create these structures outside of the
Yocto Project Files Git repository.</para> source directory (usually <filename>poky</filename>).</para>
<para>As an example, the following transcript shows how to create the bare clone <para>As an example, the following transcript shows how to create the bare clone
of the <filename>linux-yocto-3.2</filename> kernel and then create a copy of of the <filename>linux-yocto-3.2</filename> kernel and then create a copy of
that clone. that clone.
@ -166,15 +161,14 @@
edit to point to your locally modified kernel source files and to build the kernel edit to point to your locally modified kernel source files and to build the kernel
image. image.
Pointing to these local files is much more efficient than requiring a download of the Pointing to these local files is much more efficient than requiring a download of the
source files from upstream each time you make changes to the kernel.</para> 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 <para>You can find the <filename>poky-extras</filename> Git Repository in the
"Yocto Metadata Layers" area of the Yocto Project Source Repositories at "Yocto Metadata Layers" area of the Yocto Project Source Repositories at
<ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>. <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
It is good practice to create this Git repository inside the Yocto Project It is good practice to create this Git repository inside the source directory.</para>
files Git repository.</para>
<para>Following is an example that creates the <filename>poky-extras</filename> Git <para>Following is an example that creates the <filename>poky-extras</filename> Git
repository inside the Yocto Project files Git repository, which is named repository inside the source directory, which is named <filename>poky</filename>
<filename>poky</filename> in this case: in this case:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ git clone git://git.yoctoproject.org/poky-extras poky-extras $ git clone git://git.yoctoproject.org/poky-extras poky-extras
Initialized empty Git repository in /home/scottrif/poky/poky-extras/.git/ Initialized empty Git repository in /home/scottrif/poky/poky-extras/.git/
@ -194,7 +188,7 @@
layer. layer.
You can get set up for BSP development one of two ways: tarball extraction or You can get set up for BSP development one of two ways: tarball extraction or
with a local Git repository. with a local Git repository.
It is a good idea to use the same method used to set up the Yocto Project Files. 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 Regardless of the method you use, the Yocto Project uses the following BSP layer
naming scheme: naming scheme:
<literallayout class='monospaced'> <literallayout class='monospaced'>
@ -220,16 +214,16 @@
Again, this method just produces a snapshot of the BSP layer in the form Again, this method just produces a snapshot of the BSP layer in the form
of a hierarchical directory structure.</para></listitem> of a hierarchical directory structure.</para></listitem>
<listitem><para><emphasis>Git Repository Method:</emphasis> If you are working <listitem><para><emphasis>Git Repository Method:</emphasis> If you are working
with a Yocto Project Files Git repository, you should also use this method 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. to set up the <filename>meta-intel</filename> Git repository.
You can locate the <filename>meta-intel</filename> Git repository in the You can locate the <filename>meta-intel</filename> Git repository in the
"Yocto Metadata Layers" area of the Yocto Project Source Repositories at "Yocto Metadata Layers" area of the Yocto Project Source Repositories at
<ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para> <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para>
<para>Typically, you set up the <filename>meta-intel</filename> Git repository inside <para>Typically, you set up the <filename>meta-intel</filename> Git repository inside
the Yocto Project Files Git repository. the source directory.
For example, the following transcript shows the steps to clone the For example, the following transcript shows the steps to clone the
<filename>meta-intel</filename> <filename>meta-intel</filename>
Git repository inside the <filename>poky</filename> Git repository. Git repository inside the local <filename>poky</filename> Git repository.
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ git clone git://git.yoctoproject.org/meta-intel.git $ git clone git://git.yoctoproject.org/meta-intel.git
Initialized empty Git repository in /home/scottrif/poky/meta-intel/.git/ Initialized empty Git repository in /home/scottrif/poky/meta-intel/.git/
@ -268,13 +262,13 @@
<para> <para>
The build process is as follows: The build process is as follows:
<orderedlist> <orderedlist>
<listitem><para>Make sure you have the Yocto Project files as described in the <listitem><para>Make sure you have set up the source directory described in the
previous section.</para></listitem> previous section.</para></listitem>
<listitem><para>Initialize the build environment by sourcing a build environment <listitem><para>Initialize the build environment by sourcing a build environment
script.</para></listitem> script.</para></listitem>
<listitem><para>Optionally ensure the <filename>conf/local.conf</filename> configuration file, <listitem><para>Optionally ensure the <filename>conf/local.conf</filename> configuration file,
which is found in the which is found in the
<link linkend='yocto-project-build-directory'>Yocto Project Build Directory</link>, <link linkend='build-directory'>build directory</link>,
is set up how you want it. is set up how you want it.
This file defines many aspects of the build environment including This file defines many aspects of the build environment including
the target machine architecture through the the target machine architecture through the