Gitiles
Code Review Sign In
gerrit.openbmc.org / mdmillerii / openbmc / 60f9d69e016b11c468c98ea75ba0a60c44afbbc4 / . / import-layers / yocto-poky / documentation / dev-manual / dev-manual-model.xml
blob: ff44a3f68bfdd69c86884cfc9ce8f6d1197b7b36 [file] [log] [blame]
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
<chapter id='dev-manual-model'>
<title>Common Development Models</title>
<para>
Many development models exist for which you can use the Yocto Project.
This chapter overviews simple methods that use tools provided by the
Yocto Project:
<itemizedlist>
<listitem><para><emphasis>System Development:</emphasis>
System Development covers Board Support Package (BSP) development
and kernel modification or configuration.
For an example on how to create a BSP, see the
"<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
section in the Yocto Project Board Support Package (BSP)
Developer's Guide.
For more complete information on how to work with the kernel,
see the
<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>.
</para></listitem>
<listitem><para><emphasis>User Application Development:</emphasis>
User Application Development covers development of applications
that you intend to run on target hardware.
For information on how to set up your host development system for
user-space application development, see the
<ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>.
For a simple example of user-space application development using
the <trademark class='trade'>Eclipse</trademark> IDE, see the
"<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-developing-applications-using-eclipse'>Developing Applications Using <trademark class='trade'>Eclipse</trademark></ulink>" section.
</para></listitem>
<listitem><para><emphasis>Temporary Source Code Modification:</emphasis>
Direct modification of temporary source code is a convenient
development model to quickly iterate and develop towards a
solution.
Once you implement the solution, 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 Toaster:</emphasis>
You can use <ulink url='&YOCTO_HOME_URL;/Tools-resources/projects/toaster'>Toaster</ulink>
to build custom operating system images within the build
environment.
Toaster provides an efficient interface to the OpenEmbedded build
that allows you to start builds and examine build statistics.
</para></listitem>
<listitem><para><emphasis>Using a Development Shell:</emphasis>
You can use a
<link linkend='platdev-appdev-devshell'><filename>devshell</filename></link>
to efficiently debug
commands or simply edit packages.
Working inside a development shell is a quick way to set up the
OpenEmbedded build environment to work on parts of a project.
</para></listitem>
</itemizedlist>
</para>
<section id='system-development-model'>
<title>System Development Workflow</title>
<para>
System development involves modification or creation of an image that you want to run on
a specific hardware target.
Usually, when you want to create an image that runs on embedded hardware, the image does
not require the same number of features that a full-fledged Linux distribution provides.
Thus, you can create a much smaller image that is designed to use only the
features for your particular hardware.
</para>
<para>
To help you understand how system development works in the Yocto Project, this section
covers two types of image development: BSP creation and kernel modification or
configuration.
</para>
<section id='developing-a-board-support-package-bsp'>
<title>Developing a Board Support Package (BSP)</title>
<para>
A BSP is a collection of recipes that, when applied during a build, results in
an image that you can run on a particular board.
Thus, the package when compiled into the new image, supports the operation of the board.
</para>
<note>
For a brief list of terms used when describing the development process in the Yocto Project,
see the "<link linkend='yocto-project-terms'>Yocto Project Terms</link>" section.
</note>
<para>
The remainder of this section presents the basic
steps used to create a BSP using the Yocto Project's
<ulink url='&YOCTO_DOCS_BSP_URL;#using-the-yocto-projects-bsp-tools'>BSP Tools</ulink>.
Although not required for BSP creation, the
<filename>meta-intel</filename> repository, which contains
many BSPs supported by the Yocto Project, is part of the example.
</para>
<para>
For an example that shows how to create a new layer using the tools, see the
"<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
section in the Yocto Project Board Support Package (BSP) Developer's Guide.
</para>
<para>
The following illustration and list summarize the BSP creation general workflow.
</para>
<para>
<imagedata fileref="figures/bsp-dev-flow.png" width="6in" depth="7in" align="center" scalefit="1" />
</para>
<para>
<orderedlist>
<listitem><para><emphasis>Set up your host development system to support
development using the Yocto Project</emphasis>: See the
"<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>"
and the
"<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>" sections both
in the Yocto Project Quick Start for requirements.</para></listitem>
<listitem><para><emphasis>Establish a local copy of the project files on your
system</emphasis>: You need this <link linkend='source-directory'>Source
Directory</link> available on your host system.
Having these files on your system gives you access to the build
process and to the tools you need.
For information on how to set up the Source Directory,
see the
"<link linkend='getting-setup'>Getting Set Up</link>" section.</para></listitem>
<listitem><para><emphasis>Establish the <filename>meta-intel</filename>
repository on your system</emphasis>: Having local copies
of these supported BSP layers on your system gives you
access to layers you might be able to build on or modify
to create your BSP.
For information on how to get these files, see the
"<link linkend='getting-setup'>Getting Set Up</link>" section.</para></listitem>
<listitem><para><emphasis>Create your own BSP layer using the
<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'><filename>yocto-bsp</filename></ulink> script</emphasis>:
Layers are ideal for
isolating and storing work for a given piece of hardware.
A layer is really just a location or area in which you place
the recipes and configurations for your BSP.
In fact, a BSP is, in itself, a special type of layer.
The simplest way to create a new BSP layer that is compliant with the
Yocto Project is to use the <filename>yocto-bsp</filename> script.
For information about that script, see the
"<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
section in the Yocto Project Board Support (BSP) Developer's Guide.
</para>
<para>
Another example that illustrates a layer
is an application.
Suppose you are creating an application that has
library or other dependencies in order for it to
compile and run.
The layer, in this case, would be where all the
recipes that define those dependencies are kept.
The key point for a layer is that it is an isolated
area that contains all the relevant information for
the project that the OpenEmbedded build system knows
about.
For more information on layers, see the
"<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>"
section.
For more information on BSP layers, see the
"<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
section in the Yocto Project Board Support Package (BSP)
Developer's Guide.
<note>
<para>
Five BSPs exist that are part of the Yocto Project release:
<filename>beaglebone</filename> (ARM),
<filename>mpc8315e</filename> (PowerPC),
and <filename>edgerouter</filename> (MIPS).
The recipes and configurations for these five BSPs
are located and dispersed within the
<link linkend='source-directory'>Source Directory</link>.
</para>
<para>
Three core Intel BSPs exist as part of the Yocto
Project release in the
<filename>meta-intel</filename> layer:
<itemizedlist>
<listitem><para><filename>intel-core2-32</filename>,
which is a BSP optimized for the Core2 family of CPUs
as well as all CPUs prior to the Silvermont core.
</para></listitem>
<listitem><para><filename>intel-corei7-64</filename>,
which is a BSP optimized for Nehalem and later
Core and Xeon CPUs as well as Silvermont and later
Atom CPUs, such as the Baytrail SoCs.
</para></listitem>
<listitem><para><filename>intel-quark</filename>,
which is a BSP optimized for the Intel Galileo
gen1 &amp; gen2 development boards.
</para></listitem>
</itemizedlist>
</para>
</note>
</para>
<para>When you set up a layer for a new BSP, you should follow a standard layout.
This layout is described in the
"<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout'>Example Filesystem Layout</ulink>"
section of the Board Support Package (BSP) Development Guide.
In the standard layout, you will notice a suggested structure for recipes and
configuration information.
You can see the standard layout for a BSP by examining
any supported BSP found in the <filename>meta-intel</filename> layer inside
the Source Directory.</para></listitem>
<listitem><para><emphasis>Make configuration changes to your new BSP
layer</emphasis>: The standard BSP layer structure organizes the files you need
to edit in <filename>conf</filename> and several <filename>recipes-*</filename>
directories within the BSP layer.
Configuration changes identify where your new layer is on the local system
and identify which kernel you are going to use.
When you run the <filename>yocto-bsp</filename> script, you are able to interactively
configure many things for the BSP (e.g. keyboard, touchscreen, and so forth).
</para></listitem>
<listitem><para><emphasis>Make recipe changes to your new BSP layer</emphasis>: Recipe
changes include altering recipes (<filename>.bb</filename> files), removing
recipes you do not use, and adding new recipes or append files
(<filename>.bbappend</filename>) that you need to support your hardware.
</para></listitem>
<listitem><para><emphasis>Prepare for the build</emphasis>: Once you have made all the
changes to your BSP layer, there remains a few things
you need to do for the OpenEmbedded build system in order for it to create your image.
You need to get the build environment ready by sourcing an environment setup script
(i.e. <filename>oe-init-build-env</filename> or
<filename>oe-init-build-env-memres</filename>)
and you need to be sure two key configuration files are configured appropriately:
the <filename>conf/local.conf</filename> and the
<filename>conf/bblayers.conf</filename> file.
You must make the OpenEmbedded build system aware of your new layer.
See the
"<link linkend='enabling-your-layer'>Enabling Your Layer</link>" section
for information on how to let the build system know about your new layer.</para>
<para>The entire process for building an image is overviewed in the section
"<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" section
of the Yocto Project Quick Start.
You might want to reference this information.</para></listitem>
<listitem><para><emphasis>Build the image</emphasis>: The OpenEmbedded build system
uses the BitBake tool to build images based on the type of image you want to create.
You can find more information about BitBake in the
<ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
</para>
<para>The build process supports several types of images to satisfy different needs.
See the
"<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter
in the Yocto Project Reference Manual for information on
supported images.</para></listitem>
</orderedlist>
</para>
<para>
You can view a video presentation on "Building Custom Embedded Images with Yocto"
at <ulink url='http://free-electrons.com/blog/elc-2011-videos'>Free Electrons</ulink>.
After going to the page, just search for "Embedded".
You can also find supplemental information in the
<ulink url='&YOCTO_DOCS_BSP_URL;'>
Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
Finally, there is helpful material and links on this
<ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>wiki page</ulink>.
Although a bit dated, you might find the information on the wiki
helpful.
</para>
</section>
<section id='modifying-the-kernel'>
<title><anchor id='kernel-spot' />Modifying the Kernel</title>
<para>
Kernel modification involves changing the Yocto Project kernel, which could involve changing
configuration options as well as adding new kernel recipes.
Configuration changes can be added in the form of configuration fragments, while recipe
modification comes through the kernel's <filename>recipes-kernel</filename> area
in a kernel layer you create.
</para>
<para>
The remainder of this section presents a high-level overview of the Yocto Project
kernel architecture and the steps to modify the kernel.
You can reference the
"<link linkend='patching-the-kernel'>Patching the Kernel</link>" section
for an example that changes the source code of the kernel.
For information on how to configure the kernel, see the
"<link linkend='configuring-the-kernel'>Configuring the Kernel</link>" section.
For more information on the kernel and on modifying the kernel, see the
<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>.
</para>
<section id='kernel-overview'>
<title>Kernel Overview</title>
<para>
Traditionally, when one thinks of a patched kernel, they think of a base kernel
source tree and a fixed structure that contains kernel patches.
The Yocto Project, however, employs mechanisms that, in a sense, result in a kernel source
generator.
By the end of this section, this analogy will become clearer.
</para>
<para>
You can find a web interface to the Yocto Project kernel source repositories at
<ulink url='&YOCTO_GIT_URL;'></ulink>.
If you look at the interface, you will see to the left a grouping of
Git repositories titled "Yocto Linux Kernel."
Within this group, you will find several kernels supported by
the Yocto Project:
<itemizedlist>
<listitem><para><emphasis>
<filename>linux-yocto-3.14</filename></emphasis> - The
stable Yocto Project kernel to use with the Yocto
Project Releases 1.6 and 1.7.
This kernel is based on the Linux 3.14 released kernel.
</para></listitem>
<listitem><para><emphasis>
<filename>linux-yocto-3.17</filename></emphasis> - An
additional, unsupported Yocto Project kernel used with
the Yocto Project Release 1.7.
This kernel is based on the Linux 3.17 released kernel.
</para></listitem>
<listitem><para><emphasis>
<filename>linux-yocto-3.19</filename></emphasis> - The
stable Yocto Project kernel to use with the Yocto
Project Release 1.8.
This kernel is based on the Linux 3.19 released kernel.
</para></listitem>
<listitem><para><emphasis>
<filename>linux-yocto-4.1</filename></emphasis> - The
stable Yocto Project kernel to use with the Yocto
Project Release 2.0.
This kernel is based on the Linux 4.1 released kernel.
</para></listitem>
<listitem><para><emphasis>
<filename>linux-yocto-4.4</filename></emphasis> - The
stable Yocto Project kernel to use with the Yocto
Project Release 2.1.
This kernel is based on the Linux 4.4 released kernel.
</para></listitem>
<listitem><para><emphasis>
<filename>linux-yocto-dev</filename></emphasis> - A
development kernel based on the latest upstream release
candidate available.
</para></listitem>
</itemizedlist>
<note>
Long Term Support Initiative (LTSI) for Yocto Project kernels
is as follows:
<itemizedlist>
<listitem><para>For Yocto Project releases 1.7, 1.8, and 2.0,
the LTSI kernel is <filename>linux-yocto-3.14</filename>.
</para></listitem>
<listitem><para>For Yocto Project release 2.1, the
LTSI kernel is <filename>linux-yocto-4.1</filename>.
</para></listitem>
</itemizedlist>
</note>
</para>
<para>
The kernels are maintained using the Git revision control system
that structures them using the familiar "tree", "branch", and "leaf" scheme.
Branches represent diversions from general code to more specific code, while leaves
represent the end-points for a complete and unique kernel whose source files,
when gathered from the root of the tree to the leaf, accumulate to create the files
necessary for a specific piece of hardware and its features.
The following figure displays this concept:
<para>
<imagedata fileref="figures/kernel-overview-1.png"
width="6in" depth="6in" align="center" scale="100" />
</para>
<para>
Within the figure, the "Kernel.org Branch Point" represents the point in the tree
where a supported base kernel is modified from the Linux kernel.
For example, this could be the branch point for the <filename>linux-yocto-3.19</filename>
kernel.
Thus, everything further to the right in the structure is based on the
<filename>linux-yocto-3.19</filename> kernel.
Branch points to the right in the figure represent where the
<filename>linux-yocto-3.19</filename> kernel is modified for specific hardware
or types of kernels, such as real-time kernels.
Each leaf thus represents the end-point for a kernel designed to run on a specific
targeted device.
</para>
<para>
The overall result is a Git-maintained repository from which all the supported
kernel types can be derived for all the supported devices.
A big advantage to this scheme is the sharing of common features by keeping them in
"larger" branches within the tree.
This practice eliminates redundant storage of similar features shared among kernels.
</para>
<note>
Keep in mind the figure does not take into account all the supported Yocto
Project kernel types, but rather shows a single generic kernel just for conceptual purposes.
Also keep in mind that this structure represents the Yocto Project source repositories
that are either pulled from during the build or established on the host development system
prior to the build by either cloning a particular kernel's Git repository or by
downloading and unpacking a tarball.
</note>
<para>
Upstream storage of all the available kernel source code is one thing, while
representing and using the code on your host development system is another.
Conceptually, you can think of the kernel source repositories as all the
source files necessary for all the supported kernels.
As a developer, you are just interested in the source files for the kernel on
which you are working.
And, furthermore, you need them available on your host system.
</para>
<para>
Kernel source code is available on your host system a couple of different
ways.
If you are working in the kernel all the time, you probably would want
to set up your own local Git repository of the kernel tree.
If you just need to make some patches to the kernel, you can access
temporary kernel source files that were extracted and used
during a build.
We will just talk about working with the temporary source code.
For more information on how to get kernel source code onto your
host system, see the
"<link linkend='local-kernel-files'>Yocto Project Kernel</link>"
bulleted item earlier in the manual.
</para>
<para>
What happens during the build?
When you build the kernel on your development system, all files needed for the build
are taken from the source repositories pointed to by the
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> variable
and gathered in a temporary work area
where they are subsequently used to create the unique kernel.
Thus, in a sense, the process constructs a local source tree specific to your
kernel to generate the new kernel image - a source generator if you will.
</para>
The following figure shows the temporary file structure
created on your host system when the build occurs.
This
<link linkend='build-directory'>Build Directory</link> contains all the
source files used during the build.
</para>
<para>
<imagedata fileref="figures/kernel-overview-2-generic.png"
width="6in" depth="5in" align="center" scale="100" />
</para>
<para>
Again, for additional information on the Yocto Project kernel's
architecture and its branching strategy, see the
<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>.
You can also reference the
"<link linkend='patching-the-kernel'>Patching the Kernel</link>"
section for a detailed example that modifies the kernel.
</para>
</section>
<section id='kernel-modification-workflow'>
<title>Kernel Modification Workflow</title>
<para>
This illustration and the following list summarizes the kernel modification general workflow.
</para>
<para>
<imagedata fileref="figures/kernel-dev-flow.png"
width="6in" depth="5in" align="center" scalefit="1" />
</para>
<para>
<orderedlist>
<listitem><para><emphasis>Set up your host development system to support
development using the Yocto Project</emphasis>: See
"<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>" and
"<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>" sections both
in the Yocto Project Quick Start for requirements.</para></listitem>
<listitem><para><emphasis>Establish a local copy of project files on your
system</emphasis>: Having the <link linkend='source-directory'>Source
Directory</link> on your system gives you access to the build process and tools
you need.
For information on how to get these files, see the bulleted item
"<link linkend='local-yp-release'>Yocto Project Release</link>" earlier in this manual.
</para></listitem>
<listitem><para><emphasis>Establish the temporary kernel source files</emphasis>:
Temporary kernel source files are kept in the
<link linkend='build-directory'>Build Directory</link>
created by the
OpenEmbedded build system when you run BitBake.
If you have never built the kernel in which you are
interested, you need to run an initial build to
establish local kernel source files.</para>
<para>If you are building an image for the first time, you need to get the build
environment ready by sourcing an environment setup script
(i.e. <filename>oe-init-build-env</filename> or
<filename>oe-init-build-env-memres</filename>).
You also need to be sure two key configuration files
(<filename>local.conf</filename> and <filename>bblayers.conf</filename>)
are configured appropriately.</para>
<para>The entire process for building an image is overviewed in the
"<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
section of the Yocto Project Quick Start.
You might want to reference this information.
You can find more information on BitBake in the
<ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
</para>
<para>The build process supports several types of images to satisfy different needs.
See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in
the Yocto Project Reference Manual for information on supported images.
</para></listitem>
<listitem><para><emphasis>Make changes to the kernel source code if
applicable</emphasis>: Modifying the kernel does not always mean directly
changing source files.
However, if you have to do this, you make the changes to the files in the
Build Directory.</para></listitem>
<listitem><para><emphasis>Make kernel configuration changes if applicable</emphasis>:
If your situation calls for changing the kernel's
configuration, you can use
<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'><filename>menuconfig</filename></ulink>,
which allows you to interactively develop and test the
configuration changes you are making to the kernel.
Saving changes you make with
<filename>menuconfig</filename> updates
the kernel's <filename>.config</filename> file.
<note><title>Warning</title>
Try to resist the temptation to directly edit an
existing <filename>.config</filename> file, which is
found in the Build Directory at
<filename>tmp/sysroots/<replaceable>machine-name</replaceable>/kernel</filename>.
Doing so, can produce unexpected results when the
OpenEmbedded build system regenerates the configuration
file.
</note>
Once you are satisfied with the configuration
changes made using <filename>menuconfig</filename>
and you have saved them, you can directly compare the
resulting <filename>.config</filename> file against an
existing original and gather those changes into a
<link linkend='creating-config-fragments'>configuration fragment file</link>
to be referenced from within the kernel's
<filename>.bbappend</filename> file.</para>
<para>Additionally, if you are working in a BSP layer
and need to modify the BSP's kernel's configuration,
you can use the
<ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'><filename>yocto-kernel</filename></ulink>
script as well as <filename>menuconfig</filename>.
The <filename>yocto-kernel</filename> script lets
you interactively set up kernel configurations.
</para></listitem>
<listitem><para><emphasis>Rebuild the kernel image with your changes</emphasis>:
Rebuilding the kernel image applies your changes.
</para></listitem>
</orderedlist>
</para>
</section>
</section>
</section>
<section id='application-development-workflow-using-an-sdk'>
<title>Application Development Workflow Using an SDK</title>
<para>
Standard and extensible Software Development Kits (SDK) make it easy
to develop applications inside or outside of the Yocto Project
development environment.
Tools exist to help the application developer during any phase
of development.
For information on how to install and use an SDK, see the
<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-intro'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>.
</para>
</section>
<section id="dev-modifying-source-code">
<title>Modifying Source Code</title>
<para>
A common development workflow consists of modifying project source
files that are external to the Yocto Project and then integrating
that project's build output into an image built using the
OpenEmbedded build system.
Given this scenario, development engineers typically want to stick
to their familiar project development tools and methods, which allows
them to just focus on the project.
</para>
<para>
Several workflows exist that allow you to develop, build, and test
code that is going to be integrated into an image built using the
OpenEmbedded build system.
This section describes two:
<itemizedlist>
<listitem><para><emphasis><filename>devtool</filename>:</emphasis>
A set of tools to aid in working on the source code built by
the OpenEmbedded build system.
Section
"<link linkend='using-devtool-in-your-workflow'>Using <filename>devtool</filename> in Your Workflow</link>"
describes this workflow.
If you want more information that showcases the workflow, click
<ulink url='https://drive.google.com/a/linaro.org/file/d/0B3KGzY5fW7laTDVxUXo3UDRvd2s/view'>here</ulink>
for a presentation by Trevor Woerner that, while somewhat dated,
provides detailed background information and a complete
working tutorial.
</para></listitem>
<listitem><para><emphasis><ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink>:</emphasis>
A powerful tool that allows you to capture source
code changes without having a clean source tree.
While Quilt is not the preferred workflow of the two, this
section includes it for users that are committed to using
the tool.
See the
"<link linkend='using-a-quilt-workflow'>Using Quilt in Your Workflow</link>"
section for more information.
</para></listitem>
</itemizedlist>
</para>
<section id='using-devtool-in-your-workflow'>
<title>Using <filename>devtool</filename> in Your Workflow</title>
<para>
As mentioned earlier, <filename>devtool</filename> helps
you easily develop projects whose build output must be part of
an image built using the OpenEmbedded build system.
</para>
<para>
Three entry points exist that allow you to develop using
<filename>devtool</filename>:
<itemizedlist>
<listitem><para><emphasis><filename>devtool add</filename></emphasis>
</para></listitem>
<listitem><para><emphasis><filename>devtool modify</filename></emphasis>
</para></listitem>
<listitem><para><emphasis><filename>devtool upgrade</filename></emphasis>
</para></listitem>
</itemizedlist>
</para>
<para>
The remainder of this section presents these workflows.
</para>
<section id='use-devtool-to-integrate-new-code'>
<title>Use <filename>devtool add</filename> to Integrate New Code</title>
<para>
The <filename>devtool add</filename> command generates
a new recipe based on existing source code.
This command takes advantage of the
<link linkend='devtool-the-workspace-layer-structure'>workspace</link>
layer that many <filename>devtool</filename> commands
use.
The command is flexible enough to allow you to extract source
code into both the workspace or a separate local Git repository
and to use existing code that does not need to be extracted.
</para>
<para>
Depending on your particular scenario, the arguments and options
you use with <filename>devtool add</filename> form different
combinations.
The following diagram shows common development flows
you would use with the <filename>devtool add</filename>
command:
</para>
<para>
<imagedata fileref="figures/devtool-add-flow.png" align="center" />
</para>
<para>
<orderedlist>
<listitem><para><emphasis>Generating the New Recipe</emphasis>:
The top part of the flow shows three scenarios by which
you could use <filename>devtool add</filename> to
generate a recipe based on existing source code.</para>
<para>In a shared development environment, it is
typical where other developers are responsible for
various areas of source code.
As a developer, you are probably interested in using
that source code as part of your development using
the Yocto Project.
All you need is access to the code, a recipe, and a
controlled area in which to do your work.</para>
<para>Within the diagram, three possible scenarios
feed into the <filename>devtool add</filename> workflow:
<itemizedlist>
<listitem><para><emphasis>Left</emphasis>:
The left scenario represents a common situation
where the source code does not exist locally
and needs to be extracted.
In this situation, you just let it get
extracted to the default workspace - you do not
want it in some specific location outside of the
workspace.
Thus, everything you need will be located in the
workspace:
<literallayout class='monospaced'>
$ devtool add <replaceable>recipe fetchuri</replaceable>
</literallayout>
With this command, <filename>devtool</filename>
creates a recipe and an append file in the
workspace as well as extracts the upstream
source files into a local Git repository also
within the <filename>sources</filename> folder.
</para></listitem>
<listitem><para><emphasis>Middle</emphasis>:
The middle scenario also represents a situation where
the source code does not exist locally.
In this case, the code is again upstream
and needs to be extracted to some
local area - this time outside of the default
workspace.
As always, if required <filename>devtool</filename> creates
a Git repository locally during the extraction.
Furthermore, the first positional argument
<replaceable>srctree</replaceable> in this case
identifies where the
<filename>devtool add</filename> command
will locate the extracted code outside of the
workspace:
<literallayout class='monospaced'>
$ devtool add <replaceable>recipe srctree fetchuri</replaceable>
</literallayout>
In summary, the source code is pulled from
<replaceable>fetchuri</replaceable> and extracted
into the location defined by
<replaceable>srctree</replaceable> as a local
Git repository.</para>
<para>Within workspace, <filename>devtool</filename>
creates both the recipe and an append file
for the recipe.
</para></listitem>
<listitem><para><emphasis>Right</emphasis>:
The right scenario represents a situation
where the source tree (srctree) has been
previously prepared outside of the
<filename>devtool</filename> workspace.
</para>
<para>The following command names the recipe
and identifies where the existing source tree
is located:
<literallayout class='monospaced'>
$ devtool add <replaceable>recipe srctree</replaceable>
</literallayout>
The command examines the source code and creates
a recipe for it placing the recipe into the
workspace.</para>
<para>Because the extracted source code already exists,
<filename>devtool</filename> does not try to
relocate it into the workspace - just the new
the recipe is placed in the workspace.</para>
<para>Aside from a recipe folder, the command
also creates an append folder and places an initial
<filename>*.bbappend</filename> within.
</para></listitem>
</itemizedlist>
</para></listitem>
<listitem><para><emphasis>Edit the Recipe</emphasis>:
At this point, you can use <filename>devtool edit-recipe</filename>
to open up the editor as defined by the
<filename>$EDITOR</filename> environment variable
and modify the file:
<literallayout class='monospaced'>
$ devtool edit-recipe <replaceable>recipe</replaceable>
</literallayout>
From within the editor, you can make modifications to the
recipe that take affect when you build it later.
</para></listitem>
<listitem><para><emphasis>Build the Recipe or Rebuild the Image</emphasis>:
At this point in the flow, the next step you
take depends on what you are going to do with
the new code.</para>
<para>If you need to take the build output and eventually
move it to the target hardware, you would use
<filename>devtool build</filename>:
<note>
You could use <filename>bitbake</filename> to build
the recipe as well.
</note>
<literallayout class='monospaced'>
$ devtool build <replaceable>recipe</replaceable>
</literallayout></para>
<para>On the other hand, if you want an image to
contain the recipe's packages for immediate deployment
onto a device (e.g. for testing purposes), you can use
the <filename>devtool build-image</filename> command:
<literallayout class='monospaced'>
$ devtool build-image <replaceable>image</replaceable>
</literallayout>
</para></listitem>
<listitem><para><emphasis>Deploy the Build Output</emphasis>:
When you use the <filename>devtool build</filename>
command to build out your recipe, you probably want to
see if the resulting build output works as expected on target
hardware.
<note>
This step assumes you have a previously built
image that is already either running in QEMU or
running on actual hardware.
Also, it is assumed that for deployment of the image
to the target, SSH is installed in the image and if
the image is running on real hardware that you have
network access to and from your development machine.
</note>
You can deploy your build output to that target hardware by
using the <filename>devtool deploy-target</filename> command:
<literallayout class='monospaced'>
$ devtool deploy-target <replaceable>recipe target</replaceable>
</literallayout>
The <replaceable>target</replaceable> is a live target machine
running as an SSH server.</para>
<para>You can, of course, also deploy the image you build
using the <filename>devtool build-image</filename> command
to actual hardware.
However, <filename>devtool</filename> does not provide a
specific command that allows you to do this.
</para></listitem>
<listitem><para><emphasis>Optionally Update the Recipe With Patch Files</emphasis>:
Once you are satisfied with the recipe, if you have made
any changes to the source tree that you want to have
applied by the recipe, you need to generate patches
from those changes.
You do this before moving the recipe
to its final layer and cleaning up the workspace area
<filename>devtool</filename> uses.
This optional step is especially relevant if you are
using or adding third-party software.</para>
<para>To convert commits created using Git to patch files,
use the <filename>devtool update-recipe</filename> command.
<note>
Any changes you want to turn into patches must be
committed to the Git repository in the source tree.
</note>
<literallayout class='monospaced'>
$ devtool update-recipe <replaceable>recipe</replaceable>
</literallayout>
</para></listitem>
<listitem><para><emphasis>Move the Recipe to its Permanent Layer</emphasis>:
Before cleaning up the workspace, you need to move the
final recipe to its permanent layer.
You must do this before using the
<filename>devtool reset</filename> command if you want to
retain the recipe.
</para></listitem>
<listitem><para><emphasis>Reset the Recipe</emphasis>:
As a final step, you can restore the state such that
standard layers and the upstream source is used to build
the recipe rather than data in the workspace.
To reset the recipe, use the <filename>devtool reset</filename>
command:
<literallayout class='monospaced'>
$ devtool reset <replaceable>recipe</replaceable>
</literallayout>
</para></listitem>
</orderedlist>
</para>
</section>
<section id='devtool-use-devtool-modify-to-enable-work-on-code-associated-with-an-existing-recipe'>
<title>Use <filename>devtool modify</filename> to Enable Work on Code Associated with an Existing Recipe</title>
<para>
The <filename>devtool modify</filename> command prepares the
way to work on existing code that already has a recipe in
place.
The command is flexible enough to allow you to extract code,
specify the existing recipe, and keep track of and gather any
patch files from other developers that are
associated with the code.
</para>
<para>
Depending on your particular scenario, the arguments and options
you use with <filename>devtool modify</filename> form different
combinations.
The following diagram shows common development flows
you would use with the <filename>devtool modify</filename>
command:
</para>
<para>
<imagedata fileref="figures/devtool-modify-flow.png" align="center" />
</para>
<para>
<orderedlist>
<listitem><para><emphasis>Preparing to Modify the Code</emphasis>:
The top part of the flow shows three scenarios by which
you could use <filename>devtool modify</filename> to
prepare to work on source files.
Each scenario assumes the following:
<itemizedlist>
<listitem><para>The recipe exists in some layer external
to the <filename>devtool</filename> workspace.
</para></listitem>
<listitem><para>The source files exist upstream in an
un-extracted state or locally in a previously
extracted state.
</para></listitem>
</itemizedlist>
The typical situation is where another developer has
created some layer for use with the Yocto Project and
their recipe already resides in that layer.
Furthermore, their source code is readily available
either upstream or locally.
<itemizedlist>
<listitem><para><emphasis>Left</emphasis>:
The left scenario represents a common situation
where the source code does not exist locally
and needs to be extracted.
In this situation, the source is extracted
into the default workspace location.
The recipe, in this scenario, is in its own
layer outside the workspace
(i.e.
<filename>meta-</filename><replaceable>layername</replaceable>).
</para>
<para>The following command identifies the recipe
and by default extracts the source files:
<literallayout class='monospaced'>
$ devtool modify <replaceable>recipe</replaceable>
</literallayout>
Once <filename>devtool</filename>locates the recipe,
it uses the
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
variable to locate the source code and
any local patch files from other developers are
located.
<note>
You cannot provide an URL for
<replaceable>srctree</replaceable> when using the
<filename>devtool modify</filename> command.
</note>
With this scenario, however, since no
<replaceable>srctree</replaceable> argument exists, the
<filename>devtool modify</filename> command by default
extracts the source files to a Git structure.
Furthermore, the location for the extracted source is the
default area within the workspace.
The result is that the command sets up both the source
code and an append file within the workspace with the
recipe remaining in its original location.
</para></listitem>
<listitem><para><emphasis>Middle</emphasis>:
The middle scenario represents a situation where
the source code also does not exist locally.
In this case, the code is again upstream
and needs to be extracted to some
local area as a Git repository.
The recipe, in this scenario, is again in its own
layer outside the workspace.</para>
<para>The following command tells
<filename>devtool</filename> what recipe with
which to work and, in this case, identifies a local
area for the extracted source files that is outside
of the default workspace:
<literallayout class='monospaced'>
$ devtool modify <replaceable>recipe srctree</replaceable>
</literallayout>
As with all extractions, the command uses
the recipe's <filename>SRC_URI</filename> to locate the
source files.
Once the files are located, the command by default
extracts them.
Providing the <replaceable>srctree</replaceable>
argument instructs <filename>devtool</filename> where
place the extracted source.</para>
<para>Within workspace, <filename>devtool</filename>
creates an append file for the recipe.
The recipe remains in its original location but
the source files are extracted to the location you
provided with <replaceable>srctree</replaceable>.
</para></listitem>
<listitem><para><emphasis>Right</emphasis>:
The right scenario represents a situation
where the source tree
(<replaceable>srctree</replaceable>) exists as a
previously extracted Git structure outside of
the <filename>devtool</filename> workspace.
In this example, the recipe also exists
elsewhere in its own layer.
</para>
<para>The following command tells
<filename>devtool</filename> the recipe
with which to work, uses the "-n" option to indicate
source does not need to be extracted, and uses
<replaceable>srctree</replaceable> to point to the
previously extracted source files:
<literallayout class='monospaced'>
$ devtool modify -n <replaceable>recipe srctree</replaceable>
</literallayout>
</para>
<para>Once the command finishes, it creates only
an append file for the recipe in the workspace.
The recipe and the source code remain in their
original locations.
</para></listitem>
</itemizedlist>
</para></listitem>
<listitem><para><emphasis>Edit the Source</emphasis>:
Once you have used the <filename>devtool modify</filename>
command, you are free to make changes to the source
files.
You can use any editor you like to make and save
your source code modifications.
</para></listitem>
<listitem><para><emphasis>Build the Recipe</emphasis>:
Once you have updated the source files, you can build
the recipe.
You can either use <filename>devtool build</filename> or
<filename>bitbake</filename>.
Either method produces build output that is stored
in
<ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>.
</para></listitem>
<listitem><para><emphasis>Deploy the Build Output</emphasis>:
When you use the <filename>devtool build</filename>
command or <filename>bitbake</filename> to build out your
recipe, you probably want to see if the resulting build
output works as expected on target hardware.
<note>
This step assumes you have a previously built
image that is already either running in QEMU or
running on actual hardware.
Also, it is assumed that for deployment of the image
to the target, SSH is installed in the image and if
the image is running on real hardware that you have
network access to and from your development machine.
</note>
You can deploy your build output to that target hardware by
using the <filename>devtool deploy-target</filename> command:
<literallayout class='monospaced'>
$ devtool deploy-target <replaceable>recipe target</replaceable>
</literallayout>
The <replaceable>target</replaceable> is a live target machine
running as an SSH server.</para>
<para>You can, of course, also deploy the image you build
using the <filename>devtool build-image</filename> command
to actual hardware.
However, <filename>devtool</filename> does not provide a
specific command that allows you to do this.
</para></listitem>
<listitem><para><emphasis>Optionally Create Patch Files for Your Changes</emphasis>:
After you have debugged your changes, you can
use <filename>devtool update-recipe</filename> to
generate patch files for all the commits you have
made.
<note>
Patch files are generated only for changes
you have committed.
</note>
<literallayout class='monospaced'>
$ devtool update-recipe <replaceable>recipe</replaceable>
</literallayout>
By default, the
<filename>devtool update-recipe</filename> command
creates the patch files in a folder named the same
as the recipe beneath the folder in which the recipe
resides, and updates the recipe's
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
statement to point to the generated patch files.
<note>
You can use the
"--append <replaceable>LAYERDIR</replaceable>"
option to cause the command to create append files
in a specific layer rather than the default
recipe layer.
</note>
</para></listitem>
<listitem><para><emphasis>Restore the Workspace</emphasis>:
The <filename>devtool reset</filename> restores the
state so that standard layers and upstream sources are
used to build the recipe rather than what is in the
workspace.
<literallayout class='monospaced'>
$ devtool reset <replaceable>recipe</replaceable>
</literallayout>
</para></listitem>
</orderedlist>
</para>
</section>
<section id='devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software'>
<title>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</title>
<para>
The <filename>devtool upgrade</filename> command updates
an existing recipe so that you can build it for an updated
set of source files.
The command is flexible enough to allow you to specify
source code revision and versioning schemes, extract code into
or out of the <filename>devtool</filename> workspace, and
work with any source file forms that the fetchers support.
</para>
<para>
Depending on your particular scenario, the arguments and options
you use with <filename>devtool upgrade</filename> form different
combinations.
The following diagram shows a common development flow
you would use with the <filename>devtool modify</filename>
command:
</para>
<para>
<imagedata fileref="figures/devtool-upgrade-flow.png" align="center" />
</para>
<para>
<orderedlist>
<listitem><para><emphasis>Initiate the Upgrade</emphasis>:
The top part of the flow shows a typical scenario by which
you could use <filename>devtool upgrade</filename>.
The following conditions exist:
<itemizedlist>
<listitem><para>The recipe exists in some layer external
to the <filename>devtool</filename> workspace.
</para></listitem>
<listitem><para>The source files for the new release
exist adjacent to the same location pointed to by
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
in the recipe (e.g. a tarball with the new version
number in the name, or as a different revision in
the upstream Git repository).
</para></listitem>
</itemizedlist>
A common situation is where third-party software has
undergone a revision so that it has been upgraded.
The recipe you have access to is likely in your own layer.
Thus, you need to upgrade the recipe to use the
newer version of the software:
<literallayout class='monospaced'>
$ devtool upgrade -V <replaceable>version recipe</replaceable>
</literallayout>
By default, the <filename>devtool upgrade</filename> command
extracts source code into the <filename>sources</filename>
directory in the workspace.
If you want the code extracted to any other location, you
need to provide the <replaceable>srctree</replaceable>
positional argument with the command as follows:
<literallayout class='monospaced'>
$ devtool upgrade -V <replaceable>version recipe srctree</replaceable>
</literallayout>
Also, in this example, the "-V" option is used to specify
the new version.
If the source files pointed to by the
<filename>SRC_URI</filename> statement in the recipe are
in a Git repository, you must provide the "-S" option and
specify a revision for the software.</para>
<para>Once <filename>devtool</filename> locates the recipe,
it uses the <filename>SRC_URI</filename> variable to locate
the source code and any local patch files from other
developers are located.
The result is that the command sets up the source
code, the new version of the recipe, and an append file
all within the workspace.
</para></listitem>
<listitem><para><emphasis>Resolve any Conflicts created by the Upgrade</emphasis>:
At this point, there could be some conflicts due to the
software being upgraded to a new version.
This would occur if your recipe specifies some patch files in
<filename>SRC_URI</filename> that conflict with changes
made in the new version of the software.
If this is the case, you need to resolve the conflicts
by editing the source and following the normal
<filename>git rebase</filename> conflict resolution
process.</para>
<para>Before moving onto the next step, be sure to resolve any
such conflicts created through use of a newer or different
version of the software.
</para></listitem>
<listitem><para><emphasis>Build the Recipe</emphasis>:
Once you have your recipe in order, you can build it.
You can either use <filename>devtool build</filename> or
<filename>bitbake</filename>.
Either method produces build output that is stored
in
<ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>.
</para></listitem>
<listitem><para><emphasis>Deploy the Build Output</emphasis>:
When you use the <filename>devtool build</filename>
command or <filename>bitbake</filename> to build out your
recipe, you probably want to see if the resulting build
output works as expected on target hardware.
<note>
This step assumes you have a previously built
image that is already either running in QEMU or
running on actual hardware.
Also, it is assumed that for deployment of the image
to the target, SSH is installed in the image and if
the image is running on real hardware that you have
network access to and from your development machine.
</note>
You can deploy your build output to that target hardware by
using the <filename>devtool deploy-target</filename> command:
<literallayout class='monospaced'>
$ devtool deploy-target <replaceable>recipe target</replaceable>
</literallayout>
The <replaceable>target</replaceable> is a live target machine
running as an SSH server.</para>
<para>You can, of course, also deploy the image you build
using the <filename>devtool build-image</filename> command
to actual hardware.
However, <filename>devtool</filename> does not provide a
specific command that allows you to do this.
</para></listitem>
<listitem><para><emphasis>Optionally Create Patch Files for Your Changes</emphasis>:
After you have debugged your changes, you can
use <filename>devtool update-recipe</filename> to
generate patch files for all the commits you have
made.
<note>
Patch files are generated only for changes
you have committed.
</note>
<literallayout class='monospaced'>
$ devtool update-recipe <replaceable>recipe</replaceable>
</literallayout>
By default, the
<filename>devtool update-recipe</filename> command
creates the patch files in a folder named the same
as the recipe beneath the folder in which the recipe
resides, and updates the recipe's
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
statement to point to the generated patch files.
</para></listitem>
<listitem><para><emphasis>Move the Recipe to its Permanent Layer</emphasis>:
Before cleaning up the workspace, you need to move the
final recipe to its permanent layer.
You can either overwrite the original recipe or you can
overlay the upgraded recipe into a separate layer.
You must do this before using the
<filename>devtool reset</filename> command if you want to
retain the upgraded recipe.
</para></listitem>
<listitem><para><emphasis>Restore the Workspace</emphasis>:
The <filename>devtool reset</filename> restores the
state so that standard layers and upstream sources are
used to build the recipe rather than what is in the
workspace.
<literallayout class='monospaced'>
$ devtool reset <replaceable>recipe</replaceable>
</literallayout>
</para></listitem>
</orderedlist>
</para>
</section>
</section>
<section id='devtool-quick-reference'>
<title><filename>devtool</filename> Quick Reference</title>
<para>
<filename>devtool</filename> has more functionality than simply
adding a new recipe and the supporting Metadata to a temporary
workspace layer.
This section provides a short reference on
<filename>devtool</filename> and its commands.
</para>
<section id='devtool-getting-help'>
<title>Getting Help</title>
<para>
The easiest way to get help with the
<filename>devtool</filename> command is using the
<filename>--help</filename> option:
<literallayout class='monospaced'>
usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] [-d] [-q]
[--color COLOR] [-h]
&lt;subcommand&gt; ...
OpenEmbedded development tool
optional arguments:
--basepath BASEPATH Base directory of SDK / build directory
--bbpath BBPATH Explicitly specify the BBPATH, rather than getting it
from the metadata
-d, --debug Enable debug output
-q, --quiet Print only errors
--color COLOR Colorize output (where COLOR is auto, always, never)
-h, --help show this help message and exit
subcommands:
Beginning work on a recipe:
add Add a new recipe
modify Modify the source for an existing recipe
upgrade Upgrade an existing recipe
Getting information:
status Show workspace status
search Search available recipes
Working on a recipe in the workspace:
build Build a recipe
edit-recipe Edit a recipe file in your workspace
configure-help Get help on configure script options
update-recipe Apply changes from external source tree to recipe
reset Remove a recipe from your workspace
Testing changes on target:
deploy-target Deploy recipe output files to live target machine
undeploy-target Undeploy recipe output files in live target machine
build-image Build image including workspace recipe packages
Advanced:
create-workspace Set up workspace in an alternative location
extract Extract the source for an existing recipe
sync Synchronize the source tree for an existing recipe
Use devtool &lt;subcommand&gt; --help to get help on a specific command
</literallayout>
</para>
<para>
As directed in the general help output, you can get more
syntax on a specific command by providing the command
name and using <filename>--help</filename>:
<literallayout class='monospaced'>
$ devtool add --help
usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI]
[--version VERSION] [--no-git] [--binary] [--also-native]
[--src-subdir SUBDIR]
[recipename] [srctree] [fetchuri]
Adds a new recipe to the workspace to build a specified source tree. Can
optionally fetch a remote URI and unpack it to create the source tree.
positional arguments:
recipename Name for new recipe to add (just name - no version,
path or extension). If not specified, will attempt to
auto-detect it.
srctree Path to external source tree. If not specified, a
subdirectory of
/home/scottrif/poky/build/workspace/sources will be
used.
fetchuri Fetch the specified URI and extract it to create the
source tree
optional arguments:
-h, --help show this help message and exit
--same-dir, -s Build in same directory as source
--no-same-dir Force build in a separate build directory
--fetch URI, -f URI Fetch the specified URI and extract it to create the
source tree (deprecated - pass as positional argument
instead)
--version VERSION, -V VERSION
Version to use within recipe (PV)
--no-git, -g If fetching source, do not set up source tree as a git
repository
--binary, -b Treat the source tree as something that should be
installed verbatim (no compilation, same directory
structure). Useful with binary packages e.g. RPMs.
--also-native Also add native variant (i.e. support building recipe
for the build host as well as the target machine)
--src-subdir SUBDIR Specify subdirectory within source tree to use
</literallayout>
</para>
</section>
<section id='devtool-the-workspace-layer-structure'>
<title>The Workspace Layer Structure</title>
<para>
<filename>devtool</filename> uses a "Workspace" layer
in which to accomplish builds.
This layer is not specific to any single
<filename>devtool</filename> command but is rather a common
working area used across the tool.
</para>
<para>
The following figure shows the workspace structure:
</para>
<para>
<imagedata fileref="figures/build-workspace-directory.png"
width="6in" depth="5in" align="left" scale="70" />
</para>
<para>
<literallayout class='monospaced'>
attic - A directory created if devtool believes it preserve
anything when you run "devtool reset". For example, if you
run "devtool add", make changes to the recipe, and then
run "devtool reset", devtool takes notice that the file has
been changed and moves it into the attic should you still
want the recipe.
README - Provides information on what is in workspace layer and how to
manage it.
.devtool_md5 - A checksum file used by devtool.
appends - A directory that contains *.bbappend files, which point to
external source.
conf - A configuration directory that contains the layer.conf file.
recipes - A directory containing recipes. This directory contains a
folder for each directory added whose name matches that of the
added recipe. devtool places the <replaceable>recipe</replaceable>.bb file
within that sub-directory.
sources - A directory containing a working copy of the source files used
when building the recipe. This is the default directory used
as the location of the source tree when you do not provide a
source tree path. This directory contains a folder for each
set of source files matched to a corresponding recipe.
</literallayout>
</para>
</section>
<section id='devtool-adding-a-new-recipe-to-the-workspace'>
<title>Adding a New Recipe to the Workspace Layer</title>
<para>
Use the <filename>devtool add</filename> command to add a new recipe
to the workspace layer.
The recipe you add should not exist -
<filename>devtool</filename> creates it for you.
The source files the recipe uses should exist in an external
area.
</para>
<para>
The following example creates and adds a new recipe named
<filename>jackson</filename> to a workspace layer the tool creates.
The source code built by the recipes resides in
<filename>/home/scottrif/sources/jackson</filename>:
<literallayout class='monospaced'>
$ devtool add jackson /home/scottrif/sources/jackson
</literallayout>
</para>
<para>
If you add a recipe and the workspace layer does not exist,
the command creates the layer and populates it as
described in
"<link linkend='devtool-the-workspace-layer-structure'>The Workspace Layer Structure</link>"
section.
</para>
<para>
Running <filename>devtool add</filename> when the
workspace layer exists causes the tool to add the recipe,
append files, and source files into the existing workspace layer.
The <filename>.bbappend</filename> file is created to point
to the external source tree.
</para>
</section>
<section id='devtool-extracting-the-source-for-an-existing-recipe'>
<title>Extracting the Source for an Existing Recipe</title>
<para>
Use the <filename>devtool extract</filename> command to
extract the source for an existing recipe.
When you use this command, you must supply the root name
of the recipe (i.e. no version, paths, or extensions), and
you must supply the directory to which you want the source
extracted.
</para>
<para>
Additional command options let you control the name of a
development branch into which you can checkout the source
and whether or not to keep a temporary directory, which is
useful for debugging.
</para>
</section>
<section id='devtool-synchronizing-a-recipes-extracted-source-tree'>
<title>Synchronizing a Recipe's Extracted Source Tree</title>
<para>
Use the <filename>devtool sync</filename> command to
synchronize a previously extracted source tree for an
existing recipe.
When you use this command, you must supply the root name
of the recipe (i.e. no version, paths, or extensions), and
you must supply the directory to which you want the source
extracted.
</para>
<para>
Additional command options let you control the name of a
development branch into which you can checkout the source
and whether or not to keep a temporary directory, which is
useful for debugging.
</para>
</section>
<section id='devtool-modifying-a-recipe'>
<title>Modifying an Existing Recipe</title>
<para>
Use the <filename>devtool modify</filename> command to begin
modifying the source of an existing recipe.
This command is very similar to the
<link linkend='devtool-adding-a-new-recipe-to-the-workspace'><filename>add</filename></link>
command except that it does not physically create the
recipe in the workspace layer because the recipe already
exists in an another layer.
</para>
<para>
The <filename>devtool modify</filename> command extracts the
source for a recipe, sets it up as a Git repository if the
source had not already been fetched from Git, checks out a
branch for development, and applies any patches from the recipe
as commits on top.
You can use the following command to checkout the source
files:
<literallayout class='monospaced'>
$ devtool modify <replaceable>recipe</replaceable>
</literallayout>
Using the above command form, <filename>devtool</filename> uses
the existing recipe's
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
statement to locate the upstream source, extracts the source
into the default sources location in the workspace.
The default development branch used is "devtool".
</para>
</section>
<section id='devtool-edit-an-existing-recipe'>
<title>Edit an Existing Recipe</title>
<para>
Use the <filename>devtool edit-recipe</filename> command
to run the default editor, which is identified using the
<filename>EDITOR</filename> variable, on the specified recipe.
</para>
<para>
When you use the <filename>devtool edit-recipe</filename>
command, you must supply the root name of the recipe
(i.e. no version, paths, or extensions).
Also, the recipe file itself must reside in the workspace
as a result of the <filename>devtool add</filename> or
<filename>devtool upgrade</filename> commands.
However, you can override that requirement by using the
"-a" or "--any-recipe" option.
Using either of these options allows you to edit any recipe
regardless of its location.
</para>
</section>
<section id='devtool-updating-a-recipe'>
<title>Updating a Recipe</title>
<para>
Use the <filename>devtool update-recipe</filename> command to
update your recipe with patches that reflect changes you make
to the source files.
For example, if you know you are going to work on some
code, you could first use the
<link linkend='devtool-modifying-a-recipe'><filename>devtool modify</filename></link>
command to extract the code and set up the workspace.
After which, you could modify, compile, and test the code.
</para>
<para>
When you are satisfied with the results and you have committed
your changes to the Git repository, you can then
run the <filename>devtool update-recipe</filename> to create the
patches and update the recipe:
<literallayout class='monospaced'>
$ devtool update-recipe <replaceable>recipe</replaceable>
</literallayout>
If you run the <filename>devtool update-recipe</filename>
without committing your changes, the command ignores the
changes.
</para>
<para>
Often, you might want to apply customizations made to your
software in your own layer rather than apply them to the
original recipe.
If so, you can use the
<filename>-a</filename> or <filename>--append</filename>
option with the <filename>devtool update-recipe</filename>
command.
These options allow you to specify the layer into which to
write an append file:
<literallayout class='monospaced'>
$ devtool update-recipe <replaceable>recipe</replaceable> -a <replaceable>base-layer-directory</replaceable>
</literallayout>
The <filename>*.bbappend</filename> file is created at the
appropriate path within the specified layer directory, which
may or may not be in your <filename>bblayers.conf</filename>
file.
If an append file already exists, the command updates it
appropriately.
</para>
</section>
<section id='devtool-upgrading-a-recipe'>
<title>Upgrading a Recipe</title>
<para>
Use the <filename>devtool upgrade</filename> command
to upgrade an existing recipe to a new upstream version.
The command puts the upgraded recipe file into the
workspace along with any associated files, and extracts
the source tree to a specified location should patches
need rebased or added to as a result of the upgrade.
</para>
<para>
When you use the <filename>devtool upgrade</filename> command,
you must supply the root name of the recipe (i.e. no version,
paths, or extensions), and you must supply the directory
to which you want the source extracted.
Additional command options let you control things such as
the version number to which you want to upgrade (i.e. the
<ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>),
the source revision to which you want to upgrade (i.e. the
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>,
whether or not to apply patches, and so forth.
</para>
</section>
<section id='devtool-resetting-a-recipe'>
<title>Resetting a Recipe</title>
<para>
Use the <filename>devtool reset</filename> command to remove a
recipe and its configuration (e.g. the corresponding
<filename>.bbappend</filename> file) from the workspace layer.
Realize that this command deletes the recipe and the
append file.
The command does not physically move them for you.
Consequently, you must be sure to physically relocate your
updated recipe and the append file outside of the workspace
layer before running the <filename>devtool reset</filename>
command.
</para>
<para>
If the <filename>devtool reset</filename> command detects that
the recipe or the append files have been modified, the
command preserves the modified files in a separate "attic"
subdirectory under the workspace layer.
</para>
<para>
Here is an example that resets the workspace directory that
contains the <filename>mtr</filename> recipe:
<literallayout class='monospaced'>
$ devtool reset mtr
NOTE: Cleaning sysroot for recipe mtr...
NOTE: Leaving source tree /home/scottrif/poky/build/workspace/sources/mtr as-is; if you no
longer need it then please delete it manually
$
</literallayout>
</para>
</section>
<section id='devtool-building-your-recipe'>
<title>Building Your Recipe</title>
<para>
Use the <filename>devtool build</filename> command to cause the
OpenEmbedded build system to build your recipe.
The <filename>devtool build</filename> command is equivalent to
<filename>bitbake -c populate_sysroot</filename>.
</para>
<para>
When you use the <filename>devtool build</filename> command,
you must supply the root name of the recipe (i.e. no version,
paths, or extensions).
You can use either the "-s" or the "--disable-parallel-make"
option to disable parallel makes during the build.
Here is an example:
<literallayout class='monospaced'>
$ devtool build <replaceable>recipe</replaceable>
</literallayout>
</para>
</section>
<section id='devtool-building-your-image'>
<title>Building Your Image</title>
<para>
Use the <filename>devtool build-image</filename> command
to build an image, extending it to include packages from
recipes in the workspace.
Using this command is useful when you want an image that
ready for immediate deployment onto a device for testing.
For proper integration into a final image, you need to
edit your custom image recipe appropriately.
</para>
<para>
When you use the <filename>devtool build-image</filename>
command, you must supply the name of the image.
This command has no command line options:
<literallayout class='monospaced'>
$ devtool build-image <replaceable>image</replaceable>
</literallayout>
</para>
</section>
<section id='devtool-deploying-your-software-on-the-target-machine'>
<title>Deploying Your Software on the Target Machine</title>
<para>
Use the <filename>devtool deploy-target</filename> command to
deploy the recipe's build output to the live target machine:
<literallayout class='monospaced'>
$ devtool deploy-target <replaceable>recipe</replaceable>&nbsp;<replaceable>target</replaceable>
</literallayout>
The <replaceable>target</replaceable> is the address of the
target machine, which must be running an SSH server (i.e.
<filename>user@hostname[:destdir]</filename>).
</para>
<para>
This command deploys all files installed during the
<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
task.
Furthermore, you do not need to have package management enabled
within the target machine.
If you do, the package manager is bypassed.
<note><title>Notes</title>
<para>
The <filename>deploy-target</filename>
functionality is for development only.
You should never use it to update an image that will be
used in production.
</para>
</note>
</para>
</section>
<section id='devtool-removing-your-software-from-the-target-machine'>
<title>Removing Your Software from the Target Machine</title>
<para>
Use the <filename>devtool undeploy-target</filename> command to
remove deployed build output from the target machine.
For the <filename>devtool undeploy-target</filename> command to
work, you must have previously used the
<link linkend='devtool-deploying-your-software-on-the-target-machine'><filename>devtool deploy-target</filename></link>
command.
<literallayout class='monospaced'>
$ devtool undeploy-target <replaceable>recipe</replaceable>&nbsp;<replaceable>target</replaceable>
</literallayout>
The <replaceable>target</replaceable> is the address of the
target machine, which must be running an SSH server (i.e.
<filename>user@hostname</filename>).
</para>
</section>
<section id='devtool-creating-the-workspace'>
<title>Creating the Workspace Layer in an Alternative Location</title>
<para>
Use the <filename>devtool create-workspace</filename> command to
create a new workspace layer in your
<link linkend='build-directory'>Build Directory</link>.
When you create a new workspace layer, it is populated with the
<filename>README</filename> file and the
<filename>conf</filename> directory only.
</para>
<para>
The following example creates a new workspace layer in your
current working and by default names the workspace layer
"workspace":
<literallayout class='monospaced'>
$ devtool create-workspace
</literallayout>
</para>
<para>
You can create a workspace layer anywhere by supplying
a pathname with the command.
The following command creates a new workspace layer named
"new-workspace":
<literallayout class='monospaced'>
$ devtool create-workspace /home/scottrif/new-workspace
</literallayout>
</para>
</section>
<section id='devtool-get-the-status-of-the-recipes-in-your-workspace'>
<title>Get the Status of the Recipes in Your Workspace</title>
<para>
Use the <filename>devtool status</filename> command to
list the recipes currently in your workspace.
Information includes the paths to their respective
external source trees.
</para>
<para>
The <filename>devtool status</filename> command has no
command-line options:
<literallayout class='monospaced'>
devtool status
</literallayout>
Following is sample output after using
<link linkend='devtool-adding-a-new-recipe-to-the-workspace'><filename>devtool add</filename></link>
to create and add the <filename>mtr_0.86.bb</filename> recipe
to the <filename>workspace</filename> directory:
<literallayout class='monospaced'>
$ devtool status
mtr: /home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb)
$
</literallayout>
</para>
</section>
<section id='devtool-search-for-available-target-recipes'>
<title>Search for Available Target Recipes</title>
<para>
Use the <filename>devtool search</filename> command to
search for available target recipes.
The command matches the recipe name, package name,
description, and installed files.
The command displays the recipe name as a result of a
match.
</para>
<para>
When you use the <filename>devtool search</filename> command,
you must supply a <replaceable>keyword</replaceable>.
The command uses the <replaceable>keyword</replaceable> when
searching for a match.
</para>
</section>
</section>
<section id="using-a-quilt-workflow">
<title>Using Quilt in Your 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
source code, test changes, and then preserve the changes in the
form of a patch all using Quilt.
<note><title>Tip</title>
With regard to preserving changes to source files if you
clean a recipe or have <filename>rm_work</filename> enabled,
the workflow described in the
"<link linkend='using-devtool-in-your-workflow'>Using <filename>devtool</filename> in Your Workflow</link>"
section is a safer development flow than than the flow that
uses Quilt.
</note>
</para>
<para>
Follow these general steps:
<orderedlist>
<listitem><para><emphasis>Find the Source Code:</emphasis>
Temporary source code used by the OpenEmbedded build system
is kept in the
<link linkend='build-directory'>Build Directory</link>.
See the
"<link linkend='finding-the-temporary-source-code'>Finding Temporary Source Code</link>"
section to learn how to locate the directory that has the
temporary source code for a particular package.
</para></listitem>
<listitem><para><emphasis>Change Your Working Directory:</emphasis>
You need to be in the directory that has the temporary source code.
That directory is defined by the
<ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
variable.</para></listitem>
<listitem><para><emphasis>Create a New Patch:</emphasis>
Before modifying source code, you need to create a new patch.
To create a new patch file, use <filename>quilt new</filename> as below:
<literallayout class='monospaced'>
$ quilt new my_changes.patch
</literallayout></para></listitem>
<listitem><para><emphasis>Notify Quilt and Add Files:</emphasis>
After creating the patch, you need to notify Quilt about the files
you plan to edit.
You notify Quilt by adding the files to the patch you just created:
<literallayout class='monospaced'>
$ quilt add file1.c file2.c file3.c
</literallayout>
</para></listitem>
<listitem><para><emphasis>Edit the Files:</emphasis>
Make your changes in the source code to the files you added
to the patch.
</para></listitem>
<listitem><para><emphasis>Test Your Changes:</emphasis>
Once you have modified the source code, the easiest way to
your changes is by calling the
<filename>do_compile</filename> task as shown in the
following example:
<literallayout class='monospaced'>
$ bitbake -c compile -f <replaceable>package</replaceable>
</literallayout>
The <filename>-f</filename> or <filename>--force</filename>
option forces the specified task to execute.
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 run the
<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-clean'><filename>do_clean</filename></ulink>
or
<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleanall'><filename>do_cleanall</filename></ulink>
tasks using BitBake (i.e.
<filename>bitbake -c clean <replaceable>package</replaceable></filename>
and
<filename>bitbake -c cleanall <replaceable>package</replaceable></filename>).
Modifications will also disappear if you use the <filename>rm_work</filename>
feature as described in the
"<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
section of the Yocto Project Quick Start.
</note></para></listitem>
<listitem><para><emphasis>Generate the Patch:</emphasis>
Once your changes work as expected, you need to use Quilt to generate the final patch that
contains all your modifications.
<literallayout class='monospaced'>
$ quilt refresh
</literallayout>
At this point, the <filename>my_changes.patch</filename> file has all your edits made
to the <filename>file1.c</filename>, <filename>file2.c</filename>, and
<filename>file3.c</filename> files.</para>
<para>You can find the resulting patch file in the <filename>patches/</filename>
subdirectory of the source (<filename>S</filename>) directory.</para></listitem>
<listitem><para><emphasis>Copy the Patch File:</emphasis>
For simplicity, copy the patch file into a directory named <filename>files</filename>,
which you can create in the same directory that holds the recipe
(<filename>.bb</filename>) file or the
append (<filename>.bbappend</filename>) file.
Placing the patch here guarantees that the OpenEmbedded build system will find
the patch.
Next, add the patch into the
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
of the recipe.
Here is an example:
<literallayout class='monospaced'>
SRC_URI += "file://my_changes.patch"
</literallayout></para></listitem>
</orderedlist>
</para>
</section>
<section id='finding-the-temporary-source-code'>
<title>Finding Temporary Source Code</title>
<para>
You might find it helpful during development to modify the
temporary source code used by recipes to build packages.
For example, suppose you are developing a patch and you need to
experiment a bit to figure out your solution.
After you have initially built the package, you can iteratively
tweak the source code, which is located in the
<link linkend='build-directory'>Build Directory</link>, and then
you can force a re-compile and quickly test your altered code.
Once you settle on a solution, you can then preserve your changes
in the form of patches.
If you are using Quilt for development, see the
"<link linkend='using-a-quilt-workflow'>Using Quilt in Your Workflow</link>"
section for more information.
</para>
<para>
During a build, the unpacked temporary source code used by recipes
to build packages is available in the Build Directory as
defined by the
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> variable.
Below is the default value for the <filename>S</filename> variable as defined in the
<filename>meta/conf/bitbake.conf</filename> configuration file in the
<link linkend='source-directory'>Source Directory</link>:
<literallayout class='monospaced'>
S = "${WORKDIR}/${BP}"
</literallayout>
You should be aware that many recipes override the <filename>S</filename> variable.
For example, recipes that fetch their source from Git usually set
<filename>S</filename> to <filename>${WORKDIR}/git</filename>.
<note>
The
<ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink>
represents the base recipe name, which consists of the name and version:
<literallayout class='monospaced'>
BP = "${BPN}-${PV}"
</literallayout>
</note>
</para>
<para>
The path to the work directory for the recipe
(<ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>)
is defined as follows:
<literallayout class='monospaced'>
${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
</literallayout>
The actual directory depends on several things:
<itemizedlist>
<listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>:
The top-level build output directory</listitem>
<listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></ulink>:
The target system identifier</listitem>
<listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>:
The recipe name</listitem>
<listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTENDPE'><filename>EXTENDPE</filename></ulink>:
The epoch - (if
<ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>
is not specified, which is usually the case for most
recipes, then <filename>EXTENDPE</filename> is blank)</listitem>
<listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:
The recipe version</listitem>
<listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>:
The recipe revision</listitem>
</itemizedlist>
</para>
<para>
As an example, assume a Source Directory top-level folder
named <filename>poky</filename>, a default Build Directory at
<filename>poky/build</filename>, and a
<filename>qemux86-poky-linux</filename> machine target
system.
Furthermore, suppose your recipe is named
<filename>foo_1.3.0.bb</filename>.
In this case, the work directory the build system uses to
build the package would be as follows:
<literallayout class='monospaced'>
poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
</literallayout>
</para>
<para>
Now that you know where to locate the directory that has the
temporary source code, you can use a Quilt as described in section
"<link linkend='using-a-quilt-workflow'>Using Quilt in Your Workflow</link>"
to make your edits, test the changes, and preserve the changes in
the form of patches.
</para>
</section>
</section>
<section id='image-development-using-toaster'>
<title>Image Development Using Toaster</title>
<para>
Toaster is a web interface to the Yocto Project's OpenEmbedded build
system.
You can initiate builds using Toaster as well as examine the results
and statistics of builds.
See the
<ulink url='&YOCTO_DOCS_TOAST_URL;#toaster-manual-intro'>Toaster User Manual</ulink>
for information on how to set up and use Toaster to build images.
</para>
</section>
<section id="platdev-appdev-devshell">
<title>Using a Development Shell</title>
<para>
When debugging certain commands or even when just editing packages,
<filename>devshell</filename> can be a useful tool.
When you invoke <filename>devshell</filename>, all tasks up to and
including
<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
are run for the specified target.
Then, a new terminal is opened and you are placed in
<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>,
the source directory.
In the new terminal, all the OpenEmbedded build-related environment variables are
still defined so you can use commands such as <filename>configure</filename> and
<filename>make</filename>.
The commands execute just as if the OpenEmbedded build system were executing them.
Consequently, working this way can be helpful when debugging a build or preparing
software to be used with the OpenEmbedded build system.
</para>
<para>
Following is an example that uses <filename>devshell</filename> on a target named
<filename>matchbox-desktop</filename>:
<literallayout class='monospaced'>
$ bitbake matchbox-desktop -c devshell
</literallayout>
</para>
<para>
This command spawns a terminal with a shell prompt within the OpenEmbedded build environment.
The <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_TERMINAL'><filename>OE_TERMINAL</filename></ulink>
variable controls what type of shell is opened.
</para>
<para>
For spawned terminals, the following occurs:
<itemizedlist>
<listitem><para>The <filename>PATH</filename> variable includes the
cross-toolchain.</para></listitem>
<listitem><para>The <filename>pkgconfig</filename> variables find the correct
<filename>.pc</filename> files.</para></listitem>
<listitem><para>The <filename>configure</filename> command finds the
Yocto Project site files as well as any other necessary files.</para></listitem>
</itemizedlist>
</para>
<para>
Within this environment, you can run configure or compile
commands as if they were being run by
the OpenEmbedded build system itself.
As noted earlier, the working directory also automatically changes to the
Source Directory (<ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>).
</para>
<para>
To manually run a specific task using <filename>devshell</filename>,
run the corresponding <filename>run.*</filename> script in
the
<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/temp</filename>
directory (e.g.,
<filename>run.do_configure.</filename><replaceable>pid</replaceable>).
If a task's script does not exist, which would be the case if the task was
skipped by way of the sstate cache, you can create the task by first running
it outside of the <filename>devshell</filename>:
<literallayout class='monospaced'>
$ bitbake -c <replaceable>task</replaceable>
</literallayout>
<note><title>Notes</title>
<itemizedlist>
<listitem><para>Execution of a task's <filename>run.*</filename>
script and BitBake's execution of a task are identical.
In other words, running the script re-runs the task
just as it would be run using the
<filename>bitbake -c</filename> command.
</para></listitem>
<listitem><para>Any <filename>run.*</filename> file that does not
have a <filename>.pid</filename> extension is a
symbolic link (symlink) to the most recent version of that
file.
</para></listitem>
</itemizedlist>
</note>
</para>
<para>
Remember, that the <filename>devshell</filename> is a mechanism that allows
you to get into the BitBake task execution environment.
And as such, all commands must be called just as BitBake would call them.
That means you need to provide the appropriate options for
cross-compilation and so forth as applicable.
</para>
<para>
When you are finished using <filename>devshell</filename>, exit the shell
or close the terminal window.
</para>
<note><title>Notes</title>
<itemizedlist>
<listitem><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></listitem>
<listitem><para>
It is also worth noting that <filename>devshell</filename> still works over
X11 forwarding and similar situations.
</para></listitem>
</itemizedlist>
</note>
</section>
</chapter>