2011-07-15 19:54:29 +00:00
|
|
|
|
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
2012-03-09 19:40:39 +00:00
|
|
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
|
|
|
|
|
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
|
2011-07-15 19:54:29 +00:00
|
|
|
|
|
|
|
|
|
<chapter id='dev-manual-model'>
|
|
|
|
|
|
|
|
|
|
<title>Common Development Models</title>
|
|
|
|
|
|
2011-07-27 19:47:59 +00:00
|
|
|
|
<para>
|
|
|
|
|
Many development models exist for which you can use the Yocto Project.
|
2012-06-12 14:48:52 +00:00
|
|
|
|
This chapter overviews the following methods:
|
|
|
|
|
<itemizedlist>
|
|
|
|
|
<listitem><para><emphasis>System Development:</emphasis>
|
|
|
|
|
System Development covers Board Support Package (BSP) development and kernel
|
|
|
|
|
modification or configuration.
|
|
|
|
|
If you want to examine specific examples of the system development models,
|
|
|
|
|
see the "<link linkend='dev-manual-bsp-appendix'>BSP Development Example</link>"
|
|
|
|
|
appendix and the
|
|
|
|
|
"<link linkend='dev-manual-kernel-appendix'>Kernel Modification Example</link>" appendix.
|
|
|
|
|
</para></listitem>
|
|
|
|
|
<listitem><para><emphasis>User Application Development:</emphasis>
|
|
|
|
|
User Application Development covers development of applications that you intend
|
|
|
|
|
to run on some target hardware.
|
|
|
|
|
For a user-space application development example that uses the
|
|
|
|
|
<trademark class='trade'>Eclipse</trademark> IDE,
|
|
|
|
|
see the
|
|
|
|
|
<ulink url='&YOCTO_DOCS_ADT_URL;'>
|
|
|
|
|
The Yocto Project Application Development Toolkit (ADT) User's Guide</ulink>.
|
|
|
|
|
</para></listitem>
|
|
|
|
|
<listitem><para><emphasis>Temporary Source Code Modification:</emphasis>
|
|
|
|
|
Direct modification of temporary source code is a convenient development model
|
|
|
|
|
to quickly iterate and develop towards a solution.
|
|
|
|
|
Once the solution has been implemented, you should of course take steps to
|
|
|
|
|
get the changes upstream and applied in the affected recipes.</para></listitem>
|
|
|
|
|
<listitem><para><emphasis>Image Development using Hob:</emphasis>
|
|
|
|
|
You can use the <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink> to build
|
2012-07-02 16:59:11 +00:00
|
|
|
|
custom operating system images within the build environment.
|
|
|
|
|
Hob provides an efficient interface to the OpenEmbedded build system.</para></listitem>
|
2012-07-13 20:43:30 +00:00
|
|
|
|
<listitem><para><emphasis>Using a Development Shell:</emphasis>
|
|
|
|
|
You can use a <filename>devshell</filename> to efficiently debug commands or simply
|
|
|
|
|
edit packages.
|
|
|
|
|
Working inside a development shell is a quick way to set up the OpenEmbedded build
|
|
|
|
|
environment to work on parts of a project.</para></listitem>
|
2012-06-12 14:48:52 +00:00
|
|
|
|
</itemizedlist>
|
2012-03-22 20:58:20 +00:00
|
|
|
|
</para>
|
|
|
|
|
|
2011-07-27 19:47:59 +00:00
|
|
|
|
<section id='system-development-model'>
|
2012-03-22 21:09:03 +00:00
|
|
|
|
<title>System Development Workflow</title>
|
2011-07-15 20:17:07 +00:00
|
|
|
|
|
|
|
|
|
<para>
|
2011-07-27 19:47:59 +00:00
|
|
|
|
System development involves modification or creation of an image that you want to run on
|
|
|
|
|
a specific hardware target.
|
2011-09-20 17:26:58 +00:00
|
|
|
|
Usually, when you want to create an image that runs on embedded hardware, the image does
|
2011-11-02 20:37:32 +00:00
|
|
|
|
not require the same number of features that a full-fledged Linux distribution provides.
|
|
|
|
|
Thus, you can create a much smaller image that is designed to use only the hardware
|
2011-07-27 19:47:59 +00:00
|
|
|
|
features for your particular hardware.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
To help you understand how system development works in the Yocto Project, this section
|
2011-09-20 17:26:58 +00:00
|
|
|
|
covers two types of image development: BSP creation and kernel modification or
|
|
|
|
|
configuration.
|
2011-07-15 20:17:07 +00:00
|
|
|
|
</para>
|
|
|
|
|
|
2011-07-27 19:59:59 +00:00
|
|
|
|
<section id='developing-a-board-support-package-bsp'>
|
2011-07-27 19:10:25 +00:00
|
|
|
|
<title>Developing a Board Support Package (BSP)</title>
|
2011-07-15 20:17:07 +00:00
|
|
|
|
|
2011-07-27 19:10:25 +00:00
|
|
|
|
<para>
|
2012-06-12 14:48:52 +00:00
|
|
|
|
A BSP is a packageof recipes that, when applied, during a build results in
|
2011-11-10 21:28:32 +00:00
|
|
|
|
an image that you can run on a particular board.
|
2011-07-27 19:10:25 +00:00
|
|
|
|
Thus, the package, when compiled into the new image, supports the operation of the board.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<note>
|
|
|
|
|
For a brief list of terms used when describing the development process in the Yocto Project,
|
2011-09-20 17:26:58 +00:00
|
|
|
|
see the "<link linkend='yocto-project-terms'>Yocto Project Terms</link>" section.
|
2011-07-27 19:10:25 +00:00
|
|
|
|
</note>
|
|
|
|
|
|
|
|
|
|
<para>
|
2011-11-10 21:28:32 +00:00
|
|
|
|
The remainder of this section presents the basic steps used to create a BSP
|
|
|
|
|
based on an existing BSP that ships with the Yocto Project.
|
2011-09-20 17:26:58 +00:00
|
|
|
|
You can reference the "<link linkend='dev-manual-bsp-appendix'>BSP Development Example</link>"
|
|
|
|
|
appendix for a detailed example that uses the Crown Bay BSP as a base BSP from which to start.
|
2011-07-27 19:10:25 +00:00
|
|
|
|
</para>
|
|
|
|
|
|
2011-07-27 22:04:14 +00:00
|
|
|
|
<para>
|
2011-09-20 17:26:58 +00:00
|
|
|
|
The following illustration and list summarize the BSP creation general workflow.
|
2011-07-27 22:04:14 +00:00
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
2011-08-10 21:42:29 +00:00
|
|
|
|
<imagedata fileref="figures/bsp-dev-flow.png" width="6in" depth="7in" align="center" scalefit="1" />
|
2011-07-27 22:04:14 +00:00
|
|
|
|
</para>
|
|
|
|
|
|
2011-07-27 19:10:25 +00:00
|
|
|
|
<para>
|
|
|
|
|
<orderedlist>
|
|
|
|
|
<listitem><para><emphasis>Set up your host development system to support
|
2011-09-20 17:26:58 +00:00
|
|
|
|
development using the Yocto Project</emphasis>: See the
|
2012-03-09 19:40:39 +00:00
|
|
|
|
"<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distributions</ulink>"
|
|
|
|
|
and the
|
|
|
|
|
"<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both
|
2011-08-02 20:00:48 +00:00
|
|
|
|
in the Yocto Project Quick Start for requirements.</para></listitem>
|
2012-07-02 16:59:11 +00:00
|
|
|
|
<listitem><para><emphasis>Establish a local copy of the project files on your
|
|
|
|
|
system</emphasis>: You need this <link linkend='source-directory'>source
|
|
|
|
|
directory</link> available on your host system.
|
|
|
|
|
Having these files on your system gives you access to the build
|
2011-11-10 21:28:32 +00:00
|
|
|
|
process and to the tools you need.
|
2012-07-02 16:59:11 +00:00
|
|
|
|
For information on how to set up the source directory, see the
|
2011-09-20 17:26:58 +00:00
|
|
|
|
"<link linkend='getting-setup'>Getting Setup</link>" section.</para></listitem>
|
2011-08-01 21:39:35 +00:00
|
|
|
|
<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
|
2011-11-10 21:28:32 +00:00
|
|
|
|
process and to the tools you need for creating a BSP.
|
2011-09-20 17:26:58 +00:00
|
|
|
|
For information on how to get these files, see the
|
|
|
|
|
"<link linkend='getting-setup'>Getting Setup</link>" section.</para></listitem>
|
2012-07-02 16:59:11 +00:00
|
|
|
|
<listitem><para><emphasis>Choose a BSP that is supported by the Yocto Project
|
|
|
|
|
as your base BSP</emphasis>:
|
2011-07-27 19:10:25 +00:00
|
|
|
|
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
|
|
|
|
|
recipes and configuration files from scratch.
|
|
|
|
|
While it is possible to create everything from scratch, basing your new BSP
|
|
|
|
|
on something that is close is much easier.
|
2011-09-20 17:26:58 +00:00
|
|
|
|
Or, at a minimum, leveraging off an existing BSP
|
|
|
|
|
gives you some structure with which to start.</para>
|
2011-07-27 19:10:25 +00:00
|
|
|
|
<para>At this point you need to understand your target hardware well enough to determine which
|
|
|
|
|
existing BSP it most closely matches.
|
2011-09-20 17:26:58 +00:00
|
|
|
|
Things to consider are your hardware’s on-board features, such as CPU type and graphics support.
|
2011-07-27 19:10:25 +00:00
|
|
|
|
You should look at the README files for supported BSPs to get an idea of which one
|
|
|
|
|
you could use.
|
2011-09-20 17:26:58 +00:00
|
|
|
|
A generic <trademark class='registered'>Intel</trademark>
|
|
|
|
|
<trademark class='trade'>Atom</trademark>-based BSP to consider is the
|
|
|
|
|
Crown Bay that does not support the <trademark class='registered'>Intel</trademark>
|
|
|
|
|
Embedded Media Graphics Driver (EMGD).
|
2011-07-27 19:10:25 +00:00
|
|
|
|
The remainder of this example uses that base BSP.</para>
|
2012-04-26 13:08:13 +00:00
|
|
|
|
<para>To see the supported BSPs, go to the
|
|
|
|
|
<ulink url='&YOCTO_HOME_URL;/download'>Download</ulink> page on the Yocto Project
|
|
|
|
|
website and click on “BSP Downloads.”</para></listitem>
|
2011-07-27 19:10:25 +00:00
|
|
|
|
<listitem><para><emphasis>Create your own BSP layer</emphasis>: Layers are ideal for
|
2011-08-01 21:39:35 +00:00
|
|
|
|
isolating and storing work for a given piece of hardware.
|
2012-04-26 14:01:25 +00:00
|
|
|
|
A layer is really just a location or area in which you place the recipes for your BSP.
|
2011-07-27 19:10:25 +00:00
|
|
|
|
In fact, a BSP is, in itself, a special type of layer.
|
2012-04-26 14:01:25 +00:00
|
|
|
|
</para>
|
|
|
|
|
<para>
|
2011-09-20 17:26:58 +00:00
|
|
|
|
Another example that illustrates a layer is an application.
|
2011-07-27 19:10:25 +00:00
|
|
|
|
Suppose you are creating an application that has library or other dependencies in
|
|
|
|
|
order for it to compile and run.
|
|
|
|
|
The layer, in this case, would be where all the recipes that define those dependencies
|
2011-09-20 17:26:58 +00:00
|
|
|
|
are kept.
|
|
|
|
|
The key point for a layer is that it is an isolated area that contains
|
2012-07-02 16:59:11 +00:00
|
|
|
|
all the relevant information for the project that the OpenEmbedded build
|
2012-04-26 14:01:25 +00:00
|
|
|
|
system knows about.
|
|
|
|
|
For more information on layers, see the
|
|
|
|
|
"<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>"
|
|
|
|
|
section.
|
|
|
|
|
For more information on BSP layers, see the
|
|
|
|
|
"<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" section in the
|
|
|
|
|
Yocto Project Board Support Package (BSP) Developer's Guide.</para>
|
2012-07-02 16:59:11 +00:00
|
|
|
|
<note>Four BSPs exist that are part of the
|
2011-08-01 21:39:35 +00:00
|
|
|
|
Yocto Project release: <filename>atom-pc</filename>, <filename>beagleboard</filename>,
|
|
|
|
|
<filename>mpc8315e</filename>, and <filename>routerstationpro</filename>.
|
2011-07-27 19:10:25 +00:00
|
|
|
|
The recipes and configurations for these four BSPs are located and dispersed
|
2012-07-02 16:59:11 +00:00
|
|
|
|
within the <link linkend='source-directory'>source directory</link>.
|
2011-07-27 19:10:25 +00:00
|
|
|
|
On the other hand, BSP layers for Crown Bay, Emenlow, Jasper Forest,
|
2012-04-26 14:01:25 +00:00
|
|
|
|
N450, Cedar Trail, Fish River, Fish River Island II, Romley, sys940x, tlk,
|
|
|
|
|
and Sugar Bay exist in their own separate layers within the larger
|
|
|
|
|
<filename>meta-intel</filename> layer.</note>
|
2011-09-20 17:26:58 +00:00
|
|
|
|
<para>When you set up a layer for a new BSP, you should follow a standard layout.
|
|
|
|
|
This layout is described in the section
|
2012-03-09 19:40:39 +00:00
|
|
|
|
"<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout'>Example Filesystem Layout</ulink>"
|
|
|
|
|
section of the Board Support Package (BSP) Development Guide.
|
2011-09-20 17:26:58 +00:00
|
|
|
|
In the standard layout, you will notice a suggested structure for recipes and
|
2011-07-27 19:10:25 +00:00
|
|
|
|
configuration information.
|
|
|
|
|
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
|
2012-07-02 16:59:11 +00:00
|
|
|
|
source directory.</para></listitem>
|
2011-08-01 21:39:35 +00:00
|
|
|
|
<listitem><para><emphasis>Make configuration changes to your new BSP
|
2012-03-09 19:40:39 +00:00
|
|
|
|
layer</emphasis>: The standard BSP layer structure organizes the files you need
|
|
|
|
|
to edit in <filename>conf</filename> and several <filename>recipes-*</filename>
|
|
|
|
|
directories within the BSP layer.
|
2011-08-01 21:39:35 +00:00
|
|
|
|
Configuration changes identify where your new layer is on the local system
|
2011-07-27 19:10:25 +00:00
|
|
|
|
and identify which kernel you are going to use.
|
2011-08-01 21:39:35 +00:00
|
|
|
|
</para></listitem>
|
|
|
|
|
<listitem><para><emphasis>Make recipe changes to your new BSP layer</emphasis>: Recipe
|
|
|
|
|
changes include altering recipes (<filename>.bb</filename> files), removing
|
2011-07-27 19:10:25 +00:00
|
|
|
|
recipes you don't use, and adding new recipes that you need to support your hardware.
|
|
|
|
|
</para></listitem>
|
|
|
|
|
<listitem><para><emphasis>Prepare for the build</emphasis>: Once you have made all the
|
2011-09-20 17:26:58 +00:00
|
|
|
|
changes to your BSP layer, there remains a few things
|
2012-07-02 16:59:11 +00:00
|
|
|
|
you need to do for the OpenEmbedded build system in order for it to create your image.
|
2011-07-27 19:10:25 +00:00
|
|
|
|
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>
|
2011-09-20 17:26:58 +00:00
|
|
|
|
<para>The entire process for building an image is overviewed in the section
|
2012-03-09 19:40:39 +00:00
|
|
|
|
"<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section
|
|
|
|
|
of the Yocto Project Quick Start.
|
2011-07-27 19:10:25 +00:00
|
|
|
|
You might want to reference this information.</para></listitem>
|
2012-07-02 16:59:11 +00:00
|
|
|
|
<listitem><para><emphasis>Build the image</emphasis>: The OpenEmbedded build system
|
|
|
|
|
uses the BitBake tool to build images based on the type of image you want to create.
|
2011-07-27 19:10:25 +00:00
|
|
|
|
You can find more information on BitBake
|
2012-07-13 21:57:18 +00:00
|
|
|
|
<ulink url='&BITBAKE_DOCS_URL;'>here</ulink>.</para>
|
2011-07-27 19:10:25 +00:00
|
|
|
|
<para>The build process supports several types of images to satisfy different needs.
|
2011-09-20 17:26:58 +00:00
|
|
|
|
See the
|
2012-07-16 17:53:16 +00:00
|
|
|
|
"<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter
|
|
|
|
|
in the Yocto Project Reference Manual for information on
|
2012-01-11 16:08:13 +00:00
|
|
|
|
supported images.</para></listitem>
|
2011-07-27 19:10:25 +00:00
|
|
|
|
</orderedlist>
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
2011-08-16 16:17:55 +00:00
|
|
|
|
You can view a video presentation on "Building Custom Embedded Images with Yocto"
|
|
|
|
|
at <ulink url='http://free-electrons.com/blog/elc-2011-videos'>Free Electrons</ulink>.
|
2011-08-31 13:46:23 +00:00
|
|
|
|
You can also find supplemental information in
|
2012-03-09 19:40:39 +00:00
|
|
|
|
<ulink url='&YOCTO_DOCS_BSP_URL;'>
|
2011-08-31 13:46:23 +00:00
|
|
|
|
The Board Support Package (BSP) Development Guide</ulink>.
|
2011-09-20 17:26:58 +00:00
|
|
|
|
Finally, there is wiki page write up of the example also located
|
2012-03-09 19:40:39 +00:00
|
|
|
|
<ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>
|
2011-09-20 17:26:58 +00:00
|
|
|
|
here</ulink> that you might find helpful.
|
2011-07-27 19:47:59 +00:00
|
|
|
|
</para>
|
2011-07-27 19:10:25 +00:00
|
|
|
|
</section>
|
|
|
|
|
|
2011-07-28 13:21:28 +00:00
|
|
|
|
<section id='modifying-the-kernel'>
|
|
|
|
|
<title><anchor id='kernel-spot' />Modifying the Kernel</title>
|
2011-07-27 19:10:25 +00:00
|
|
|
|
|
|
|
|
|
<para>
|
2012-07-02 17:19:10 +00:00
|
|
|
|
Kernel modification involves changing the Yocto Project kernel, which could involve changing
|
2011-10-20 17:38:05 +00:00
|
|
|
|
configuration options as well as adding new kernel recipes.
|
2011-08-01 21:39:35 +00:00
|
|
|
|
Configuration changes can be added in the form of configuration fragments, while recipe
|
|
|
|
|
modification comes through the kernel's <filename>recipes-kernel</filename> area
|
|
|
|
|
in a kernel layer you create.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
2012-07-02 17:19:10 +00:00
|
|
|
|
The remainder of this section presents a high-level overview of the Yocto Project
|
|
|
|
|
kernel architecture and the steps to modify the kernel.
|
2011-08-31 13:46:23 +00:00
|
|
|
|
For a complete discussion of the kernel, see
|
2012-03-09 19:40:39 +00:00
|
|
|
|
<ulink url='&YOCTO_DOCS_KERNEL_URL;'>
|
2011-08-31 13:46:23 +00:00
|
|
|
|
The Yocto Project Kernel Architecture and Use Manual</ulink>.
|
2011-09-20 17:26:58 +00:00
|
|
|
|
You can reference the appendix
|
|
|
|
|
"<link linkend='dev-manual-kernel-appendix'>Kernel Modification Example</link>"
|
2011-08-01 21:39:35 +00:00
|
|
|
|
for a detailed example that changes the configuration of a kernel.
|
2011-07-27 19:10:25 +00:00
|
|
|
|
</para>
|
2011-08-01 21:39:35 +00:00
|
|
|
|
|
|
|
|
|
<section id='kernel-overview'>
|
|
|
|
|
<title>Kernel Overview</title>
|
|
|
|
|
|
|
|
|
|
<para>
|
2011-10-20 17:38:05 +00:00
|
|
|
|
Traditionally, when one thinks of a patched kernel, they think of a base kernel
|
2011-11-02 20:37:32 +00:00
|
|
|
|
source tree and a fixed structure that contains kernel patches.
|
|
|
|
|
The Yocto Project, however, employs mechanisms, that in a sense, result in a kernel source
|
2011-08-01 21:39:35 +00:00
|
|
|
|
generator.
|
2011-09-20 17:26:58 +00:00
|
|
|
|
By the end of this section, this analogy will become clearer.
|
2011-08-01 21:39:35 +00:00
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
2012-07-02 17:19:10 +00:00
|
|
|
|
You can find a web interface to the Yocto Project kernel source repositories at
|
2012-03-09 19:40:39 +00:00
|
|
|
|
<ulink url='&YOCTO_GIT_URL;'></ulink>.
|
2011-08-31 13:46:23 +00:00
|
|
|
|
If you look at the interface, you will see to the left a grouping of
|
|
|
|
|
Git repositories titled "Yocto Linux Kernel."
|
2012-04-26 14:03:39 +00:00
|
|
|
|
Within this group, you will find several kernels supported by
|
2011-08-31 13:46:23 +00:00
|
|
|
|
the Yocto Project:
|
|
|
|
|
<itemizedlist>
|
|
|
|
|
<listitem><para><emphasis><filename>linux-yocto-2.6.34</filename></emphasis> - The
|
2012-07-02 17:19:10 +00:00
|
|
|
|
stable Yocto Project kernel that is based on the Linux 2.6.34 released kernel.</para></listitem>
|
2011-08-31 13:46:23 +00:00
|
|
|
|
<listitem><para><emphasis><filename>linux-yocto-2.6.37</filename></emphasis> - The
|
2012-07-02 17:19:10 +00:00
|
|
|
|
stable Yocto Project kernel that is based on the Linux 2.6.37 released kernel.</para></listitem>
|
2012-02-02 20:40:01 +00:00
|
|
|
|
<listitem><para><emphasis><filename>linux-yocto-3.0</filename></emphasis> - The stable
|
2012-07-02 17:19:10 +00:00
|
|
|
|
Yocto Project kernel that is based on the Linux 3.0 released kernel.</para></listitem>
|
2012-02-02 20:40:01 +00:00
|
|
|
|
<listitem><para><emphasis><filename>linux-yocto-3.0-1.1.x</filename></emphasis> - The
|
2012-07-02 17:19:10 +00:00
|
|
|
|
stable Yocto Project kernel to use with the Yocto Project Release 1.1.x. This kernel
|
|
|
|
|
is based on the Linux 3.0 released kernel.</para></listitem>
|
2012-04-23 20:41:10 +00:00
|
|
|
|
<listitem><para><emphasis><filename>linux-yocto-3.2</filename></emphasis> - The
|
2012-07-02 17:19:10 +00:00
|
|
|
|
stable Yocto Project kernel to use with the Yocto Project Release 1.2. This kernel
|
|
|
|
|
is based on the Linux 3.2 released kernel.</para></listitem>
|
2011-08-31 13:46:23 +00:00
|
|
|
|
<listitem><para><emphasis><filename>linux-yocto-dev</filename></emphasis> - A development
|
|
|
|
|
kernel based on the latest upstream release candidate available.</para></listitem>
|
|
|
|
|
</itemizedlist>
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
2011-10-20 17:38:05 +00:00
|
|
|
|
The kernels are maintained using the Git revision control system
|
|
|
|
|
that structures them using the familiar "tree", "branch", and "leaf" scheme.
|
2011-08-31 13:46:23 +00:00
|
|
|
|
Branches represent diversions from general code to more specific code, while leaves
|
|
|
|
|
represent the end-points for a complete and unique kernel whose source files
|
|
|
|
|
when gathered from the root of the tree to the leaf accumulate to create the files
|
|
|
|
|
necessary for a specific piece of hardware and its features.
|
|
|
|
|
The following figure displays this concept:
|
|
|
|
|
<para>
|
|
|
|
|
<imagedata fileref="figures/kernel-overview-1.png"
|
|
|
|
|
width="6in" depth="6in" align="center" scale="100" />
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
Within the figure, the "Kernel.org Branch Point" represents the point in the tree
|
2011-10-20 17:38:05 +00:00
|
|
|
|
where a supported base kernel is modified from the Linux kernel.
|
2011-08-31 13:46:23 +00:00
|
|
|
|
For example, this could be the branch point for the <filename>linux-yocto-3.0</filename>
|
|
|
|
|
kernel.
|
|
|
|
|
Thus, everything further to the right in the structure is based on the
|
|
|
|
|
<filename>linux-yocto-3.0</filename> kernel.
|
|
|
|
|
Branch points to right in the figure represent where the
|
|
|
|
|
<filename>linux-yocto-3.0</filename> kernel is modified for specific hardware
|
|
|
|
|
or types of kernels, such as real-time kernels.
|
|
|
|
|
Each leaf thus represents the end-point for a kernel designed to run on a specific
|
|
|
|
|
targeted device.
|
2011-08-01 21:39:35 +00:00
|
|
|
|
</para>
|
2011-08-31 13:46:23 +00:00
|
|
|
|
|
2011-08-01 21:39:35 +00:00
|
|
|
|
<para>
|
2011-08-31 13:46:23 +00:00
|
|
|
|
The overall result is a Git-maintained repository from which all the supported
|
2012-07-02 16:59:11 +00:00
|
|
|
|
kernel types can be derived for all the supported devices.
|
2011-08-01 21:39:35 +00:00
|
|
|
|
A big advantage to this scheme is the sharing of common features by keeping them in
|
2011-08-31 13:46:23 +00:00
|
|
|
|
"larger" branches within the tree.
|
2011-08-01 21:39:35 +00:00
|
|
|
|
This practice eliminates redundant storage of similar features shared among kernels.
|
|
|
|
|
</para>
|
|
|
|
|
|
2011-08-31 13:46:23 +00:00
|
|
|
|
<note>
|
2012-07-02 17:19:10 +00:00
|
|
|
|
Keep in mind the figure does not take into account all the supported Yocto
|
|
|
|
|
Project kernel types, but rather shows a single generic kernel just for conceptual purposes.
|
2011-08-31 13:46:23 +00:00
|
|
|
|
Also keep in mind that this structure represents the Yocto Project source repositories
|
|
|
|
|
that are either pulled from during the build or established on the host development system
|
|
|
|
|
prior to the build by either cloning a particular kernel's Git repository or by
|
|
|
|
|
downloading and unpacking a tarball.
|
|
|
|
|
</note>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
Storage of all the available kernel source code is one thing, while representing the
|
|
|
|
|
code on your host development system is another.
|
2012-07-02 16:59:11 +00:00
|
|
|
|
Conceptually, you can think of the kernel source repositories as all the
|
2011-08-31 13:46:23 +00:00
|
|
|
|
source files necessary for all the supported kernels.
|
|
|
|
|
As a developer, you are just interested in the source files for the kernel on
|
|
|
|
|
on which you are working.
|
|
|
|
|
And, furthermore, you need them available on your host system.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
You make kernel source code available on your host development system by using
|
2012-07-02 17:19:10 +00:00
|
|
|
|
Git to create a bare clone of the Yocto Project kernel Git repository
|
2011-08-31 13:46:23 +00:00
|
|
|
|
in which you are interested.
|
|
|
|
|
Then, you use Git again to clone a copy of that bare clone.
|
|
|
|
|
This copy represents the directory structure on your host system that is particular
|
|
|
|
|
to the kernel you want.
|
|
|
|
|
These are the files you actually modify to change the kernel.
|
2012-07-02 17:19:10 +00:00
|
|
|
|
See the <link linkend='local-kernel-files'>Yocto Project Kernel</link> item earlier
|
2011-08-31 13:46:23 +00:00
|
|
|
|
in this manual for an example of how to set up the kernel source directory
|
|
|
|
|
structure on your host system.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
This next figure illustrates how the kernel source files might be arranged on
|
|
|
|
|
your host system.
|
|
|
|
|
</para>
|
|
|
|
|
|
2011-08-01 21:39:35 +00:00
|
|
|
|
<para>
|
2012-04-26 14:46:36 +00:00
|
|
|
|
<imagedata fileref="figures/kernel-overview-3-denzil.png"
|
2011-08-31 13:46:23 +00:00
|
|
|
|
width="6in" depth="4in" align="center" scale="100" />
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
In the previous figure, the file structure on the left represents the bare clone
|
|
|
|
|
set up to track the Yocto Project kernel Git repository.
|
|
|
|
|
The structure on the right represents the copy of the bare clone.
|
|
|
|
|
When you make modifcations to the kernel source code, this is the area in which
|
|
|
|
|
you work.
|
|
|
|
|
Once you make corrections, you must use Git to push the committed changes to the
|
|
|
|
|
bare clone.
|
|
|
|
|
The example in <xref linkend='modifying-the-kernel-source-code'>
|
|
|
|
|
Modifying the Kernel Source Code</xref> provides a detailed example.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
What happens during the build?
|
2011-08-01 21:39:35 +00:00
|
|
|
|
When you build the kernel on your development system all files needed for the build
|
2012-07-02 16:59:11 +00:00
|
|
|
|
are taken from the source repositories pointed to by the
|
2011-08-01 21:39:35 +00:00
|
|
|
|
<filename>SRC_URI</filename> variable and gathered in a temporary work area
|
|
|
|
|
where they are subsequently used to create the unique kernel.
|
|
|
|
|
Thus, in a sense, the process constructs a local source tree specific to your
|
|
|
|
|
kernel to generate the new kernel image - a source generator if you will.
|
|
|
|
|
</para>
|
2011-08-31 13:46:23 +00:00
|
|
|
|
The following figure shows the temporary file structure
|
|
|
|
|
created on your host system when the build occurs.
|
|
|
|
|
This build directory contains all the source files used during the build.
|
2011-08-02 20:00:48 +00:00
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
2011-08-31 13:46:23 +00:00
|
|
|
|
<imagedata fileref="figures/kernel-overview-2.png"
|
|
|
|
|
width="6in" depth="5in" align="center" scale="100" />
|
|
|
|
|
</para>
|
2011-08-02 14:48:52 +00:00
|
|
|
|
|
2011-08-01 21:39:35 +00:00
|
|
|
|
<para>
|
2012-07-02 16:59:11 +00:00
|
|
|
|
Again, for a complete discussion of the Yocto Project kernel's architecture and its
|
2011-08-31 13:46:23 +00:00
|
|
|
|
branching strategy,
|
2012-04-26 15:05:38 +00:00
|
|
|
|
see <ulink url='&YOCTO_DOCS_KERNEL_URL;'>
|
2011-08-01 21:39:35 +00:00
|
|
|
|
The Yocto Project Kernel Architecture and Use Manual</ulink>.
|
2012-04-26 15:05:38 +00:00
|
|
|
|
You can also reference the
|
|
|
|
|
"<link linkend='modifying-the-kernel-source-code'>Modifying the Kernel Source Code</link>"
|
|
|
|
|
section for a detailed example that modifies the kernel.
|
2011-08-01 21:39:35 +00:00
|
|
|
|
</para>
|
|
|
|
|
</section>
|
|
|
|
|
|
|
|
|
|
<section id='kernel-modification-workflow'>
|
|
|
|
|
<title>Kernel Modification Workflow</title>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
This illustration and the following list summarizes the kernel modification general workflow.
|
|
|
|
|
</para>
|
|
|
|
|
|
2011-08-11 17:18:38 +00:00
|
|
|
|
<para>
|
2011-09-23 15:07:41 +00:00
|
|
|
|
<imagedata fileref="figures/kernel-dev-flow.png"
|
|
|
|
|
width="6in" depth="7.5in" align="center" scalefit="1" />
|
2011-08-11 17:18:38 +00:00
|
|
|
|
</para>
|
2011-08-01 21:39:35 +00:00
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
<orderedlist>
|
|
|
|
|
<listitem><para><emphasis>Set up your host development system to support
|
|
|
|
|
development using the Yocto Project</emphasis>: See
|
2012-03-09 19:40:39 +00:00
|
|
|
|
"<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
|
2011-08-02 20:00:48 +00:00
|
|
|
|
in the Yocto Project Quick Start for requirements.</para></listitem>
|
2012-07-02 16:59:11 +00:00
|
|
|
|
<listitem><para><emphasis>Establish a local copy of project files on your
|
|
|
|
|
system</emphasis>: Having the <link linkend='source-directory'>source
|
|
|
|
|
directory</link> on your system gives you access to the build process and tools
|
|
|
|
|
you need.
|
2011-08-01 21:39:35 +00:00
|
|
|
|
For information on how to get these files, see the bulleted item
|
2011-09-20 17:26:58 +00:00
|
|
|
|
"<link linkend='local-yp-release'>Yocto Project Release</link>" earlier in this manual.
|
2011-08-01 21:39:35 +00:00
|
|
|
|
</para></listitem>
|
2012-07-02 16:59:11 +00:00
|
|
|
|
<listitem><para><emphasis>Set up a local copy of the <filename>poky-extras</filename> Git
|
|
|
|
|
repository</emphasis>: This local repository is the area for your configuration
|
2011-08-10 23:27:45 +00:00
|
|
|
|
fragments, new kernel recipes, and the kernel <filename>.bbappend</filename>
|
|
|
|
|
file used during the build.
|
2012-07-02 16:59:11 +00:00
|
|
|
|
It is good practice to set this repository up inside your local
|
|
|
|
|
source directory.
|
2011-08-02 20:00:48 +00:00
|
|
|
|
For information on how to get these files, see the bulleted item
|
2011-09-20 17:26:58 +00:00
|
|
|
|
"<link linkend='poky-extras-repo'>The <filename>poky-extras</filename> Git Repository</link>"
|
2011-10-20 17:38:05 +00:00
|
|
|
|
earlier in this manual.
|
|
|
|
|
<note>While it is certainly possible to modify the kernel without involving
|
|
|
|
|
a local Git repository, the suggested workflow for kernel modification
|
|
|
|
|
using the Yocto Project does use a Git repository.</note></para></listitem>
|
2012-07-02 17:19:10 +00:00
|
|
|
|
<listitem><para><emphasis>Establish a local copy of the Yocto Project kernel files on your
|
2011-08-10 23:27:45 +00:00
|
|
|
|
system</emphasis>: In order to make modifications to the kernel you need two things:
|
2012-07-02 17:19:10 +00:00
|
|
|
|
a bare clone of the Yocto Project kernel you are modifying and
|
2011-09-20 17:26:58 +00:00
|
|
|
|
a copy of that bare clone.
|
2011-08-10 23:27:45 +00:00
|
|
|
|
The bare clone is required by the build process and is the area to which you
|
2011-09-20 17:26:58 +00:00
|
|
|
|
push your kernel source changes (pulling does not work with bare clones).
|
2011-08-10 23:27:45 +00:00
|
|
|
|
The copy of the bare clone is a local Git repository that contains all the kernel's
|
|
|
|
|
source files.
|
|
|
|
|
You make your changes to the files in this copy of the bare clone.
|
|
|
|
|
For information on how to set these two items up, see the bulleted item
|
2012-07-02 17:19:10 +00:00
|
|
|
|
"<link linkend='local-kernel-files'>Yocto Project Kernel</link>"
|
2011-09-20 17:26:58 +00:00
|
|
|
|
earlier in this manual.</para></listitem>
|
2011-08-10 23:27:45 +00:00
|
|
|
|
<listitem><para><emphasis>Make changes to the kernel source code if
|
|
|
|
|
applicable</emphasis>: Modifying the kernel does not always mean directly
|
|
|
|
|
changing source files.
|
2011-09-20 17:26:58 +00:00
|
|
|
|
However, if you have to do this, you make the changes in the local
|
2011-08-10 23:27:45 +00:00
|
|
|
|
Git repository you set up to hold the source files (i.e. the copy of the
|
|
|
|
|
bare clone).
|
2011-09-20 17:26:58 +00:00
|
|
|
|
Once the changes are made, you need to use Git commands to commit the changes
|
2011-08-10 23:27:45 +00:00
|
|
|
|
and then push them to the bare clone.</para></listitem>
|
2011-08-02 14:48:52 +00:00
|
|
|
|
<listitem><para><emphasis>Make kernel configuration changes
|
2011-10-20 17:38:05 +00:00
|
|
|
|
if applicable</emphasis>:
|
2011-09-20 17:26:58 +00:00
|
|
|
|
If your situation calls for changing the kernel's configuration, you can
|
2011-08-10 23:27:45 +00:00
|
|
|
|
use <filename>menuconfig</filename>
|
|
|
|
|
to enable and disable kernel configurations.
|
2011-09-20 17:26:58 +00:00
|
|
|
|
Using <filename>menuconfig</filename> allows you to interactively develop and test the
|
|
|
|
|
configuration changes you are making to the kernel.
|
|
|
|
|
When saved, changes using <filename>menuconfig</filename> update the kernel's
|
|
|
|
|
<filename>.config</filename>.
|
2011-10-20 17:38:05 +00:00
|
|
|
|
Try to resist the temptation of directly editing the <filename>.config</filename>
|
2012-02-22 19:51:35 +00:00
|
|
|
|
file found in the
|
2012-07-02 16:59:11 +00:00
|
|
|
|
<link linkend='build-directory'>build directory</link> at
|
2011-10-20 17:38:05 +00:00
|
|
|
|
<filename>tmp/sysroots/<machine-name>/kernel</filename>.
|
2012-07-02 16:59:11 +00:00
|
|
|
|
Doing so, can produce unexpected results when the OpenEmbedded build system
|
2011-10-20 17:38:05 +00:00
|
|
|
|
regenerates the configuration file.</para>
|
|
|
|
|
<para>Once you are satisfied with the configuration changes made using
|
|
|
|
|
<filename>menuconfig</filename>, you can directly examine the
|
|
|
|
|
<filename>.config</filename> file against a saved original and gather those
|
2012-03-13 22:45:51 +00:00
|
|
|
|
changes into a config fragment to be referenced from within the kernel's
|
|
|
|
|
<filename>.bbappend</filename> file.</para></listitem>
|
2011-10-20 17:38:05 +00:00
|
|
|
|
<listitem><para><emphasis>Add or extend kernel recipes if applicable</emphasis>:
|
|
|
|
|
The standard
|
2011-08-10 23:27:45 +00:00
|
|
|
|
layer structure organizes recipe files inside the
|
2012-07-02 16:59:11 +00:00
|
|
|
|
<filename>meta-kernel-dev</filename> layer that is within the local
|
2011-08-10 23:27:45 +00:00
|
|
|
|
<filename>poky-extras</filename> Git repository.
|
2011-09-20 17:26:58 +00:00
|
|
|
|
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>
|
2011-08-10 23:27:45 +00:00
|
|
|
|
file that appends information to the kernel's recipe file used during the
|
|
|
|
|
build.
|
2011-08-01 21:39:35 +00:00
|
|
|
|
</para></listitem>
|
|
|
|
|
<listitem><para><emphasis>Prepare for the build</emphasis>: Once you have made all the
|
2011-08-10 23:27:45 +00:00
|
|
|
|
changes to your kernel (configurations, source code changes, recipe additions,
|
2011-09-20 17:26:58 +00:00
|
|
|
|
or recipe changes), there remains a few things
|
2012-07-02 16:59:11 +00:00
|
|
|
|
you need to do in order for the build system to create your image.
|
2011-09-20 17:26:58 +00:00
|
|
|
|
If you have not done so, you need to get the build environment ready by sourcing
|
2011-08-02 14:48:52 +00:00
|
|
|
|
the environment setup script described earlier.
|
2011-08-31 14:00:07 +00:00
|
|
|
|
You also need to be sure two key configuration files
|
|
|
|
|
(<filename>local.conf</filename> and <filename>bblayers.conf</filename>)
|
|
|
|
|
are configured appropriately.</para>
|
2011-08-01 21:39:35 +00:00
|
|
|
|
<para>The entire process for building an image is overviewed in the
|
2012-03-09 19:40:39 +00:00
|
|
|
|
"<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
|
|
|
|
|
section of the Yocto Project Quick Start.
|
2011-08-10 23:27:45 +00:00
|
|
|
|
You might want to reference this information.
|
|
|
|
|
Also, you should look at the detailed examples found in the appendices at
|
2011-09-20 17:26:58 +00:00
|
|
|
|
at the end of this manual.</para></listitem>
|
2012-07-02 16:59:11 +00:00
|
|
|
|
<listitem><para><emphasis>Build the image</emphasis>: The OpenEmbedded
|
|
|
|
|
build system uses the BitBake
|
2011-08-02 14:48:52 +00:00
|
|
|
|
tool to build images based on the type of image you want to create.
|
2011-08-01 21:39:35 +00:00
|
|
|
|
You can find more information on BitBake
|
2012-07-13 21:57:18 +00:00
|
|
|
|
<ulink url='&BITBAKE_DOCS_URL;'>here</ulink>.</para>
|
2011-08-01 21:39:35 +00:00
|
|
|
|
<para>The build process supports several types of images to satisfy different needs.
|
2012-07-16 17:53:16 +00:00
|
|
|
|
See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in
|
|
|
|
|
the Yocto Project Reference Manual for information on supported images.</para></listitem>
|
2011-08-02 14:48:52 +00:00
|
|
|
|
<listitem><para><emphasis>Make your configuration changes available
|
2011-09-20 17:26:58 +00:00
|
|
|
|
in the kernel layer</emphasis>: Up to this point, all the configuration changes to the
|
2011-08-01 21:39:35 +00:00
|
|
|
|
kernel have been done and tested iteratively.
|
2011-09-20 17:26:58 +00:00
|
|
|
|
Once they are tested and ready to go, you can move them into the kernel layer,
|
|
|
|
|
which allows you to distribute the layer.</para></listitem>
|
|
|
|
|
<listitem><para><emphasis>If applicable, share your in-tree changes</emphasis>:
|
|
|
|
|
If the changes you made
|
2012-07-02 17:19:10 +00:00
|
|
|
|
are suited for all Yocto Project kernel users, you might want to send them on
|
|
|
|
|
for inclusion into the upstream kernel's Git repository.
|
2011-10-20 17:38:05 +00:00
|
|
|
|
If the changes are accepted, the Yocto Project Maintainer pulls them into
|
|
|
|
|
the master branch of the kernel tree.
|
2011-09-20 17:26:58 +00:00
|
|
|
|
Doing so makes them available to everyone using the kernel.</para></listitem>
|
2011-08-01 21:39:35 +00:00
|
|
|
|
</orderedlist>
|
|
|
|
|
</para>
|
|
|
|
|
</section>
|
2011-07-27 19:10:25 +00:00
|
|
|
|
</section>
|
2011-07-15 20:17:07 +00:00
|
|
|
|
</section>
|
|
|
|
|
|
2012-07-02 16:59:11 +00:00
|
|
|
|
<section id='application-development-workflow'>
|
2011-09-20 20:02:34 +00:00
|
|
|
|
<title>Application Development Workflow</title>
|
2011-07-27 19:47:59 +00:00
|
|
|
|
|
|
|
|
|
<para>
|
2011-09-20 20:02:34 +00:00
|
|
|
|
Application development involves creation of an application that you want to be able
|
2012-07-02 17:19:10 +00:00
|
|
|
|
to run on your target hardware, which is running a Yocto Project kernel image.
|
2011-09-23 15:07:41 +00:00
|
|
|
|
The Yocto Project provides an Application Development Toolkit (ADT) that
|
|
|
|
|
facilitates quick development and integration of your application into its run-time environment.
|
|
|
|
|
Using the ADT you can employ cross-development toolchains designed for your target hardware
|
2011-09-20 20:02:34 +00:00
|
|
|
|
to compile and link your application.
|
2011-09-23 15:07:41 +00:00
|
|
|
|
You can then deploy your application to the actual hardware or to the QEMU emulator for testing.
|
|
|
|
|
If you are familiar with the popular Eclipse IDE, you can use an Eclipse Yocto Plug-in to
|
|
|
|
|
allow you to develop, deploy, and test your application all from within Eclipse.
|
2011-09-20 20:02:34 +00:00
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
2012-07-02 16:59:11 +00:00
|
|
|
|
While we strongly suggest using the ADT to develop your application, you might
|
2011-09-23 15:07:41 +00:00
|
|
|
|
not want to.
|
|
|
|
|
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.
|
2011-09-20 20:02:34 +00:00
|
|
|
|
</para>
|
|
|
|
|
|
2011-09-23 15:07:41 +00:00
|
|
|
|
<section id='workflow-using-the-adt-and-eclipse'>
|
|
|
|
|
<title>Workflow Using the ADT and <trademark class='trade'>Eclipse</trademark></title>
|
2011-09-20 20:02:34 +00:00
|
|
|
|
|
2011-09-23 15:07:41 +00:00
|
|
|
|
<para>
|
2012-07-02 16:59:11 +00:00
|
|
|
|
To help you understand how application development works using the ADT, this section
|
2011-09-23 15:07:41 +00:00
|
|
|
|
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
|
|
|
|
|
IDE, see
|
2012-03-09 19:40:39 +00:00
|
|
|
|
<ulink url='&YOCTO_DOCS_ADT_URL;'>
|
2011-09-23 15:07:41 +00:00
|
|
|
|
The Application Development Toolkit (ADT) User's Manual</ulink>.
|
|
|
|
|
</para>
|
2011-09-20 20:02:34 +00:00
|
|
|
|
|
2011-09-23 15:07:41 +00:00
|
|
|
|
<para>
|
2012-07-02 16:59:11 +00:00
|
|
|
|
The following illustration and list summarize the application development general workflow.
|
2011-09-23 15:07:41 +00:00
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
<imagedata fileref="figures/app-dev-flow.png"
|
|
|
|
|
width="7in" depth="8in" align="center" scale="100" />
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
<orderedlist>
|
|
|
|
|
<listitem><para><emphasis>Prepare the Host System for the Yocto Project</emphasis>:
|
|
|
|
|
See
|
2012-03-09 19:40:39 +00:00
|
|
|
|
"<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
|
2011-09-23 15:07:41 +00:00
|
|
|
|
in the Yocto Project Quick Start for requirements.</para></listitem>
|
2012-07-02 17:19:10 +00:00
|
|
|
|
<listitem><para><emphasis>Secure the Yocto Project Kernel Target Image</emphasis>:
|
2012-07-02 16:59:11 +00:00
|
|
|
|
You must have a target kernel image that has been built using the OpenEmbeded
|
|
|
|
|
build system.</para>
|
2011-09-23 15:07:41 +00:00
|
|
|
|
<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
|
2012-04-26 15:16:52 +00:00
|
|
|
|
(QEMU or real hardware), the area from which you get the image differs.
|
2011-09-23 15:07:41 +00:00
|
|
|
|
<itemizedlist>
|
|
|
|
|
<listitem><para>Download the image from
|
2012-03-09 19:40:39 +00:00
|
|
|
|
<ulink url='&YOCTO_MACHINES_DL_URL;'>
|
2011-09-23 15:07:41 +00:00
|
|
|
|
<filename>machines</filename></ulink> if your target architecture is supported
|
|
|
|
|
and you are going to develop and test your application on actual hardware.
|
|
|
|
|
</para></listitem>
|
|
|
|
|
<listitem><para>Download the image from the
|
2012-03-09 19:40:39 +00:00
|
|
|
|
<ulink url='&YOCTO_QEMU_DL_URL;'>
|
2011-09-23 15:07:41 +00:00
|
|
|
|
<filename>machines/qemu</filename></ulink> if your target architecture is supported
|
|
|
|
|
and you are going to develop and test your application using the QEMU
|
|
|
|
|
emulator.</para></listitem>
|
|
|
|
|
<listitem><para>Build your image if you cannot find a pre-built image that matches
|
|
|
|
|
your target architecture.
|
|
|
|
|
If your target architecture is similar to a supported architecture, you can
|
|
|
|
|
modify the kernel image before you build it.
|
|
|
|
|
See the
|
|
|
|
|
"<link linkend='kernel-modification-workflow'>Kernel Modification Workflow</link>"
|
|
|
|
|
section earlier in this manual for information on how to create a modified
|
2012-07-02 17:19:10 +00:00
|
|
|
|
Yocto Project kernel.</para></listitem>
|
2011-09-23 15:07:41 +00:00
|
|
|
|
</itemizedlist></para>
|
|
|
|
|
<para>For information on pre-built kernel image naming schemes for images
|
|
|
|
|
that can run on the QEMU emulator, see the
|
2012-03-09 19:40:39 +00:00
|
|
|
|
"<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>"
|
|
|
|
|
section in the Yocto Project Quick Start.</para></listitem>
|
2011-09-23 15:07:41 +00:00
|
|
|
|
<listitem><para><emphasis>Install the ADT</emphasis>:
|
|
|
|
|
The ADT provides a target-specific cross-development toolchain, the root filesystem,
|
|
|
|
|
the QEMU emulator, and other tools that can help you develop your application.
|
2012-07-02 16:59:11 +00:00
|
|
|
|
While it is possible to get these pieces separately, the ADT Installer provides an
|
2011-09-23 15:07:41 +00:00
|
|
|
|
easy method.
|
|
|
|
|
You can get these pieces by running an ADT installer script, which is configurable.
|
|
|
|
|
For information on how to install the ADT, see the
|
2012-03-09 19:40:39 +00:00
|
|
|
|
"<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Using the ADT Installer</ulink>"
|
|
|
|
|
section
|
|
|
|
|
in the Yocto Project Application Development (ADT) User's Manual.</para></listitem>
|
2011-09-23 15:07:41 +00:00
|
|
|
|
<listitem><para><emphasis>If Applicable, Secure the Target Root Filesystem</emphasis>:
|
|
|
|
|
If you choose not to install the ADT using the ADT Installer,
|
|
|
|
|
you need to find and download the
|
|
|
|
|
appropriate root filesystems.
|
|
|
|
|
You can find these tarballs in the same areas used for the kernel images.
|
|
|
|
|
Depending on the type of image you are running, the root filesystem you need differs.
|
|
|
|
|
For example, if you are developing an application that runs on an image that
|
|
|
|
|
supports Sato, you need to get root filesystem that supports Sato.
|
|
|
|
|
</para></listitem>
|
|
|
|
|
<listitem><para><emphasis>Create and Build your Application</emphasis>:
|
|
|
|
|
At this point, you need to have source files for your application.
|
|
|
|
|
Once you have the files, you can use the Eclipse IDE to import them and build the
|
|
|
|
|
project.
|
|
|
|
|
If you are not using Eclipse, you need to use the cross-development tools you have
|
|
|
|
|
installed to create the image.</para></listitem>
|
|
|
|
|
<listitem><para><emphasis>Deploy the Image with the Application</emphasis>:
|
|
|
|
|
If you are using the Eclipse IDE, you can deploy your image to the hardware or to
|
|
|
|
|
QEMU through the project's preferences.
|
|
|
|
|
If you are not using the Eclipse IDE, then you need to deploy the application using
|
|
|
|
|
other methods to the hardware.
|
|
|
|
|
Or, if you are using QEMU, you need to use that tool and load your image in for testing.
|
|
|
|
|
</para></listitem>
|
|
|
|
|
<listitem><para><emphasis>Test and Debug the Application</emphasis>:
|
|
|
|
|
Once your application is deployed, you need to test it.
|
|
|
|
|
Within the Eclipse IDE, you can use the debubbing environment along with the
|
|
|
|
|
set of user-space tools installed along with the ADT to debug your application.
|
|
|
|
|
Of course, the same user-space tools are available separately to use if you choose
|
|
|
|
|
not to use the Eclipse IDE.</para></listitem>
|
|
|
|
|
</orderedlist>
|
|
|
|
|
</para>
|
|
|
|
|
</section>
|
|
|
|
|
|
|
|
|
|
<section id='workflow-without-adt'>
|
|
|
|
|
<title>Workflow Without ADT</title>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
If you want to develop an application outside of the Yocto Project ADT environment, you
|
|
|
|
|
can still employ the cross-development toolchain, the QEMU emulator, and a number of supported
|
|
|
|
|
target image files.
|
|
|
|
|
You just need to follow these general steps:
|
|
|
|
|
<orderedlist>
|
|
|
|
|
<listitem><para><emphasis>Install the cross-development toolchain for your target hardware:</emphasis>
|
|
|
|
|
For information on how to install the toolchain, see the
|
2012-03-09 19:40:39 +00:00
|
|
|
|
"<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>"
|
|
|
|
|
section
|
|
|
|
|
in the Yocto Project Application Development (ADT) User's Manual.</para></listitem>
|
2011-09-23 15:07:41 +00:00
|
|
|
|
<listitem><para><emphasis>Download the Target Image:</emphasis> The Yocto Project supports
|
|
|
|
|
several target architectures and has many pre-built kernel images and root filesystem
|
|
|
|
|
images.</para>
|
|
|
|
|
<para>If you are going to develop your application on hardware, go to the
|
2012-03-09 19:40:39 +00:00
|
|
|
|
<ulink url='&YOCTO_MACHINES_DL_URL;'>
|
2011-09-23 15:07:41 +00:00
|
|
|
|
<filename>machines</filename></ulink> download area and choose a target machine area
|
|
|
|
|
from which to download the kernel image and root filesystem.
|
|
|
|
|
This download area could have several files in it that support development using
|
|
|
|
|
actual hardware.
|
|
|
|
|
For example, the area might contain <filename>.hddimg</filename> files that combine the
|
|
|
|
|
kernel image with the filesystem, boot loaders, etc.
|
|
|
|
|
Be sure to get the files you need for your particular development process.</para>
|
|
|
|
|
<para>If you are going to develop your application and then run and test it using the QEMU
|
|
|
|
|
emulator, go to the
|
2012-03-09 19:40:39 +00:00
|
|
|
|
<ulink url='&YOCTO_QEMU_DL_URL;'>
|
2011-09-23 15:07:41 +00:00
|
|
|
|
<filename>machines/qemu</filename></ulink> download area.
|
|
|
|
|
From this area, go down into the directory for your target architecture
|
|
|
|
|
(e.g. <filename>qemux86_64</filename> for an
|
|
|
|
|
<trademark class='registered'>Intel</trademark>-based 64-bit architecture).
|
|
|
|
|
Download kernel, root filesystem, and any other files you need for your process.
|
|
|
|
|
<note>In order to use the root filesystem in QEMU, you need to extract it.
|
|
|
|
|
See the
|
2012-03-09 19:40:39 +00:00
|
|
|
|
"<ulink url='&YOCTO_DOCS_ADT_URL;#extracting-the-root-filesystem'>Extracting the Root Filesystem</ulink>" section for information on how to extract the
|
2011-09-23 15:07:41 +00:00
|
|
|
|
root filesystem.</note></para></listitem>
|
|
|
|
|
<listitem><para><emphasis>Develop and Test your Application:</emphasis> At this point,
|
|
|
|
|
you have the tools to develop your application.
|
|
|
|
|
If you need to separately install and use the QEMU emulator, you can go to
|
|
|
|
|
<ulink url='http://www.qemu.org'>QEMU Home Page</ulink> to download and learn about the
|
|
|
|
|
emulator.</para></listitem>
|
|
|
|
|
</orderedlist>
|
|
|
|
|
</para>
|
|
|
|
|
</section>
|
2011-07-27 19:47:59 +00:00
|
|
|
|
</section>
|
|
|
|
|
|
2012-06-12 14:48:52 +00:00
|
|
|
|
<section id="modifying-temporary-source-code">
|
|
|
|
|
<title>Modifying Temporary Source Code</title>
|
|
|
|
|
|
|
|
|
|
<para>
|
2012-07-02 16:59:11 +00:00
|
|
|
|
You might
|
2012-06-12 14:48:52 +00:00
|
|
|
|
find it helpful during development to modify the temporary source code used by recipes
|
|
|
|
|
to build packages.
|
|
|
|
|
For example, suppose you are developing a patch and you need to experiment a bit
|
|
|
|
|
to figure out your solution.
|
|
|
|
|
After you have initially built the package, you can iteratively tweak the
|
|
|
|
|
source code, which is located in the
|
2012-07-02 16:59:11 +00:00
|
|
|
|
<link linkend='build-directory'>build directory</link>, and then
|
2012-06-12 14:48:52 +00:00
|
|
|
|
you can force a re-compile and quickly test your altered code.
|
|
|
|
|
Once you settle on a solution, you can then preserve your changes in the form of
|
|
|
|
|
patches.
|
|
|
|
|
You can accomplish these steps all within either a
|
|
|
|
|
<ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink> or
|
|
|
|
|
<link linkend='git'>Git</link> workflow.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<section id='finding-the-temporary-source-code'>
|
|
|
|
|
<title>Finding the Temporary Source Code</title>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
During a build, the unpacked temporary source code used by recipes
|
2012-07-02 16:59:11 +00:00
|
|
|
|
to build packages is available in the build directory as
|
2012-06-12 14:48:52 +00:00
|
|
|
|
defined by the
|
|
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> variable.
|
|
|
|
|
Below is the default value for the <filename>S</filename> variable as defined in the
|
|
|
|
|
<filename>meta/conf/bitbake.conf</filename> configuration file in the
|
2012-07-02 16:59:11 +00:00
|
|
|
|
<link linkend='source-directory'>source directory</link>:
|
2012-06-12 14:48:52 +00:00
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
|
S = ${WORKDIR}/${BP}
|
|
|
|
|
</literallayout>
|
|
|
|
|
You should be aware that many recipes override the <filename>S</filename> variable.
|
|
|
|
|
For example, recipes that fetch their source from Git usually set
|
|
|
|
|
<filename>S</filename> to <filename>${WORKDIR}/git</filename>.
|
|
|
|
|
<note>
|
|
|
|
|
<filename>BP</filename> represents the "Base Package", which is the base package
|
|
|
|
|
name and the package version:
|
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
|
BP = ${BPN}-${PV}
|
|
|
|
|
</literallayout>
|
|
|
|
|
</note>
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
The path to the work directory for the recipe
|
|
|
|
|
(<ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>) depends
|
|
|
|
|
on the package name and the architecture of the target device.
|
|
|
|
|
For example, here is the work directory for packages whose targets are not device-dependent:
|
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
|
${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
|
|
|
|
|
</literallayout>
|
|
|
|
|
Let's look at an example without variables.
|
2012-07-02 16:59:11 +00:00
|
|
|
|
Assuming a top-level source directory named <filename>poky</filename>
|
|
|
|
|
and a default build directory of <filename>poky/build</filename>,
|
2012-06-12 14:48:52 +00:00
|
|
|
|
the following is the work directory for the <filename>acl</filename> package:
|
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
|
~/poky/build/tmp/work/i586-poky-linux/acl-2.2.51-r3
|
|
|
|
|
</literallayout>
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
If your package is dependent on the target device, the work directory varies slightly:
|
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
|
${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
|
|
|
|
|
</literallayout>
|
2012-07-02 16:59:11 +00:00
|
|
|
|
Again, assuming top-level source directory named <filename>poky</filename>
|
|
|
|
|
and a default build directory of <filename>poky/build</filename>, the
|
2012-06-12 14:48:52 +00:00
|
|
|
|
following is the work directory for the <filename>acl</filename> package that is being
|
|
|
|
|
built for a MIPS-based device:
|
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
|
~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2
|
|
|
|
|
</literallayout>
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<note>
|
2012-07-02 16:59:11 +00:00
|
|
|
|
To better understand how the OpenEmbedded build system resolves directories during the
|
2012-06-12 14:48:52 +00:00
|
|
|
|
build process, see the glossary entries for the
|
|
|
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>,
|
|
|
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>,
|
|
|
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-TOPDIR'><filename>TOPDIR</filename></ulink>,
|
|
|
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>,
|
|
|
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_OS'><filename>TARGET_OS</filename></ulink>,
|
|
|
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>,
|
|
|
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>,
|
|
|
|
|
and
|
|
|
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
|
|
|
|
|
variables in the Yocto Project Reference Manual.
|
|
|
|
|
</note>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
Now that you know where to locate the directory that has the temporary source code, you can use a
|
|
|
|
|
Quilt or Git workflow to make your edits, test the changes, and preserve the
|
|
|
|
|
changes in the form of patches.
|
|
|
|
|
</para>
|
|
|
|
|
</section>
|
|
|
|
|
|
|
|
|
|
<section id="using-a-quilt-workflow">
|
|
|
|
|
<title>Using a Quilt Workflow</title>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
<ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink>
|
|
|
|
|
is a powerful tool that allows you to capture source code changes without having
|
|
|
|
|
a clean source tree.
|
|
|
|
|
This section outlines the typical workflow you can use to modify temporary source code,
|
|
|
|
|
test changes, and then preserve the changes in the form of a patch all using Quilt.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
Follow these general steps:
|
|
|
|
|
<orderedlist>
|
|
|
|
|
<listitem><para><emphasis>Find the Source Code:</emphasis>
|
2012-07-02 16:59:11 +00:00
|
|
|
|
The temporary source code used by the OpenEmbedded build system is kept in the
|
|
|
|
|
build directory.
|
2012-06-12 14:48:52 +00:00
|
|
|
|
See the
|
|
|
|
|
"<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
|
|
|
|
|
section to learn how to locate the directory that has the temporary source code for a
|
|
|
|
|
particular package.</para></listitem>
|
|
|
|
|
<listitem><para><emphasis>Change Your Working Directory:</emphasis>
|
|
|
|
|
You need to be in the directory that has the temporary source code.
|
|
|
|
|
That directory is defined by the
|
|
|
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink>
|
|
|
|
|
variable.</para></listitem>
|
|
|
|
|
<listitem><para><emphasis>Create a New Patch:</emphasis>
|
|
|
|
|
Before modifying source code, you need to create a new patch.
|
|
|
|
|
To create a new patch file, use <filename>quilt new</filename> as below:
|
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
|
$ quilt new my_changes.patch
|
|
|
|
|
</literallayout></para></listitem>
|
|
|
|
|
<listitem><para><emphasis>Notify Quilt and Add Files:</emphasis>
|
|
|
|
|
After creating the patch, you need to notify Quilt about the files you will
|
|
|
|
|
be changing.
|
|
|
|
|
Add the files you will be modifying into the patch you just created:
|
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
|
$ quilt add file1.c file2.c file3.c
|
|
|
|
|
</literallayout></para></listitem>
|
|
|
|
|
<listitem><para><emphasis>Edit the Files:</emphasis>
|
|
|
|
|
Make the changes to the temporary source code.</para></listitem>
|
|
|
|
|
<listitem><para><emphasis>Test Your Changes:</emphasis>
|
|
|
|
|
Once you have modified the source code, the easiest way to test your changes
|
|
|
|
|
is by calling the <filename>compile</filename> task as shown in the following example:
|
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
|
$ bitbake -c compile -f <name_of_package>
|
|
|
|
|
</literallayout>
|
|
|
|
|
The <filename>-f</filename> or <filename>--force</filename>
|
|
|
|
|
option forces re-execution of the specified task.
|
|
|
|
|
If you find problems with your code, you can just keep editing and
|
|
|
|
|
re-testing iteratively until things work as expected.
|
|
|
|
|
<note>All the modifications you make to the temporary source code
|
|
|
|
|
disappear once you <filename>-c clean</filename> or
|
|
|
|
|
<filename>-c cleanall</filename> with BitBake for the package.
|
|
|
|
|
Modifications will also disappear if you use the <filename>rm_work</filename>
|
|
|
|
|
feature as described in the
|
|
|
|
|
"<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
|
|
|
|
|
section of the Yocto Project Quick Start.
|
|
|
|
|
</note></para></listitem>
|
|
|
|
|
<listitem><para><emphasis>Generate the Patch:</emphasis>
|
|
|
|
|
Once your changes work as expected, you need to use Quilt to generate the final patch that
|
|
|
|
|
contains all your modifications.
|
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
|
$ quilt refresh
|
|
|
|
|
</literallayout>
|
|
|
|
|
At this point the <filename>my_changes.patch</filename> file has all your edits made
|
|
|
|
|
to the <filename>file1.c</filename>, <filename>file2.c</filename>, and
|
|
|
|
|
<filename>file3.c</filename> files.</para>
|
|
|
|
|
<para>You can find the resulting patch file in the <filename>patches/</filename>
|
|
|
|
|
subdirectory of the source (<filename>S</filename>) directory.</para></listitem>
|
|
|
|
|
<listitem><para><emphasis>Copy the Patch File:</emphasis>
|
|
|
|
|
For simplicity, copy the patch file into a directory named <filename>files</filename>,
|
|
|
|
|
which you can create in the same directory as the recipe.
|
2012-07-02 16:59:11 +00:00
|
|
|
|
Placing the patch here guarantees that the OpenEmbedded build system will find
|
2012-06-12 14:48:52 +00:00
|
|
|
|
the patch.
|
|
|
|
|
Next, add the patch into the
|
|
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
|
|
|
|
|
of the recipe.
|
|
|
|
|
Here is an example:
|
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
|
SRC_URI += "file://my_changes.patch"
|
|
|
|
|
</literallayout></para></listitem>
|
|
|
|
|
<listitem><para><emphasis>Increment the Package Revision Number:</emphasis>
|
|
|
|
|
Finally, don't forget to 'bump' the
|
|
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename>
|
|
|
|
|
value in the same recipe since the resulting packages have changed.</para></listitem>
|
|
|
|
|
</orderedlist>
|
|
|
|
|
</para> </section>
|
|
|
|
|
|
|
|
|
|
<section id='using-a-git-workflow'>
|
|
|
|
|
<title>Using a Git Workflow</title>
|
|
|
|
|
<para>
|
|
|
|
|
Git is an even more powerful tool that allows you to capture source code changes without having
|
|
|
|
|
a clean source tree.
|
|
|
|
|
This section outlines the typical workflow you can use to modify temporary source code,
|
|
|
|
|
test changes, and then preserve the changes in the form of a patch all using Git.
|
|
|
|
|
For general information on Git as it is used in the Yocto Project, see the
|
|
|
|
|
"<link linkend='git'>Git</link>" section.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<note>
|
|
|
|
|
This workflow uses Git only for its ability to manage local changes to the source code
|
2012-07-02 16:59:11 +00:00
|
|
|
|
and produce patches independent of any version control system used with the Yocto Project.
|
2012-06-12 14:48:52 +00:00
|
|
|
|
</note>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
Follow these general steps:
|
|
|
|
|
<orderedlist>
|
|
|
|
|
<listitem><para><emphasis>Find the Source Code:</emphasis>
|
2012-07-02 16:59:11 +00:00
|
|
|
|
The temporary source code used by the OpenEmbedded build system is kept in the
|
|
|
|
|
build directory.
|
2012-06-12 14:48:52 +00:00
|
|
|
|
See the
|
|
|
|
|
"<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
|
|
|
|
|
section to learn how to locate the directory that has the temporary source code for a
|
|
|
|
|
particular package.</para></listitem>
|
|
|
|
|
<listitem><para><emphasis>Change Your Working Directory:</emphasis>
|
|
|
|
|
You need to be in the directory that has the temporary source code.
|
|
|
|
|
That directory is defined by the
|
|
|
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink>
|
|
|
|
|
variable.</para></listitem>
|
|
|
|
|
<listitem><para><emphasis>Initialize a Git Repository:</emphasis>
|
|
|
|
|
Use the <filename>git init</filename> command to initialize a new local repository
|
|
|
|
|
that is based on the work directory:
|
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
|
$ git init
|
|
|
|
|
</literallayout></para></listitem>
|
|
|
|
|
<listitem><para><emphasis>Stage all the files:</emphasis>
|
|
|
|
|
Use the <filename>git add *</filename> command to stage all the files in the source
|
|
|
|
|
code directory so that they can be committed:
|
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
|
$ git add *
|
|
|
|
|
</literallayout></para></listitem>
|
|
|
|
|
<listitem><para><emphasis>Commit the Source Files:</emphasis>
|
|
|
|
|
Use the <filename>git commit</filename> command to initially commit all the files in
|
|
|
|
|
the work directory:
|
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
|
$ git commit
|
|
|
|
|
</literallayout>
|
|
|
|
|
At this point, your Git repository is aware of all the source code files.
|
|
|
|
|
Any edits you now make to files will be tracked by Git.</para></listitem>
|
|
|
|
|
<listitem><para><emphasis>Edit the Files:</emphasis>
|
|
|
|
|
Make the changes to the temporary source code.</para></listitem>
|
|
|
|
|
<listitem><para><emphasis>Test Your Changes:</emphasis>
|
|
|
|
|
Once you have modified the source code, the easiest way to test your changes
|
|
|
|
|
is by calling the <filename>compile</filename> task as shown in the following example:
|
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
|
$ bitbake -c compile -f <name_of_package>
|
|
|
|
|
</literallayout>
|
|
|
|
|
The <filename>-f</filename> or <filename>--force</filename>
|
|
|
|
|
option forces re-execution of the specified task.
|
|
|
|
|
If you find problems with your code, you can just keep editing and
|
|
|
|
|
re-testing iteratively until things work as expected.
|
|
|
|
|
<note>All the modifications you make to the temporary source code
|
|
|
|
|
disappear once you <filename>-c clean</filename> or
|
|
|
|
|
<filename>-c cleanall</filename> with BitBake for the package.
|
|
|
|
|
Modifications will also disappear if you use the <filename>rm_work</filename>
|
|
|
|
|
feature as described in the
|
|
|
|
|
"<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
|
|
|
|
|
section of the Yocto Project Quick Start.
|
|
|
|
|
</note></para></listitem>
|
|
|
|
|
<listitem><para><emphasis>See the List of Files You Changed:</emphasis>
|
|
|
|
|
Use the <filename>git status</filename> command to see what files you have actually edited.
|
|
|
|
|
The ability to have Git track the files you have changed is an advantage that this
|
|
|
|
|
workflow has over the Quilt workflow.
|
|
|
|
|
Here is the Git command to list your changed files:
|
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
|
$ git status
|
|
|
|
|
</literallayout></para></listitem>
|
|
|
|
|
<listitem><para><emphasis>Stage the Modified Files:</emphasis>
|
|
|
|
|
Use the <filename>git add</filename> command to stage the changed files so they
|
|
|
|
|
can be committed as follows:
|
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
|
$ git add file1.c file2.c file3.c
|
|
|
|
|
</literallayout></para></listitem>
|
|
|
|
|
<listitem><para><emphasis>Commit the Staged Files and View Your Changes:</emphasis>
|
|
|
|
|
Use the <filename>git commit</filename> command to commit the changes to the
|
|
|
|
|
local repository.
|
|
|
|
|
Once you have committed the files, you can use the <filename>git log</filename>
|
|
|
|
|
command to see your changes:
|
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
|
$ git commit
|
|
|
|
|
$ git log
|
|
|
|
|
</literallayout></para></listitem>
|
|
|
|
|
<listitem><para><emphasis>Generate the Patch:</emphasis>
|
|
|
|
|
Once the changes are committed, use the <filename>git format-patch</filename>
|
|
|
|
|
command to generate a patch file:
|
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
|
$ git format-patch HEAD~1
|
|
|
|
|
</literallayout>
|
|
|
|
|
The <filename>HEAD~1</filename> part of the command causes Git to generate the
|
|
|
|
|
patch file for the most recent commit.</para>
|
|
|
|
|
<para>At this point, the patch file has all your edits made
|
|
|
|
|
to the <filename>file1.c</filename>, <filename>file2.c</filename>, and
|
|
|
|
|
<filename>file3.c</filename> files.
|
|
|
|
|
You can find the resulting patch file in the current directory.
|
|
|
|
|
The patch file ends with <filename>.patch</filename>.</para></listitem>
|
|
|
|
|
<listitem><para><emphasis>Copy the Patch File:</emphasis>
|
|
|
|
|
For simplicity, copy the patch file into a directory named <filename>files</filename>,
|
|
|
|
|
which you can create in the same directory as the recipe.
|
2012-07-02 16:59:11 +00:00
|
|
|
|
Placing the patch here guarantees that the OpenEmbedded build system will find
|
2012-06-12 14:48:52 +00:00
|
|
|
|
the patch.
|
|
|
|
|
Next, add the patch into the
|
|
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
|
|
|
|
|
of the recipe.
|
|
|
|
|
Here is an example:
|
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
|
SRC_URI += "file://my_changes.patch"
|
|
|
|
|
</literallayout></para></listitem>
|
|
|
|
|
<listitem><para><emphasis>Increment the Package Revision Number:</emphasis>
|
|
|
|
|
Finally, don't forget to 'bump' the
|
|
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename>
|
|
|
|
|
value in the same recipe since the resulting packages have changed.</para></listitem>
|
|
|
|
|
</orderedlist>
|
|
|
|
|
</para>
|
|
|
|
|
</section>
|
|
|
|
|
</section>
|
|
|
|
|
|
2012-03-22 21:01:11 +00:00
|
|
|
|
<section id='image-development-using-hob'>
|
|
|
|
|
<title>Image Development Using Hob</title>
|
|
|
|
|
|
2012-03-22 22:41:26 +00:00
|
|
|
|
<para>
|
2012-07-02 16:59:11 +00:00
|
|
|
|
The <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink> is a graphical user interface for the
|
|
|
|
|
OpenEmbedded build system, which is based on BitBake.
|
2012-03-22 22:41:26 +00:00
|
|
|
|
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.
|
2012-07-02 16:59:11 +00:00
|
|
|
|
In other words, building images with the Hob lets you take care of common build tasks more easily.
|
2012-03-22 22:41:26 +00:00
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
For a better understanding of Hob, see the project page at
|
|
|
|
|
<ulink url='&YOCTO_HOME_URL;/projects/hob'></ulink> on the Yocto Project website.
|
|
|
|
|
The page has a short introductory training video on Hob.
|
|
|
|
|
The following lists some features of Hob:
|
|
|
|
|
<itemizedlist>
|
|
|
|
|
<listitem><para>You can setup and run Hob using these commands:
|
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
|
$ source oe-init-build-env
|
|
|
|
|
$ hob
|
|
|
|
|
</literallayout></para></listitem>
|
|
|
|
|
<listitem><para>You can set the
|
|
|
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
|
|
|
|
|
for which you are building the image.</para></listitem>
|
|
|
|
|
<listitem><para>You can modify various policy settings such as the package format used to build with,
|
|
|
|
|
the parrallelism BitBake uses, whether or not to build an external toolchain, and which host
|
|
|
|
|
to build against.</para></listitem>
|
2012-04-26 15:29:21 +00:00
|
|
|
|
<listitem><para>You can manage
|
|
|
|
|
<link linkend='understanding-and-creating-layers'>layers</link>.</para></listitem>
|
2012-03-22 22:41:26 +00:00
|
|
|
|
<listitem><para>You can select a base image and then add extra packages for your custom build.
|
|
|
|
|
</para></listitem>
|
|
|
|
|
<listitem><para>You can launch and monitor the build from within Hob.</para></listitem>
|
|
|
|
|
</itemizedlist>
|
|
|
|
|
</para>
|
2012-03-22 21:01:11 +00:00
|
|
|
|
</section>
|
|
|
|
|
|
2012-07-13 20:43:30 +00:00
|
|
|
|
<section id="platdev-appdev-devshell">
|
|
|
|
|
<title>Using a Development Shell</title>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
When debugging certain commands or even when just editing packages,
|
|
|
|
|
<filename>devshell</filename> can be a useful tool.
|
|
|
|
|
When you invoke <filename>devshell</filename>, source files are
|
|
|
|
|
extracted into your working directory and patches are applied.
|
|
|
|
|
Then, a new terminal is opened and you are placed in the working directory.
|
|
|
|
|
In the new terminal, all the OpenEmbedded build-related environment variables are
|
|
|
|
|
still defined so you can use commands such as <filename>configure</filename> and
|
|
|
|
|
<filename>make</filename>.
|
|
|
|
|
The commands execute just as if the OpenEmbedded build system were executing them.
|
|
|
|
|
Consequently, working this way can be helpful when debugging a build or preparing
|
|
|
|
|
software to be used with the OpenEmbedded build system.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
Following is an example that uses <filename>devshell</filename> on a target named
|
|
|
|
|
<filename>matchbox-desktop</filename>:
|
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
|
$ bitbake matchbox-desktop -c devshell
|
|
|
|
|
</literallayout>
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
This command opens a terminal with a shell prompt within the OpenEmbedded build environment.
|
|
|
|
|
The default shell is xterm.
|
|
|
|
|
The following occurs:
|
|
|
|
|
<itemizedlist>
|
|
|
|
|
<listitem><para>The <filename>PATH</filename> variable includes the
|
|
|
|
|
cross-toolchain.</para></listitem>
|
|
|
|
|
<listitem><para>The <filename>pkgconfig</filename> variables find the correct
|
|
|
|
|
<filename>.pc</filename> files.</para></listitem>
|
|
|
|
|
<listitem><para>The <filename>configure</filename> command finds the
|
|
|
|
|
Yocto Project site files as well as any other necessary files.</para></listitem>
|
|
|
|
|
</itemizedlist>
|
|
|
|
|
Within this environment, you can run <filename>configure</filename>
|
|
|
|
|
or <filename>compile</filename> commands as if they were being run by
|
|
|
|
|
the OpenEmbedded build system itself.
|
|
|
|
|
As noted earlier, the working directory also automatically changes to the
|
|
|
|
|
source directory (<ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>).
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
When you are finished, you just exit the shell or close the terminal window.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
Because an external shell is launched rather than opening directly into the
|
|
|
|
|
original terminal window, it allows easier interaction with BitBake's multiple
|
|
|
|
|
threads as well as accomodates a future client/server split.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<note>
|
|
|
|
|
<para>
|
|
|
|
|
It is worth remembering that when using <filename>devshell</filename>
|
|
|
|
|
you need to use the full compiler name such as <filename>arm-poky-linux-gnueabi-gcc</filename>
|
|
|
|
|
instead of just using <filename>gcc</filename>.
|
|
|
|
|
The same applies to other applications such as <filename>binutils</filename>,
|
|
|
|
|
<filename>libtool</filename> and so forth.
|
|
|
|
|
BitBake sets up environment variables such as <filename>CC</filename>
|
|
|
|
|
to assist applications, such as <filename>make</filename> to find the correct tools.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
It is also worth noting that <filename>devshell</filename> still works over
|
|
|
|
|
X11 forwarding and similar situations
|
|
|
|
|
</para>
|
|
|
|
|
</note>
|
|
|
|
|
</section>
|
|
|
|
|
|
2011-07-15 19:54:29 +00:00
|
|
|
|
</chapter>
|
|
|
|
|
<!--
|
|
|
|
|
vim: expandtab tw=80 ts=4
|
|
|
|
|
-->
|