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