summaryrefslogtreecommitdiffstats
path: root/documentation/adt-manual
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2012-07-23 11:23:56 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2012-07-24 10:35:34 +0100
commit41c7020d7ae6c81e8fa092f2a0c8e0c3ac976a62 (patch)
treeebc327616f0ceff8ba21fbf1004e6c85038e3982 /documentation/adt-manual
parentfad4b8fbbdab7a9701e63475317a804188376c27 (diff)
downloadpoky-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>
Diffstat (limited to 'documentation/adt-manual')
-rw-r--r--documentation/adt-manual/adt-eclipse.xml740
-rw-r--r--documentation/adt-manual/adt-intro.xml20
-rw-r--r--documentation/adt-manual/adt-manual.xml2
3 files changed, 15 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-&lt;release&gt;-&lt;date&gt;-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 -&gt; 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 ‘&lt;-m 256 -full-screen&gt;’
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 -&gt; New -&gt; 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 -&gt; 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 -&gt; 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 -&gt; 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 -&gt; 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 -&gt; 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/&lt;programname&gt;</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>&lt;project_location&gt;/&lt;project_name&gt;</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<!--
739vim: 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'>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-04-20 03:12:49 +0000