summaryrefslogtreecommitdiffstats
path: root/documentation/sdk-manual/sdk-eclipse-project.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/sdk-manual/sdk-eclipse-project.xml')
-rw-r--r--documentation/sdk-manual/sdk-eclipse-project.xml1248
1 files changed, 0 insertions, 1248 deletions
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-05-04 00:09:01 +0000