mirror of
https://git.yoctoproject.org/poky
synced 2026-01-29 21:08:42 +01:00
documentation: Moved devtool workflow to sdk manual
Fixes [YOCTO #11630] The section on the devtool workflow in the dev-manual was 99% identical to what was in the sdk-manual. I have moved the workflow procedure from the old "Model" chapter of the dev-manual to be merged with what was in the sdk-manual. In truth, the only things added were a note about devtool not being exclusive to SDK development. The result of moving (deleting) this section was that the "model" chapter of the dev-manual went away. The devtool stuff, Quilt, devshell, and python shell are all out now and there is no chapter left. So, mega-manual had to be adjusted to not pull that chapter in when building the dev-manual. I had to delete three figures that were used in the flow. The figures were already replicated in the sdk-manual. The figures were deleted from the figures folder of both the dev-manual and the mega-manual. I had to make sure all references to the old devtool stuf in the YP doc set were adjusted. (From yocto-docs rev: 5dbd643d31ab502df53a22229e457a03da7772b7) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
committed by
Richard Purdie
Richard Purdie
parent
b15a65b8ea
commit
293b53674c
@@ -131,8 +131,6 @@ TARFILES = dev-style.css dev-manual.html \
|
||||
TARFILES = dev-style.css dev-manual.html \
|
||||
figures/dev-title.png \
|
||||
figures/recipe-workflow.png \
|
||||
figures/devtool-add-flow.png figures/devtool-modify-flow.png \
|
||||
figures/devtool-upgrade-flow.png \
|
||||
eclipse
|
||||
endif
|
||||
|
||||
@@ -241,8 +239,7 @@ TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png \
|
||||
figures/sdk-generation.png figures/recipe-workflow.png \
|
||||
figures/build-workspace-directory.png figures/mega-title.png \
|
||||
figures/toaster-title.png figures/hosted-service.png \
|
||||
figures/simple-configuration.png figures/devtool-add-flow.png \
|
||||
figures/devtool-modify-flow.png figures/devtool-upgrade-flow.png \
|
||||
figures/simple-configuration.png \
|
||||
figures/compatible-layers.png figures/import-layer.png figures/new-project.png \
|
||||
figures/sdk-environment.png figures/sdk-installed-standard-sdk-directory.png \
|
||||
figures/sdk-devtool-add-flow.png figures/sdk-installed-extensible-sdk-directory.png \
|
||||
|
||||
@@ -1516,8 +1516,9 @@
|
||||
<para>
|
||||
You can find a complete description of the
|
||||
<filename>devtool add</filename> command in the
|
||||
"<link linkend='use-devtool-to-integrate-new-code'>Use <filename>devtool add</filename> to Add an Application</link>"
|
||||
section.
|
||||
"<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-a-closer-look-at-devtool-add'>A Closer Look at <filename>devtool</filename> add</ulink>"
|
||||
section in the Yocto Project Software Development Kit
|
||||
(SDK) Developer's Guide.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
@@ -4081,10 +4082,11 @@
|
||||
<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 the flow that
|
||||
uses Quilt.
|
||||
the
|
||||
<ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename> workflow</ulink>
|
||||
as described in the Yocto Project Software Development Kit
|
||||
(SDK) Developer's Guide is a safer development flow than the
|
||||
flow that uses Quilt.
|
||||
</note>
|
||||
</para>
|
||||
|
||||
@@ -6966,7 +6968,8 @@
|
||||
|
||||
<para>
|
||||
Two methods exist by which you can create the patch:
|
||||
<link linkend='using-devtool-in-your-workflow'><filename>devtool</filename></link> and
|
||||
<ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename></ulink>
|
||||
and
|
||||
<link linkend='using-a-quilt-workflow'>Quilt</link>.
|
||||
For kernel patches, the Git workflow is more appropriate.
|
||||
This section assumes the Git workflow and shows the steps specific to
|
||||
|
||||
@@ -1,721 +0,0 @@
|
||||
<!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>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>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="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.
|
||||
See the
|
||||
"<ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename> Quick Reference</ulink>"
|
||||
in the Yocto Project Reference Manual for a
|
||||
<filename>devtool</filename> quick reference.
|
||||
</para>
|
||||
|
||||
<section id='use-devtool-to-integrate-new-code'>
|
||||
<title>Use <filename>devtool add</filename> to Add an Application</title>
|
||||
|
||||
<para>
|
||||
The <filename>devtool add</filename> command generates
|
||||
a new recipe based on existing source code.
|
||||
This command takes advantage of the
|
||||
<ulink url='&YOCTO_DOCS_DEV_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>
|
||||
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.
|
||||
If required, <filename>devtool</filename>
|
||||
always 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>:
|
||||
<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>Finish Your Work With the Recipe</emphasis>:
|
||||
The <filename>devtool finish</filename> command creates
|
||||
any patches corresponding to commits in the local
|
||||
Git repository, moves the new recipe to a more permanent
|
||||
layer, and then resets the recipe so that the recipe is
|
||||
built normally rather than from the workspace.
|
||||
<literallayout class='monospaced'>
|
||||
$ devtool finish <replaceable>recipe layer</replaceable>
|
||||
</literallayout>
|
||||
<note>
|
||||
Any changes you want to turn into patches must be
|
||||
committed to the Git repository in the source tree.
|
||||
</note></para>
|
||||
|
||||
<para>As mentioned, the <filename>devtool finish</filename>
|
||||
command moves the final recipe to its permanent layer.
|
||||
</para>
|
||||
|
||||
<para>As a final process of the
|
||||
<filename>devtool finish</filename> command, the state
|
||||
of the standard layers and the upstream source is
|
||||
restored so that you can build the recipe from those
|
||||
areas rather than the workspace.
|
||||
<note>
|
||||
You can use the <filename>devtool reset</filename>
|
||||
command to put things back should you decide you
|
||||
do not want to proceed with your work.
|
||||
If you do use this command, realize that the source
|
||||
tree is preserved.
|
||||
</note>
|
||||
</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 Modify the Source of an Existing Component</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
|
||||
to 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.
|
||||
</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>Finish Your Work With the Recipe</emphasis>:
|
||||
The <filename>devtool finish</filename> command creates
|
||||
any patches corresponding to commits in the local
|
||||
Git repository, updates the recipe to point to them
|
||||
(or creates a <filename>.bbappend</filename> file to do
|
||||
so, depending on the specified destination layer), and
|
||||
then resets the recipe so that the recipe is built normally
|
||||
rather than from the workspace.
|
||||
<literallayout class='monospaced'>
|
||||
$ devtool finish <replaceable>recipe layer</replaceable>
|
||||
</literallayout>
|
||||
<note>
|
||||
Any changes you want to turn into patches must be
|
||||
committed to the Git repository in the source tree.
|
||||
</note></para>
|
||||
|
||||
<para>Because there is no need to move the recipe,
|
||||
<filename>devtool finish</filename> either updates the
|
||||
original recipe in the original layer or the command
|
||||
creates a <filename>.bbappend</filename> in a different
|
||||
layer as provided by <replaceable>layer</replaceable>.
|
||||
</para>
|
||||
|
||||
<para>As a final process of the
|
||||
<filename>devtool finish</filename> command, the state
|
||||
of the standard layers and the upstream source is
|
||||
restored so that you can build the recipe from those
|
||||
areas rather than the workspace.
|
||||
<note>
|
||||
You can use the <filename>devtool reset</filename>
|
||||
command to put things back should you decide you
|
||||
do not want to proceed with your work.
|
||||
If you do use this command, realize that the source
|
||||
tree is preserved.
|
||||
</note>
|
||||
</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>
|
||||
The following diagram shows the common development flow
|
||||
you would use with the <filename>devtool upgrade</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>Finish Your Work With the Recipe</emphasis>:
|
||||
The <filename>devtool finish</filename> command creates
|
||||
any patches corresponding to commits in the local
|
||||
Git repository, moves the new recipe to a more permanent
|
||||
layer, and then resets the recipe so that the recipe is
|
||||
built normally rather than from the workspace.
|
||||
If you specify a destination layer that is the same as
|
||||
the original source, then the old version of the
|
||||
recipe and associated files will be removed prior to
|
||||
adding the new version.
|
||||
<literallayout class='monospaced'>
|
||||
$ devtool finish <replaceable>recipe layer</replaceable>
|
||||
</literallayout>
|
||||
<note>
|
||||
Any changes you want to turn into patches must be
|
||||
committed to the Git repository in the source tree.
|
||||
</note></para>
|
||||
<para>As a final process of the
|
||||
<filename>devtool finish</filename> command, the state
|
||||
of the standard layers and the upstream source is
|
||||
restored so that you can build the recipe from those
|
||||
areas rather than the workspace.
|
||||
<note>
|
||||
You can use the <filename>devtool reset</filename>
|
||||
command to put things back should you decide you
|
||||
do not want to proceed with your work.
|
||||
If you do use this command, realize that the source
|
||||
tree is preserved.
|
||||
</note>
|
||||
</para></listitem>
|
||||
</orderedlist>
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
</chapter>
|
||||
@@ -199,10 +199,10 @@
|
||||
<title>Setting Up to Work on a Kernel</title>
|
||||
|
||||
<para>
|
||||
Kernel development is best accomplished using the
|
||||
<filename>devtool</filename> tool and not through traditional
|
||||
kernel workflow methods.
|
||||
This section provides procedures for both.
|
||||
Kernel development is best accomplished using
|
||||
<ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename></ulink>
|
||||
and not through traditional kernel workflow methods.
|
||||
This section provides procedures to set up for both.
|
||||
</para>
|
||||
|
||||
<section id='getting-ready-to-develop-using-devtool'>
|
||||
|
||||
@@ -152,8 +152,6 @@
|
||||
|
||||
<xi:include href="dev-manual-newbie.xml"/>
|
||||
|
||||
<xi:include href="dev-manual-model.xml"/>
|
||||
|
||||
<xi:include href="dev-manual-common-tasks.xml"/>
|
||||
|
||||
<xi:include href="dev-manual-qemu.xml"/>
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 174 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 160 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 136 KiB |
@@ -237,7 +237,7 @@
|
||||
<title>Other Resources</title>
|
||||
|
||||
<para>
|
||||
The sections that follow provide instructions for completing
|
||||
The remainder of this manual provides instructions for completing
|
||||
specific Linux kernel development tasks.
|
||||
These instructions assume you are comfortable working with
|
||||
<ulink url='http://openembedded.org/wiki/Bitbake'>BitBake</ulink>
|
||||
@@ -251,9 +251,9 @@
|
||||
<ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
The
|
||||
"<ulink url='&YOCTO_DOCS_DEV_URL;#dev-modifying-source-code'>Modifying Source Code</ulink>"
|
||||
section in the Yocto Project Development Manual
|
||||
<ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename> workflow</ulink>
|
||||
as described in the Yocto Project Software Development Kit
|
||||
(SDK) Developer's Guide.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
The
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 175 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 149 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 137 KiB |
@@ -130,8 +130,6 @@
|
||||
xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-start.xml"/>
|
||||
<xi:include
|
||||
xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-newbie.xml"/>
|
||||
<xi:include
|
||||
xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-model.xml"/>
|
||||
<xi:include
|
||||
xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-common-tasks.xml"/>
|
||||
<xi:include
|
||||
|
||||
@@ -235,6 +235,13 @@
|
||||
you build, test and package software within the extensible SDK, and
|
||||
optionally integrate it into an image built by the OpenEmbedded
|
||||
build system.
|
||||
<note><title>Tip</title>
|
||||
The use of <filename>devtool</filename> is not limited to
|
||||
the extensible SDK.
|
||||
You can use <filename>devtool</filename> to help you easily
|
||||
develop any project whose build output must be part of an
|
||||
image built using the OpenEmbedded build system.
|
||||
</note>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@@ -244,6 +251,12 @@
|
||||
number of sub-commands for each function.
|
||||
You can run <filename>devtool --help</filename> to see all the
|
||||
commands.
|
||||
<note>
|
||||
See the
|
||||
"<ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename> Quick Reference</ulink>"
|
||||
in the Yocto Project Reference Manual for a
|
||||
<filename>devtool</filename> quick reference.
|
||||
</note>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@@ -1262,7 +1275,7 @@
|
||||
<title>Working With Recipes</title>
|
||||
|
||||
<para>
|
||||
When building a recipe with <filename>devtool build</filename> the
|
||||
When building a recipe with <filename>devtool build</filename>, the
|
||||
typical build progression is as follows:
|
||||
<orderedlist>
|
||||
<listitem><para>
|
||||
|
||||
@@ -945,9 +945,7 @@
|
||||
is a great place to get a feel for how to use the Yocto
|
||||
Project.
|
||||
The manual contains conceptual and procedural information
|
||||
that covers
|
||||
<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-model'>common development models</ulink>
|
||||
and introduces
|
||||
that introduces
|
||||
<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-newbie'>the Yocto Project open source development environment</ulink>.
|
||||
The manual also contains several targeted sections that
|
||||
cover specific
|
||||
|
||||
Reference in New Issue
Block a user