blob: 9957057e998a32a8155efba29fa5221ca705a521 [file] [log] [blame]
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001<!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
Brad Bishop6e60e8b2018-02-01 10:27:11 -05005<appendix id='sdk-appendix-latest-yp-eclipse-plug-in'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006 <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.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050075 <note>
76 If you experience a NullPointer Exception after
77 launch Eclipse or the debugger from within Eclipse,
78 try adding the following
79 to your <filename>eclipse.ini</filename> file,
80 which is located in the directory in which you
81 unpacked the Eclipse tar file:
82 <literallayout class='monospaced'>
83 --launcher.GTK_version
84 2
85 </literallayout>
86 Alternatively, you can export the
87 <filename>SWT_GTK</filename> variable in your
88 shell as follows:
89 <literallayout class='monospaced'>
90 $ export SWT_GTK3=0
91 </literallayout>
92 </note>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060093 </para></listitem>
94 </orderedlist>
95 </para>
96 </section>
97
98 <section id='mars-configuring-the-mars-eclipse-ide'>
99 <title>Configuring the Mars Eclipse IDE</title>
100
101 <para>
102 Follow these steps to configure the Mars Eclipse IDE.
103 <note>
104 Depending on how you installed Eclipse and what you have
105 already done, some of the options will not appear.
106 If you cannot find an option as directed by the manual,
107 it has already been installed.
108 </note>
109 <orderedlist>
110 <listitem><para>Be sure Eclipse is running and
111 you are in your workbench.
112 </para></listitem>
113 <listitem><para>Select "Install New Software" from
114 the "Help" pull-down menu.
115 </para></listitem>
116 <listitem><para>Select
117 "Mars - http://download.eclipse.org/releases/mars"
118 from the "Work with:" pull-down menu.
119 </para></listitem>
120 <listitem><para>Expand the box next to
121 "Linux Tools" and select "C/C++ Remote
122 (Over TCF/TE) Run/Debug Launcher" and
123 "TM Terminal".
124 </para></listitem>
125 <listitem><para>Expand the box next to "Mobile and
126 Device Development" and select the following
127 boxes:
128 <literallayout class='monospaced'>
129 C/C++ Remote (Over TCF/TE) Run/Debug Launcher
130 Remote System Explorer User Actions
131 TM Terminal
132 TCF Remote System Explorer add-in
133 TCF Target Explorer
134 </literallayout>
135 </para></listitem>
136 <listitem><para>Expand the box next to
137 "Programming Languages" and select the
138 following boxes:
139 <literallayout class='monospaced'>
140 C/C++ Autotools Support
141 C/C++ Development Tools SDK
142 </literallayout>
143 </para></listitem>
144 <listitem><para>
145 Complete the installation by clicking through
146 appropriate "Next" and "Finish" buttons.
147 </para></listitem>
148 </orderedlist>
149 </para>
150 </section>
151
152 <section id='mars-installing-the-eclipse-yocto-plug-in'>
153 <title>Installing or Accessing the Mars Eclipse Yocto Plug-in</title>
154
155 <para>
156 You can install the Eclipse Yocto Plug-in into the Eclipse
157 IDE one of two ways: use the Yocto Project's Eclipse
158 Update site to install the pre-built plug-in or build and
159 install the plug-in from the latest source code.
160 </para>
161
162 <section id='mars-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 Mars Eclipse Yocto Plug-in from the update
167 site, follow these steps:
168 <orderedlist>
169 <listitem><para>Start up the Eclipse IDE.
170 </para></listitem>
171 <listitem><para>In Eclipse, select "Install New
172 Software" from the "Help" menu.
173 </para></listitem>
174 <listitem><para>Click "Add..." in the "Work with:"
175 area.
176 </para></listitem>
177 <listitem><para>Enter
178 <filename>&ECLIPSE_DL_PLUGIN_URL;/mars</filename>
179 in the URL field and provide a meaningful name
180 in the "Name" field.
181 </para></listitem>
182 <listitem><para>Click "OK" to have the entry added
183 to the "Work with:" drop-down list.
184 </para></listitem>
185 <listitem><para>Select the entry for the plug-in
186 from the "Work with:" drop-down list.
187 </para></listitem>
188 <listitem><para>Check the boxes next to the following:
189 <literallayout class='monospaced'>
190 Yocto Project SDK Plug-in
191 Yocto Project Documentation plug-in
192 </literallayout>
193 </para></listitem>
194 <listitem><para>Complete the remaining software
195 installation steps and then restart the Eclipse
196 IDE to finish the installation of the plug-in.
197 <note>
198 You can click "OK" when prompted about
199 installing software that contains unsigned
200 content.
201 </note>
202 </para></listitem>
203 </orderedlist>
204 </para>
205 </section>
206
207 <section id='mars-zip-file-method'>
208 <title>Installing the Plug-in Using the Latest Source Code</title>
209
210 <para>
211 To install the Mars Eclipse Yocto Plug-in from the latest
212 source code, follow these steps:
213 <orderedlist>
214 <listitem><para>Be sure your development system
215 has JDK 1.7+
216 </para></listitem>
217 <listitem><para>install X11-related packages:
218 <literallayout class='monospaced'>
219 $ sudo apt-get install xauth
220 </literallayout>
221 </para></listitem>
222 <listitem><para>In a new terminal shell, create a Git
223 repository with:
224 <literallayout class='monospaced'>
225 $ cd ~
226 $ git clone git://git.yoctoproject.org/eclipse-poky
227 </literallayout>
228 </para></listitem>
229 <listitem><para>Use Git to checkout the correct
230 tag:
231 <literallayout class='monospaced'>
232 $ cd ~/eclipse-poky
233 $ git checkout mars/yocto-&DISTRO;
234 </literallayout>
235 This puts you in a detached HEAD state, which
236 is fine since you are only going to be building
237 and not developing.
238 </para></listitem>
239 <listitem><para>Change to the
240 <filename>scripts</filename>
241 directory within the Git repository:
242 <literallayout class='monospaced'>
243 $ cd scripts
244 </literallayout>
245 </para></listitem>
246 <listitem><para>Set up the local build environment
247 by running the setup script:
248 <literallayout class='monospaced'>
249 $ ./setup.sh
250 </literallayout>
251 When the script finishes execution,
252 it prompts you with instructions on how to run
253 the <filename>build.sh</filename> script, which
254 is also in the <filename>scripts</filename>
255 directory of the Git repository created
256 earlier.
257 </para></listitem>
258 <listitem><para>Run the <filename>build.sh</filename>
259 script as directed.
260 Be sure to provide the tag name, documentation
261 branch, and a release name.</para>
262 <para>
263 Following is an example:
264 <literallayout class='monospaced'>
265 $ ECLIPSE_HOME=/home/scottrif/eclipse-poky/scripts/eclipse ./build.sh -l mars/yocto-&DISTRO; master yocto-&DISTRO; 2>&amp;1 | tee build.log
266 </literallayout>
267 The previous example command adds the tag you
268 need for <filename>mars/yocto-&DISTRO;</filename>
269 to <filename>HEAD</filename>, then tells the
270 build script to use the local (-l) Git checkout
271 for the build.
272 After running the script, the file
273 <filename>org.yocto.sdk-</filename><replaceable>release</replaceable><filename>-</filename><replaceable>date</replaceable><filename>-archive.zip</filename>
274 is in the current directory.
275 </para></listitem>
276 <listitem><para>If necessary, start the Eclipse IDE
277 and be sure you are in the Workbench.
278 </para></listitem>
279 <listitem><para>Select "Install New Software" from
280 the "Help" pull-down menu.
281 </para></listitem>
282 <listitem><para>Click "Add".
283 </para></listitem>
284 <listitem><para>Provide anything you want in the
285 "Name" field.
286 </para></listitem>
287 <listitem><para>Click "Archive" and browse to the
288 ZIP file you built earlier.
289 This ZIP file should not be "unzipped", and must
290 be the <filename>*archive.zip</filename> file
291 created by running the
292 <filename>build.sh</filename> script.
293 </para></listitem>
294 <listitem><para>Click the "OK" button.
295 </para></listitem>
296 <listitem><para>Check the boxes that appear in
297 the installation window to install the
298 following:
299 <literallayout class='monospaced'>
300 Yocto Project SDK Plug-in
301 Yocto Project Documentation plug-in
302 </literallayout>
303 </para></listitem>
304 <listitem><para>Finish the installation by clicking
305 through the appropriate buttons.
306 You can click "OK" when prompted about
307 installing software that contains unsigned
308 content.
309 </para></listitem>
310 <listitem><para>Restart the Eclipse IDE if
311 necessary.
312 </para></listitem>
313 </orderedlist>
314 </para>
315
316 <para>
317 At this point you should be able to configure the
318 Eclipse Yocto Plug-in as described in the
319 "<link linkend='mars-configuring-the-eclipse-yocto-plug-in'>Configuring the Mars Eclipse Yocto Plug-in</link>"
320 section.</para>
321 </section>
322 </section>
323
324 <section id='mars-configuring-the-eclipse-yocto-plug-in'>
325 <title>Configuring the Mars Eclipse Yocto Plug-in</title>
326
327 <para>
328 Configuring the Mars Eclipse Yocto Plug-in involves setting the
329 Cross Compiler options and the Target options.
330 The configurations you choose become the default settings
331 for all projects.
332 You do have opportunities to change them later when
333 you configure the project (see the following section).
334 </para>
335
336 <para>
337 To start, you need to do the following from within the
338 Eclipse IDE:
339 <itemizedlist>
340 <listitem><para>Choose "Preferences" from the
341 "Window" menu to display the Preferences Dialog.
342 </para></listitem>
343 <listitem><para>Click "Yocto Project SDK" to display
344 the configuration screen.
345 </para></listitem>
346 </itemizedlist>
347 The following sub-sections describe how to configure the
348 the plug-in.
349 <note>
350 Throughout the descriptions, a start-to-finish example for
351 preparing a QEMU image for use with Eclipse is referenced
352 as the "wiki" and is linked to the example on the
353 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'> Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
354 wiki page.
355 </note>
356 </para>
357
358 <section id='mars-configuring-the-cross-compiler-options'>
359 <title>Configuring the Cross-Compiler Options</title>
360
361 <para>
362 Cross Compiler options enable Eclipse to use your specific
363 cross compiler toolchain.
364 To configure these options, you must select
365 the type of toolchain, point to the toolchain, specify
366 the sysroot location, and select the target
367 architecture.
368 <itemizedlist>
369 <listitem><para><emphasis>Selecting the Toolchain Type:</emphasis>
370 Choose between
371 <filename>Standalone pre-built toolchain</filename>
372 and
373 <filename>Build system derived toolchain</filename>
374 for Cross Compiler Options.
375 <itemizedlist>
376 <listitem><para><emphasis>
377 <filename>Standalone Pre-built Toolchain:</filename></emphasis>
378 Select this type when you are using
379 a stand-alone cross-toolchain.
380 For example, suppose you are an
381 application developer and do not
382 need to build a target image.
383 Instead, you just want to use an
384 architecture-specific toolchain on
385 an existing kernel and target root
386 filesystem.
387 In other words, you have downloaded
388 and installed a pre-built toolchain
389 for an existing image.
390 </para></listitem>
391 <listitem><para><emphasis>
392 <filename>Build System Derived Toolchain:</filename></emphasis>
393 Select this type if you built the
394 toolchain as part of the
395 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
396 When you select
397 <filename>Build system derived toolchain</filename>,
398 you are using the toolchain built and
399 bundled inside the Build Directory.
400 For example, suppose you created a
401 suitable image using the steps in the
402 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
403 In this situation, you would select the
404 <filename>Build system derived toolchain</filename>.
405 </para></listitem>
406 </itemizedlist>
407 </para></listitem>
408 <listitem><para><emphasis>Specify the Toolchain Root Location:</emphasis>
409 If you are using a stand-alone pre-built
410 toolchain, you should be pointing to where it is
411 installed (e.g.
412 <filename>/opt/poky/&DISTRO;</filename>).
413 See the
414 "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
415 section for information about how the SDK is
416 installed.</para>
417 <para>If you are using a build system derived
418 toolchain, the path you provide for the
419 <filename>Toolchain Root Location</filename>
420 field is the
421 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
422 from which you run the
423 <filename>bitbake</filename> command (e.g
424 <filename>/home/scottrif/poky/build</filename>).</para>
425 <para>For more information, see the
426 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
427 section.
428 </para></listitem>
429 <listitem><para><emphasis>Specify Sysroot Location:</emphasis>
430 This location is where the root filesystem for
431 the target hardware resides.
432 </para>
433 <para>This location depends on where you
434 separately extracted and installed the target
435 filesystem.
436 As an example, suppose you prepared an image
437 using the steps in the
438 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
439 If so, the <filename>MY_QEMU_ROOTFS</filename>
440 directory is found in the
441 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
442 and you would browse to and select that directory
443 (e.g. <filename>/home/scottrif/build/MY_QEMU_ROOTFS</filename>).
444 </para>
445 <para>For more information on how to install the
446 toolchain and on how to extract and install the
447 sysroot filesystem, see the
448 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
449 section.
450 </para></listitem>
451 <listitem><para><emphasis>Select the Target Architecture:</emphasis>
452 The target architecture is the type of hardware
453 you are going to use or emulate.
454 Use the pull-down
455 <filename>Target Architecture</filename> menu
456 to make your selection.
457 The pull-down menu should have the supported
458 architectures.
459 If the architecture you need is not listed in
460 the menu, you will need to build the image.
461 See the
462 "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
463 section of the Yocto Project Quick Start for
464 more information.
465 You can also see the
466 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
467 </para></listitem>
468 </itemizedlist>
469 </para>
470 </section>
471
472 <section id='mars-configuring-the-target-options'>
473 <title>Configuring the Target Options</title>
474
475 <para>
476 You can choose to emulate hardware using the QEMU
477 emulator, or you can choose to run your image on actual
478 hardware.
479 <itemizedlist>
480 <listitem><para><emphasis>QEMU:</emphasis>
481 Select this option if you will be using the
482 QEMU emulator.
483 If you are using the emulator, you also need to
484 locate the kernel and specify any custom
485 options.</para>
486 <para>If you selected the
487 <filename>Build system derived toolchain</filename>,
488 the target kernel you built will be located in
489 the
490 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
491 in
492 <filename>tmp/deploy/images/<replaceable>machine</replaceable></filename>
493 directory.
494 As an example, suppose you performed the steps in
495 the
496 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
497 In this case, you specify your Build Directory path
498 followed by the image (e.g.
499 <filename>/home/scottrif/poky/build/tmp/deploy/images/qemux86/bzImage-qemux86.bin</filename>).
500 </para>
501 <para>If you selected the standalone pre-built
502 toolchain, the pre-built image you downloaded is
503 located in the directory you specified when you
504 downloaded the image.</para>
505 <para>Most custom options are for advanced QEMU
506 users to further customize their QEMU instance.
507 These options are specified between paired
508 angled brackets.
509 Some options must be specified outside the
510 brackets.
511 In particular, the options
512 <filename>serial</filename>,
513 <filename>nographic</filename>, and
514 <filename>kvm</filename> must all be outside the
515 brackets.
516 Use the <filename>man qemu</filename> command
517 to get help on all the options and their use.
518 The following is an example:
519 <literallayout class='monospaced'>
520 serial ‘&lt;-m 256 -full-screen&gt;’
521 </literallayout></para>
522 <para>
523 Regardless of the mode, Sysroot is already
524 defined as part of the Cross-Compiler Options
525 configuration in the
526 <filename>Sysroot Location:</filename> field.
527 </para></listitem>
528 <listitem><para><emphasis>External HW:</emphasis>
529 Select this option if you will be using actual
530 hardware.</para></listitem>
531 </itemizedlist>
532 </para>
533
534 <para>
535 Click the "Apply" and "OK" to save your plug-in
536 configurations.
537 </para>
538 </section>
539 </section>
540 </section>
541
542 <section id='mars-creating-the-project'>
543 <title>Creating the Project</title>
544
545 <para>
546 You can create two types of projects: Autotools-based, or
547 Makefile-based.
548 This section describes how to create Autotools-based projects
549 from within the Eclipse IDE.
550 For information on creating Makefile-based projects in a
551 terminal window, see the
552 "<link linkend='makefile-based-projects'>Makefile-Based Projects</link>"
553 section.
554 <note>
555 Do not use special characters in project names
556 (e.g. spaces, underscores, etc.). Doing so can
557 cause configuration to fail.
558 </note>
559 </para>
560
561 <para>
562 To create a project based on a Yocto template and then display
563 the source code, follow these steps:
564 <orderedlist>
565 <listitem><para>Select "C Project" from the "File -> New" menu.
566 </para></listitem>
567 <listitem><para>Expand <filename>Yocto Project SDK Autotools Project</filename>.
568 </para></listitem>
569 <listitem><para>Select <filename>Hello World ANSI C Autotools Projects</filename>.
570 This is an Autotools-based project based on a Yocto
571 template.
572 </para></listitem>
573 <listitem><para>Put a name in the <filename>Project name:</filename>
574 field.
575 Do not use hyphens as part of the name
576 (e.g. <filename>hello</filename>).
577 </para></listitem>
578 <listitem><para>Click "Next".
579 </para></listitem>
580 <listitem><para>Add appropriate information in the various
581 fields.
582 </para></listitem>
583 <listitem><para>Click "Finish".
584 </para></listitem>
585 <listitem><para>If the "open perspective" prompt appears,
586 click "Yes" so that you in the C/C++ perspective.
587 </para></listitem>
588 <listitem><para>The left-hand navigation pane shows your
589 project.
590 You can display your source by double clicking the
591 project's source file.
592 </para></listitem>
593 </orderedlist>
594 </para>
595 </section>
596
597 <section id='mars-configuring-the-cross-toolchains'>
598 <title>Configuring the Cross-Toolchains</title>
599
600 <para>
601 The earlier section,
602 "<link linkend='mars-configuring-the-eclipse-yocto-plug-in'>Configuring the Mars Eclipse Yocto Plug-in</link>",
603 sets up the default project configurations.
604 You can override these settings for a given project by following
605 these steps:
606 <orderedlist>
607 <listitem><para>Select "Yocto Project Settings" from
608 the "Project -> Properties" menu.
609 This selection brings up the Yocto Project Settings
610 Dialog and allows you to make changes specific to an
611 individual project.</para>
612 <para>By default, the Cross Compiler Options and Target
613 Options for a project are inherited from settings you
614 provided using the Preferences Dialog as described
615 earlier in the
616 "<link linkend='mars-configuring-the-eclipse-yocto-plug-in'>Configuring the Mars Eclipse Yocto Plug-in</link>" section.
617 The Yocto Project Settings Dialog allows you to override
618 those default settings for a given project.
619 </para></listitem>
620 <listitem><para>Make or verify your configurations for the
621 project and click "OK".
622 </para></listitem>
623 <listitem><para>Right-click in the navigation pane and
624 select "Reconfigure Project" from the pop-up menu.
625 This selection reconfigures the project by running
626 <filename>autogen.sh</filename> in the workspace for
627 your project.
628 The script also runs <filename>libtoolize</filename>,
629 <filename>aclocal</filename>,
630 <filename>autoconf</filename>,
631 <filename>autoheader</filename>,
632 <filename>automake --a</filename>, and
633 <filename>./configure</filename>.
634 Click on the "Console" tab beneath your source code to
635 see the results of reconfiguring your project.
636 </para></listitem>
637 </orderedlist>
638 </para>
639 </section>
640
641 <section id='mars-building-the-project'>
642 <title>Building the Project</title>
643
644 <para>
645 To build the project select "Build All" from the
646 "Project" menu.
647 The console should update and you can note the cross-compiler
648 you are using.
649 <note>
650 When building "Yocto Project SDK Autotools" projects, the
651 Eclipse IDE might display error messages for
652 Functions/Symbols/Types that cannot be "resolved", even when
653 the related include file is listed at the project navigator and
654 when the project is able to build.
655 For these cases only, it is recommended to add a new linked
656 folder to the appropriate sysroot.
657 Use these steps to add the linked folder:
658 <orderedlist>
659 <listitem><para>
660 Select the project.
661 </para></listitem>
662 <listitem><para>
663 Select "Folder" from the
664 <filename>File > New</filename> menu.
665 </para></listitem>
666 <listitem><para>
667 In the "New Folder" Dialog, select "Link to alternate
668 location (linked folder)".
669 </para></listitem>
670 <listitem><para>
671 Click "Browse" to navigate to the include folder inside
672 the same sysroot location selected in the Yocto Project
673 configuration preferences.
674 </para></listitem>
675 <listitem><para>
676 Click "OK".
677 </para></listitem>
678 <listitem><para>
679 Click "Finish" to save the linked folder.
680 </para></listitem>
681 </orderedlist>
682 </note>
683 </para>
684 </section>
685
686 <section id='mars-starting-qemu-in-user-space-nfs-mode'>
687 <title>Starting QEMU in User-Space NFS Mode</title>
688
689 <para>
690 To start the QEMU emulator from within Eclipse, follow these
691 steps:
692 <note>
693 See the
694 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
695 chapter in the Yocto Project Development Manual
696 for more information on using QEMU.
697 </note>
698 <orderedlist>
699 <listitem><para>Expose and select "External Tools
700 Configurations ..." from the "Run -> External Tools" menu.
701 </para></listitem>
702 <listitem><para>
703 Locate and select your image in the navigation panel to
704 the left (e.g. <filename>qemu_i586-poky-linux</filename>).
705 </para></listitem>
706 <listitem><para>
707 Click "Run" to launch QEMU.
708 <note>
709 The host on which you are running QEMU must have
710 the <filename>rpcbind</filename> utility running to be
711 able to make RPC calls on a server on that machine.
712 If QEMU does not invoke and you receive error messages
713 involving <filename>rpcbind</filename>, follow the
714 suggestions to get the service running.
715 As an example, on a new Ubuntu 16.04 LTS installation,
716 you must do the following in order to get QEMU to
717 launch:
718 <literallayout class='monospaced'>
719 $ sudo apt-get install rpcbind
720 </literallayout>
721 After installing <filename>rpcbind</filename>, you
722 need to edit the
723 <filename>/etc/init.d/rpcbind</filename> file to
724 include the following line:
725 <literallayout class='monospaced'>
726 OPTIONS="-i -w"
727 </literallayout>
728 After modifying the file, you need to start the
729 service:
730 <literallayout class='monospaced'>
731 $ sudo service portmap restart
732 </literallayout>
733 </note>
734 </para></listitem>
735 <listitem><para>If needed, enter your host root password in
736 the shell window at the prompt.
737 This sets up a <filename>Tap 0</filename> connection
738 needed for running in user-space NFS mode.
739 </para></listitem>
740 <listitem><para>Wait for QEMU to launch.
741 </para></listitem>
742 <listitem><para>Once QEMU launches, you can begin operating
743 within that environment.
744 One useful task at this point would be to determine the
745 IP Address for the user-space NFS by using the
746 <filename>ifconfig</filename> command.
747 The IP address of the QEMU machine appears in the
748 xterm window.
749 You can use this address to help you see which particular
750 IP address the instance of QEMU is using.
751 </para></listitem>
752 </orderedlist>
753 </para>
754 </section>
755
756 <section id='mars-deploying-and-debugging-the-application'>
757 <title>Deploying and Debugging the Application</title>
758
759 <para>
760 Once the QEMU emulator is running the image, you can deploy
761 your application using the Eclipse IDE and then use
762 the emulator to perform debugging.
763 Follow these steps to deploy the application.
764 <note>
765 Currently, Eclipse does not support SSH port forwarding.
766 Consequently, if you need to run or debug a remote
767 application using the host display, you must create a
768 tunneling connection from outside Eclipse and keep
769 that connection alive during your work.
770 For example, in a new terminal, run the following:
771 <literallayout class='monospaced'>
772 $ ssh -XY <replaceable>user_name</replaceable>@<replaceable>remote_host_ip</replaceable>
773 </literallayout>
774 Using the above form, here is an example:
775 <literallayout class='monospaced'>
776 $ ssh -XY root@192.168.7.2
777 </literallayout>
778 After running the command, add the command to be executed
779 in Eclipse's run configuration before the application
780 as follows:
781 <literallayout class='monospaced'>
782 export DISPLAY=:10.0
783 </literallayout>
784 Be sure to not destroy the connection during your QEMU
785 session (i.e. do not
786 exit out of or close that shell).
787 </note>
788 <orderedlist>
789 <listitem><para>Select "Debug Configurations..." from the
790 "Run" menu.</para></listitem>
791 <listitem><para>In the left area, expand
792 <filename>C/C++Remote Application</filename>.
793 </para></listitem>
794 <listitem><para>Locate your project and select it to bring
795 up a new tabbed view in the Debug Configurations Dialog.
796 </para></listitem>
797 <listitem><para>Click on the "Debugger" tab to see the
798 cross-tool debugger you are using.
799 Be sure to change to the debugger perspective in Eclipse.
800 </para></listitem>
801 <listitem><para>Click on the "Main" tab.
802 </para></listitem>
803 <listitem><para>Create a new connection to the QEMU instance
804 by clicking on "new".</para></listitem>
805 <listitem><para>Select <filename>SSH</filename>, which means
806 Secure Socket Shell.
807 Optionally, you can select an TCF connection instead.
808 </para></listitem>
809 <listitem><para>Click "Next".
810 </para></listitem>
811 <listitem><para>Clear out the "Connection name" field and
812 enter any name you want for the connection.
813 </para></listitem>
814 <listitem><para>Put the IP address for the connection in
815 the "Host" field.
816 For QEMU, the default is <filename>192.168.7.2</filename>.
817 However, if a previous QEMU session did not exit
818 cleanly, the IP address increments (e.g.
819 <filename>192.168.7.3</filename>).
820 <note>
821 You can find the IP address for the current QEMU
822 session by looking in the xterm that opens when
823 you launch QEMU.
824 </note>
825 </para></listitem>
826 <listitem><para>Enter <filename>root</filename>, which
827 is the default for QEMU, for the "User" field.
828 Be sure to leave the password field empty.
829 </para></listitem>
830 <listitem><para>Click "Finish" to close the
831 New Connections Dialog.
832 </para></listitem>
833 <listitem><para>If necessary, use the drop-down menu now in the
834 "Connection" field and pick the IP Address you entered.
835 </para></listitem>
836 <listitem><para>Assuming you are connecting as the root user,
837 which is the default for QEMU x86-64 SDK images provided by
838 the Yocto Project, in the "Remote Absolute File Path for
839 C/C++ Application" field, browse to
840 <filename>/home/root</filename>.
841 You could also browse to any other path you have write
842 access to on the target such as
843 <filename>/usr/bin</filename>.
844 This location is where your application will be located on
845 the QEMU system.
846 If you fail to browse to and specify an appropriate
847 location, QEMU will not understand what to remotely
848 launch.
849 Eclipse is helpful in that it auto fills your application
850 name for you assuming you browsed to a directory.
851 <note>
852 If you are prompted to provide a username and to
853 optionally set a password, be sure you provide
854 "root" as the username and you leave the password
855 field blank.
856 </note>
857 </para></listitem>
858 <listitem><para>
859 Be sure you change to the "Debug" perspective in Eclipse.
860 </para></listitem>
861 <listitem><para>Click "Debug"
862 </para></listitem>
863 <listitem><para>Accept the debug perspective.
864 </para></listitem>
865 </orderedlist>
866 </para>
867 </section>
868
869 <section id='mars-using-Linuxtools'>
870 <title>Using Linuxtools</title>
871
872 <para>
873 As mentioned earlier in the manual, performance tools exist
874 (Linuxtools) that enhance your development experience.
875 These tools are aids in developing and debugging applications and
876 images.
877 You can run these tools from within the Eclipse IDE through the
878 "Linuxtools" menu.
879 </para>
880
881 <para>
882 For information on how to configure and use these tools, see
883 <ulink url='http://www.eclipse.org/linuxtools/'>http://www.eclipse.org/linuxtools/</ulink>.
884 </para>
885 </section>
886</appendix>
887<!--
888vim: expandtab tw=80 ts=4
889-->