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

documentation: dev-manual - Removed all trailing whitespace. 

(From yocto-docs rev: d117584a589460412a7fc4df15512b0d9c9448c7)

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-12-07 17:23:56 -06:00 committed by Richard Purdie
parent eb8c9e1494
commit 72d01bf43d
7 changed files with 2070 additions and 2070 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

File diff suppressed because it is too large Load Diff

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

@ -10,19 +10,19 @@
<para>
Welcome to the Yocto Project Development Manual!
This manual gives you an idea of how to use the Yocto Project to develop embedded Linux
images and user-space applications to run on targeted devices.
This manual gives you an idea of how to use the Yocto Project to develop embedded Linux
images and user-space applications to run on targeted devices.
Reading this manual gives you an overview of image, kernel, and user-space application development
using the Yocto Project.
using the Yocto Project.
Because much of the information in this manual is general, it contains many references to other
sources where you can find more detail.
For example, detailed information on Git, repositories and open source in general
can be found in many places.
Another example is how to get set up to use the Yocto Project, which our Yocto Project
can be found in many places.
Another example is how to get set up to use the Yocto Project, which our Yocto Project
Quick Start covers.
</para>
<para>
<para>
The Yocto Project Development Manual, however, does provide detailed examples
on how to change the kernel source code, reconfigure the kernel, and develop
an application using the popular <trademark class='trade'>Eclipse</trademark> IDE.
@ -35,15 +35,15 @@
<para>
The following list describes what you can get from this guide:
<itemizedlist>
<listitem><para>Information that lets you get set
<listitem><para>Information that lets you get set
up to develop using the Yocto Project.</para></listitem>
<listitem><para>Information to help developers who are new to the open source environment
and to the distributed revision control system Git, which the Yocto Project
<listitem><para>Information to help developers who are new to the open source environment
and to the distributed revision control system Git, which the Yocto Project
uses.</para></listitem>
<listitem><para>An understanding of common end-to-end development models and tasks.</para></listitem>
<listitem><para>Development case overviews for both system development and user-space
<listitem><para>Development case overviews for both system development and user-space
applications.</para></listitem>
<listitem><para>An overview and understanding of the emulation environment used with
<listitem><para>An overview and understanding of the emulation environment used with
the Yocto Project - the Quick EMUlator (QEMU).</para></listitem>
<listitem><para>An understanding of basic kernel architecture and concepts.</para></listitem>
<listitem><para>Many references to other sources of related information.</para></listitem>
@ -57,18 +57,18 @@
<para>
This manual will not give you the following:
<itemizedlist>
<listitem><para>Step-by-step instructions if those instructions exist in other Yocto
Project documentation.
For example, the Yocto Project Application Developer's Guide contains detailed
instruction on how to run the
<listitem><para>Step-by-step instructions if those instructions exist in other Yocto
Project documentation.
For example, the Yocto Project Application Developer's Guide contains detailed
instruction on how to run the
<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>,
which is used to set up a cross-development environment.</para></listitem>
<listitem><para>Reference material.
This type of material resides in an appropriate reference manual.
For example, system variables are documented in the
<listitem><para>Reference material.
This type of material resides in an appropriate reference manual.
For example, system variables are documented in the
<ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>.</para></listitem>
<listitem><para>Detailed public information that is not specific to the Yocto Project.
For example, exhaustive information on how to use Git is covered better through the
<listitem><para>Detailed public information that is not specific to the Yocto Project.
For example, exhaustive information on how to use Git is covered better through the
Internet than in this manual.</para></listitem>
</itemizedlist>
</para>
@ -76,56 +76,56 @@
<section id='other-information'>
<title>Other Information</title>
<para>
Because this manual presents overview information for many different topics, you will
need to supplement it with other information.
The following list presents other sources of information you might find helpful:
<itemizedlist>
<listitem><para><emphasis>The <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>:
</emphasis> The home page for the Yocto Project provides lots of information on the project
</emphasis> The home page for the Yocto Project provides lots of information on the project
as well as links to software and documentation.</para></listitem>
<listitem><para><emphasis>
<ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>:</emphasis> This short document lets you get started
<ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>:</emphasis> This short document lets you get started
with the Yocto Project quickly and start building an image.</para></listitem>
<listitem><para><emphasis>
<ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>:</emphasis> This manual is a reference
guide to the OpenEmbedded build system known as "Poky."
The manual also contains a reference chapter on Board Support Package (BSP)
<listitem><para><emphasis>
<ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>:</emphasis> This manual is a reference
guide to the OpenEmbedded build system known as "Poky."
The manual also contains a reference chapter on Board Support Package (BSP)
layout.</para></listitem>
<listitem><para><emphasis>
<ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>:</emphasis>
This guide provides information that lets you get going with the Application
Development Toolkit (ADT) and stand-alone cross-development toolchains to
This guide provides information that lets you get going with the Application
Development Toolkit (ADT) and stand-alone cross-development toolchains to
develop projects using the Yocto Project.</para></listitem>
<listitem><para><emphasis>
<ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>:</emphasis>
This guide defines the structure for BSP components.
This guide defines the structure for BSP components.
Having a commonly understood structure encourages standardization.</para></listitem>
<listitem><para><emphasis>
<ulink url='&YOCTO_DOCS_KERNEL_URL;'>Yocto Project Kernel Architecture and Use Manual</ulink>:</emphasis>
This manual describes the architecture of the Yocto Project kernel and provides
This manual describes the architecture of the Yocto Project kernel and provides
some work flow examples.</para></listitem>
<listitem><para><emphasis>
<ulink url='http://www.youtube.com/watch?v=3ZlOu-gLsh0'>
Eclipse IDE Yocto Plug-in</ulink>:</emphasis> A step-by-step instructional video that
demonstrates how an application developer uses Yocto Plug-in features within
demonstrates how an application developer uses Yocto Plug-in features within
the Eclipse IDE.</para></listitem>
<listitem><para><emphasis>
<ulink url='&YOCTO_WIKI_URL;/wiki/FAQ'>FAQ</ulink>:</emphasis>
A list of commonly asked questions and their answers.</para></listitem>
<listitem><para><emphasis>
<ulink url='&YOCTO_HOME_URL;/download/yocto/yocto-project-&DISTRO;-release-notes-poky-&POKYVERSION;'>
Release Notes</ulink>:</emphasis> Features, updates and known issues for the current
Release Notes</ulink>:</emphasis> Features, updates and known issues for the current
release of the Yocto Project.</para></listitem>
<listitem><para><emphasis>
<ulink url='&YOCTO_HOME_URL;/projects/hob'>
Hob</ulink>:</emphasis> A graphical user interface for BitBake.
Hob</ulink>:</emphasis> A graphical user interface for BitBake.
Hob's primary goal is to enable a user to perform common tasks more easily.</para></listitem>
<listitem><para><emphasis>
<ulink url='&YOCTO_HOME_URL;/documentation/build-appliance'>
Build Appliance</ulink>:</emphasis> A bootable custom embedded Linux image you can
either build using a non-Linux development system (VMware applications) or download
Build Appliance</ulink>:</emphasis> A bootable custom embedded Linux image you can
either build using a non-Linux development system (VMware applications) or download
from the Yocto Project website.
See the <ulink url='&YOCTO_HOME_URL;/documentation/build-appliance'>Build Appliance</ulink>
page for more information.</para></listitem>
@ -135,20 +135,20 @@
If you find problems with the Yocto Project, you should report them using this
application.</para></listitem>
<listitem><para><emphasis>
Yocto Project Mailing Lists:</emphasis> To subscribe to the Yocto Project mailing
Yocto Project Mailing Lists:</emphasis> To subscribe to the Yocto Project mailing
lists, click on the following URLs and follow the instructions:
<itemizedlist>
<listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> for a
<listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> for a
Yocto Project Discussions mailing list.</para></listitem>
<listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> for a
<listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> for a
Yocto Project Discussions mailing list about the Poky build system.</para></listitem>
<listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto-announce'></ulink>
for a mailing list to receive official Yocto Project announcements for developments and
as well as Yocto Project milestones.</para></listitem>
</itemizedlist></para></listitem>
<listitem><para><emphasis>Internet Relay Chat (IRC):</emphasis>
Two IRC channels on freenode are available
for Yocto Project and Poky discussions: <filename>#yocto</filename> and
Two IRC channels on freenode are available
for Yocto Project and Poky discussions: <filename>#yocto</filename> and
<filename>#poky</filename>, respectively.</para></listitem>
<listitem><para><emphasis>
<ulink url='&OH_HOME_URL;'>OpenedHand</ulink>:</emphasis>
@ -157,30 +157,30 @@
OpenedHand was acquired by Intel Corporation in 2008.</para></listitem>
<listitem><para><emphasis>
<ulink url='http://www.intel.com/'>Intel Corporation</ulink>:</emphasis>
A multinational semiconductor chip manufacturer company whose Software and
A multinational semiconductor chip manufacturer company whose Software and
Services Group created and supports the Yocto Project.
Intel acquired OpenedHand in 2008.</para></listitem>
<listitem><para><emphasis>
<ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>:</emphasis>
The build system used by the Yocto Project.
This project is the upstream, generic, embedded distribution from which the Yocto
The build system used by the Yocto Project.
This project is the upstream, generic, embedded distribution from which the Yocto
Project derives its build system (Poky) from and to which it contributes.</para></listitem>
<listitem><para><emphasis>
<ulink url='http://developer.berlios.de/projects/bitbake/'>
BitBake</ulink>:</emphasis> The tool used by the OpenEmbedded build system
BitBake</ulink>:</emphasis> The tool used by the OpenEmbedded build system
to process project metadata.</para></listitem>
<listitem><para><emphasis>
BitBake User Manual:</emphasis>
A comprehensive guide to the BitBake tool.
If you want information on BitBake, see the user manual inculded in the
<filename>bitbake/doc/manual</filename> directory of the
If you want information on BitBake, see the user manual inculded in the
<filename>bitbake/doc/manual</filename> directory of the
<link linkend='source-directory'>Source Directory</link>.</para></listitem>
<listitem><para><emphasis>
<ulink url='http://wiki.qemu.org/Index.html'>Quick EMUlator (QEMU)</ulink>:
</emphasis> An open-source machine emulator and virtualizer.</para></listitem>
</itemizedlist>
</para>
</section>
</section>
</chapter>
<!--
vim: expandtab tw=80 ts=4

