aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2016-03-21 18:09:13 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2016-03-23 21:56:09 +0000
commit6db8cbcbadd0019fa5d879c6cc727a2819341b07 (patch)
tree0d29a338170a463945b95033d49becfa5907ae16
parent922eaeb963f6e3518a18fc8e7ad4cf53264e59e0 (diff)
downloadopenembedded-core-contrib-6db8cbcbadd0019fa5d879c6cc727a2819341b07.tar.gz
sdk-manual: Applied review edits to the manual.
(From yocto-docs rev: be853fb74b28bcf1b27b3b7a8e83012928d4e53a) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/sdk-manual/sdk-appendix-customizing.xml48
-rw-r--r--documentation/sdk-manual/sdk-appendix-obtain.xml8
-rw-r--r--documentation/sdk-manual/sdk-extensible.xml891
-rw-r--r--documentation/sdk-manual/sdk-intro.xml4
-rw-r--r--documentation/sdk-manual/sdk-using.xml22
5 files changed, 498 insertions, 475 deletions
diff --git a/documentation/sdk-manual/sdk-appendix-customizing.xml b/documentation/sdk-manual/sdk-appendix-customizing.xml
index 3ee0d7c90a..7a438725b6 100644
--- a/documentation/sdk-manual/sdk-appendix-customizing.xml
+++ b/documentation/sdk-manual/sdk-appendix-customizing.xml
@@ -17,11 +17,11 @@
<para>
The extensible SDK primarily consists of a pre-configured copy of
- the build system from which it was produced.
+ the OpenEmbedded build system from which it was produced.
Thus, the SDK's configuration is derived using that build system.
- However, filters exist that are applied such as the following that
- are applied to <filename>local.conf</filename> and
- <filename>auto.conf</filename> when present:
+ However, filters such as the following exist that the OpenEmbedded
+ build system applies to <filename>local.conf</filename> and
+ <filename>auto.conf</filename> when these files are present:
<itemizedlist>
<listitem><para>
Variables whose values start with "/" are excluded since the
@@ -44,8 +44,9 @@
Variables listed in
<ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_WHITELIST'><filename>SDK_LOCAL_CONF_WHITELIST</filename></ulink>
are included.
- Including these variables overrides either of the above two
- conditions.
+ Including a variable in the value of
+ <filename>SDK_LOCAL_CONF_WHITELIST</filename> overrides either
+ of the above two conditions.
The default value is blank.
</para></listitem>
<listitem><para>
@@ -68,9 +69,9 @@
when present, are appended to the end of
<filename>conf/local.conf</filename> within the produced SDK, without
any filtering.
- Not filtering these contents is particularly useful if you want to
- set a variable value just for the SDK and not the build system used to
- create the SDK.
+ The <filename>sdk-extra.conf</filename> file is particularly useful
+ if you want to set a variable value just for the SDK and not the
+ OpenEmbedded build system used to create the SDK.
</para>
</section>
@@ -141,14 +142,14 @@
appear in
<ulink url='&YOCTO_DOCS_REF_URL;#var-COREBASE'><filename>COREBASE</filename></ulink>
(other than layers that are enabled through
- <filename>bblayers.conf</filename>), then must list these
+ <filename>bblayers.conf</filename>), then you must list these
files in
<ulink url='&YOCTO_DOCS_REF_URL;#var-COREBASE_FILES'><filename>COREBASE_FILES</filename></ulink>
so that the files are copied into the SDK.
</para></listitem>
<listitem><para>
- If your build system setup uses a different environment setup
- script other than
+ If your OpenEmbedded build system setup uses a different
+ environment setup script other than
<ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
or
<ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>,
@@ -270,15 +271,16 @@
<itemizedlist>
<listitem><para>
If the mirror value you are setting is appropriate to
- be set for both the build system that is actually
- building the SDK and the SDK itself (i.e. the mirror
- is accessible in both places or it will fail quickly
- on the build system side, and its contents will not
- interfere with the build), then you can set the
- variable in your <filename>local.conf</filename>
- or custom distro configuration file.
- You can "whitelist" the variable through the SDK by
- adding the following:
+ be set for both the OpenEmbedded build system that is
+ actually building the SDK and the SDK itself (i.e. the
+ mirror is accessible in both places or it will fail
+ quickly on the OpenEmbedded build system side, and its
+ contents will not interfere with the build), then you
+ can set the variable in your
+ <filename>local.conf</filename> or custom distro
+ configuration file.
+ You can then "whitelist" the variable through
+ to the SDK by adding the following:
<literallayout class='monospaced'>
SDK_LOCAL_CONF_WHITELIST = "SSTATE_MIRRORS"
</literallayout>
@@ -324,8 +326,8 @@
<ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink>
to "minimal" produces an SDK installer that is around 35 Mbytes in
size, which downloads and installs quickly.
- You need to realize, though, that the installer does not install any
- libraries or tools out of the box.
+ You need to realize, though, that the minimal installer does not
+ install any libraries or tools out of the box.
These must be installed either "on the fly" or through actions you
perform using <filename>devtool</filename> or explicitly with the
<filename>devtool sdk-install</filename> command.
diff --git a/documentation/sdk-manual/sdk-appendix-obtain.xml b/documentation/sdk-manual/sdk-appendix-obtain.xml
index daa5e79fe8..3d4e364bf6 100644
--- a/documentation/sdk-manual/sdk-appendix-obtain.xml
+++ b/documentation/sdk-manual/sdk-appendix-obtain.xml
@@ -222,15 +222,15 @@
different than the installed structure for the standard SDK.
The extensible SDK does not separate host and target parts in the
same manner as does the standard SDK.
- The extensible SDK uses an embedded copy of the build system, which
- has its own sysroots.
+ The extensible SDK uses an embedded copy of the OpenEmbedded
+ build system, which has its own sysroots.
</para>
<para>
Of note in the directory structure are an environment setup script
for the SDK, a configuration file for the target, a version file for
- the target, and a log file for the build system preparation script run
- by the installer.
+ the target, and a log file for the OpenEmbedded build system
+ preparation script run by the installer.
</para>
<para>
diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml
index f9f04072d7..58d2aec977 100644
--- a/documentation/sdk-manual/sdk-extensible.xml
+++ b/documentation/sdk-manual/sdk-extensible.xml
@@ -10,8 +10,8 @@
This chapter describes the extensible SDK and how to use it.
The extensible SDK makes it easy to add new applications and libraries
to an image, modify the source for an existing component, test
- changes on the target hardware, and ease integration into the rest
- of the build system.
+ changes on the target hardware, and ease integration into the rest of the
+ <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>.
</para>
<para>
@@ -45,12 +45,17 @@
<filename>poky_sdk</filename> folder of your home directory.
As with the standard SDK, you can choose to install the
extensible SDK in any location when you run the installer.
+ However, unlike the standard SDK, the location you choose needs
+ to be writable for whichever users need to use the SDK,
+ since files will need to be written under that directory during
+ the normal course of operation.
</para></listitem>
<listitem><para><emphasis>Build Tools and Build System:</emphasis>
The extensible SDK installer performs additional tasks as
compared to the standard SDK installer.
The extensible SDK installer extracts build tools specific
- to the SDK and the installer also prepares the build system.
+ to the SDK and the installer also prepares the OpenEmbedded
+ build system.
Here is example output for running the extensible SDK
installer:
<literallayout class='monospaced'>
@@ -86,458 +91,478 @@
</para>
</section>
-<section id='sdk-use-devtool-to-add-an-application'>
- <title>Use <filename>devtool add</filename> to Add an Application</title>
+<section id='using-devtool-in-your-sdk-workflow'>
+ <title>Using <filename>devtool</filename> in Your SDK Workflow</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.
+ <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>
- 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:
+ These 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>
+ </itemizedlist>
</para>
<para>
- <imagedata fileref="figures/sdk-devtool-add-flow.png" align="center" />
+ The remainder of this section presents these workflows.
</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'>
+ <section id='sdk-use-devtool-to-add-an-application'>
+ <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/sdk-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'>
+ </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'>
+ </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'>
+ </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'>
+ </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'>
+ </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'>
+ </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'>
+ </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'>
+ </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='sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component'>
- <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/sdk-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'>
+ </literallayout>
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component'>
+ <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/sdk-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'>
+ </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'>
+ </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'>
+ </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 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'>
+ </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'>
+ </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>
+ </literallayout>
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
</section>
<section id='sdk-installing-additional-items-into-the-extensible-sdk'>
@@ -574,7 +599,7 @@
It is important to remember that building the item from source takes
significantly longer than installing the pre-built artifact.
Also, if no recipe exists for the item you want to add to the SDK, you
- must add it using the <filename>devtool add</filename> command.
+ must instead add it using the <filename>devtool add</filename> command.
</para>
</section>
@@ -635,8 +660,8 @@
constructs a new SDK installer containing those recipes and the
resulting binary artifacts.
The recipes go into their own separate layer in the constructed
- derivative SDK, leaving the workspace clean and ready for you
- to add your own recipes.
+ derivative SDK, leaving the workspace clean and ready for users
+ to add their own recipes.
</para>
</section>
diff --git a/documentation/sdk-manual/sdk-intro.xml b/documentation/sdk-manual/sdk-intro.xml
index d71aafeba1..ae27562037 100644
--- a/documentation/sdk-manual/sdk-intro.xml
+++ b/documentation/sdk-manual/sdk-intro.xml
@@ -42,7 +42,7 @@
tools that allow you to easily add new applications and libraries to
an image, modify the source of an existing component, test changes on
the target hardware, and easily integrate an application into the
- the Yocto Project build system.
+ <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>.
</para>
<para>
@@ -79,7 +79,7 @@
<itemizedlist>
<listitem><para>An architecture-specific cross-toolchain and
matching sysroots (target and native) all built by the
- <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>.
+ OpenEmbedded build system.
The toolchain and sysroots are based on a
<ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
configuration and extensions,
diff --git a/documentation/sdk-manual/sdk-using.xml b/documentation/sdk-manual/sdk-using.xml
index c752656ce4..10089ca3ae 100644
--- a/documentation/sdk-manual/sdk-using.xml
+++ b/documentation/sdk-manual/sdk-using.xml
@@ -24,18 +24,10 @@
<title>Why use the Standard SDK and What is in It?</title>
<para>
- Fundamentally, the standard SDK exists so that you can access
- cross-development tools.
- This paragraph describes why you use the Standard SDK.
- Probably need to compare that against why you would not be interested
- in the extensible SDK here as well.
- According to Paul, the most interest lies in the extensible SDK.
- So providing this comparison would be helpful.
- Currently, my understanding boils down to this: The only reason to use
- the Standard SDK is if you want to build and debug source code that
- you have.
- That pretty much sums it up.
- If there is more detail, I need to know about it.
+ The Standard SDK provides a cross-development toolchain and libraries
+ tailored to the contents of a specific image.
+ You would use the Standard SDK if you want a more traditional toolchain
+ experience.
</para>
<para>
@@ -125,6 +117,10 @@
<note>
You must change the permissions on the toolchain
installer script so that it is executable.
+ Here is an example:
+ <literallayout class='monospaced'>
+ $ chmod +x poky-glibc-x86_64-core-image-sato-i586-toolchain-2.1.sh
+ </literallayout>
</note>
</para>
@@ -440,7 +436,7 @@
</section>
<section id='sdk-developing-applications-using-eclipse'>
- <title>Devloping Applications Using <trademark class='trade'>Eclipse</trademark></title>
+ <title>Developing Applications Using <trademark class='trade'>Eclipse</trademark></title>
<para>
If you are familiar with the popular Eclipse IDE, you can use an