summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2019-04-12 14:19:54 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2019-06-18 11:30:37 +0100
commit05818e63ed1a817953a07495e67d03acc5412d62 (patch)
tree12330afbaf81b05fb5a9f36e65e3c5f3a4edb39a /documentation
parent714a44f98c9cf2d718197237afd46fe14c627a49 (diff)
downloadpoky-05818e63ed1a817953a07495e67d03acc5412d62.tar.gz
sdk-manual: Removed all references to Eclipse
One Neon appendix completely removed. One other chapter removed that held the latest version of Eclipse use removed. A figure was also removed. (From yocto-docs rev: 03524fc363f9232a2ed45d10688ddeb0439b0917) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/sdk-manual/figures/sdk-eclipse-dev-flow.pngbin62626 -> 0 bytes
-rw-r--r--documentation/sdk-manual/sdk-appendix-neon.xml956
-rw-r--r--documentation/sdk-manual/sdk-eclipse-project.xml1248
3 files changed, 0 insertions, 2204 deletions
diff --git a/documentation/sdk-manual/figures/sdk-eclipse-dev-flow.png b/documentation/sdk-manual/figures/sdk-eclipse-dev-flow.png
deleted file mode 100644
index 9f986e0d41..0000000000
--- a/documentation/sdk-manual/figures/sdk-eclipse-dev-flow.png
+++ /dev/null
Binary files differ
diff --git a/documentation/sdk-manual/sdk-appendix-neon.xml b/documentation/sdk-manual/sdk-appendix-neon.xml
deleted file mode 100644
index 0fb92985a4..0000000000
--- a/documentation/sdk-manual/sdk-appendix-neon.xml
+++ /dev/null
@@ -1,956 +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-neon-yp-eclipse-plug-in'>
6 <title>Using <trademark class='trade'>Eclipse</trademark> Neon</title>
7
8 <para>
9 This release of the Yocto Project supports both the Oxygen and Neon
10 versions of the Eclipse IDE.
11 This appendix presents information that describes how to obtain and
12 configure the Neon 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='application-development-workflow-using-eclipse'>Application Development Workflow Using <trademark class='trade'>Eclipse</trademark></link>"
18 section.
19 </para>
20
21 <section id='neon-setting-up-the-eclipse-ide'>
22 <title>Setting Up the Neon 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 Neon 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='neon-installing-eclipse-ide'>
45 <title>Installing the Neon Eclipse IDE</title>
46
47 <para>
48 Follow these steps to locate, install, and configure
49 Neon Eclipse:
50 <orderedlist>
51 <listitem><para><emphasis>Locate the Neon Download:</emphasis>
52 Open a browser and go to
53 <ulink url='http://www.eclipse.org/neon/'>http://www.eclipse.org/neon/</ulink>.
54 </para></listitem>
55 <listitem><para><emphasis>Download the Tarball:</emphasis>
56 Click the "Download" button and look for the
57 "Eclipse IDE for C/C++ Developers" Neon 3 Package.
58 Select the correct platform download link listed at
59 the right.
60 For example, click on "64-bit" next to Linux if your
61 build host is running a 64-bit Linux distribution.
62 Click through the process to save the file.
63 </para></listitem>
64 <listitem><para><emphasis>Unpack the Tarball:</emphasis>
65 Move to a directory and unpack the tarball.
66 The following commands unpack the tarball into the
67 home directory:
68 <literallayout class='monospaced'>
69 $ cd ~
70 $ tar -xzvf ~/Downloads/eclipse-cpp-neon-3-linux-gtk-x86_64.tar.gz
71 </literallayout>
72 Everything unpacks into a folder named "Eclipse".
73 </para></listitem>
74 <listitem><para><emphasis>Launch Eclipse:</emphasis>
75 The following commands launch Eclipse assuming you
76 unpacked it in your home directory:
77 <literallayout class='monospaced'>
78 $ cd ~/eclipse
79 $ ./eclipse
80 </literallayout>
81 Accept the default "workspace" once Eclipse launches.
82 </para></listitem>
83 </orderedlist>
84 </para>
85 </section>
86
87 <section id='neon-configuring-the-neon-eclipse-ide'>
88 <title>Configuring the Neon Eclipse IDE</title>
89
90 <para>
91 Follow these steps to configure the Neon Eclipse IDE.
92 <note><title>Notes</title>
93 <itemizedlist>
94 <listitem><para>
95 Depending on how you installed Eclipse and what
96 you have already done, some of the options do
97 not appear.
98 If you cannot find an option as directed by the
99 manual, it has already been installed.
100 </para></listitem>
101 <listitem><para>
102 If you want to see all options regardless of
103 whether they are installed or not, deselect the
104 "Hide items that are already installed"
105 check box.
106 </para></listitem>
107 </itemizedlist>
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 "Neon - http://download.eclipse.org/releases/neon"
118 from the "Work with:" pull-down menu.
119 </para></listitem>
120 <listitem><para>Expand the box next to
121 "Linux Tools" and select the following
122 <literallayout class='monospaced'>
123 C/C++ Remote (Over TCF/TE) Run/Debug Launcher
124 TM Terminal
125 </literallayout>
126 </para></listitem>
127 <listitem><para>Expand the box next to "Mobile and
128 Device Development" and select the following
129 boxes:
130 <literallayout class='monospaced'>
131 C/C++ Remote (Over TCF/TE) Run/Debug Launcher
132 Remote System Explorer User Actions
133 TM Terminal
134 TCF Remote System Explorer add-in
135 TCF Target Explorer
136 </literallayout>
137 </para></listitem>
138 <listitem><para>Expand the box next to
139 "Programming Languages" and select the
140 following box:
141 <literallayout class='monospaced'>
142 C/C++ Development Tools SDK
143 </literallayout>
144 </para></listitem>
145 <listitem><para>
146 Complete the installation by clicking through
147 appropriate "Next" and "Finish" buttons.
148 </para></listitem>
149 </orderedlist>
150 </para>
151 </section>
152
153 <section id='neon-installing-the-eclipse-yocto-plug-in'>
154 <title>Installing or Accessing the Neon Eclipse Yocto Plug-in</title>
155
156 <para>
157 You can install the Eclipse Yocto Plug-in into the Eclipse
158 IDE one of two ways: use the Yocto Project's Eclipse
159 Update site to install the pre-built plug-in or build and
160 install the plug-in from the latest source code.
161 </para>
162
163 <section id='neon-new-software'>
164 <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title>
165
166 <para>
167 To install the Neon Eclipse Yocto Plug-in from the update
168 site, follow these steps:
169 <orderedlist>
170 <listitem><para>Start up the Eclipse IDE.
171 </para></listitem>
172 <listitem><para>In Eclipse, select "Install New
173 Software" from the "Help" menu.
174 </para></listitem>
175 <listitem><para>Click "Add..." in the "Work with:"
176 area.
177 </para></listitem>
178 <listitem><para>Enter
179 <filename>&ECLIPSE_DL_PLUGIN_URL;/neon</filename>
180 in the URL field and provide a meaningful name
181 in the "Name" field.
182 </para></listitem>
183 <listitem><para>
184 Click "OK" to have the entry automatically
185 populate the "Work with:" field and to have
186 the items for installation appear in the window
187 below.
188 </para></listitem>
189 <listitem><para>Check the boxes next to the following:
190 <literallayout class='monospaced'>
191 Yocto Project SDK Plug-in
192 Yocto Project Documentation plug-in
193 </literallayout>
194 </para></listitem>
195 <listitem><para>Complete the remaining software
196 installation steps and then restart the Eclipse
197 IDE to finish the installation of the plug-in.
198 <note>
199 You can click "OK" when prompted about
200 installing software that contains unsigned
201 content.
202 </note>
203 </para></listitem>
204 </orderedlist>
205 </para>
206 </section>
207
208 <section id='neon-zip-file-method'>
209 <title>Installing the Plug-in Using the Latest Source Code</title>
210
211 <para>
212 To install the Neon Eclipse Yocto Plug-in from the latest
213 source code, follow these steps:
214 <orderedlist>
215 <listitem><para>
216 Be sure your build host has JDK version 1.8
217 or greater.
218 On a Linux build host you can determine the
219 version using the following command:
220 <literallayout class='monospaced'>
221 $ java -version
222 </literallayout>
223 </para></listitem>
224 <listitem><para>install X11-related packages:
225 <literallayout class='monospaced'>
226 $ sudo apt-get install xauth
227 </literallayout>
228 </para></listitem>
229 <listitem><para>In a new terminal shell, create a Git
230 repository with:
231 <literallayout class='monospaced'>
232 $ cd ~
233 $ git clone git://git.yoctoproject.org/eclipse-yocto
234 </literallayout>
235 </para></listitem>
236 <listitem><para>
237 Use Git to create the correct tag:
238 <literallayout class='monospaced'>
239 $ cd ~/eclipse-yocto
240 $ git checkout -b neon/&DISTRO_NAME_NO_CAP; remotes/origin/neon/&DISTRO_NAME_NO_CAP;
241 </literallayout>
242 This creates a local tag named
243 <filename>neon/&DISTRO_NAME_NO_CAP;</filename>
244 based on the branch
245 <filename>origin/neon/&DISTRO_NAME_NO_CAP;</filename>.
246 You are put into a detached HEAD state,
247 which is fine since you are only going to
248 be building and not developing.
249 </para></listitem>
250 <listitem><para>Change to the
251 <filename>scripts</filename>
252 directory within the Git repository:
253 <literallayout class='monospaced'>
254 $ cd scripts
255 </literallayout>
256 </para></listitem>
257 <listitem><para>Set up the local build environment
258 by running the setup script:
259 <literallayout class='monospaced'>
260 $ ./setup.sh
261 </literallayout>
262 When the script finishes execution,
263 it prompts you with instructions on how to run
264 the <filename>build.sh</filename> script, which
265 is also in the <filename>scripts</filename>
266 directory of the Git repository created
267 earlier.
268 </para></listitem>
269 <listitem><para>
270 Run the <filename>build.sh</filename>
271 script as directed.
272 Be sure to provide the tag name,
273 documentation branch, and a release name.</para>
274
275 <para>Following is an example:
276 <literallayout class='monospaced'>
277 $ ECLIPSE_HOME=/home/scottrif/eclipse-yocto/scripts/eclipse ./build.sh -l neon/&DISTRO_NAME_NO_CAP; master yocto-&DISTRO; 2>&amp;1 | tee build.log
278 </literallayout>
279 The previous example command adds the tag
280 you need for
281 <filename>neon/&DISTRO_NAME_NO_CAP;</filename>
282 to <filename>HEAD</filename>, then tells
283 the build script to use the local (-l) Git
284 checkout for the build.
285 After running the script, the file
286 <filename>org.yocto.sdk-</filename><replaceable>release</replaceable><filename>-</filename><replaceable>date</replaceable><filename>-archive.zip</filename>
287 is in the current directory.
288 </para></listitem>
289 <listitem><para>If necessary, start the Eclipse IDE
290 and be sure you are in the Workbench.
291 </para></listitem>
292 <listitem><para>Select "Install New Software" from
293 the "Help" pull-down menu.
294 </para></listitem>
295 <listitem><para>Click "Add".
296 </para></listitem>
297 <listitem><para>Provide anything you want in the
298 "Name" field.
299 </para></listitem>
300 <listitem><para>Click "Archive" and browse to the
301 ZIP file you built earlier.
302 This ZIP file should not be "unzipped", and must
303 be the <filename>*archive.zip</filename> file
304 created by running the
305 <filename>build.sh</filename> script.
306 </para></listitem>
307 <listitem><para>Click the "OK" button.
308 </para></listitem>
309 <listitem><para>Check the boxes that appear in
310 the installation window to install the
311 following:
312 <literallayout class='monospaced'>
313 Yocto Project SDK Plug-in
314 Yocto Project Documentation plug-in
315 </literallayout>
316 </para></listitem>
317 <listitem><para>Finish the installation by clicking
318 through the appropriate buttons.
319 You can click "OK" when prompted about
320 installing software that contains unsigned
321 content.
322 </para></listitem>
323 <listitem><para>Restart the Eclipse IDE if
324 necessary.
325 </para></listitem>
326 </orderedlist>
327 </para>
328
329 <para>
330 At this point you should be able to configure the
331 Eclipse Yocto Plug-in as described in the
332 "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>"
333 section.</para>
334 </section>
335 </section>
336
337 <section id='neon-configuring-the-eclipse-yocto-plug-in'>
338 <title>Configuring the Neon Eclipse Yocto Plug-In</title>
339
340 <para>
341 Configuring the Neon Eclipse Yocto Plug-in involves setting the
342 Cross Compiler options and the Target options.
343 The configurations you choose become the default settings
344 for all projects.
345 You do have opportunities to change them later when
346 you configure the project (see the following section).
347 </para>
348
349 <para>
350 To start, you need to do the following from within the
351 Eclipse IDE:
352 <orderedlist>
353 <listitem><para>
354 Choose "Preferences" from the
355 "Window" menu to display the Preferences Dialog.
356 </para></listitem>
357 <listitem><para>
358 Click "Yocto Project SDK" to display
359 the configuration screen.
360 </para></listitem>
361 </orderedlist>
362 The following sub-sections describe how to configure the
363 the plug-in.
364 <note>
365 Throughout the descriptions, a start-to-finish example for
366 preparing a QEMU image for use with Eclipse is referenced
367 as the "wiki" and is linked to the example on the
368 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'> Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
369 wiki page.
370 </note>
371 </para>
372
373 <section id='neon-configuring-the-cross-compiler-options'>
374 <title>Configuring the Cross-Compiler Options</title>
375
376 <para>
377 Cross Compiler options enable Eclipse to use your specific
378 cross compiler toolchain.
379 To configure these options, you must select
380 the type of toolchain, point to the toolchain, specify
381 the sysroot location, and select the target
382 architecture.
383 <itemizedlist>
384 <listitem><para>
385 <emphasis>Selecting the Toolchain Type:</emphasis>
386 Choose between "Standalone pre-built toolchain"
387 and
388 "Build system derived toolchain" for Cross Compiler
389 Options.
390 <itemizedlist>
391 <listitem><para>
392 <emphasis>Standalone Pre-built Toolchain:</emphasis>
393 Select this type when you are using
394 a stand-alone cross-toolchain.
395 For example, suppose you are an
396 application developer and do not
397 need to build a target image.
398 Instead, you just want to use an
399 architecture-specific toolchain on
400 an existing kernel and target root
401 filesystem.
402 In other words, you have downloaded
403 and installed a pre-built toolchain
404 for an existing image.
405 </para></listitem>
406 <listitem><para>
407 <emphasis>Build System Derived Toolchain:</emphasis>
408 Select this type if you built the
409 toolchain as part of the
410 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
411 When you select "Build system derived
412 toolchain", you are using the toolchain
413 built and bundled inside the Build
414 Directory.
415 For example, suppose you created a
416 suitable image using the steps in the
417 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
418 In this situation, you would select
419 "Build system derived toolchain".
420 </para></listitem>
421 </itemizedlist>
422 </para></listitem>
423 <listitem><para>
424 <emphasis>Specify the Toolchain Root Location:</emphasis>
425 If you are using a stand-alone pre-built
426 toolchain, you should be pointing to where it is
427 installed (e.g.
428 <filename>/opt/poky/&DISTRO;</filename>).
429 See the
430 "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
431 section for information about how the SDK is
432 installed.</para>
433
434 <para>If you are using a build system derived
435 toolchain, the path you provide for the
436 "Toolchain Root Location" field is the
437 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
438 from which you run the
439 <filename>bitbake</filename> command (e.g
440 <filename>/home/scottrif/poky/build</filename>).</para>
441 <para>For more information, see the
442 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
443 section.
444 </para></listitem>
445 <listitem><para>
446 <emphasis>Specify Sysroot Location:</emphasis>
447 This location is where the root filesystem for
448 the target hardware resides.
449 </para>
450
451 <para>This location depends on where you
452 separately extracted and installed the
453 target filesystem when you either built
454 it or downloaded it.
455 <note>
456 If you downloaded the root filesystem
457 for the target hardware rather than
458 built it, you must download the
459 <filename>sato-sdk</filename> image
460 in order to build any c/c++ projects.
461 </note>
462 As an example, suppose you prepared an image
463 using the steps in the
464 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
465 If so, the <filename>MY_QEMU_ROOTFS</filename>
466 directory is found in the
467 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
468 and you would browse to and select that directory
469 (e.g. <filename>/home/scottrif/build/MY_QEMU_ROOTFS</filename>).
470 </para>
471
472 <para>For more information on how to install the
473 toolchain and on how to extract and install the
474 sysroot filesystem, see the
475 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
476 section.
477 </para></listitem>
478 <listitem><para>
479 <emphasis>Select the Target Architecture:</emphasis>
480 The target architecture is the type of hardware
481 you are going to use or emulate.
482 Use the pull-down "Target Architecture" menu
483 to make your selection.
484 The pull-down menu should have the supported
485 architectures.
486 If the architecture you need is not listed in
487 the menu, you will need to build the image.
488 See the
489 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-building-a-simple-image'>Building a Simple Image</ulink>"
490 section of the Yocto Project Development Tasks
491 Manual for more information.
492 You can also see the
493 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
494 </para></listitem>
495 </itemizedlist>
496 </para>
497 </section>
498
499 <section id='neon-configuring-the-target-options'>
500 <title>Configuring the Target Options</title>
501
502 <para>
503 You can choose to emulate hardware using the QEMU
504 emulator, or you can choose to run your image on actual
505 hardware.
506 <itemizedlist>
507 <listitem><para>
508 <emphasis>QEMU:</emphasis>
509 Select this option if you will be using the
510 QEMU emulator.
511 If you are using the emulator, you also need to
512 locate the kernel and specify any custom
513 options.</para>
514
515 <para>If you selected the Build system derived
516 toolchain, the target kernel you built will be
517 located in the
518 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
519 in
520 <filename>tmp/deploy/images/<replaceable>machine</replaceable></filename>
521 directory.
522 As an example, suppose you performed the steps in
523 the
524 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
525 In this case, you specify your Build Directory path
526 followed by the image (e.g.
527 <filename>/home/scottrif/poky/build/tmp/deploy/images/qemux86/bzImage-qemux86.bin</filename>).
528 </para>
529
530 <para>If you selected the standalone pre-built
531 toolchain, the pre-built image you downloaded is
532 located in the directory you specified when you
533 downloaded the image.</para>
534
535 <para>Most custom options are for advanced QEMU
536 users to further customize their QEMU instance.
537 These options are specified between paired
538 angled brackets.
539 Some options must be specified outside the
540 brackets.
541 In particular, the options
542 <filename>serial</filename>,
543 <filename>nographic</filename>, and
544 <filename>kvm</filename> must all be outside the
545 brackets.
546 Use the <filename>man qemu</filename> command
547 to get help on all the options and their use.
548 The following is an example:
549 <literallayout class='monospaced'>
550 serial ‘&lt;-m 256 -full-screen&gt;’
551 </literallayout>
552 Regardless of the mode, Sysroot is already
553 defined as part of the Cross-Compiler Options
554 configuration in the "Sysroot Location:" field.
555 </para></listitem>
556 <listitem><para>
557 <emphasis>External HW:</emphasis>
558 Select this option if you will be using actual
559 hardware.
560 </para></listitem>
561 </itemizedlist>
562 </para>
563
564 <para>
565 Click the "Apply" and "OK" to save your plug-in
566 configurations.
567 </para>
568 </section>
569 </section>
570 </section>
571
572 <section id='neon-creating-the-project'>
573 <title>Creating the Project</title>
574
575 <para>
576 You can create two types of projects: Autotools-based, or
577 Makefile-based.
578 This section describes how to create Autotools-based projects
579 from within the Eclipse IDE.
580 For information on creating Makefile-based projects in a
581 terminal window, see the
582 "<link linkend='makefile-based-projects'>Makefile-Based Projects</link>"
583 section.
584 <note>
585 Do not use special characters in project names
586 (e.g. spaces, underscores, etc.). Doing so can
587 cause the configuration to fail.
588 </note>
589 </para>
590
591 <para>
592 To create a project based on a Yocto template and then display
593 the source code, follow these steps:
594 <orderedlist>
595 <listitem><para>
596 Select "C Project" from the "File -> New" menu.
597 </para></listitem>
598 <listitem><para>
599 Expand "Yocto Project SDK Autotools Project".
600 </para></listitem>
601 <listitem><para>
602 Select "Hello World ANSI C Autotools Projects".
603 This is an Autotools-based project based on a Yocto
604 template.
605 </para></listitem>
606 <listitem><para>
607 Put a name in the "Project name:" field.
608 Do not use hyphens as part of the name
609 (e.g. "hello").
610 </para></listitem>
611 <listitem><para>
612 Click "Next".
613 </para></listitem>
614 <listitem><para>
615 Add appropriate information in the various fields.
616 </para></listitem>
617 <listitem><para>
618 Click "Finish".
619 </para></listitem>
620 <listitem><para>
621 If the "open perspective" prompt appears,
622 click "Yes" so that you are in the C/C++ perspective.
623 </para></listitem>
624 <listitem><para>
625 The left-hand navigation pane shows your project.
626 You can display your source by double clicking the
627 project's source file.
628 </para></listitem>
629 </orderedlist>
630 </para>
631 </section>
632
633 <section id='neon-configuring-the-cross-toolchains'>
634 <title>Configuring the Cross-Toolchains</title>
635
636 <para>
637 The earlier section,
638 "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>",
639 sets up the default project configurations.
640 You can override these settings for a given project by following
641 these steps:
642 <orderedlist>
643 <listitem><para>
644 Select "Yocto Project Settings" from
645 the "Project -> Properties" menu.
646 This selection brings up the Yocto Project Settings
647 Dialog and allows you to make changes specific to an
648 individual project.</para>
649 <para>By default, the Cross Compiler Options and Target
650 Options for a project are inherited from settings you
651 provided using the Preferences Dialog as described
652 earlier in the
653 "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>" section.
654 The Yocto Project Settings Dialog allows you to override
655 those default settings for a given project.
656 </para></listitem>
657 <listitem><para>
658 Make or verify your configurations for the project and
659 click "OK".
660 </para></listitem>
661 <listitem><para>
662 Right-click in the navigation pane and select
663 "Reconfigure Project" from the pop-up menu.
664 This selection reconfigures the project by running
665 <ulink url='https://en.wikipedia.org/wiki/GNU_Build_System'>Autotools GNU utility programs</ulink>
666 such as Autoconf, Automake, and so forth in the
667 workspace for your project.
668 Click on the "Console" tab beneath your source code
669 to see the results of reconfiguring your project.
670 </para></listitem>
671 </orderedlist>
672 </para>
673 </section>
674
675 <section id='neon-building-the-project'>
676 <title>Building the Project</title>
677
678 <para>
679 To build the project select "Build All" from the
680 "Project" menu.
681 The console should update and you can note the cross-compiler
682 you are using.
683 <note>
684 When building "Yocto Project SDK Autotools" projects, the
685 Eclipse IDE might display error messages for
686 Functions/Symbols/Types that cannot be "resolved", even when
687 the related include file is listed at the project navigator and
688 when the project is able to build.
689 For these cases only, it is recommended to add a new linked
690 folder to the appropriate sysroot.
691 Use these steps to add the linked folder:
692 <orderedlist>
693 <listitem><para>
694 Select the project.
695 </para></listitem>
696 <listitem><para>
697 Select "Folder" from the "File > New" menu.
698 </para></listitem>
699 <listitem><para>
700 In the "New Folder" Dialog, select "Link to alternate
701 location (linked folder)".
702 </para></listitem>
703 <listitem><para>
704 Click "Browse" to navigate to the include folder inside
705 the same sysroot location selected in the Yocto Project
706 configuration preferences.
707 </para></listitem>
708 <listitem><para>
709 Click "OK".
710 </para></listitem>
711 <listitem><para>
712 Click "Finish" to save the linked folder.
713 </para></listitem>
714 </orderedlist>
715 </note>
716 </para>
717 </section>
718
719 <section id='neon-starting-qemu-in-user-space-nfs-mode'>
720 <title>Starting QEMU in User-Space NFS Mode</title>
721
722 <para>
723 To start the QEMU emulator from within Eclipse, follow these
724 steps:
725 <note>
726 See the
727 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
728 chapter in the Yocto Project Development Tasks Manual
729 for more information on using QEMU.
730 </note>
731 <orderedlist>
732 <listitem><para>Expose and select "External Tools
733 Configurations ..." from the "Run -> External Tools" menu.
734 </para></listitem>
735 <listitem><para>
736 Locate and select your image in the navigation panel to
737 the left (e.g. <filename>qemu_i586-poky-linux</filename>).
738 </para></listitem>
739 <listitem><para>
740 Click "Run" to launch QEMU.
741 <note>
742 The host on which you are running QEMU must have
743 the <filename>rpcbind</filename> utility running to be
744 able to make RPC calls on a server on that machine.
745 If QEMU does not invoke and you receive error messages
746 involving <filename>rpcbind</filename>, follow the
747 suggestions to get the service running.
748 As an example, on a new Ubuntu 16.04 LTS installation,
749 you must do the following in order to get QEMU to
750 launch:
751 <literallayout class='monospaced'>
752 $ sudo apt-get install rpcbind
753 </literallayout>
754 After installing <filename>rpcbind</filename>, you
755 need to edit the
756 <filename>/etc/init.d/rpcbind</filename> file to
757 include the following line:
758 <literallayout class='monospaced'>
759 OPTIONS="-i -w"
760 </literallayout>
761 After modifying the file, you need to start the
762 service:
763 <literallayout class='monospaced'>
764 $ sudo service portmap restart
765 </literallayout>
766 </note>
767 </para></listitem>
768 <listitem><para>If needed, enter your host root password in
769 the shell window at the prompt.
770 This sets up a <filename>Tap 0</filename> connection
771 needed for running in user-space NFS mode.
772 </para></listitem>
773 <listitem><para>Wait for QEMU to launch.
774 </para></listitem>
775 <listitem><para>Once QEMU launches, you can begin operating
776 within that environment.
777 One useful task at this point would be to determine the
778 IP Address for the user-space NFS by using the
779 <filename>ifconfig</filename> command.
780 The IP address of the QEMU machine appears in the
781 xterm window.
782 You can use this address to help you see which particular
783 IP address the instance of QEMU is using.
784 </para></listitem>
785 </orderedlist>
786 </para>
787 </section>
788
789 <section id='neon-deploying-and-debugging-the-application'>
790 <title>Deploying and Debugging the Application</title>
791
792 <para>
793 Once the QEMU emulator is running the image, you can deploy
794 your application using the Eclipse IDE and then use
795 the emulator to perform debugging.
796 Follow these steps to deploy the application.
797 <note>
798 Currently, Eclipse does not support SSH port forwarding.
799 Consequently, if you need to run or debug a remote
800 application using the host display, you must create a
801 tunneling connection from outside Eclipse and keep
802 that connection alive during your work.
803 For example, in a new terminal, run the following:
804 <literallayout class='monospaced'>
805 $ ssh -XY <replaceable>user_name</replaceable>@<replaceable>remote_host_ip</replaceable>
806 </literallayout>
807 Using the above form, here is an example:
808 <literallayout class='monospaced'>
809 $ ssh -XY root@192.168.7.2
810 </literallayout>
811 After running the command, add the command to be executed
812 in Eclipse's run configuration before the application
813 as follows:
814 <literallayout class='monospaced'>
815 export DISPLAY=:10.0
816 </literallayout>
817 Be sure to not destroy the connection during your QEMU
818 session (i.e. do not
819 exit out of or close that shell).
820 </note>
821 <orderedlist>
822 <listitem><para>
823 Select "Debug Configurations..." from the
824 "Run" menu.</para></listitem>
825 <listitem><para>
826 In the left area, expand
827 "C/C++Remote Application".
828 </para></listitem>
829 <listitem><para>
830 Locate your project and select it to bring
831 up a new tabbed view in the Debug Configurations Dialog.
832 </para></listitem>
833 <listitem><para>
834 Click on the "Debugger" tab to see the
835 cross-tool debugger you are using.
836 Be sure to change to the debugger perspective in Eclipse.
837 </para></listitem>
838 <listitem><para>
839 Click on the "Main" tab.
840 </para></listitem>
841 <listitem><para>Create a new connection to the QEMU instance
842 by clicking on "new".</para></listitem>
843 <listitem><para>
844 Select "SSH", which means
845 Secure Socket Shell.
846 Optionally, you can select a TCF connection instead.
847 </para></listitem>
848 <listitem><para>
849 Click "Next".
850 </para></listitem>
851 <listitem><para>
852 Clear out the "Connection name" field and
853 enter any name you want for the connection.
854 </para></listitem>
855 <listitem><para>
856 Put the IP address for the connection in
857 the "Host" field.
858 For QEMU, the default is "192.168.7.2".
859 However, if a previous QEMU session did not exit
860 cleanly, the IP address increments (e.g.
861 "192.168.7.3").
862 <note>
863 You can find the IP address for the current QEMU
864 session by looking in the xterm that opens when
865 you launch QEMU.
866 </note>
867 </para></listitem>
868 <listitem><para>
869 Enter "root", which
870 is the default for QEMU, for the "User" field.
871 Be sure to leave the password field empty.
872 </para></listitem>
873 <listitem><para>Click "Finish" to close the
874 New Connections Dialog.
875 </para></listitem>
876 <listitem><para>
877 If necessary, use the drop-down menu now in the
878 "Connection" field and pick the IP Address you entered.
879 </para></listitem>
880 <listitem><para>
881 Assuming you are connecting as the root user,
882 which is the default for QEMU x86-64 SDK images provided by
883 the Yocto Project, in the "Remote Absolute File Path for
884 C/C++ Application" field, browse to
885 <filename>/home/root/</filename><replaceable>ProjectName</replaceable>
886 (e.g. <filename>/home/root/hello</filename>).
887 You could also browse to any other path you have write
888 access to on the target such as
889 <filename>/usr/bin</filename>.
890 This location is where your application will be located on
891 the QEMU system.
892 If you fail to browse to and specify an appropriate
893 location, QEMU will not understand what to remotely
894 launch.
895 Eclipse is helpful in that it auto fills your application
896 name for you assuming you browsed to a directory.
897 <note><title>Tips</title>
898 <itemizedlist>
899 <listitem><para>
900 If you are prompted to provide a username
901 and to optionally set a password, be sure
902 you provide "root" as the username and you
903 leave the password field blank.
904 </para></listitem>
905 <listitem><para>
906 If browsing to a directory fails or times
907 out, but you can
908 <filename>ssh</filename> into your QEMU
909 or target from the command line and you
910 have proxies set up, it is likely that
911 Eclipse is sending the SSH traffic to a
912 proxy.
913 In this case, either use TCF , or click on
914 "Configure proxy settings" in the
915 connection dialog and add the target IP
916 address to the "bypass proxy" section.
917 You might also need to change
918 "Active Provider" from Native to Manual.
919 </para></listitem>
920 </itemizedlist>
921 </note>
922 </para></listitem>
923 <listitem><para>
924 Be sure you change to the "Debug" perspective in Eclipse.
925 </para></listitem>
926 <listitem><para>
927 Click "Debug"
928 </para></listitem>
929 <listitem><para>
930 Accept the debug perspective.
931 </para></listitem>
932 </orderedlist>
933 </para>
934 </section>
935
936 <section id='neon-using-Linuxtools'>
937 <title>Using Linuxtools</title>
938
939 <para>
940 As mentioned earlier in the manual, performance tools exist
941 (Linuxtools) that enhance your development experience.
942 These tools are aids in developing and debugging applications and
943 images.
944 You can run these tools from within the Eclipse IDE through the
945 "Linuxtools" menu.
946 </para>
947
948 <para>
949 For information on how to configure and use these tools, see
950 <ulink url='http://www.eclipse.org/linuxtools/'>http://www.eclipse.org/linuxtools/</ulink>.
951 </para>
952 </section>
953</appendix>
954<!--
955vim: expandtab tw=80 ts=4
956-->
diff --git a/documentation/sdk-manual/sdk-eclipse-project.xml b/documentation/sdk-manual/sdk-eclipse-project.xml
deleted file mode 100644
index 15a9ae7535..0000000000
--- a/documentation/sdk-manual/sdk-eclipse-project.xml
+++ /dev/null
@@ -1,1248 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='sdk-eclipse-project'>
6
7 <title>Developing Applications Using <trademark class='trade'>Eclipse</trademark></title>
8
9 <para>
10 If you are familiar with the popular Eclipse IDE, you can use an
11 Eclipse Yocto Plug-in to allow you to develop, deploy, and test your
12 application all from within Eclipse.
13 This chapter describes general workflow using the SDK and Eclipse
14 and how to configure and set up Eclipse.
15 <note><title>Notes</title>
16 <itemizedlist>
17 <listitem><para>
18 This chapter assumes development of applications on top of
19 an image prepared using the Yocto Project.
20 As such, inclusion of a pre-built image or the building of
21 an image is included in the workflow.
22 </para></listitem>
23 <listitem><para>
24 The chapter also assumes development on a build host that
25 is set up to use the Yocto Project.
26 Realize that you can easily use Eclipse and the Yocto
27 Project plug-in to develop an application for any number
28 of images developed and tested on different machines.
29 </para></listitem>
30 </itemizedlist>
31 </note>
32 </para>
33
34 <section id='application-development-workflow-using-eclipse'>
35 <title>Application Development Workflow Using <trademark class='trade'>Eclipse</trademark></title>
36
37 <para>
38 The following figure and supporting list summarize a
39 general workflow for application development that uses the
40 SDK within the Eclipse IDE.
41 The application developed runs on top of an image created using
42 the Yocto Project.
43 </para>
44
45 <para>
46 <imagedata fileref="figures/sdk-eclipse-dev-flow.png"
47 width="7in" depth="7in" align="center" scale="100" />
48 </para>
49
50 <para>
51 <orderedlist>
52 <listitem><para>
53 <emphasis>Prepare the Host System for the Yocto Project</emphasis>:
54 Because this example workflow assumes development on a
55 system set up to use the Yocto Project, you need to be
56 sure your
57 <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>
58 can use the Yocto Project.
59 See the
60 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host'>Preparing the Build Host</ulink>"
61 section in the Yocto Project Development Tasks Manual for
62 information on how to set up your build host.
63 <note>
64 Be sure you install the "xterm" package, which is a
65 <ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-build-host'>graphical and Eclipse plug-in extra</ulink>
66 needed by Eclipse.
67 </note>
68 </para></listitem>
69 <listitem><para>
70 <emphasis>Secure the Yocto Project Kernel Target Image</emphasis>:
71 This example workflow assumes application development on
72 top of an image built using the Yocto Project.
73 Depending on whether you are using a pre-built image
74 that matches your target architecture or you are using an
75 image you build using the
76 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded Build System</ulink>
77 and where you are going to run the image while you
78 develop your application (QEMU or real hardware), the
79 area from which you get the image differs.
80 <itemizedlist>
81 <listitem><para>
82 Download the image from
83 <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink>
84 if your target architecture is supported and
85 you are going to develop and test your
86 application on actual hardware.
87 </para></listitem>
88 <listitem><para>
89 Download the image from
90 <ulink url='&YOCTO_QEMU_DL_URL;'>
91 <filename>machines/qemu</filename></ulink> if
92 your target architecture is supported and you
93 are going to develop and test your application
94 using the
95 <ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>QEMU Emulator</ulink>.
96 </para></listitem>
97 <listitem><para>
98 Build your image if you cannot find a pre-built
99 image that matches your target architecture.
100 If your target architecture is similar to a
101 supported architecture, you can modify the
102 kernel image before you build it.
103 See the
104 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</ulink>"
105 section in the Yocto Project Linux Kernel
106 Development Manual for an example.
107 You can also see the
108 "<ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage#Making_a_Suitable_Qemux86_Image'>Making a Suitable Qemux86 Image</ulink>"
109 wiki for steps needed to build an image suitable
110 for QEMU and for debugging within the Eclipse IDE.
111 </para></listitem>
112 </itemizedlist>
113 </para></listitem>
114 <listitem>
115 <para><emphasis>Install the SDK</emphasis>:
116 The SDK provides a target-specific cross-development
117 toolchain, the root filesystem, the QEMU emulator, and
118 other tools that can help you develop your application.
119 For information on how to install the SDK, see the
120 "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
121 section.
122 </para></listitem>
123 <listitem><para>
124 <emphasis>Secure the Target Root Filesystem and the Cross-Development Toolchain</emphasis>:
125 You need to find and download the appropriate root
126 filesystem and the cross-development toolchain.</para>
127
128 <para>You can find the tarballs for the root filesystem
129 in the same area used for the kernel image.
130 Depending on the type of image you are running, the
131 root filesystem you need differs.
132 For example, if you are developing an application that
133 runs on an image that supports Sato, you need to get a
134 root filesystem that supports Sato.</para>
135
136 <para>You can find the cross-development toolchains at
137 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'><filename>toolchains</filename></ulink>.
138 Be sure to get the correct toolchain for your
139 development host and your target architecture.
140 See the "<link linkend='sdk-locating-pre-built-sdk-installers'>Locating Pre-Built SDK Installers</link>"
141 section for information and the
142 "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
143 section for installation information.
144 <note>
145 As an alternative to downloading an SDK, you can
146 build the SDK installer.
147 For information on building the installer, see the
148 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
149 section.
150 Another helpful resource for building an installer
151 is the
152 "<ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink>"
153 wiki page.
154 </note>
155 </para></listitem>
156 <listitem><para>
157 <emphasis>Create and Build Your Application</emphasis>:
158 You need to have source files for your application.
159 Once you have the files, you can use the Eclipse IDE
160 to import them and build the project.
161 </para></listitem>
162 <listitem><para>
163 <emphasis>Deploy the Image With the Application</emphasis>:
164 Using the Eclipse IDE, you can deploy your image to the
165 hardware or to QEMU through the project's preferences.
166 You can also use Eclipse to load and test your image
167 under QEMU.
168 See the
169 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
170 chapter in the Yocto Project Development Tasks Manual
171 for information on using QEMU.
172 </para></listitem>
173 <listitem><para>
174 <emphasis>Test and Debug the Application</emphasis>:
175 Once your application is deployed, you need to test it.
176 Within the Eclipse IDE, you can use the debugging
177 environment along with supported performance enhancing
178 <ulink url='http://www.eclipse.org/linuxtools/'>Linux Tools</ulink>.
179 </para></listitem>
180 </orderedlist>
181 </para>
182 </section>
183
184 <section id='adt-eclipse'>
185 <title>Working Within Eclipse</title>
186
187 <para>
188 The Eclipse IDE is a popular development environment and it
189 fully supports development using the Yocto Project.
190 </para>
191
192 <para>
193 When you install and configure the Eclipse Yocto Project
194 Plug-in into the Eclipse IDE, you maximize your Yocto
195 Project experience.
196 Installing and configuring the Plug-in results in an
197 environment that has extensions specifically designed to let
198 you more easily develop software.
199 These extensions allow for cross-compilation, deployment, and
200 execution of your output into a QEMU emulation session as well
201 as actual target hardware.
202 You can also perform cross-debugging and profiling.
203 The environment also supports performance enhancing
204 <ulink url='http://www.eclipse.org/linuxtools/'>tools</ulink>
205 that allow you to perform remote profiling, tracing,
206 collection of power data, collection of latency data, and
207 collection of performance data.
208 <note>
209 This release of the Yocto Project supports both the Oxygen
210 and Neon versions of the Eclipse IDE.
211 This section provides information on how to use the Oxygen
212 release with the Yocto Project.
213 For information on how to use the Neon version of Eclipse
214 with the Yocto Project, see
215 "<link linkend='sdk-appendix-neon-yp-eclipse-plug-in'>Appendix D</link>".
216 </note>
217 </para>
218
219 <section id='oxygen-setting-up-the-eclipse-ide'>
220 <title>Setting Up the Oxygen Version of the Eclipse IDE</title>
221
222 <para>
223 To develop within the Eclipse IDE, you need to do the
224 following:
225 <orderedlist>
226 <listitem><para>
227 Install the Oxygen version of the Eclipse IDE.
228 </para></listitem>
229 <listitem><para>
230 Configure the Eclipse IDE.
231 </para></listitem>
232 <listitem><para>
233 Install the Eclipse Yocto Plug-in.
234 </para></listitem>
235 <listitem><para>
236 Configure the Eclipse Yocto Plug-in.
237 </para></listitem>
238 </orderedlist>
239 <note>
240 Do not install Eclipse from your distribution's package
241 repository.
242 Be sure to install Eclipse from the official Eclipse
243 download site as directed in the next section.
244 </note>
245 </para>
246
247 <section id='oxygen-installing-eclipse-ide'>
248 <title>Installing the Oxygen Eclipse IDE</title>
249
250 <para>
251 Follow these steps to locate, install, and configure
252 Oxygen Eclipse:
253 <orderedlist>
254 <listitem><para>
255 <emphasis>Locate the Oxygen Download:</emphasis>
256 Open a browser and go to
257 <ulink url='http://www.eclipse.org/oxygen/'>http://www.eclipse.org/oxygen/</ulink>.
258 </para></listitem>
259 <listitem><para>
260 <emphasis>Download the Tarball:</emphasis>
261 Click through the "Download" buttons to
262 download the file.
263 </para></listitem>
264 <listitem><para>
265 <emphasis>Unpack the Tarball:</emphasis>
266 Move to a clean directory and unpack the
267 tarball.
268 Here is an example:
269 <literallayout class='monospaced'>
270 $ cd ~
271 $ tar -xzvf ~/Downloads/eclipse-inst-linux64.tar.gz
272 </literallayout>
273 Everything unpacks into a folder named
274 "eclipse-installer".
275 </para></listitem>
276 <listitem><para>
277 <emphasis>Launch the Installer:</emphasis>
278 Use the following commands to launch the
279 installer:
280 <literallayout class='monospaced'>
281 $ cd ~/eclipse-installer
282 $ ./eclipse-inst
283 </literallayout>
284 </para></listitem>
285 <listitem><para>
286 <emphasis>Select Your IDE:</emphasis>
287 From the list, select the "Eclipse IDE for
288 C/C++ Developers".
289 </para></listitem>
290 <listitem><para>
291 <emphasis>Install the Software:</emphasis>
292 Click "Install" to begin the installation.
293 Accept all the certificates and any license
294 agreements.
295 Click "Install" again to finish the installation.
296 </para></listitem>
297 <listitem><para>
298 <emphasis>Launch Oxygen:</emphasis>
299 Accept the default "workspace" and click the
300 "Launch" button.
301 You should see the Eclipse welcome page from which
302 can click "workbench" to enter your workspace.
303 <note>
304 The executable for Eclipse is located in the
305 <filename>eclipse/cpp-oxygen/eclipse</filename>
306 folder.
307 To launch Eclipse outside of the installation
308 process, simply execute that binary.
309 Here is an example:
310 <literallayout class='monospaced'>
311 $ ~/eclipse/cpp-oxygen/eclipse/eclipse
312 </literallayout>
313 </note>
314 </para></listitem>
315 </orderedlist>
316 </para>
317 </section>
318
319 <section id='oxygen-configuring-the-eclipse-ide'>
320 <title>Configuring the Oxygen Eclipse IDE</title>
321
322 <para>
323 Follow these steps to configure the Oxygen Eclipse IDE.
324 <note><title>Notes</title>
325 <itemizedlist>
326 <listitem><para>
327 Depending on how you installed Eclipse and what
328 you have already done, some of the options do
329 not appear.
330 If you cannot find an option as directed by the
331 manual, it has already been installed.
332 </para></listitem>
333 <listitem><para>
334 If you want to see all options regardless of
335 whether they are installed or not, deselect the
336 "Hide items that are already installed"
337 check box.
338 </para></listitem>
339 </itemizedlist>
340 </note>
341 <orderedlist>
342 <listitem><para>
343 Be sure Eclipse is running and you are in your
344 workbench.
345 Just click "workbench" if you are not in your
346 default workspace.
347 </para></listitem>
348 <listitem><para>
349 Select "Install New Software" from the "Help"
350 pull-down menu.
351 </para></listitem>
352 <listitem><para>
353 Select
354 "Oxygen - http://download.eclipse.org/releases/oxygen"
355 from the "Work with:" pull-down menu.
356 </para></listitem>
357 <listitem><para>
358 Expand the box next to "Linux Tools" and select
359 the following:
360 <literallayout class='monospaced'>
361 C/C++ Remote (Over TCF/TE) Run/Debug Launcher
362 TM Terminal
363 </literallayout>
364 </para></listitem>
365 <listitem><para>
366 Expand the box next to "Mobile and Device
367 Development" and select the following
368 boxes:
369 <literallayout class='monospaced'>
370 C/C++ Remote (Over TCF/TE) Run/Debug Launcher
371 Remote System Explorer User Actions
372 TM Terminal
373 TCF Remote System Explorer add-in
374 TCF Target Explorer
375 </literallayout>
376 </para></listitem>
377 <listitem><para>
378 Expand the box next to "Programming Languages"
379 and select the following box:
380 <literallayout class='monospaced'>
381 C/C++ Development Tools SDK
382 </literallayout>
383 </para></listitem>
384 <listitem><para>
385 Complete the installation by clicking through
386 appropriate "Next" and "Finish" buttons and then
387 restart the Eclipse IDE.
388 </para></listitem>
389 </orderedlist>
390 </para>
391 </section>
392
393 <section id='oxygen-installing-the-eclipse-yocto-plug-in'>
394 <title>Installing or Accessing the Oxygen Eclipse Yocto Plug-in</title>
395
396 <para>
397 You can install the Eclipse Yocto Plug-in into the
398 Eclipse IDE one of two ways: use the Yocto Project's
399 Eclipse Update site to install the pre-built plug-in,
400 or build and install the plug-in from the latest
401 source code.
402 </para>
403
404 <section id='oxygen-new-software'>
405 <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title>
406
407 <para>
408 To install the Oxygen Eclipse Yocto Plug-in from the
409 update site, follow these steps:
410 <orderedlist>
411 <listitem><para>
412 Start up the Eclipse IDE.
413 </para></listitem>
414 <listitem><para>
415 In Eclipse, select "Install New
416 Software" from the "Help" menu.
417 </para></listitem>
418 <listitem><para>
419 Click "Add..." in the "Work with:" area.
420 </para></listitem>
421 <listitem><para>
422 Enter
423 <filename>&ECLIPSE_DL_PLUGIN_URL;/oxygen</filename>
424 in the URL field and provide a meaningful
425 name in the "Name" field.
426 </para></listitem>
427 <listitem><para>
428 Click "OK" to have the entry automatically
429 populate the "Work with:" field and to have
430 the items for installation appear in the window
431 below.
432 </para></listitem>
433 <listitem><para>
434 Check the boxes next to the following:
435 <literallayout class='monospaced'>
436 Yocto Project SDK Plug-in
437 Yocto Project Documentation plug-in
438 </literallayout>
439 </para></listitem>
440 <listitem><para>
441 Complete the remaining software
442 installation steps and then restart the
443 Eclipse IDE to finish the installation of
444 the plug-in.
445 <note>
446 You can click "OK" when prompted about
447 installing software that contains
448 unsigned content.
449 </note>
450 </para></listitem>
451 </orderedlist>
452 </para>
453 </section>
454
455 <section id='oxygen-zip-file-method'>
456 <title>Installing the Plug-in Using the Latest Source Code</title>
457
458 <para>
459 To install the Oxygen Eclipse Yocto Plug-in from the
460 latest source code, follow these steps:
461 <orderedlist>
462 <listitem><para>
463 Be sure your build host has JDK version 1.8
464 or greater.
465 On a Linux build host you can determine the
466 version using the following command:
467 <literallayout class='monospaced'>
468 $ java -version
469 </literallayout>
470 </para></listitem>
471 <listitem><para>
472 Install X11-related packages:
473 <literallayout class='monospaced'>
474 $ sudo apt-get install xauth
475 </literallayout>
476 </para></listitem>
477 <listitem><para>
478 In a new terminal shell, create a
479 Git repository with:
480 <literallayout class='monospaced'>
481 $ cd ~
482 $ git clone git://git.yoctoproject.org/eclipse-yocto
483 </literallayout>
484 </para></listitem>
485 <listitem><para>
486 Use Git to create the correct tag:
487 <literallayout class='monospaced'>
488 $ cd ~/eclipse-yocto
489 $ git checkout -b oxygen/&DISTRO_NAME_NO_CAP; remotes/origin/oxygen/&DISTRO_NAME_NO_CAP;
490 </literallayout>
491 This creates a local tag named
492 <filename>oxygen/&DISTRO_NAME_NO_CAP;</filename>
493 based on the branch
494 <filename>origin/oxygen/&DISTRO_NAME_NO_CAP;</filename>.
495 You are put into a detached HEAD state,
496 which is fine since you are only going to
497 be building and not developing.
498 </para></listitem>
499 <listitem><para>
500 Change to the <filename>scripts</filename>
501 directory within the Git repository:
502 <literallayout class='monospaced'>
503 $ cd scripts
504 </literallayout>
505 </para></listitem>
506 <listitem><para>
507 Set up the local build environment
508 by running the setup script:
509 <literallayout class='monospaced'>
510 $ ./setup.sh
511 </literallayout>
512 When the script finishes execution,
513 it prompts you with instructions on how to
514 run the <filename>build.sh</filename>
515 script, which is also in the
516 <filename>scripts</filename> directory of
517 the Git repository created earlier.
518 </para></listitem>
519 <listitem><para>
520 Run the <filename>build.sh</filename>
521 script as directed.
522 Be sure to provide the tag name,
523 documentation branch, and a release name.
524 </para>
525 <para>
526 Following is an example:
527 <literallayout class='monospaced'>
528 $ ECLIPSE_HOME=/home/scottrif/eclipse-yocto/scripts/eclipse ./build.sh -l oxygen/&DISTRO_NAME_NO_CAP; master yocto-&DISTRO; 2>&amp;1 | tee build.log
529 </literallayout>
530 The previous example command adds the tag
531 you need for
532 <filename>oxygen/&DISTRO_NAME_NO_CAP;</filename>
533 to <filename>HEAD</filename>, then tells
534 the build script to use the local (-l) Git
535 checkout for the build.
536 After running the script, the file
537 <filename>org.yocto.sdk-</filename><replaceable>release</replaceable><filename>-</filename><replaceable>date</replaceable><filename>-archive.zip</filename>
538 is in the current directory.
539 </para></listitem>
540 <listitem><para>
541 If necessary, start the Eclipse IDE
542 and be sure you are in the Workbench.
543 </para></listitem>
544 <listitem><para>
545 Select "Install New Software" from
546 the "Help" pull-down menu.
547 </para></listitem>
548 <listitem><para>
549 Click "Add".
550 </para></listitem>
551 <listitem><para>
552 Provide anything you want in the
553 "Name" field.
554 </para></listitem>
555 <listitem><para>
556 Click "Archive" and browse to the
557 ZIP file you built earlier.
558 This ZIP file should not be "unzipped", and
559 must be the
560 <filename>*archive.zip</filename> file
561 created by running the
562 <filename>build.sh</filename> script.
563 </para></listitem>
564 <listitem><para>
565 Click the "OK" button.
566 </para></listitem>
567 <listitem><para>
568 Check the boxes that appear in
569 the installation window to install the
570 following:
571 <literallayout class='monospaced'>
572 Yocto Project SDK Plug-in
573 Yocto Project Documentation plug-in
574 </literallayout>
575 </para></listitem>
576 <listitem><para>
577 Finish the installation by clicking
578 through the appropriate buttons.
579 You can click "OK" when prompted about
580 installing software that contains unsigned
581 content.
582 </para></listitem>
583 <listitem><para>
584 Restart the Eclipse IDE if necessary.
585 </para></listitem>
586 </orderedlist>
587 </para>
588
589 <para>
590 At this point you should be able to configure the
591 Eclipse Yocto Plug-in as described in the
592 "<link linkend='oxygen-configuring-the-eclipse-yocto-plug-in'>Configuring the Oxygen Eclipse Yocto Plug-in</link>"
593 section.
594 </para>
595 </section>
596 </section>
597
598 <section id='oxygen-configuring-the-eclipse-yocto-plug-in'>
599 <title>Configuring the Oxygen Eclipse Yocto Plug-In</title>
600
601 <para>
602 Configuring the Oxygen Eclipse Yocto Plug-in involves
603 setting the Cross Compiler options and the Target
604 options.
605 The configurations you choose become the default
606 settings for all projects.
607 You do have opportunities to change them later when
608 you configure the project (see the following section).
609 </para>
610
611 <para>
612 To start, you need to do the following from within the
613 Eclipse IDE:
614 <orderedlist>
615 <listitem><para>
616 Choose "Preferences" from the "Window" menu to
617 display the Preferences Dialog.
618 </para></listitem>
619 <listitem><para>
620 Click "Yocto Project SDK" to display
621 the configuration screen.
622 </para></listitem>
623 </orderedlist>
624 The following sub-sections describe how to configure
625 the plug-in.
626 <note>
627 Throughout the descriptions, a start-to-finish
628 example for preparing a QEMU image for use with
629 Eclipse is referenced as the "wiki" and is linked
630 to the example on the
631 "<ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'> Cookbook guide to Making an Eclipse Debug Capable Image</ulink>"
632 wiki page.
633 </note>
634 </para>
635
636 <section id='oxygen-configuring-the-cross-compiler-options'>
637 <title>Configuring the Cross-Compiler Options</title>
638
639 <para>
640 Cross Compiler options enable Eclipse to use your
641 specific cross compiler toolchain.
642 To configure these options, you must select
643 the type of toolchain, point to the toolchain,
644 specify the sysroot location, and select the target
645 architecture.
646 <itemizedlist>
647 <listitem><para>
648 <emphasis>Selecting the Toolchain Type:</emphasis>
649 Choose between "Standalone pre-built toolchain"
650 and "Build system derived toolchain" for
651 Cross Compiler Options.
652 <itemizedlist>
653 <listitem><para>
654 <emphasis>Standalone Pre-built Toolchain:</emphasis>
655 Select this type when you are using
656 a stand-alone cross-toolchain.
657 For example, suppose you are an
658 application developer and do not
659 need to build a target image.
660 Instead, you just want to use an
661 architecture-specific toolchain on
662 an existing kernel and target root
663 filesystem.
664 In other words, you have downloaded
665 and installed a pre-built toolchain
666 for an existing image.
667 </para></listitem>
668 <listitem><para>
669 <emphasis>Build System Derived Toolchain:</emphasis>
670 Select this type if you built the
671 toolchain as part of the
672 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
673 When you select "Build system derived
674 toolchain", you are using the toolchain
675 built and bundled inside the Build
676 Directory.
677 For example, suppose you created a
678 suitable image using the steps in the
679 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
680 In this situation, you would select
681 "Build system derived toolchain".
682 </para></listitem>
683 </itemizedlist>
684 </para></listitem>
685 <listitem><para>
686 <emphasis>Specify the Toolchain Root Location:</emphasis>
687 If you are using a stand-alone pre-built
688 toolchain, you should be pointing to where
689 it is installed (e.g.
690 <filename>/opt/poky/&DISTRO;</filename>).
691 See the
692 "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
693 section for information about how the SDK is
694 installed.</para>
695
696 <para>If you are using a build system
697 derived toolchain, the path you provide for
698 the "Toolchain Root Location" field is the
699 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
700 from which you run the
701 <filename>bitbake</filename> command (e.g
702 <filename>/home/scottrif/poky/build</filename>).
703 </para>
704 <para>For more information, see the
705 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
706 section.
707 </para></listitem>
708 <listitem><para>
709 <emphasis>Specify Sysroot Location:</emphasis>
710 This location is where the root filesystem
711 for the target hardware resides.
712 </para>
713
714 <para>This location depends on where you
715 separately extracted and installed the
716 target filesystem when you either built
717 it or downloaded it.
718 <note>
719 If you downloaded the root filesystem
720 for the target hardware rather than
721 built it, you must download the
722 <filename>sato-sdk</filename> image
723 in order to build any c/c++ projects.
724 </note>
725 As an example, suppose you prepared an
726 image using the steps in the
727 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
728 If so, the
729 <filename>MY_QEMU_ROOTFS</filename>
730 directory is found in the Build Directory
731 and you would browse to and select that
732 directory (e.g.
733 <filename>/home/scottrif/poky/build/MY_QEMU_ROOTFS</filename>).
734 </para>
735
736 <para>For more information on how to
737 install the toolchain and on how to extract
738 and install the sysroot filesystem, see the
739 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
740 section.
741 </para></listitem>
742 <listitem><para>
743 <emphasis>Select the Target Architecture:</emphasis>
744 The target architecture is the type of
745 hardware you are going to use or emulate.
746 Use the pull-down "Target Architecture"
747 menu to make your selection.
748 The pull-down menu should have the
749 supported architectures.
750 If the architecture you need is not listed
751 in the menu, you will need to build the
752 image.
753 See the
754 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-building-a-simple-image'>Building a Simple Image</ulink>"
755 section of the Yocto Project Development Tasks
756 Manual for more information.
757 You can also see the
758 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
759 </para></listitem>
760 </itemizedlist>
761 </para>
762 </section>
763
764 <section id='oxygen-configuring-the-target-options'>
765 <title>Configuring the Target Options</title>
766
767 <para>
768 You can choose to emulate hardware using the QEMU
769 emulator, or you can choose to run your image on
770 actual hardware.
771 <itemizedlist>
772 <listitem><para>
773 <emphasis>QEMU:</emphasis>
774 Select this option if you will be using the
775 QEMU emulator.
776 If you are using the emulator, you also
777 need to locate the kernel and specify any
778 custom options.</para>
779
780 <para>If you selected the Build system derived
781 toolchain, the target kernel you built will be
782 located in the
783 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
784 in
785 <filename>tmp/deploy/images/<replaceable>machine</replaceable></filename>
786 directory.
787 As an example, suppose you performed the
788 steps in the
789 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
790 In this case, you specify your Build
791 Directory path followed by the image (e.g.
792 <filename>/home/scottrif/poky/build/tmp/deploy/images/qemux86/bzImage-qemux86.bin</filename>).
793 </para>
794
795 <para>If you selected the standalone
796 pre-built toolchain, the pre-built image
797 you downloaded is located in the directory
798 you specified when you downloaded the
799 image.</para>
800
801 <para>Most custom options are for advanced
802 QEMU users to further customize their QEMU
803 instance.
804 These options are specified between paired
805 angled brackets.
806 Some options must be specified outside the
807 brackets.
808 In particular, the options
809 <filename>serial</filename>,
810 <filename>nographic</filename>, and
811 <filename>kvm</filename> must all be
812 outside the brackets.
813 Use the <filename>man qemu</filename>
814 command to get help on all the options and
815 their use.
816 The following is an example:
817 <literallayout class='monospaced'>
818 serial ‘&lt;-m 256 -full-screen&gt;’
819 </literallayout>
820 Regardless of the mode, Sysroot is already
821 defined as part of the Cross-Compiler
822 Options configuration in the "Sysroot
823 Location:" field.
824 </para></listitem>
825 <listitem><para>
826 <emphasis>External HW:</emphasis>
827 Select this option if you will be using
828 actual hardware.
829 </para></listitem>
830 </itemizedlist>
831 </para>
832
833 <para>
834 Click "Apply and Close" to save your plug-in
835 configurations.
836 </para>
837 </section>
838 </section>
839 </section>
840
841 <section id='oxygen-creating-the-project'>
842 <title>Creating the Project</title>
843
844 <para>
845 You can create two types of projects: Autotools-based, or
846 Makefile-based.
847 This section describes how to create Autotools-based
848 projects from within the Eclipse IDE.
849 For information on creating Makefile-based projects in a
850 terminal window, see the
851 "<link linkend='makefile-based-projects'>Makefile-Based Projects</link>"
852 section.
853 <note>
854 Do not use special characters in project names
855 (e.g. spaces, underscores, etc.). Doing so can
856 cause configuration to fail.
857 </note>
858 </para>
859
860 <para>
861 To create a project based on a Yocto template and then
862 display the source code, follow these steps:
863 <orderedlist>
864 <listitem><para>
865 Select "C/C++ Project" from the "File -> New" menu.
866 </para></listitem>
867 <listitem><para>
868 Select "C Managed Build" from the available options and
869 click "Next".
870 </para></listitem>
871 <listitem><para>
872 Expand "Yocto Project SDK Autotools Project".
873 </para></listitem>
874 <listitem><para>
875 Select "Hello World ANSI C Autotools Projects".
876 This is an Autotools-based project based on a Yocto
877 template.
878 </para></listitem>
879 <listitem><para>
880 Put a name in the "Project name:" field.
881 Do not use hyphens as part of the name
882 (e.g. "hello").
883 </para></listitem>
884 <listitem><para>
885 Click "Next".
886 </para></listitem>
887 <listitem><para>
888 Add appropriate information in the various fields.
889 </para></listitem>
890 <listitem><para>
891 Click "Finish".
892 </para></listitem>
893 <listitem><para>
894 If the "open perspective" prompt appears,
895 click "Yes" so that you in the C/C++ perspective.
896 </para></listitem>
897 <listitem><para>The left-hand navigation pane shows
898 your project.
899 You can display your source by double clicking the
900 project's source file.
901 </para></listitem>
902 </orderedlist>
903 </para>
904 </section>
905
906 <section id='oxygen-configuring-the-cross-toolchains'>
907 <title>Configuring the Cross-Toolchains</title>
908
909 <para>
910 The earlier section,
911 "<link linkend='oxygen-configuring-the-eclipse-yocto-plug-in'>Configuring the Oxygen Eclipse Yocto Plug-in</link>",
912 sets up the default project configurations.
913 You can override these settings for a given project by
914 following these steps:
915 <orderedlist>
916 <listitem><para>
917 Select "Yocto Project Settings" from
918 the "Project -> Properties" menu.
919 This selection brings up the Yocto Project Settings
920 Dialog and allows you to make changes specific to
921 an individual project.</para>
922 <para>By default, the Cross Compiler Options and
923 Target Options for a project are inherited from
924 settings you provided using the Preferences Dialog
925 as described earlier in the
926 "<link linkend='oxygen-configuring-the-eclipse-yocto-plug-in'>Configuring the Oxygen Eclipse Yocto Plug-in</link>"
927 section.
928 The Yocto Project Settings Dialog allows you to
929 override those default settings for a given
930 project.
931 </para></listitem>
932 <listitem><para>
933 Make or verify your configurations for the
934 project and click "Apply and Close".
935 </para></listitem>
936 <listitem><para>
937 Right-click in the navigation pane and select
938 "Reconfigure Project" from the pop-up menu.
939 This selection reconfigures the project by running
940 <ulink url='https://en.wikipedia.org/wiki/GNU_Build_System'>Autotools GNU utility programs</ulink>
941 such as Autoconf, Automake, and so forth in the
942 workspace for your project.
943 Click on the "Console" tab beneath your source code
944 to see the results of reconfiguring your project.
945 </para></listitem>
946 </orderedlist>
947 </para>
948 </section>
949
950 <section id='oxygen-building-the-project'>
951 <title>Building the Project</title>
952 <para>
953 To build the project select "Build All" from the
954 "Project" menu.
955 The console should update and you can note the
956 cross-compiler you are using (i.e.
957 <filename>i586-poky-linux-gcc</filename> in this example).
958 <note>
959 When building "Yocto Project SDK Autotools" projects,
960 the Eclipse IDE might display error messages for
961 Functions/Symbols/Types that cannot be "resolved",
962 even when the related include file is listed at the
963 project navigator and when the project is able to
964 build.
965 For these cases only, it is recommended to add a new
966 linked folder to the appropriate sysroot.
967 Use these steps to add the linked folder:
968 <orderedlist>
969 <listitem><para>
970 Select the project.
971 </para></listitem>
972 <listitem><para>
973 Select "Folder" from the "File -> New" menu.
974 </para></listitem>
975 <listitem><para>
976 In the "New Folder" Dialog, click the "Advanced"
977 button and then activate "Link to
978 alternate location (linked folder)" button.
979 </para></listitem>
980 <listitem><para>
981 Click "Browse" to navigate to the include
982 folder inside the same sysroot location
983 selected in the Yocto Project
984 configuration preferences.
985 </para></listitem>
986 <listitem><para>
987 Click "Finish" to save the linked folder.
988 </para></listitem>
989 </orderedlist>
990 </note>
991 </para>
992 </section>
993
994 <section id='oxygen-starting-qemu-in-user-space-nfs-mode'>
995 <title>Starting QEMU in User-Space NFS Mode</title>
996
997 <para>
998 To start the QEMU emulator from within Eclipse, follow
999 these steps:
1000 <note>
1001 See the
1002 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
1003 chapter in the Yocto Project Development Tasks Manual
1004 for more information on using QEMU.
1005 </note>
1006 <orderedlist>
1007 <listitem><para>Expose and select "External Tools
1008 Configurations ..." from the "Run -> External
1009 Tools" menu.
1010 </para></listitem>
1011 <listitem><para>
1012 Locate and select your image in the navigation
1013 panel to the left
1014 (e.g. <filename>qemu_i586-poky-linux</filename>).
1015 </para></listitem>
1016 <listitem><para>
1017 Click "Run" to launch QEMU.
1018 <note>
1019 The host on which you are running QEMU must
1020 have the <filename>rpcbind</filename> utility
1021 running to be able to make RPC calls on a
1022 server on that machine.
1023 If QEMU does not invoke and you receive error
1024 messages involving
1025 <filename>rpcbind</filename>, follow the
1026 suggestions to get the service running.
1027 As an example, on a new Ubuntu 16.04 LTS
1028 installation, you must do the following in a new
1029 shell in order to get QEMU to launch:
1030 <literallayout class='monospaced'>
1031 $ sudo apt-get install rpcbind
1032 </literallayout>
1033 After installing <filename>rpcbind</filename>,
1034 you need to edit the
1035 <filename>/etc/init.d/rpcbind</filename> file
1036 to include the following line:
1037 <literallayout class='monospaced'>
1038 OPTIONS="-i -w"
1039 </literallayout>
1040 After modifying the file, you need to start the
1041 service:
1042 <literallayout class='monospaced'>
1043 $ sudo service portmap restart
1044 </literallayout>
1045 </note>
1046 </para></listitem>
1047 <listitem><para>
1048 If needed, enter your host root password in
1049 the shell window at the prompt.
1050 This sets up a <filename>Tap 0</filename>
1051 connection needed for running in user-space NFS
1052 mode.
1053 </para></listitem>
1054 <listitem><para>
1055 Wait for QEMU to launch.
1056 </para></listitem>
1057 <listitem><para>
1058 Once QEMU launches, you can begin operating
1059 within that environment.
1060 One useful task at this point would be to determine
1061 the IP Address for the user-space NFS by using the
1062 <filename>ifconfig</filename> command.
1063 The IP address of the QEMU machine appears in the
1064 xterm window.
1065 You can use this address to help you see which
1066 particular
1067 IP address the instance of QEMU is using.
1068 </para></listitem>
1069 </orderedlist>
1070 </para>
1071 </section>
1072
1073 <section id='oxygen-deploying-and-debugging-the-application'>
1074 <title>Deploying and Debugging the Application</title>
1075
1076 <para>
1077 Once the QEMU emulator is running the image, you can deploy
1078 your application using the Eclipse IDE and then use
1079 the emulator to perform debugging.
1080 Follow these steps to deploy the application.
1081 <note>
1082 Currently, Eclipse does not support SSH port
1083 forwarding.
1084 Consequently, if you need to run or debug a remote
1085 application using the host display, you must create a
1086 tunneling connection from outside Eclipse and keep
1087 that connection alive during your work.
1088 For example, in a new terminal, run the following:
1089 <literallayout class='monospaced'>
1090 $ ssh -XY <replaceable>user_name</replaceable>@<replaceable>remote_host_ip</replaceable>
1091 </literallayout>
1092 Using the above form, here is an example:
1093 <literallayout class='monospaced'>
1094 $ ssh -XY root@192.168.7.2
1095 </literallayout>
1096 After running the command, add the command to be
1097 executed in Eclipse's run configuration before the
1098 application as follows:
1099 <literallayout class='monospaced'>
1100 export DISPLAY=:10.0
1101 </literallayout>
1102 Be sure to not destroy the connection during your QEMU
1103 session (i.e. do not
1104 exit out of or close that shell).
1105 </note>
1106 <orderedlist>
1107 <listitem><para>
1108 Select "Debug Configurations..." from the
1109 "Run" menu.
1110 </para></listitem>
1111 <listitem><para>
1112 In the left area, expand
1113 "C/C++Remote Application".
1114 </para></listitem>
1115 <listitem><para>
1116 Locate your project and select it to bring
1117 up a new tabbed view in the Debug Configurations
1118 Dialog.
1119 </para></listitem>
1120 <listitem><para>
1121 Click on the "Debugger" tab to see the
1122 cross-tool debugger you are using.
1123 Be sure to change to the debugger perspective in
1124 Eclipse.
1125 </para></listitem>
1126 <listitem><para>
1127 Click on the "Main" tab.
1128 </para></listitem>
1129 <listitem><para>
1130 Create a new connection to the QEMU instance
1131 by clicking on "new".</para></listitem>
1132 <listitem><para>Select "SSH", which
1133 means Secure Socket Shell and then click "OK".
1134 Optionally, you can select a TCF connection
1135 instead.
1136 </para></listitem>
1137 <listitem><para>
1138 Clear out the "Connection name" field and
1139 enter any name you want for the connection.
1140 </para></listitem>
1141 <listitem><para>
1142 Put the IP address for the connection in
1143 the "Host" field.
1144 For QEMU, the default is "192.168.7.2".
1145 However, if a previous QEMU session did not exit
1146 cleanly, the IP address increments (e.g.
1147 "192.168.7.3").
1148 <note>
1149 You can find the IP address for the current
1150 QEMU session by looking in the xterm that
1151 opens when you launch QEMU.
1152 </note>
1153 </para></listitem>
1154 <listitem><para>
1155 Enter "root", which
1156 is the default for QEMU, for the "User" field.
1157 Be sure to leave the password field empty.
1158 </para></listitem>
1159 <listitem><para>
1160 Click "Finish" to close the New Connections Dialog.
1161 </para></listitem>
1162 <listitem><para>
1163 If necessary, use the drop-down menu now in the
1164 "Connection" field and pick the IP Address you
1165 entered.
1166 </para></listitem>
1167 <listitem><para>
1168 Assuming you are connecting as the root
1169 user, which is the default for QEMU x86-64 SDK
1170 images provided by the Yocto Project, in the
1171 "Remote Absolute File Path for C/C++ Application"
1172 field, browse to
1173 <filename>/home/root/</filename><replaceable>ProjectName</replaceable>
1174 (e.g. <filename>/home/root/hello</filename>).
1175 You could also browse to any other path you have
1176 write access to on the target such as
1177 <filename>/usr/bin</filename>.
1178 This location is where your application will be
1179 located on the QEMU system.
1180 If you fail to browse to and specify an appropriate
1181 location, QEMU will not understand what to remotely
1182 launch.
1183 Eclipse is helpful in that it auto fills your
1184 application name for you assuming you browsed to a
1185 directory.
1186 <note><title>Tips</title>
1187 <itemizedlist>
1188 <listitem><para>
1189 If you are prompted to provide a username
1190 and to optionally set a password, be sure
1191 you provide "root" as the username and you
1192 leave the password field blank.
1193 </para></listitem>
1194 <listitem><para>
1195 If browsing to a directory fails or times
1196 out, but you can
1197 <filename>ssh</filename> into your QEMU
1198 or target from the command line and you
1199 have proxies set up, it is likely that
1200 Eclipse is sending the SSH traffic to a
1201 proxy.
1202 In this case, either use TCF , or click on
1203 "Configure proxy settings" in the
1204 connection dialog and add the target IP
1205 address to the "bypass proxy" section.
1206 You might also need to change
1207 "Active Provider" from Native to Manual.
1208 </para></listitem>
1209 </itemizedlist>
1210 </note>
1211 </para></listitem>
1212 <listitem><para>
1213 Be sure you change to the "Debug" perspective in
1214 Eclipse.
1215 </para></listitem>
1216 <listitem><para>
1217 Click "Debug"
1218 </para></listitem>
1219 <listitem><para>
1220 Accept the debug perspective.
1221 </para></listitem>
1222 </orderedlist>
1223 </para>
1224 </section>
1225
1226 <section id='oxygen-using-Linuxtools'>
1227 <title>Using Linuxtools</title>
1228
1229 <para>
1230 As mentioned earlier in the manual, performance tools exist
1231 (Linuxtools) that enhance your development experience.
1232 These tools are aids in developing and debugging
1233 applications and images.
1234 You can run these tools from within the Eclipse IDE through
1235 the "Linuxtools" menu.
1236 </para>
1237
1238 <para>
1239 For information on how to configure and use these tools,
1240 see
1241 <ulink url='http://www.eclipse.org/linuxtools/'>http://www.eclipse.org/linuxtools/</ulink>.
1242 </para>
1243 </section>
1244 </section>
1245</chapter>
1246<!--
1247vim: expandtab tw=80 ts=4
1248-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-04-20 16:07:18 +0000