232
documentation/dev-manual/dev-manual-kernel-appendix-orig.xml
View File

@ -7,16 +7,16 @@
<title>Kernel Modification Example</title>
<para>
Kernel modification involves changing or adding configurations to an existing kernel,
changing or adding recipes to the kernel that are needed to support specific hardware features,
or even altering the source code itself.
This appendix presents simple examples that modify the kernel source code,
Kernel modification involves changing or adding configurations to an existing kernel,
changing or adding recipes to the kernel that are needed to support specific hardware features,
or even altering the source code itself.
This appendix presents simple examples that modify the kernel source code,
change the kernel configuration, and add a kernel source recipe.
<note>
You can use the <filename>yocto-kernel</filename> script
found in the <link linkend='source-directory'>Source Directory</link>
under <filename>scripts</filename> to manage kernel patches and configuration.
See the "<ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'>Managing kernel Patches and Config Items with yocto-kernel</ulink>"
See the "<ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'>Managing kernel Patches and Config Items with yocto-kernel</ulink>"
section in the Yocto Project Board Support Packages (BSP) Developer's Guide for
more information.</note>
</para>
@ -25,87 +25,87 @@
<title>Modifying the Kernel Source Code</title>
<para>
This example adds some simple QEMU emulator console output at boot time by
This example adds some simple QEMU emulator console output at boot time by
adding <filename>printk</filename> statements to the kernel's
<filename>calibrate.c</filename> source code file.
Booting the modified image causes the added messages to appear on the emulator's
console.
</para>
</para>
<section id='understanding-the-files-you-need'>
<title>Understanding the Files You Need</title>
<para>
Before you modify the kernel, you need to know what Git repositories and file
Before you modify the kernel, you need to know what Git repositories and file
structures you need.
Briefly, you need the following:
Briefly, you need the following:
<itemizedlist>
<listitem><para>A local
<link linkend='source-directory'>Source Directory</link> for the
<listitem><para>A local
<link linkend='source-directory'>Source Directory</link> for the
poky Git repository</para></listitem>
<listitem><para>Local copies of the
<link linkend='poky-extras-repo'><filename>poky-extras</filename></link>
Git repository placed within the Source Directory.</para></listitem>
<listitem><para>A bare clone of the
<link linkend='local-kernel-files'>Yocto Project Kernel</link> upstream Git
Git repository placed within the Source Directory.</para></listitem>
<listitem><para>A bare clone of the
<link linkend='local-kernel-files'>Yocto Project Kernel</link> upstream Git
repository to which you want to push your modifications.
</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
modifications</para></listitem>
</itemizedlist>
</para>
<para>
The following figure summarizes these four areas.
Within each rectangular that represents a data structure, a
host development directory pathname appears at the
lower left-hand corner of the box.
<para>
The following figure summarizes these four areas.
Within each rectangular that represents a data structure, a
host development directory pathname appears at the
lower left-hand corner of the box.
These pathnames are the locations used in this example.
The figure also provides key statements and commands used during the kernel
modification process:
</para>
<para>
<imagedata fileref="figures/kernel-example-repos-generic.png" width="7in" depth="5in"
<imagedata fileref="figures/kernel-example-repos-generic.png" width="7in" depth="5in"
align="center" scale="100" />
</para>
<para>
Here is a brief description of the four areas:
<itemizedlist>
<listitem><para><emphasis>Local Source Directory:</emphasis>
This area contains all the metadata that supports building images
<listitem><para><emphasis>Local Source Directory:</emphasis>
This area contains all the metadata that supports building images
using the OpenEmbedded build system.
In this example, the
<link linkend='source-directory'>Source Directory</link> also
contains the
<link linkend='build-directory'>Build Directory</link>,
which contains the configuration directory
In this example, the
<link linkend='source-directory'>Source Directory</link> also
contains the
<link linkend='build-directory'>Build Directory</link>,
which contains the configuration directory
that lets you control the build.
Also in this example, the Source Directory contains local copies of the
Also in this example, the Source Directory contains local copies of the
<filename>poky-extras</filename> Git repository.</para>
<para>See the bulleted item
"<link linkend='local-yp-release'>Yocto Project Release</link>"
for information on how to get these files on your local system.</para></listitem>
<listitem><para><emphasis>Local copies of the&nbsp;<filename>poky-extras</filename>&nbsp;Git Repository:</emphasis>
This area contains the <filename>meta-kernel-dev</filename> layer,
<listitem><para><emphasis>Local copies of the&nbsp;<filename>poky-extras</filename>&nbsp;Git Repository:</emphasis>
This area contains the <filename>meta-kernel-dev</filename> layer,
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
local kernel source files and to identify the kernel being built.
This Git repository is a gathering place for extensions to the Yocto Project
(or really any) kernel recipes that faciliate the creation and development
of kernel features, BSPs or configurations.</para>
<para>See the bulleted item
"<link linkend='poky-extras-repo'>The
<filename>poky-extras</filename> Git Repository</link>"
for information on how to get these files.</para></listitem>
<listitem><para><emphasis>Bare Clone of the Yocto Project kernel:</emphasis>
This bare Git repository tracks the upstream Git repository of the Linux
"<link linkend='poky-extras-repo'>The
<filename>poky-extras</filename> Git Repository</link>"
for information on how to get these files.</para></listitem>
<listitem><para><emphasis>Bare Clone of the Yocto Project kernel:</emphasis>
This bare Git repository tracks the upstream Git repository of the Linux
Yocto kernel source code you are changing.
When you modify the kernel you must work through a bare clone.
All source code changes you make to the kernel must be committed and
All source code changes you make to the kernel must be committed and
pushed to the bare clone using Git commands.
As mentioned, the <filename>.bbappend</filename> file in the
As mentioned, the <filename>.bbappend</filename> file in the
<filename>poky-extras</filename> repository points to the bare clone
so that the build process can locate the locally changed source files.</para>
<para>See the bulleted item
@ -113,16 +113,16 @@
for information on how to set up the bare clone.
</para></listitem>
<listitem><para><emphasis>Copy of the Yocto Project Kernel Bare Clone:</emphasis>
This Git repository contains the actual source files that you modify.
This Git repository contains the actual source files that you modify.
Any changes you make to files in this location need to ultimately be pushed
to the bare clone using the <filename>git push</filename> command.</para>
<para>See the bulleted item
"<link linkend='local-kernel-files'>Yocto Project Kernel</link>"
for information on how to set up the bare clone.
<note>Typically, Git workflows follow a scheme where changes made to a local area
<note>Typically, Git workflows follow a scheme where changes made to a local area
are pulled into a Git repository.
However, because the <filename>git pull</filename> command does not work
with bare clones, this workflow pushes changes to the
However, because the <filename>git pull</filename> command does not work
with bare clones, this workflow pushes changes to the
repository even though you could use other more complicated methods to
get changes into the bare clone.</note>
</para></listitem>
@ -134,11 +134,11 @@
<title>Setting Up the Local Source Directory</title>
<para>
You can set up the
You can set up the
<link linkend='source-directory'>Source Directory</link>
through tarball extraction or by
cloning the <filename>poky</filename> Git repository.
This example uses <filename>poky</filename> as the root directory of the
through tarball extraction or by
cloning the <filename>poky</filename> Git repository.
This example uses <filename>poky</filename> as the root directory of the
local Source Directory.
See the bulleted item
"<link linkend='local-yp-release'>Yocto Project Release</link>"
@ -146,17 +146,17 @@
</para>
<para>
Once you have Source Directory set up,
you have many development branches from which you can work.
From inside the local repository you can see the branch names and the tag names used
Once you have Source Directory set up,
you have many development branches from which you can work.
From inside the local repository you can see the branch names and the tag names used
in the upstream Git repository by using either of the following commands:
<literallayout class='monospaced'>
$ cd poky
$ git branch -a
$ git tag -l
</literallayout>
This example uses the Yocto Project &DISTRO; Release code named "&DISTRO_NAME;",
which maps to the <filename>&DISTRO_NAME;</filename> branch in the repository.
</literallayout>
This example uses the Yocto Project &DISTRO; Release code named "&DISTRO_NAME;",
which maps to the <filename>&DISTRO_NAME;</filename> branch in the repository.
The following commands create and checkout the local <filename>&DISTRO_NAME;</filename>
branch:
<literallayout class='monospaced'>
@ -171,20 +171,20 @@
<title>Setting Up the Local poky-extras Git Repository</title>
<para>
This example creates a local copy of the <filename>poky-extras</filename> Git
This example creates a local copy of the <filename>poky-extras</filename> Git
repository inside the <filename>poky</filename> Source Directory.
See the bulleted item "<link linkend='poky-extras-repo'>The
<filename>poky-extras</filename> Git Repository</link>"
See the bulleted item "<link linkend='poky-extras-repo'>The
<filename>poky-extras</filename> Git Repository</link>"
for information on how to set up a local copy of the
<filename>poky-extras</filename> repository.
</para>
<para>
Because this example uses the Yocto Project &DISTRO; Release code
named "&DISTRO_NAME;", which maps to the <filename>&DISTRO_NAME;</filename>
branch in the repository, you need to be sure you are using that
Because this example uses the Yocto Project &DISTRO; Release code
named "&DISTRO_NAME;", which maps to the <filename>&DISTRO_NAME;</filename>
branch in the repository, you need to be sure you are using that
branch for <filename>poky-extras</filename>.
The following commands create and checkout the local
The following commands create and checkout the local
branch you are using for the <filename>&DISTRO_NAME;</filename>
branch:
<literallayout class='monospaced'>
@ -201,25 +201,25 @@
<para>
This example modifies the <filename>linux-yocto-3.4</filename> kernel.
Thus, you need to create a bare clone of that kernel and then make a copy of the
Thus, you need to create a bare clone of that kernel and then make a copy of the
bare clone.
See the bulleted item
"<link linkend='local-kernel-files'>Yocto Project Kernel</link>"
"<link linkend='local-kernel-files'>Yocto Project Kernel</link>"
for information on how to do that.
</para>
<para>
The bare clone exists for the kernel build tools and simply as the receiving end
The bare clone exists for the kernel build tools and simply as the receiving end
of <filename>git push</filename>
commands after you make edits and commits inside the copy of the clone.
The copy (<filename>my-linux-yocto-3.4-work</filename> in this example) has to have
The copy (<filename>my-linux-yocto-3.4-work</filename> in this example) has to have
a local branch created and checked out for your work.
This example uses <filename>common-pc-base</filename> as the local branch.
The following commands create and checkout the branch:
<literallayout class='monospaced'>
$ cd ~/my-linux-yocto-3.4-work
$ git checkout -b standard-common-pc-base origin/standard/common-pc/base
Branch standard-common-pc-base set up to track remote branch
Branch standard-common-pc-base set up to track remote branch
standard/common-pc/base from origin.
Switched to a new branch 'standard-common-pc-base'
</literallayout>
@ -230,22 +230,22 @@
<title>Building and Booting the Default QEMU Kernel Image</title>
<para>
Before we make changes to the kernel source files, this example first builds the
Before we make changes to the kernel source files, this example first builds the
default image and then boots it inside the QEMU emulator.
<note>
Because a full build can take hours, you should check two variables in the
<filename>build</filename> directory that is created after you source the
Because a full build can take hours, you should check two variables in the
<filename>build</filename> directory that is created after you source the
<filename>&OE_INIT_FILE;</filename> script.
You can find these variables
<filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename>
in the <filename>build/conf</filename> directory in the
in the <filename>build/conf</filename> directory in the
<filename>local.conf</filename> configuration file.
By default, these variables are commented out.
If your host development system supports multi-core and multi-thread capabilities,
you can uncomment these statements and set the variables to significantly shorten
the full build time.
As a guideline, set both <filename>BB_NUMBER_THREADS</filename> and
<filename>PARALLEL_MAKE</filename> to twice the number
As a guideline, set both <filename>BB_NUMBER_THREADS</filename> and
<filename>PARALLEL_MAKE</filename> to twice the number
of cores your machine supports.
</note>
The following two commands <filename>source</filename> the build environment setup script
@ -255,9 +255,9 @@
$ cd ~/poky
$ source &OE_INIT_FILE;
You had no conf/local.conf file. This configuration file has therefore been
created for you with some default values. You may wish to edit it to use a
different MACHINE (target hardware) or enable parallel build options to take
advantage of multiple cores for example. See the file for more information as
created for you with some default values. You may wish to edit it to use a
different MACHINE (target hardware) or enable parallel build options to take
advantage of multiple cores for example. See the file for more information as
common configuration options are commented.
The Yocto Project has extensive documentation about OE including a reference manual
@ -305,7 +305,7 @@
before starting the build.</note>
</para>
<para>
<para>
After the build completes, you can start the QEMU emulator using the resulting image
<filename>qemux86</filename> as follows:
<literallayout class='monospaced'>
@ -317,9 +317,9 @@
As the image boots in the emulator, console message and status output appears
across the terminal window.
Because the output scrolls by quickly, it is difficult to read.
To examine the output, you log into the system using the
To examine the output, you log into the system using the
login <filename>root</filename> with no password.
Once you are logged in, issue the following command to scroll through the
Once you are logged in, issue the following command to scroll through the
console output:
<literallayout class='monospaced'>
# dmesg | less
@ -360,7 +360,7 @@
</para>
<para>
Here is the altered code showing five new <filename>printk</filename> statements
Here is the altered code showing five new <filename>printk</filename> statements
near the top of the function:
<literallayout class='monospaced'>
void __cpuinit calibrate_delay(void)
@ -392,9 +392,9 @@
</para>
<para>
Once the source code has been modified, you need to use Git to push the changes to
the bare clone.
If you do not push the changes, then the OpenEmbedded build system will not pick
Once the source code has been modified, you need to use Git to push the changes to
the bare clone.
If you do not push the changes, then the OpenEmbedded build system will not pick
up the changed source files.
</para>
@ -411,43 +411,43 @@
<para>
At this point, the source has been changed and pushed.
The example now defines some variables used by the OpenEmbedded build system
The example now defines some variables used by the OpenEmbedded build system
to locate your kernel source.
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
type of machine you are building and to help speed up the build should your host support
multiple-core and thread capabilities.
</para>
<para>
Do the following to make sure the build parameters are set up for the example.
Once you set up these build parameters, they do not have to change unless you
Once you set up these build parameters, they do not have to change unless you
change the target architecture of the machine you are building or you move
the bare clone, copy of the clone, or the <filename>poky-extras</filename> repository:
<itemizedlist>
<listitem><para><emphasis>Build for the Correct Target Architecture:</emphasis> The
<filename>local.conf</filename> file in the build directory defines the build's
<listitem><para><emphasis>Build for the Correct Target Architecture:</emphasis> The
<filename>local.conf</filename> file in the build directory defines the build's
target architecture.
By default, <filename>MACHINE</filename> is set to
<filename>qemux86</filename>, which specifies a 32-bit
<trademark class='registered'>Intel</trademark> Architecture
target machine suitable for the QEMU emulator.
By default, <filename>MACHINE</filename> is set to
<filename>qemux86</filename>, which specifies a 32-bit
<trademark class='registered'>Intel</trademark> Architecture
target machine suitable for the QEMU emulator.
In this example, <filename>MACHINE</filename> is correctly configured.
</para></listitem>
<listitem><para><emphasis>Optimize Build Time:</emphasis> Also in the
<filename>local.conf</filename> file are two variables that can speed your
<listitem><para><emphasis>Optimize Build Time:</emphasis> Also in the
<filename>local.conf</filename> file are two variables that can speed your
build time if your host supports multi-core and multi-thread capabilities:
<filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename>.
If the host system has multiple cores then you can optimize build time
by setting both these variables to twice the number of
If the host system has multiple cores then you can optimize build time
by setting both these variables to twice the number of
cores.</para></listitem>
<listitem><para><emphasis>Identify Your <filename>meta-kernel-dev</filename>
Layer:</emphasis> The <filename>BBLAYERS</filename> variable in the
<filename>bblayers.conf</filename> file found in the
Layer:</emphasis> The <filename>BBLAYERS</filename> variable in the
<filename>bblayers.conf</filename> file found in the
<filename>poky/build/conf</filename> directory needs to have the path to your local
<filename>meta-kernel-dev</filename> layer.
By default, the <filename>BBLAYERS</filename> variable contains paths to
<filename>meta</filename> and <filename>meta-yocto</filename> in the
<filename>meta-kernel-dev</filename> layer.
By default, the <filename>BBLAYERS</filename> variable contains paths to
<filename>meta</filename> and <filename>meta-yocto</filename> in the
<filename>poky</filename> Git repository.
Add the path to your <filename>meta-kernel-dev</filename> location.
Be sure to substitute your user information in the statement.
@ -460,14 +460,14 @@
/home/scottrif/poky/poky-extras/meta-kernel-dev \
"
</literallayout></para></listitem>
<listitem><para><emphasis>Identify Your Source Files:</emphasis> In the
<filename>linux-yocto_3.4.bbappend</filename> file located in the
<listitem><para><emphasis>Identify Your Source Files:</emphasis> In the
<filename>linux-yocto_3.4.bbappend</filename> file located in the
<filename>poky-extras/meta-kernel-dev/recipes-kernel/linux</filename>
directory, you need to identify the location of the
directory, you need to identify the location of the
local source code, which in this example is the bare clone named
<filename>linux-yocto-3.4.git</filename>.
To do this, set the <filename>KSRC_linux_yocto</filename> variable to point to your
local <filename>linux-yocto-3.4.git</filename> Git repository by adding the
local <filename>linux-yocto-3.4.git</filename> Git repository by adding the
following statement.
Also, be sure the <filename>SRC_URI</filename> variable is pointing to
your kernel source files by removing the comment.
@ -480,20 +480,20 @@
</para>
<note>
<para>Before attempting to build the modified kernel, there is one more set of changes you
<para>Before attempting to build the modified kernel, there is one more set of changes you
need to make in the <filename>meta-kernel-dev</filename> layer.
Because all the kernel <filename>.bbappend</filename> files are parsed during the
build process regardless of whether you are using them or not, you should either
comment out the <filename>COMPATIBLE_MACHINE</filename> statements in all
unused <filename>.bbappend</filename> files, or simply remove (or rename) all the files
except the one your are using for the build
Because all the kernel <filename>.bbappend</filename> files are parsed during the
build process regardless of whether you are using them or not, you should either
comment out the <filename>COMPATIBLE_MACHINE</filename> statements in all
unused <filename>.bbappend</filename> files, or simply remove (or rename) all the files
except the one your are using for the build
(i.e. <filename>linux-yocto_3.4.bbappend</filename> in this example).</para>
<para>If you do not make one of these two adjustments, your machine will be compatible
with all the kernel recipes in the <filename>meta-kernel-dev</filename> layer.
with all the kernel recipes in the <filename>meta-kernel-dev</filename> layer.
When your machine is comapatible with all the kernel recipes, the build attempts
to build all kernels in the layer.
You could end up with build errors blocking your work.</para>
</note>
</note>
</section>
<section id='building-and-booting-the-modified-qemu-kernel-image'>
@ -511,7 +511,7 @@
$ source &OE_INIT_FILE;
</literallayout>
</para></listitem>
<listitem><para>Be sure old images are cleaned out by running the
<listitem><para>Be sure old images are cleaned out by running the
<filename>cleanall</filename> BitBake task as follows from your build directory:
<literallayout class='monospaced'>
$ bitbake -c cleanall linux-yocto
@ -524,7 +524,7 @@
<literallayout class='monospaced'>
$ bitbake -k core-image-minimal
</literallayout></para></listitem>
<listitem><para>Finally, boot the modified image in the QEMU emulator
<listitem><para>Finally, boot the modified image in the QEMU emulator
using this command:
<literallayout class='monospaced'>
$ runqemu qemux86
@ -533,7 +533,7 @@
</para>
<para>
Log into the machine using <filename>root</filename> with no password and then
Log into the machine using <filename>root</filename> with no password and then
use the following shell command to scroll through the console's boot output.
<literallayout class='monospaced'>
# dmesg | less
@ -541,7 +541,7 @@
</para>
<para>
You should see the results of your <filename>printk</filename> statements
You should see the results of your <filename>printk</filename> statements
as part of the output.
</para>
</section>

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

