summaryrefslogtreecommitdiffstats
path: root/documentation/sdk-manual/sdk-appendix-mars.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/sdk-manual/sdk-appendix-mars.xml')
-rw-r--r--documentation/sdk-manual/sdk-appendix-mars.xml878
1 files changed, 878 insertions, 0 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-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-24 20:08:21 +0000