Yocto 2.4
Move OpenBMC to Yocto 2.4(rocko)
Tested: Built and verified Witherspoon and Palmetto images
Change-Id: I12057b18610d6fb0e6903c60213690301e9b0c67
Signed-off-by: Brad Bishop <bradleyb@fuzziesquirrel.com>
diff --git a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-title.png b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-title.png
index e9d5b34..e69e039 100644
--- a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-title.png
+++ b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-title.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-customizing.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-customizing.xml
index 965cccc..587526f 100644
--- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-customizing.xml
+++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-customizing.xml
@@ -148,9 +148,7 @@
<listitem><para>
If your OpenEmbedded build system setup uses a different
environment setup script other than
- <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
- or
- <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>,
then you must set
<ulink url='&YOCTO_DOCS_REF_URL;#var-OE_INIT_ENV_SCRIPT'><filename>OE_INIT_ENV_SCRIPT</filename></ulink>
to point to the environment setup script you use.
@@ -289,7 +287,7 @@
for the SDK alone, create a
<filename>conf/sdk-extra.conf</filename> either in
your
- <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
or within any layer and put your
<filename>SSTATE_MIRRORS</filename> setting within
that file.
diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-mars.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-mars.xml
index 9957057..2d80f64 100644
--- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-mars.xml
+++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-mars.xml
@@ -14,8 +14,8 @@
from start to finish.
For general information on using the Eclipse IDE and the Yocto
Project Eclipse Plug-In, see the
- "<link linkend='sdk-developing-applications-using-eclipse'>Developing Applications Using <trademark class='trade'>Eclipse</trademark></link>"
- section.
+ "<link linkend='sdk-eclipse-project'>Developing Applications Using <trademark class='trade'>Eclipse</trademark></link>"
+ Chapter.
</para>
<section id='mars-setting-up-the-eclipse-ide'>
@@ -392,7 +392,7 @@
<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>.
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
When you select
<filename>Build system derived toolchain</filename>,
you are using the toolchain built and
@@ -418,7 +418,7 @@
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>
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
from which you run the
<filename>bitbake</filename> command (e.g
<filename>/home/scottrif/poky/build</filename>).</para>
@@ -431,14 +431,22 @@
the target hardware resides.
</para>
<para>This location depends on where you
- separately extracted and installed the target
- filesystem.
+ separately extracted and installed the
+ target filesystem when you either built
+ it or downloaded it.
+ <note>
+ If you downloaded the root filesystem
+ for the target hardware rather than
+ built it, you must download the
+ <filename>sato-sdk</filename> image
+ in order to build any c/c++ projects.
+ </note>
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>
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
and you would browse to and select that directory
(e.g. <filename>/home/scottrif/build/MY_QEMU_ROOTFS</filename>).
</para>
@@ -487,7 +495,7 @@
<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>
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
in
<filename>tmp/deploy/images/<replaceable>machine</replaceable></filename>
directory.
@@ -692,7 +700,7 @@
<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
+ chapter in the Yocto Project Development Tasks Manual
for more information on using QEMU.
</note>
<orderedlist>
@@ -804,7 +812,7 @@
by clicking on "new".</para></listitem>
<listitem><para>Select <filename>SSH</filename>, which means
Secure Socket Shell.
- Optionally, you can select an TCF connection instead.
+ Optionally, you can select a TCF connection instead.
</para></listitem>
<listitem><para>Click "Next".
</para></listitem>
@@ -848,11 +856,30 @@
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><title>Tips</title>
+ <itemizedlist>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ <listitem><para>
+ If browsing to a directory fails or times
+ out, but you can
+ <filename>ssh</filename> into your QEMU
+ or target from the command line and you
+ have proxies set up, it is likely that
+ Eclipse is sending the SSH traffic to a
+ proxy.
+ In this case, either use TCF , or click on
+ "Configure proxy settings" in the
+ connection dialog and add the target IP
+ address to the "bypass proxy" section.
+ You might also need to change
+ "Active Provider" from Native to Manual.
+ </para></listitem>
+ </itemizedlist>
</note>
</para></listitem>
<listitem><para>
diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml
index d0cbf9c..ab9055e 100644
--- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml
+++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml
@@ -18,37 +18,78 @@
</para>
<para>
- You can find SDK installers here:
- <itemizedlist>
- <listitem><para><emphasis>Standard SDK Installers:</emphasis>
+ Follow these steps to locate and hand-install the toolchain:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Go to the Installers Directory:</emphasis>
Go to <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>
- and find the folder that matches your host development system
- (i.e. <filename>i686</filename> for 32-bit machines or
- <filename>x86_64</filename> for 64-bit machines).</para>
-
- <para>Go into that folder and download the SDK installer
- whose name includes the appropriate target architecture.
- The toolchains provided by the Yocto Project are based off of
- the <filename>core-image-sato</filename> image and contain
- libraries appropriate for developing against that image.
- For example, if your host development system is a 64-bit x86
- system and you are going to use your cross-toolchain for a
- 32-bit x86 target, go into the <filename>x86_64</filename>
- folder and download the following installer:
- <literallayout class='monospaced'>
- poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
- </literallayout>
</para></listitem>
- <listitem><para><emphasis>Extensible SDK Installers:</emphasis>
- Installers for the extensible SDK are also located in
- <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>.
- These installers have the string
- <filename>ext</filename> as part of their names:
+ <listitem><para>
+ <emphasis>Open the Folder for Your Development System:</emphasis>
+ Open the folder that matches your host development system
+ (i.e. <filename>i686</filename> for 32-bit machines or
+ <filename>x86_64</filename> for 64-bit machines).
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Locate and Download the SDK Installer:</emphasis>
+ You need to find and download the installer appropriate for
+ your development system, target hardware, and image type.
+ </para>
+
+ <para>The installer files (<filename>*.sh</filename>) follow
+ this naming convention:
+ <literallayout class='monospaced'>
+ poky-eglibc-<replaceable>host_system</replaceable>-core-image-<replaceable>type</replaceable>-<replaceable>arch</replaceable>-toolchain-ext-<replaceable>release</replaceable>.sh
+
+ Where:
+ <replaceable>host_system</replaceable> is a string representing your development system:
+ i686 or x86_64.
+
+ <replaceable>type</replaceable> is a string representing either a "sato" or "minimal"
+ image.
+
+ <replaceable>arch</replaceable> is a string representing the target architecture:
+ aarch64, armv5e, core2-64, coretexa8hf-neon, i586, mips3242,
+ mips64, or ppc7400.
+
+ <replaceable>release</replaceable> is the version of Yocto Project.
+
+ NOTE:
+ The standard SDK installer does not have the "-ext" string as
+ part of the filename.
+
+ </literallayout>
+ The toolchains provided by the Yocto Project are based off of
+ the <filename>core-image-sato</filename> and
+ <filename>core-image-minimal</filename> images and contain
+ libraries appropriate for developing against those images.
+ </para>
+
+ <para>For example, if your host development system is a
+ 64-bit x86 system and you are need an extended SDK for a
+ 64-bit core2 target, go into the <filename>x86_64</filename>
+ folder and download the following installer:
<literallayout class='monospaced'>
poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
</literallayout>
</para></listitem>
- </itemizedlist>
+ <listitem><para>
+ <emphasis>Run the Installer:</emphasis>
+ Be sure you have execution privileges and run the installer.
+ Following is an example from the <filename>Downloads</filename>
+ directory:
+ <literallayout class='monospaced'>
+ $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
+ </literallayout>
+ During execution of the script, you choose the root location
+ for the toolchain.
+ See the
+ "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
+ section and the
+ "<link linkend='sdk-installed-extensible-sdk-directory-structure'>Installed Extensible SDK Directory Structure</link>"
+ section for more information.
+ </para></listitem>
+ </orderedlist>
</para>
</section>
@@ -57,65 +98,135 @@
<para>
As an alternative to locating and downloading a SDK installer,
- you can build the SDK installer assuming you have first sourced
- the environment setup script.
- See the
- "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
- section in the Yocto Project Quick Start for steps that show you
- how to set up the Yocto Project environment.
- In particular, you need to be sure the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
- variable matches the architecture for which you are building and that
- the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>
- variable is correctly set if you are building a toolchain designed to
- run on an architecture that differs from your current development host
- machine (i.e. the build machine).
- </para>
-
- <para>
- To build the SDK installer for a standard SDK and populate
- the SDK image, use the following command:
- <literallayout class='monospaced'>
+ you can build the SDK installer.
+ Follow these steps:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Set Up the Build Environment:</emphasis>
+ Be sure you are set up to use BitBake in a shell.
+ See the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Setting Up the Development Host to Use the Yocto Project</ulink>"
+ section in the Yocto Project Development Tasks Manual for
+ information on how to get a build host ready that is either a
+ native Linux machine or a machine that uses CROPS.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Clone the <filename>poky</filename> Repository:</emphasis>
+ You need to have a local copy of the Yocto Project
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ (i.e. a local <filename>poky</filename> repository).
+ See the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>"
+ and possibly the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>"
+ and
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>"
+ sections all in the Yocto Project Development Tasks Manual for
+ information on how to clone the <filename>poky</filename>
+ repository and check out the appropriate branch for your work.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Initialize the Build Environment:</emphasis>
+ While in the root directory of the Source Directory (i.e.
+ <filename>poky</filename>), run the
+ <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
+ environment setup script to define the OpenEmbedded
+ build environment on your build host.
+ <literallayout class='monospaced'>
+ $ source &OE_INIT_FILE;
+ </literallayout>
+ Among other things, the script creates the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
+ which is <filename>build</filename> in this case
+ and is located in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
+ After the script runs, your current working directory
+ is set to the <filename>build</filename> directory.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Make Sure You Are Building an Installer for the Correct Machine:</emphasis>
+ Check to be sure that your
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+ variable in the <filename>local.conf</filename> file in your
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
+ matches the architecture for which you are building.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Make Sure Your SDK Machine is Correctly Set:</emphasis>
+ If you are building a toolchain designed to run on an
+ architecture that differs from your current development host
+ machine (i.e. the build machine), be sure that the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>
+ variable in the <filename>local.conf</filename> file in your
+ Build Directory is correctly set.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Build the SDK Installer:</emphasis>
+ To build the SDK installer for a standard SDK and populate
+ the SDK image, use the following command form.
+ Be sure to replace <replaceable>image</replaceable> with
+ an image (e.g. "core-image-sato"):
+ <literallayout class='monospaced'>
$ bitbake <replaceable>image</replaceable> -c populate_sdk
- </literallayout>
- You can do the same for the extensible SDK using this command:
- <literallayout class='monospaced'>
+ </literallayout>
+ You can do the same for the extensible SDK using this command
+ form:
+ <literallayout class='monospaced'>
$ bitbake <replaceable>image</replaceable> -c populate_sdk_ext
- </literallayout>
- These commands result in a SDK installer that contains the sysroot
- that matches your target root filesystem.
- </para>
+ </literallayout>
+ These commands result in a SDK installer that contains the
+ sysroot that matches your target root filesystem.</para>
- <para>
- When the <filename>bitbake</filename> command completes, the SDK
- installer will be in
- <filename>tmp/deploy/sdk</filename> in the Build Directory.
- <note><title>Notes</title>
- <itemizedlist>
- <listitem><para>
- By default, this toolchain does not build static binaries.
- If you want to use the toolchain to build these types of
- libraries, you need to be sure your SDK has the
- appropriate static development libraries.
- Use the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></ulink>
- variable inside your <filename>local.conf</filename> file
- to install the appropriate library packages in the SDK.
- Following is an example using <filename>libc</filename>
- static development libraries:
- <literallayout class='monospaced'>
+ <para>When the <filename>bitbake</filename> command completes,
+ the SDK installer will be in
+ <filename>tmp/deploy/sdk</filename> in the Build Directory.
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ By default, this toolchain does not build static
+ binaries.
+ If you want to use the toolchain to build these
+ types of libraries, you need to be sure your SDK
+ has the appropriate static development libraries.
+ Use the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></ulink>
+ variable inside your <filename>local.conf</filename>
+ file to install the appropriate library packages
+ in the SDK.
+ Following is an example using
+ <filename>libc</filename> static development
+ libraries:
+ <literallayout class='monospaced'>
TOOLCHAIN_TARGET_TASK_append = " libc-staticdev"
- </literallayout>
- </para></listitem>
- <listitem><para>
- For additional information on building the installer,
- see the
- <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
- wiki page.
- </para></listitem>
- </itemizedlist>
- </note>
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ For additional information on building the
+ installer, see the
+ <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
+ wiki page.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Run the Installer:</emphasis>
+ You can now run the SDK installer from
+ <filename>tmp/deploy/sdk</filename> in the Build Directory.
+ Following is an example:
+ <literallayout class='monospaced'>
+ $ cd ~/poky/build/tmp/deploy/sdk
+ $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
+ </literallayout>
+ During execution of the script, you choose the root location
+ for the toolchain.
+ See the
+ "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
+ section and the
+ "<link linkend='sdk-installed-extensible-sdk-directory-structure'>Installed Extensible SDK Directory Structure</link>"
+ section for more information.
+ </para></listitem>
+ </orderedlist>
</para>
</section>
@@ -126,55 +237,106 @@
After installing the toolchain, for some use cases you
might need to separately extract a root filesystem:
<itemizedlist>
- <listitem><para>You want to boot the image using NFS.
+ <listitem><para>
+ You want to boot the image using NFS.
</para></listitem>
- <listitem><para>You want to use the root filesystem as the
+ <listitem><para>
+ You want to use the root filesystem as the
target sysroot.
For example, the Eclipse IDE environment with the Eclipse
Yocto Plug-in installed allows you to use QEMU to boot
- under NFS.</para></listitem>
- <listitem><para>You want to develop your target application
+ under NFS.
+ </para></listitem>
+ <listitem><para>
+ You want to develop your target application
using the root filesystem as the target sysroot.
</para></listitem>
</itemizedlist>
</para>
<para>
- To extract the root filesystem, first <filename>source</filename>
- the cross-development environment setup script to establish
- necessary environment variables.
- If you built the toolchain in the Build Directory, you will find
- the toolchain environment script in the
- <filename>tmp</filename> directory.
- If you installed the toolchain by hand, the environment setup
- script is located in <filename>/opt/poky/&DISTRO;</filename>.
- </para>
+ Follow these steps to extract the root filesystem:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Locate and Download the Tarball for the Pre-Built
+ Root Filesystem Image File:</emphasis>
+ You need to find and download the root filesystem image
+ file that is appropriate for your target system.
+ These files are kept in the
+ <ulink url='&YOCTO_DL_URL;/releases/yocto/yocto-&DISTRO;/machines/'>Index of Releases</ulink>
+ in the "machines" directory.</para>
- <para>
- After sourcing the environment script, use the
- <filename>runqemu-extract-sdk</filename> command and provide the
- filesystem image.
- </para>
+ <para>The "machines" directory contains tarballs
+ (<filename>*.tar.bz2</filename>) for supported machines.
+ The directory also contains flattened root filesystem
+ image files (<filename>*.ext4</filename>), which you can use
+ with QEMU directly.</para>
- <para>
- Following is an example.
- The second command sets up the environment.
- In this case, the setup script is located in the
- <filename>/opt/poky/&DISTRO;</filename> directory.
- The third command extracts the root filesystem from a previously
- built filesystem that is located in the
- <filename>~/Downloads</filename> directory.
- Furthermore, this command extracts the root filesystem into the
- <filename>qemux86-sato</filename> directory:
- <literallayout class='monospaced'>
- $ cd ~
- $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
- $ runqemu-extract-sdk \
- ~/Downloads/core-image-sato-sdk-qemux86-2011091411831.rootfs.tar.bz2 \
- $HOME/qemux86-sato
- </literallayout>
- You could now point to the target sysroot at
- <filename>qemux86-sato</filename>.
+ <para>The pre-built root filesystem image files
+ follow these naming conventions:
+ <literallayout class='monospaced'>
+ core-image-<replaceable>profile</replaceable>-<replaceable>arch</replaceable>.tar.bz2
+
+ Where:
+ <replaceable>profile</replaceable> is the filesystem image's profile:
+ lsb, lsb-dev, lsb-sdk, lsb-qt3, minimal, minimal-dev, sato,
+ sato-dev, sato-sdk, minimal-initramfs, or sdk-ptest. For
+ information on these types of image profiles, see the
+ "Images" chapter in the Yocto Project Reference Manual.
+
+ <replaceable>arch</replaceable> is a string representing the target architecture:
+ beaglebone, edgerouter, genericx86, genericx86-64, mpc8315e-rdb,
+ qemuarm, qemuarm64, qemumips, qemumips64, qemuppc, qemux86, or
+ qemux86-64.
+
+ </literallayout>
+ The root filesystems provided by the Yocto Project are based
+ off of the <filename>core-image-sato</filename> and
+ <filename>core-image-minimal</filename> images.
+ </para>
+
+ <para>For example, if your target hardware system is a
+ BeagleBone board and your image is a
+ <filename>core-image-minimal</filename> image, you need
+ to download the following root filesystem image file:
+ <literallayout class='monospaced'>
+ core-image-minimal-beaglebone.tar.bz2
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Initialize the Cross-Development Environment:</emphasis>
+ You must <filename>source</filename>
+ the cross-development environment setup script to establish
+ necessary environment variables.</para>
+
+ <para>This script is located in the top-level directory in
+ which you installed the toolchain (e.g.
+ <filename>poky_sdk</filename>).</para>
+
+ <para>Following is an example for the Core2 64-bit
+ architecture:
+ <literallayout class='monospaced'>
+ $ source ~/poky_sdk/environment-setup-core2-64-poky-linux
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Extract the Root Filesystem:</emphasis>
+ Use the <filename>runqemu-extract-sdk</filename> command
+ and provide the root filesystem image.</para>
+
+ <para>Following is an example command that extracts the root
+ filesystem from a previously built root filesystem image that
+ was downloaded from the
+ <ulink url='&YOCTO_DOCS_REF_URL;#index-downloads'>Index of Releases</ulink>.
+ This command extracts the root filesystem into the
+ <filename>core2-64-sato</filename> directory:
+ <literallayout class='monospaced'>
+ $ runqemu-extract-sdk ~/Downloads/core-image-sato-core2-64.tar.bz2 ~/core2-64-sato
+ </literallayout>
+ You could now point to the target sysroot at
+ <filename>core2-64-sato</filename>.
+ </para></listitem>
+ </orderedlist>
</para>
</section>
diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-eclipse-project.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-eclipse-project.xml
new file mode 100644
index 0000000..bdb8344
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-eclipse-project.xml
@@ -0,0 +1,1211 @@
+<!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-eclipse-project'>
+
+ <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 chapter 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_KERNEL_DEV_URL;#using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</ulink>"
+ section in the Yocto Project Linux Kernel
+ 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 SDK 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 Tasks 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-latest-yp-eclipse-plug-in'>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/neon/'>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>&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_REF_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_REF_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 when you either built
+ it or downloaded it.
+ <note>
+ If you downloaded the root filesystem
+ for the target hardware rather than
+ built it, you must download the
+ <filename>sato-sdk</filename> image
+ in order to build any c/c++ projects.
+ </note>
+ 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_REF_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_REF_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 ‘<-m 256 -full-screen>’
+ </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 Tasks 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 a 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><title>Tips</title>
+ <itemizedlist>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ <listitem><para>
+ If browsing to a directory fails or times
+ out, but you can
+ <filename>ssh</filename> into your QEMU
+ or target from the command line and you
+ have proxies set up, it is likely that
+ Eclipse is sending the SSH traffic to a
+ proxy.
+ In this case, either use TCF , or click on
+ "Configure proxy settings" in the
+ connection dialog and add the target IP
+ address to the "bypass proxy" section.
+ You might also need to change
+ "Active Provider" from Native to Manual.
+ </para></listitem>
+ </itemizedlist>
+ </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>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-extensible.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-extensible.xml
index 1496476..444d816 100644
--- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-extensible.xml
+++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-extensible.xml
@@ -15,7 +15,7 @@
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>.
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>.
<note>
For a side-by-side comparison of main features supported for an
extensible SDK as compared to a standard SDK, see the
@@ -235,15 +235,28 @@
you build, test and package software within the extensible SDK, and
optionally integrate it into an image built by the OpenEmbedded
build system.
+ <note><title>Tip</title>
+ The use of <filename>devtool</filename> is not limited to
+ the extensible SDK.
+ You can use <filename>devtool</filename> to help you easily
+ develop any project whose build output must be part of an
+ image built using the OpenEmbedded build system.
+ </note>
</para>
<para>
The <filename>devtool</filename> command line is organized
similarly to
- <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> in that it has a
+ <ulink url='&YOCTO_DOCS_REF_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>
+ See the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename> Quick Reference</ulink>"
+ in the Yocto Project Reference Manual for a
+ <filename>devtool</filename> quick reference.
+ </note>
</para>
<para>
@@ -293,7 +306,7 @@
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>
+ <ulink url='&YOCTO_DOCS_REF_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
@@ -612,7 +625,7 @@
extracts them.
Providing the <replaceable>srctree</replaceable>
argument instructs <filename>devtool</filename> where
- place the extracted source.</para>
+ to place the extracted source.</para>
<para>Within workspace, <filename>devtool</filename>
creates an append file for the recipe.
@@ -1262,7 +1275,7 @@
<title>Working With Recipes</title>
<para>
- When building a recipe with <filename>devtool build</filename> the
+ When building a recipe with <filename>devtool build</filename>, the
typical build progression is as follows:
<orderedlist>
<listitem><para>
diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-intro.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-intro.xml
index 6840169..b6925fa 100644
--- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-intro.xml
+++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-intro.xml
@@ -9,8 +9,8 @@
<title>Introduction</title>
<para>
- Welcome to the Yocto Project Software Development Kit (SDK)
- Developer's Guide.
+ Welcome to the Yocto Project Application Development and the
+ Extensible Software Development Kit (eSDK) manual.
This manual provides information that explains how to use both the
Yocto Project extensible and standard SDKs to develop
applications and images.
@@ -52,7 +52,7 @@
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>.
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>.
</para>
<para>
@@ -93,7 +93,7 @@
matching sysroots (target and native) all built by the
OpenEmbedded build system (e.g. the SDK).
The toolchain and sysroots are based on a
- <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
+ <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
configuration and extensions,
which allows you to cross-develop on the host machine for the
target hardware.
@@ -207,7 +207,7 @@
<para>
The
- <ulink url='&YOCTO_DOCS_DEV_URL;#cross-development-toolchain'>Cross-Development Toolchain</ulink>
+ <ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain'>Cross-Development Toolchain</ulink>
consists of a cross-compiler, cross-linker, and cross-debugger
that are used to develop user-space applications for targeted
hardware.
@@ -215,7 +215,7 @@
built-in <filename>devtool</filename> functionality.
This toolchain is created by running a SDK installer script
or through a
- <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
that is based on your Metadata configuration or extension for
your targeted device.
The cross-toolchain works with a matching target sysroot.
@@ -245,16 +245,15 @@
<listitem><para>
If you have cloned the <filename>poky</filename> Git
repository to create a
- <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
and you have sourced the environment setup script, QEMU is
installed and automatically available.
</para></listitem>
<listitem><para>
If you have downloaded a Yocto Project release and unpacked
- it to create a
- <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
- and you have sourced the environment setup script, QEMU is
- installed and automatically available.
+ it to create a Source Directory and you have sourced the
+ environment setup script, QEMU is installed and
+ automatically available.
</para></listitem>
<listitem><para>
If you have installed the cross-toolchain tarball and you
@@ -295,8 +294,8 @@
For information about the application development workflow that
uses the Eclipse IDE and for a detailed example of how to install
and configure the Eclipse Yocto Project Plug-in, see the
- "<link linkend='sdk-developing-applications-using-eclipse'>Developing Applications Using <trademark class='trade'>Eclipse</trademark></link>"
- section.
+ "<link linkend='sdk-eclipse-project'>Developing Applications Using <trademark class='trade'>Eclipse</trademark></link>"
+ Chapter.
</para>
</section>
@@ -385,7 +384,7 @@
to download and learn about the emulator.
See the
"<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
- chapter in the Yocto Project Development Manual
+ chapter in the Yocto Project Development Tasks Manual
for information on using QEMU within the Yocto
Project.</para></listitem>
</orderedlist>
diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual.xml
index 5c28e34..7fc0472 100644
--- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual.xml
+++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual.xml
@@ -17,14 +17,14 @@
</mediaobject>
<title>
- Yocto Project Software Development Kit (SDK) Developer's Guide
+ Yocto Project Application Development and the Extensible Software Development Kit (eSDK)
</title>
<authorgroup>
<author>
<firstname>Scott</firstname> <surname>Rifenbark</surname>
<affiliation>
- <orgname>Scotty's Documentation Services, LLC</orgname>
+ <orgname>Scotty's Documentation Services, INC</orgname>
</affiliation>
<email>srifenbark@gmail.com</email>
</author>
@@ -47,24 +47,19 @@
<revremark>Released with the Yocto Project 2.3 Release.</revremark>
</revision>
<revision>
- <revnumber>2.3.1</revnumber>
- <date>June 2017</date>
- <revremark>Released with the Yocto Project 2.3.1 Release.</revremark>
+ <revnumber>2.4</revnumber>
+ <date>October 2017</date>
+ <revremark>Released with the Yocto Project 2.4 Release.</revremark>
</revision>
<revision>
- <revnumber>2.3.2</revnumber>
- <date>September 2017</date>
- <revremark>Released with the Yocto Project 2.3.2 Release.</revremark>
- </revision>
- <revision>
- <revnumber>2.3.3</revnumber>
+ <revnumber>2.4.1</revnumber>
<date>January 2018</date>
- <revremark>Released with the Yocto Project 2.3.3 Release.</revremark>
+ <revremark>Released with the Yocto Project 2.4.1 Release.</revremark>
</revision>
<revision>
- <revnumber>2.3.4</revnumber>
- <date>April 2018</date>
- <revremark>Released with the Yocto Project 2.3.4 Release.</revremark>
+ <revnumber>2.4.2</revnumber>
+ <date>March 2018</date>
+ <revremark>Released with the Yocto Project 2.4.2 Release.</revremark>
</revision>
</revhistory>
@@ -81,28 +76,29 @@
<note><title>Manual Notes</title>
<itemizedlist>
<listitem><para>
- For the latest version of the Yocto Project Software
- Development Kit (SDK) Developer's Guide associated with
- this Yocto Project release (version &YOCTO_DOC_VERSION;),
- see the Yocto Project Software Development Kit (SDK)
- Developer's Guide from the
+ This version of the
+ <emphasis>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</emphasis>
+ manual is for the &YOCTO_DOC_VERSION; release of the
+ Yocto Project.
+ To be sure you have the latest version of the manual
+ for this release, use the manual from the
<ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>.
</para></listitem>
<listitem><para>
- This version of the manual is version
- &YOCTO_DOC_VERSION;.
- For later releases of the Yocto Project (if they exist),
- go to the
+ For manuals associated with other releases of the Yocto
+ Project, go to the
<ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
and use the drop-down "Active Releases" button
- and choose the Yocto Project version for which you want
- the manual.
+ and choose the manual associated with the desired
+ Yocto Project.
</para></listitem>
<listitem><para>
- For an in-development version of the Yocto Project
- Software Development Kit (SDK) Developer's Guide, see
- <ulink url='&YOCTO_DOCS_URL;/latest/sdk-manual/sdk-manual.html'></ulink>.
- </para></listitem>
+ To report any inaccuracies or problems with this
+ manual, send an email to the Yocto Project
+ discussion group at
+ <filename>yocto@yoctoproject.com</filename> or log into
+ the freenode <filename>#yocto</filename> channel.
+ </para></listitem>
</itemizedlist>
</note>
@@ -118,6 +114,8 @@
<xi:include href="sdk-working-projects.xml"/>
+ <xi:include href="sdk-eclipse-project.xml"/>
+
<xi:include href="sdk-appendix-obtain.xml"/>
<xi:include href="sdk-appendix-customizing.xml"/>
diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-working-projects.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-working-projects.xml
index 54bc4d7..6965e3f 100644
--- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-working-projects.xml
+++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-working-projects.xml
@@ -10,8 +10,9 @@
You can use the SDK toolchain directly with Makefile,
Autotools, and <trademark class='trade'>Eclipse</trademark> based
projects.
- This chapter covers information specific to each of these types of
- projects.
+ This chapter covers the first two, while the
+ "<link linkend='sdk-eclipse-project'>Developing Applications Using <trademark class='trade'>Eclipse</trademark></link>"
+ Chapter covers the latter.
</para>
<section id='autotools-based-projects'>
@@ -276,1184 +277,6 @@
</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 SDK 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-latest-yp-eclipse-plug-in'>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/neon/'>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>&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 ‘<-m 256 -full-screen>’
- </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