File diff suppressed because it is too large Load Diff

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

File diff suppressed because it is too large Load Diff

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

@ -7,14 +7,14 @@
<title>Getting Started with the Yocto Project</title>
<para>
This chapter introduces the Yocto Project and gives you an idea of what you need to get started.
You can find enough information to set up your development host and build or use images for
hardware supported by the Yocto Project by reading the
This chapter introduces the Yocto Project and gives you an idea of what you need to get started.
You can find enough information to set up your development host and build or use images for
hardware supported by the Yocto Project by reading the
<ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
</para>
<para>
The remainder of this chapter summarizes what is in the Yocto Project Quick Start and provides
The remainder of this chapter summarizes what is in the Yocto Project Quick Start and provides
some higher-level concepts you might want to consider.
</para>
@ -22,24 +22,24 @@
<title>Introducing the Yocto Project</title>
<para>
The Yocto Project is an open-source collaboration project focused on embedded Linux development.
The project currently provides a build system, which is
The Yocto Project is an open-source collaboration project focused on embedded Linux development.
The project currently provides a build system, which is
referred to as the OpenEmbedded build system in the Yocto Project documentation.
The Yocto Project provides various ancillary tools suitable for the embedded developer
and also features the Sato reference User Interface, which is optimized for
The Yocto Project provides various ancillary tools suitable for the embedded developer
and also features the Sato reference User Interface, which is optimized for
stylus driven, low-resolution screens.
</para>
<para>
You can use the OpenEmbedded build system, which uses
BitBake to develop complete Linux
images and associated user-space applications for architectures based on ARM, MIPS, PowerPC,
x86 and x86-64.
You can use the OpenEmbedded build system, which uses
BitBake to develop complete Linux
images and associated user-space applications for architectures based on ARM, MIPS, PowerPC,
x86 and x86-64.
While the Yocto Project does not provide a strict testing framework,
it does provide or generate for you artifacts that let you perform target-level and
emulated testing and debugging.
it does provide or generate for you artifacts that let you perform target-level and
emulated testing and debugging.
Additionally, if you are an <trademark class='trade'>Eclipse</trademark>
IDE user, you can install an Eclipse Yocto Plug-in to allow you to
IDE user, you can install an Eclipse Yocto Plug-in to allow you to
develop within that familiar environment.
</para>
</section>
@ -50,59 +50,59 @@
<para>
Here is what you need to get set up to use the Yocto Project:
<itemizedlist>
<listitem><para><emphasis>Host System:</emphasis> You should have a reasonably current
<listitem><para><emphasis>Host System:</emphasis> You should have a reasonably current
Linux-based host system.
You will have the best results with a recent release of Fedora,
You will have the best results with a recent release of Fedora,
OpenSUSE, Ubuntu, or CentOS as these releases are frequently tested against the Yocto Project
and officially supported.
and officially supported.
For a list of the distributions under validation and their status, see the
"<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" section
in the Yocto Project Reference Manual and the wiki page at
in the Yocto Project Reference Manual and the wiki page at
<ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink>.</para>
<para>
You should also have about 100 gigabytes of free disk space for building images.
</para></listitem>
<listitem><para><emphasis>Packages:</emphasis> The OpenEmbedded build system
requires certain packages exist on your development system (e.g. Python 2.6 or 2.7).
See "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>"
requires certain packages exist on your development system (e.g. Python 2.6 or 2.7).
See "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>"
section in the Yocto Project Quick Start for the exact package
requirements and the installation commands to install them
requirements and the installation commands to install them
for the supported distributions.</para></listitem>
<listitem id='local-yp-release'><para><emphasis>Yocto Project Release:</emphasis>
You need a release of the Yocto Project.
<listitem id='local-yp-release'><para><emphasis>Yocto Project Release:</emphasis>
You need a release of the Yocto Project.
You set up a with local <link linkend='source-directory'>Source Directory</link>
one of two ways depending on whether you
one of two ways depending on whether you
are going to contribute back into the Yocto Project or not.
<note>
Regardless of the method you use, this manual refers to the resulting local
hierarchical set of files as the "Source Directory."
</note>
<itemizedlist>
<listitem><para><emphasis>Tarball Extraction:</emphasis> If you are not going to contribute
back into the Yocto Project, you can simply download a Yocto Project release you want
<listitem><para><emphasis>Tarball Extraction:</emphasis> If you are not going to contribute
back into the Yocto Project, you can simply download a Yocto Project release you want
from the website’s <ulink url='&YOCTO_HOME_URL;/download'>download page</ulink>.
Once you have the tarball, just extract it into a directory of your choice.</para>
<para>For example, the following command extracts the Yocto Project &DISTRO;
release tarball
<para>For example, the following command extracts the Yocto Project &DISTRO;
release tarball
into the current working directory and sets up the local Source Directory
with a top-level folder named <filename>&YOCTO_POKY;</filename>:
<literallayout class='monospaced'>
$ tar xfj &YOCTO_POKY_TARBALL;
</literallayout></para>
<para>This method does not produce a local Git repository.
<para>This method does not produce a local Git repository.
Instead, you simply end up with a snapshot of the release.</para></listitem>
<listitem><para><emphasis>Git Repository Method:</emphasis> If you are going to be contributing
back into the Yocto Project or you simply want to keep up
with the latest developments, you should use Git commands to set up a local
Git repository of the upstream <filename>poky</filename> source repository.
Doing so creates a repository with a complete history of changes and allows
Doing so creates a repository with a complete history of changes and allows
you to easily submit your changes upstream to the project.
Because you cloned the repository, you have access to all the Yocto Project development
branches and tag names used in the upstream repository.</para>
<para>The following transcript shows how to clone the <filename>poky</filename>
<para>The following transcript shows how to clone the <filename>poky</filename>
Git repository into the current working directory.
<note>You can view the Yocto Project Source Repositories at
<ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink></note>
<ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink></note>
The command creates the local repository in a directory named <filename>poky</filename>.
For information on Git used within the Yocto Project, see the
"<link linkend='git'>Git</link>" section.
@ -120,27 +120,27 @@
wiki page</ulink>, which describes how to create both <filename>poky</filename>
and <filename>meta-intel</filename> Git repositories.</para></listitem>
</itemizedlist></para></listitem>
<listitem id='local-kernel-files'><para><emphasis>Yocto Project Kernel:</emphasis>
If you are going to be making modifications to a supported Yocto Project kernel, you
<listitem id='local-kernel-files'><para><emphasis>Yocto Project Kernel:</emphasis>
If you are going to be making modifications to a supported Yocto Project kernel, you
need to establish local copies of the source.
You can find Git repositories of supported Yocto Project Kernels organized under
"Yocto Linux Kernel" in the Yocto Project Source Repositories at
<ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para>
<para>This setup can involve creating a bare clone of the Yocto Project kernel and then
<para>This setup can involve creating a bare clone of the Yocto Project kernel and then
copying that cloned repository.
You can create the bare clone and the copy of the bare clone anywhere you like.
For simplicity, it is recommended that you create these structures outside of the
For simplicity, it is recommended that you create these structures outside of the
Source Directory (usually <filename>poky</filename>).</para>
<para>As an example, the following transcript shows how to create the bare clone
of the <filename>linux-yocto-3.4</filename> kernel and then create a copy of
of the <filename>linux-yocto-3.4</filename> kernel and then create a copy of
that clone.
<note>When you have a local Yocto Project kernel Git repository, you can
reference that repository rather than the upstream Git repository as
<note>When you have a local Yocto Project kernel Git repository, you can
reference that repository rather than the upstream Git repository as
part of the <filename>clone</filename> command.
Doing so can speed up the process.</note></para>
<para>In the following example, the bare clone is named
<filename>linux-yocto-3.4.git</filename>, while the
copy is named <filename>my-linux-yocto-3.4-work</filename>:
<para>In the following example, the bare clone is named
<filename>linux-yocto-3.4.git</filename>, while the
copy is named <filename>my-linux-yocto-3.4-work</filename>:
<literallayout class='monospaced'>
$ git clone --bare git://git.yoctoproject.org/linux-yocto-3.4 linux-yocto-3.4.git
Initialized empty Git repository in /home/scottrif/linux-yocto-3.4.git/
@ -158,20 +158,20 @@
</literallayout></para></listitem>
<listitem id='poky-extras-repo'><para><emphasis>
The <filename>poky-extras</filename> Git Repository</emphasis>:
The <filename>poky-extras</filename> Git repository contains metadata needed
The <filename>poky-extras</filename> Git repository contains metadata needed
only if you are modifying and building the kernel image.
In particular, it contains the kernel BitBake append (<filename>.bbappend</filename>)
files that you
files that you
edit to point to your locally modified kernel source files and to build the kernel
image.
Pointing to these local files is much more efficient than requiring a download of the
image.
Pointing to these local files is much more efficient than requiring a download of the
kernel's source files from upstream each time you make changes to the kernel.</para>
<para>You can find the <filename>poky-extras</filename> Git Repository in the
"Yocto Metadata Layers" area of the Yocto Project Source Repositories at
<para>You can find the <filename>poky-extras</filename> Git Repository in the
"Yocto Metadata Layers" area of the Yocto Project Source Repositories at
<ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
It is good practice to create this Git repository inside the Source Directory.</para>
<para>Following is an example that creates the <filename>poky-extras</filename> Git
repository inside the Source Directory, which is named <filename>poky</filename>
<para>Following is an example that creates the <filename>poky-extras</filename> Git
repository inside the Source Directory, which is named <filename>poky</filename>
in this case:
<literallayout class='monospaced'>
$ cd ~/poky
@ -183,21 +183,21 @@
Receiving objects: 100% (618/618), 526.26 KiB | 111 KiB/s, done.
Resolving deltas: 100% (192/192), done.
</literallayout></para></listitem>
<listitem><para id='supported-board-support-packages-(bsps)'><emphasis>Supported Board
Support Packages (BSPs):</emphasis>
The Yocto Project provides a layer called <filename>meta-intel</filename> and
<listitem><para id='supported-board-support-packages-(bsps)'><emphasis>Supported Board
Support Packages (BSPs):</emphasis>
The Yocto Project provides a layer called <filename>meta-intel</filename> and
it is maintained in its own separate Git repository.
The <filename>meta-intel</filename> layer contains many supported
The <filename>meta-intel</filename> layer contains many supported
<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>.</para>
<para>Similar considerations exist for setting up the <filename>meta-intel</filename>
layer.
layer.
You can get set up for BSP development one of two ways: tarball extraction or
with a local Git repository.
It is a good idea to use the same method that you used to set up the Source Directory.
Regardless of the method you use, the Yocto Project uses the following BSP layer
Regardless of the method you use, the Yocto Project uses the following BSP layer
naming scheme:
<literallayout class='monospaced'>
meta-&lt;BSP_name&gt;
<literallayout class='monospaced'>
meta-&lt;BSP_name&gt;
</literallayout>
where <filename>&lt;BSP_name&gt;</filename> is the recognized BSP name.
Here are some examples:
@ -211,22 +211,22 @@
section in the Yocto Project Board Support Package (BSP) Developer's Guide for more
information on BSP Layers.
<itemizedlist>
<listitem><para><emphasis>Tarball Extraction:</emphasis> You can download any released
BSP tarball from the same
<ulink url='&YOCTO_HOME_URL;/download'>download site</ulink> used
to get the Yocto Project release.
<listitem><para><emphasis>Tarball Extraction:</emphasis> You can download any released
BSP tarball from the same
<ulink url='&YOCTO_HOME_URL;/download'>download site</ulink> used
to get the Yocto Project release.
Once you have the tarball, just extract it into a directory of your choice.
Again, this method just produces a snapshot of the BSP layer in the form
of a hierarchical directory structure.</para></listitem>
<listitem><para><emphasis>Git Repository Method:</emphasis> If you are working
with a local Git repository for your Source Directory, you should also use this method
<listitem><para><emphasis>Git Repository Method:</emphasis> If you are working
with a local Git repository for your Source Directory, you should also use this method
to set up the <filename>meta-intel</filename> Git repository.
You can locate the <filename>meta-intel</filename> Git repository in the
You can locate the <filename>meta-intel</filename> Git repository in the
"Yocto Metadata Layers" area of the Yocto Project Source Repositories at
<ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para>
<para>Typically, you set up the <filename>meta-intel</filename> Git repository inside
the Source Directory.
For example, the following transcript shows the steps to clone the
For example, the following transcript shows the steps to clone the
<filename>meta-intel</filename>
Git repository inside the local <filename>poky</filename> Git repository.
<literallayout class='monospaced'>
@ -239,15 +239,15 @@
Receiving objects: 100% (3380/3380), 1.77 MiB | 128 KiB/s, done.
Resolving deltas: 100% (1689/1689), done.
</literallayout></para>
<para>The same
<para>The same
<ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'>
wiki page</ulink> referenced earlier covers how to
wiki page</ulink> referenced earlier covers how to
set up the <filename>meta-intel</filename> Git repository.</para></listitem>
</itemizedlist></para></listitem>
<listitem><para><emphasis>Eclipse Yocto Plug-in:</emphasis> If you are developing
<listitem><para><emphasis>Eclipse Yocto Plug-in:</emphasis> If you are developing
applications using the Eclipse Integrated Development Environment (IDE),
you will need this plug-in.
See the
you will need this plug-in.
See the
"<link linkend='setting-up-the-eclipse-ide'>Setting up the Eclipse IDE</link>"
section for more information.</para></listitem>
</itemizedlist>
@ -258,8 +258,8 @@
<title>Building Images</title>
<para>
The build process creates an entire Linux distribution, including the toolchain, from source.
For more information on this topic, see the
The build process creates an entire Linux distribution, including the toolchain, from source.
For more information on this topic, see the
"<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
section in the Yocto Project Quick Start.
</para>
@ -267,27 +267,27 @@
<para>
The build process is as follows:
<orderedlist>
<listitem><para>Make sure you have set up the Source Directory described in the
<listitem><para>Make sure you have set up the Source Directory described in the
previous section.</para></listitem>
<listitem><para>Initialize the build environment by sourcing a build environment
<listitem><para>Initialize the build environment by sourcing a build environment
script.</para></listitem>
<listitem><para>Optionally ensure the <filename>conf/local.conf</filename> configuration file,
which is found in the
<link linkend='build-directory'>Build Directory</link>,
is set up how you want it.
This file defines many aspects of the build environment including
the target machine architecture through the
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'>MACHINE</ulink></filename> variable,
the development machine's processor use through the
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</ulink></filename> and
which is found in the
<link linkend='build-directory'>Build Directory</link>,
is set up how you want it.
This file defines many aspects of the build environment including
the target machine architecture through the
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'>MACHINE</ulink></filename> variable,
the development machine's processor use through the
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</ulink></filename> and
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'>PARALLEL_MAKE</ulink></filename> variables, and
a centralized tarball download directory through the
a centralized tarball download directory through the
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'>DL_DIR</ulink></filename> variable.</para></listitem>
<listitem><para>Build the image using the <filename>bitbake</filename> command.
If you want information on BitBake, see the user manual inculded in the
<filename>bitbake/doc/manual</filename> directory of the
If you want information on BitBake, see the user manual inculded in the
<filename>bitbake/doc/manual</filename> directory of the
<link linkend='source-directory'>Source Directory</link>.</para></listitem>
<listitem><para>Run the image either on the actual hardware or using the QEMU
<listitem><para>Run the image either on the actual hardware or using the QEMU
emulator.</para></listitem>
</orderedlist>
</para>
@ -297,8 +297,8 @@
<title>Using Pre-Built Binaries and QEMU</title>
<para>
Another option you have to get started is to use pre-built binaries.
The Yocto Project provides many types of binaries with each release.
Another option you have to get started is to use pre-built binaries.
The Yocto Project provides many types of binaries with each release.
See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
chapter in the Yocto Project Reference Manual
for descriptions of the types of binaries that ship with a Yocto Project
@ -306,51 +306,51 @@
</para>
<para>
Using a pre-built binary is ideal for developing software applications to run on your
target hardware.
To do this, you need to be able to access the appropriate cross-toolchain tarball for
the architecture on which you are developing.
If you are using an SDK type image, the image ships with the complete toolchain native to
the architecture.
If you are not using an SDK type image, you need to separately download and
Using a pre-built binary is ideal for developing software applications to run on your
target hardware.
To do this, you need to be able to access the appropriate cross-toolchain tarball for
the architecture on which you are developing.
If you are using an SDK type image, the image ships with the complete toolchain native to
the architecture.
If you are not using an SDK type image, you need to separately download and
install the stand-alone Yocto Project cross-toolchain tarball.
</para>
<para>
Regardless of the type of image you are using, you need to download the pre-built kernel
that you will boot in the QEMU emulator and then download and extract the target root
Regardless of the type of image you are using, you need to download the pre-built kernel
that you will boot in the QEMU emulator and then download and extract the target root
filesystem for your target machine’s architecture.
You can get architecture-specific binaries and filesystems from
<ulink url='&YOCTO_MACHINES_DL_URL;'>machines</ulink>.
You can get installation scripts for stand-alone toolchains from
<ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchains</ulink>.
Once you have all your files, you set up the environment to emulate the hardware
by sourcing an environment setup script.
Once you have all your files, you set up the environment to emulate the hardware
by sourcing an environment setup script.
Finally, you start the QEMU emulator.
You can find details on all these steps in the
You can find details on all these steps in the
"<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>"
section of the Yocto Project Quick Start.
section of the Yocto Project Quick Start.
</para>
<para>
<para>
Using QEMU to emulate your hardware can result in speed issues
depending on the target and host architecture mix.
For example, using the <filename>qemux86</filename> image in the emulator
on an Intel-based 32-bit (x86) host machine is fast because the target and
For example, using the <filename>qemux86</filename> image in the emulator
on an Intel-based 32-bit (x86) host machine is fast because the target and
host architectures match.
On the other hand, using the <filename>qemuarm</filename> image on the same Intel-based
host can be slower.
But, you still achieve faithful emulation of ARM-specific issues.
But, you still achieve faithful emulation of ARM-specific issues.
</para>
<para>
To speed things up, the QEMU images support using <filename>distcc</filename>
to call a cross-compiler outside the emulated system.
to call a cross-compiler outside the emulated system.
If you used <filename>runqemu</filename> to start QEMU, and the
<filename>distccd</filename> application is present on the host system, any
<filename>distccd</filename> application is present on the host system, any
BitBake cross-compiling toolchain available from the build system is automatically
used from within QEMU simply by calling <filename>distcc</filename>.
You can accomplish this by defining the cross-compiler variable
You can accomplish this by defining the cross-compiler variable
(e.g. <filename>export CC="distcc"</filename>).
Alternatively, if you are using a suitable SDK image or the appropriate
stand-alone toolchain is present in <filename>/opt/poky</filename>,
@ -358,27 +358,27 @@
</para>
<note>
Several mechanisms exist that let you connect to the system running on the
Several mechanisms exist that let you connect to the system running on the
QEMU emulator:
<itemizedlist>
<listitem><para>QEMU provides a framebuffer interface that makes standard
<listitem><para>QEMU provides a framebuffer interface that makes standard
consoles available.</para></listitem>
<listitem><para>Generally, headless embedded devices have a serial port.
If so, you can configure the operating system of the running image
to use that port to run a console.
to use that port to run a console.
The connection uses standard IP networking.</para></listitem>
<listitem><para>SSH servers exist in some QEMU images.
The <filename>core-image-sato</filename> QEMU image has a Dropbear secure
The <filename>core-image-sato</filename> QEMU image has a Dropbear secure
shell (ssh) server that runs with the root password disabled.
The <filename>core-image-basic</filename> and <filename>core-image-lsb</filename> QEMU images
The <filename>core-image-basic</filename> and <filename>core-image-lsb</filename> QEMU images
have OpenSSH instead of Dropbear.
Including these SSH servers allow you to use standard <filename>ssh</filename> and
Including these SSH servers allow you to use standard <filename>ssh</filename> and
<filename>scp</filename> commands.
The <filename>core-image-minimal</filename> QEMU image, however, contains no ssh
The <filename>core-image-minimal</filename> QEMU image, however, contains no ssh
server.</para></listitem>
<listitem><para>You can use a provided, user-space NFS server to boot the QEMU session
<listitem><para>You can use a provided, user-space NFS server to boot the QEMU session
using a local copy of the root filesystem on the host.
In order to make this connection, you must extract a root filesystem tarball by using the
In order to make this connection, you must extract a root filesystem tarball by using the
<filename>runqemu-extract-sdk</filename> command.
After running the command, you must then point the <filename>runqemu</filename>
script to the extracted directory instead of a root filesystem image file.</para></listitem>

18
documentation/dev-manual/dev-manual.xml
View File

@ -2,7 +2,7 @@
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
<book id='dev-manual' lang='en'
<book id='dev-manual' lang='en'
xmlns:xi="http://www.w3.org/2003/XInclude"
xmlns="http://docbook.org/ns/docbook"
>
@ -10,13 +10,13 @@
<mediaobject>
<imageobject>
<imagedata fileref='figures/dev-title.png'
format='SVG'
<imagedata fileref='figures/dev-title.png'
format='SVG'
align='left' scalefit='1' width='100%'/>
</imageobject>
</imageobject>
</mediaobject>
<title></title>
<title></title>
<authorgroup>
<author>
@ -58,9 +58,9 @@
<legalnotice>
<para>
Permission is granted to copy, distribute and/or modify this document under
Permission is granted to copy, distribute and/or modify this document under
the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">
Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by
Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by
Creative Commons.
</para>
@ -86,6 +86,6 @@
<xi:include href="dev-manual-common-tasks.xml"/>
</book>
<!--
vim: expandtab tw=80 ts=4
<!--
vim: expandtab tw=80 ts=4
-->