documentation/adt-manual: Rewrite for Indigo version of Eclipse.

These edits are extensive and cross into two files: adt-prepare.xml
and adt-eclipse.xml.  This is the first pass of a large re-write
to bring the examples up-to-date using the preferred version of
the Eclipse IDE (Indego 3.7).  Much has changed.

(From yocto-docs rev: 57c1f905c6d66268a498e013193d003596f2303d)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark 2011-09-09 09:38:02 -07:00 committed by Richard Purdie
parent 826a53adf6
commit 0bd5bba8ab
2 changed files with 217 additions and 174 deletions

View File

@ -29,30 +29,36 @@
<para>
To develop within the Eclipse IDE, you need to do the following:
<orderedlist>
<listitem><para>Be sure the optimal version of Eclipse IDE
<listitem><para>Be sure the optimal version of the Eclipse IDE
is installed.</para></listitem>
<listitem><para>Install the Eclipse Plug-in requirements prior to installing
the Eclipse Yocto Plug-in.</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>
</para>
<section id='installing-eclipse-ide'>
<title>Installing Eclipse IDE</title>
<title>Installing the Eclipse IDE</title>
<para>
It is recommended that you have the Indigo 3.7 version of the
Eclipse IDE installed on your development system.
If you dont have this version, you can find it at
<ulink url='http://www.eclipse.org/downloads'></ulink>.
From that site, choose the Eclipse Classic version.
From that site, choose the Eclipse Classic version particular to your development
host.
This version contains the Eclipse Platform, the Java Development
Tools (JDT), and the Plug-in Development Environment.
</para>
<para>
Once you have downloaded the tarball, extract it into a clean
directory and complete the installation.
directory.
For example, the following command unpacks and installs the Eclipse IDE
into a clean directory named <filename>eclipse</filename>:
<literallayout class='monospaced'>
$ tar -xzvf ~/Downloads/Eclipse-SDK-3.7-linux-gtk-x86_64.tar.gz
</literallayout>
</para>
<para>
@ -81,72 +87,97 @@
</para>
</section>
<section id='installing-required-plug-ins-and-the-eclipse-yocto-plug-in'>
<title>Installing Required Plug-ins and the Eclipse Yocto Plug-in</title>
<section id='configuring-the-eclipse-ide'>
<title>Configuring the Eclipse IDE</title>
<para>
Before installing the Yocto Plug-in, you need to be sure that the
<filename>CDT 8.0</filename>, <filename>RSE 3.2</filename>, and
<filename>Autotools</filename> plug-ins are all installed in the
following order.
After installing these three plug-ins, you can install the Eclipse Yocto Plug-in.
Use the following URLs for the plug-ins:
Before installing and configuring the Eclipse Yocto Plug-in, you need to configure
the Eclipse IDE.
Follow these general steps to configure Eclipse:
<orderedlist>
<listitem><para><emphasis>
<ulink url='http://download.eclipse.org/tools/cdt/releases/indigo/'>CDT 8.0:</ulink>
</emphasis> For <filename>CDT main features</filename>, select the
checkbox so you get all items.
For <filename>CDT optional features</filename> expand the selections and check
<filename>C/C++ Remote Launch</filename>.</para></listitem>
<listitem><para><emphasis>
<ulink url='http://download.eclipse.org/tm/updates/3.2'>RSE 3.2:</ulink></emphasis>
Check the box next to <filename>TM and RSE Main Features</filename> so you select all
those items.
Note that all items in the main features depend on 3.2.1 version.
Expand the items under <filename>TM and RSE Uncategorized 3.2.1</filename> and
select the following: <filename>Remote System Explorer End-User Runtime</filename>,
<filename>Remote System Explorer Extended SDK</filename>,
<filename>Remote System Explorer User Actions</filename>,
<filename>RSE Core</filename>, <filename>RSE Terminals UI</filename>,
and <filename>Target Management Terminal</filename>.</para></listitem>
<listitem><para><emphasis>
<ulink url='http://download.eclipse.org/technology/linuxtools/update/'>Autotools:</ulink>
</emphasis> Expand the items under “Linux Tools” and select “Autotools support for
CDT (Incubation)”.</para></listitem>
<listitem><para><emphasis>
<ulink url='http://www.yoctoproject.org/downloads/eclipse-plugin/1.1'>Yocto Plug-in:
</ulink></emphasis> Check the box next to
<filename>Development tools &amp; SDKs for Yocto Linux</filename>
to select all the items.</para></listitem>
</orderedlist>
</para>
<para>
Follow these general steps to install an Eclipse plug-in:
<orderedlist>
<listitem><para>From within the Eclipse IDE, select the
<filename>Install New Software</filename> item from the <filename>Help</filename>
menu.</para></listitem>
<listitem><para>Click <filename>Add…</filename> in the
<filename>Work with:</filename> area.</para></listitem>
<listitem><para>Enter the URL for the repository and leave the <filename>Name</filename>
field blank.</para></listitem>
<listitem><para>Check the boxes next to the software you need to
install and then complete the installation.
For information on the specific software packages you need to include,
see the previous list.</para></listitem>
<listitem><para>Start the Eclipse IDE.</para></listitem>
<listitem><para>Select "Install New Software" from the "Help" pull-down menu.
</para></listitem>
<listitem><para>Select <filename>Indego - http://download.eclipse.org/releases/indego</filename>
from the "Work with:" pull-down menu.</para></listitem>
<listitem><para>Expand the box next to <filename>Programming Languages</filename>
and select the <filename>Autotools Support for CDT (incubation)</filename>
and <filename>C/C++ Development Tools</filename> boxes.</para></listitem>
<listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem>
<listitem><para>Select "Install New Software" from the "Help" pull-down menu.</para></listitem>
<listitem><para>After the Eclipse IDE restarts, click the
"Available Software Sites" link.</para></listitem>
<listitem><para>Check the box next to
<filename>http://download.eclipse.org/tm/updates/3.3</filename>
and click "OK".</para></listitem>
<listitem><para>Select <filename>http://download.eclipse.org/tm/updates/3.3</filename>
from the "Work with:" pull-down menu.</para></listitem>
<listitem><para>Check the box next to <filename>TM and RSE Main Features</filename>.
</para></listitem>
<listitem><para>Expand the box next to <filename>TM and RSE Optional Add-ons</filename>
and select every item except <filename>RSE Unit Tests</filename> and
<filename>RSE WinCE Services (incubation)</filename>.</para></listitem>
<listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem>
<listitem><para>After the Eclipse IDE restarts, click the
"Available Software Sites" link.</para></listitem>
<listitem><para>Check the box next to
<filename>http://download.eclipse.org/tools/cdt/releases/indego</filename>
and click "OK".</para></listitem>
<listitem><para>Select <filename>http://download.eclipse.org/tools/cdt/releases/indego</filename>
from the "Work with:" pull-down menu.</para></listitem>
<listitem><para>Check the box next to <filename>CDT Main Features</filename>.
</para></listitem>
<listitem><para>Expand the box next to <filename>CDT Optional Features</filename>
and select <filename>C/C++ Remote Launch</filename> and
<filename>Target Communication Framework (incubation)</filename>.</para></listitem>
<listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem>
</orderedlist>
</para>
</section>
<section id='configuring-the-plug-in'>
<title>Configuring the Plug-in</title>
<section id='installing-the-eclipse-yocto-plug-in'>
<title>Installing the Eclipse Yocto Plug-in</title>
<para>
Configuring the Eclipse Yocto Plug-in involves choosing the Cross
Compiler Options, selecting the Target Architecture, and choosing
the Target Options.
The settings you choose become the default settings for all projects.
To install the Eclipse Yocto Plug-in, follow these special steps.
The steps are WIP and are not final.
Once they are final they will be replaced with the actual steps:
<orderedlist>
<listitem><para>Open a shell and create a Git repository with:
<literallayout class='monospaced'>
$ git clone git://git.yoctoproject.org/yocto-eclipse yocto-eclipse
</literallayout></para></listitem>
<listitem><para>In Eclipse, select "Import" from the "File" menu.</para></listitem>
<listitem><para>Expand the "General" box and pick "existing projects into workspace".
</para></listitem>
<listitem><para>Select the root directory and browse to "~/yocto-eclipse/plugins".
</para></listitem>
<listitem><para>There will be three things there.
Select each one and install one at a time.
Do all three.</para></listitem>
<listitem><para>Restart everything.</para></listitem>
</orderedlist>
</para>
<para>
At this point I should be able to invoke Eclipse from the shell using the following:
<literallayout class='monospaced'>
$ cd ~/eclipse
$ ./eclipse -vmargs -XX:PermSize=256M
</literallayout>
What is shown is the default projects in the left pane.
I should be able to right-click on one of these and run as an Eclipse application to
bring up the Eclipse instance again with the Eclipse Yocto Plug-in working.
</para>
</section>
<section id='configuring-the-eclipse-yocto-plug-in'>
<title>Configuring the Eclipse Yocto Plug-in</title>
<para>
Configuring the 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>
@ -156,7 +187,7 @@
<itemizedlist>
<listitem><para>Choose <filename>Windows -&gt; Preferences</filename> to display
the Preferences Dialog</para></listitem>
<listitem><para>Click <filename>Yocto SDK</filename></para></listitem>
<listitem><para>Click <filename>Yocto ADT</filename></para></listitem>
</itemizedlist>
</para>
@ -164,86 +195,90 @@
<title>Configuring the Cross-Compiler Options</title>
<para>
Choose between <filename>Stand-alone Prebuilt Toolchain</filename>
and <filename>Build System Derived Toolchain</filename> for Cross
Compiler Options.
To configure the Cross Compiler 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><filename>Stand-alone Prebuilt Toolchain:</filename></emphasis>
Select this mode
when you are not concerned with building a target image or you do not have
a Yocto Project build tree on your development system.
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.
When you use <filename>Stand-alone Prebuilt Toolchain</filename>,
you are using the toolchain installed
in the <filename>/opt/poky</filename> directory.</para></listitem>
<listitem><para><emphasis><filename>Build System Derived Toolchain:</filename></emphasis>
Select this mode
if you are building images for target hardware or your
development environment already has a Yocto Project build tree.
In this case, you likely already have a Yocto Project build tree on
your system or you (or someone else) will be building one.
When you select <filename>Build System Derived Toolchain</filename>,
you are using the toolchain bundled
inside the Yocto Project build tree.
If you use this mode, you must also supply the Yocto Project build directory
in the <filename>Preferences Dialog</filename>.</para></listitem>
<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 mode 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.
</para></listitem>
<listitem><para><emphasis>
<filename>Build System Derived Toolchain:</filename></emphasis>
Select this mode if the cross-toolchain has been installed and built
as part of the Yocto Project build tree.
When you select <filename>Build system derived toolchain</filename>,
you are using the toolchain bundled
inside the Yocto Project build tree.
</para></listitem>
</itemizedlist>
</para></listitem>
<listitem><para><emphasis>Point to the Toolchain:</emphasis>
If you are using a stand-alone pre-built toolchain, you should be pointing to the
<filename>/opt/poky/$SDKVERSION</filename> directory.
This is the location for toolchains installed by the ADT Installer or by hand.
Sections <link linkend='configuring-and-running-the-adt-installer-script'>
Configuring and Running the ADT Installer Script</link> and
<link linkend='using-an-existing-toolchain-tarball'>
Using a Cross-Toolchain Tarball</link> describe two ways to install
a stand-alone cross-toolchain in the
<filename>/opt/poky</filename> directory.
<note>It is possible to install a stand-alone cross-toolchain in a directory
other than <filename>/opt/poky</filename>.
However, doing so is discouraged.</note></para>
<para>If you are using a system-derived toolchain, the path you provide
for the <filename>Toolchain Root Location</filename>
field is the Yocto Project's build directory.
See section <link linkend='using-the-toolchain-from-within-the-build-tree'>
Using BitBake and the Yocto Project Build Tree</link> for
information on how to install the toolchain into the Yocto
Project build tree.</para></listitem>
<listitem><para><emphasis>Specify the Sysroot Location:</emphasis>
This location is where the root filesystem for the
target hardware is created on the development system by the ADT Installer.
The QEMU user-space tools, the
NFS boot process, and the cross-toolchain all use the sysroot location.
</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='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#building-image'> Building an Image</ulink> section of the
<ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html'>
The Yocto Project Quick Start</ulink> for more information.</para></listitem>
</itemizedlist>
</para>
</section>
<section id='configuring-the-sysroot'>
<title>Configuring the Sysroot</title>
<para>
Specify the sysroot location, which is where the root filesystem for the
target hardware is created on the development system by the ADT Installer.
The QEMU user-space tools, the
NFS boot process, and the cross-toolchain all use the sysroot location
regardless of whether you select
(<filename>Stand-alone Prebuilt Toolchain</filename> or
<filename>Build System Derived Toolchain</filename>).
</para>
</section>
<section id='selecting-the-target-architecture'>
<title>Selecting the Target Architecture</title>
<para>
Use the pull-down <filename>Target Architecture</filename> menu and select the
target architecture.
</para>
<para>
The target architecture is the type of hardware you are
going to use or emulate.
This pull-down menu should have the supported architectures.
If the architecture you need is not listed in the menu, you
will need to re-visit the section "<link linkend='adt-prepare'>Preparing to Use
the Application Development Toolkit (ADT)</link>" earlier in this document.
</para>
</section>
<section id='choosing-the-target-options'>
<title>Choosing the Target Options</title>
<section id='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 use actual hardware.
can choose to run your image on actual hardware.
<itemizedlist>
<listitem><para><emphasis><filename>External HW:</filename></emphasis> Select this option
if you will be using actual hardware.</para></listitem>
<listitem><para><emphasis><filename>QEMU:</filename></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 select <filename>Build System Derived Toolchain</filename>,
<para>If you selected <filename>Build system derived toolchain</filename>,
the target kernel you built will be located in the
Yocto Project build tree in <filename>tmp/deploy/images</filename> directory.
If you select <filename>Stand-alone Prebuilt Toolchain</filename>, the
pre-built kernel you downloaded is located
If you selected <filename>Standalone pre-built toolchain</filename>, 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.
@ -259,8 +294,11 @@
serial &lt;-m 256 -full-screen&gt;
</literallayout></para>
<para>
Regardless of the mode, Sysroot is already defined in the “Sysroot”
field.</para></listitem>
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><filename>External HW:</filename></emphasis> Select this option
if you will be using actual hardware.</para></listitem>
</itemizedlist>
</para>
@ -276,9 +314,9 @@
<para>
You can create two types of projects: Autotools-based, or Makefile-based.
This section describes how to create autotools-based projects from within
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 section
For information on creating Makefile-based projects in a terminal window, see the section
"<link linkend='using-the-command-line'>Using the Command Line</link>".
</para>
@ -289,21 +327,21 @@
<listitem><para>Select <filename>File -&gt; New -&gt; Project</filename>.</para></listitem>
<listitem><para>Double click <filename>CC++</filename>.</para></listitem>
<listitem><para>Double click <filename>C Project</filename> to create the project.</para></listitem>
<listitem><para>Double click <filename>Yocto SDK Project</filename>.</para></listitem>
<listitem><para>Expand <filename>Yocto ADT Project</filename>.</para></listitem>
<listitem><para>Select <filename>Hello World ANSI C Autotools Project</filename>.
This is an Autotools-based project based on a Yocto Project template.</para></listitem>
<listitem><para>Put a name in the <filename>Project name:</filename> field.</para></listitem>
<listitem><para>Put a name in the <filename>Project name:</filename> field.
Do not use hyphens as part of the name.</para></listitem>
<listitem><para>Click <filename>Next</filename>.</para></listitem>
<listitem><para>Add information in the <filename>Author</filename> field.</para></listitem>
<listitem><para>Use <filename>GNU General Public License v2.0</filename>
for the License.</para></listitem>
<listitem><para>Add information in the <filename>Author</filename> and
<filename>Copyright notice</filename> fields.</para></listitem>
<listitem><para>Be sure the <filename>License</filename> field is correct.</para></listitem>
<listitem><para>Click <filename>Finish</filename>.</para></listitem>
<listitem><para>Answer <filename>Yes</filename> to the open perspective prompt.</para></listitem>
<listitem><para>In the Project Explorer expand your project.</para></listitem>
<listitem><para>Expand <filename>src</filename>.</para></listitem>
<listitem><para>Double click on your source file and the code appears
in the window.
This is the template.</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>
@ -312,25 +350,25 @@
<title>Configuring the Cross-Toolchains</title>
<para>
The previous section, "<link linkend='configuring-the-cross-compiler-options'>
Configuring the Cross-Compiler Options</link>", set up the default project
The previous section, "<link linkend='configuring-the-eclipse-yocto-plug-in'>
Configuring the Eclipse Yocto Plug-in</link>", set up the default project
configurations.
You can change these settings for a given project by following these steps:
<orderedlist>
<listitem><para>Select <filename>Project -&gt; Invoke Yocto Tools -&gt; Reconfigure Yocto</filename>:
This selection brings up the project's <filename>Yocto Settings</filename> Dialog.
Settings are inherited from the default project configuration.
<listitem><para>Select <filename>Window -&gt; Preferences</filename>:
This selection brings up the <filename>Preferences</filename> Dialog.
If the Yocto ADT Preferences are not automatically displayed, you can navigate to
that dialog by selection <filename>Yocto ADT</filename> in the left-hand
panel.</para>
<para>Yocto ADT Settings are inherited from the default project configuration.
The information in this dialog is identical to that chosen earlier
for the <filename>Cross Compiler Option</filename>
(<filename>Stand-alone Prebuilt Toolchain</filename> or
<filename>Build System Derived Toolchain</filename>),
the <filename>Target Architecture</filename>, and the
<filename>Target Options</filename>.
The settings are inherited from the Yocto Plug-in configuration performed
after installing the plug-in.</para></listitem>
<listitem><para><filename>Select Project -&gt; Reconfigure Project</filename>:
This selection runs the <filename>autogen.sh</filename> in the workspace for your project.
The script runs <filename>libtoolize</filename>, <filename>aclocal</filename>,
for the Cross Compiler Options and Target Options as described in
<link linkend='configuring-the-eclipse-yocto-plug-in'>
Configuring the Eclipse Yocto Plug-in</link> section.</para></listitem>
<listitem><para>Select <filename>Project -&gt; Reconfigure Project</filename>:
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>.</para></listitem>
@ -353,19 +391,12 @@
<para>
To start the QEMU emulator from within Eclipse, follow these steps:
<orderedlist>
<listitem><para>Select <filename>Run -&gt; External Tools -&gt; External Tools
Configurations...</filename>.
This selection brings up the <filename>External Tools Configurations</filename>
Dialog.</para></listitem>
<listitem><para>Go to the left navigation area and expand <filename>Program</filename>.
You should find the image listed.
For example, <filename>qemu-x86_64-poky-linux</filename>.</para></listitem>
<listitem><para>Click on the image.
This brings up a new environment in the main area of the
<filename>External Tools Configurations</filename> Dialog.
The Main tab is selected.</para></listitem>
<listitem><para>Click <filename>Run</filename> next.
This brings up a shell window.</para></listitem>
<listitem><para>Expose the <filename>Run -&gt; External Tools -&gt; External Tools
Configurations...</filename> menu.
Your image should appear as a selectable menu item.
</para></listitem>
<listitem><para>Select your image from the menu.
Doing so launches a new window.</para></listitem>
<listitem><para>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>

View File

@ -280,6 +280,11 @@
</para></listitem>
</orderedlist>
</para>
<para>
After installing the toolchain, you must locate the target sysroot tarball and unpack it
into a location of your choice.
</para>
</section>
<section id='using-the-toolchain-from-within-the-build-tree'>
@ -321,6 +326,11 @@
</para></listitem>
</orderedlist>
</para>
<para>
After installing the toolchain, you must locate the target sysroot tarball and unpack
it in a directory of your choice.
</para>
</section>
</section>
@ -359,8 +369,10 @@
hardware or the QEMU emulator.
That means you either have to build them or know where to get them.
You can find lots of details on how to get or build images and kernels for your
architecture in
<ulink url='http://www.yoctoproject.org/docs/1.1/yocto-quick-start/yocto-project-qs.html'>
architecture in the
<ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#building-image'>
Building an Image</ulink> section of the
<ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html'>
The Yocto Project Quick Start</ulink>.
<note>
The Yocto Project provides basic kernels and filesystem images for several