summaryrefslogtreecommitdiffstats
path: root/documentation/sdk-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/sdk-manual')
-rw-r--r--documentation/sdk-manual/sdk-appendix-mars.xml916
-rw-r--r--documentation/sdk-manual/sdk-manual.xml2
2 files changed, 1 insertions, 917 deletions
diff --git a/documentation/sdk-manual/sdk-appendix-mars.xml b/documentation/sdk-manual/sdk-appendix-mars.xml
deleted file mode 100644
index 84167a8ce0..0000000000
--- a/documentation/sdk-manual/sdk-appendix-mars.xml
+++ /dev/null
@@ -1,916 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<appendix id='sdk-appendix-latest-yp-eclipse-plug-in'>
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-eclipse-project'>Developing Applications Using <trademark class='trade'>Eclipse</trademark></link>"
18 Chapter.
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 <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>
93 </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-yocto
227 </literallayout>
228 </para></listitem>
229 <listitem><para>Use Git to checkout the correct
230 tag:
231 <literallayout class='monospaced'>
232 $ cd ~/eclipse-yocto
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-yocto/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_REF_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_REF_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
435 target filesystem when you either built
436 it or downloaded it.
437 <note>
438 If you downloaded the root filesystem
439 for the target hardware rather than
440 built it, you must download the
441 <filename>sato-sdk</filename> image
442 in order to build any c/c++ projects.
443 </note>
444 As an example, suppose you prepared an image
445 using the steps in the
446 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
447 If so, the <filename>MY_QEMU_ROOTFS</filename>
448 directory is found in the
449 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
450 and you would browse to and select that directory
451 (e.g. <filename>/home/scottrif/build/MY_QEMU_ROOTFS</filename>).
452 </para>
453 <para>For more information on how to install the
454 toolchain and on how to extract and install the
455 sysroot filesystem, see the
456 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
457 section.
458 </para></listitem>
459 <listitem><para><emphasis>Select the Target Architecture:</emphasis>
460 The target architecture is the type of hardware
461 you are going to use or emulate.
462 Use the pull-down
463 <filename>Target Architecture</filename> menu
464 to make your selection.
465 The pull-down menu should have the supported
466 architectures.
467 If the architecture you need is not listed in
468 the menu, you will need to build the image.
469 See the
470 "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
471 section of the Yocto Project Quick Start for
472 more information.
473 You can also see the
474 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
475 </para></listitem>
476 </itemizedlist>
477 </para>
478 </section>
479
480 <section id='mars-configuring-the-target-options'>
481 <title>Configuring the Target Options</title>
482
483 <para>
484 You can choose to emulate hardware using the QEMU
485 emulator, or you can choose to run your image on actual
486 hardware.
487 <itemizedlist>
488 <listitem><para><emphasis>QEMU:</emphasis>
489 Select this option if you will be using the
490 QEMU emulator.
491 If you are using the emulator, you also need to
492 locate the kernel and specify any custom
493 options.</para>
494 <para>If you selected the
495 <filename>Build system derived toolchain</filename>,
496 the target kernel you built will be located in
497 the
498 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
499 in
500 <filename>tmp/deploy/images/<replaceable>machine</replaceable></filename>
501 directory.
502 As an example, suppose you performed the steps in
503 the
504 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
505 In this case, you specify your Build Directory path
506 followed by the image (e.g.
507 <filename>/home/scottrif/poky/build/tmp/deploy/images/qemux86/bzImage-qemux86.bin</filename>).
508 </para>
509 <para>If you selected the standalone pre-built
510 toolchain, the pre-built image you downloaded is
511 located in the directory you specified when you
512 downloaded the image.</para>
513 <para>Most custom options are for advanced QEMU
514 users to further customize their QEMU instance.
515 These options are specified between paired
516 angled brackets.
517 Some options must be specified outside the
518 brackets.
519 In particular, the options
520 <filename>serial</filename>,
521 <filename>nographic</filename>, and
522 <filename>kvm</filename> must all be outside the
523 brackets.
524 Use the <filename>man qemu</filename> command
525 to get help on all the options and their use.
526 The following is an example:
527 <literallayout class='monospaced'>
528 serial ‘&lt;-m 256 -full-screen&gt;’
529 </literallayout></para>
530 <para>
531 Regardless of the mode, Sysroot is already
532 defined as part of the Cross-Compiler Options
533 configuration in the
534 <filename>Sysroot Location:</filename> field.
535 </para></listitem>
536 <listitem><para><emphasis>External HW:</emphasis>
537 Select this option if you will be using actual
538 hardware.</para></listitem>
539 </itemizedlist>
540 </para>
541
542 <para>
543 Click the "Apply" and "OK" to save your plug-in
544 configurations.
545 </para>
546 </section>
547 </section>
548 </section>
549
550 <section id='mars-creating-the-project'>
551 <title>Creating the Project</title>
552
553 <para>
554 You can create two types of projects: Autotools-based, or
555 Makefile-based.
556 This section describes how to create Autotools-based projects
557 from within the Eclipse IDE.
558 For information on creating Makefile-based projects in a
559 terminal window, see the
560 "<link linkend='makefile-based-projects'>Makefile-Based Projects</link>"
561 section.
562 <note>
563 Do not use special characters in project names
564 (e.g. spaces, underscores, etc.). Doing so can
565 cause configuration to fail.
566 </note>
567 </para>
568
569 <para>
570 To create a project based on a Yocto template and then display
571 the source code, follow these steps:
572 <orderedlist>
573 <listitem><para>Select "C Project" from the "File -> New" menu.
574 </para></listitem>
575 <listitem><para>Expand <filename>Yocto Project SDK Autotools Project</filename>.
576 </para></listitem>
577 <listitem><para>Select <filename>Hello World ANSI C Autotools Projects</filename>.
578 This is an Autotools-based project based on a Yocto
579 template.
580 </para></listitem>
581 <listitem><para>Put a name in the <filename>Project name:</filename>
582 field.
583 Do not use hyphens as part of the name
584 (e.g. <filename>hello</filename>).
585 </para></listitem>
586 <listitem><para>Click "Next".
587 </para></listitem>
588 <listitem><para>Add appropriate information in the various
589 fields.
590 </para></listitem>
591 <listitem><para>Click "Finish".
592 </para></listitem>
593 <listitem><para>If the "open perspective" prompt appears,
594 click "Yes" so that you in the C/C++ perspective.
595 </para></listitem>
596 <listitem><para>The left-hand navigation pane shows your
597 project.
598 You can display your source by double clicking the
599 project's source file.
600 </para></listitem>
601 </orderedlist>
602 </para>
603 </section>
604
605 <section id='mars-configuring-the-cross-toolchains'>
606 <title>Configuring the Cross-Toolchains</title>
607
608 <para>
609 The earlier section,
610 "<link linkend='mars-configuring-the-eclipse-yocto-plug-in'>Configuring the Mars Eclipse Yocto Plug-in</link>",
611 sets up the default project configurations.
612 You can override these settings for a given project by following
613 these steps:
614 <orderedlist>
615 <listitem><para>Select "Yocto Project Settings" from
616 the "Project -> Properties" menu.
617 This selection brings up the Yocto Project Settings
618 Dialog and allows you to make changes specific to an
619 individual project.</para>
620 <para>By default, the Cross Compiler Options and Target
621 Options for a project are inherited from settings you
622 provided using the Preferences Dialog as described
623 earlier in the
624 "<link linkend='mars-configuring-the-eclipse-yocto-plug-in'>Configuring the Mars Eclipse Yocto Plug-in</link>" section.
625 The Yocto Project Settings Dialog allows you to override
626 those default settings for a given project.
627 </para></listitem>
628 <listitem><para>Make or verify your configurations for the
629 project and click "OK".
630 </para></listitem>
631 <listitem><para>Right-click in the navigation pane and
632 select "Reconfigure Project" from the pop-up menu.
633 This selection reconfigures the project by running
634 <filename>autogen.sh</filename> in the workspace for
635 your project.
636 The script also runs <filename>libtoolize</filename>,
637 <filename>aclocal</filename>,
638 <filename>autoconf</filename>,
639 <filename>autoheader</filename>,
640 <filename>automake --a</filename>, and
641 <filename>./configure</filename>.
642 Click on the "Console" tab beneath your source code to
643 see the results of reconfiguring your project.
644 </para></listitem>
645 </orderedlist>
646 </para>
647 </section>
648
649 <section id='mars-building-the-project'>
650 <title>Building the Project</title>
651
652 <para>
653 To build the project select "Build All" from the
654 "Project" menu.
655 The console should update and you can note the cross-compiler
656 you are using.
657 <note>
658 When building "Yocto Project SDK Autotools" projects, the
659 Eclipse IDE might display error messages for
660 Functions/Symbols/Types that cannot be "resolved", even when
661 the related include file is listed at the project navigator and
662 when the project is able to build.
663 For these cases only, it is recommended to add a new linked
664 folder to the appropriate sysroot.
665 Use these steps to add the linked folder:
666 <orderedlist>
667 <listitem><para>
668 Select the project.
669 </para></listitem>
670 <listitem><para>
671 Select "Folder" from the
672 <filename>File > New</filename> menu.
673 </para></listitem>
674 <listitem><para>
675 In the "New Folder" Dialog, select "Link to alternate
676 location (linked folder)".
677 </para></listitem>
678 <listitem><para>
679 Click "Browse" to navigate to the include folder inside
680 the same sysroot location selected in the Yocto Project
681 configuration preferences.
682 </para></listitem>
683 <listitem><para>
684 Click "OK".
685 </para></listitem>
686 <listitem><para>
687 Click "Finish" to save the linked folder.
688 </para></listitem>
689 </orderedlist>
690 </note>
691 </para>
692 </section>
693
694 <section id='mars-starting-qemu-in-user-space-nfs-mode'>
695 <title>Starting QEMU in User-Space NFS Mode</title>
696
697 <para>
698 To start the QEMU emulator from within Eclipse, follow these
699 steps:
700 <note>
701 See the
702 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
703 chapter in the Yocto Project Development Tasks Manual
704 for more information on using QEMU.
705 </note>
706 <orderedlist>
707 <listitem><para>Expose and select "External Tools
708 Configurations ..." from the "Run -> External Tools" menu.
709 </para></listitem>
710 <listitem><para>
711 Locate and select your image in the navigation panel to
712 the left (e.g. <filename>qemu_i586-poky-linux</filename>).
713 </para></listitem>
714 <listitem><para>
715 Click "Run" to launch QEMU.
716 <note>
717 The host on which you are running QEMU must have
718 the <filename>rpcbind</filename> utility running to be
719 able to make RPC calls on a server on that machine.
720 If QEMU does not invoke and you receive error messages
721 involving <filename>rpcbind</filename>, follow the
722 suggestions to get the service running.
723 As an example, on a new Ubuntu 16.04 LTS installation,
724 you must do the following in order to get QEMU to
725 launch:
726 <literallayout class='monospaced'>
727 $ sudo apt-get install rpcbind
728 </literallayout>
729 After installing <filename>rpcbind</filename>, you
730 need to edit the
731 <filename>/etc/init.d/rpcbind</filename> file to
732 include the following line:
733 <literallayout class='monospaced'>
734 OPTIONS="-i -w"
735 </literallayout>
736 After modifying the file, you need to start the
737 service:
738 <literallayout class='monospaced'>
739 $ sudo service portmap restart
740 </literallayout>
741 </note>
742 </para></listitem>
743 <listitem><para>If needed, enter your host root password in
744 the shell window at the prompt.
745 This sets up a <filename>Tap 0</filename> connection
746 needed for running in user-space NFS mode.
747 </para></listitem>
748 <listitem><para>Wait for QEMU to launch.
749 </para></listitem>
750 <listitem><para>Once QEMU launches, you can begin operating
751 within that environment.
752 One useful task at this point would be to determine the
753 IP Address for the user-space NFS by using the
754 <filename>ifconfig</filename> command.
755 The IP address of the QEMU machine appears in the
756 xterm window.
757 You can use this address to help you see which particular
758 IP address the instance of QEMU is using.
759 </para></listitem>
760 </orderedlist>
761 </para>
762 </section>
763
764 <section id='mars-deploying-and-debugging-the-application'>
765 <title>Deploying and Debugging the Application</title>
766
767 <para>
768 Once the QEMU emulator is running the image, you can deploy
769 your application using the Eclipse IDE and then use
770 the emulator to perform debugging.
771 Follow these steps to deploy the application.
772 <note>
773 Currently, Eclipse does not support SSH port forwarding.
774 Consequently, if you need to run or debug a remote
775 application using the host display, you must create a
776 tunneling connection from outside Eclipse and keep
777 that connection alive during your work.
778 For example, in a new terminal, run the following:
779 <literallayout class='monospaced'>
780 $ ssh -XY <replaceable>user_name</replaceable>@<replaceable>remote_host_ip</replaceable>
781 </literallayout>
782 Using the above form, here is an example:
783 <literallayout class='monospaced'>
784 $ ssh -XY root@192.168.7.2
785 </literallayout>
786 After running the command, add the command to be executed
787 in Eclipse's run configuration before the application
788 as follows:
789 <literallayout class='monospaced'>
790 export DISPLAY=:10.0
791 </literallayout>
792 Be sure to not destroy the connection during your QEMU
793 session (i.e. do not
794 exit out of or close that shell).
795 </note>
796 <orderedlist>
797 <listitem><para>Select "Debug Configurations..." from the
798 "Run" menu.</para></listitem>
799 <listitem><para>In the left area, expand
800 <filename>C/C++Remote Application</filename>.
801 </para></listitem>
802 <listitem><para>Locate your project and select it to bring
803 up a new tabbed view in the Debug Configurations Dialog.
804 </para></listitem>
805 <listitem><para>Click on the "Debugger" tab to see the
806 cross-tool debugger you are using.
807 Be sure to change to the debugger perspective in Eclipse.
808 </para></listitem>
809 <listitem><para>Click on the "Main" tab.
810 </para></listitem>
811 <listitem><para>Create a new connection to the QEMU instance
812 by clicking on "new".</para></listitem>
813 <listitem><para>Select <filename>SSH</filename>, which means
814 Secure Socket Shell.
815 Optionally, you can select a TCF connection instead.
816 </para></listitem>
817 <listitem><para>Click "Next".
818 </para></listitem>
819 <listitem><para>Clear out the "Connection name" field and
820 enter any name you want for the connection.
821 </para></listitem>
822 <listitem><para>Put the IP address for the connection in
823 the "Host" field.
824 For QEMU, the default is <filename>192.168.7.2</filename>.
825 However, if a previous QEMU session did not exit
826 cleanly, the IP address increments (e.g.
827 <filename>192.168.7.3</filename>).
828 <note>
829 You can find the IP address for the current QEMU
830 session by looking in the xterm that opens when
831 you launch QEMU.
832 </note>
833 </para></listitem>
834 <listitem><para>Enter <filename>root</filename>, which
835 is the default for QEMU, for the "User" field.
836 Be sure to leave the password field empty.
837 </para></listitem>
838 <listitem><para>Click "Finish" to close the
839 New Connections Dialog.
840 </para></listitem>
841 <listitem><para>If necessary, use the drop-down menu now in the
842 "Connection" field and pick the IP Address you entered.
843 </para></listitem>
844 <listitem><para>Assuming you are connecting as the root user,
845 which is the default for QEMU x86-64 SDK images provided by
846 the Yocto Project, in the "Remote Absolute File Path for
847 C/C++ Application" field, browse to
848 <filename>/home/root</filename>.
849 You could also browse to any other path you have write
850 access to on the target such as
851 <filename>/usr/bin</filename>.
852 This location is where your application will be located on
853 the QEMU system.
854 If you fail to browse to and specify an appropriate
855 location, QEMU will not understand what to remotely
856 launch.
857 Eclipse is helpful in that it auto fills your application
858 name for you assuming you browsed to a directory.
859 <note><title>Tips</title>
860 <itemizedlist>
861 <listitem><para>
862 If you are prompted to provide a username
863 and to optionally set a password, be sure
864 you provide "root" as the username and you
865 leave the password field blank.
866 </para></listitem>
867 <listitem><para>
868 If browsing to a directory fails or times
869 out, but you can
870 <filename>ssh</filename> into your QEMU
871 or target from the command line and you
872 have proxies set up, it is likely that
873 Eclipse is sending the SSH traffic to a
874 proxy.
875 In this case, either use TCF , or click on
876 "Configure proxy settings" in the
877 connection dialog and add the target IP
878 address to the "bypass proxy" section.
879 You might also need to change
880 "Active Provider" from Native to Manual.
881 </para></listitem>
882 </itemizedlist>
883 </note>
884 </para></listitem>
885 <listitem><para>
886 Be sure you change to the "Debug" perspective in Eclipse.
887 </para></listitem>
888 <listitem><para>Click "Debug"
889 </para></listitem>
890 <listitem><para>Accept the debug perspective.
891 </para></listitem>
892 </orderedlist>
893 </para>
894 </section>
895
896 <section id='mars-using-Linuxtools'>
897 <title>Using Linuxtools</title>
898
899 <para>
900 As mentioned earlier in the manual, performance tools exist
901 (Linuxtools) that enhance your development experience.
902 These tools are aids in developing and debugging applications and
903 images.
904 You can run these tools from within the Eclipse IDE through the
905 "Linuxtools" menu.
906 </para>
907
908 <para>
909 For information on how to configure and use these tools, see
910 <ulink url='http://www.eclipse.org/linuxtools/'>http://www.eclipse.org/linuxtools/</ulink>.
911 </para>
912 </section>
913</appendix>
914<!--
915vim: expandtab tw=80 ts=4
916-->
diff --git a/documentation/sdk-manual/sdk-manual.xml b/documentation/sdk-manual/sdk-manual.xml
index d33205a846..cf59f5a0f7 100644
--- a/documentation/sdk-manual/sdk-manual.xml
+++ b/documentation/sdk-manual/sdk-manual.xml
@@ -117,7 +117,7 @@
117 117
118 <xi:include href="sdk-appendix-customizing-standard.xml"/> 118 <xi:include href="sdk-appendix-customizing-standard.xml"/>
119 119
120 <xi:include href="sdk-appendix-mars.xml"/> 120 <xi:include href="sdk-appendix-neon.xml"/>
121 121
122<!-- <index id='index'> 122<!-- <index id='index'>
123 <title>Index</title> 123 <title>Index</title>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-02-12 15:51:16 +0000