summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2016-08-12 10:20:16 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2016-08-25 23:09:27 +0100
commit4d5dc4a8908c4f67268f2058e1ea6d76f72ca0ef (patch)
tree3489d42ca80e9fdb6272d09341c2069b01188ac5 /documentation
parenta3f519e19399e239cf1efde523af426f6a519d4f (diff)
downloadpoky-4d5dc4a8908c4f67268f2058e1ea6d76f72ca0ef.tar.gz
sdk-manual: Created new Mars Eclipse appendix
Fixes [YOCTO #7546] First draft of the new appendix supporting the Mars version of eclipse. New appendix file created and entry made to the sdk-manual.xml file to include that new appendix file into the main book. (From yocto-docs rev: 2fb79c29bcbb5c0801f67d4c245c07c3aa9d2ca2) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> sdk-manual: WIP on appendix C Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/sdk-manual/sdk-appendix-mars.xml878
-rw-r--r--documentation/sdk-manual/sdk-intro.xml71
-rw-r--r--documentation/sdk-manual/sdk-manual.xml2
-rw-r--r--documentation/sdk-manual/sdk-using.xml152
4 files changed, 914 insertions, 189 deletions
diff --git a/documentation/sdk-manual/sdk-appendix-mars.xml b/documentation/sdk-manual/sdk-appendix-mars.xml
new file mode 100644
index 0000000000..185dd42092
--- /dev/null
+++ b/documentation/sdk-manual/sdk-appendix-mars.xml
@@ -0,0 +1,878 @@
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<appendix id='sdk-appendix-mars'>
6 <title>Using Eclipse Mars</title>
7
8 <para>
9 This release of the Yocto Project supports both the Neon and Mars
10 versions of the Eclipse IDE.
11 This appendix presents information that describes how to obtain and
12 configure the Mars version of Eclipse.
13 It also provides a basic project example that you can work through
14 from start to finish.
15 For general information on using the Eclipse IDE and the Yocto
16 Project Eclipse Plug-In, see the
17 "<link linkend='sdk-developing-applications-using-eclipse'>Developing Applications Using <trademark class='trade'>Eclipse</trademark></link>"
18 section.
19 </para>
20
21 <section id='mars-setting-up-the-eclipse-ide'>
22 <title>Setting Up the Mars Version of the Eclipse IDE</title>
23
24 <para>
25 To develop within the Eclipse IDE, you need to do the following:
26 <orderedlist>
27 <listitem><para>Install the Mars version of the Eclipse
28 IDE.</para></listitem>
29 <listitem><para>Configure the Eclipse IDE.
30 </para></listitem>
31 <listitem><para>Install the Eclipse Yocto Plug-in.
32 </para></listitem>
33 <listitem><para>Configure the Eclipse Yocto Plug-in.
34 </para></listitem>
35 </orderedlist>
36 <note>
37 Do not install Eclipse from your distribution's package
38 repository.
39 Be sure to install Eclipse from the official Eclipse
40 download site as directed in the next section.
41 </note>
42 </para>
43
44 <section id='mars-installing-eclipse-ide'>
45 <title>Installing the Mars Eclipse IDE</title>
46
47 <para>
48 Follow these steps to locate, install, and configure
49 Mars Eclipse:
50 <orderedlist>
51 <listitem><para><emphasis>Locate the Mars Download:</emphasis>
52 Open a browser and go to
53 <ulink url='http://www.eclipse.org/mars/'>http://www.eclipse.org/mars/</ulink>.
54 </para></listitem>
55 <listitem><para><emphasis>Download the Tarball:</emphasis>
56 Click the "Download" button and then use the "Linux
57 for Eclipse IDE for C++ Developers"
58 appropriate for your development system
59 (e.g.
60 <ulink url='http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/mars/2/eclipse-cpp-mars-2-linux-gtk-x86_64.tar.gz'>64-bit under Linux for Eclipse IDE for C++ Developers</ulink>
61 if your development system is a Linux 64-bit machine.
62 </para></listitem>
63 <listitem><para><emphasis>Unpack the Tarball:</emphasis>
64 Move to a clean directory and unpack the tarball.
65 Here is an example:
66 <literallayout class='monospaced'>
67 $ cd ~
68 $ tar -xzvf ~/Downloads/eclipse-cpp-mars-2-linux-gtk-x86_64.tar.gz
69 </literallayout>
70 Everything unpacks into a folder named "Eclipse".
71 </para></listitem>
72 <listitem><para><emphasis>Launch Eclipse:</emphasis>
73 Double click the "Eclipse" file in the folder to
74 launch Eclipse.
75 </para></listitem>
76 </orderedlist>
77 </para>
78 </section>
79
80 <section id='mars-configuring-the-mars-eclipse-ide'>
81 <title>Configuring the Mars Eclipse IDE</title>
82
83 <para>
84 Follow these steps to configure the Mars Eclipse IDE.
85 <note>
86 Depending on how you installed Eclipse and what you have
87 already done, some of the options will not appear.
88 If you cannot find an option as directed by the manual,
89 it has already been installed.
90 </note>
91 <orderedlist>
92 <listitem><para>Be sure Eclipse is running and
93 you are in your workbench.
94 </para></listitem>
95 <listitem><para>Select "Install New Software" from
96 the "Help" pull-down menu.
97 </para></listitem>
98 <listitem><para>Select
99 "Mars - http://download.eclipse.org/releases/mars"
100 from the "Work with:" pull-down menu.
101 </para></listitem>
102 <listitem><para>Expand the box next to
103 "Linux Tools" and select "C/C++ Remote
104 (Over TCF/TE) Run/Debug Launcher" and
105 "TM Terminal".
106 </para></listitem>
107 <listitem><para>Expand the box next to "Mobile and
108 Device Development" and select the following
109 boxes:
110 <literallayout class='monospaced'>
111 C/C++ Remote (Over TCF/TE) Run/Debug Launcher
112 Remote System Explorer User Actions
113 TM Terminal
114 TCF Remote System Explorer add-in
115 TCF Target Explorer
116 </literallayout>
117 </para></listitem>
118 <listitem><para>Expand the box next to
119 "Programming Languages" and select the
120 following boxes:
121 <literallayout class='monospaced'>
122 C/C++ Autotools Support
123 C/C++ Development Tools SDK
124 </literallayout>
125 </para></listitem>
126 <listitem><para>
127 Complete the installation by clicking through
128 appropriate "Next" and "Finish" buttons.
129 </para></listitem>
130 </orderedlist>
131 </para>
132 </section>
133
134 <section id='mars-installing-the-eclipse-yocto-plug-in'>
135 <title>Installing or Accessing the Mars Eclipse Yocto Plug-in</title>
136
137 <para>
138 You can install the Eclipse Yocto Plug-in into the Eclipse
139 IDE one of two ways: use the Yocto Project's Eclipse
140 Update site to install the pre-built plug-in or build and
141 install the plug-in from the latest source code.
142 </para>
143
144 <section id='mars-new-software'>
145 <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title>
146
147 <para>
148 To install the Mars Eclipse Yocto Plug-in from the update
149 site, follow these steps:
150 <orderedlist>
151 <listitem><para>Start up the Eclipse IDE.
152 </para></listitem>
153 <listitem><para>In Eclipse, select "Install New
154 Software" from the "Help" menu.
155 </para></listitem>
156 <listitem><para>Click "Add..." in the "Work with:"
157 area.
158 </para></listitem>
159 <listitem><para>Enter
160 <filename>&ECLIPSE_DL_PLUGIN_URL;/mars</filename>
161 in the URL field and provide a meaningful name
162 in the "Name" field.
163 </para></listitem>
164 <listitem><para>Click "OK" to have the entry added
165 to the "Work with:" drop-down list.
166 </para></listitem>
167 <listitem><para>Select the entry for the plug-in
168 from the "Work with:" drop-down list.
169 </para></listitem>
170 <listitem><para>Check the boxes next to the following:
171 <literallayout class='monospaced'>
172 Yocto Project ADT Plug-in
173 Yocto Project Bitbake Commander Plug-in
174 Yocto Project Documentation plug-in
175 </literallayout>
176 </para></listitem>
177 <listitem><para>Complete the remaining software
178 installation steps and then restart the Eclipse
179 IDE to finish the installation of the plug-in.
180 <note>
181 You can click "OK" when prompted about
182 installing software that contains unsigned
183 content.
184 </note>
185 </para></listitem>
186 </orderedlist>
187 </para>
188 </section>
189
190 <section id='mars-zip-file-method'>
191 <title>Installing the Plug-in Using the Latest Source Code</title>
192
193 <para>
194 To install the Mars Eclipse Yocto Plug-in from the latest
195 source code, follow these steps:
196 <orderedlist>
197 <listitem><para>Be sure your development system
198 has JDK 1.7+
199 </para></listitem>
200 <listitem><para>install X11-related packages:
201 <literallayout class='monospaced'>
202 $ sudo apt-get install xauth
203 </literallayout>
204 </para></listitem>
205 <listitem><para>In a new terminal shell, create a Git
206 repository with:
207 <literallayout class='monospaced'>
208 $ cd ~
209 $ git clone git://git.yoctoproject.org/eclipse-poky
210 </literallayout>
211 </para></listitem>
212 <listitem><para>Use Git to checkout the correct
213 tag:
214
215 <note><title>Developer's Note</title>
216 <para role='writernotes'>
217 Because the 2.2 tag will not exist until after
218 the release, I must first do the following
219 before running the
220 <filename>git checkout mars/yocto-&DISTRO;</filename>
221 command in this step:
222 <literallayout class='monospaced'>
223 $ git tag mars/yocto-2.2 origin/mars-master
224 </literallayout></para>
225 </note>
226
227 <literallayout class='monospaced'>
228 $ cd ~/eclipse-poky
229 $ git checkout mars/yocto-&DISTRO;
230 </literallayout>
231 This puts you in a detached HEAD state, which
232 is fine since you are only going to be building
233 and not developing.
234 </para></listitem>
235 <listitem><para>Change to the
236 <filename>scripts</filename>
237 directory within the Git repository:
238 <literallayout class='monospaced'>
239 $ cd scripts
240 </literallayout>
241 </para></listitem>
242 <listitem><para>Set up the local build environment
243 by running the setup script:
244 <literallayout class='monospaced'>
245 $ ./setup.sh
246 </literallayout>
247 When the script finishes execution,
248 it prompts you with instructions on how to run
249 the <filename>build.sh</filename> script, which
250 is also in the <filename>scripts</filename>
251 directory of the Git repository created
252 earlier.
253 </para></listitem>
254 <listitem><para>Run the <filename>build.sh</filename>
255 script as directed.
256 Be sure to provide the tag name, documentation
257 branch, and a release name.</para>
258 <para>
259 Following is an example:
260 <literallayout class='monospaced'>
261 $ ECLIPSE_HOME=/home/scottrif/eclipse-poky/scripts/eclipse ./build.sh -l mars/yocto-&DISTRO; master yocto-&DISTRO; 2>&amp;1 | tee build.log
262 </literallayout>
263 The previous example command adds the tag you
264 need for <filename>mars/yocto-&DISTRO;</filename>
265 to <filename>HEAD</filename>, then tells the
266 build script to use the local (-l) Git checkout
267 for the build.
268 After running the script, the file
269 <filename>org.yocto.sdk-</filename><replaceable>release</replaceable><filename>-</filename><replaceable>date</replaceable><filename>-archive.zip</filename>
270 is in the current directory.
271 </para></listitem>
272 <listitem><para>If necessary, start the Eclipse IDE
273 and be sure you are in the Workbench.
274 </para></listitem>
275 <listitem><para>Select "Install New Software" from
276 the "Help" pull-down menu.
277 </para></listitem>
278 <listitem><para>Click "Add".
279 </para></listitem>
280 <listitem><para>Provide anything you want in the
281 "Name" field.
282 </para></listitem>
283 <listitem><para>Click "Archive" and browse to the
284 ZIP file you built earlier.
285 This ZIP file should not be "unzipped", and must
286 be the <filename>*archive.zip</filename> file
287 created by running the
288 <filename>build.sh</filename> script.
289 </para></listitem>
290 <listitem><para>Click the "OK" button.
291 </para></listitem>
292 <listitem><para>Check the boxes that appear in
293 the installation window to install the
294 following:
295
296 <note><title>Developer's Note</title>
297 <para role='writernotes'>
298 Right now, a check box for BitBake Commander
299 is appearing.
300 This probably needs removed.
301 Do not check this box.</para>
302 </note>
303
304 <literallayout class='monospaced'>
305 Yocto Project SDK Plug-in
306 Yocto Project Documentation plug-in
307 </literallayout>
308 </para></listitem>
309 <listitem><para>Finish the installation by clicking
310 through the appropriate buttons.
311 You can click "OK" when prompted about
312 installing software that contains unsigned
313 content.
314 </para></listitem>
315 <listitem><para>Restart the Eclipse IDE if
316 necessary.
317 </para></listitem>
318 </orderedlist>
319 </para>
320
321 <para>
322 At this point you should be able to configure the
323 Eclipse Yocto Plug-in as described in the
324 "<link linkend='mars-configuring-the-eclipse-yocto-plug-in'>Configuring the Mars Eclipse Yocto Plug-in</link>"
325 section.</para>
326 </section>
327 </section>
328
329 <section id='mars-configuring-the-eclipse-yocto-plug-in'>
330 <title>Configuring the Mars Eclipse Yocto Plug-in</title>
331
332 <para>
333 Configuring the Mars Eclipse Yocto Plug-in involves setting the
334 Cross Compiler options and the Target options.
335 The configurations you choose become the default settings
336 for all projects.
337 You do have opportunities to change them later when
338 you configure the project (see the following section).
339 </para>
340
341 <para>
342 To start, you need to do the following from within the
343 Eclipse IDE:
344 <itemizedlist>
345 <listitem><para>Choose "Preferences" from the
346 "Window" menu to display the Preferences Dialog.
347 </para></listitem>
348 <listitem><para>Click "Yocto Project SDK" to display
349 the configuration screen.
350 </para></listitem>
351 </itemizedlist>
352 The following sub-sections describe how to configure the
353 the plug-in.
354 <note>
355 Throughout the descriptions, a start-to-finish example for
356 preparing a QEMU image for use with Eclipse is referenced
357 as the "wiki" and is linked to the example on the
358 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'> Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
359 wiki page.
360 </note>
361 </para>
362
363 <section id='mars-configuring-the-cross-compiler-options'>
364 <title>Configuring the Cross-Compiler Options</title>
365
366 <para>
367 Cross Compiler options enable Eclipse to use your specific
368 cross compiler toolchain.
369 To configure these options, you must select
370 the type of toolchain, point to the toolchain, specify
371 the sysroot location, and select the target
372 architecture.
373 <itemizedlist>
374 <listitem><para><emphasis>Selecting the Toolchain Type:</emphasis>
375 Choose between
376 <filename>Standalone pre-built toolchain</filename>
377 and
378 <filename>Build system derived toolchain</filename>
379 for Cross Compiler Options.
380 <itemizedlist>
381 <listitem><para><emphasis>
382 <filename>Standalone Pre-built Toolchain:</filename></emphasis>
383 Select this type when you are using
384 a stand-alone cross-toolchain.
385 For example, suppose you are an
386 application developer and do not
387 need to build a target image.
388 Instead, you just want to use an
389 architecture-specific toolchain on
390 an existing kernel and target root
391 filesystem.
392 In other words, you have downloaded
393 and installed a pre-built toolchain
394 for an existing image.
395 </para></listitem>
396 <listitem><para><emphasis>
397 <filename>Build System Derived Toolchain:</filename></emphasis>
398 Select this type if you built the
399 toolchain as part of the
400 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
401 When you select
402 <filename>Build system derived toolchain</filename>,
403 you are using the toolchain built and
404 bundled inside the Build Directory.
405 For example, suppose you created a
406 suitable image using the steps in the
407 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
408 In this situation, you would select the
409 <filename>Build system derived toolchain</filename>.
410 </para></listitem>
411 </itemizedlist>
412 </para></listitem>
413 <listitem><para><emphasis>Specify the Toolchain Root Location:</emphasis>
414 If you are using a stand-alone pre-built
415 toolchain, you should be pointing to where it is
416 installed (e.g.
417 <filename>/opt/poky/&DISTRO;</filename>).
418 See the
419 "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
420 section for information about how the SDK is
421 installed.</para>
422 <para>If you are using a build system derived
423 toolchain, the path you provide for the
424 <filename>Toolchain Root Location</filename>
425 field is the
426 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
427 from which you run the
428 <filename>bitbake</filename> command (e.g
429 <filename>/home/scottrif/poky/build</filename>).</para>
430 <para>For more information, see the
431 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
432 section.
433 </para></listitem>
434 <listitem><para><emphasis>Specify Sysroot Location:</emphasis>
435 This location is where the root filesystem for
436 the target hardware resides.
437 </para>
438 <para>This location depends on where you
439 separately extracted and installed the target
440 filesystem.
441 As an example, suppose you prepared an image
442 using the steps in the
443 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
444 If so, the <filename>MY_QEMU_ROOTFS</filename>
445 directory is found in the
446 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
447 and you would browse to and select that directory
448 (e.g. <filename>/home/scottrif/build/MY_QEMU_ROOTFS</filename>).
449 </para>
450 <para>For more information on how to install the
451 toolchain and on how to extract and install the
452 sysroot filesystem, see the
453 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
454 section.
455 </para></listitem>
456 <listitem><para><emphasis>Select the Target Architecture:</emphasis>
457 The target architecture is the type of hardware
458 you are going to use or emulate.
459 Use the pull-down
460 <filename>Target Architecture</filename> menu
461 to make your selection.
462 The pull-down menu should have the supported
463 architectures.
464 If the architecture you need is not listed in
465 the menu, you will need to build the image.
466 See the
467 "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
468 section of the Yocto Project Quick Start for
469 more information.
470 You can also see the
471 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
472 </para></listitem>
473 </itemizedlist>
474 </para>
475 </section>
476
477 <section id='mars-configuring-the-target-options'>
478 <title>Configuring the Target Options</title>
479
480 <para>
481 You can choose to emulate hardware using the QEMU
482 emulator, or you can choose to run your image on actual
483 hardware.
484 <itemizedlist>
485 <listitem><para><emphasis>QEMU:</emphasis>
486 Select this option if you will be using the
487 QEMU emulator.
488 If you are using the emulator, you also need to
489 locate the kernel and specify any custom
490 options.</para>
491 <para>If you selected the
492 <filename>Build system derived toolchain</filename>,
493 the target kernel you built will be located in
494 the
495 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
496 in
497 <filename>tmp/deploy/images/<replaceable>machine</replaceable></filename>
498 directory.
499 As an example, suppose you performed the steps in
500 the
501 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
502 In this case, you specify your Build Directory path
503 followed by the image (e.g.
504 <filename>/home/scottrif/poky/tmp/deploy/images/qemux86/bzImage-qemux86.bin</filename>).
505 </para>
506 <para>If you selected the standalone pre-built
507 toolchain, the pre-built image you downloaded is
508 located in the directory you specified when you
509 downloaded the image.</para>
510 <para>Most custom options are for advanced QEMU
511 users to further customize their QEMU instance.
512 These options are specified between paired
513 angled brackets.
514 Some options must be specified outside the
515 brackets.
516 In particular, the options
517 <filename>serial</filename>,
518 <filename>nographic</filename>, and
519 <filename>kvm</filename> must all be outside the
520 brackets.
521 Use the <filename>man qemu</filename> command
522 to get help on all the options and their use.
523 The following is an example:
524 <literallayout class='monospaced'>
525 serial ‘&lt;-m 256 -full-screen&gt;’
526 </literallayout></para>
527 <para>
528 Regardless of the mode, Sysroot is already
529 defined as part of the Cross-Compiler Options
530 configuration in the
531 <filename>Sysroot Location:</filename> field.
532 </para></listitem>
533 <listitem><para><emphasis>External HW:</emphasis>
534 Select this option if you will be using actual
535 hardware.</para></listitem>
536 </itemizedlist>
537 </para>
538
539 <para>
540 Click the "Apply" and "OK" to save your plug-in
541 configurations.
542 </para>
543 </section>
544 </section>
545 </section>
546
547 <section id='mars-creating-the-project'>
548 <title>Creating the Project</title>
549
550 <para>
551 You can create two types of projects: Autotools-based, or
552 Makefile-based.
553 This section describes how to create Autotools-based projects
554 from within the Eclipse IDE.
555 For information on creating Makefile-based projects in a
556 terminal window, see the
557 "<link linkend='makefile-based-projects'>Makefile-Based Projects</link>"
558 section.
559 <note>
560 Do not use special characters in project names
561 (e.g. spaces, underscores, etc.). Doing so can
562 cause configuration to fail.
563 </note>
564 </para>
565
566 <para>
567 To create a project based on a Yocto template and then display
568 the source code, follow these steps:
569 <orderedlist>
570 <listitem><para>Select "C Project" from the "File -> New" menu.
571 </para></listitem>
572 <listitem><para>Expand <filename>Yocto Project SDK Autotools Project</filename>.
573 </para></listitem>
574 <listitem><para>Select <filename>Hello World ANSI C Autotools Projects</filename>.
575 This is an Autotools-based project based on a Yocto
576 template.
577 </para></listitem>
578 <listitem><para>Put a name in the <filename>Project name:</filename>
579 field.
580 Do not use hyphens as part of the name
581 (e.g. <filename>hello</filename>).
582 </para></listitem>
583 <listitem><para>Click "Next".
584 </para></listitem>
585 <listitem><para>Add appropriate information in the various
586 fields.
587 </para></listitem>
588 <listitem><para>Click "Finish".
589 </para></listitem>
590 <listitem><para>If the "open perspective" prompt appears,
591 click "Yes" so that you in the C/C++ perspective.
592 </para></listitem>
593 <listitem><para>The left-hand navigation pane shows your
594 project.
595 You can display your source by double clicking the
596 project's source file.
597 </para></listitem>
598 </orderedlist>
599 </para>
600 </section>
601
602 <section id='mars-configuring-the-cross-toolchains'>
603 <title>Configuring the Cross-Toolchains</title>
604
605 <para>
606 The earlier section,
607 "<link linkend='mars-configuring-the-eclipse-yocto-plug-in'>Configuring the Mars Eclipse Yocto Plug-in</link>",
608 sets up the default project configurations.
609 You can override these settings for a given project by following
610 these steps:
611 <orderedlist>
612 <listitem><para>Select "Yocto Project Settings" from
613 the "Project -> Properties" menu.
614 This selection brings up the Yocto Project Settings
615 Dialog and allows you to make changes specific to an
616 individual project.</para>
617 <para>By default, the Cross Compiler Options and Target
618 Options for a project are inherited from settings you
619 provided using the Preferences Dialog as described
620 earlier in the
621 "<link linkend='mars-configuring-the-eclipse-yocto-plug-in'>Configuring the Mars Eclipse Yocto Plug-in</link>" section.
622 The Yocto Project Settings Dialog allows you to override
623 those default settings for a given project.
624 </para></listitem>
625 <listitem><para>Make or verify your configurations for the
626 project and click "OK".
627 </para></listitem>
628 <listitem><para>Right-click in the navigation pane and
629 select "Reconfigure Project" from the pop-up menu.
630 This selection reconfigures the project by running
631 <filename>autogen.sh</filename> in the workspace for
632 your project.
633 The script also runs <filename>libtoolize</filename>,
634 <filename>aclocal</filename>,
635 <filename>autoconf</filename>,
636 <filename>autoheader</filename>,
637 <filename>automake --a</filename>, and
638 <filename>./configure</filename>.
639 Click on the "Console" tab beneath your source code to
640 see the results of reconfiguring your project.
641 </para></listitem>
642 </orderedlist>
643 </para>
644 </section>
645
646 <section id='mars-building-the-project'>
647 <title>Building the Project</title>
648
649 <para>
650 To build the project select "Build All" from the
651 "Project" menu.
652 The console should update and you can note the cross-compiler
653 you are using.
654 <note>
655 When building "Yocto Project SDK Autotools" projects, the
656 Eclipse IDE might display error messages for
657 Functions/Symbols/Types that cannot be "resolved", even when
658 the related include file is listed at the project navigator and
659 when the project is able to build.
660 For these cases only, it is recommended to add a new linked
661 folder to the appropriate sysroot.
662 Use these steps to add the linked folder:
663 <orderedlist>
664 <listitem><para>
665 Select the project.
666 </para></listitem>
667 <listitem><para>
668 Select "Folder" from the
669 <filename>File > New</filename> menu.
670 </para></listitem>
671 <listitem><para>
672 In the "New Folder" Dialog, select "Link to alternate
673 location (linked folder)".
674 </para></listitem>
675 <listitem><para>
676 Click "Browse" to navigate to the include folder inside
677 the same sysroot location selected in the Yocto Project
678 configuration preferences.
679 </para></listitem>
680 <listitem><para>
681 Click "OK".
682 </para></listitem>
683 <listitem><para>
684 Click "Finish" to save the linked folder.
685 </para></listitem>
686 </orderedlist>
687 </note>
688 </para>
689 </section>
690
691 <section id='mars-starting-qemu-in-user-space-nfs-mode'>
692 <title>Starting QEMU in User-Space NFS Mode</title>
693
694 <para>
695 To start the QEMU emulator from within Eclipse, follow these
696 steps:
697 <note>
698 See the
699 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
700 chapter in the Yocto Project Development Manual
701 for more information on using QEMU.
702 </note>
703 <orderedlist>
704 <listitem><para>Expose and select "External Tools
705 Configurations ..." from the "Run -> External Tools" menu.
706 </para></listitem>
707 <listitem><para>
708 Locate and select your image in the navigation panel to
709 the left (e.g. <filename>qemu_i586-poky-linux</filename>).
710 </para></listitem>
711 <listitem><para>
712 Click "Run" to launch QEMU.
713 <note>
714 The host on which you are running QEMU must have
715 the <filename>rpcbind</filename> utility running to be
716 able to make RPC calls on a server on that machine.
717 If QEMU does not invoke and you receive error messages
718 involving <filename>rpcbind</filename>, follow the
719 suggestions to get the service running.
720 As an example, on a new Ubuntu 16.04 LTS installation,
721 you must do the following in order to get QEMU to
722 launch:
723 <literallayout class='monospaced'>
724 $ sudo apt-get install rpcbind
725 </literallayout>
726 After installing <filename>rpcbind</filename>, you
727 need to edit the
728 <filename>/etc/init.d/rpcbind</filename> file to
729 include the following line:
730 <literallayout class='monospaced'>
731 OPTIONS="-i -w"
732 </literallayout>
733 After modifying the file, you need to start the
734 service:
735 <literallayout class='monospaced'>
736 $ sudo service portmap restart
737 </literallayout>
738 </note>
739 </para></listitem>
740 <listitem><para>If needed, enter your host root password in
741 the shell window at the prompt.
742 This sets up a <filename>Tap 0</filename> connection
743 needed for running in user-space NFS mode.
744 </para></listitem>
745 <listitem><para>Wait for QEMU to launch.
746 </para></listitem>
747 <listitem><para>Once QEMU launches, you can begin operating
748 within that environment.
749 One useful task at this point would be to determine the
750 IP Address for the user-space NFS by using the
751 <filename>ifconfig</filename> command.
752 The IP address of the QEMU machine appears in the
753 xterm window.
754 You can use this address to help you see which particular
755 IP address the instance of QEMU is using.
756 </para></listitem>
757 </orderedlist>
758 </para>
759 </section>
760
761 <section id='mars-deploying-and-debugging-the-application'>
762 <title>Deploying and Debugging the Application</title>
763
764 <para>
765 Once the QEMU emulator is running the image, you can deploy
766 your application using the Eclipse IDE and then use
767 the emulator to perform debugging.
768 Follow these steps to deploy the application.
769 <note>
770 Currently, Eclipse does not support SSH port forwarding.
771 Consequently, if you need to run or debug a remote
772 application using the host display, you must create a
773 tunneling connection from outside Eclipse and keep
774 that connection alive during your work.
775 For example, in a new terminal, run the following:
776 <literallayout class='monospaced'>
777 $ ssh -XY <replaceable>user_name</replaceable>@<replaceable>remote_host_ip</replaceable>
778 </literallayout>
779 Using the above form, here is an example:
780 <literallayout class='monospaced'>
781 $ ssh -XY root@192.168.7.2
782 </literallayout>
783 After running the command, add the command to be executed
784 in Eclipse's run configuration before the application
785 as follows:
786 <literallayout class='monospaced'>
787 export DISPLAY=:10.0
788 </literallayout>
789 Be sure to not destroy the connection during your QEMU
790 session (i.e. do not
791 exit out of or close that shell).
792 </note>
793 <orderedlist>
794 <listitem><para>Select "Debug Configurations..." from the
795 "Run" menu.</para></listitem>
796 <listitem><para>In the left area, expand
797 <filename>C/C++Remote Application</filename>.
798 </para></listitem>
799 <listitem><para>Locate your project and select it to bring
800 up a new tabbed view in the Debug Configurations Dialog.
801 </para></listitem>
802 <listitem><para>Click on the "Debugger" tab to see the
803 cross-tool debugger you are using.
804 Be sure to change to the debugger perspective in Eclipse.
805 </para></listitem>
806 <listitem><para>Click on the "Main" tab.
807 </para></listitem>
808 <listitem><para>Create a new connection to the QEMU instance
809 by clicking on "new".</para></listitem>
810 <listitem><para>Select <filename>SSH</filename>, which means
811 Secure Socket Shell.
812 Optionally, you can select an TCF connection instead.
813 </para></listitem>
814 <listitem><para>Click "Next".
815 </para></listitem>
816 <listitem><para>Clear out the "host name" field and enter
817 the IP Address determined earlier (e.g. 192.168.7.2).
818 </para></listitem>
819 <listitem><para>Click "Finish" to close the
820 New Connections Dialog.
821 </para></listitem>
822 <listitem><para>If necessary, use the drop-down menu now in the
823 "Connection" field and pick the IP Address you entered.
824 </para></listitem>
825 <listitem><para>Assuming you are connecting as the root user,
826 which is the default for QEMU x86-64 SDK images provided by
827 the Yocto Project, in the "Remote Absolute File Path for
828 C/C++ Application" field, browse to
829 <filename>/home/root</filename>.
830 You could also browse to any other path you have write
831 access to on the target such as
832 <filename>/usr/bin</filename>.
833 This location is where your application will be located on
834 the QEMU system.
835 If you fail to browse to and specify an appropriate
836 location, QEMU will not understand what to remotely
837 launch.
838 Eclipse is helpful in that it auto fills your application
839 name for you assuming you browsed to a directory.
840 <note>
841 If you are prompted to provide a username and to
842 optionally set a password, be sure you provide
843 "root" as the username and you leave the password
844 field blank.
845 </note>
846 </para></listitem>
847 <listitem><para>
848 Be sure you change to the "Debug" perspective in Eclipse.
849 </para></listitem>
850 <listitem><para>Click "Debug"
851 </para></listitem>
852 <listitem><para>Accept the debug perspective.
853 </para></listitem>
854 </orderedlist>
855 </para>
856 </section>
857
858 <section id='mars-using-Linuxtools'>
859 <title>Using Linuxtools</title>
860
861 <para>
862 As mentioned earlier in the manual, performance tools exist
863 (Linuxtools) that enhance your development experience.
864 These tools are aids in developing and debugging applications and
865 images.
866 You can run these tools from within the Eclipse IDE through the
867 "Linuxtools" menu.
868 </para>
869
870 <para>
871 For information on how to configure and use these tools, see
872 <ulink url='http://www.eclipse.org/linuxtools/'>http://www.eclipse.org/linuxtools/</ulink>.
873 </para>
874 </section>
875</appendix>
876<!--
877vim: expandtab tw=80 ts=4
878-->
diff --git a/documentation/sdk-manual/sdk-intro.xml b/documentation/sdk-manual/sdk-intro.xml
index 781cebf188..0995f79a93 100644
--- a/documentation/sdk-manual/sdk-intro.xml
+++ b/documentation/sdk-manual/sdk-intro.xml
@@ -113,8 +113,9 @@
113 of the SDK but is rather available for use as part of the 113 of the SDK but is rather available for use as part of the
114 development process. 114 development process.
115 </para></listitem> 115 </para></listitem>
116 <listitem><para>Various user-space tools that greatly enhance 116 <listitem><para>Various performance-related
117 your application development experience. 117 <ulink url='http://www.eclipse.org/linuxtools/index.php'>tools</ulink>
118 that can enhance your development experience.
118 These tools are also separate from the actual SDK but can be 119 These tools are also separate from the actual SDK but can be
119 independently obtained and used in the development process. 120 independently obtained and used in the development process.
120 </para></listitem> 121 </para></listitem>
@@ -196,9 +197,16 @@
196 These extensions allow for cross-compilation, deployment, and 197 These extensions allow for cross-compilation, deployment, and
197 execution of your output into a QEMU emulation session. 198 execution of your output into a QEMU emulation session.
198 You can also perform cross-debugging and profiling. 199 You can also perform cross-debugging and profiling.
199 The environment also supports a suite of tools that allows you to 200 The environment also supports many performance-related
200 perform remote profiling, tracing, collection of power data, 201 <ulink url='http://www.eclipse.org/linuxtools/index.php'>tools</ulink>
201 collection of latency data, and collection of performance data. 202 that enhance your development experience.
203 <note>
204 Previous releases of the Eclipse Yocto Plug-in supported
205 "user-space tools" (i.e. LatencyTOP, PowerTOP, Perf, SystemTap,
206 and Lttng-ust) that also added to the development experience.
207 These tools have been deprecated beginning with this release
208 of the plug-in.
209 </note>
202 </para> 210 </para>
203 211
204 <para> 212 <para>
@@ -210,54 +218,15 @@
210 </para> 218 </para>
211 </section> 219 </section>
212 220
213 <section id='user-space-tools'> 221 <section id='performance-enhancing-tools'>
214 <title>User-Space Tools</title> 222 <title>Performance Enhancing Tools</title>
215 223
216 <para> 224 <para>
217 User-space tools, which are available as part of the SDK 225 Supported performance enhancing tools are available that let you
218 development environment, can be helpful. 226 profile, debug, and perform tracing on your projects developed
219 The tools include LatencyTOP, PowerTOP, Perf, SystemTap, 227 using Eclipse.
220 and Lttng-ust. 228 For information on these tools see
221 These tools are common development tools for the Linux platform. 229 <ulink url='http://www.eclipse.org/linuxtools/'>http://www.eclipse.org/linuxtools/</ulink>.
222 <itemizedlist>
223 <listitem><para><emphasis>LatencyTOP:</emphasis> LatencyTOP
224 focuses on latency that causes skips in audio, stutters in
225 your desktop experience, or situations that overload your
226 server even when you have plenty of CPU power left.
227 </para></listitem>
228 <listitem><para><emphasis>PowerTOP:</emphasis> Helps you
229 determine what software is using the most power.
230 You can find out more about PowerTOP at
231 <ulink url='https://01.org/powertop/'></ulink>.</para></listitem>
232 <listitem><para><emphasis>Perf:</emphasis> Performance counters
233 for Linux used to keep track of certain types of hardware
234 and software events.
235 For more information on these types of counters see
236 <ulink url='https://perf.wiki.kernel.org/'></ulink>.
237 For examples on how to setup and use this tool, see the
238 "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-perf'>perf</ulink>"
239 section in the Yocto Project Profiling and Tracing Manual.
240 </para></listitem>
241 <listitem><para><emphasis>SystemTap:</emphasis> A free software
242 infrastructure that simplifies information gathering about
243 a running Linux system.
244 This information helps you diagnose performance or
245 functional problems.
246 SystemTap is not available as a user-space tool through
247 the Eclipse IDE Yocto Plug-in.
248 See <ulink url='http://sourceware.org/systemtap'></ulink>
249 for more information on SystemTap.
250 For examples on how to setup and use this tool, see the
251 "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-systemtap'>SystemTap</ulink>"
252 section in the Yocto Project Profiling and Tracing Manual.
253 </para></listitem>
254 <listitem><para><emphasis>Lttng-ust:</emphasis> A User-space
255 Tracer designed to provide detailed information on
256 user-space activity.
257 See <ulink url='http://lttng.org/ust'></ulink> for more
258 information on Lttng-ust.
259 </para></listitem>
260 </itemizedlist>
261 </para> 230 </para>
262 </section> 231 </section>
263</section> 232</section>
diff --git a/documentation/sdk-manual/sdk-manual.xml b/documentation/sdk-manual/sdk-manual.xml
index b690a14012..39a8689195 100644
--- a/documentation/sdk-manual/sdk-manual.xml
+++ b/documentation/sdk-manual/sdk-manual.xml
@@ -74,6 +74,8 @@
74 74
75 <xi:include href="sdk-appendix-customizing.xml"/> 75 <xi:include href="sdk-appendix-customizing.xml"/>
76 76
77 <xi:include href="sdk-appendix-mars.xml"/>
78
77<!-- <index id='index'> 79<!-- <index id='index'>
78 <title>Index</title> 80 <title>Index</title>
79 </index> 81 </index>
diff --git a/documentation/sdk-manual/sdk-using.xml b/documentation/sdk-manual/sdk-using.xml
index 9354ace3b9..f8e2f005bd 100644
--- a/documentation/sdk-manual/sdk-using.xml
+++ b/documentation/sdk-manual/sdk-using.xml
@@ -533,10 +533,10 @@
533 </para></listitem> 533 </para></listitem>
534 <listitem><para><emphasis>Test and debug the application</emphasis>: 534 <listitem><para><emphasis>Test and debug the application</emphasis>:
535 Once your application is deployed, you need to test it. 535 Once your application is deployed, you need to test it.
536 Within the Eclipse IDE, you can use the debugging environment along with the 536 Within the Eclipse IDE, you can use the debugging
537 set of installed user-space tools to debug your application. 537 environment along with supported performance enhancing
538 Of course, the same user-space tools are available separately if you choose 538 <ulink url='http://www.eclipse.org/linuxtools/'>tools</ulink>.
539 not to use the Eclipse IDE.</para></listitem> 539 </para></listitem>
540 </orderedlist> 540 </orderedlist>
541 </para> 541 </para>
542 </section> 542 </section>
@@ -565,9 +565,11 @@
565 execution of your output into a QEMU emulation session as well as 565 execution of your output into a QEMU emulation session as well as
566 actual target hardware. 566 actual target hardware.
567 You can also perform cross-debugging and profiling. 567 You can also perform cross-debugging and profiling.
568 The environment also supports a suite of tools that allows you 568 The environment also supports performance enhancing
569 to perform remote profiling, tracing, collection of power data, 569 <ulink url='http://www.eclipse.org/linuxtools/'>tools</ulink> that
570 collection of latency data, and collection of performance data. 570 allow you to perform remote profiling, tracing, collection of
571 power data, collection of latency data, and collection of
572 performance data.
571 </para> 573 </para>
572 574
573 <para> 575 <para>
@@ -1317,144 +1319,18 @@
1317 </para> 1319 </para>
1318 </section> 1320 </section>
1319 1321
1320 <section id='running-user-space-tools'> 1322 <section id='running-performance-tools'>
1321 <title>Running User-Space Tools</title> 1323 <title>Running Performance Tools</title>
1322 1324
1323 <para> 1325 <para>
1324 As mentioned earlier in the manual, several tools exist that 1326 As mentioned earlier in the manual, several tools exist that
1325 enhance your development experience. 1327 enhance your development experience.
1326 These tools are aids in developing and debugging applications 1328 These tools are aids in developing and debugging applications
1327 and images. 1329 and images.
1328 You can run these user-space tools from within the Eclipse 1330 You can run these tools from within the Eclipse
1329 IDE through the "YoctoProjectTools" menu. 1331 IDE through the "YoctoProjectTools" menu.
1330 </para> 1332 For more information on these tools, see
1331 1333 <ulink url='http://www.eclipse.org/linuxtools/'>http://www.eclipse.org/linuxtools/</ulink>.
1332 <para>
1333 Once you pick a tool, you need to configure it for the remote
1334 target.
1335 Every tool needs to have the connection configured.
1336 You must select an existing TCF-based RSE connection to the
1337 remote target.
1338 If one does not exist, click "New" to create one.
1339 </para>
1340
1341 <para>
1342 Here are some specifics about the remote tools:
1343 <itemizedlist>
1344 <listitem><para><emphasis><filename>Lttng2.0 trace import</filename>:</emphasis>
1345 Selecting this tool transfers the remote target's
1346 <filename>Lttng</filename> tracing data back to the
1347 local host machine and uses the Lttng Eclipse plug-in
1348 to graphically display the output.
1349 For information on how to use Lttng to trace an
1350 application,
1351 see <ulink url='http://lttng.org/documentation'></ulink>
1352 and the
1353 "<ulink url='&YOCTO_DOCS_PROF_URL;#lttng-linux-trace-toolkit-next-generation'>LTTng (Linux Trace Toolkit, next generation)</ulink>"
1354 section, which is in the Yocto Project Profiling and
1355 Tracing Manual.
1356 <note>Do not use
1357 <filename>Lttng-user space (legacy)</filename> tool.
1358 This tool no longer has any upstream support.</note>
1359 </para>
1360 <para>Before you use the
1361 <filename>Lttng2.0 trace import</filename> tool,
1362 you need to setup the Lttng Eclipse plug-in and create a
1363 Tracing project.
1364 Do the following:
1365 <orderedlist>
1366 <listitem><para>Select "Open Perspective" from the
1367 "Window" menu and then select "Other..." to
1368 bring up a menu of other perspectives.
1369 Choose "Tracing".
1370 </para></listitem>
1371 <listitem><para>Click "OK" to change the Eclipse
1372 perspective into the Tracing perspective.
1373 </para></listitem>
1374 <listitem><para>Create a new Tracing project by
1375 selecting "Project" from the "File -> New" menu.
1376 </para></listitem>
1377 <listitem><para>Choose "Tracing Project" from the
1378 "Tracing" menu and click "Next".
1379 </para></listitem>
1380 <listitem><para>Provide a name for your tracing
1381 project and click "Finish".
1382 </para></listitem>
1383 <listitem><para>Generate your tracing data on the
1384 remote target.</para></listitem>
1385 <listitem><para>Select "Lttng2.0 trace import"
1386 from the "Yocto Project Tools" menu to
1387 start the data import process.</para></listitem>
1388 <listitem><para>Specify your remote connection name.
1389 </para></listitem>
1390 <listitem><para>For the Ust directory path, specify
1391 the location of your remote tracing data.
1392 Make sure the location ends with
1393 <filename>ust</filename> (e.g.
1394 <filename>/usr/mysession/ust</filename>).
1395 </para></listitem>
1396 <listitem><para>Click "OK" to complete the import
1397 process.
1398 The data is now in the local tracing project
1399 you created.</para></listitem>
1400 <listitem><para>Right click on the data and then use
1401 the menu to Select "Generic CTF Trace" from the
1402 "Trace Type... -> Common Trace Format" menu to
1403 map the tracing type.</para></listitem>
1404 <listitem><para>Right click the mouse and select
1405 "Open" to bring up the Eclipse Lttng Trace
1406 Viewer so you view the tracing data.
1407 </para></listitem>
1408 </orderedlist></para></listitem>
1409 <listitem><para><emphasis><filename>PowerTOP</filename>:</emphasis>
1410 Selecting this tool runs PowerTOP on the remote target
1411 machine and displays the results in a new view called
1412 PowerTOP.</para>
1413 <para>The "Time to gather data(sec):" field is the time
1414 passed in seconds before data is gathered from the
1415 remote target for analysis.</para>
1416 <para>The "show pids in wakeups list:" field corresponds
1417 to the <filename>-p</filename> argument passed to
1418 <filename>PowerTOP</filename>.</para></listitem>
1419 <listitem><para><emphasis><filename>LatencyTOP and Perf</filename>:</emphasis>
1420 LatencyTOP identifies system latency, while
1421 Perf monitors the system's performance counter
1422 registers.
1423 Selecting either of these tools causes an RSE terminal
1424 view to appear from which you can run the tools.
1425 Both tools refresh the entire screen to display results
1426 while they run.
1427 For more information on setting up and using
1428 <filename>perf</filename>, see the
1429 "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-perf'>perf</ulink>"
1430 section in the Yocto Project Profiling and Tracing
1431 Manual.
1432 </para></listitem>
1433 <listitem><para><emphasis><filename>SystemTap</filename>:</emphasis>
1434 Systemtap is a tool that lets you create and reuse
1435 scripts to examine the activities of a live Linux
1436 system.
1437 You can easily extract, filter, and summarize data
1438 that helps you diagnose complex performance or
1439 functional problems.
1440 For more information on setting up and using
1441 <filename>SystemTap</filename>, see the
1442 <ulink url='https://sourceware.org/systemtap/documentation.html'>SystemTap Documentation</ulink>.
1443 </para></listitem>
1444 <listitem><para><emphasis><filename>yocto-bsp</filename>:</emphasis>
1445 The <filename>yocto-bsp</filename> tool lets you
1446 quickly set up a Board Support Package (BSP) layer.
1447 The tool requires a Metadata location, build location,
1448 BSP name, BSP output location, and a kernel
1449 architecture.
1450 For more information on the
1451 <filename>yocto-bsp</filename> tool outside of Eclipse,
1452 see the
1453 "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a new BSP Layer Using the yocto-bsp Script</ulink>"
1454 section in the Yocto Project Board Support Package
1455 (BSP) Developer's Guide.
1456 </para></listitem>
1457 </itemizedlist>
1458 </para> 1334 </para>
1459 </section> 1335 </section>
1460 </section> 1336 </section>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-19 12:20:30 +0000