diff options
| author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2012-07-23 11:23:56 -0700 |
|---|---|---|
| committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2012-07-24 10:35:34 +0100 |
| commit | 41c7020d7ae6c81e8fa092f2a0c8e0c3ac976a62 (patch) | |
| tree | ebc327616f0ceff8ba21fbf1004e6c85038e3982 | |
| parent | fad4b8fbbdab7a9701e63475317a804188376c27 (diff) | |
| download | poky-41c7020d7ae6c81e8fa092f2a0c8e0c3ac976a62.tar.gz | |
documentation: Moved the Eclipse chapter to the YP Dev Manual.
The detailed chapter that describes how to install and configure
the Eclipse Yocto Plug-in has been moved to become a subsection of
the "Workflow" chapter in the YP Development Manual. This commit
accomplished the bulk move, edits to integrate the information,
and fixes to all cross-references. Moving the chapter creates a
sectioning issue in the YP Development manual that results in
subsections that are six levels deep. Not ideal. Will look at
fixing these with a subsequent commit.
(From yocto-docs rev: e6abff8f578f2cf6997895260f607395281ae8e8)
Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
| -rw-r--r-- | documentation/adt-manual/adt-eclipse.xml | 740 | ||||
| -rw-r--r-- | documentation/adt-manual/adt-intro.xml | 20 | ||||
| -rw-r--r-- | documentation/adt-manual/adt-manual.xml | 2 | ||||
| -rw-r--r-- | documentation/dev-manual/dev-manual-model.xml | 739 |
4 files changed, 754 insertions, 747 deletions
diff --git a/documentation/adt-manual/adt-eclipse.xml b/documentation/adt-manual/adt-eclipse.xml deleted file mode 100644 index 4d400ad6df..0000000000 --- a/documentation/adt-manual/adt-eclipse.xml +++ /dev/null | |||
| @@ -1,740 +0,0 @@ | |||
| 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | ||
| 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | ||
| 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | ||
| 4 | |||
| 5 | <chapter id='adt-eclipse'> | ||
| 6 | <title>Working Within Eclipse</title> | ||
| 7 | |||
| 8 | <para> | ||
| 9 | The Eclipse IDE is a popular development environment and it fully supports | ||
| 10 | development using the Yocto Project. | ||
| 11 | When you install and configure the Eclipse Yocto Project Plug-in into | ||
| 12 | the Eclipse IDE, you maximize your Yocto Project experience. | ||
| 13 | Installing and configuring the Plug-in results in an environment that | ||
| 14 | has extensions specifically designed to let you more easily develop software. | ||
| 15 | These extensions allow for cross-compilation, deployment, and execution of | ||
| 16 | your output into a QEMU emulation session. | ||
| 17 | You can also perform cross-debugging and profiling. | ||
| 18 | The environment also supports a suite of tools that allows you to perform | ||
| 19 | remote profiling, tracing, collection of power data, collection of | ||
| 20 | latency data, and collection of performance data. | ||
| 21 | </para> | ||
| 22 | <para> | ||
| 23 | This section describes how to install and configure the Eclipse IDE | ||
| 24 | Yocto Plug-in and how to use it to develop your application. | ||
| 25 | </para> | ||
| 26 | |||
| 27 | <section id='setting-up-the-eclipse-ide'> | ||
| 28 | <title>Setting Up the Eclipse IDE</title> | ||
| 29 | |||
| 30 | <para> | ||
| 31 | To develop within the Eclipse IDE, you need to do the following: | ||
| 32 | <orderedlist> | ||
| 33 | <listitem><para>Install the optimal version of the Eclipse IDE.</para></listitem> | ||
| 34 | <listitem><para>Configure the Eclipse IDE.</para></listitem> | ||
| 35 | <listitem><para>Install the Eclipse Yocto Plug-in.</para></listitem> | ||
| 36 | <listitem><para>Configure the Eclipse Yocto Plug-in.</para></listitem> | ||
| 37 | </orderedlist> | ||
| 38 | <note> | ||
| 39 | Do not install Eclipse from your distribution's package repository. | ||
| 40 | Be sure to install Eclipse from the official Eclipse download site as directed | ||
| 41 | in the next section. | ||
| 42 | </note> | ||
| 43 | </para> | ||
| 44 | |||
| 45 | <section id='installing-eclipse-ide'> | ||
| 46 | <title>Installing the Eclipse IDE</title> | ||
| 47 | |||
| 48 | <para> | ||
| 49 | It is recommended that you have the Indigo 3.7.2 version of the | ||
| 50 | Eclipse IDE installed on your development system. | ||
| 51 | If you don’t have this version, you can find it at | ||
| 52 | <ulink url='&ECLIPSE_MAIN_URL;'></ulink>. | ||
| 53 | From that site, choose the Eclipse Classic version particular to your development | ||
| 54 | host. | ||
| 55 | This version contains the Eclipse Platform, the Java Development | ||
| 56 | Tools (JDT), and the Plug-in Development Environment. | ||
| 57 | </para> | ||
| 58 | |||
| 59 | <para> | ||
| 60 | Once you have downloaded the tarball, extract it into a clean | ||
| 61 | directory. | ||
| 62 | For example, the following commands unpack and install the Eclipse IDE | ||
| 63 | tarball found in the <filename>Downloads</filename> area | ||
| 64 | into a clean directory using the default name <filename>eclipse</filename>: | ||
| 65 | <literallayout class='monospaced'> | ||
| 66 | $ cd ~ | ||
| 67 | $ tar -xzvf ~/Downloads/eclipse-SDK-3.7.2-linux-gtk-x86_64.tar.gz | ||
| 68 | </literallayout> | ||
| 69 | </para> | ||
| 70 | |||
| 71 | <para> | ||
| 72 | One issue exists that you need to be aware of regarding the Java | ||
| 73 | Virtual machine’s garbage collection (GC) process. | ||
| 74 | The GC process does not clean up the permanent generation | ||
| 75 | space (PermGen). | ||
| 76 | This space stores metadata descriptions of classes. | ||
| 77 | The default value is set too small and it could trigger an | ||
| 78 | out-of-memory error such as the following: | ||
| 79 | <literallayout class='monospaced'> | ||
| 80 | Java.lang.OutOfMemoryError: PermGen space | ||
| 81 | </literallayout> | ||
| 82 | </para> | ||
| 83 | |||
| 84 | <para> | ||
| 85 | This error causes the application to hang. | ||
| 86 | </para> | ||
| 87 | |||
| 88 | <para> | ||
| 89 | To fix this issue, you can use the <filename>--vmargs</filename> | ||
| 90 | option when you start Eclipse to increase the size of the permanent generation space: | ||
| 91 | <literallayout class='monospaced'> | ||
| 92 | eclipse --vmargs --XX:PermSize=256M | ||
| 93 | </literallayout> | ||
| 94 | </para> | ||
| 95 | </section> | ||
| 96 | |||
| 97 | <section id='configuring-the-eclipse-ide'> | ||
| 98 | <title>Configuring the Eclipse IDE</title> | ||
| 99 | |||
| 100 | <para> | ||
| 101 | Before installing and configuring the Eclipse Yocto Plug-in, you need to configure | ||
| 102 | the Eclipse IDE. | ||
| 103 | Follow these general steps to configure Eclipse: | ||
| 104 | <orderedlist> | ||
| 105 | <listitem><para>Start the Eclipse IDE.</para></listitem> | ||
| 106 | <listitem><para>Make sure you are in your Workbench and select | ||
| 107 | "Install New Software" from the "Help" pull-down menu. | ||
| 108 | </para></listitem> | ||
| 109 | <listitem><para>Select <filename>indigo - &ECLIPSE_INDIGO_URL;</filename> | ||
| 110 | from the "Work with:" pull-down menu.</para></listitem> | ||
| 111 | <listitem><para>Expand the box next to <filename>Programming Languages</filename> | ||
| 112 | and select the <filename>Autotools Support for CDT (incubation)</filename> | ||
| 113 | and <filename>C/C++ Development Tools</filename> boxes.</para></listitem> | ||
| 114 | <listitem><para>Expand the box next to "Linux Tools" and select the | ||
| 115 | "LTTng - Linux Tracing Toolkit(incubation)" boxes.</para></listitem> | ||
| 116 | <listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem> | ||
| 117 | <listitem><para>After the Eclipse IDE restarts and from the Workbench, select | ||
| 118 | "Install New Software" from the "Help" pull-down menu.</para></listitem> | ||
| 119 | <listitem><para>Click the | ||
| 120 | "Available Software Sites" link.</para></listitem> | ||
| 121 | <listitem><para>Check the box next to | ||
| 122 | <filename>&ECLIPSE_UPDATES_URL;</filename> | ||
| 123 | and click "OK".</para></listitem> | ||
| 124 | <listitem><para>Select <filename>&ECLIPSE_UPDATES_URL;</filename> | ||
| 125 | from the "Work with:" pull-down menu.</para></listitem> | ||
| 126 | <listitem><para>Check the box next to <filename>TM and RSE Main Features</filename>. | ||
| 127 | </para></listitem> | ||
| 128 | <listitem><para>Expand the box next to <filename>TM and RSE Optional Add-ons</filename> | ||
| 129 | and select every item except <filename>RSE Unit Tests</filename> and | ||
| 130 | <filename>RSE WinCE Services (incubation)</filename>.</para></listitem> | ||
| 131 | <listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem> | ||
| 132 | <listitem><para>If necessary, select | ||
| 133 | "Install New Software" from the "Help" pull-down menu so you can click the | ||
| 134 | "Available Software Sites" link again.</para></listitem> | ||
| 135 | <listitem><para>After clicking "Available Software Sites", check the box next to | ||
| 136 | <filename>http://download.eclipse.org/tools/cdt/releases/indigo</filename> | ||
| 137 | and click "OK".</para></listitem> | ||
| 138 | <listitem><para>Select <filename>&ECLIPSE_INDIGO_CDT_URL;</filename> | ||
| 139 | from the "Work with:" pull-down menu.</para></listitem> | ||
| 140 | <listitem><para>Check the box next to <filename>CDT Main Features</filename>. | ||
| 141 | </para></listitem> | ||
| 142 | <listitem><para>Expand the box next to <filename>CDT Optional Features</filename> | ||
| 143 | and select <filename>C/C++ Remote Launch</filename> and | ||
| 144 | <filename>Target Communication Framework (incubation)</filename>.</para></listitem> | ||
| 145 | <listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem> | ||
| 146 | </orderedlist> | ||
| 147 | </para> | ||
| 148 | </section> | ||
| 149 | |||
| 150 | <section id='installing-the-eclipse-yocto-plug-in'> | ||
| 151 | <title>Installing or Accessing the Eclipse Yocto Plug-in</title> | ||
| 152 | |||
| 153 | <para> | ||
| 154 | You can install the Eclipse Yocto Plug-in into the Eclipse IDE | ||
| 155 | one of two ways: use the Yocto Project's Eclipse Update site to install the pre-built plug-in, | ||
| 156 | or build and install the plug-in from the latest source code. | ||
| 157 | If you don't want to permanently install the plug-in but just want to try it out | ||
| 158 | within the Eclipse environment, you can import the plug-in project from the | ||
| 159 | Yocto Project source repositories. | ||
| 160 | </para> | ||
| 161 | |||
| 162 | <section id='new-software'> | ||
| 163 | <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title> | ||
| 164 | |||
| 165 | <para> | ||
| 166 | To install the Eclipse Yocto Plug-in from the update site, | ||
| 167 | follow these steps: | ||
| 168 | <orderedlist> | ||
| 169 | <listitem><para>Start up the Eclipse IDE.</para></listitem> | ||
| 170 | <listitem><para>In Eclipse, select "Install New Software" from the "Help" menu.</para></listitem> | ||
| 171 | <listitem><para>Click "Add..." in the "Work with:" area.</para></listitem> | ||
| 172 | <listitem><para>Enter | ||
| 173 | <filename>&ECLIPSE_DL_PLUGIN_URL;</filename> | ||
| 174 | in the URL field and provide a meaningful name in the "Name" field.</para></listitem> | ||
| 175 | <listitem><para>Click "OK" to have the entry added to the "Work with:" | ||
| 176 | drop-down list.</para></listitem> | ||
| 177 | <listitem><para>Select the entry for the plug-in from the "Work with:" drop-down | ||
| 178 | list.</para></listitem> | ||
| 179 | <listitem><para>Check the box next to <filename>Development tools and SDKs for Yocto Linux</filename>. | ||
| 180 | </para></listitem> | ||
| 181 | <listitem><para>Complete the remaining software installation steps and | ||
| 182 | then restart the Eclipse IDE to finish the installation of the plug-in. | ||
| 183 | </para></listitem> | ||
| 184 | </orderedlist> | ||
| 185 | </para> | ||
| 186 | </section> | ||
| 187 | |||
| 188 | <section id='zip-file-method'> | ||
| 189 | <title>Installing the Plug-in Using the Latest Source Code</title> | ||
| 190 | <para> | ||
| 191 | To install the Eclipse Yocto Plug-in from the latest source code, follow these steps: | ||
| 192 | <orderedlist> | ||
| 193 | <listitem><para>Open a shell and create a Git repository with: | ||
| 194 | <literallayout class='monospaced'> | ||
| 195 | $ git clone git://git.yoctoproject.org/eclipse-poky yocto-eclipse | ||
| 196 | </literallayout> | ||
| 197 | For this example, the repository is named | ||
| 198 | <filename>~/yocto-eclipse</filename>.</para></listitem> | ||
| 199 | <listitem><para>Locate the <filename>build.sh</filename> script in the | ||
| 200 | Git repository you created in the previous step. | ||
| 201 | The script is located in the <filename>scripts</filename>.</para></listitem> | ||
| 202 | <listitem><para>Be sure to set and export the <filename>ECLIPSE_HOME</filename> environment | ||
| 203 | variable to the top-level directory in which you installed the Indigo | ||
| 204 | version of Eclipse. | ||
| 205 | For example, if your Eclipse directory is <filename>$HOME/eclipse</filename>, | ||
| 206 | use the following: | ||
| 207 | <literallayout class='monospaced'> | ||
| 208 | $ export ECLIPSE_HOME=$HOME/eclipse | ||
| 209 | </literallayout></para></listitem> | ||
| 210 | <listitem><para>Run the <filename>build.sh</filename> script and provide the | ||
| 211 | name of the Git branch along with the Yocto Project release you are | ||
| 212 | using. | ||
| 213 | Here is an example that uses the <filename>master</filename> Git repository | ||
| 214 | and the <filename>1.1M4</filename> release: | ||
| 215 | <literallayout class='monospaced'> | ||
| 216 | $ scripts/build.sh master 1.1M4 | ||
| 217 | </literallayout> | ||
| 218 | After running the script, the file | ||
| 219 | <filename>org.yocto.sdk-<release>-<date>-archive.zip</filename> | ||
| 220 | is in the current directory.</para></listitem> | ||
| 221 | <listitem><para>If necessary, start the Eclipse IDE and be sure you are in the | ||
| 222 | Workbench.</para></listitem> | ||
| 223 | <listitem><para>Select "Install New Software" from the "Help" pull-down menu. | ||
| 224 | </para></listitem> | ||
| 225 | <listitem><para>Click "Add".</para></listitem> | ||
| 226 | <listitem><para>Provide anything you want in the "Name" field.</para></listitem> | ||
| 227 | <listitem><para>Click "Archive" and browse to the ZIP file you built | ||
| 228 | in step four. | ||
| 229 | This ZIP file should not be "unzipped", and must be the | ||
| 230 | <filename>*archive.zip</filename> file created by running the | ||
| 231 | <filename>build.sh</filename> script.</para></listitem> | ||
| 232 | <listitem><para>Check the box next to the new entry in the installation window and complete | ||
| 233 | the installation.</para></listitem> | ||
| 234 | <listitem><para>Restart the Eclipse IDE if necessary.</para></listitem> | ||
| 235 | </orderedlist> | ||
| 236 | </para> | ||
| 237 | |||
| 238 | <para> | ||
| 239 | At this point you should be able to configure the Eclipse Yocto Plug-in as described in the | ||
| 240 | "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>" | ||
| 241 | section.</para> | ||
| 242 | </section> | ||
| 243 | |||
| 244 | <section id='yocto-project-source'> | ||
| 245 | <title>Importing the Plug-in Project into the Eclipse Environment</title> | ||
| 246 | <para> | ||
| 247 | Importing the Eclipse Yocto Plug-in project from the Yocto Project source repositories | ||
| 248 | is useful when you want to try out the latest plug-in from the tip of plug-in's | ||
| 249 | development tree. | ||
| 250 | It is important to understand when you import the plug-in you are not installing | ||
| 251 | it into the Eclipse application. | ||
| 252 | Rather, you are importing the project and just using it. | ||
| 253 | To import the plug-in project, follow these steps: | ||
| 254 | <orderedlist> | ||
| 255 | <listitem><para>Open a shell and create a Git repository with: | ||
| 256 | <literallayout class='monospaced'> | ||
| 257 | $ git clone git://git.yoctoproject.org/eclipse-poky yocto-eclipse | ||
| 258 | </literallayout> | ||
| 259 | For this example, the repository is named | ||
| 260 | <filename>~/yocto-eclipse</filename>.</para></listitem> | ||
| 261 | <listitem><para>In Eclipse, select "Import" from the "File" menu.</para></listitem> | ||
| 262 | <listitem><para>Expand the "General" box and select "existing projects into workspace" | ||
| 263 | and then click "Next".</para></listitem> | ||
| 264 | <listitem><para>Select the root directory and browse to | ||
| 265 | <filename>~/yocto-eclipse/plugins</filename>.</para></listitem> | ||
| 266 | <listitem><para>Three plug-ins exist: "org.yocto.bc.ui", "org.yocto.sdk.ide", and | ||
| 267 | "org.yocto.sdk.remotetools". | ||
| 268 | Select and import all of them.</para></listitem> | ||
| 269 | </orderedlist> | ||
| 270 | </para> | ||
| 271 | |||
| 272 | <para> | ||
| 273 | The left navigation pane in the Eclipse application shows the default projects. | ||
| 274 | Right-click on one of these projects and run it as an Eclipse application. | ||
| 275 | This brings up a second instance of Eclipse IDE that has the Yocto Plug-in. | ||
| 276 | </para> | ||
| 277 | </section> | ||
| 278 | </section> | ||
| 279 | |||
| 280 | <section id='configuring-the-eclipse-yocto-plug-in'> | ||
| 281 | <title>Configuring the Eclipse Yocto Plug-in</title> | ||
| 282 | |||
| 283 | <para> | ||
| 284 | Configuring the Eclipse Yocto Plug-in involves setting the Cross | ||
| 285 | Compiler options and the Target options. | ||
| 286 | The configurations you choose become the default settings for all projects. | ||
| 287 | You do have opportunities to change them later when | ||
| 288 | you configure the project (see the following section). | ||
| 289 | </para> | ||
| 290 | |||
| 291 | <para> | ||
| 292 | To start, you need to do the following from within the Eclipse IDE: | ||
| 293 | <itemizedlist> | ||
| 294 | <listitem><para>Choose <filename>Windows -> Preferences</filename> to display | ||
| 295 | the <filename>Preferences</filename> Dialog</para></listitem> | ||
| 296 | <listitem><para>Click <filename>Yocto Project ADT</filename></para></listitem> | ||
| 297 | </itemizedlist> | ||
| 298 | </para> | ||
| 299 | |||
| 300 | <section id='configuring-the-cross-compiler-options'> | ||
| 301 | <title>Configuring the Cross-Compiler Options</title> | ||
| 302 | |||
| 303 | <para> | ||
| 304 | To configure the Cross Compiler Options, you must select the type of toolchain, | ||
| 305 | point to the toolchain, specify the sysroot location, and select the target architecture. | ||
| 306 | <itemizedlist> | ||
| 307 | <listitem><para><emphasis>Selecting the Toolchain Type:</emphasis> | ||
| 308 | Choose between <filename>Standalone pre-built toolchain</filename> | ||
| 309 | and <filename>Build system derived toolchain</filename> for Cross | ||
| 310 | Compiler Options. | ||
| 311 | <itemizedlist> | ||
| 312 | <listitem><para><emphasis> | ||
| 313 | <filename>Standalone Pre-built Toolchain:</filename></emphasis> | ||
| 314 | Select this mode when you are using a stand-alone cross-toolchain. | ||
| 315 | For example, suppose you are an application developer and do not | ||
| 316 | need to build a target image. | ||
| 317 | Instead, you just want to use an architecture-specific toolchain on an | ||
| 318 | existing kernel and target root filesystem. | ||
| 319 | </para></listitem> | ||
| 320 | <listitem><para><emphasis> | ||
| 321 | <filename>Build System Derived Toolchain:</filename></emphasis> | ||
| 322 | Select this mode if the cross-toolchain has been installed and built | ||
| 323 | as part of the build directory. | ||
| 324 | When you select <filename>Build system derived toolchain</filename>, | ||
| 325 | you are using the toolchain bundled | ||
| 326 | inside the build directory. | ||
| 327 | </para></listitem> | ||
| 328 | </itemizedlist> | ||
| 329 | </para></listitem> | ||
| 330 | <listitem><para><emphasis>Point to the Toolchain:</emphasis> | ||
| 331 | If you are using a stand-alone pre-built toolchain, you should be pointing to the | ||
| 332 | <filename>&YOCTO_ADTPATH_DIR;</filename> directory. | ||
| 333 | This is the location for toolchains installed by the ADT Installer or by hand. | ||
| 334 | Sections "<link linkend='configuring-and-running-the-adt-installer-script'>Configuring | ||
| 335 | and Running the ADT Installer Script</link>" and | ||
| 336 | "<link linkend='using-an-existing-toolchain-tarball'>Using a Cross-Toolchain | ||
| 337 | Tarball</link>" describe two ways to install | ||
| 338 | a stand-alone cross-toolchain in the | ||
| 339 | <filename>/opt/poky</filename> directory. | ||
| 340 | <note>It is possible to install a stand-alone cross-toolchain in a directory | ||
| 341 | other than <filename>/opt/poky</filename>. | ||
| 342 | However, doing so is discouraged.</note></para> | ||
| 343 | <para>If you are using a system-derived toolchain, the path you provide | ||
| 344 | for the <filename>Toolchain Root Location</filename> | ||
| 345 | field is the build directory. | ||
| 346 | See section "<link linkend='using-the-toolchain-from-within-the-build-tree'>Using | ||
| 347 | BitBake and the build directory</link>" for | ||
| 348 | information on how to install the toolchain into the build directory.</para></listitem> | ||
| 349 | <listitem><para><emphasis>Specify the Sysroot Location:</emphasis> | ||
| 350 | This location is where the root filesystem for the | ||
| 351 | target hardware is created on the development system by the ADT Installer. | ||
| 352 | The QEMU user-space tools, the | ||
| 353 | NFS boot process, and the cross-toolchain all use the sysroot location. | ||
| 354 | </para></listitem> | ||
| 355 | <listitem><para><emphasis>Select the Target Architecture:</emphasis> | ||
| 356 | The target architecture is the type of hardware you are | ||
| 357 | going to use or emulate. | ||
| 358 | Use the pull-down <filename>Target Architecture</filename> menu to make | ||
| 359 | your selection. | ||
| 360 | The pull-down menu should have the supported architectures. | ||
| 361 | If the architecture you need is not listed in the menu, you | ||
| 362 | will need to build the image. | ||
| 363 | See the "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section | ||
| 364 | of The Yocto Project Quick Start for more information.</para></listitem> | ||
| 365 | </itemizedlist> | ||
| 366 | </para> | ||
| 367 | </section> | ||
| 368 | |||
| 369 | <section id='configuring-the-target-options'> | ||
| 370 | <title>Configuring the Target Options</title> | ||
| 371 | |||
| 372 | <para> | ||
| 373 | You can choose to emulate hardware using the QEMU emulator, or you | ||
| 374 | can choose to run your image on actual hardware. | ||
| 375 | <itemizedlist> | ||
| 376 | <listitem><para><emphasis><filename>QEMU:</filename></emphasis> Select this option if | ||
| 377 | you will be using the QEMU emulator. | ||
| 378 | If you are using the emulator, you also need to locate the kernel | ||
| 379 | and specify any custom options.</para> | ||
| 380 | <para>If you selected <filename>Build system derived toolchain</filename>, | ||
| 381 | the target kernel you built will be located in the | ||
| 382 | build directory in <filename>tmp/deploy/images</filename> directory. | ||
| 383 | If you selected <filename>Standalone pre-built toolchain</filename>, the | ||
| 384 | pre-built image you downloaded is located | ||
| 385 | in the directory you specified when you downloaded the image.</para> | ||
| 386 | <para>Most custom options are for advanced QEMU users to further | ||
| 387 | customize their QEMU instance. | ||
| 388 | These options are specified between paired angled brackets. | ||
| 389 | Some options must be specified outside the brackets. | ||
| 390 | In particular, the options <filename>serial</filename>, | ||
| 391 | <filename>nographic</filename>, and <filename>kvm</filename> must all | ||
| 392 | be outside the brackets. | ||
| 393 | Use the <filename>man qemu</filename> command to get help on all the options | ||
| 394 | and their use. | ||
| 395 | The following is an example: | ||
| 396 | <literallayout class='monospaced'> | ||
| 397 | serial ‘<-m 256 -full-screen>’ | ||
| 398 | </literallayout></para> | ||
| 399 | <para> | ||
| 400 | Regardless of the mode, Sysroot is already defined as part of the | ||
| 401 | Cross Compiler Options configuration in the | ||
| 402 | <filename>Sysroot Location:</filename> field.</para></listitem> | ||
| 403 | <listitem><para><emphasis><filename>External HW:</filename></emphasis> Select this option | ||
| 404 | if you will be using actual hardware.</para></listitem> | ||
| 405 | </itemizedlist> | ||
| 406 | </para> | ||
| 407 | |||
| 408 | <para> | ||
| 409 | Click the <filename>OK</filename> button to save your plug-in configurations. | ||
| 410 | </para> | ||
| 411 | </section> | ||
| 412 | </section> | ||
| 413 | </section> | ||
| 414 | |||
| 415 | <section id='creating-the-project'> | ||
| 416 | <title>Creating the Project</title> | ||
| 417 | |||
| 418 | <para> | ||
| 419 | You can create two types of projects: Autotools-based, or Makefile-based. | ||
| 420 | This section describes how to create Autotools-based projects from within | ||
| 421 | the Eclipse IDE. | ||
| 422 | For information on creating Makefile-based projects in a terminal window, see the section | ||
| 423 | "<link linkend='using-the-command-line'>Using the Command Line</link>". | ||
| 424 | </para> | ||
| 425 | |||
| 426 | <para> | ||
| 427 | To create a project based on a Yocto template and then display the source code, | ||
| 428 | follow these steps: | ||
| 429 | <orderedlist> | ||
| 430 | <listitem><para>Select <filename>File -> New -> Project</filename>.</para></listitem> | ||
| 431 | <listitem><para>Double click <filename>CC++</filename>.</para></listitem> | ||
| 432 | <listitem><para>Double click <filename>C Project</filename> to create the project.</para></listitem> | ||
| 433 | <listitem><para>Expand <filename>Yocto Project ADT Project</filename>.</para></listitem> | ||
| 434 | <listitem><para>Select <filename>Hello World ANSI C Autotools Project</filename>. | ||
| 435 | This is an Autotools-based project based on a Yocto template.</para></listitem> | ||
| 436 | <listitem><para>Put a name in the <filename>Project name:</filename> field. | ||
| 437 | Do not use hyphens as part of the name.</para></listitem> | ||
| 438 | <listitem><para>Click <filename>Next</filename>.</para></listitem> | ||
| 439 | <listitem><para>Add information in the <filename>Author</filename> and | ||
| 440 | <filename>Copyright notice</filename> fields.</para></listitem> | ||
| 441 | <listitem><para>Be sure the <filename>License</filename> field is correct.</para></listitem> | ||
| 442 | <listitem><para>Click <filename>Finish</filename>.</para></listitem> | ||
| 443 | <listitem><para>If the "open perspective" prompt appears, click "Yes" so that you | ||
| 444 | in the C/C++ perspective.</para></listitem> | ||
| 445 | <listitem><para>The left-hand navigation pane shows your project. | ||
| 446 | You can display your source by double clicking the project's source file. | ||
| 447 | </para></listitem> | ||
| 448 | </orderedlist> | ||
| 449 | </para> | ||
| 450 | </section> | ||
| 451 | |||
| 452 | <section id='configuring-the-cross-toolchains'> | ||
| 453 | <title>Configuring the Cross-Toolchains</title> | ||
| 454 | |||
| 455 | <para> | ||
| 456 | The earlier section, "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring | ||
| 457 | the Eclipse Yocto Plug-in</link>", sets up the default project | ||
| 458 | configurations. | ||
| 459 | You can override these settings for a given project by following these steps: | ||
| 460 | <orderedlist> | ||
| 461 | <listitem><para>Select <filename>Project -> Change Yocto Project Settings</filename>: | ||
| 462 | This selection brings up the <filename>Yocot Project Settings</filename> Dialog | ||
| 463 | and allows you to make changes specific to an individual project. | ||
| 464 | </para> | ||
| 465 | <para>By default, the Cross Compiler Options and Target Options for a project | ||
| 466 | are inherited from settings you provide using the <filename>Preferences</filename> | ||
| 467 | Dialog as described earlier | ||
| 468 | in the "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse | ||
| 469 | Yocto Plug-in</link>" section. | ||
| 470 | The <filename>Yocto Project Settings</filename> | ||
| 471 | Dialog allows you to override those default settings | ||
| 472 | for a given project.</para></listitem> | ||
| 473 | <listitem><para>Make your configurations for the project and click "OK".</para></listitem> | ||
| 474 | <listitem><para>Select <filename>Project -> Reconfigure Project</filename>: | ||
| 475 | This selection reconfigures the project by running | ||
| 476 | <filename>autogen.sh</filename> in the workspace for your project. | ||
| 477 | The script also runs <filename>libtoolize</filename>, <filename>aclocal</filename>, | ||
| 478 | <filename>autoconf</filename>, <filename>autoheader</filename>, | ||
| 479 | <filename>automake --a</filename>, and | ||
| 480 | <filename>./configure</filename>. | ||
| 481 | Click on the <filename>Console</filename> tab beneath your source code to | ||
| 482 | see the results of reconfiguring your project.</para></listitem> | ||
| 483 | </orderedlist> | ||
| 484 | </para> | ||
| 485 | </section> | ||
| 486 | |||
| 487 | <section id='building-the-project'> | ||
| 488 | <title>Building the Project</title> | ||
| 489 | |||
| 490 | <para> | ||
| 491 | To build the project, select <filename>Project -> Build Project</filename>. | ||
| 492 | The console should update and you can note the cross-compiler you are using. | ||
| 493 | </para> | ||
| 494 | </section> | ||
| 495 | |||
| 496 | <section id='starting-qemu-in-user-space-nfs-mode'> | ||
| 497 | <title>Starting QEMU in User Space NFS Mode</title> | ||
| 498 | |||
| 499 | <para> | ||
| 500 | To start the QEMU emulator from within Eclipse, follow these steps: | ||
| 501 | <orderedlist> | ||
| 502 | <listitem><para>Expose the <filename>Run -> External Tools</filename> menu. | ||
| 503 | Your image should appear as a selectable menu item. | ||
| 504 | </para></listitem> | ||
| 505 | <listitem><para>Select your image from the menu to launch the | ||
| 506 | emulator in a new window.</para></listitem> | ||
| 507 | <listitem><para>If needed, enter your host root password in the shell window at the prompt. | ||
| 508 | This sets up a <filename>Tap 0</filename> connection needed for running in user-space | ||
| 509 | NFS mode.</para></listitem> | ||
| 510 | <listitem><para>Wait for QEMU to launch.</para></listitem> | ||
| 511 | <listitem><para>Once QEMU launches, you can begin operating within that | ||
| 512 | environment. | ||
| 513 | For example, you could determine the IP Address | ||
| 514 | for the user-space NFS by using the <filename>ifconfig</filename> command. | ||
| 515 | </para></listitem> | ||
| 516 | </orderedlist> | ||
| 517 | </para> | ||
| 518 | </section> | ||
| 519 | |||
| 520 | <section id='deploying-and-debugging-the-application'> | ||
| 521 | <title>Deploying and Debugging the Application</title> | ||
| 522 | |||
| 523 | <para> | ||
| 524 | Once the QEMU emulator is running the image, using the Eclipse IDE | ||
| 525 | you can deploy your application and use the emulator to perform debugging. | ||
| 526 | Follow these steps to deploy the application. | ||
| 527 | <orderedlist> | ||
| 528 | <listitem><para>Select <filename>Run -> Debug Configurations...</filename></para></listitem> | ||
| 529 | <listitem><para>In the left area, expand <filename>C/C++Remote Application</filename>.</para></listitem> | ||
| 530 | <listitem><para>Locate your project and select it to bring up a new | ||
| 531 | tabbed view in the <filename>Debug Configurations</filename> Dialog.</para></listitem> | ||
| 532 | <listitem><para>Enter the absolute path into which you want to deploy | ||
| 533 | the application. | ||
| 534 | Use the <filename>Remote Absolute File Path for C/C++Application:</filename> field. | ||
| 535 | For example, enter <filename>/usr/bin/<programname></filename>.</para></listitem> | ||
| 536 | <listitem><para>Click on the <filename>Debugger</filename> tab to see the cross-tool debugger | ||
| 537 | you are using.</para></listitem> | ||
| 538 | <listitem><para>Click on the <filename>Main</filename> tab.</para></listitem> | ||
| 539 | <listitem><para>Create a new connection to the QEMU instance | ||
| 540 | by clicking on <filename>new</filename>.</para></listitem> | ||
| 541 | <listitem><para>Select <filename>TCF</filename>, which means Target Communication | ||
| 542 | Framework.</para></listitem> | ||
| 543 | <listitem><para>Click <filename>Next</filename>.</para></listitem> | ||
| 544 | <listitem><para>Clear out the <filename>host name</filename> field and enter the IP Address | ||
| 545 | determined earlier.</para></listitem> | ||
| 546 | <listitem><para>Click <filename>Finish</filename> to close the | ||
| 547 | <filename>New Connections</filename> Dialog.</para></listitem> | ||
| 548 | <listitem><para>Use the drop-down menu now in the <filename>Connection</filename> field and pick | ||
| 549 | the IP Address you entered.</para></listitem> | ||
| 550 | <listitem><para>Click <filename>Debug</filename> to bring up a login screen | ||
| 551 | and login.</para></listitem> | ||
| 552 | <listitem><para>Accept the debug perspective.</para></listitem> | ||
| 553 | </orderedlist> | ||
| 554 | </para> | ||
| 555 | </section> | ||
| 556 | |||
| 557 | <section id='running-user-space-tools'> | ||
| 558 | <title>Running User-Space Tools</title> | ||
| 559 | |||
| 560 | <para> | ||
| 561 | As mentioned earlier in the manual, several tools exist that enhance | ||
| 562 | your development experience. | ||
| 563 | These tools are aids in developing and debugging applications and images. | ||
| 564 | You can run these user-space tools from within the Eclipse IDE through the | ||
| 565 | <filename>YoctoTools</filename> menu. | ||
| 566 | </para> | ||
| 567 | |||
| 568 | <para> | ||
| 569 | Once you pick a tool, you need to configure it for the remote target. | ||
| 570 | Every tool needs to have the connection configured. | ||
| 571 | You must select an existing TCF-based RSE connection to the remote target. | ||
| 572 | If one does not exist, click <filename>New</filename> to create one. | ||
| 573 | </para> | ||
| 574 | |||
| 575 | <para> | ||
| 576 | Here are some specifics about the remote tools: | ||
| 577 | <itemizedlist> | ||
| 578 | <listitem><para><emphasis><filename>OProfile</filename>:</emphasis> Selecting this tool causes | ||
| 579 | the <filename>oprofile-server</filename> on the remote target to launch on | ||
| 580 | the local host machine. | ||
| 581 | The <filename>oprofile-viewer</filename> must be installed on the local host machine and the | ||
| 582 | <filename>oprofile-server</filename> must be installed on the remote target, | ||
| 583 | respectively, in order to use. | ||
| 584 | You must compile and install the <filename>oprofile-viewer</filename> from the source code | ||
| 585 | on your local host machine. | ||
| 586 | Furthermore, in order to convert the target's sample format data into a form that the | ||
| 587 | host can use, you must have <filename>oprofile</filename> version 0.9.4 or | ||
| 588 | greater installed on the host.</para> | ||
| 589 | <para>You can locate both the viewer and server from | ||
| 590 | <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/oprofileui/'></ulink>. | ||
| 591 | <note>The <filename>oprofile-server</filename> is installed by default on | ||
| 592 | the <filename>core-image-sato-sdk</filename> image.</note></para></listitem> | ||
| 593 | <listitem><para><emphasis><filename>Lttng-ust</filename>:</emphasis> Selecting this tool runs | ||
| 594 | <filename>usttrace</filename> on the remote target, transfers the output data back | ||
| 595 | to the local host machine, and uses the <filename>lttng</filename> Eclipse plug-in to | ||
| 596 | graphically display the output. | ||
| 597 | For information on how to use <filename>lttng</filename> to trace an application, see | ||
| 598 | <ulink url='http://lttng.org/files/ust/manual/ust.html'></ulink>.</para> | ||
| 599 | <para>For <filename>Application</filename>, you must supply the absolute path name of the | ||
| 600 | application to be traced by user mode <filename>lttng</filename>. | ||
| 601 | For example, typing <filename>/path/to/foo</filename> triggers | ||
| 602 | <filename>usttrace /path/to/foo</filename> on the remote target to trace the | ||
| 603 | program <filename>/path/to/foo</filename>.</para> | ||
| 604 | <para><filename>Argument</filename> is passed to <filename>usttrace</filename> | ||
| 605 | running on the remote target.</para> | ||
| 606 | <para>Before you use the <filename>lttng-ust</filename> tool, you need to setup | ||
| 607 | the <filename>lttng</filename> Eclipse plug-in and create a <filename>lttng</filename> | ||
| 608 | project. | ||
| 609 | Do the following: | ||
| 610 | <orderedlist> | ||
| 611 | <listitem><para>Follow these | ||
| 612 | <ulink url='http://wiki.eclipse.org/Linux_Tools_Project/LTTng#Downloading_and_installing_the_LTTng_parser_library'>instructions</ulink> | ||
| 613 | to download and install the <filename>lttng</filename> parser library. | ||
| 614 | </para></listitem> | ||
| 615 | <listitem><para>Select <filename>Window -> Open Perspective -> Other</filename> | ||
| 616 | and then select <filename>LTTng</filename>.</para></listitem> | ||
| 617 | <listitem><para>Click <filename>OK</filename> to change the Eclipse perspective | ||
| 618 | into the <filename>LTTng</filename> perspective.</para></listitem> | ||
| 619 | <listitem><para>Create a new <filename>LTTng</filename> project by selecting | ||
| 620 | <filename>File -> New -> Project</filename>.</para></listitem> | ||
| 621 | <listitem><para>Choose <filename>LTTng -> LTTng Project</filename>.</para></listitem> | ||
| 622 | <listitem><para>Click <filename>YoctoTools -> lttng-ust</filename> to start user mode | ||
| 623 | <filename>lttng</filename> on the remote target.</para></listitem> | ||
| 624 | </orderedlist></para> | ||
| 625 | <para>After the output data has been transferred from the remote target back to the local | ||
| 626 | host machine, new traces will be imported into the selected <filename>LTTng</filename> project. | ||
| 627 | Then you can go to the <filename>LTTng</filename> project, right click the imported | ||
| 628 | trace, and set the trace type as the <filename>LTTng</filename> kernel trace. | ||
| 629 | Finally, right click the imported trace and select <filename>Open</filename> | ||
| 630 | to display the data graphically.</para></listitem> | ||
| 631 | <listitem><para><emphasis><filename>PowerTOP</filename>:</emphasis> Selecting this tool runs | ||
| 632 | <filename>powertop</filename> on the remote target machine and displays the results in a | ||
| 633 | new view called <filename>powertop</filename>.</para> | ||
| 634 | <para><filename>Time to gather data(sec):</filename> is the time passed in seconds before data | ||
| 635 | is gathered from the remote target for analysis.</para> | ||
| 636 | <para><filename>show pids in wakeups list:</filename> corresponds to the | ||
| 637 | <filename>-p</filename> argument | ||
| 638 | passed to <filename>powertop</filename>.</para></listitem> | ||
| 639 | <listitem><para><emphasis><filename>LatencyTOP and Perf</filename>:</emphasis> | ||
| 640 | <filename>latencytop</filename> identifies system latency, while | ||
| 641 | <filename>perf</filename> monitors the system's | ||
| 642 | performance counter registers. | ||
| 643 | Selecting either of these tools causes an RSE terminal view to appear | ||
| 644 | from which you can run the tools. | ||
| 645 | Both tools refresh the entire screen to display results while they run.</para></listitem> | ||
| 646 | </itemizedlist> | ||
| 647 | </para> | ||
| 648 | </section> | ||
| 649 | |||
| 650 | <section id='customizing-an-image-using-a-bitbake-commander-project-and-hob'> | ||
| 651 | <title>Customizing an Image Using a BitBake Commander Project and Hob</title> | ||
| 652 | |||
| 653 | <para> | ||
| 654 | Within Eclipse, you can create a Yocto BitBake Commander project, | ||
| 655 | edit the metadata, and then use the | ||
| 656 | <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink> to build a customized | ||
| 657 | image all within one IDE. | ||
| 658 | </para> | ||
| 659 | |||
| 660 | <section id='creating-the-yocto-bitbake-commander-project'> | ||
| 661 | <title>Creating the Yocto BitBake Commander Project</title> | ||
| 662 | |||
| 663 | <para> | ||
| 664 | To create a Yocto BitBake Commander project, follow these steps: | ||
| 665 | <orderedlist> | ||
| 666 | <listitem><para>Select <filename>Window -> Open Perspective -> Other</filename> | ||
| 667 | and then choose <filename>Bitbake Commander</filename>.</para></listitem> | ||
| 668 | <listitem><para>Click <filename>OK</filename> to change the Eclipse perspective into the | ||
| 669 | Bitbake Commander perspective.</para></listitem> | ||
| 670 | <listitem><para>Select <filename>File -> New -> Project</filename> to create a new Yocto | ||
| 671 | Bitbake Commander project.</para></listitem> | ||
| 672 | <listitem><para>Choose <filename>Yocto Project Bitbake Commander -> New Yocto Project</filename> | ||
| 673 | and click <filename>Next</filename>.</para></listitem> | ||
| 674 | <listitem><para>Enter the Project Name and choose the Project Location. | ||
| 675 | The Yocto project's metadata files will be put under the directory | ||
| 676 | <filename><project_location>/<project_name></filename>. | ||
| 677 | If that directory does not exist, you need to check | ||
| 678 | the "Clone from Yocto Git Repository" box, which would execute a | ||
| 679 | <filename>git clone</filename> command to get the project's metadata files. | ||
| 680 | </para></listitem> | ||
| 681 | <listitem><para>Select <filename>Finish</filename> to create the project.</para></listitem> | ||
| 682 | </orderedlist> | ||
| 683 | </para> | ||
| 684 | </section> | ||
| 685 | |||
| 686 | <section id='editing-the-metadata-files'> | ||
| 687 | <title>Editing the Metadata Files</title> | ||
| 688 | |||
| 689 | <para> | ||
| 690 | After you create the Yocto Bitbake Commander project, you can modify the metadata files | ||
| 691 | by opening them in the project. | ||
| 692 | When editing recipe files (<filename>.bb</filename> files), you can view BitBake | ||
| 693 | variable values and information by hovering the mouse pointer over the variable name and | ||
| 694 | waiting a few seconds. | ||
| 695 | </para> | ||
| 696 | |||
| 697 | <para> | ||
| 698 | To edit the metadata, follow these steps: | ||
| 699 | <orderedlist> | ||
| 700 | <listitem><para>Select your Yocto Bitbake Commander project.</para></listitem> | ||
| 701 | <listitem><para>Select <filename>File -> New -> Yocto BitBake Commander -> BitBake Recipe</filename> | ||
| 702 | to open a new recipe wizard.</para></listitem> | ||
| 703 | <listitem><para>Point to your source by filling in the "SRC_URL" field. | ||
| 704 | For example, you can add a recipe to your | ||
| 705 | <ulink url='&YOCTO_DOCS_DEV_URL;#yocto-project-source-files'>source directory structure</ulink> | ||
| 706 | by defining "SRC_URL" as follows: | ||
| 707 | <literallayout class='monospaced'> | ||
| 708 | ftp://ftp.gnu.org/gnu/m4/m4-1.4.9.tar.gz | ||
| 709 | </literallayout></para></listitem> | ||
| 710 | <listitem><para>Click "Populate" to calculate the archive md5, sha256, | ||
| 711 | license checksum values and to auto-generate the recipe filename.</para></listitem> | ||
| 712 | <listitem><para>Fill in the "Description" field.</para></listitem> | ||
| 713 | <listitem><para>Be sure values for all required fields exist.</para></listitem> | ||
| 714 | <listitem><para>Click <filename>Finish</filename>.</para></listitem> | ||
| 715 | </orderedlist> | ||
| 716 | </para> | ||
| 717 | </section> | ||
| 718 | |||
| 719 | <section id='buiding-and-customizing-the-image'> | ||
| 720 | <title>Building and Customizing the Image</title> | ||
| 721 | |||
| 722 | <para> | ||
| 723 | To build and customize the image in Eclipse, follow these steps: | ||
| 724 | <orderedlist> | ||
| 725 | <listitem><para>Select your Yocto Bitbake Commander project.</para></listitem> | ||
| 726 | <listitem><para>Select <filename>Project -> Launch HOB</filename>.</para></listitem> | ||
| 727 | <listitem><para>Enter the build directory where you want to put your final images.</para></listitem> | ||
| 728 | <listitem><para>Click <filename>OK</filename> to launch Hob.</para></listitem> | ||
| 729 | <listitem><para>Use Hob to customize and build your own images. | ||
| 730 | For information on Hob, see the | ||
| 731 | <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob Project Page</ulink> on the | ||
| 732 | Yocto Project website.</para></listitem> | ||
| 733 | </orderedlist> | ||
| 734 | </para> | ||
| 735 | </section> | ||
| 736 | </section> | ||
| 737 | </chapter> | ||
| 738 | <!-- | ||
| 739 | vim: expandtab tw=80 ts=4 | ||
| 740 | --> | ||
diff --git a/documentation/adt-manual/adt-intro.xml b/documentation/adt-manual/adt-intro.xml index 04c47369f9..93737826b5 100644 --- a/documentation/adt-manual/adt-intro.xml +++ b/documentation/adt-manual/adt-intro.xml | |||
| @@ -13,11 +13,13 @@ | |||
| 13 | 13 | ||
| 14 | <para> | 14 | <para> |
| 15 | The Yocto Project provides an application development environment based on | 15 | The Yocto Project provides an application development environment based on |
| 16 | an Application Development Toolkit (ADT). | 16 | an Application Development Toolkit (ADT) and the availability of stand-alone |
| 17 | This manual describes the ADT and how you can configure and install it. | 17 | cross-development toolchains and other tools. |
| 18 | You will also learn how to customize the development packages installation, | 18 | This manual describes the ADT and how you can configure and install it, |
| 19 | learn about the Eclipse Yocto Plug-in, and learn how to use command line | 19 | how to access and use the cross-development toolchains, how to |
| 20 | development for both Autotools-based and Makefile-based projects. | 20 | customize the development packages installation, |
| 21 | how to use command line development for both Autotools-based and Makefile-based projects, | ||
| 22 | and an introduction to the Eclipse Yocto Plug-in. | ||
| 21 | </para> | 23 | </para> |
| 22 | 24 | ||
| 23 | <section id='book-intro'> | 25 | <section id='book-intro'> |
| @@ -88,6 +90,14 @@ | |||
| 88 | remote profiling, tracing, collection of power data, collection of | 90 | remote profiling, tracing, collection of power data, collection of |
| 89 | latency data, and collection of performance data. | 91 | latency data, and collection of performance data. |
| 90 | </para> | 92 | </para> |
| 93 | |||
| 94 | <para> | ||
| 95 | For information about the application development workflow that uses the Eclipse | ||
| 96 | IDE and for a detailed example of how to install and configure the Eclipse | ||
| 97 | Yocto Project Plug-in, see the | ||
| 98 | "<ulink url='&YOCTO_DOCS_DEV_URL;#adt-eclipse'>Working Within Eclipse</ulink>" section | ||
| 99 | of the Yocto Project Development Manual. | ||
| 100 | </para> | ||
| 91 | </section> | 101 | </section> |
| 92 | 102 | ||
| 93 | <section id='the-qemu-emulator'> | 103 | <section id='the-qemu-emulator'> |
diff --git a/documentation/adt-manual/adt-manual.xml b/documentation/adt-manual/adt-manual.xml index c553e7cc08..285c347fae 100644 --- a/documentation/adt-manual/adt-manual.xml +++ b/documentation/adt-manual/adt-manual.xml | |||
| @@ -85,8 +85,6 @@ | |||
| 85 | 85 | ||
| 86 | <xi:include href="adt-package.xml"/> | 86 | <xi:include href="adt-package.xml"/> |
| 87 | 87 | ||
| 88 | <xi:include href="adt-eclipse.xml"/> | ||
| 89 | |||
| 90 | <xi:include href="adt-command.xml"/> | 88 | <xi:include href="adt-command.xml"/> |
| 91 | 89 | ||
| 92 | <!-- <index id='index'> | 90 | <!-- <index id='index'> |
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml index b5274b8452..3bfd1a3963 100644 --- a/documentation/dev-manual/dev-manual-model.xml +++ b/documentation/dev-manual/dev-manual-model.xml | |||
| @@ -641,6 +641,745 @@ | |||
| 641 | </para> | 641 | </para> |
| 642 | </section> | 642 | </section> |
| 643 | 643 | ||
| 644 | <section id='adt-eclipse'> | ||
| 645 | <title>Working Within Eclipse</title> | ||
| 646 | |||
| 647 | <para> | ||
| 648 | The Eclipse IDE is a popular development environment and it fully supports | ||
| 649 | development using the Yocto Project. | ||
| 650 | When you install and configure the Eclipse Yocto Project Plug-in into | ||
| 651 | the Eclipse IDE, you maximize your Yocto Project experience. | ||
| 652 | Installing and configuring the Plug-in results in an environment that | ||
| 653 | has extensions specifically designed to let you more easily develop software. | ||
| 654 | These extensions allow for cross-compilation, deployment, and execution of | ||
| 655 | your output into a QEMU emulation session. | ||
| 656 | You can also perform cross-debugging and profiling. | ||
| 657 | The environment also supports a suite of tools that allows you to perform | ||
| 658 | remote profiling, tracing, collection of power data, collection of | ||
| 659 | latency data, and collection of performance data. | ||
| 660 | </para> | ||
| 661 | |||
| 662 | <para> | ||
| 663 | This section describes how to install and configure the Eclipse IDE | ||
| 664 | Yocto Plug-in and how to use it to develop your application. | ||
| 665 | </para> | ||
| 666 | |||
| 667 | <section id='setting-up-the-eclipse-ide'> | ||
| 668 | <title>Setting Up the Eclipse IDE</title> | ||
| 669 | |||
| 670 | <para> | ||
| 671 | To develop within the Eclipse IDE, you need to do the following: | ||
| 672 | <orderedlist> | ||
| 673 | <listitem><para>Install the optimal version of the Eclipse IDE.</para></listitem> | ||
| 674 | <listitem><para>Configure the Eclipse IDE.</para></listitem> | ||
| 675 | <listitem><para>Install the Eclipse Yocto Plug-in.</para></listitem> | ||
| 676 | <listitem><para>Configure the Eclipse Yocto Plug-in.</para></listitem> | ||
| 677 | </orderedlist> | ||
| 678 | <note> | ||
| 679 | Do not install Eclipse from your distribution's package repository. | ||
| 680 | Be sure to install Eclipse from the official Eclipse download site as directed | ||
| 681 | in the next section. | ||
| 682 | </note> | ||
| 683 | </para> | ||
| 684 | |||
| 685 | <section id='installing-eclipse-ide'> | ||
| 686 | <title>Installing the Eclipse IDE</title> | ||
| 687 | |||
| 688 | <para> | ||
| 689 | It is recommended that you have the Indigo 3.7.2 version of the | ||
| 690 | Eclipse IDE installed on your development system. | ||
| 691 | If you don’t have this version, you can find it at | ||
| 692 | <ulink url='&ECLIPSE_MAIN_URL;'></ulink>. | ||
| 693 | From that site, choose the Eclipse Classic version particular to your development | ||
| 694 | host. | ||
| 695 | This version contains the Eclipse Platform, the Java Development | ||
| 696 | Tools (JDT), and the Plug-in Development Environment. | ||
| 697 | </para> | ||
| 698 | |||
| 699 | <para> | ||
| 700 | Once you have downloaded the tarball, extract it into a clean | ||
| 701 | directory. | ||
| 702 | For example, the following commands unpack and install the Eclipse IDE | ||
| 703 | tarball found in the <filename>Downloads</filename> area | ||
| 704 | into a clean directory using the default name <filename>eclipse</filename>: | ||
| 705 | <literallayout class='monospaced'> | ||
| 706 | $ cd ~ | ||
| 707 | $ tar -xzvf ~/Downloads/eclipse-SDK-3.7.2-linux-gtk-x86_64.tar.gz | ||
| 708 | </literallayout> | ||
| 709 | </para> | ||
| 710 | |||
| 711 | <para> | ||
| 712 | One issue exists that you need to be aware of regarding the Java | ||
| 713 | Virtual machine’s garbage collection (GC) process. | ||
| 714 | The GC process does not clean up the permanent generation | ||
| 715 | space (PermGen). | ||
| 716 | This space stores metadata descriptions of classes. | ||
| 717 | The default value is set too small and it could trigger an | ||
| 718 | out-of-memory error such as the following: | ||
| 719 | <literallayout class='monospaced'> | ||
| 720 | Java.lang.OutOfMemoryError: PermGen space | ||
| 721 | </literallayout> | ||
| 722 | </para> | ||
| 723 | |||
| 724 | <para> | ||
| 725 | This error causes the application to hang. | ||
| 726 | </para> | ||
| 727 | |||
| 728 | <para> | ||
| 729 | To fix this issue, you can use the <filename>--vmargs</filename> | ||
| 730 | option when you start Eclipse to increase the size of the permanent generation space: | ||
| 731 | <literallayout class='monospaced'> | ||
| 732 | eclipse --vmargs --XX:PermSize=256M | ||
| 733 | </literallayout> | ||
| 734 | </para> | ||
| 735 | </section> | ||
| 736 | |||
| 737 | <section id='configuring-the-eclipse-ide'> | ||
| 738 | <title>Configuring the Eclipse IDE</title> | ||
| 739 | |||
| 740 | <para> | ||
| 741 | Before installing and configuring the Eclipse Yocto Plug-in, you need to configure | ||
| 742 | the Eclipse IDE. | ||
| 743 | Follow these general steps to configure Eclipse: | ||
| 744 | <orderedlist> | ||
| 745 | <listitem><para>Start the Eclipse IDE.</para></listitem> | ||
| 746 | <listitem><para>Make sure you are in your Workbench and select | ||
| 747 | "Install New Software" from the "Help" pull-down menu. | ||
| 748 | </para></listitem> | ||
| 749 | <listitem><para>Select <filename>indigo - &ECLIPSE_INDIGO_URL;</filename> | ||
| 750 | from the "Work with:" pull-down menu.</para></listitem> | ||
| 751 | <listitem><para>Expand the box next to <filename>Programming Languages</filename> | ||
| 752 | and select the <filename>Autotools Support for CDT (incubation)</filename> | ||
| 753 | and <filename>C/C++ Development Tools</filename> boxes.</para></listitem> | ||
| 754 | <listitem><para>Expand the box next to "Linux Tools" and select the | ||
| 755 | "LTTng - Linux Tracing Toolkit(incubation)" boxes.</para></listitem> | ||
| 756 | <listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem> | ||
| 757 | <listitem><para>After the Eclipse IDE restarts and from the Workbench, select | ||
| 758 | "Install New Software" from the "Help" pull-down menu.</para></listitem> | ||
| 759 | <listitem><para>Click the | ||
| 760 | "Available Software Sites" link.</para></listitem> | ||
| 761 | <listitem><para>Check the box next to | ||
| 762 | <filename>&ECLIPSE_UPDATES_URL;</filename> | ||
| 763 | and click "OK".</para></listitem> | ||
| 764 | <listitem><para>Select <filename>&ECLIPSE_UPDATES_URL;</filename> | ||
| 765 | from the "Work with:" pull-down menu.</para></listitem> | ||
| 766 | <listitem><para>Check the box next to <filename>TM and RSE Main Features</filename>. | ||
| 767 | </para></listitem> | ||
| 768 | <listitem><para>Expand the box next to <filename>TM and RSE Optional Add-ons</filename> | ||
| 769 | and select every item except <filename>RSE Unit Tests</filename> and | ||
| 770 | <filename>RSE WinCE Services (incubation)</filename>.</para></listitem> | ||
| 771 | <listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem> | ||
| 772 | <listitem><para>If necessary, select | ||
| 773 | "Install New Software" from the "Help" pull-down menu so you can click the | ||
| 774 | "Available Software Sites" link again.</para></listitem> | ||
| 775 | <listitem><para>After clicking "Available Software Sites", check the box next to | ||
| 776 | <filename>http://download.eclipse.org/tools/cdt/releases/indigo</filename> | ||
| 777 | and click "OK".</para></listitem> | ||
| 778 | <listitem><para>Select <filename>&ECLIPSE_INDIGO_CDT_URL;</filename> | ||
| 779 | from the "Work with:" pull-down menu.</para></listitem> | ||
| 780 | <listitem><para>Check the box next to <filename>CDT Main Features</filename>. | ||
| 781 | </para></listitem> | ||
| 782 | <listitem><para>Expand the box next to <filename>CDT Optional Features</filename> | ||
| 783 | and select <filename>C/C++ Remote Launch</filename> and | ||
| 784 | <filename>Target Communication Framework (incubation)</filename>.</para></listitem> | ||
| 785 | <listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem> | ||
| 786 | </orderedlist> | ||
| 787 | </para> | ||
| 788 | </section> | ||
| 789 | |||
| 790 | <section id='installing-the-eclipse-yocto-plug-in'> | ||
| 791 | <title>Installing or Accessing the Eclipse Yocto Plug-in</title> | ||
| 792 | |||
| 793 | <para> | ||
| 794 | You can install the Eclipse Yocto Plug-in into the Eclipse IDE | ||
| 795 | one of two ways: use the Yocto Project's Eclipse Update site to install the pre-built plug-in, | ||
| 796 | or build and install the plug-in from the latest source code. | ||
| 797 | If you don't want to permanently install the plug-in but just want to try it out | ||
| 798 | within the Eclipse environment, you can import the plug-in project from the | ||
| 799 | Yocto Project source repositories. | ||
| 800 | </para> | ||
| 801 | |||
| 802 | <section id='new-software'> | ||
| 803 | <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title> | ||
| 804 | |||
| 805 | <para> | ||
| 806 | To install the Eclipse Yocto Plug-in from the update site, | ||
| 807 | follow these steps: | ||
| 808 | <orderedlist> | ||
| 809 | <listitem><para>Start up the Eclipse IDE.</para></listitem> | ||
| 810 | <listitem><para>In Eclipse, select "Install New Software" from the "Help" menu.</para></listitem> | ||
| 811 | <listitem><para>Click "Add..." in the "Work with:" area.</para></listitem> | ||
| 812 | <listitem><para>Enter | ||
| 813 | <filename>&ECLIPSE_DL_PLUGIN_URL;</filename> | ||
| 814 | in the URL field and provide a meaningful name in the "Name" field.</para></listitem> | ||
| 815 | <listitem><para>Click "OK" to have the entry added to the "Work with:" | ||
| 816 | drop-down list.</para></listitem> | ||
| 817 | <listitem><para>Select the entry for the plug-in from the "Work with:" drop-down | ||
| 818 | list.</para></listitem> | ||
| 819 | <listitem><para>Check the box next to <filename>Development tools and SDKs for Yocto Linux</filename>. | ||
| 820 | </para></listitem> | ||
| 821 | <listitem><para>Complete the remaining software installation steps and | ||
| 822 | then restart the Eclipse IDE to finish the installation of the plug-in. | ||
| 823 | </para></listitem> | ||
| 824 | </orderedlist> | ||
| 825 | </para> | ||
| 826 | </section> | ||
| 827 | |||
| 828 | <section id='zip-file-method'> | ||
| 829 | <title>Installing the Plug-in Using the Latest Source Code</title> | ||
| 830 | |||
| 831 | <para> | ||
| 832 | To install the Eclipse Yocto Plug-in from the latest source code, follow these steps: | ||
| 833 | <orderedlist> | ||
| 834 | <listitem><para>Open a shell and create a Git repository with: | ||
| 835 | <literallayout class='monospaced'> | ||
| 836 | $ git clone git://git.yoctoproject.org/eclipse-poky yocto-eclipse | ||
| 837 | </literallayout> | ||
| 838 | For this example, the repository is named | ||
| 839 | <filename>~/yocto-eclipse</filename>.</para></listitem> | ||
| 840 | <listitem><para>Locate the <filename>build.sh</filename> script in the | ||
| 841 | Git repository you created in the previous step. | ||
| 842 | The script is located in the <filename>scripts</filename>.</para></listitem> | ||
| 843 | <listitem><para>Be sure to set and export the <filename>ECLIPSE_HOME</filename> environment | ||
| 844 | variable to the top-level directory in which you installed the Indigo | ||
| 845 | version of Eclipse. | ||
| 846 | For example, if your Eclipse directory is <filename>$HOME/eclipse</filename>, | ||
| 847 | use the following: | ||
| 848 | <literallayout class='monospaced'> | ||
| 849 | $ export ECLIPSE_HOME=$HOME/eclipse | ||
| 850 | </literallayout></para></listitem> | ||
| 851 | <listitem><para>Run the <filename>build.sh</filename> script and provide the | ||
| 852 | name of the Git branch along with the Yocto Project release you are | ||
| 853 | using. | ||
| 854 | Here is an example that uses the <filename>master</filename> Git repository | ||
| 855 | and the <filename>1.1M4</filename> release: | ||
| 856 | <literallayout class='monospaced'> | ||
| 857 | $ scripts/build.sh master 1.1M4 | ||
| 858 | </literallayout> | ||
| 859 | After running the script, the file | ||
| 860 | <filename>org.yocto.sdk-<release>-<date>-archive.zip</filename> | ||
| 861 | is in the current directory.</para></listitem> | ||
| 862 | <listitem><para>If necessary, start the Eclipse IDE and be sure you are in the | ||
| 863 | Workbench.</para></listitem> | ||
| 864 | <listitem><para>Select "Install New Software" from the "Help" pull-down menu. | ||
| 865 | </para></listitem> | ||
| 866 | <listitem><para>Click "Add".</para></listitem> | ||
| 867 | <listitem><para>Provide anything you want in the "Name" field.</para></listitem> | ||
| 868 | <listitem><para>Click "Archive" and browse to the ZIP file you built | ||
| 869 | in step four. | ||
| 870 | This ZIP file should not be "unzipped", and must be the | ||
| 871 | <filename>*archive.zip</filename> file created by running the | ||
| 872 | <filename>build.sh</filename> script.</para></listitem> | ||
| 873 | <listitem><para>Check the box next to the new entry in the installation window and complete | ||
| 874 | the installation.</para></listitem> | ||
| 875 | <listitem><para>Restart the Eclipse IDE if necessary.</para></listitem> | ||
| 876 | </orderedlist> | ||
| 877 | </para> | ||
| 878 | |||
| 879 | <para> | ||
| 880 | At this point you should be able to configure the Eclipse Yocto Plug-in as described in the | ||
| 881 | "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>" | ||
| 882 | section.</para> | ||
| 883 | </section> | ||
| 884 | |||
| 885 | <section id='yocto-project-source'> | ||
| 886 | <title>Importing the Plug-in Project into the Eclipse Environment</title> | ||
| 887 | |||
| 888 | <para> | ||
| 889 | Importing the Eclipse Yocto Plug-in project from the Yocto Project source repositories | ||
| 890 | is useful when you want to try out the latest plug-in from the tip of plug-in's | ||
| 891 | development tree. | ||
| 892 | It is important to understand when you import the plug-in you are not installing | ||
| 893 | it into the Eclipse application. | ||
| 894 | Rather, you are importing the project and just using it. | ||
| 895 | To import the plug-in project, follow these steps: | ||
| 896 | <orderedlist> | ||
| 897 | <listitem><para>Open a shell and create a Git repository with: | ||
| 898 | <literallayout class='monospaced'> | ||
| 899 | $ git clone git://git.yoctoproject.org/eclipse-poky yocto-eclipse | ||
| 900 | </literallayout> | ||
| 901 | For this example, the repository is named | ||
| 902 | <filename>~/yocto-eclipse</filename>.</para></listitem> | ||
| 903 | <listitem><para>In Eclipse, select "Import" from the "File" menu.</para></listitem> | ||
| 904 | <listitem><para>Expand the "General" box and select "existing projects into workspace" | ||
| 905 | and then click "Next".</para></listitem> | ||
| 906 | <listitem><para>Select the root directory and browse to | ||
| 907 | <filename>~/yocto-eclipse/plugins</filename>.</para></listitem> | ||
| 908 | <listitem><para>Three plug-ins exist: "org.yocto.bc.ui", "org.yocto.sdk.ide", and | ||
| 909 | "org.yocto.sdk.remotetools". | ||
| 910 | Select and import all of them.</para></listitem> | ||
| 911 | </orderedlist> | ||
| 912 | </para> | ||
| 913 | |||
| 914 | <para> | ||
| 915 | The left navigation pane in the Eclipse application shows the default projects. | ||
| 916 | Right-click on one of these projects and run it as an Eclipse application. | ||
| 917 | This brings up a second instance of Eclipse IDE that has the Yocto Plug-in. | ||
| 918 | </para> | ||
| 919 | </section> | ||
| 920 | </section> | ||
| 921 | |||
| 922 | <section id='configuring-the-eclipse-yocto-plug-in'> | ||
| 923 | <title>Configuring the Eclipse Yocto Plug-in</title> | ||
| 924 | |||
| 925 | <para> | ||
| 926 | Configuring the Eclipse Yocto Plug-in involves setting the Cross | ||
| 927 | Compiler options and the Target options. | ||
| 928 | The configurations you choose become the default settings for all projects. | ||
| 929 | You do have opportunities to change them later when | ||
| 930 | you configure the project (see the following section). | ||
| 931 | </para> | ||
| 932 | |||
| 933 | <para> | ||
| 934 | To start, you need to do the following from within the Eclipse IDE: | ||
| 935 | <itemizedlist> | ||
| 936 | <listitem><para>Choose <filename>Windows -> Preferences</filename> to display | ||
| 937 | the <filename>Preferences</filename> Dialog</para></listitem> | ||
| 938 | <listitem><para>Click <filename>Yocto Project ADT</filename></para></listitem> | ||
| 939 | </itemizedlist> | ||
| 940 | </para> | ||
| 941 | |||
| 942 | <section id='configuring-the-cross-compiler-options'> | ||
| 943 | <title>Configuring the Cross-Compiler Options</title> | ||
| 944 | |||
| 945 | <para> | ||
| 946 | To configure the Cross Compiler Options, you must select the type of toolchain, | ||
| 947 | point to the toolchain, specify the sysroot location, and select the target architecture. | ||
| 948 | <itemizedlist> | ||
| 949 | <listitem><para><emphasis>Selecting the Toolchain Type:</emphasis> | ||
| 950 | Choose between <filename>Standalone pre-built toolchain</filename> | ||
| 951 | and <filename>Build system derived toolchain</filename> for Cross | ||
| 952 | Compiler Options. | ||
| 953 | <itemizedlist> | ||
| 954 | <listitem><para><emphasis> | ||
| 955 | <filename>Standalone Pre-built Toolchain:</filename></emphasis> | ||
| 956 | Select this mode when you are using a stand-alone cross-toolchain. | ||
| 957 | For example, suppose you are an application developer and do not | ||
| 958 | need to build a target image. | ||
| 959 | Instead, you just want to use an architecture-specific toolchain on an | ||
| 960 | existing kernel and target root filesystem. | ||
| 961 | </para></listitem> | ||
| 962 | <listitem><para><emphasis> | ||
| 963 | <filename>Build System Derived Toolchain:</filename></emphasis> | ||
| 964 | Select this mode if the cross-toolchain has been installed and built | ||
| 965 | as part of the build directory. | ||
| 966 | When you select <filename>Build system derived toolchain</filename>, | ||
| 967 | you are using the toolchain bundled | ||
| 968 | inside the build directory. | ||
| 969 | </para></listitem> | ||
| 970 | </itemizedlist> | ||
| 971 | </para></listitem> | ||
| 972 | <listitem><para><emphasis>Point to the Toolchain:</emphasis> | ||
| 973 | If you are using a stand-alone pre-built toolchain, you should be pointing to the | ||
| 974 | <filename>&YOCTO_ADTPATH_DIR;</filename> directory. | ||
| 975 | This is the location for toolchains installed by the ADT Installer or by hand. | ||
| 976 | Sections "<ulink url='&YOCTO_DOCS_ADT_URL;#configuring-and-running-the-adt-installer-script'>Configuring | ||
| 977 | and Running the ADT Installer Script</ulink>" and | ||
| 978 | "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" | ||
| 979 | in the Yocto Project Application Developer's Guide | ||
| 980 | describe two ways to install a stand-alone cross-toolchain in the | ||
| 981 | <filename>/opt/poky</filename> directory. | ||
| 982 | <note>It is possible to install a stand-alone cross-toolchain in a directory | ||
| 983 | other than <filename>/opt/poky</filename>. | ||
| 984 | However, doing so is discouraged.</note></para> | ||
| 985 | <para>If you are using a system-derived toolchain, the path you provide | ||
| 986 | for the <filename>Toolchain Root Location</filename> | ||
| 987 | field is the build directory. | ||
| 988 | See the "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-toolchain-from-within-the-build-tree'>Using | ||
| 989 | BitBake and the build directory</ulink>" section in the Yocto Project Application | ||
| 990 | Developer's Guide for information on how to install the toolchain into the build | ||
| 991 | directory.</para></listitem> | ||
| 992 | <listitem><para><emphasis>Specify the Sysroot Location:</emphasis> | ||
| 993 | This location is where the root filesystem for the | ||
| 994 | target hardware is created on the development system by the ADT Installer. | ||
| 995 | The QEMU user-space tools, the | ||
| 996 | NFS boot process, and the cross-toolchain all use the sysroot location. | ||
| 997 | </para></listitem> | ||
| 998 | <listitem><para><emphasis>Select the Target Architecture:</emphasis> | ||
| 999 | The target architecture is the type of hardware you are | ||
| 1000 | going to use or emulate. | ||
| 1001 | Use the pull-down <filename>Target Architecture</filename> menu to make | ||
| 1002 | your selection. | ||
| 1003 | The pull-down menu should have the supported architectures. | ||
| 1004 | If the architecture you need is not listed in the menu, you | ||
| 1005 | will need to build the image. | ||
| 1006 | See the "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section | ||
| 1007 | of The Yocto Project Quick Start for more information.</para></listitem> | ||
| 1008 | </itemizedlist> | ||
| 1009 | </para> | ||
| 1010 | </section> | ||
| 1011 | |||
| 1012 | <section id='configuring-the-target-options'> | ||
| 1013 | <title>Configuring the Target Options</title> | ||
| 1014 | |||
| 1015 | <para> | ||
| 1016 | You can choose to emulate hardware using the QEMU emulator, or you | ||
| 1017 | can choose to run your image on actual hardware. | ||
| 1018 | <itemizedlist> | ||
| 1019 | <listitem><para><emphasis><filename>QEMU:</filename></emphasis> Select this option if | ||
| 1020 | you will be using the QEMU emulator. | ||
| 1021 | If you are using the emulator, you also need to locate the kernel | ||
| 1022 | and specify any custom options.</para> | ||
| 1023 | <para>If you selected <filename>Build system derived toolchain</filename>, | ||
| 1024 | the target kernel you built will be located in the | ||
| 1025 | build directory in <filename>tmp/deploy/images</filename> directory. | ||
| 1026 | If you selected <filename>Standalone pre-built toolchain</filename>, the | ||
| 1027 | pre-built image you downloaded is located | ||
| 1028 | in the directory you specified when you downloaded the image.</para> | ||
| 1029 | <para>Most custom options are for advanced QEMU users to further | ||
| 1030 | customize their QEMU instance. | ||
| 1031 | These options are specified between paired angled brackets. | ||
| 1032 | Some options must be specified outside the brackets. | ||
| 1033 | In particular, the options <filename>serial</filename>, | ||
| 1034 | <filename>nographic</filename>, and <filename>kvm</filename> must all | ||
| 1035 | be outside the brackets. | ||
| 1036 | Use the <filename>man qemu</filename> command to get help on all the options | ||
| 1037 | and their use. | ||
| 1038 | The following is an example: | ||
| 1039 | <literallayout class='monospaced'> | ||
| 1040 | serial ‘<-m 256 -full-screen>’ | ||
| 1041 | </literallayout></para> | ||
| 1042 | <para> | ||
| 1043 | Regardless of the mode, Sysroot is already defined as part of the | ||
| 1044 | Cross Compiler Options configuration in the | ||
| 1045 | <filename>Sysroot Location:</filename> field.</para></listitem> | ||
| 1046 | <listitem><para><emphasis><filename>External HW:</filename></emphasis> Select this option | ||
| 1047 | if you will be using actual hardware.</para></listitem> | ||
| 1048 | </itemizedlist> | ||
| 1049 | </para> | ||
| 1050 | |||
| 1051 | <para> | ||
| 1052 | Click the <filename>OK</filename> button to save your plug-in configurations. | ||
| 1053 | </para> | ||
| 1054 | </section> | ||
| 1055 | </section> | ||
| 1056 | </section> | ||
| 1057 | |||
| 1058 | <section id='creating-the-project'> | ||
| 1059 | <title>Creating the Project</title> | ||
| 1060 | |||
| 1061 | <para> | ||
| 1062 | You can create two types of projects: Autotools-based, or Makefile-based. | ||
| 1063 | This section describes how to create Autotools-based projects from within | ||
| 1064 | the Eclipse IDE. | ||
| 1065 | For information on creating Makefile-based projects in a terminal window, see the section | ||
| 1066 | "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-command-line'>Using the Command Line</ulink>" | ||
| 1067 | in the Yocto Project Application Developer's Guide. | ||
| 1068 | </para> | ||
| 1069 | |||
| 1070 | <para> | ||
| 1071 | To create a project based on a Yocto template and then display the source code, | ||
| 1072 | follow these steps: | ||
| 1073 | <orderedlist> | ||
| 1074 | <listitem><para>Select <filename>File -> New -> Project</filename>.</para></listitem> | ||
| 1075 | <listitem><para>Double click <filename>CC++</filename>.</para></listitem> | ||
| 1076 | <listitem><para>Double click <filename>C Project</filename> to create the project.</para></listitem> | ||
| 1077 | <listitem><para>Expand <filename>Yocto Project ADT Project</filename>.</para></listitem> | ||
| 1078 | <listitem><para>Select <filename>Hello World ANSI C Autotools Project</filename>. | ||
| 1079 | This is an Autotools-based project based on a Yocto template.</para></listitem> | ||
| 1080 | <listitem><para>Put a name in the <filename>Project name:</filename> field. | ||
| 1081 | Do not use hyphens as part of the name.</para></listitem> | ||
| 1082 | <listitem><para>Click <filename>Next</filename>.</para></listitem> | ||
| 1083 | <listitem><para>Add information in the <filename>Author</filename> and | ||
| 1084 | <filename>Copyright notice</filename> fields.</para></listitem> | ||
| 1085 | <listitem><para>Be sure the <filename>License</filename> field is correct.</para></listitem> | ||
| 1086 | <listitem><para>Click <filename>Finish</filename>.</para></listitem> | ||
| 1087 | <listitem><para>If the "open perspective" prompt appears, click "Yes" so that you | ||
| 1088 | in the C/C++ perspective.</para></listitem> | ||
| 1089 | <listitem><para>The left-hand navigation pane shows your project. | ||
| 1090 | You can display your source by double clicking the project's source file. | ||
| 1091 | </para></listitem> | ||
| 1092 | </orderedlist> | ||
| 1093 | </para> | ||
| 1094 | </section> | ||
| 1095 | |||
| 1096 | <section id='configuring-the-cross-toolchains'> | ||
| 1097 | <title>Configuring the Cross-Toolchains</title> | ||
| 1098 | |||
| 1099 | <para> | ||
| 1100 | The earlier section, "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring | ||
| 1101 | the Eclipse Yocto Plug-in</link>", sets up the default project | ||
| 1102 | configurations. | ||
| 1103 | You can override these settings for a given project by following these steps: | ||
| 1104 | <orderedlist> | ||
| 1105 | <listitem><para>Select <filename>Project -> Change Yocto Project Settings</filename>: | ||
| 1106 | This selection brings up the <filename>Yocot Project Settings</filename> Dialog | ||
| 1107 | and allows you to make changes specific to an individual project. | ||
| 1108 | </para> | ||
| 1109 | <para>By default, the Cross Compiler Options and Target Options for a project | ||
| 1110 | are inherited from settings you provide using the <filename>Preferences</filename> | ||
| 1111 | Dialog as described earlier | ||
| 1112 | in the "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse | ||
| 1113 | Yocto Plug-in</link>" section. | ||
| 1114 | The <filename>Yocto Project Settings</filename> | ||
| 1115 | Dialog allows you to override those default settings | ||
| 1116 | for a given project.</para></listitem> | ||
| 1117 | <listitem><para>Make your configurations for the project and click "OK".</para></listitem> | ||
| 1118 | <listitem><para>Select <filename>Project -> Reconfigure Project</filename>: | ||
| 1119 | This selection reconfigures the project by running | ||
| 1120 | <filename>autogen.sh</filename> in the workspace for your project. | ||
| 1121 | The script also runs <filename>libtoolize</filename>, <filename>aclocal</filename>, | ||
| 1122 | <filename>autoconf</filename>, <filename>autoheader</filename>, | ||
| 1123 | <filename>automake --a</filename>, and | ||
| 1124 | <filename>./configure</filename>. | ||
| 1125 | Click on the <filename>Console</filename> tab beneath your source code to | ||
| 1126 | see the results of reconfiguring your project.</para></listitem> | ||
| 1127 | </orderedlist> | ||
| 1128 | </para> | ||
| 1129 | </section> | ||
| 1130 | |||
| 1131 | <section id='building-the-project'> | ||
| 1132 | <title>Building the Project</title> | ||
| 1133 | |||
| 1134 | <para> | ||
| 1135 | To build the project, select <filename>Project -> Build Project</filename>. | ||
| 1136 | The console should update and you can note the cross-compiler you are using. | ||
| 1137 | </para> | ||
| 1138 | </section> | ||
| 1139 | |||
| 1140 | <section id='starting-qemu-in-user-space-nfs-mode'> | ||
| 1141 | <title>Starting QEMU in User Space NFS Mode</title> | ||
| 1142 | |||
| 1143 | <para> | ||
| 1144 | To start the QEMU emulator from within Eclipse, follow these steps: | ||
| 1145 | <orderedlist> | ||
| 1146 | <listitem><para>Expose the <filename>Run -> External Tools</filename> menu. | ||
| 1147 | Your image should appear as a selectable menu item. | ||
| 1148 | </para></listitem> | ||
| 1149 | <listitem><para>Select your image from the menu to launch the | ||
| 1150 | emulator in a new window.</para></listitem> | ||
| 1151 | <listitem><para>If needed, enter your host root password in the shell window at the prompt. | ||
| 1152 | This sets up a <filename>Tap 0</filename> connection needed for running in user-space | ||
| 1153 | NFS mode.</para></listitem> | ||
| 1154 | <listitem><para>Wait for QEMU to launch.</para></listitem> | ||
| 1155 | <listitem><para>Once QEMU launches, you can begin operating within that | ||
| 1156 | environment. | ||
| 1157 | For example, you could determine the IP Address | ||
| 1158 | for the user-space NFS by using the <filename>ifconfig</filename> command. | ||
| 1159 | </para></listitem> | ||
| 1160 | </orderedlist> | ||
| 1161 | </para> | ||
| 1162 | </section> | ||
| 1163 | |||
| 1164 | <section id='deploying-and-debugging-the-application'> | ||
| 1165 | <title>Deploying and Debugging the Application</title> | ||
| 1166 | |||
| 1167 | <para> | ||
| 1168 | Once the QEMU emulator is running the image, using the Eclipse IDE | ||
| 1169 | you can deploy your application and use the emulator to perform debugging. | ||
| 1170 | Follow these steps to deploy the application. | ||
| 1171 | <orderedlist> | ||
| 1172 | <listitem><para>Select <filename>Run -> Debug Configurations...</filename></para></listitem> | ||
| 1173 | <listitem><para>In the left area, expand <filename>C/C++Remote Application</filename>.</para></listitem> | ||
| 1174 | <listitem><para>Locate your project and select it to bring up a new | ||
| 1175 | tabbed view in the <filename>Debug Configurations</filename> Dialog.</para></listitem> | ||
| 1176 | <listitem><para>Enter the absolute path into which you want to deploy | ||
| 1177 | the application. | ||
| 1178 | Use the <filename>Remote Absolute File Path for C/C++Application:</filename> field. | ||
| 1179 | For example, enter <filename>/usr/bin/<programname></filename>.</para></listitem> | ||
| 1180 | <listitem><para>Click on the <filename>Debugger</filename> tab to see the cross-tool debugger | ||
| 1181 | you are using.</para></listitem> | ||
| 1182 | <listitem><para>Click on the <filename>Main</filename> tab.</para></listitem> | ||
| 1183 | <listitem><para>Create a new connection to the QEMU instance | ||
| 1184 | by clicking on <filename>new</filename>.</para></listitem> | ||
| 1185 | <listitem><para>Select <filename>TCF</filename>, which means Target Communication | ||
| 1186 | Framework.</para></listitem> | ||
| 1187 | <listitem><para>Click <filename>Next</filename>.</para></listitem> | ||
| 1188 | <listitem><para>Clear out the <filename>host name</filename> field and enter the IP Address | ||
| 1189 | determined earlier.</para></listitem> | ||
| 1190 | <listitem><para>Click <filename>Finish</filename> to close the | ||
| 1191 | <filename>New Connections</filename> Dialog.</para></listitem> | ||
| 1192 | <listitem><para>Use the drop-down menu now in the <filename>Connection</filename> field and pick | ||
| 1193 | the IP Address you entered.</para></listitem> | ||
| 1194 | <listitem><para>Click <filename>Debug</filename> to bring up a login screen | ||
| 1195 | and login.</para></listitem> | ||
| 1196 | <listitem><para>Accept the debug perspective.</para></listitem> | ||
| 1197 | </orderedlist> | ||
| 1198 | </para> | ||
| 1199 | </section> | ||
| 1200 | |||
| 1201 | <section id='running-user-space-tools'> | ||
| 1202 | <title>Running User-Space Tools</title> | ||
| 1203 | |||
| 1204 | <para> | ||
| 1205 | As mentioned earlier in the manual, several tools exist that enhance | ||
| 1206 | your development experience. | ||
| 1207 | These tools are aids in developing and debugging applications and images. | ||
| 1208 | You can run these user-space tools from within the Eclipse IDE through the | ||
| 1209 | <filename>YoctoTools</filename> menu. | ||
| 1210 | </para> | ||
| 1211 | |||
| 1212 | <para> | ||
| 1213 | Once you pick a tool, you need to configure it for the remote target. | ||
| 1214 | Every tool needs to have the connection configured. | ||
| 1215 | You must select an existing TCF-based RSE connection to the remote target. | ||
| 1216 | If one does not exist, click <filename>New</filename> to create one. | ||
| 1217 | </para> | ||
| 1218 | |||
| 1219 | <para> | ||
| 1220 | Here are some specifics about the remote tools: | ||
| 1221 | <itemizedlist> | ||
| 1222 | <listitem><para><emphasis><filename>OProfile</filename>:</emphasis> Selecting this tool causes | ||
| 1223 | the <filename>oprofile-server</filename> on the remote target to launch on | ||
| 1224 | the local host machine. | ||
| 1225 | The <filename>oprofile-viewer</filename> must be installed on the local host machine and the | ||
| 1226 | <filename>oprofile-server</filename> must be installed on the remote target, | ||
| 1227 | respectively, in order to use. | ||
| 1228 | You must compile and install the <filename>oprofile-viewer</filename> from the source code | ||
| 1229 | on your local host machine. | ||
| 1230 | Furthermore, in order to convert the target's sample format data into a form that the | ||
| 1231 | host can use, you must have <filename>oprofile</filename> version 0.9.4 or | ||
| 1232 | greater installed on the host.</para> | ||
| 1233 | <para>You can locate both the viewer and server from | ||
| 1234 | <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/oprofileui/'></ulink>. | ||
| 1235 | <note>The <filename>oprofile-server</filename> is installed by default on | ||
| 1236 | the <filename>core-image-sato-sdk</filename> image.</note></para></listitem> | ||
| 1237 | <listitem><para><emphasis><filename>Lttng-ust</filename>:</emphasis> Selecting this tool runs | ||
| 1238 | <filename>usttrace</filename> on the remote target, transfers the output data back | ||
| 1239 | to the local host machine, and uses the <filename>lttng</filename> Eclipse plug-in to | ||
| 1240 | graphically display the output. | ||
| 1241 | For information on how to use <filename>lttng</filename> to trace an application, see | ||
| 1242 | <ulink url='http://lttng.org/files/ust/manual/ust.html'></ulink>.</para> | ||
| 1243 | <para>For <filename>Application</filename>, you must supply the absolute path name of the | ||
| 1244 | application to be traced by user mode <filename>lttng</filename>. | ||
| 1245 | For example, typing <filename>/path/to/foo</filename> triggers | ||
| 1246 | <filename>usttrace /path/to/foo</filename> on the remote target to trace the | ||
| 1247 | program <filename>/path/to/foo</filename>.</para> | ||
| 1248 | <para><filename>Argument</filename> is passed to <filename>usttrace</filename> | ||
| 1249 | running on the remote target.</para> | ||
| 1250 | <para>Before you use the <filename>lttng-ust</filename> tool, you need to setup | ||
| 1251 | the <filename>lttng</filename> Eclipse plug-in and create a <filename>lttng</filename> | ||
| 1252 | project. | ||
| 1253 | Do the following: | ||
| 1254 | <orderedlist> | ||
| 1255 | <listitem><para>Follow these | ||
| 1256 | <ulink url='http://wiki.eclipse.org/Linux_Tools_Project/LTTng#Downloading_and_installing_the_LTTng_parser_library'>instructions</ulink> | ||
| 1257 | to download and install the <filename>lttng</filename> parser library. | ||
| 1258 | </para></listitem> | ||
| 1259 | <listitem><para>Select <filename>Window -> Open Perspective -> Other</filename> | ||
| 1260 | and then select <filename>LTTng</filename>.</para></listitem> | ||
| 1261 | <listitem><para>Click <filename>OK</filename> to change the Eclipse perspective | ||
| 1262 | into the <filename>LTTng</filename> perspective.</para></listitem> | ||
| 1263 | <listitem><para>Create a new <filename>LTTng</filename> project by selecting | ||
| 1264 | <filename>File -> New -> Project</filename>.</para></listitem> | ||
| 1265 | <listitem><para>Choose <filename>LTTng -> LTTng Project</filename>.</para></listitem> | ||
| 1266 | <listitem><para>Click <filename>YoctoTools -> lttng-ust</filename> to start user mode | ||
| 1267 | <filename>lttng</filename> on the remote target.</para></listitem> | ||
| 1268 | </orderedlist></para> | ||
| 1269 | <para>After the output data has been transferred from the remote target back to the local | ||
| 1270 | host machine, new traces will be imported into the selected <filename>LTTng</filename> project. | ||
| 1271 | Then you can go to the <filename>LTTng</filename> project, right click the imported | ||
| 1272 | trace, and set the trace type as the <filename>LTTng</filename> kernel trace. | ||
| 1273 | Finally, right click the imported trace and select <filename>Open</filename> | ||
| 1274 | to display the data graphically.</para></listitem> | ||
| 1275 | <listitem><para><emphasis><filename>PowerTOP</filename>:</emphasis> Selecting this tool runs | ||
| 1276 | <filename>powertop</filename> on the remote target machine and displays the results in a | ||
| 1277 | new view called <filename>powertop</filename>.</para> | ||
| 1278 | <para><filename>Time to gather data(sec):</filename> is the time passed in seconds before data | ||
| 1279 | is gathered from the remote target for analysis.</para> | ||
| 1280 | <para><filename>show pids in wakeups list:</filename> corresponds to the | ||
| 1281 | <filename>-p</filename> argument | ||
| 1282 | passed to <filename>powertop</filename>.</para></listitem> | ||
| 1283 | <listitem><para><emphasis><filename>LatencyTOP and Perf</filename>:</emphasis> | ||
| 1284 | <filename>latencytop</filename> identifies system latency, while | ||
| 1285 | <filename>perf</filename> monitors the system's | ||
| 1286 | performance counter registers. | ||
| 1287 | Selecting either of these tools causes an RSE terminal view to appear | ||
| 1288 | from which you can run the tools. | ||
| 1289 | Both tools refresh the entire screen to display results while they run.</para></listitem> | ||
| 1290 | </itemizedlist> | ||
| 1291 | </para> | ||
| 1292 | </section> | ||
| 1293 | |||
| 1294 | <section id='customizing-an-image-using-a-bitbake-commander-project-and-hob'> | ||
| 1295 | <title>Customizing an Image Using a BitBake Commander Project and Hob</title> | ||
| 1296 | |||
| 1297 | <para> | ||
| 1298 | Within Eclipse, you can create a Yocto BitBake Commander project, | ||
| 1299 | edit the metadata, and then use the | ||
| 1300 | <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink> to build a customized | ||
| 1301 | image all within one IDE. | ||
| 1302 | </para> | ||
| 1303 | |||
| 1304 | <section id='creating-the-yocto-bitbake-commander-project'> | ||
| 1305 | <title>Creating the Yocto BitBake Commander Project</title> | ||
| 1306 | |||
| 1307 | <para> | ||
| 1308 | To create a Yocto BitBake Commander project, follow these steps: | ||
| 1309 | <orderedlist> | ||
| 1310 | <listitem><para>Select <filename>Window -> Open Perspective -> Other</filename> | ||
| 1311 | and then choose <filename>Bitbake Commander</filename>.</para></listitem> | ||
| 1312 | <listitem><para>Click <filename>OK</filename> to change the Eclipse perspective into the | ||
| 1313 | Bitbake Commander perspective.</para></listitem> | ||
| 1314 | <listitem><para>Select <filename>File -> New -> Project</filename> to create a new Yocto | ||
| 1315 | Bitbake Commander project.</para></listitem> | ||
| 1316 | <listitem><para>Choose <filename>Yocto Project Bitbake Commander -> New Yocto Project</filename> | ||
| 1317 | and click <filename>Next</filename>.</para></listitem> | ||
| 1318 | <listitem><para>Enter the Project Name and choose the Project Location. | ||
| 1319 | The Yocto project's metadata files will be put under the directory | ||
| 1320 | <filename><project_location>/<project_name></filename>. | ||
| 1321 | If that directory does not exist, you need to check | ||
| 1322 | the "Clone from Yocto Git Repository" box, which would execute a | ||
| 1323 | <filename>git clone</filename> command to get the project's metadata files. | ||
| 1324 | </para></listitem> | ||
| 1325 | <listitem><para>Select <filename>Finish</filename> to create the project.</para></listitem> | ||
| 1326 | </orderedlist> | ||
| 1327 | </para> | ||
| 1328 | </section> | ||
| 1329 | |||
| 1330 | <section id='editing-the-metadata-files'> | ||
| 1331 | <title>Editing the Metadata Files</title> | ||
| 1332 | |||
| 1333 | <para> | ||
| 1334 | After you create the Yocto Bitbake Commander project, you can modify the metadata files | ||
| 1335 | by opening them in the project. | ||
| 1336 | When editing recipe files (<filename>.bb</filename> files), you can view BitBake | ||
| 1337 | variable values and information by hovering the mouse pointer over the variable name and | ||
| 1338 | waiting a few seconds. | ||
| 1339 | </para> | ||
| 1340 | |||
| 1341 | <para> | ||
| 1342 | To edit the metadata, follow these steps: | ||
| 1343 | <orderedlist> | ||
| 1344 | <listitem><para>Select your Yocto Bitbake Commander project.</para></listitem> | ||
| 1345 | <listitem><para>Select <filename>File -> New -> Yocto BitBake Commander -> BitBake Recipe</filename> | ||
| 1346 | to open a new recipe wizard.</para></listitem> | ||
| 1347 | <listitem><para>Point to your source by filling in the "SRC_URL" field. | ||
| 1348 | For example, you can add a recipe to your | ||
| 1349 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink> | ||
| 1350 | by defining "SRC_URL" as follows: | ||
| 1351 | <literallayout class='monospaced'> | ||
| 1352 | ftp://ftp.gnu.org/gnu/m4/m4-1.4.9.tar.gz | ||
| 1353 | </literallayout></para></listitem> | ||
| 1354 | <listitem><para>Click "Populate" to calculate the archive md5, sha256, | ||
| 1355 | license checksum values and to auto-generate the recipe filename.</para></listitem> | ||
| 1356 | <listitem><para>Fill in the "Description" field.</para></listitem> | ||
| 1357 | <listitem><para>Be sure values for all required fields exist.</para></listitem> | ||
| 1358 | <listitem><para>Click <filename>Finish</filename>.</para></listitem> | ||
| 1359 | </orderedlist> | ||
| 1360 | </para> | ||
| 1361 | </section> | ||
| 1362 | |||
| 1363 | <section id='buiding-and-customizing-the-image'> | ||
| 1364 | <title>Building and Customizing the Image</title> | ||
| 1365 | |||
| 1366 | <para> | ||
| 1367 | To build and customize the image in Eclipse, follow these steps: | ||
| 1368 | <orderedlist> | ||
| 1369 | <listitem><para>Select your Yocto Bitbake Commander project.</para></listitem> | ||
| 1370 | <listitem><para>Select <filename>Project -> Launch HOB</filename>.</para></listitem> | ||
| 1371 | <listitem><para>Enter the build directory where you want to put your final images.</para></listitem> | ||
| 1372 | <listitem><para>Click <filename>OK</filename> to launch Hob.</para></listitem> | ||
| 1373 | <listitem><para>Use Hob to customize and build your own images. | ||
| 1374 | For information on Hob, see the | ||
| 1375 | <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob Project Page</ulink> on the | ||
| 1376 | Yocto Project website.</para></listitem> | ||
| 1377 | </orderedlist> | ||
| 1378 | </para> | ||
| 1379 | </section> | ||
| 1380 | </section> | ||
| 1381 | </section> | ||
| 1382 | |||
| 644 | <section id='workflow-using-stand-alone-cross-development-toolchains'> | 1383 | <section id='workflow-using-stand-alone-cross-development-toolchains'> |
| 645 | <title>Workflow Using Stand-alone Cross-development Toolchains</title> | 1384 | <title>Workflow Using Stand-alone Cross-development Toolchains</title> |
| 646 | 1385 | ||