aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2016-09-19 16:45:26 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2016-09-28 15:02:32 +0100
commitfe8d57543313cd6ef79141ed374ac4f708f4e810 (patch)
treef75ba6bf5c207d2a6260dc6f45f76a4ce7903e6d
parented6a5495a19b7f2bc0f9ae35027b27f2bb973576 (diff)
downloadopenembedded-core-contrib-fe8d57543313cd6ef79141ed374ac4f708f4e810.tar.gz
sdk-manual: New Projet chapter added and other fixes
I extracted the sections on Makefile, Autotools, and Eclipse into their own new chapter. Seemed to make sense as they are projet types for both standard and extensible SDK types. Also, swapped the order of appearance from standard first to extensible first. This swapping caused a bit of rewriting. (From yocto-docs rev: 138a4d5576123da800a8fd8d99462a138ceeb743) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/sdk-manual/sdk-extensible.xml2866
-rw-r--r--documentation/sdk-manual/sdk-intro.xml124
-rw-r--r--documentation/sdk-manual/sdk-manual.xml4
-rw-r--r--documentation/sdk-manual/sdk-using.xml1563
-rw-r--r--documentation/sdk-manual/sdk-working-projects.xml1461
5 files changed, 3198 insertions, 2820 deletions
diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml
index 73b317f5c8..8c568a739e 100644
--- a/documentation/sdk-manual/sdk-extensible.xml
+++ b/documentation/sdk-manual/sdk-extensible.xml
@@ -4,1516 +4,1628 @@
<chapter id='sdk-extensible'>
-<title>Using the Extensible SDK</title>
-
-<para>
- 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
- <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>.
-</para>
-
-<para>
- Information in this chapter covers features that are not part of the
- standard SDK.
- In other words, the chapter presents information unique to the
- extensible SDK only.
- For information on how to use the standard SDK, see the
- "<link linkend='sdk-using-the-standard-sdk'>Using the Standard SDK</link>"
- chapter.
-</para>
-
-<section id='sdk-setting-up-to-use-the-extensible-sdk'>
- <title>Setting Up to Use the Extensible SDK</title>
+ <title>Using the Extensible SDK</title>
<para>
- Getting set up to use the extensible SDK is identical to getting set
- up to use the standard SDK.
- You still need to locate and run the installer and then run the
- environment setup script.
- See the
- "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
- and the
- "<link linkend='sdk-running-the-sdk-environment-setup-script'>Running the SDK Environment Setup Script</link>"
- sections for general information.
- The following items highlight the only differences between getting
- set up to use the extensible SDK as compared to the standard SDK:
- <itemizedlist>
- <listitem><para><emphasis>Default Installation Directory:</emphasis>
- By default, the extensible SDK installs into the
- <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.
- to the SDK and the installer also prepares the internal build
- system within the SDK.
- You can find pre-built extensible SDK installers in the same
- <ulink url='http://downloads.yoctoproject.org/releases/yocto/yocto-&DISTRO;/toolchain/'>toolchain</ulink>
- location as the pre-built standard SDK installers.
- For extensible SDK installers, the
- <filename>ext</filename> string is part of the name.
- Here is an example:
- <literallayout class='monospaced'>
- poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
- </literallayout>
- <note>
- As an alternative to downloading an SDK, you can build the toolchain
- installer.
- For information on building the installer, see the
- "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
- section.
- Another helpful resource for building an installer is the
- <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
- wiki page.
- </note>
- Here is example output for running the extensible SDK
- installer:
- <literallayout class='monospaced'>
- $ ./poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-&DISTRO;.sh
- Poky (Yocto Project Reference Distro) Extensible SDK installer version &DISTRO;
- ===================================================================================
- Enter target directory for SDK (default: ~/poky_sdk):
- You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed[Y/n]? Y
- Extracting SDK......................................................................done
- Setting it up...
- Extracting buildtools...
- Preparing build system...
- done
- SDK has been successfully set up and is ready to be used.
- Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
- $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux
- </literallayout>
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- After installing the SDK, you need to run the SDK environment setup
- script.
- Here is the output from an example run:
- <literallayout class='monospaced'>
- $ cd /home/scottrif/poky_sdk
- $ source environment-setup-core2-64-poky-linux
- SDK environment now set up; additionally you may now run devtool to perform development tasks.
- Run devtool --help for further details.
- </literallayout>
- Once you run the environment setup script, you have
- <filename>devtool</filename> available.
- </para>
-</section>
-
-<section id='using-devtool-in-your-sdk-workflow'>
- <title>Using <filename>devtool</filename> in Your SDK Workflow</title>
-
- <para>
- The cornerstone of the extensible SDK is a command-line tool
- called <filename>devtool</filename>.
- This tool provides a number of features that help
- you build, test and package software within the extensible SDK, and
- optionally integrate it into an image built by the OpenEmbedded build
- system.
- </para>
-
- <para>
- The <filename>devtool</filename> command line is organized similarly
- to
- <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> in that it has a
- number of sub-commands for each function.
- You can run <filename>devtool --help</filename> to see all the
- commands.
+ This chapter describes the extensible SDK and how to install it.
+ Information covers the pieces of the SDK, how to install it, and
+ presents a look at using the <filename>devtool</filename>
+ functionality.
+ 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
+ <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>.
<note>
- See the
- "<ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename>&nbsp;Quick Reference</ulink>"
- in the Yocto Project Reference Manual for more a
- <filename>devtool</filename> reference.
+ For a side-by-side comparison of main features supported for an
+ extensible SDK as compared to a standard SDK, see the
+ "<link linkend='sdk-manual-intro'>Introduction</link>"
+ section.
</note>
</para>
<para>
- Two <filename>devtool</filename> subcommands that provide
- entry-points into development are:
- <itemizedlist>
- <listitem><para><emphasis><filename>devtool add</filename></emphasis>:
- Assists in adding new software to be built.
- </para></listitem>
- <listitem><para><emphasis><filename>devtool modify</filename></emphasis>:
- Sets up an environment to enable you to modify the source of
- an existing component.
- </para></listitem>
- </itemizedlist>
- As with the OpenEmbedded build system, "recipes" represent software
- packages within <filename>devtool</filename>.
- When you use <filename>devtool add</filename>, a recipe is
- automatically created.
- When you use <filename>devtool modify</filename>, the specified
- existing recipe is used in order to determine where to get the source
- code and how to patch it.
- In both cases, an environment is set up so that when you build the
- recipe a source tree that is under your control is used in order to
- allow you to make changes to the source as desired.
- By default, both new recipes and the source go into a "workspace"
- directory under the SDK.
- </para>
-
- <para>
- The remainder of this section presents the
- <filename>devtool add</filename> and
- <filename>devtool modify</filename> workflows.
+ You can use an extensible SDK to work on Makefile, Autotools, and
+ Eclipse-based projects.
+ See the
+ "<link linkend='sdk-working-projects'>Working with Different Types of Projects</link>"
+ chapter for more information.
</para>
- <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>
+ <section id='sdk-extensible-sdk-intro'>
+ <title>Why use the Extensible SDK and What is in It?</title>
<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:
+ The extensible SDK provides a cross-development toolchain and
+ libraries tailored to the contents of a specific image.
+ You would use the Extensible SDK if you want a toolchain experience
+ supplemented with the powerful set of <filename>devtool</filename>
+ commands tailored for the Yocto Project environment.
</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.
- 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>
+ The installed extensible SDK consists of several files and
+ directories.
+ Basically, it contains an SDK environment setup script, some
+ configuration files, an internal build system, and the
+ <filename>devtool</filename> functionality.
</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>
+ <section id='sdk-setting-up-to-use-the-extensible-sdk'>
+ <title>Setting Up to Use the Extensible SDK</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.
+ The first thing you need to do is install the SDK on your host
+ development machine by running the <filename>*.sh</filename>
+ installation script.
</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:
+ You can download a tarball installer, which includes the
+ pre-built toolchain, the <filename>runqemu</filename>
+ script, the internal build system, <filename>devtool</filename>,
+ and support files from the appropriate directory under
+ <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>.
+ Toolchains are available for 32-bit and 64-bit x86 development
+ systems from the <filename>i686</filename> and
+ <filename>x86_64</filename> directories, respectively.
+ The toolchains the Yocto Project provides are based off the
+ <filename>core-image-sato</filename> image and contain
+ libraries appropriate for developing against that image.
+ Each type of development system supports five or more target
+ architectures.
</para>
<para>
- <imagedata fileref="figures/sdk-devtool-modify-flow.png" align="center" />
- </para>
+ The names of the tarball installer scripts are such that a
+ string representing the host system appears first in the
+ filename and then is immediately followed by a string
+ representing the target architecture.
+ An extensible SDK has the string "-ext" as part of the name.
+ <literallayout class='monospaced'>
+ poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-ext-<replaceable>release_version</replaceable>.sh
- <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>
+ Where:
+ <replaceable>host_system</replaceable> is a string representing your development system:
- <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>
+ i686 or x86_64.
- <section id='sdk-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>
+ <replaceable>image_type</replaceable> is the image for which the SDK was built.
- <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>
+ <replaceable>arch</replaceable> is a string representing the tuned target architecture:
- <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:
+ i586, x86_64, powerpc, mips, armv7a or armv5te
+
+ <replaceable>release_version</replaceable> is a string representing the release number of the
+ Yocto Project:
+
+ &DISTRO;, &DISTRO;+snapshot
+ </literallayout>
+ For example, the following toolchain installer is for a 64-bit
+ development host system and a i586-tuned target architecture
+ based off the SDK for <filename>core-image-sato</filename> and
+ using the current &DISTRO; snapshot:
+ <literallayout class='monospaced'>
+ poky-glibc-x86_64-core-image-sato-i586-toolchain-ext-&DISTRO;.sh
+ </literallayout>
+ <note>
+ As an alternative to downloading an SDK, you can build the
+ toolchain installer.
+ For information on building the installer, see the
+ "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
+ section.
+ Another helpful resource for building an installer is the
+ <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
+ wiki page.
+ This wiki page focuses on development when using the Eclipse
+ IDE.
+ </note>
</para>
<para>
- <imagedata fileref="figures/sdk-devtool-upgrade-flow.png" align="center" />
+ The SDK and toolchains are self-contained and by default are
+ installed into the <filename>poky_sdk</filename> folder in your
+ home directory.
+ You can choose to install the extensible SDK in any location when
+ you run the installer.
+ However, 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>
<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, 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>
+ The following command shows how to run the installer given a
+ toolchain tarball for a 64-bit x86 development host system and
+ a 64-bit x86 target architecture.
+ The example assumes the toolchain installer is located in
+ <filename>~/Downloads/</filename>.
+ <note>
+ If you do not have write permissions for the directory
+ into which you are installing the SDK, the installer
+ notifies you and exits.
+ Be sure you have write permissions in the directory and
+ run the installer again.
+ </note>
+ <literallayout class='monospaced'>
+ $ ./poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-&DISTRO;.sh
+ Poky (Yocto Project Reference Distro) Extensible SDK installer version &DISTRO;
+ ===================================================================================
+ Enter target directory for SDK (default: ~/poky_sdk):
+ You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed[Y/n]? Y
+ Extracting SDK......................................................................done
+ Setting it up...
+ Extracting buildtools...
+ Preparing build system...
+ done
+ SDK has been successfully set up and is ready to be used.
+ Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
+ $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux
+ </literallayout>
</para>
</section>
-</section>
-
-<section id='sdk-a-closer-look-at-devtool-add'>
- <title>A Closer Look at <filename>devtool add</filename></title>
- <para>
- The <filename>devtool add</filename> command automatically creates a
- recipe based on the source tree with which you provide it.
- Currently, the command has support for the following:
- <itemizedlist>
- <listitem><para>
- Autotools (<filename>autoconf</filename> and
- <filename>automake</filename>)
- </para></listitem>
- <listitem><para>
- CMake
- </para></listitem>
- <listitem><para>
- Scons
- </para></listitem>
- <listitem><para>
- <filename>qmake</filename>
- </para></listitem>
- <listitem><para>
- Plain <filename>Makefile</filename>
- </para></listitem>
- <listitem><para>
- Out-of-tree kernel module
- </para></listitem>
- <listitem><para>
- Binary package (i.e. "-b" option)
- </para></listitem>
- <listitem><para>
- Node.js module
- </para></listitem>
- <listitem><para>
- Python modules that use <filename>setuptools</filename>
- or <filename>distutils</filename>
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- Apart from binary packages, the determination of how a source tree
- should be treated is automatic based on the files present within
- that source tree.
- For example, if a <filename>CMakeLists.txt</filename> file is found,
- then the source tree is assumed to be using
- CMake and is treated accordingly.
- <note>
- In most cases, you need to edit the automatically generated
- recipe in order to make it build properly.
- Typically, you would go through several edit and build cycles
- until you can build the recipe.
- Once the recipe can be built, you could use possible further
- iterations to test the recipe on the target device.
- </note>
- </para>
-
- <para>
- The remainder of this section covers specifics regarding how parts
- of the recipe are generated.
- </para>
-
- <section id='sdk-name-and-version'>
- <title>Name and Version</title>
+ <section id='sdk-running-the-extensible-sdk-environment-setup-script'>
+ <title>Running the Extensible SDK Environment Setup Script</title>
<para>
- If you do not specify a name and version on the command
- line, <filename>devtool add</filename> attempts to determine
- the name and version of the software being built from
- various metadata within the source tree.
- Furthermore, the command sets the name of the created recipe
- file accordingly.
- If the name or version cannot be determined, the
- <filename>devtool add</filename> command prints an error and
- you must re-run the command with both the name and version
- or just the name or version specified.
+ Once you have the SDK installed, you must run the SDK environment
+ setup script before you can actually use it.
+ This setup script resides in the directory you chose when you
+ installed the SDK, which is either the default
+ <filename>poky_sdk</filename> directory or the directory you
+ chose during installation.
</para>
<para>
- Sometimes the name or version determined from the source tree
- might be incorrect.
- For such a case, you must reset the recipe:
+ Before running the script, be sure it is the one that matches the
+ architecture for which you are developing.
+ Environment setup scripts begin with the string
+ "<filename>environment-setup</filename>" and include as part of
+ their name the tuned target architecture.
+ As an example, the following commands set the working directory
+ to where the SDK was installed and then source the environment
+ setup script.
+ In this example, the setup script is for an IA-based
+ target machine using i586 tuning:
<literallayout class='monospaced'>
- $ devtool reset -n <replaceable>recipename</replaceable>
+ $ cd /home/scottrif/poky_sdk
+ $ source environment-setup-core2-64-poky-linux
+ SDK environment now set up; additionally you may now run devtool to perform development tasks.
+ Run devtool --help for further details.
+ </literallayout>
+ When you run the setup script, many environment variables are
+ defined:
+ <literallayout class='monospaced'>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKTARGETSYSROOT'><filename>SDKTARGETSYSROOT</filename></ulink> - The path to the sysroot used for cross-compilation
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PKG_CONFIG_PATH'><filename>PKG_CONFIG_PATH</filename></ulink> - The path to the target pkg-config files
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_SITE'><filename>CONFIG_SITE</filename></ulink> - A GNU autoconf site file preconfigured for the target
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> - The minimal command and arguments to run the C compiler
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CXX'><filename>CXX</filename></ulink> - The minimal command and arguments to run the C++ compiler
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CPP'><filename>CPP</filename></ulink> - The minimal command and arguments to run the C preprocessor
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-AS'><filename>AS</filename></ulink> - The minimal command and arguments to run the assembler
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink> - The minimal command and arguments to run the linker
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-GDB'><filename>GDB</filename></ulink> - The minimal command and arguments to run the GNU Debugger
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-STRIP'><filename>STRIP</filename></ulink> - The minimal command and arguments to run 'strip', which strips symbols
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-RANLIB'><filename>RANLIB</filename></ulink> - The minimal command and arguments to run 'ranlib'
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJCOPY'><filename>OBJCOPY</filename></ulink> - The minimal command and arguments to run 'objcopy'
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJDUMP'><filename>OBJDUMP</filename></ulink> - The minimal command and arguments to run 'objdump'
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-AR'><filename>AR</filename></ulink> - The minimal command and arguments to run 'ar'
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-NM'><filename>NM</filename></ulink> - The minimal command and arguments to run 'nm'
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></ulink> - The toolchain binary prefix for the target tools
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CROSS_COMPILE'><filename>CROSS_COMPILE</filename></ulink> - The toolchain binary prefix for the target tools
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink> - The minimal arguments for GNU configure
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'><filename>CFLAGS</filename></ulink> - Suggested C flags
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'><filename>CXXFLAGS</filename></ulink> - Suggested C++ flags
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LDFLAGS'><filename>LDFLAGS</filename></ulink> - Suggested linker flags when you use CC to link
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CPPFLAGS'><filename>CPPFLAGS</filename></ulink> - Suggested preprocessor flags
</literallayout>
- After running the <filename>devtool reset</filename> command,
- you need to run <filename>devtool add</filename> again and
- provide the name or the version.
</para>
</section>
- <section id='sdk-dependency-detection-and-mapping'>
- <title>Dependency Detection and Mapping</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 attempts to
- detect build-time dependencies and map them to other recipes
- in the system.
- During this mapping, the command fills in the names of those
- recipes in the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
- value within the recipe.
- If a dependency cannot be mapped, then a comment is placed in
- the recipe indicating such.
- The inability to map a dependency might be caused because the
- naming is not recognized or because the dependency simply is
- not available.
- For cases where the dependency is not available, you must use
- the <filename>devtool add</filename> command to add an
- additional recipe to satisfy the dependency and then come
- back to the first recipe and add its name to
- <filename>DEPENDS</filename>.
+ The cornerstone of the extensible SDK is a command-line tool
+ called <filename>devtool</filename>.
+ This tool provides a number of features that help
+ you build, test and package software within the extensible SDK, and
+ optionally integrate it into an image built by the OpenEmbedded build
+ system.
</para>
<para>
- If you need to add runtime dependencies, you can do so by
- adding the following to your recipe:
- <literallayout class='monospaced'>
- RDEPENDS_${PN} += "dependency1 dependency2 ..."
- </literallayout>
+ The <filename>devtool</filename> command line is organized similarly
+ to
+ <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> in that it has a
+ number of sub-commands for each function.
+ You can run <filename>devtool --help</filename> to see all the
+ commands.
<note>
- The <filename>devtool add</filename> command often cannot
- distinguish between mandatory and optional dependencies.
- Consequently, some of the detected dependencies might
- in fact be optional.
- When in doubt, consult the documentation or the configure
- script for the software the recipe is building for further
- details.
- In some cases, you might find you can substitute the
- dependency for an option to disable the associated
- functionality passed to the configure script.
+ See the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename>&nbsp;Quick Reference</ulink>"
+ in the Yocto Project Reference Manual for more a
+ <filename>devtool</filename> reference.
</note>
</para>
- </section>
-
- <section id='sdk-license-detection'>
- <title>License Detection</title>
<para>
- The <filename>devtool add</filename> command attempts to
- determine if the software you are adding is able to be
- distributed under a common open-source license and sets the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
- value accordingly.
- You should double-check this value against the documentation
- or source files for the software you are building and update
- that <filename>LICENSE</filename> value if necessary.
+ Two <filename>devtool</filename> subcommands that provide
+ entry-points into development are:
+ <itemizedlist>
+ <listitem><para><emphasis><filename>devtool add</filename></emphasis>:
+ Assists in adding new software to be built.
+ </para></listitem>
+ <listitem><para><emphasis><filename>devtool modify</filename></emphasis>:
+ Sets up an environment to enable you to modify the source of
+ an existing component.
+ </para></listitem>
+ </itemizedlist>
+ As with the OpenEmbedded build system, "recipes" represent software
+ packages within <filename>devtool</filename>.
+ When you use <filename>devtool add</filename>, a recipe is
+ automatically created.
+ When you use <filename>devtool modify</filename>, the specified
+ existing recipe is used in order to determine where to get the source
+ code and how to patch it.
+ In both cases, an environment is set up so that when you build the
+ recipe a source tree that is under your control is used in order to
+ allow you to make changes to the source as desired.
+ By default, both new recipes and the source go into a "workspace"
+ directory under the SDK.
</para>
<para>
- The <filename>devtool add</filename> command also sets the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
- value to point to all files that appear to be license-related.
- However, license statements often appear in comments at the top
- of source files or within documentation.
- Consequently, you might need to amend the
- <filename>LIC_FILES_CHKSUM</filename> variable to point to one
- or more of those comments if present.
- Setting <filename>LIC_FILES_CHKSUM</filename> is particularly
- important for third-party software.
- The mechanism attempts to ensure correct licensing should you
- upgrade the recipe to a newer upstream version in future.
- Any change in licensing is detected and you receive an error
- prompting you to check the license text again.
+ The remainder of this section presents the
+ <filename>devtool add</filename> and
+ <filename>devtool modify</filename> workflows.
</para>
- <para>
- If the <filename>devtool add</filename> command cannot
- determine licensing information, the
- <filename>LICENSE</filename> value is set to "CLOSED" and the
- <filename>LIC_FILES_CHKSUM</filename> value remains unset.
- This behavior allows you to continue with development but is
- unlikely to be correct in all cases.
- Consequently, you should check the documentation or source
- files for the software you are building to determine the actual
- license.
- </para>
+ <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.
+ 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='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'>
+ $ 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.
+ </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='sdk-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/sdk-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, 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>
- <section id='sdk-adding-makefile-only-software'>
- <title>Adding Makefile-Only Software</title>
-
- <para>
- The use of <filename>make</filename> by itself is very common
- in both proprietary and open source software.
- Unfortunately, Makefiles are often not written with
- cross-compilation in mind.
- Thus, <filename>devtool add</filename> often cannot do very
- much to ensure that these Makefiles build correctly.
- It is very common, for example, to explicitly call
- <filename>gcc</filename> instead of using the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>
- variable.
- Usually, in a cross-compilation environment,
- <filename>gcc</filename> is the compiler for the build host
- and the cross-compiler is named something similar to
- <filename>arm-poky-linux-gnueabi-gcc</filename> and might
- require some arguments (e.g. to point to the associated sysroot
- for the target machine).
- </para>
+ <section id='sdk-a-closer-look-at-devtool-add'>
+ <title>A Closer Look at <filename>devtool add</filename></title>
<para>
- When writing a recipe for Makefile-only software, keep the
- following in mind:
+ The <filename>devtool add</filename> command automatically creates a
+ recipe based on the source tree with which you provide it.
+ Currently, the command has support for the following:
<itemizedlist>
<listitem><para>
- You probably need to patch the Makefile to use
- variables instead of hardcoding tools within the
- toolchain such as <filename>gcc</filename> and
- <filename>g++</filename>.
+ Autotools (<filename>autoconf</filename> and
+ <filename>automake</filename>)
</para></listitem>
<listitem><para>
- The environment in which <filename>make</filename> runs
- is set up with various standard variables for
- compilation (e.g. <filename>CC</filename>,
- <filename>CXX</filename>, and so forth) in a similar
- manner to the environment set up by the SDK's
- environment setup script.
- One easy way to see these variables is to run the
- <filename>devtool build</filename> command on the
- recipe and then look in
- <filename>oe-logs/run.do_compile</filename>.
- Towards the top of this file you will see a list of
- environment variables that are being set.
- You can take advantage of these variables within the
- Makefile.
+ CMake
</para></listitem>
<listitem><para>
- If the Makefile sets a default for a variable using "=",
- that default overrides the value set in the environment,
- which is usually not desirable.
- In this situation, you can either patch the Makefile
- so it sets the default using the "?=" operator, or
- you can alternatively force the value on the
- <filename>make</filename> command line.
- To force the value on the command line, add the
- variable setting to
- <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></ulink>
- or
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
- within the recipe.
- Here is an example using <filename>EXTRA_OEMAKE</filename>:
- <literallayout class='monospaced'>
- EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'"
- </literallayout>
- In the above example, single quotes are used around the
- variable settings as the values are likely to contain
- spaces because required default options are passed to
- the compiler.
+ Scons
</para></listitem>
<listitem><para>
- Hardcoding paths inside Makefiles is often problematic
- in a cross-compilation environment.
- This is particularly true because those hardcoded paths
- often point to locations on the build host and thus
- will either be read-only or will introduce
- contamination into the cross-compilation by virtue of
- being specific to the build host rather than the target.
- Patching the Makefile to use prefix variables or other
- path variables is usually the way to handle this.
+ <filename>qmake</filename>
</para></listitem>
<listitem><para>
- Sometimes a Makefile runs target-specific commands such
- as <filename>ldconfig</filename>.
- For such cases, you might be able to simply apply
- patches that remove these commands from the Makefile.
+ Plain <filename>Makefile</filename>
+ </para></listitem>
+ <listitem><para>
+ Out-of-tree kernel module
+ </para></listitem>
+ <listitem><para>
+ Binary package (i.e. "-b" option)
</para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id='sdk-adding-native-tools'>
- <title>Adding Native Tools</title>
-
- <para>
- Often, you need to build additional tools that run on the
- build host system as opposed to the target.
- You should indicate this using one of the following methods
- when you run <filename>devtool add</filename>:
- <itemizedlist>
<listitem><para>
- Specify the name of the recipe such that it ends
- with "-native".
- Specifying the name like this produces a recipe that
- only builds for the build host.
+ Node.js module
</para></listitem>
<listitem><para>
- Specify the "&dash;&dash;also-native" option with the
- <filename>devtool add</filename> command.
- Specifying this option creates a recipe file that still
- builds for the target but also creates a variant with
- a "-native" suffix that builds for the build host.
+ Python modules that use <filename>setuptools</filename>
+ or <filename>distutils</filename>
</para></listitem>
</itemizedlist>
+ </para>
+
+ <para>
+ Apart from binary packages, the determination of how a source tree
+ should be treated is automatic based on the files present within
+ that source tree.
+ For example, if a <filename>CMakeLists.txt</filename> file is found,
+ then the source tree is assumed to be using
+ CMake and is treated accordingly.
<note>
- If you need to add a tool that is shipped as part of a
- source tree that builds code for the target, you can
- typically accomplish this by building the native and target
- parts separately rather than within the same compilation
- process.
- Realize though that with the "&dash;&dash;also-native" option, you
- can add the tool using just one recipe file.
+ In most cases, you need to edit the automatically generated
+ recipe in order to make it build properly.
+ Typically, you would go through several edit and build cycles
+ until you can build the recipe.
+ Once the recipe can be built, you could use possible further
+ iterations to test the recipe on the target device.
</note>
</para>
- </section>
-
- <section id='sdk-adding-node-js-modules'>
- <title>Adding Node.js Modules</title>
<para>
- You can use the <filename>devtool add</filename> command two
- different ways to add Node.js modules: 1) Through
- <filename>npm</filename> and, 2) from a repository or local
- source.
+ The remainder of this section covers specifics regarding how parts
+ of the recipe are generated.
</para>
- <para>
- Use the following form to add Node.js modules through
- <filename>npm</filename>:
- <literallayout class='monospaced'>
- $ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1"
- </literallayout>
- The name and version parameters are mandatory.
- Lockdown and shrinkwrap files are generated and pointed to by
- the recipe in order to freeze the version that is fetched for
- the dependencies according to the first time.
- This also saves checksums that are verified on future fetches.
- Together, these behaviors ensure the reproducibility and
- integrity of the build.
- <note><title>Notes</title>
+ <section id='sdk-name-and-version'>
+ <title>Name and Version</title>
+
+ <para>
+ If you do not specify a name and version on the command
+ line, <filename>devtool add</filename> attempts to determine
+ the name and version of the software being built from
+ various metadata within the source tree.
+ Furthermore, the command sets the name of the created recipe
+ file accordingly.
+ If the name or version cannot be determined, the
+ <filename>devtool add</filename> command prints an error and
+ you must re-run the command with both the name and version
+ or just the name or version specified.
+ </para>
+
+ <para>
+ Sometimes the name or version determined from the source tree
+ might be incorrect.
+ For such a case, you must reset the recipe:
+ <literallayout class='monospaced'>
+ $ devtool reset -n <replaceable>recipename</replaceable>
+ </literallayout>
+ After running the <filename>devtool reset</filename> command,
+ you need to run <filename>devtool add</filename> again and
+ provide the name or the version.
+ </para>
+ </section>
+
+ <section id='sdk-dependency-detection-and-mapping'>
+ <title>Dependency Detection and Mapping</title>
+
+ <para>
+ The <filename>devtool add</filename> command attempts to
+ detect build-time dependencies and map them to other recipes
+ in the system.
+ During this mapping, the command fills in the names of those
+ recipes in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
+ value within the recipe.
+ If a dependency cannot be mapped, then a comment is placed in
+ the recipe indicating such.
+ The inability to map a dependency might be caused because the
+ naming is not recognized or because the dependency simply is
+ not available.
+ For cases where the dependency is not available, you must use
+ the <filename>devtool add</filename> command to add an
+ additional recipe to satisfy the dependency and then come
+ back to the first recipe and add its name to
+ <filename>DEPENDS</filename>.
+ </para>
+
+ <para>
+ If you need to add runtime dependencies, you can do so by
+ adding the following to your recipe:
+ <literallayout class='monospaced'>
+ RDEPENDS_${PN} += "dependency1 dependency2 ..."
+ </literallayout>
+ <note>
+ The <filename>devtool add</filename> command often cannot
+ distinguish between mandatory and optional dependencies.
+ Consequently, some of the detected dependencies might
+ in fact be optional.
+ When in doubt, consult the documentation or the configure
+ script for the software the recipe is building for further
+ details.
+ In some cases, you might find you can substitute the
+ dependency for an option to disable the associated
+ functionality passed to the configure script.
+ </note>
+ </para>
+ </section>
+
+ <section id='sdk-license-detection'>
+ <title>License Detection</title>
+
+ <para>
+ The <filename>devtool add</filename> command attempts to
+ determine if the software you are adding is able to be
+ distributed under a common open-source license and sets the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
+ value accordingly.
+ You should double-check this value against the documentation
+ or source files for the software you are building and update
+ that <filename>LICENSE</filename> value if necessary.
+ </para>
+
+ <para>
+ The <filename>devtool add</filename> command also sets the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
+ value to point to all files that appear to be license-related.
+ However, license statements often appear in comments at the top
+ of source files or within documentation.
+ Consequently, you might need to amend the
+ <filename>LIC_FILES_CHKSUM</filename> variable to point to one
+ or more of those comments if present.
+ Setting <filename>LIC_FILES_CHKSUM</filename> is particularly
+ important for third-party software.
+ The mechanism attempts to ensure correct licensing should you
+ upgrade the recipe to a newer upstream version in future.
+ Any change in licensing is detected and you receive an error
+ prompting you to check the license text again.
+ </para>
+
+ <para>
+ If the <filename>devtool add</filename> command cannot
+ determine licensing information, the
+ <filename>LICENSE</filename> value is set to "CLOSED" and the
+ <filename>LIC_FILES_CHKSUM</filename> value remains unset.
+ This behavior allows you to continue with development but is
+ unlikely to be correct in all cases.
+ Consequently, you should check the documentation or source
+ files for the software you are building to determine the actual
+ license.
+ </para>
+ </section>
+
+ <section id='sdk-adding-makefile-only-software'>
+ <title>Adding Makefile-Only Software</title>
+
+ <para>
+ The use of <filename>make</filename> by itself is very common
+ in both proprietary and open source software.
+ Unfortunately, Makefiles are often not written with
+ cross-compilation in mind.
+ Thus, <filename>devtool add</filename> often cannot do very
+ much to ensure that these Makefiles build correctly.
+ It is very common, for example, to explicitly call
+ <filename>gcc</filename> instead of using the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>
+ variable.
+ Usually, in a cross-compilation environment,
+ <filename>gcc</filename> is the compiler for the build host
+ and the cross-compiler is named something similar to
+ <filename>arm-poky-linux-gnueabi-gcc</filename> and might
+ require some arguments (e.g. to point to the associated sysroot
+ for the target machine).
+ </para>
+
+ <para>
+ When writing a recipe for Makefile-only software, keep the
+ following in mind:
<itemizedlist>
<listitem><para>
- You must use quotes around the URL.
- The <filename>devtool add</filename> does not require
- the quotes, but the shell considers ";" as a splitter
- between multiple commands.
- Thus, without the quotes,
- <filename>devtool add</filename> does not receive the
- other parts, which results in several "command not
- found" errors.
+ You probably need to patch the Makefile to use
+ variables instead of hardcoding tools within the
+ toolchain such as <filename>gcc</filename> and
+ <filename>g++</filename>.
</para></listitem>
<listitem><para>
- In order to support adding
- Node.js modules, a
- <filename>nodejs</filename> recipe must be part of your
- SDK in order to provide Node.js
- itself.
+ The environment in which <filename>make</filename> runs
+ is set up with various standard variables for
+ compilation (e.g. <filename>CC</filename>,
+ <filename>CXX</filename>, and so forth) in a similar
+ manner to the environment set up by the SDK's
+ environment setup script.
+ One easy way to see these variables is to run the
+ <filename>devtool build</filename> command on the
+ recipe and then look in
+ <filename>oe-logs/run.do_compile</filename>.
+ Towards the top of this file you will see a list of
+ environment variables that are being set.
+ You can take advantage of these variables within the
+ Makefile.
+ </para></listitem>
+ <listitem><para>
+ If the Makefile sets a default for a variable using "=",
+ that default overrides the value set in the environment,
+ which is usually not desirable.
+ In this situation, you can either patch the Makefile
+ so it sets the default using the "?=" operator, or
+ you can alternatively force the value on the
+ <filename>make</filename> command line.
+ To force the value on the command line, add the
+ variable setting to
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></ulink>
+ or
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
+ within the recipe.
+ Here is an example using <filename>EXTRA_OEMAKE</filename>:
+ <literallayout class='monospaced'>
+ EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'"
+ </literallayout>
+ In the above example, single quotes are used around the
+ variable settings as the values are likely to contain
+ spaces because required default options are passed to
+ the compiler.
+ </para></listitem>
+ <listitem><para>
+ Hardcoding paths inside Makefiles is often problematic
+ in a cross-compilation environment.
+ This is particularly true because those hardcoded paths
+ often point to locations on the build host and thus
+ will either be read-only or will introduce
+ contamination into the cross-compilation by virtue of
+ being specific to the build host rather than the target.
+ Patching the Makefile to use prefix variables or other
+ path variables is usually the way to handle this.
+ </para></listitem>
+ <listitem><para>
+ Sometimes a Makefile runs target-specific commands such
+ as <filename>ldconfig</filename>.
+ For such cases, you might be able to simply apply
+ patches that remove these commands from the Makefile.
</para></listitem>
</itemizedlist>
- </note>
- </para>
+ </para>
+ </section>
- <para>
- As mentioned earlier, you can also add Node.js modules
- directly from a repository or local source tree.
- To add modules this way, use <filename>devtool add</filename> in
- the following form:
- <literallayout class='monospaced'>
- $ devtool add https://github.com/diversario/node-ssdp
- </literallayout>
- In this example, <filename>devtool</filename> fetches the specified
- Git repository, detects that the code is Node.js code, fetches
- dependencies using <filename>npm</filename>, and sets
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
- accordingly.
- </para>
- </section>
-</section>
+ <section id='sdk-adding-native-tools'>
+ <title>Adding Native Tools</title>
-<section id='sdk-working-with-recipes'>
- <title>Working With Recipes</title>
-
- <para>
- When building a recipe with <filename>devtool build</filename> the
- typical build progression is as follows:
- <orderedlist>
- <listitem><para>
- Fetch the source
- </para></listitem>
- <listitem><para>
- Unpack the source
- </para></listitem>
- <listitem><para>
- Configure the source
- </para></listitem>
- <listitem><para>
- Compiling the source
- </para></listitem>
- <listitem><para>
- Install the build output
- </para></listitem>
- <listitem><para>
- Package the installed output
- </para></listitem>
- </orderedlist>
- For recipes in the workspace, fetching and unpacking is disabled
- as the source tree has already been prepared and is persistent.
- Each of these build steps is defined as a function, usually with a
- "do_" prefix.
- These functions are typically shell scripts but can instead be written
- in Python.
- </para>
-
- <para>
- If you look at the contents of a recipe, you will see that the
- recipe does not include complete instructions for building the
- software.
- Instead, common functionality is encapsulated in classes inherited
- with the <filename>inherit</filename> directive, leaving the recipe
- to describe just the things that are specific to the software to be
- built.
- A <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-base'><filename>base</filename></ulink>
- class exists that is implicitly inherited by all recipes and provides
- the functionality that most typical recipes need.
- </para>
-
- <para>
- The remainder of this section presents information useful when
- working with recipes.
- </para>
+ <para>
+ Often, you need to build additional tools that run on the
+ build host system as opposed to the target.
+ You should indicate this using one of the following methods
+ when you run <filename>devtool add</filename>:
+ <itemizedlist>
+ <listitem><para>
+ Specify the name of the recipe such that it ends
+ with "-native".
+ Specifying the name like this produces a recipe that
+ only builds for the build host.
+ </para></listitem>
+ <listitem><para>
+ Specify the "&dash;&dash;also-native" option with the
+ <filename>devtool add</filename> command.
+ Specifying this option creates a recipe file that still
+ builds for the target but also creates a variant with
+ a "-native" suffix that builds for the build host.
+ </para></listitem>
+ </itemizedlist>
+ <note>
+ If you need to add a tool that is shipped as part of a
+ source tree that builds code for the target, you can
+ typically accomplish this by building the native and target
+ parts separately rather than within the same compilation
+ process.
+ Realize though that with the "&dash;&dash;also-native" option, you
+ can add the tool using just one recipe file.
+ </note>
+ </para>
+ </section>
+
+ <section id='sdk-adding-node-js-modules'>
+ <title>Adding Node.js Modules</title>
+
+ <para>
+ You can use the <filename>devtool add</filename> command two
+ different ways to add Node.js modules: 1) Through
+ <filename>npm</filename> and, 2) from a repository or local
+ source.
+ </para>
+
+ <para>
+ Use the following form to add Node.js modules through
+ <filename>npm</filename>:
+ <literallayout class='monospaced'>
+ $ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1"
+ </literallayout>
+ The name and version parameters are mandatory.
+ Lockdown and shrinkwrap files are generated and pointed to by
+ the recipe in order to freeze the version that is fetched for
+ the dependencies according to the first time.
+ This also saves checksums that are verified on future fetches.
+ Together, these behaviors ensure the reproducibility and
+ integrity of the build.
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ You must use quotes around the URL.
+ The <filename>devtool add</filename> does not require
+ the quotes, but the shell considers ";" as a splitter
+ between multiple commands.
+ Thus, without the quotes,
+ <filename>devtool add</filename> does not receive the
+ other parts, which results in several "command not
+ found" errors.
+ </para></listitem>
+ <listitem><para>
+ In order to support adding
+ Node.js modules, a
+ <filename>nodejs</filename> recipe must be part of your
+ SDK in order to provide Node.js
+ itself.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
- <section id='sdk-finding-logs-and-work-files'>
- <title>Finding Logs and Work Files</title>
+ <para>
+ As mentioned earlier, you can also add Node.js modules
+ directly from a repository or local source tree.
+ To add modules this way, use <filename>devtool add</filename> in
+ the following form:
+ <literallayout class='monospaced'>
+ $ devtool add https://github.com/diversario/node-ssdp
+ </literallayout>
+ In this example, <filename>devtool</filename> fetches the specified
+ Git repository, detects that the code is Node.js code, fetches
+ dependencies using <filename>npm</filename>, and sets
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+ accordingly.
+ </para>
+ </section>
+ </section>
- <para>
- When you are debugging a recipe that you previously created using
- <filename>devtool add</filename> or whose source you are modifying
- by using the <filename>devtool modify</filename> command, after
- the first run of <filename>devtool build</filename>, you will
- find some symbolic links created within the source tree:
- <filename>oe-logs</filename>, which points to the directory in
- which log files and run scripts for each build step are created
- and <filename>oe-workdir</filename>, which points to the temporary
- work area for the recipe.
- You can use these links to get more information on what is
- happening at each build step.
- </para>
+ <section id='sdk-working-with-recipes'>
+ <title>Working With Recipes</title>
<para>
- These locations under <filename>oe-workdir</filename> are
- particularly useful:
- <itemizedlist>
- <listitem><para><filename>image/</filename>:
- Contains all of the files installed at the
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
- stage.
- Within a recipe, this directory is referred to by the
- expression
- <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>.
+ When building a recipe with <filename>devtool build</filename> the
+ typical build progression is as follows:
+ <orderedlist>
+ <listitem><para>
+ Fetch the source
</para></listitem>
- <listitem><para><filename>sysroot-destdir/</filename>:
- Contains a subset of files installed within
- <filename>do_install</filename> that have been put into the
- shared sysroot.
- For more information, see the
- "<link linkend='sdk-sharing-files-between-recipes'>Sharing Files Between Recipes</link>"
- section.
+ <listitem><para>
+ Unpack the source
</para></listitem>
- <listitem><para><filename>packages-split/</filename>:
- Contains subdirectories for each package produced by the
- recipe.
- For more information, see the
- "<link linkend='sdk-packaging'>Packaging</link>" section.
+ <listitem><para>
+ Configure the source
</para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id='sdk-setting-configure-arguments'>
- <title>Setting Configure Arguments</title>
-
- <para>
- If the software your recipe is building uses GNU autoconf,
- then a fixed set of arguments is passed to it to enable
- cross-compilation plus any extras specified by
- <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink>
- or
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
- set within the recipe.
- If you wish to pass additional options, add them to
- <filename>EXTRA_OECONF</filename> or
- <filename>PACKAGECONFIG_CONFARGS</filename>.
- Other supported build tools have similar variables
- (e.g.
- <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></ulink>
- for CMake,
- <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OESCONS'><filename>EXTRA_OESCONS</filename></ulink>
- for Scons, and so forth).
- If you need to pass anything on the <filename>make</filename>
- command line, you can use <filename>EXTRA_OEMAKE</filename> or the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
- variables to do so.
+ <listitem><para>
+ Compiling the source
+ </para></listitem>
+ <listitem><para>
+ Install the build output
+ </para></listitem>
+ <listitem><para>
+ Package the installed output
+ </para></listitem>
+ </orderedlist>
+ For recipes in the workspace, fetching and unpacking is disabled
+ as the source tree has already been prepared and is persistent.
+ Each of these build steps is defined as a function, usually with a
+ "do_" prefix.
+ These functions are typically shell scripts but can instead be written
+ in Python.
</para>
<para>
- You can use the <filename>devtool configure-help</filename> command
- to help you set the arguments listed in the previous paragraph.
- The command determines the exact options being passed, and shows
- them to you along with any custom arguments specified through
- <filename>EXTRA_OECONF</filename> or
- <filename>PACKAGECONFIG_CONFARGS</filename>.
- If applicable, the command also shows you the output of the
- configure script's "&dash;&dash;help" option as a reference.
+ If you look at the contents of a recipe, you will see that the
+ recipe does not include complete instructions for building the
+ software.
+ Instead, common functionality is encapsulated in classes inherited
+ with the <filename>inherit</filename> directive, leaving the recipe
+ to describe just the things that are specific to the software to be
+ built.
+ A <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-base'><filename>base</filename></ulink>
+ class exists that is implicitly inherited by all recipes and provides
+ the functionality that most typical recipes need.
</para>
- </section>
-
- <section id='sdk-sharing-files-between-recipes'>
- <title>Sharing Files Between Recipes</title>
<para>
- Recipes often need to use files provided by other recipes on
- the build host.
- For example, an application linking to a common library needs
- access to the library itself and its associated headers.
- The way this access is accomplished within the extensible SDK is
- through the sysroot.
- One sysroot exists per "machine" for which the SDK is being built.
- In practical terms, this means a sysroot exists for the target
- machine, and a sysroot exists for the build host.
+ The remainder of this section presents information useful when
+ working with recipes.
</para>
- <para>
- Recipes should never write files directly into the sysroot.
- Instead, files should be installed into standard locations
- during the
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
- task within the
- <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>
- directory.
- A subset of these files automatically go into the sysroot.
- The reason for this limitation is that almost all files that go
- into the sysroot are cataloged in manifests in order to ensure
- they can be removed later when a recipe is modified or removed.
- Thus, the sysroot is able to remain free from stale files.
- </para>
+ <section id='sdk-finding-logs-and-work-files'>
+ <title>Finding Logs and Work Files</title>
+
+ <para>
+ When you are debugging a recipe that you previously created using
+ <filename>devtool add</filename> or whose source you are modifying
+ by using the <filename>devtool modify</filename> command, after
+ the first run of <filename>devtool build</filename>, you will
+ find some symbolic links created within the source tree:
+ <filename>oe-logs</filename>, which points to the directory in
+ which log files and run scripts for each build step are created
+ and <filename>oe-workdir</filename>, which points to the temporary
+ work area for the recipe.
+ You can use these links to get more information on what is
+ happening at each build step.
+ </para>
+
+ <para>
+ These locations under <filename>oe-workdir</filename> are
+ particularly useful:
+ <itemizedlist>
+ <listitem><para><filename>image/</filename>:
+ Contains all of the files installed at the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
+ stage.
+ Within a recipe, this directory is referred to by the
+ expression
+ <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>.
+ </para></listitem>
+ <listitem><para><filename>sysroot-destdir/</filename>:
+ Contains a subset of files installed within
+ <filename>do_install</filename> that have been put into the
+ shared sysroot.
+ For more information, see the
+ "<link linkend='sdk-sharing-files-between-recipes'>Sharing Files Between Recipes</link>"
+ section.
+ </para></listitem>
+ <listitem><para><filename>packages-split/</filename>:
+ Contains subdirectories for each package produced by the
+ recipe.
+ For more information, see the
+ "<link linkend='sdk-packaging'>Packaging</link>" section.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='sdk-setting-configure-arguments'>
+ <title>Setting Configure Arguments</title>
+
+ <para>
+ If the software your recipe is building uses GNU autoconf,
+ then a fixed set of arguments is passed to it to enable
+ cross-compilation plus any extras specified by
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink>
+ or
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
+ set within the recipe.
+ If you wish to pass additional options, add them to
+ <filename>EXTRA_OECONF</filename> or
+ <filename>PACKAGECONFIG_CONFARGS</filename>.
+ Other supported build tools have similar variables
+ (e.g.
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></ulink>
+ for CMake,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OESCONS'><filename>EXTRA_OESCONS</filename></ulink>
+ for Scons, and so forth).
+ If you need to pass anything on the <filename>make</filename>
+ command line, you can use <filename>EXTRA_OEMAKE</filename> or the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
+ variables to do so.
+ </para>
+
+ <para>
+ You can use the <filename>devtool configure-help</filename> command
+ to help you set the arguments listed in the previous paragraph.
+ The command determines the exact options being passed, and shows
+ them to you along with any custom arguments specified through
+ <filename>EXTRA_OECONF</filename> or
+ <filename>PACKAGECONFIG_CONFARGS</filename>.
+ If applicable, the command also shows you the output of the
+ configure script's "&dash;&dash;help" option as a reference.
+ </para>
+ </section>
+
+ <section id='sdk-sharing-files-between-recipes'>
+ <title>Sharing Files Between Recipes</title>
+
+ <para>
+ Recipes often need to use files provided by other recipes on
+ the build host.
+ For example, an application linking to a common library needs
+ access to the library itself and its associated headers.
+ The way this access is accomplished within the extensible SDK is
+ through the sysroot.
+ One sysroot exists per "machine" for which the SDK is being built.
+ In practical terms, this means a sysroot exists for the target
+ machine, and a sysroot exists for the build host.
+ </para>
+
+ <para>
+ Recipes should never write files directly into the sysroot.
+ Instead, files should be installed into standard locations
+ during the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
+ task within the
+ <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>
+ directory.
+ A subset of these files automatically go into the sysroot.
+ The reason for this limitation is that almost all files that go
+ into the sysroot are cataloged in manifests in order to ensure
+ they can be removed later when a recipe is modified or removed.
+ Thus, the sysroot is able to remain free from stale files.
+ </para>
+ </section>
+
+ <section id='sdk-packaging'>
+ <title>Packaging</title>
+
+ <para>
+ Packaging is not always particularly relevant within the
+ extensible SDK.
+ However, if you examine how build output gets into the final image
+ on the target device, it is important to understand packaging
+ because the contents of the image are expressed in terms of
+ packages and not recipes.
+ </para>
+
+ <para>
+ During the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
+ task, files installed during the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
+ task are split into one main package, which is almost always named
+ the same as the recipe, and several other packages.
+ This separation is done because not all of those installed files
+ are always useful in every image.
+ For example, you probably do not need any of the documentation
+ installed in a production image.
+ Consequently, for each recipe the documentation files are separated
+ into a <filename>-doc</filename> package.
+ Recipes that package software that has optional modules or
+ plugins might do additional package splitting as well.
+ </para>
+
+ <para>
+ After building a recipe you can see where files have gone by
+ looking in the <filename>oe-workdir/packages-split</filename>
+ directory, which contains a subdirectory for each package.
+ Apart from some advanced cases, the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>
+ variables controls splitting.
+ The <filename>PACKAGES</filename> variable lists all of the
+ packages to be produced, while the <filename>FILES</filename>
+ variable specifies which files to include in each package,
+ using an override to specify the package.
+ For example, <filename>FILES_${PN}</filename> specifies the files
+ to go into the main package (i.e. the main package is named the
+ same as the recipe and
+ <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
+ evaluates to the recipe name).
+ The order of the <filename>PACKAGES</filename> value is significant.
+ For each installed file, the first package whose
+ <filename>FILES</filename> value matches the file is the package
+ into which the file goes.
+ Defaults exist for both the <filename>PACKAGES</filename> and
+ <filename>FILES</filename> variables.
+ Consequently, you might find you do not even need to set these
+ variables in your recipe unless the software the recipe is
+ building installs files into non-standard locations.
+ </para>
+ </section>
</section>
- <section id='sdk-packaging'>
- <title>Packaging</title>
+ <section id='sdk-restoring-the-target-device-to-its-original-state'>
+ <title>Restoring the Target Device to its Original State</title>
<para>
- Packaging is not always particularly relevant within the
- extensible SDK.
- However, if you examine how build output gets into the final image
- on the target device, it is important to understand packaging
- because the contents of the image are expressed in terms of
- packages and not recipes.
- </para>
-
- <para>
- During the
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
- task, files installed during the
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
- task are split into one main package, which is almost always named
- the same as the recipe, and several other packages.
- This separation is done because not all of those installed files
- are always useful in every image.
- For example, you probably do not need any of the documentation
- installed in a production image.
- Consequently, for each recipe the documentation files are separated
- into a <filename>-doc</filename> package.
- Recipes that package software that has optional modules or
- plugins might do additional package splitting as well.
- </para>
-
- <para>
- After building a recipe you can see where files have gone by
- looking in the <filename>oe-workdir/packages-split</filename>
- directory, which contains a subdirectory for each package.
- Apart from some advanced cases, the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>
- and
- <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>
- variables controls splitting.
- The <filename>PACKAGES</filename> variable lists all of the
- packages to be produced, while the <filename>FILES</filename>
- variable specifies which files to include in each package,
- using an override to specify the package.
- For example, <filename>FILES_${PN}</filename> specifies the files
- to go into the main package (i.e. the main package is named the
- same as the recipe and
- <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
- evaluates to the recipe name).
- The order of the <filename>PACKAGES</filename> value is significant.
- For each installed file, the first package whose
- <filename>FILES</filename> value matches the file is the package
- into which the file goes.
- Defaults exist for both the <filename>PACKAGES</filename> and
- <filename>FILES</filename> variables.
- Consequently, you might find you do not even need to set these
- variables in your recipe unless the software the recipe is
- building installs files into non-standard locations.
- </para>
- </section>
-</section>
-
-<section id='sdk-restoring-the-target-device-to-its-original-state'>
- <title>Restoring the Target Device to its Original State</title>
-
- <para>
- If you use the <filename>devtool deploy-target</filename>
- command to write a recipe's build output to the target, and
- you are working on an existing component of the system, then you
- might find yourself in a situation where you need to restore the
- original files that existed prior to running the
- <filename>devtool deploy-target</filename> command.
- Because the <filename>devtool deploy-target</filename> command
- backs up any files it overwrites, you can use the
- <filename>devtool undeploy-target</filename> to restore those files
- and remove any other files the recipe deployed.
- Consider the following example:
- <literallayout class='monospaced'>
+ If you use the <filename>devtool deploy-target</filename>
+ command to write a recipe's build output to the target, and
+ you are working on an existing component of the system, then you
+ might find yourself in a situation where you need to restore the
+ original files that existed prior to running the
+ <filename>devtool deploy-target</filename> command.
+ Because the <filename>devtool deploy-target</filename> command
+ backs up any files it overwrites, you can use the
+ <filename>devtool undeploy-target</filename> to restore those files
+ and remove any other files the recipe deployed.
+ Consider the following example:
+ <literallayout class='monospaced'>
$ devtool undeploy-target lighttpd root@192.168.7.2
- </literallayout>
- If you have deployed multiple applications, you can remove them
- all at once thus restoring the target device back to its
- original state:
- <literallayout class='monospaced'>
+ </literallayout>
+ If you have deployed multiple applications, you can remove them
+ all at once thus restoring the target device back to its
+ original state:
+ <literallayout class='monospaced'>
$ devtool undeploy-target -a root@192.168.7.2
- </literallayout>
- Information about files deployed to the target as well as any
- backed up files are stored on the target itself.
- This storage of course requires some additional space
- on the target machine.
- <note>
- The <filename>devtool deploy-target</filename> and
- <filename>devtool undeploy-target</filename> command do not
- currently interact with any package management system on the
- target device (e.g. RPM or OPKG).
- Consequently, you should not intermingle operations
- <filename>devtool deploy-target</filename> and the package
- manager operations on the target device.
- Doing so could result in a conflicting set of files.
- </note>
- </para>
-</section>
+ </literallayout>
+ Information about files deployed to the target as well as any
+ backed up files are stored on the target itself.
+ This storage of course requires some additional space
+ on the target machine.
+ <note>
+ The <filename>devtool deploy-target</filename> and
+ <filename>devtool undeploy-target</filename> command do not
+ currently interact with any package management system on the
+ target device (e.g. RPM or OPKG).
+ Consequently, you should not intermingle operations
+ <filename>devtool deploy-target</filename> and the package
+ manager operations on the target device.
+ Doing so could result in a conflicting set of files.
+ </note>
+ </para>
+ </section>
-<section id='sdk-installing-additional-items-into-the-extensible-sdk'>
- <title>Installing Additional Items Into the Extensible SDK</title>
+ <section id='sdk-installing-additional-items-into-the-extensible-sdk'>
+ <title>Installing Additional Items Into the Extensible SDK</title>
- <para>
- The extensible SDK typically only comes with a small number of tools
- and libraries out of the box.
- If you have a minimal SDK, then it starts mostly empty and is
- populated on-demand.
- However, sometimes you will need to explicitly install extra items
- into the SDK.
- If you need these extra items, you can first search for the items
- using the <filename>devtool search</filename> command.
- For example, suppose you need to link to libGL but you are not sure
- which recipe provides it.
- You can use the following command to find out:
- <literallayout class='monospaced'>
+ <para>
+ The extensible SDK typically only comes with a small number of tools
+ and libraries out of the box.
+ If you have a minimal SDK, then it starts mostly empty and is
+ populated on-demand.
+ However, sometimes you will need to explicitly install extra items
+ into the SDK.
+ If you need these extra items, you can first search for the items
+ using the <filename>devtool search</filename> command.
+ For example, suppose you need to link to libGL but you are not sure
+ which recipe provides it.
+ You can use the following command to find out:
+ <literallayout class='monospaced'>
$ devtool search libGL
mesa A free implementation of the OpenGL API
- </literallayout>
- Once you know the recipe (i.e. <filename>mesa</filename> in this
- example), you can install it:
- <literallayout class='monospaced'>
+ </literallayout>
+ Once you know the recipe (i.e. <filename>mesa</filename> in this
+ example), you can install it:
+ <literallayout class='monospaced'>
$ devtool sdk-install mesa
- </literallayout>
- By default, the <filename>devtool sdk-install</filename> assumes the
- item is available in pre-built form from your SDK provider.
- If the item is not available and it is acceptable to build the item
- from source, you can add the "-s" option as follows:
- <literallayout class='monospaced'>
+ </literallayout>
+ By default, the <filename>devtool sdk-install</filename> assumes the
+ item is available in pre-built form from your SDK provider.
+ If the item is not available and it is acceptable to build the item
+ from source, you can add the "-s" option as follows:
+ <literallayout class='monospaced'>
$ devtool sdk-install -s mesa
- </literallayout>
- 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 instead add it using the <filename>devtool add</filename> command.
- </para>
-</section>
+ </literallayout>
+ 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 instead add it using the <filename>devtool add</filename> command.
+ </para>
+ </section>
-<section id='sdk-updating-the-extensible-sdk'>
- <title>Updating the Extensible SDK</title>
+ <section id='sdk-updating-the-extensible-sdk'>
+ <title>Updating the Extensible SDK</title>
- <para>
- If you are working with an extensible SDK that gets occasionally
- updated (e.g. typically when that SDK has been provided to you by
- another party), then you will need to manually pull down those
- updates to your installed SDK.
- </para>
+ <para>
+ If you are working with an extensible SDK that gets occasionally
+ updated (e.g. typically when that SDK has been provided to you by
+ another party), then you will need to manually pull down those
+ updates to your installed SDK.
+ </para>
- <para>
- To update your installed SDK, run the following:
- <literallayout class='monospaced'>
+ <para>
+ To update your installed SDK, run the following:
+ <literallayout class='monospaced'>
$ devtool sdk-update
- </literallayout>
- The previous command assumes your SDK provider has set the default
- update URL for you.
- If that URL has not been set, you need to specify it yourself as
- follows:
- <literallayout class='monospaced'>
+ </literallayout>
+ The previous command assumes your SDK provider has set the default
+ update URL for you.
+ If that URL has not been set, you need to specify it yourself as
+ follows:
+ <literallayout class='monospaced'>
$ devtool sdk-update <replaceable>path_to_update_directory</replaceable>
- </literallayout>
- <note>
- The URL needs to point specifically to a published SDK and not an
- SDK installer that you would download and install.
- </note>
- </para>
-</section>
-
-<section id='sdk-creating-a-derivative-sdk-with-additional-components'>
- <title>Creating a Derivative SDK With Additional Components</title>
+ </literallayout>
+ <note>
+ The URL needs to point specifically to a published SDK and not an
+ SDK installer that you would download and install.
+ </note>
+ </para>
+ </section>
- <para>
- You might need to produce an SDK that contains your own custom
- libraries for sending to a third party (e.g., if you are a vendor with
- customers needing to build their own software for the target platform).
- If that is the case, then you can produce a derivative SDK based on
- the currently installed SDK fairly easily.
- Use these steps:
- <orderedlist>
- <listitem><para>If necessary, install an extensible SDK that
- you want to use as a base for your derivative SDK.
- </para></listitem>
- <listitem><para>Source the environment script for the SDK.
- </para></listitem>
- <listitem><para>Add the extra libraries or other components
- you want by using the <filename>devtool add</filename>
- command.
- </para></listitem>
- <listitem><para>Run the <filename>devtool build-sdk</filename>
- command.
- </para></listitem>
- </orderedlist>
- The above procedure takes the recipes added to the workspace and
- 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 users
- to add their own recipes.
- </para>
-</section>
+ <section id='sdk-creating-a-derivative-sdk-with-additional-components'>
+ <title>Creating a Derivative SDK With Additional Components</title>
+ <para>
+ You might need to produce an SDK that contains your own custom
+ libraries for sending to a third party (e.g., if you are a vendor with
+ customers needing to build their own software for the target platform).
+ If that is the case, then you can produce a derivative SDK based on
+ the currently installed SDK fairly easily.
+ Use these steps:
+ <orderedlist>
+ <listitem><para>If necessary, install an extensible SDK that
+ you want to use as a base for your derivative SDK.
+ </para></listitem>
+ <listitem><para>Source the environment script for the SDK.
+ </para></listitem>
+ <listitem><para>Add the extra libraries or other components
+ you want by using the <filename>devtool add</filename>
+ command.
+ </para></listitem>
+ <listitem><para>Run the <filename>devtool build-sdk</filename>
+ command.
+ </para></listitem>
+ </orderedlist>
+ The above procedure takes the recipes added to the workspace and
+ 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 users
+ to add their own recipes.
+ </para>
+ </section>
</chapter>
<!--
vim: expandtab tw=80 ts=4
diff --git a/documentation/sdk-manual/sdk-intro.xml b/documentation/sdk-manual/sdk-intro.xml
index 0995f79a93..e0f51e1cf1 100644
--- a/documentation/sdk-manual/sdk-intro.xml
+++ b/documentation/sdk-manual/sdk-intro.xml
@@ -12,25 +12,24 @@
Welcome to the Yocto Project Software Development Kit (SDK)
Developer's Guide.
This manual provides information that explains how to use both the
- standard Yocto Project SDK and an extensible SDK to develop
- applications and images using the Yocto Project.
+ Yocto Project extensible and standard SDKs to develop
+ applications and images.
Additionally, the manual also provides information on how to use
the popular <trademark class='trade'>Eclipse</trademark> IDE as part
of your application development workflow within the SDK environment.
+ <note>
+ Prior to the 2.0 Release of the Yocto Project, application
+ development was primarily accomplished through the use of the
+ Application Development Toolkit (ADT) and the availability
+ of stand-alone cross-development toolchains and other tools.
+ With the 2.1 Release of the Yocto Project, application development
+ has transitioned to within a tool-rich extensible SDK and the more
+ traditional standard SDK.
+ </note>
</para>
<para>
- Prior to the 2.0 Release of the Yocto Project, application
- development was primarily accomplished through the use of the
- Application Development Toolkit (ADT) and the availability
- of stand-alone cross-development toolchains and other tools.
- With the 2.1 Release of the Yocto Project, application development
- has transitioned to within a more traditional SDK and extensible
- SDK.
- </para>
-
- <para>
- A standard SDK consists of the following:
+ All SDKs consist of the following:
<itemizedlist>
<listitem><para><emphasis>Cross-Development Toolchain</emphasis>:
This toolchain contains a compiler, debugger, and various
@@ -46,19 +45,19 @@
preparing for SDK use.
</para></listitem>
</itemizedlist>
- You can use the standard SDK to independently develop and test code
- that is destined to run on some target machine.
</para>
<para>
- An extensible SDK consists of everything that the standard SDK has plus
- 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
+ Additionally an extensible SDK has 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
<ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>.
</para>
<para>
+ You can use an SDK to independently develop and test code
+ that is destined to run on some target machine.
SDKs are completely self-contained.
The binaries are linked against their own copy of
<filename>libc</filename>, which results in no dependencies
@@ -73,7 +72,7 @@
<para>
Another feature for the SDKs is that only one set of cross-compiler
- toolchain binaries are produced per architecture.
+ toolchain binaries are produced for any given architecture.
This feature takes advantage of the fact that the target hardware can
be passed to <filename>gcc</filename> as a set of compiler options.
Those options are set up by the environment script and contained in
@@ -98,6 +97,8 @@
configuration and extensions,
which allows you to cross-develop on the host machine for the
target hardware.
+ Additionally, the extensible SDK contains the
+ <filename>devtool</filename> functionality.
</para></listitem>
<listitem><para>The Quick EMUlator (QEMU), which lets you simulate
target hardware.
@@ -122,6 +123,85 @@
</itemizedlist>
</para>
+ <para>
+ In summary, the extensible and standard SDK share many features.
+ However, the extensible SDK has powerful development tools to help you
+ more quickly develop applications.
+ Following is a table that summarizes the primary differences between
+ the standard and extensible SDK types when considering which to
+ build:
+ <informaltable frame='none'>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1' colwidth='1*'/>
+ <colspec colname='c2' colwidth='1*'/>
+ <colspec colname='c3' colwidth='1*'/>
+ <thead>
+ <row>
+ <entry align="left"><emphasis>Feature</emphasis></entry>
+ <entry align="left"><emphasis>Standard SDK</emphasis></entry>
+ <entry align="left"><emphasis>Extensible SDK</emphasis></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry align="left">Toolchain</entry>
+ <entry align="left">Yes</entry>
+ <entry align="left">Yes*</entry>
+ </row>
+ <row>
+ <entry align="left">Debugger</entry>
+ <entry align="left">Yes</entry>
+ <entry align="left">Yes*</entry>
+ </row>
+ <row>
+ <entry align="left">Size</entry>
+ <entry align="left">100+ MBytes</entry>
+ <entry align="left">1+ GBytes (or 300+ MBytes for minimal w/toolchain)</entry>
+ </row>
+ <row>
+ <entry align="left"><filename>devtool</filename></entry>
+ <entry align="left">No</entry>
+ <entry align="left">Yes</entry>
+ </row>
+ <row>
+ <entry align="left">Build Images</entry>
+ <entry align="left">No</entry>
+ <entry align="left">Yes</entry>
+ </row>
+ <row>
+ <entry align="left">Updateable</entry>
+ <entry align="left">No</entry>
+ <entry align="left">Yes</entry>
+ </row>
+ <row>
+ <entry align="left">Managed Sysroot**</entry>
+ <entry align="left">No</entry>
+ <entry align="left">Yes</entry>
+ </row>
+ <row>
+ <entry align="left">Installed Packages</entry>
+ <entry align="left">No***</entry>
+ <entry align="left">Yes****</entry>
+ </row>
+ <row>
+ <entry align="left">Construction</entry>
+ <entry align="left">Packages</entry>
+ <entry align="left">Shared State</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <literallayout class='monospaced'>
+ * Extensible SDK will contain the toolchain and debugger if <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink> is "full" or <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink> is "1", which is the default.
+
+ ** Sysroot is managed through use of <filename>devtool</filename>. Thus, it is less likely that you will corrupt your SDK sysroot when you try to add additional libraries.
+
+ *** Runtime package management can be added to the standard SDK but it is not supported by default.
+
+ **** You must build and make the shared state available to extensible SDK users for "packages" you want to enable users to install.
+ </literallayout>
+ </para>
+
<section id='the-cross-development-toolchain'>
<title>The Cross-Development Toolchain</title>
@@ -131,6 +211,8 @@
consists of a cross-compiler, cross-linker, and cross-debugger
that are used to develop user-space applications for targeted
hardware.
+ Additionally, for an extensible SDK, the toolchain also has
+ built-in <filename>devtool</filename> functionality.
This toolchain is created by running a toolchain installer script
or through a
<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
@@ -258,7 +340,7 @@
For information on how to install the SDK, see the
"<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
section.</para></listitem>
- <listitem><para><emphasis>Download the Target Image:</emphasis>
+ <listitem><para><emphasis>Download or Build the Target Image:</emphasis>
The Yocto Project supports several target architectures
and has many pre-built kernel images and root filesystem
images.</para>
diff --git a/documentation/sdk-manual/sdk-manual.xml b/documentation/sdk-manual/sdk-manual.xml
index 39a8689195..66cd10d507 100644
--- a/documentation/sdk-manual/sdk-manual.xml
+++ b/documentation/sdk-manual/sdk-manual.xml
@@ -66,9 +66,11 @@
<xi:include href="sdk-intro.xml"/>
+ <xi:include href="sdk-extensible.xml"/>
+
<xi:include href="sdk-using.xml"/>
- <xi:include href="sdk-extensible.xml"/>
+ <xi:include href="sdk-working-projects.xml"/>
<xi:include href="sdk-appendix-obtain.xml"/>
diff --git a/documentation/sdk-manual/sdk-using.xml b/documentation/sdk-manual/sdk-using.xml
index dd11304319..44cb49c0c8 100644
--- a/documentation/sdk-manual/sdk-using.xml
+++ b/documentation/sdk-manual/sdk-using.xml
@@ -3,74 +3,82 @@
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
<chapter id='sdk-using-the-standard-sdk'>
-
-<title>Using the Standard SDK</title>
-
-<para>
- This chapter describes the standard SDK and how to use it.
- Information covers the pieces of the SDK, how to install it, and presents
- several task-based procedures common for developing with a standard SDK.
- <note>
- The tasks you can perform using a standard SDK are also applicable
- when you are using an extensible SDK.
- For information on the differences when using an extensible SDK as
- compared to a standard SDK, see the
- "<link linkend='sdk-extensible'>Using the Extensible SDK</link>"
- chapter.
- </note>
-</para>
-
-<section id='sdk-standard-sdk-intro'>
- <title>Why use the Standard SDK and What is in It?</title>
+ <title>Using the Standard SDK</title>
<para>
- 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.
+ This chapter describes the standard SDK and how to install it.
+ Information includes unique installation and setup aspects for the
+ standard SDK.
+ <note>
+ For a side-by-side comparison of main features supported for a
+ standard SDK as compared to an extensible SDK, see the
+ "<link linkend='sdk-manual-intro'>Introduction</link>"
+ section.
+ </note>
</para>
<para>
- The installed Standard SDK consists of several files and directories.
- Basically, it contains an SDK environment setup script, some
- configuration files, and host and target root filesystems to support
- usage.
- You can see the directory structure in the
- "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
- section.
+ You can use a standard SDK to work on Makefile, Autotools, and
+ Eclipse-based projects.
+ See the
+ "<link linkend='sdk-working-projects'>Working with Different Types of Projects</link>"
+ chapter for more information.
</para>
-</section>
-<section id='sdk-installing-the-sdk'>
- <title>Installing the SDK</title>
+ <section id='sdk-standard-sdk-intro'>
+ <title>Why use the Standard SDK and What is in It?</title>
- <para>
- The first thing you need to do is install the SDK on your host
- development machine by running the <filename>*.sh</filename>
- installation script.
- </para>
+ <para>
+ 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 as compared to the extensible SDK, which
+ provides an internal build system and the
+ <filename>devtool</filename> functionality.
+ </para>
- <para>
- You can download a tarball installer, which includes the
- pre-built toolchain, the <filename>runqemu</filename>
- script, and support files from the appropriate directory under
- <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>.
- Toolchains are available for 32-bit and 64-bit x86 development
- systems from the <filename>i686</filename> and
- <filename>x86_64</filename> directories, respectively.
- The toolchains the Yocto Project provides are based off the
- <filename>core-image-sato</filename> image and contain
- libraries appropriate for developing against that image.
- Each type of development system supports five or more target
- architectures.
- </para>
+ <para>
+ The installed Standard SDK consists of several files and
+ directories.
+ Basically, it contains an SDK environment setup script, some
+ configuration files, and host and target root filesystems to
+ support usage.
+ You can see the directory structure in the
+ "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
+ section.
+ </para>
+ </section>
- <para>
- The names of the tarball installer scripts are such that a
- string representing the host system appears first in the
- filename and then is immediately followed by a string
- representing the target architecture.
- <literallayout class='monospaced'>
+ <section id='sdk-installing-the-sdk'>
+ <title>Installing the SDK</title>
+
+ <para>
+ The first thing you need to do is install the SDK on your host
+ development machine by running the <filename>*.sh</filename>
+ installation script.
+ </para>
+
+ <para>
+ You can download a tarball installer, which includes the
+ pre-built toolchain, the <filename>runqemu</filename>
+ script, and support files from the appropriate directory under
+ <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>.
+ Toolchains are available for 32-bit and 64-bit x86 development
+ systems from the <filename>i686</filename> and
+ <filename>x86_64</filename> directories, respectively.
+ The toolchains the Yocto Project provides are based off the
+ <filename>core-image-sato</filename> image and contain
+ libraries appropriate for developing against that image.
+ Each type of development system supports five or more target
+ architectures.
+ </para>
+
+ <para>
+ The names of the tarball installer scripts are such that a
+ string representing the host system appears first in the
+ filename and then is immediately followed by a string
+ representing the target architecture.
+ <literallayout class='monospaced'>
poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-<replaceable>release_version</replaceable>.sh
Where:
@@ -88,57 +96,58 @@
Yocto Project:
&DISTRO;, &DISTRO;+snapshot
- </literallayout>
- For example, the following toolchain installer is for a 64-bit
- development host system and a i586-tuned target architecture
- based off the SDK for <filename>core-image-sato</filename> and
- using the current &DISTRO; snapshot:
- <literallayout class='monospaced'>
+ </literallayout>
+ For example, the following toolchain installer is for a 64-bit
+ development host system and a i586-tuned target architecture
+ based off the SDK for <filename>core-image-sato</filename> and
+ using the current &DISTRO; snapshot:
+ <literallayout class='monospaced'>
poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
- </literallayout>
- <note>
- As an alternative to downloading an SDK, you can build the toolchain
- installer.
- For information on building the installer, see the
- "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
- section.
- Another helpful resource for building an installer is the
- <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
- wiki page.
- This wiki page focuses on development when using the Eclipse IDE.
- </note>
- </para>
+ </literallayout>
+ <note>
+ As an alternative to downloading an SDK, you can build the
+ toolchain installer.
+ For information on building the installer, see the
+ "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
+ section.
+ Another helpful resource for building an installer is the
+ <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
+ wiki page.
+ This wiki page focuses on development when using the Eclipse
+ IDE.
+ </note>
+ </para>
- <para>
- The SDK and toolchains are self-contained and by default are installed
- into <filename>/opt/poky</filename>.
- However, when you run the SDK installer, you can choose an
- installation directory.
- <note>
- You must change the permissions on the toolchain
- installer script so that it is executable:
- <literallayout class='monospaced'>
+ <para>
+ The SDK and toolchains are self-contained and by default are
+ installed into <filename>/opt/poky</filename>.
+ However, when you run the SDK installer, you can choose an
+ installation directory.
+ <note>
+ You must change the permissions on the toolchain
+ installer script so that it is executable:
+ <literallayout class='monospaced'>
$ chmod +x poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
- </literallayout>
- </note>
- </para>
+ </literallayout>
+ </note>
+ </para>
- <para>
- The following command shows how to run the installer given a
- toolchain tarball for a 64-bit x86 development host system and
- a 32-bit x86 target architecture.
- The example assumes the toolchain installer is located in
- <filename>~/Downloads/</filename>.
- <note>
- If you do not have write permissions for the directory
- into which you are installing the SDK, the installer
- notifies you and exits.
- Be sure you have write permissions in the directory and
- run the installer again.
- </note>
- <literallayout class='monospaced'>
+ <para>
+ The following command shows how to run the installer given a
+ toolchain tarball for a 64-bit x86 development host system and
+ a 32-bit x86 target architecture.
+ The example assumes the toolchain installer is located in
+ <filename>~/Downloads/</filename>.
+ <note>
+ If you do not have write permissions for the directory
+ into which you are installing the SDK, the installer
+ notifies you and exits.
+ Be sure you have write permissions in the directory and
+ run the installer again.
+ </note>
+ <literallayout class='monospaced'>
$ ./poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
- Poky (Yocto Project Reference Distro) SDK installer version 2.0
+ Poky (Yocto Project Reference Distro) SDK installer version &DISTRO;
===============================================================
Enter target directory for SDK (default: /opt/poky/&DISTRO;):
You are about to install the SDK to "/opt/poky/&DISTRO;". Proceed[Y/n]? Y
@@ -147,1337 +156,49 @@
SDK has been successfully set up and is ready to be used.
Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
$ . /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
- </literallayout>
- </para>
-
- <para>
- Again, reference the
- "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
- section for more details on the resulting directory structure of
- the installed SDK.
- </para>
-</section>
-
-<section id='sdk-running-the-sdk-environment-setup-script'>
- <title>Running the SDK Environment Setup Script</title>
-
- <para>
- Once you have the SDK installed, you must run the SDK environment
- setup script before you can actually use it.
- This setup script resides in the directory you chose when you installed
- the SDK.
- For information on where this setup script can reside, see the
- "<link linkend='sdk-appendix-obtain'>Obtaining the SDK</link>"
- Appendix.
- </para>
-
- <para>
- Before running the script, be sure it is the one that matches the
- architecture for which you are developing.
- Environment setup scripts begin with the string
- "<filename>environment-setup</filename>" and include as part of their
- name the tuned target architecture.
- For example, the command to source a setup script for an IA-based
- target machine using i586 tuning and located in the default SDK
- installation directory is as follows:
- <literallayout class='monospaced'>
- $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
- </literallayout>
- When you run the setup script, many environment variables are
- defined:
- <literallayout class='monospaced'>
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKTARGETSYSROOT'><filename>SDKTARGETSYSROOT</filename></ulink> - The path to the sysroot used for cross-compilation
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PKG_CONFIG_PATH'><filename>PKG_CONFIG_PATH</filename></ulink> - The path to the target pkg-config files
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_SITE'><filename>CONFIG_SITE</filename></ulink> - A GNU autoconf site file preconfigured for the target
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> - The minimal command and arguments to run the C compiler
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CXX'><filename>CXX</filename></ulink> - The minimal command and arguments to run the C++ compiler
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CPP'><filename>CPP</filename></ulink> - The minimal command and arguments to run the C preprocessor
- <ulink url='&YOCTO_DOCS_REF_URL;#var-AS'><filename>AS</filename></ulink> - The minimal command and arguments to run the assembler
- <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink> - The minimal command and arguments to run the linker
- <ulink url='&YOCTO_DOCS_REF_URL;#var-GDB'><filename>GDB</filename></ulink> - The minimal command and arguments to run the GNU Debugger
- <ulink url='&YOCTO_DOCS_REF_URL;#var-STRIP'><filename>STRIP</filename></ulink> - The minimal command and arguments to run 'strip', which strips symbols
- <ulink url='&YOCTO_DOCS_REF_URL;#var-RANLIB'><filename>RANLIB</filename></ulink> - The minimal command and arguments to run 'ranlib'
- <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJCOPY'><filename>OBJCOPY</filename></ulink> - The minimal command and arguments to run 'objcopy'
- <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJDUMP'><filename>OBJDUMP</filename></ulink> - The minimal command and arguments to run 'objdump'
- <ulink url='&YOCTO_DOCS_REF_URL;#var-AR'><filename>AR</filename></ulink> - The minimal command and arguments to run 'ar'
- <ulink url='&YOCTO_DOCS_REF_URL;#var-NM'><filename>NM</filename></ulink> - The minimal command and arguments to run 'nm'
- <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></ulink> - The toolchain binary prefix for the target tools
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CROSS_COMPILE'><filename>CROSS_COMPILE</filename></ulink> - The toolchain binary prefix for the target tools
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink> - The minimal arguments for GNU configure
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'><filename>CFLAGS</filename></ulink> - Suggested C flags
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'><filename>CXXFLAGS</filename></ulink> - Suggested C++ flags
- <ulink url='&YOCTO_DOCS_REF_URL;#var-LDFLAGS'><filename>LDFLAGS</filename></ulink> - Suggested linker flags when you use CC to link
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CPPFLAGS'><filename>CPPFLAGS</filename></ulink> - Suggested preprocessor flags
- </literallayout>
- </para>
-</section>
-
-<section id='autotools-based-projects'>
- <title>Autotools-Based Projects</title>
-
- <para>
- Once you have a suitable cross-toolchain installed, it is very easy to
- develop a project outside of the OpenEmbedded build system.
- This section presents a simple "Helloworld" example that shows how
- to set up, compile, and run the project.
- </para>
-
- <section id='creating-and-running-a-project-based-on-gnu-autotools'>
- <title>Creating and Running a Project Based on GNU Autotools</title>
-
- <para>
- Follow these steps to create a simple Autotools-based project:
- <orderedlist>
- <listitem><para><emphasis>Create your directory:</emphasis>
- Create a clean directory for your project and then make
- that directory your working location:
- <literallayout class='monospaced'>
- $ mkdir $HOME/helloworld
- $ cd $HOME/helloworld
- </literallayout></para></listitem>
- <listitem><para><emphasis>Populate the directory:</emphasis>
- Create <filename>hello.c</filename>, <filename>Makefile.am</filename>,
- and <filename>configure.ac</filename> files as follows:
- <itemizedlist>
- <listitem><para>For <filename>hello.c</filename>, include
- these lines:
- <literallayout class='monospaced'>
- #include &lt;stdio.h&gt;
-
- main()
- {
- printf("Hello World!\n");
- }
- </literallayout></para></listitem>
- <listitem><para>For <filename>Makefile.am</filename>,
- include these lines:
- <literallayout class='monospaced'>
- bin_PROGRAMS = hello
- hello_SOURCES = hello.c
- </literallayout></para></listitem>
- <listitem><para>For <filename>configure.in</filename>,
- include these lines:
- <literallayout class='monospaced'>
- AC_INIT(hello,0.1)
- AM_INIT_AUTOMAKE([foreign])
- AC_PROG_CC
- AC_PROG_INSTALL
- AC_OUTPUT(Makefile)
- </literallayout></para></listitem>
- </itemizedlist></para></listitem>
- <listitem><para><emphasis>Source the cross-toolchain
- environment setup file:</emphasis>
- As described earlier in the manual, installing the
- cross-toolchain creates a cross-toolchain
- environment setup script in the directory that the SDK
- was installed.
- Before you can use the tools to develop your project,
- you must source this setup script.
- The script begins with the string "environment-setup" and
- contains the machine architecture, which is followed by the
- string "poky-linux".
- Here is an example that sources a script from the
- default SDK installation directory that uses the
- 32-bit Intel x86 Architecture and the
- &DISTRO_NAME; Yocto Project release:
- <literallayout class='monospaced'>
- $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
- </literallayout></para></listitem>
- <listitem><para><emphasis>Generate the local aclocal.m4
- files and create the configure script:</emphasis>
- The following GNU Autotools generate the local
- <filename>aclocal.m4</filename> files and create the
- configure script:
- <literallayout class='monospaced'>
- $ aclocal
- $ autoconf
- </literallayout></para></listitem>
- <listitem><para><emphasis>Generate files needed by GNU
- coding standards:</emphasis>
- GNU coding standards require certain files in order for the
- project to be compliant.
- This command creates those files:
- <literallayout class='monospaced'>
- $ touch NEWS README AUTHORS ChangeLog
- </literallayout></para></listitem>
- <listitem><para><emphasis>Generate the configure
- file:</emphasis>
- This command generates the <filename>configure</filename>:
- <literallayout class='monospaced'>
- $ automake -a
- </literallayout></para></listitem>
- <listitem><para><emphasis>Cross-compile the project:</emphasis>
- This command compiles the project using the cross-compiler.
- The
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink>
- environment variable provides the minimal arguments for
- GNU configure:
- <literallayout class='monospaced'>
- $ ./configure ${CONFIGURE_FLAGS}
- </literallayout></para></listitem>
- <listitem><para><emphasis>Make and install the project:</emphasis>
- These two commands generate and install the project into the
- destination directory:
- <literallayout class='monospaced'>
- $ make
- $ make install DESTDIR=./tmp
- </literallayout></para></listitem>
- <listitem><para><emphasis>Verify the installation:</emphasis>
- This command is a simple way to verify the installation
- of your project.
- Running the command prints the architecture on which
- the binary file can run.
- This architecture should be the same architecture that
- the installed cross-toolchain supports.
- <literallayout class='monospaced'>
- $ file ./tmp/usr/local/bin/hello
- </literallayout></para></listitem>
- <listitem><para><emphasis>Execute your project:</emphasis>
- To execute the project in the shell, simply enter the name.
- You could also copy the binary to the actual target hardware
- and run the project there as well:
- <literallayout class='monospaced'>
- $ ./hello
- </literallayout>
- As expected, the project displays the "Hello World!" message.
- </para></listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id='passing-host-options'>
- <title>Passing Host Options</title>
-
- <para>
- For an Autotools-based project, you can use the cross-toolchain by just
- passing the appropriate host option to <filename>configure.sh</filename>.
- The host option you use is derived from the name of the environment setup
- script found in the directory in which you installed the cross-toolchain.
- For example, the host option for an ARM-based target that uses the GNU EABI
- is <filename>armv5te-poky-linux-gnueabi</filename>.
- You will notice that the name of the script is
- <filename>environment-setup-armv5te-poky-linux-gnueabi</filename>.
- Thus, the following command works to update your project and
- rebuild it using the appropriate cross-toolchain tools:
- <literallayout class='monospaced'>
- $ ./configure --host=armv5te-poky-linux-gnueabi \
- --with-libtool-sysroot=<replaceable>sysroot_dir</replaceable>
</literallayout>
- <note>
- If the <filename>configure</filename> script results in problems recognizing the
- <filename>--with-libtool-sysroot=</filename><replaceable>sysroot-dir</replaceable> option,
- regenerate the script to enable the support by doing the following and then
- run the script again:
- <literallayout class='monospaced'>
- $ libtoolize --automake
- $ aclocal -I ${OECORE_TARGET_SYSROOT}/usr/share/aclocal \
- [-I <replaceable>dir_containing_your_project-specific_m4_macros</replaceable>]
- $ autoconf
- $ autoheader
- $ automake -a
- </literallayout>
- </note>
</para>
- </section>
-</section>
-
-<section id='makefile-based-projects'>
- <title>Makefile-Based Projects</title>
-
- <para>
- For Makefile-based projects, the cross-toolchain environment variables
- established by running the cross-toolchain environment setup script
- are subject to general <filename>make</filename> rules.
- </para>
-
- <para>
- To illustrate this, consider the following four cross-toolchain
- environment variables:
- <literallayout class='monospaced'>
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'>CC</ulink>=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/&DISTRO;/sysroots/i586-poky-linux
- <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'>LD</ulink>=i586-poky-linux-ld --sysroot=/opt/poky/&DISTRO;/sysroots/i586-poky-linux
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'>CXXFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types
- </literallayout>
- Now, consider the following three cases:
- <itemizedlist>
- <listitem><para><emphasis>Case 1 - No Variables Set in the <filename>Makefile</filename>:</emphasis>
- Because these variables are not specifically set in the
- <filename>Makefile</filename>, the variables retain their
- values based on the environment.
- </para></listitem>
- <listitem><para><emphasis>Case 2 - Variables Set in the <filename>Makefile</filename>:</emphasis>
- Specifically setting variables in the
- <filename>Makefile</filename> during the build results in the
- environment settings of the variables being overwritten.
- </para></listitem>
- <listitem><para><emphasis>Case 3 - Variables Set when the <filename>Makefile</filename> is Executed from the Command Line:</emphasis>
- Executing the <filename>Makefile</filename> from the command
- line results in the variables being overwritten with
- command-line content regardless of what is being set in the
- <filename>Makefile</filename>.
- In this case, environment variables are not considered unless
- you use the "-e" flag during the build:
- <literallayout class='monospaced'>
- $ make -e <replaceable>file</replaceable>
- </literallayout>
- If you use this flag, then the environment values of the
- variables override any variables specifically set in the
- <filename>Makefile</filename>.
- </para></listitem>
- </itemizedlist>
- <note>
- For the list of variables set up by the cross-toolchain environment
- setup script, see the
- "<link linkend='sdk-running-the-sdk-environment-setup-script'>Running the SDK Environment Setup Script</link>"
- section.
- </note>
- </para>
-</section>
-
-<section id='sdk-developing-applications-using-eclipse'>
- <title>Developing Applications Using <trademark class='trade'>Eclipse</trademark></title>
-
- <para>
- If you are familiar with the popular Eclipse IDE, you can use an
- Eclipse Yocto Plug-in to allow you to develop, deploy, and test your
- application all from within Eclipse.
- This section describes general workflow using the SDK and Eclipse
- and how to configure and set up Eclipse.
- </para>
-
- <section id='workflow-using-eclipse'>
-
- <title>Workflow Using <trademark class='trade'>Eclipse</trademark></title>
<para>
- The following figure and supporting list summarize the application
- development general workflow that employs both the SDK Eclipse.
- </para>
-
- <para>
- <imagedata fileref="figures/sdk-eclipse-dev-flow.png"
- width="7in" depth="7in" align="center" scale="100" />
- </para>
-
- <para>
- <orderedlist>
- <listitem><para><emphasis>Prepare the host system for the Yocto Project</emphasis>:
- See
- "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
- and
- "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" sections both
- in the Yocto Project Reference Manual for requirements.
- In particular, be sure your host system has the
- <filename>xterm</filename> package installed.
- </para></listitem>
- <listitem><para><emphasis>Secure the Yocto Project kernel target image</emphasis>:
- You must have a target kernel image that has been built using the OpenEmbedded
- build system.</para>
- <para>Depending on whether the Yocto Project has a pre-built image that matches your target
- architecture and where you are going to run the image while you develop your application
- (QEMU or real hardware), the area from which you get the image differs.
- <itemizedlist>
- <listitem><para>Download the image from
- <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink>
- if your target architecture is supported and you are going to develop
- and test your application on actual hardware.</para></listitem>
- <listitem><para>Download the image from
- <ulink url='&YOCTO_QEMU_DL_URL;'>
- <filename>machines/qemu</filename></ulink> if your target architecture is supported
- and you are going to develop and test your application using the QEMU
- emulator.</para></listitem>
- <listitem><para>Build your image if you cannot find a pre-built image that matches
- your target architecture.
- If your target architecture is similar to a supported architecture, you can
- modify the kernel image before you build it.
- See the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>"
- section in the Yocto Project Development
- manual for an example.
- </para></listitem>
- </itemizedlist>
- </para></listitem>
- <listitem><para><emphasis>Install the SDK</emphasis>:
- The SDK provides a target-specific cross-development toolchain, the root filesystem,
- the QEMU emulator, and other tools that can help you develop your application.
- For information on how to install the SDK, see the
- "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
- section.
- </para></listitem>
- <listitem><para><emphasis>
- Secure the target root filesystem
- and the Cross-development toolchain</emphasis>:
- You need to find and download the appropriate root
- filesystem and the cross-development toolchain.</para>
- <para>You can find the tarballs for the root filesystem in
- the same area used for the kernel image.
- Depending on the type of image you are running, the root
- filesystem you need differs.
- For example, if you are developing an application that
- runs on an image that supports Sato, you need to get a
- root filesystem that supports Sato.</para>
- <para>You can find the cross-development toolchains at
- <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'><filename>toolchains</filename></ulink>.
- Be sure to get the correct toolchain for your development host and your
- target architecture.
- See the "<link linkend='sdk-locating-pre-built-sdk-installers'>Locating Pre-Built SDK Installers</link>"
- section for information and the
- "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
- section for installation information.
- <note>
- As an alternative to downloading an SDK, you can build
- the toolchain installer.
- For information on building the installer, see the
- "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
- section.
- Another helpful resource for building an installer is
- the
- <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
- wiki page.
- </note>
- </para></listitem>
- <listitem><para><emphasis>Create and build your application</emphasis>:
- At this point, you need to have source files for your application.
- Once you have the files, you can use the Eclipse IDE to import them and build the
- project.
- If you are not using Eclipse, you need to use the cross-development tools you have
- installed to create the image.</para></listitem>
- <listitem><para>
- <emphasis>Deploy the image with the application</emphasis>:
- Using the Eclipse IDE, you can deploy your image to the
- hardware or to QEMU through the project's preferences.
- You can also use Eclipse to load and test your image under
- QEMU.
- See the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
- chapter in the Yocto Project Development Manual
- for information on using QEMU.
- </para></listitem>
- <listitem><para><emphasis>Test and debug the application</emphasis>:
- Once your application is deployed, you need to test it.
- Within the Eclipse IDE, you can use the debugging
- environment along with supported performance enhancing
- <ulink url='http://www.eclipse.org/linuxtools/'>Linux Tools</ulink>.
- </para></listitem>
- </orderedlist>
+ Again, reference the
+ "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
+ section for more details on the resulting directory structure of
+ the installed SDK.
</para>
</section>
- <section id='adt-eclipse'>
- <title>Working Within Eclipse</title>
+ <section id='sdk-running-the-sdk-environment-setup-script'>
+ <title>Running the SDK Environment Setup Script</title>
<para>
- The Eclipse IDE is a popular development environment and it fully
- supports development using the Yocto Project.
+ Once you have the SDK installed, you must run the SDK environment
+ setup script before you can actually use it.
+ This setup script resides in the directory you chose when you
+ installed the SDK.
+ For information on where this setup script can reside, see the
+ "<link linkend='sdk-appendix-obtain'>Obtaining the SDK</link>"
+ Appendix.
</para>
<para>
- When you install and configure the Eclipse Yocto Project Plug-in
- into the Eclipse IDE, you maximize your Yocto Project experience.
- Installing and configuring the Plug-in results in an environment
- that has extensions specifically designed to let you more easily
- develop software.
- These extensions allow for cross-compilation, deployment, and
- execution of your output into a QEMU emulation session as well as
- actual target hardware.
- You can also perform cross-debugging and profiling.
- The environment also supports performance enhancing
- <ulink url='http://www.eclipse.org/linuxtools/'>tools</ulink> that
- allow you to perform remote profiling, tracing, collection of
- power data, collection of latency data, and collection of
- performance data.
- <note>
- This release of the Yocto Project supports both the Neon
- and Mars versions of the Eclipse IDE.
- This section provides information on how to use the Neon
- release with the Yocto Project.
- For information on how to use the Mars version of Eclipse
- with the Yocto Project, see
- "<link linkend='sdk-appendix-mars'>Appendix C</link>.
- </note>
+ Before running the script, be sure it is the one that matches the
+ architecture for which you are developing.
+ Environment setup scripts begin with the string
+ "<filename>environment-setup</filename>" and include as part of
+ their name the tuned target architecture.
+ For example, the command to source a setup script for an IA-based
+ target machine using i586 tuning and located in the default SDK
+ installation directory is as follows:
+ <literallayout class='monospaced'>
+ $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
+ </literallayout>
+ When you run the setup script, the same environment variables are
+ defined as are when you run the setup script for an extensible SDK.
+ See the
+ "<link linkend='sdk-running-the-extensible-sdk-environment-setup-script'>Running the Extensible SDK Environment Setup Script</link>"
+ section for more information.
</para>
-
- <section id='neon-setting-up-the-eclipse-ide'>
- <title>Setting Up the Neon Version of the Eclipse IDE</title>
-
- <para>
- To develop within the Eclipse IDE, you need to do the following:
- <orderedlist>
- <listitem><para>Install the Neon version of the Eclipse
- IDE.</para></listitem>
- <listitem><para>Configure the Eclipse IDE.
- </para></listitem>
- <listitem><para>Install the Eclipse Yocto Plug-in.
- </para></listitem>
- <listitem><para>Configure the Eclipse Yocto Plug-in.
- </para></listitem>
- </orderedlist>
- <note>
- Do not install Eclipse from your distribution's package
- repository.
- Be sure to install Eclipse from the official Eclipse
- download site as directed in the next section.
- </note>
- </para>
-
- <section id='neon-installing-eclipse-ide'>
- <title>Installing the Neon Eclipse IDE</title>
-
- <para>
- Follow these steps to locate, install, and configure
- Neon Eclipse:
- <orderedlist>
- <listitem><para>
- <emphasis>Locate the Neon Download:</emphasis>
- Open a browser and go to
- <ulink url='http://www.eclipse.org/mars/'>http://www.eclipse.org/neon/</ulink>.
- </para></listitem>
- <listitem><para>
- <emphasis>Download the Tarball:</emphasis>
- Click through the "Download" buttons to
- download the file.
- </para></listitem>
- <listitem><para>
- <emphasis>Unpack the Tarball:</emphasis>
- Move to a clean directory and unpack the tarball.
- Here is an example:
- <literallayout class='monospaced'>
- $ cd ~
- $ tar -xzvf ~/Downloads/eclipse-inst-linux64.tar.gz
- </literallayout>
- Everything unpacks into a folder named
- "eclipse-installer".
- </para></listitem>
- <listitem><para>
- <emphasis>Launch the Installer:</emphasis>
- Use the following commands to launch the installer:
- <literallayout class='monospaced'>
- $ cd ~/eclipse-installer
- $ ./eclipse-inst
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Select Your IDE:</emphasis>
- From the list, select the "Eclipse IDE for
- C/C++ Developers".
- </para></listitem>
- <listitem><para>
- <emphasis>Install the Software:</emphasis>
- Accept the default "cpp-neon" directory and click
- "Install".
- Accept any license agreements and approve any
- certificates.
- </para></listitem>
- <listitem><para>
- <emphasis>Launch Neon:</emphasis>
- Click the "Launch" button and accept the default
- "workspace".
- </para></listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id='neon-configuring-the-mars-eclipse-ide'>
- <title>Configuring the Neon Eclipse IDE</title>
-
- <para>
- Follow these steps to configure the Neon Eclipse IDE.
- <note>
- Depending on how you installed Eclipse and what you have
- already done, some of the options will not appear.
- If you cannot find an option as directed by the manual,
- it has already been installed.
- </note>
- <orderedlist>
- <listitem><para>Be sure Eclipse is running and
- you are in your workbench.
- </para></listitem>
- <listitem><para>Select "Install New Software" from
- the "Help" pull-down menu.
- </para></listitem>
- <listitem><para>Select
- "Neon - http://download.eclipse.org/releases/neon"
- from the "Work with:" pull-down menu.
- </para></listitem>
- <listitem><para>Expand the box next to
- "Linux Tools" and select the following:
- <literallayout class='monospaced'>
- C/C++ Remote (Over TCF/TE) Run/Debug Launcher
- TM Terminal
- </literallayout>
- </para></listitem>
- <listitem><para>Expand the box next to "Mobile and
- Device Development" and select the following
- boxes:
- <literallayout class='monospaced'>
- C/C++ Remote (Over TCF/TE) Run/Debug Launcher
- Remote System Explorer User Actions
- TM Terminal
- TCF Remote System Explorer add-in
- TCF Target Explorer
- </literallayout>
- </para></listitem>
- <listitem><para>Expand the box next to
- "Programming Languages" and select the
- following box:
- <literallayout class='monospaced'>
- C/C++ Development Tools SDK
- </literallayout>
- </para></listitem>
- <listitem><para>
- Complete the installation by clicking through
- appropriate "Next" and "Finish" buttons.
- </para></listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id='neon-installing-the-eclipse-yocto-plug-in'>
- <title>Installing or Accessing the Neon Eclipse Yocto Plug-in</title>
-
- <para>
- You can install the Eclipse Yocto Plug-in into the Eclipse
- IDE one of two ways: use the Yocto Project's Eclipse
- Update site to install the pre-built plug-in or build and
- install the plug-in from the latest source code.
- </para>
-
- <section id='neon-new-software'>
- <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title>
-
- <para>
- To install the Neon Eclipse Yocto Plug-in from the
- update site, follow these steps:
- <orderedlist>
- <listitem><para>Start up the Eclipse IDE.
- </para></listitem>
- <listitem><para>In Eclipse, select "Install New
- Software" from the "Help" menu.
- </para></listitem>
- <listitem><para>Click "Add..." in the "Work with:"
- area.
- </para></listitem>
- <listitem><para>Enter
- <filename>&ECLIPSE_DL_PLUGIN_URL;/neon</filename>
- in the URL field and provide a meaningful name
- in the "Name" field.
- </para></listitem>
- <listitem><para>Click "OK" to have the entry added
- to the "Work with:" drop-down list.
- </para></listitem>
- <listitem><para>Select the entry for the plug-in
- from the "Work with:" drop-down list.
- </para></listitem>
- <listitem><para>Check the boxes next to the following:
- <literallayout class='monospaced'>
- Yocto Project SDK Plug-in
- Yocto Project Documentation plug-in
- </literallayout>
- </para></listitem>
- <listitem><para>Complete the remaining software
- installation steps and then restart the Eclipse
- IDE to finish the installation of the plug-in.
- <note>
- You can click "OK" when prompted about
- installing software that contains unsigned
- content.
- </note>
- </para></listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id='neon-zip-file-method'>
- <title>Installing the Plug-in Using the Latest Source Code</title>
-
- <para>
- To install the Neon Eclipse Yocto Plug-in from the
- latest source code, follow these steps:
- <orderedlist>
- <listitem><para>Be sure your development system
- has JDK 1.8+
- </para></listitem>
- <listitem><para>install X11-related packages:
- <literallayout class='monospaced'>
- $ sudo apt-get install xauth
- </literallayout>
- </para></listitem>
- <listitem><para>In a new terminal shell, create a
- Git repository with:
- <literallayout class='monospaced'>
- $ cd ~
- $ git clone git://git.yoctoproject.org/eclipse-poky
- </literallayout>
- </para></listitem>
- <listitem><para>Use Git to create the correct
- tag:
- <literallayout class='monospaced'>
- $ cd ~/eclipse-poky
- $ git checkout neon/yocto-&DISTRO;
- </literallayout>
- This creates a local tag named
- <filename>neon/yocto-&DISTRO;</filename>
- based on the branch
- <filename>origin/neon-master</filename>.
- You are put into a detached HEAD state, which
- is fine since you are only going to be building
- and not developing.
- </para></listitem>
- <listitem><para>Change to the
- <filename>scripts</filename>
- directory within the Git repository:
- <literallayout class='monospaced'>
- $ cd scripts
- </literallayout>
- </para></listitem>
- <listitem><para>Set up the local build environment
- by running the setup script:
- <literallayout class='monospaced'>
- $ ./setup.sh
- </literallayout>
- When the script finishes execution,
- it prompts you with instructions on how to run
- the <filename>build.sh</filename> script, which
- is also in the <filename>scripts</filename>
- directory of the Git repository created
- earlier.
- </para></listitem>
- <listitem><para>
- Run the <filename>build.sh</filename>
- script as directed.
- Be sure to provide the tag name, documentation
- branch, and a release name.</para>
- <para>
- Following is an example:
- <literallayout class='monospaced'>
- $ ECLIPSE_HOME=/home/scottrif/eclipse-poky/scripts/eclipse ./build.sh -l neon/yocto-&DISTRO; master yocto-&DISTRO; 2>&amp;1 | tee build.log
- </literallayout>
- The previous example command adds the tag you
- need for
- <filename>mars/yocto-&DISTRO;</filename>
- to <filename>HEAD</filename>, then tells the
- build script to use the local (-l) Git checkout
- for the build.
- After running the script, the file
- <filename>org.yocto.sdk-</filename><replaceable>release</replaceable><filename>-</filename><replaceable>date</replaceable><filename>-archive.zip</filename>
- is in the current directory.
- </para></listitem>
- <listitem><para>If necessary, start the Eclipse IDE
- and be sure you are in the Workbench.
- </para></listitem>
- <listitem><para>Select "Install New Software" from
- the "Help" pull-down menu.
- </para></listitem>
- <listitem><para>Click "Add".
- </para></listitem>
- <listitem><para>Provide anything you want in the
- "Name" field.
- </para></listitem>
- <listitem><para>Click "Archive" and browse to the
- ZIP file you built earlier.
- This ZIP file should not be "unzipped", and must
- be the <filename>*archive.zip</filename> file
- created by running the
- <filename>build.sh</filename> script.
- </para></listitem>
- <listitem><para>Click the "OK" button.
- </para></listitem>
- <listitem><para>Check the boxes that appear in
- the installation window to install the
- following:
- <literallayout class='monospaced'>
- Yocto Project SDK Plug-in
- Yocto Project Documentation plug-in
- </literallayout>
- </para></listitem>
- <listitem><para>Finish the installation by clicking
- through the appropriate buttons.
- You can click "OK" when prompted about
- installing software that contains unsigned
- content.
- </para></listitem>
- <listitem><para>Restart the Eclipse IDE if
- necessary.
- </para></listitem>
- </orderedlist>
- </para>
-
- <para>
- At this point you should be able to configure the
- Eclipse Yocto Plug-in as described in the
- "<link linkend='mars-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>"
- section.
- </para>
- </section>
- </section>
-
- <section id='neon-configuring-the-eclipse-yocto-plug-in'>
- <title>Configuring the Neon Eclipse Yocto Plug-in</title>
-
- <para>
- Configuring the Neon Eclipse Yocto Plug-in involves
- setting the Cross Compiler options and the Target options.
- The configurations you choose become the default settings
- for all projects.
- You do have opportunities to change them later when
- you configure the project (see the following section).
- </para>
-
- <para>
- To start, you need to do the following from within the
- Eclipse IDE:
- <itemizedlist>
- <listitem><para>Choose "Preferences" from the
- "Window" menu to display the Preferences Dialog.
- </para></listitem>
- <listitem><para>Click "Yocto Project SDK" to display
- the configuration screen.
- </para></listitem>
- </itemizedlist>
- The following sub-sections describe how to configure the
- the plug-in.
- <note>
- Throughout the descriptions, a start-to-finish example for
- preparing a QEMU image for use with Eclipse is referenced
- as the "wiki" and is linked to the example on the
- <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'> Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
- wiki page.
- </note>
- </para>
-
- <section id='neon-configuring-the-cross-compiler-options'>
- <title>Configuring the Cross-Compiler Options</title>
-
- <para>
- Cross Compiler options enable Eclipse to use your specific
- cross compiler toolchain.
- To configure these options, you must select
- the type of toolchain, point to the toolchain, specify
- the sysroot location, and select the target
- architecture.
- <itemizedlist>
- <listitem><para><emphasis>Selecting the Toolchain Type:</emphasis>
- Choose between
- <filename>Standalone pre-built toolchain</filename>
- and
- <filename>Build system derived toolchain</filename>
- for Cross Compiler Options.
- <itemizedlist>
- <listitem><para><emphasis>
- <filename>Standalone Pre-built Toolchain:</filename></emphasis>
- Select this type when you are using
- a stand-alone cross-toolchain.
- For example, suppose you are an
- application developer and do not
- need to build a target image.
- Instead, you just want to use an
- architecture-specific toolchain on
- an existing kernel and target root
- filesystem.
- In other words, you have downloaded
- and installed a pre-built toolchain
- for an existing image.
- </para></listitem>
- <listitem><para><emphasis>
- <filename>Build System Derived Toolchain:</filename></emphasis>
- Select this type if you built the
- toolchain as part of the
- <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
- When you select
- <filename>Build system derived toolchain</filename>,
- you are using the toolchain built and
- bundled inside the Build Directory.
- For example, suppose you created a
- suitable image using the steps in the
- <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
- In this situation, you would select the
- <filename>Build system derived toolchain</filename>.
- </para></listitem>
- </itemizedlist>
- </para></listitem>
- <listitem><para><emphasis>Specify the Toolchain Root Location:</emphasis>
- If you are using a stand-alone pre-built
- toolchain, you should be pointing to where it is
- installed (e.g.
- <filename>/opt/poky/&DISTRO;</filename>).
- See the
- "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
- section for information about how the SDK is
- installed.</para>
- <para>If you are using a build system derived
- toolchain, the path you provide for the
- <filename>Toolchain Root Location</filename>
- field is the
- <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
- from which you run the
- <filename>bitbake</filename> command (e.g
- <filename>/home/scottrif/poky/build</filename>).</para>
- <para>For more information, see the
- "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
- section.
- </para></listitem>
- <listitem><para><emphasis>Specify Sysroot Location:</emphasis>
- This location is where the root filesystem for
- the target hardware resides.
- </para>
- <para>This location depends on where you
- separately extracted and installed the target
- filesystem.
- As an example, suppose you prepared an image
- using the steps in the
- <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
- If so, the <filename>MY_QEMU_ROOTFS</filename>
- directory is found in the
- <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
- and you would browse to and select that directory
- (e.g. <filename>/home/scottrif/poky/build/MY_QEMU_ROOTFS</filename>).
- </para>
- <para>For more information on how to install the
- toolchain and on how to extract and install the
- sysroot filesystem, see the
- "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
- section.
- </para></listitem>
- <listitem><para><emphasis>Select the Target Architecture:</emphasis>
- The target architecture is the type of hardware
- you are going to use or emulate.
- Use the pull-down
- <filename>Target Architecture</filename> menu
- to make your selection.
- The pull-down menu should have the supported
- architectures.
- If the architecture you need is not listed in
- the menu, you will need to build the image.
- See the
- "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
- section of the Yocto Project Quick Start for
- more information.
- You can also see the
- <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id='neon-configuring-the-target-options'>
- <title>Configuring the Target Options</title>
-
- <para>
- You can choose to emulate hardware using the QEMU
- emulator, or you can choose to run your image on actual
- hardware.
- <itemizedlist>
- <listitem><para><emphasis>QEMU:</emphasis>
- Select this option if you will be using the
- QEMU emulator.
- If you are using the emulator, you also need to
- locate the kernel and specify any custom
- options.</para>
- <para>If you selected the
- <filename>Build system derived toolchain</filename>,
- the target kernel you built will be located in
- the
- <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
- in
- <filename>tmp/deploy/images/<replaceable>machine</replaceable></filename>
- directory.
- As an example, suppose you performed the steps in
- the
- <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
- In this case, you specify your Build Directory path
- followed by the image (e.g.
- <filename>/home/scottrif/poky/build/tmp/deploy/images/qemux86/bzImage-qemux86.bin</filename>).
- </para>
- <para>If you selected the standalone pre-built
- toolchain, the pre-built image you downloaded is
- located in the directory you specified when you
- downloaded the image.</para>
- <para>Most custom options are for advanced QEMU
- users to further customize their QEMU instance.
- These options are specified between paired
- angled brackets.
- Some options must be specified outside the
- brackets.
- In particular, the options
- <filename>serial</filename>,
- <filename>nographic</filename>, and
- <filename>kvm</filename> must all be outside the
- brackets.
- Use the <filename>man qemu</filename> command
- to get help on all the options and their use.
- The following is an example:
- <literallayout class='monospaced'>
- serial ‘&lt;-m 256 -full-screen&gt;’
- </literallayout></para>
- <para>
- Regardless of the mode, Sysroot is already
- defined as part of the Cross-Compiler Options
- configuration in the
- <filename>Sysroot Location:</filename> field.
- </para></listitem>
- <listitem><para><emphasis>External HW:</emphasis>
- Select this option if you will be using actual
- hardware.</para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- Click the "Apply" and "OK" to save your plug-in
- configurations.
- </para>
- </section>
- </section>
- </section>
-
- <section id='neon-creating-the-project'>
- <title>Creating the Project</title>
-
- <para>
- You can create two types of projects: Autotools-based, or
- Makefile-based.
- This section describes how to create Autotools-based projects
- from within the Eclipse IDE.
- For information on creating Makefile-based projects in a
- terminal window, see the
- "<link linkend='makefile-based-projects'>Makefile-Based Projects</link>"
- section.
- <note>
- Do not use special characters in project names
- (e.g. spaces, underscores, etc.). Doing so can
- cause configuration to fail.
- </note>
- </para>
-
- <para>
- To create a project based on a Yocto template and then display
- the source code, follow these steps:
- <orderedlist>
- <listitem><para>Select "C Project" from the "File -> New" menu.
- </para></listitem>
- <listitem><para>Expand <filename>Yocto Project SDK Autotools Project</filename>.
- </para></listitem>
- <listitem><para>Select <filename>Hello World ANSI C Autotools Projects</filename>.
- This is an Autotools-based project based on a Yocto
- template.
- </para></listitem>
- <listitem><para>Put a name in the <filename>Project name:</filename>
- field.
- Do not use hyphens as part of the name
- (e.g. <filename>hello</filename>).
- </para></listitem>
- <listitem><para>Click "Next".
- </para></listitem>
- <listitem><para>Add appropriate information in the various
- fields.
- </para></listitem>
- <listitem><para>Click "Finish".
- </para></listitem>
- <listitem><para>If the "open perspective" prompt appears,
- click "Yes" so that you in the C/C++ perspective.
- </para></listitem>
- <listitem><para>The left-hand navigation pane shows your
- project.
- You can display your source by double clicking the
- project's source file.
- </para></listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id='neon-configuring-the-cross-toolchains'>
- <title>Configuring the Cross-Toolchains</title>
-
- <para>
- The earlier section,
- "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>",
- sets up the default project configurations.
- You can override these settings for a given project by following
- these steps:
- <orderedlist>
- <listitem><para>Select "Yocto Project Settings" from
- the "Project -> Properties" menu.
- This selection brings up the Yocto Project Settings
- Dialog and allows you to make changes specific to an
- individual project.</para>
- <para>By default, the Cross Compiler Options and Target
- Options for a project are inherited from settings you
- provided using the Preferences Dialog as described
- earlier in the
- "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>" section.
- The Yocto Project Settings Dialog allows you to override
- those default settings for a given project.
- </para></listitem>
- <listitem><para>Make or verify your configurations for the
- project and click "OK".
- </para></listitem>
- <listitem><para>Right-click in the navigation pane and
- select "Reconfigure Project" from the pop-up menu.
- This selection reconfigures the project by running
- <filename>autogen.sh</filename> in the workspace for
- your project.
- The script also runs <filename>libtoolize</filename>,
- <filename>aclocal</filename>,
- <filename>autoconf</filename>,
- <filename>autoheader</filename>,
- <filename>automake --a</filename>, and
- <filename>./configure</filename>.
- Click on the "Console" tab beneath your source code to
- see the results of reconfiguring your project.
- </para></listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id='neon-building-the-project'>
- <title>Building the Project</title>
-
- <para>
- To build the project select "Build All" from the
- "Project" menu.
- The console should update and you can note the cross-compiler
- you are using.
- <note>
- When building "Yocto Project SDK Autotools" projects, the
- Eclipse IDE might display error messages for
- Functions/Symbols/Types that cannot be "resolved", even when
- the related include file is listed at the project navigator and
- when the project is able to build.
- For these cases only, it is recommended to add a new linked
- folder to the appropriate sysroot.
- Use these steps to add the linked folder:
- <orderedlist>
- <listitem><para>
- Select the project.
- </para></listitem>
- <listitem><para>
- Select "Folder" from the
- <filename>File > New</filename> menu.
- </para></listitem>
- <listitem><para>
- In the "New Folder" Dialog, select "Link to alternate
- location (linked folder)".
- </para></listitem>
- <listitem><para>
- Click "Browse" to navigate to the include folder inside
- the same sysroot location selected in the Yocto Project
- configuration preferences.
- </para></listitem>
- <listitem><para>
- Click "OK".
- </para></listitem>
- <listitem><para>
- Click "Finish" to save the linked folder.
- </para></listitem>
- </orderedlist>
- </note>
- </para>
- </section>
-
- <section id='neon-starting-qemu-in-user-space-nfs-mode'>
- <title>Starting QEMU in User-Space NFS Mode</title>
-
- <para>
- To start the QEMU emulator from within Eclipse, follow these
- steps:
- <note>
- See the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
- chapter in the Yocto Project Development Manual
- for more information on using QEMU.
- </note>
- <orderedlist>
- <listitem><para>Expose and select "External Tools
- Configurations ..." from the "Run -> External Tools" menu.
- </para></listitem>
- <listitem><para>
- Locate and select your image in the navigation panel to
- the left (e.g. <filename>qemu_i586-poky-linux</filename>).
- </para></listitem>
- <listitem><para>
- Click "Run" to launch QEMU.
- <note>
- The host on which you are running QEMU must have
- the <filename>rpcbind</filename> utility running to be
- able to make RPC calls on a server on that machine.
- If QEMU does not invoke and you receive error messages
- involving <filename>rpcbind</filename>, follow the
- suggestions to get the service running.
- As an example, on a new Ubuntu 16.04 LTS installation,
- you must do the following in order to get QEMU to
- launch:
- <literallayout class='monospaced'>
- $ sudo apt-get install rpcbind
- </literallayout>
- After installing <filename>rpcbind</filename>, you
- need to edit the
- <filename>/etc/init.d/rpcbind</filename> file to
- include the following line:
- <literallayout class='monospaced'>
- OPTIONS="-i -w"
- </literallayout>
- After modifying the file, you need to start the
- service:
- <literallayout class='monospaced'>
- $ sudo service portmap restart
- </literallayout>
- </note>
- </para></listitem>
- <listitem><para>If needed, enter your host root password in
- the shell window at the prompt.
- This sets up a <filename>Tap 0</filename> connection
- needed for running in user-space NFS mode.
- </para></listitem>
- <listitem><para>Wait for QEMU to launch.
- </para></listitem>
- <listitem><para>Once QEMU launches, you can begin operating
- within that environment.
- One useful task at this point would be to determine the
- IP Address for the user-space NFS by using the
- <filename>ifconfig</filename> command.
- The IP address of the QEMU machine appears in the
- xterm window.
- You can use this address to help you see which particular
- IP address the instance of QEMU is using.
- </para></listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id='neon-deploying-and-debugging-the-application'>
- <title>Deploying and Debugging the Application</title>
-
- <para>
- Once the QEMU emulator is running the image, you can deploy
- your application using the Eclipse IDE and then use
- the emulator to perform debugging.
- Follow these steps to deploy the application.
- <note>
- Currently, Eclipse does not support SSH port forwarding.
- Consequently, if you need to run or debug a remote
- application using the host display, you must create a
- tunneling connection from outside Eclipse and keep
- that connection alive during your work.
- For example, in a new terminal, run the following:
- <literallayout class='monospaced'>
- $ ssh -XY <replaceable>user_name</replaceable>@<replaceable>remote_host_ip</replaceable>
- </literallayout>
- Using the above form, here is an example:
- <literallayout class='monospaced'>
- $ ssh -XY root@192.168.7.2
- </literallayout>
- After running the command, add the command to be executed
- in Eclipse's run configuration before the application
- as follows:
- <literallayout class='monospaced'>
- export DISPLAY=:10.0
- </literallayout>
- Be sure to not destroy the connection during your QEMU
- session (i.e. do not
- exit out of or close that shell).
- </note>
- <orderedlist>
- <listitem><para>Select "Debug Configurations..." from the
- "Run" menu.</para></listitem>
- <listitem><para>In the left area, expand
- <filename>C/C++Remote Application</filename>.
- </para></listitem>
- <listitem><para>Locate your project and select it to bring
- up a new tabbed view in the Debug Configurations Dialog.
- </para></listitem>
- <listitem><para>Click on the "Debugger" tab to see the
- cross-tool debugger you are using.
- Be sure to change to the debugger perspective in Eclipse.
- </para></listitem>
- <listitem><para>Click on the "Main" tab.
- </para></listitem>
- <listitem><para>Create a new connection to the QEMU instance
- by clicking on "new".</para></listitem>
- <listitem><para>Select <filename>SSH</filename>, which means
- Secure Socket Shell and then click "OK".
- Optionally, you can select an TCF connection instead.
- </para></listitem>
- <listitem><para>Clear out the "Connection name" field and
- enter any name you want for the connection.
- </para></listitem>
- <listitem><para>Put the IP address for the connection in
- the "Host" field.
- For QEMU, the default is <filename>192.168.7.2</filename>.
- However, if a previous QEMU session did not exit
- cleanly, the IP address increments (e.g.
- <filename>192.168.7.3</filename>).
- <note>
- You can find the IP address for the current QEMU
- session by looking in the xterm that opens when
- you launch QEMU.
- </note>
- </para></listitem>
- <listitem><para>Enter <filename>root</filename>, which
- is the default for QEMU, for the "User" field.
- Be sure to leave the password field empty.
- </para></listitem>
- <listitem><para>Click "Finish" to close the
- New Connections Dialog.
- </para></listitem>
- <listitem><para>If necessary, use the drop-down menu now in the
- "Connection" field and pick the IP Address you entered.
- </para></listitem>
- <listitem><para>Assuming you are connecting as the root
- user, which is the default for QEMU x86-64 SDK images
- provided by the Yocto Project, in the "Remote Absolute
- File Path for C/C++ Application" field, browse to
- <filename>/home/root/</filename><replaceable>ProjectName</replaceable>
- (e.g. <filename>/home/root/hello</filename>).
- You could also browse to any other path you have write
- access to on the target such as
- <filename>/usr/bin</filename>.
- This location is where your application will be located
- on the QEMU system.
- If you fail to browse to and specify an appropriate
- location, QEMU will not understand what to remotely
- launch.
- Eclipse is helpful in that it auto fills your
- application name for you assuming you browsed to a
- directory.
- <note>
- If you are prompted to provide a username and to
- optionally set a password, be sure you provide
- "root" as the username and you leave the password
- field blank.
- </note>
- </para></listitem>
- <listitem><para>
- Be sure you change to the "Debug" perspective in
- Eclipse.
- </para></listitem>
- <listitem><para>Click "Debug"
- </para></listitem>
- <listitem><para>Accept the debug perspective.
- </para></listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id='neon-using-Linuxtools'>
- <title>Using Linuxtools</title>
-
- <para>
- As mentioned earlier in the manual, performance tools exist
- (Linuxtools) that enhance your development experience.
- These tools are aids in developing and debugging applications and
- images.
- You can run these tools from within the Eclipse IDE through the
- "Linuxtools" menu.
- </para>
-
- <para>
- For information on how to configure and use these tools, see
- <ulink url='http://www.eclipse.org/linuxtools/'>http://www.eclipse.org/linuxtools/</ulink>.
- </para>
- </section>
</section>
-</section>
-
</chapter>
<!--
vim: expandtab tw=80 ts=4
diff --git a/documentation/sdk-manual/sdk-working-projects.xml b/documentation/sdk-manual/sdk-working-projects.xml
new file mode 100644
index 0000000000..15e533000c
--- /dev/null
+++ b/documentation/sdk-manual/sdk-working-projects.xml
@@ -0,0 +1,1461 @@
+<!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='sdk-working-projects'>
+
+ <title>Working with Different Types of Projects</title>
+
+ <para>
+ You can use extensible and standard SDKs when working with Makefile,
+ Autotools, and <trademark class='trade'>Eclipse</trademark> based
+ projects.
+ This chapter covers information specific to each of these types of
+ projects.
+ </para>
+
+ <section id='autotools-based-projects'>
+ <title>Autotools-Based Projects</title>
+
+ <para>
+ Once you have a suitable cross-toolchain installed, it is very easy
+ to develop a project outside of the OpenEmbedded build system.
+ This section presents a simple "Helloworld" example that shows how
+ to set up, compile, and run the project.
+ </para>
+
+ <section id='creating-and-running-a-project-based-on-gnu-autotools'>
+ <title>Creating and Running a Project Based on GNU Autotools</title>
+
+ <para>
+ Follow these steps to create a simple Autotools-based project:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Create your directory:</emphasis>
+ Create a clean directory for your project and then make
+ that directory your working location:
+ <literallayout class='monospaced'>
+ $ mkdir $HOME/helloworld
+ $ cd $HOME/helloworld
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Populate the directory:</emphasis>
+ Create <filename>hello.c</filename>,
+ <filename>Makefile.am</filename>,
+ and <filename>configure.ac</filename> files as follows:
+ <itemizedlist>
+ <listitem><para>
+ For <filename>hello.c</filename>, include
+ these lines:
+ <literallayout class='monospaced'>
+ #include &lt;stdio.h&gt;
+
+ main()
+ {
+ printf("Hello World!\n");
+ }
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ For <filename>Makefile.am</filename>,
+ include these lines:
+ <literallayout class='monospaced'>
+ bin_PROGRAMS = hello
+ hello_SOURCES = hello.c
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ For <filename>configure.in</filename>,
+ include these lines:
+ <literallayout class='monospaced'>
+ AC_INIT(hello,0.1)
+ AM_INIT_AUTOMAKE([foreign])
+ AC_PROG_CC
+ AC_PROG_INSTALL
+ AC_OUTPUT(Makefile)
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Source the cross-toolchain
+ environment setup file:</emphasis>
+ As described earlier in the manual, installing the
+ cross-toolchain creates a cross-toolchain
+ environment setup script in the directory that the SDK
+ was installed.
+ Before you can use the tools to develop your project,
+ you must source this setup script.
+ The script begins with the string "environment-setup"
+ and contains the machine architecture, which is
+ followed by the string "poky-linux".
+ Here is an example that sources a script from the
+ default SDK installation directory that uses the
+ 32-bit Intel x86 Architecture and the
+ &DISTRO_NAME; Yocto Project release:
+ <literallayout class='monospaced'>
+ $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Generate the local aclocal.m4
+ files and create the configure script:</emphasis>
+ The following GNU Autotools generate the local
+ <filename>aclocal.m4</filename> files and create the
+ configure script:
+ <literallayout class='monospaced'>
+ $ aclocal
+ $ autoconf
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Generate files needed by GNU coding
+ standards:</emphasis>
+ GNU coding standards require certain files in order
+ for the project to be compliant.
+ This command creates those files:
+ <literallayout class='monospaced'>
+ $ touch NEWS README AUTHORS ChangeLog
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Generate the configure file:</emphasis>
+ This command generates the
+ <filename>configure</filename>:
+ <literallayout class='monospaced'>
+ $ automake -a
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Cross-compile the project:</emphasis>
+ This command compiles the project using the
+ cross-compiler.
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink>
+ environment variable provides the minimal arguments for
+ GNU configure:
+ <literallayout class='monospaced'>
+ $ ./configure ${CONFIGURE_FLAGS}
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Make and install the project:</emphasis>
+ These two commands generate and install the project
+ into the destination directory:
+ <literallayout class='monospaced'>
+ $ make
+ $ make install DESTDIR=./tmp
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Verify the installation:</emphasis>
+ This command is a simple way to verify the installation
+ of your project.
+ Running the command prints the architecture on which
+ the binary file can run.
+ This architecture should be the same architecture that
+ the installed cross-toolchain supports.
+ <literallayout class='monospaced'>
+ $ file ./tmp/usr/local/bin/hello
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Execute your project:</emphasis>
+ To execute the project in the shell, simply enter
+ the name.
+ You could also copy the binary to the actual target
+ hardware and run the project there as well:
+ <literallayout class='monospaced'>
+ $ ./hello
+ </literallayout>
+ As expected, the project displays the "Hello World!"
+ message.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='passing-host-options'>
+ <title>Passing Host Options</title>
+
+ <para>
+ For an Autotools-based project, you can use the cross-toolchain
+ by just passing the appropriate host option to
+ <filename>configure.sh</filename>.
+ The host option you use is derived from the name of the
+ environment setup script found in the directory in which you
+ installed the cross-toolchain.
+ For example, the host option for an ARM-based target that uses
+ the GNU EABI is <filename>armv5te-poky-linux-gnueabi</filename>.
+ You will notice that the name of the script is
+ <filename>environment-setup-armv5te-poky-linux-gnueabi</filename>.
+ Thus, the following command works to update your project and
+ rebuild it using the appropriate cross-toolchain tools:
+ <literallayout class='monospaced'>
+ $ ./configure --host=armv5te-poky-linux-gnueabi \
+ --with-libtool-sysroot=<replaceable>sysroot_dir</replaceable>
+ </literallayout>
+ <note>
+ If the <filename>configure</filename> script results in
+ problems recognizing the
+ <filename>--with-libtool-sysroot=</filename><replaceable>sysroot-dir</replaceable>
+ option, regenerate the script to enable the support by
+ doing the following and then run the script again:
+ <literallayout class='monospaced'>
+ $ libtoolize --automake
+ $ aclocal -I ${OECORE_TARGET_SYSROOT}/usr/share/aclocal \
+ [-I <replaceable>dir_containing_your_project-specific_m4_macros</replaceable>]
+ $ autoconf
+ $ autoheader
+ $ automake -a
+ </literallayout>
+ </note>
+ </para>
+ </section>
+ </section>
+
+ <section id='makefile-based-projects'>
+ <title>Makefile-Based Projects</title>
+
+ <para>
+ For Makefile-based projects, the cross-toolchain environment
+ variables established by running the cross-toolchain environment
+ setup script are subject to general <filename>make</filename>
+ rules.
+ </para>
+
+ <para>
+ To illustrate this, consider the following four cross-toolchain
+ environment variables:
+ <literallayout class='monospaced'>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'>CC</ulink>=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/&DISTRO;/sysroots/i586-poky-linux
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'>LD</ulink>=i586-poky-linux-ld --sysroot=/opt/poky/&DISTRO;/sysroots/i586-poky-linux
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'>CXXFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types
+ </literallayout>
+ Now, consider the following three cases:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Case 1 - No Variables Set in the
+ <filename>Makefile</filename>:</emphasis>
+ Because these variables are not specifically set in the
+ <filename>Makefile</filename>, the variables retain their
+ values based on the environment.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Case 2 - Variables Set in the
+ <filename>Makefile</filename>:</emphasis>
+ Specifically setting variables in the
+ <filename>Makefile</filename> during the build results in
+ the environment settings of the variables being
+ overwritten.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Case 3 - Variables Set when the
+ <filename>Makefile</filename> is Executed from the
+ Command Line:</emphasis>
+ Executing the <filename>Makefile</filename> from the
+ command-line results in the variables being overwritten
+ with command-line content regardless of what is being set
+ in the <filename>Makefile</filename>.
+ In this case, environment variables are not considered
+ unless you use the "-e" flag during the build:
+ <literallayout class='monospaced'>
+ $ make -e <replaceable>file</replaceable>
+ </literallayout>
+ If you use this flag, then the environment values of the
+ variables override any variables specifically set in the
+ <filename>Makefile</filename>.
+ </para></listitem>
+ </itemizedlist>
+ <note>
+ For the list of variables set up by the cross-toolchain
+ environment setup script, see the
+ "<link linkend='sdk-running-the-sdk-environment-setup-script'>Running the SDK Environment Setup Script</link>"
+ section.
+ </note>
+ </para>
+ </section>
+
+ <section id='sdk-developing-applications-using-eclipse'>
+ <title>Developing Applications Using <trademark class='trade'>Eclipse</trademark></title>
+
+ <para>
+ If you are familiar with the popular Eclipse IDE, you can use an
+ Eclipse Yocto Plug-in to allow you to develop, deploy, and test your
+ application all from within Eclipse.
+ This section describes general workflow using the SDK and Eclipse
+ and how to configure and set up Eclipse.
+ </para>
+
+ <section id='workflow-using-eclipse'>
+ <title>Workflow Using <trademark class='trade'>Eclipse</trademark></title>
+
+ <para>
+ The following figure and supporting list summarize the
+ application development general workflow that employs both the
+ SDK Eclipse.
+ </para>
+
+ <para>
+ <imagedata fileref="figures/sdk-eclipse-dev-flow.png"
+ width="7in" depth="7in" align="center" scale="100" />
+ </para>
+
+ <para>
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Prepare the host system for the Yocto
+ Project</emphasis>:
+ See
+ "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
+ and
+ "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>"
+ sections both in the Yocto Project Reference Manual for
+ requirements.
+ In particular, be sure your host system has the
+ <filename>xterm</filename> package installed.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Secure the Yocto Project kernel target
+ image</emphasis>:
+ You must have a target kernel image that has been built
+ using the OpenEmbedded build system.</para>
+ <para>Depending on whether the Yocto Project has a
+ pre-built image that matches your target architecture
+ and where you are going to run the image while you
+ develop your application (QEMU or real hardware), the
+ area from which you get the image differs.
+ <itemizedlist>
+ <listitem><para>
+ Download the image from
+ <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink>
+ if your target architecture is supported and
+ you are going to develop and test your
+ application on actual hardware.
+ </para></listitem>
+ <listitem><para>
+ Download the image from
+ <ulink url='&YOCTO_QEMU_DL_URL;'>
+ <filename>machines/qemu</filename></ulink> if
+ your target architecture is supported and you
+ are going to develop and test your application
+ using the QEMU emulator.
+ </para></listitem>
+ <listitem><para>
+ Build your image if you cannot find a pre-built
+ image that matches your target architecture.
+ If your target architecture is similar to a
+ supported architecture, you can modify the
+ kernel image before you build it.
+ See the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>"
+ section in the Yocto Project Development
+ manual for an example.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem>
+ <para><emphasis>Install the SDK</emphasis>:
+ The SDK provides a target-specific cross-development
+ toolchain, the root filesystem, the QEMU emulator, and
+ other tools that can help you develop your application.
+ For information on how to install the SDK, see the
+ "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
+ section.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Secure the target root filesystem
+ and the Cross-development toolchain</emphasis>:
+ You need to find and download the appropriate root
+ filesystem and the cross-development toolchain.</para>
+ <para>You can find the tarballs for the root filesystem
+ in the same area used for the kernel image.
+ Depending on the type of image you are running, the
+ root filesystem you need differs.
+ For example, if you are developing an application that
+ runs on an image that supports Sato, you need to get a
+ root filesystem that supports Sato.</para>
+ <para>You can find the cross-development toolchains at
+ <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'><filename>toolchains</filename></ulink>.
+ Be sure to get the correct toolchain for your
+ development host and your target architecture.
+ See the "<link linkend='sdk-locating-pre-built-sdk-installers'>Locating Pre-Built SDK Installers</link>"
+ section for information and the
+ "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
+ section for installation information.
+ <note>
+ As an alternative to downloading an SDK, you can
+ build the toolchain installer.
+ For information on building the installer, see the
+ "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
+ section.
+ Another helpful resource for building an installer
+ is the
+ <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
+ wiki page.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Create and build your application</emphasis>:
+ At this point, you need to have source files for your
+ application.
+ Once you have the files, you can use the Eclipse IDE
+ to import them and build the project.
+ If you are not using Eclipse, you need to use the
+ cross-development tools you have installed to create
+ the image.</para></listitem>
+ <listitem><para>
+ <emphasis>Deploy the image with the
+ application</emphasis>:
+ Using the Eclipse IDE, you can deploy your image to the
+ hardware or to QEMU through the project's preferences.
+ You can also use Eclipse to load and test your image
+ under QEMU.
+ See the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
+ chapter in the Yocto Project Development Manual
+ for information on using QEMU.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Test and debug the application</emphasis>:
+ Once your application is deployed, you need to test it.
+ Within the Eclipse IDE, you can use the debugging
+ environment along with supported performance enhancing
+ <ulink url='http://www.eclipse.org/linuxtools/'>Linux Tools</ulink>.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='adt-eclipse'>
+ <title>Working Within Eclipse</title>
+
+ <para>
+ The Eclipse IDE is a popular development environment and it
+ fully supports development using the Yocto Project.
+ </para>
+
+ <para>
+ When you install and configure the Eclipse Yocto Project
+ Plug-in into the Eclipse IDE, you maximize your Yocto
+ Project experience.
+ Installing and configuring the Plug-in results in an
+ environment that has extensions specifically designed to let
+ you more easily develop software.
+ These extensions allow for cross-compilation, deployment, and
+ execution of your output into a QEMU emulation session as well
+ as actual target hardware.
+ You can also perform cross-debugging and profiling.
+ The environment also supports performance enhancing
+ <ulink url='http://www.eclipse.org/linuxtools/'>tools</ulink>
+ that allow you to perform remote profiling, tracing,
+ collection of power data, collection of latency data, and
+ collection of performance data.
+ <note>
+ This release of the Yocto Project supports both the Neon
+ and Mars versions of the Eclipse IDE.
+ This section provides information on how to use the Neon
+ release with the Yocto Project.
+ For information on how to use the Mars version of Eclipse
+ with the Yocto Project, see
+ "<link linkend='sdk-appendix-mars'>Appendix C</link>.
+ </note>
+ </para>
+
+ <section id='neon-setting-up-the-eclipse-ide'>
+ <title>Setting Up the Neon Version of the Eclipse IDE</title>
+
+ <para>
+ To develop within the Eclipse IDE, you need to do the
+ following:
+ <orderedlist>
+ <listitem><para>
+ Install the Neon version of the Eclipse IDE.
+ </para></listitem>
+ <listitem><para>
+ Configure the Eclipse IDE.
+ </para></listitem>
+ <listitem><para>
+ Install the Eclipse Yocto Plug-in.
+ </para></listitem>
+ <listitem><para>
+ Configure the Eclipse Yocto Plug-in.
+ </para></listitem>
+ </orderedlist>
+ <note>
+ Do not install Eclipse from your distribution's package
+ repository.
+ Be sure to install Eclipse from the official Eclipse
+ download site as directed in the next section.
+ </note>
+ </para>
+
+ <section id='neon-installing-eclipse-ide'>
+ <title>Installing the Neon Eclipse IDE</title>
+
+ <para>
+ Follow these steps to locate, install, and configure
+ Neon Eclipse:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Locate the Neon Download:</emphasis>
+ Open a browser and go to
+ <ulink url='http://www.eclipse.org/mars/'>http://www.eclipse.org/neon/</ulink>.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Download the Tarball:</emphasis>
+ Click through the "Download" buttons to
+ download the file.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Unpack the Tarball:</emphasis>
+ Move to a clean directory and unpack the
+ tarball.
+ Here is an example:
+ <literallayout class='monospaced'>
+ $ cd ~
+ $ tar -xzvf ~/Downloads/eclipse-inst-linux64.tar.gz
+ </literallayout>
+ Everything unpacks into a folder named
+ "eclipse-installer".
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Launch the Installer:</emphasis>
+ Use the following commands to launch the
+ installer:
+ <literallayout class='monospaced'>
+ $ cd ~/eclipse-installer
+ $ ./eclipse-inst
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Select Your IDE:</emphasis>
+ From the list, select the "Eclipse IDE for
+ C/C++ Developers".
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Install the Software:</emphasis>
+ Accept the default "cpp-neon" directory and
+ click "Install".
+ Accept any license agreements and approve any
+ certificates.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Launch Neon:</emphasis>
+ Click the "Launch" button and accept the
+ default "workspace".
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='neon-configuring-the-mars-eclipse-ide'>
+ <title>Configuring the Neon Eclipse IDE</title>
+
+ <para>
+ Follow these steps to configure the Neon Eclipse IDE.
+ <note>
+ Depending on how you installed Eclipse and what
+ you have already done, some of the options will
+ not appear.
+ If you cannot find an option as directed by the
+ manual, it has already been installed.
+ </note>
+ <orderedlist>
+ <listitem><para>
+ Be sure Eclipse is running and you are in your
+ workbench.
+ </para></listitem>
+ <listitem><para>
+ Select "Install New Software" from the "Help"
+ pull-down menu.
+ </para></listitem>
+ <listitem><para>
+ Select
+ "Neon - http://download.eclipse.org/releases/neon"
+ from the "Work with:" pull-down menu.
+ </para></listitem>
+ <listitem><para>
+ Expand the box next to "Linux Tools" and select
+ the following:
+ <literallayout class='monospaced'>
+ C/C++ Remote (Over TCF/TE) Run/Debug Launcher
+ TM Terminal
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Expand the box next to "Mobile and Device
+ Development" and select the following
+ boxes:
+ <literallayout class='monospaced'>
+ C/C++ Remote (Over TCF/TE) Run/Debug Launcher
+ Remote System Explorer User Actions
+ TM Terminal
+ TCF Remote System Explorer add-in
+ TCF Target Explorer
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Expand the box next to "Programming Languages"
+ and select the following box:
+ <literallayout class='monospaced'>
+ C/C++ Development Tools SDK
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Complete the installation by clicking through
+ appropriate "Next" and "Finish" buttons.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='neon-installing-the-eclipse-yocto-plug-in'>
+ <title>Installing or Accessing the Neon Eclipse Yocto Plug-in</title>
+
+ <para>
+ You can install the Eclipse Yocto Plug-in into the
+ Eclipse IDE one of two ways: use the Yocto Project's
+ Eclipse Update site to install the pre-built plug-in
+ or build and install the plug-in from the latest
+ source code.
+ </para>
+
+ <section id='neon-new-software'>
+ <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title>
+
+ <para>
+ To install the Neon Eclipse Yocto Plug-in from the
+ update site, follow these steps:
+ <orderedlist>
+ <listitem><para>
+ Start up the Eclipse IDE.
+ </para></listitem>
+ <listitem><para>
+ In Eclipse, select "Install New
+ Software" from the "Help" menu.
+ </para></listitem>
+ <listitem><para>
+ Click "Add..." in the "Work with:" area.
+ </para></listitem>
+ <listitem><para>
+ Enter
+ <filename>&ECLIPSE_DL_PLUGIN_URL;/neon</filename>
+ in the URL field and provide a meaningful
+ name in the "Name" field.
+ </para></listitem>
+ <listitem><para>
+ Click "OK" to have the entry added
+ to the "Work with:" drop-down list.
+ </para></listitem>
+ <listitem><para>
+ Select the entry for the plug-in
+ from the "Work with:" drop-down list.
+ </para></listitem>
+ <listitem><para>
+ Check the boxes next to the following:
+ <literallayout class='monospaced'>
+ Yocto Project SDK Plug-in
+ Yocto Project Documentation plug-in
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Complete the remaining software
+ installation steps and then restart the
+ Eclipse IDE to finish the installation of
+ the plug-in.
+ <note>
+ You can click "OK" when prompted about
+ installing software that contains
+ unsigned content.
+ </note>
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='neon-zip-file-method'>
+ <title>Installing the Plug-in Using the Latest Source Code</title>
+
+ <para>
+ To install the Neon Eclipse Yocto Plug-in from the
+ latest source code, follow these steps:
+ <orderedlist>
+ <listitem><para>
+ Be sure your development system
+ has JDK 1.8+
+ </para></listitem>
+ <listitem><para>
+ Install X11-related packages:
+ <literallayout class='monospaced'>
+ $ sudo apt-get install xauth
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ In a new terminal shell, create a
+ Git repository with:
+ <literallayout class='monospaced'>
+ $ cd ~
+ $ git clone git://git.yoctoproject.org/eclipse-poky
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Use Git to create the correct tag:
+ <literallayout class='monospaced'>
+ $ cd ~/eclipse-poky
+ $ git checkout neon/yocto-&DISTRO;
+ </literallayout>
+ This creates a local tag named
+ <filename>neon/yocto-&DISTRO;</filename>
+ based on the branch
+ <filename>origin/neon-master</filename>.
+ You are put into a detached HEAD state,
+ which is fine since you are only going to
+ be building and not developing.
+ </para></listitem>
+ <listitem><para>
+ Change to the <filename>scripts</filename>
+ directory within the Git repository:
+ <literallayout class='monospaced'>
+ $ cd scripts
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Set up the local build environment
+ by running the setup script:
+ <literallayout class='monospaced'>
+ $ ./setup.sh
+ </literallayout>
+ When the script finishes execution,
+ it prompts you with instructions on how to
+ run the <filename>build.sh</filename>
+ script, which is also in the
+ <filename>scripts</filename> directory of
+ the Git repository created earlier.
+ </para></listitem>
+ <listitem><para>
+ Run the <filename>build.sh</filename>
+ script as directed.
+ Be sure to provide the tag name,
+ documentation branch, and a release name.
+ </para>
+ <para>
+ Following is an example:
+ <literallayout class='monospaced'>
+ $ ECLIPSE_HOME=/home/scottrif/eclipse-poky/scripts/eclipse ./build.sh -l neon/yocto-&DISTRO; master yocto-&DISTRO; 2>&amp;1 | tee build.log
+ </literallayout>
+ The previous example command adds the tag
+ you need for
+ <filename>mars/yocto-&DISTRO;</filename>
+ to <filename>HEAD</filename>, then tells
+ the build script to use the local (-l) Git
+ checkout for the build.
+ After running the script, the file
+ <filename>org.yocto.sdk-</filename><replaceable>release</replaceable><filename>-</filename><replaceable>date</replaceable><filename>-archive.zip</filename>
+ is in the current directory.
+ </para></listitem>
+ <listitem><para>
+ If necessary, start the Eclipse IDE
+ and be sure you are in the Workbench.
+ </para></listitem>
+ <listitem><para>
+ Select "Install New Software" from
+ the "Help" pull-down menu.
+ </para></listitem>
+ <listitem><para>
+ Click "Add".
+ </para></listitem>
+ <listitem><para>
+ Provide anything you want in the
+ "Name" field.
+ </para></listitem>
+ <listitem><para>
+ Click "Archive" and browse to the
+ ZIP file you built earlier.
+ This ZIP file should not be "unzipped", and
+ must be the
+ <filename>*archive.zip</filename> file
+ created by running the
+ <filename>build.sh</filename> script.
+ </para></listitem>
+ <listitem><para>
+ Click the "OK" button.
+ </para></listitem>
+ <listitem><para>
+ Check the boxes that appear in
+ the installation window to install the
+ following:
+ <literallayout class='monospaced'>
+ Yocto Project SDK Plug-in
+ Yocto Project Documentation plug-in
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Finish the installation by clicking
+ through the appropriate buttons.
+ You can click "OK" when prompted about
+ installing software that contains unsigned
+ content.
+ </para></listitem>
+ <listitem><para>
+ Restart the Eclipse IDE if necessary.
+ </para></listitem>
+ </orderedlist>
+ </para>
+
+ <para>
+ At this point you should be able to configure the
+ Eclipse Yocto Plug-in as described in the
+ "<link linkend='mars-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>"
+ section.
+ </para>
+ </section>
+ </section>
+
+ <section id='neon-configuring-the-eclipse-yocto-plug-in'>
+ <title>Configuring the Neon Eclipse Yocto Plug-in</title>
+
+ <para>
+ Configuring the Neon Eclipse Yocto Plug-in involves
+ setting the Cross Compiler options and the Target
+ options.
+ The configurations you choose become the default
+ settings for all projects.
+ You do have opportunities to change them later when
+ you configure the project (see the following section).
+ </para>
+
+ <para>
+ To start, you need to do the following from within the
+ Eclipse IDE:
+ <itemizedlist>
+ <listitem><para>
+ Choose "Preferences" from the "Window" menu to
+ display the Preferences Dialog.
+ </para></listitem>
+ <listitem><para>
+ Click "Yocto Project SDK" to display
+ the configuration screen.
+ </para></listitem>
+ </itemizedlist>
+ The following sub-sections describe how to configure
+ the plug-in.
+ <note>
+ Throughout the descriptions, a start-to-finish
+ example for preparing a QEMU image for use with
+ Eclipse is referenced as the "wiki" and is linked
+ to the example on the
+ <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'> Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
+ wiki page.
+ </note>
+ </para>
+
+ <section id='neon-configuring-the-cross-compiler-options'>
+ <title>Configuring the Cross-Compiler Options</title>
+
+ <para>
+ Cross Compiler options enable Eclipse to use your
+ specific cross compiler toolchain.
+ To configure these options, you must select
+ the type of toolchain, point to the toolchain,
+ specify the sysroot location, and select the target
+ architecture.
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Selecting the Toolchain
+ Type:</emphasis>
+ Choose between
+ <filename>Standalone pre-built toolchain</filename>
+ and
+ <filename>Build system derived toolchain</filename>
+ for Cross Compiler Options.
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>
+ <filename>Standalone Pre-built Toolchain:</filename>
+ </emphasis>
+ Select this type when you are using
+ a stand-alone cross-toolchain.
+ For example, suppose you are an
+ application developer and do not
+ need to build a target image.
+ Instead, you just want to use an
+ architecture-specific toolchain on
+ an existing kernel and target root
+ filesystem.
+ In other words, you have downloaded
+ and installed a pre-built toolchain
+ for an existing image.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>
+ <filename>Build System Derived Toolchain:</filename>
+ </emphasis>
+ Select this type if you built the
+ toolchain as part of the
+ <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+ When you select
+ <filename>Build system derived toolchain</filename>,
+ you are using the toolchain built
+ and bundled inside the Build
+ Directory.
+ For example, suppose you created a
+ suitable image using the steps in the
+ <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
+ In this situation, you would select
+ the
+ <filename>Build system derived toolchain</filename>.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Specify the Toolchain Root
+ Location:</emphasis>
+ If you are using a stand-alone pre-built
+ toolchain, you should be pointing to where
+ it is installed (e.g.
+ <filename>/opt/poky/&DISTRO;</filename>).
+ See the
+ "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
+ section for information about how the SDK is
+ installed.</para>
+ <para>If you are using a build system
+ derived toolchain, the path you provide for
+ the
+ <filename>Toolchain Root Location</filename>
+ field is the
+ <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+ from which you run the
+ <filename>bitbake</filename> command (e.g
+ <filename>/home/scottrif/poky/build</filename>).
+ </para>
+ <para>For more information, see the
+ "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
+ section.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Specify Sysroot Location:
+ </emphasis>
+ This location is where the root filesystem
+ for the target hardware resides.
+ </para>
+ <para>This location depends on where you
+ separately extracted and installed the
+ target filesystem.
+ As an example, suppose you prepared an
+ image using the steps in the
+ <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
+ If so, the
+ <filename>MY_QEMU_ROOTFS</filename>
+ directory is found in the
+ <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+ and you would browse to and select that
+ directory (e.g.
+ <filename>/home/scottrif/poky/build/MY_QEMU_ROOTFS</filename>).
+ </para>
+ <para>For more information on how to
+ install the toolchain and on how to extract
+ and install the sysroot filesystem, see the
+ "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
+ section.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Select the Target Architecture:
+ </emphasis>
+ The target architecture is the type of
+ hardware you are going to use or emulate.
+ Use the pull-down
+ <filename>Target Architecture</filename>
+ menu to make your selection.
+ The pull-down menu should have the
+ supported architectures.
+ If the architecture you need is not listed
+ in the menu, you will need to build the
+ image.
+ See the
+ "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
+ section of the Yocto Project Quick Start
+ for more information.
+ You can also see the
+ <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='neon-configuring-the-target-options'>
+ <title>Configuring the Target Options</title>
+
+ <para>
+ You can choose to emulate hardware using the QEMU
+ emulator, or you can choose to run your image on
+ actual hardware.
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>QEMU:</emphasis>
+ Select this option if you will be using the
+ QEMU emulator.
+ If you are using the emulator, you also
+ need to locate the kernel and specify any
+ custom options.</para>
+ <para>If you selected the
+ <filename>Build system derived toolchain</filename>,
+ the target kernel you built will be located
+ in the
+ <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+ in
+ <filename>tmp/deploy/images/<replaceable>machine</replaceable></filename>
+ directory.
+ As an example, suppose you performed the
+ steps in the
+ <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
+ In this case, you specify your Build
+ Directory path followed by the image (e.g.
+ <filename>/home/scottrif/poky/build/tmp/deploy/images/qemux86/bzImage-qemux86.bin</filename>).
+ </para>
+ <para>If you selected the standalone
+ pre-built toolchain, the pre-built image
+ you downloaded is located in the directory
+ you specified when you downloaded the
+ image.</para>
+ <para>Most custom options are for advanced
+ QEMU users to further customize their QEMU
+ instance.
+ These options are specified between paired
+ angled brackets.
+ Some options must be specified outside the
+ brackets.
+ In particular, the options
+ <filename>serial</filename>,
+ <filename>nographic</filename>, and
+ <filename>kvm</filename> must all be
+ outside the brackets.
+ Use the <filename>man qemu</filename>
+ command to get help on all the options and
+ their use.
+ The following is an example:
+ <literallayout class='monospaced'>
+ serial ‘&lt;-m 256 -full-screen&gt;’
+ </literallayout></para>
+ <para>
+ Regardless of the mode, Sysroot is already
+ defined as part of the Cross-Compiler
+ Options configuration in the
+ <filename>Sysroot Location:</filename>
+ field.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>External HW:</emphasis>
+ Select this option if you will be using
+ actual hardware.</para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Click the "Apply" and "OK" to save your plug-in
+ configurations.
+ </para>
+ </section>
+ </section>
+ </section>
+
+ <section id='neon-creating-the-project'>
+ <title>Creating the Project</title>
+
+ <para>
+ You can create two types of projects: Autotools-based, or
+ Makefile-based.
+ This section describes how to create Autotools-based
+ projects from within the Eclipse IDE.
+ For information on creating Makefile-based projects in a
+ terminal window, see the
+ "<link linkend='makefile-based-projects'>Makefile-Based Projects</link>"
+ section.
+ <note>
+ Do not use special characters in project names
+ (e.g. spaces, underscores, etc.). Doing so can
+ cause configuration to fail.
+ </note>
+ </para>
+
+ <para>
+ To create a project based on a Yocto template and then
+ display the source code, follow these steps:
+ <orderedlist>
+ <listitem><para>
+ Select "C Project" from the "File -> New" menu.
+ </para></listitem>
+ <listitem><para>
+ Expand
+ <filename>Yocto Project SDK Autotools Project</filename>.
+ </para></listitem>
+ <listitem><para>
+ Select <filename>Hello World ANSI C Autotools Projects</filename>.
+ This is an Autotools-based project based on a Yocto
+ template.
+ </para></listitem>
+ <listitem><para>
+ Put a name in the
+ <filename>Project name:</filename> field.
+ Do not use hyphens as part of the name
+ (e.g. <filename>hello</filename>).
+ </para></listitem>
+ <listitem><para>
+ Click "Next".
+ </para></listitem>
+ <listitem><para>
+ Add appropriate information in the various fields.
+ </para></listitem>
+ <listitem><para>
+ Click "Finish".
+ </para></listitem>
+ <listitem><para>
+ If the "open perspective" prompt appears,
+ click "Yes" so that you in the C/C++ perspective.
+ </para></listitem>
+ <listitem><para>The left-hand navigation pane shows
+ your project.
+ You can display your source by double clicking the
+ project's source file.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='neon-configuring-the-cross-toolchains'>
+ <title>Configuring the Cross-Toolchains</title>
+
+ <para>
+ The earlier section,
+ "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>",
+ sets up the default project configurations.
+ You can override these settings for a given project by
+ following these steps:
+ <orderedlist>
+ <listitem><para>
+ Select "Yocto Project Settings" from
+ the "Project -> Properties" menu.
+ This selection brings up the Yocto Project Settings
+ Dialog and allows you to make changes specific to
+ an individual project.</para>
+ <para>By default, the Cross Compiler Options and
+ Target Options for a project are inherited from
+ settings you provided using the Preferences Dialog
+ as described earlier in the
+ "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>"
+ section.
+ The Yocto Project Settings Dialog allows you to
+ override those default settings for a given
+ project.
+ </para></listitem>
+ <listitem><para>
+ Make or verify your configurations for the
+ project and click "OK".
+ </para></listitem>
+ <listitem><para>
+ Right-click in the navigation pane and
+ select "Reconfigure Project" from the pop-up menu.
+ This selection reconfigures the project by running
+ <filename>autogen.sh</filename> in the workspace
+ for your project.
+ The script also runs
+ <filename>libtoolize</filename>,
+ <filename>aclocal</filename>,
+ <filename>autoconf</filename>,
+ <filename>autoheader</filename>,
+ <filename>automake --a</filename>, and
+ <filename>./configure</filename>.
+ Click on the "Console" tab beneath your source code
+ to see the results of reconfiguring your project.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='neon-building-the-project'>
+ <title>Building the Project</title>
+
+ <para>
+ To build the project select "Build All" from the
+ "Project" menu.
+ The console should update and you can note the
+ cross-compiler you are using.
+ <note>
+ When building "Yocto Project SDK Autotools" projects,
+ the Eclipse IDE might display error messages for
+ Functions/Symbols/Types that cannot be "resolved",
+ even when the related include file is listed at the
+ project navigator and when the project is able to
+ build.
+ For these cases only, it is recommended to add a new
+ linked folder to the appropriate sysroot.
+ Use these steps to add the linked folder:
+ <orderedlist>
+ <listitem><para>
+ Select the project.
+ </para></listitem>
+ <listitem><para>
+ Select "Folder" from the
+ <filename>File > New</filename> menu.
+ </para></listitem>
+ <listitem><para>
+ In the "New Folder" Dialog, select "Link to
+ alternate location (linked folder)".
+ </para></listitem>
+ <listitem><para>
+ Click "Browse" to navigate to the include
+ folder inside the same sysroot location
+ selected in the Yocto Project
+ configuration preferences.
+ </para></listitem>
+ <listitem><para>
+ Click "OK".
+ </para></listitem>
+ <listitem><para>
+ Click "Finish" to save the linked folder.
+ </para></listitem>
+ </orderedlist>
+ </note>
+ </para>
+ </section>
+
+ <section id='neon-starting-qemu-in-user-space-nfs-mode'>
+ <title>Starting QEMU in User-Space NFS Mode</title>
+
+ <para>
+ To start the QEMU emulator from within Eclipse, follow
+ these steps:
+ <note>
+ See the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
+ chapter in the Yocto Project Development Manual
+ for more information on using QEMU.
+ </note>
+ <orderedlist>
+ <listitem><para>Expose and select "External Tools
+ Configurations ..." from the "Run -> External
+ Tools" menu.
+ </para></listitem>
+ <listitem><para>
+ Locate and select your image in the navigation
+ panel to the left
+ (e.g. <filename>qemu_i586-poky-linux</filename>).
+ </para></listitem>
+ <listitem><para>
+ Click "Run" to launch QEMU.
+ <note>
+ The host on which you are running QEMU must
+ have the <filename>rpcbind</filename> utility
+ running to be able to make RPC calls on a
+ server on that machine.
+ If QEMU does not invoke and you receive error
+ messages involving
+ <filename>rpcbind</filename>, follow the
+ suggestions to get the service running.
+ As an example, on a new Ubuntu 16.04 LTS
+ installation, you must do the following in
+ order to get QEMU to launch:
+ <literallayout class='monospaced'>
+ $ sudo apt-get install rpcbind
+ </literallayout>
+ After installing <filename>rpcbind</filename>,
+ you need to edit the
+ <filename>/etc/init.d/rpcbind</filename> file
+ to include the following line:
+ <literallayout class='monospaced'>
+ OPTIONS="-i -w"
+ </literallayout>
+ After modifying the file, you need to start the
+ service:
+ <literallayout class='monospaced'>
+ $ sudo service portmap restart
+ </literallayout>
+ </note>
+ </para></listitem>
+ <listitem><para>
+ If needed, enter your host root password in
+ the shell window at the prompt.
+ This sets up a <filename>Tap 0</filename>
+ connection needed for running in user-space NFS
+ mode.
+ </para></listitem>
+ <listitem><para>
+ Wait for QEMU to launch.
+ </para></listitem>
+ <listitem><para>
+ Once QEMU launches, you can begin operating
+ within that environment.
+ One useful task at this point would be to determine
+ the IP Address for the user-space NFS by using the
+ <filename>ifconfig</filename> command.
+ The IP address of the QEMU machine appears in the
+ xterm window.
+ You can use this address to help you see which
+ particular
+ IP address the instance of QEMU is using.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='neon-deploying-and-debugging-the-application'>
+ <title>Deploying and Debugging the Application</title>
+
+ <para>
+ Once the QEMU emulator is running the image, you can deploy
+ your application using the Eclipse IDE and then use
+ the emulator to perform debugging.
+ Follow these steps to deploy the application.
+ <note>
+ Currently, Eclipse does not support SSH port
+ forwarding.
+ Consequently, if you need to run or debug a remote
+ application using the host display, you must create a
+ tunneling connection from outside Eclipse and keep
+ that connection alive during your work.
+ For example, in a new terminal, run the following:
+ <literallayout class='monospaced'>
+ $ ssh -XY <replaceable>user_name</replaceable>@<replaceable>remote_host_ip</replaceable>
+ </literallayout>
+ Using the above form, here is an example:
+ <literallayout class='monospaced'>
+ $ ssh -XY root@192.168.7.2
+ </literallayout>
+ After running the command, add the command to be
+ executed in Eclipse's run configuration before the
+ application as follows:
+ <literallayout class='monospaced'>
+ export DISPLAY=:10.0
+ </literallayout>
+ Be sure to not destroy the connection during your QEMU
+ session (i.e. do not
+ exit out of or close that shell).
+ </note>
+ <orderedlist>
+ <listitem><para>
+ Select "Debug Configurations..." from the
+ "Run" menu.
+ </para></listitem>
+ <listitem><para>
+ In the left area, expand
+ <filename>C/C++Remote Application</filename>.
+ </para></listitem>
+ <listitem><para>
+ Locate your project and select it to bring
+ up a new tabbed view in the Debug Configurations
+ Dialog.
+ </para></listitem>
+ <listitem><para>
+ Click on the "Debugger" tab to see the
+ cross-tool debugger you are using.
+ Be sure to change to the debugger perspective in
+ Eclipse.
+ </para></listitem>
+ <listitem><para>
+ Click on the "Main" tab.
+ </para></listitem>
+ <listitem><para>
+ Create a new connection to the QEMU instance
+ by clicking on "new".</para></listitem>
+ <listitem><para>Select <filename>SSH</filename>, which
+ means Secure Socket Shell and then click "OK".
+ Optionally, you can select an TCF connection
+ instead.
+ </para></listitem>
+ <listitem><para>
+ Clear out the "Connection name" field and
+ enter any name you want for the connection.
+ </para></listitem>
+ <listitem><para>
+ Put the IP address for the connection in
+ the "Host" field.
+ For QEMU, the default is
+ <filename>192.168.7.2</filename>.
+ However, if a previous QEMU session did not exit
+ cleanly, the IP address increments (e.g.
+ <filename>192.168.7.3</filename>).
+ <note>
+ You can find the IP address for the current
+ QEMU session by looking in the xterm that
+ opens when you launch QEMU.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ Enter <filename>root</filename>, which
+ is the default for QEMU, for the "User" field.
+ Be sure to leave the password field empty.
+ </para></listitem>
+ <listitem><para>
+ Click "Finish" to close the New Connections Dialog.
+ </para></listitem>
+ <listitem><para>
+ If necessary, use the drop-down menu now in the
+ "Connection" field and pick the IP Address you
+ entered.
+ </para></listitem>
+ <listitem><para>
+ Assuming you are connecting as the root
+ user, which is the default for QEMU x86-64 SDK
+ images provided by the Yocto Project, in the
+ "Remote Absolute File Path for C/C++ Application"
+ field, browse to
+ <filename>/home/root/</filename><replaceable>ProjectName</replaceable>
+ (e.g. <filename>/home/root/hello</filename>).
+ You could also browse to any other path you have
+ write access to on the target such as
+ <filename>/usr/bin</filename>.
+ This location is where your application will be
+ located on the QEMU system.
+ If you fail to browse to and specify an appropriate
+ location, QEMU will not understand what to remotely
+ launch.
+ Eclipse is helpful in that it auto fills your
+ application name for you assuming you browsed to a
+ directory.
+ <note>
+ If you are prompted to provide a username and
+ to optionally set a password, be sure you
+ provide "root" as the username and you leave
+ the password field blank.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ Be sure you change to the "Debug" perspective in
+ Eclipse.
+ </para></listitem>
+ <listitem><para>
+ Click "Debug"
+ </para></listitem>
+ <listitem><para>
+ Accept the debug perspective.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='neon-using-Linuxtools'>
+ <title>Using Linuxtools</title>
+
+ <para>
+ As mentioned earlier in the manual, performance tools exist
+ (Linuxtools) that enhance your development experience.
+ These tools are aids in developing and debugging
+ applications and images.
+ You can run these tools from within the Eclipse IDE through
+ the "Linuxtools" menu.
+ </para>
+
+ <para>
+ For information on how to configure and use these tools,
+ see
+ <ulink url='http://www.eclipse.org/linuxtools/'>http://www.eclipse.org/linuxtools/</ulink>.
+ </para>
+ </section>
+ </section>
+ </section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->