blob: 0fb92985a4eaf5f27c18fd8e8d49196b05ee9abc [file] [log] [blame]
Brad Bishop316dfdd2018-06-25 12:45:53 -04001<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<appendix id='sdk-appendix-neon-yp-eclipse-plug-in'>
6 <title>Using <trademark class='trade'>Eclipse</trademark> Neon</title>
7
8 <para>
9 This release of the Yocto Project supports both the Oxygen and Neon
10 versions of the Eclipse IDE.
11 This appendix presents information that describes how to obtain and
12 configure the Neon version of Eclipse.
13 It also provides a basic project example that you can work through
14 from start to finish.
15 For general information on using the Eclipse IDE and the Yocto
16 Project Eclipse Plug-In, see the
Brad Bishopd5ae7d92018-06-14 09:52:03 -070017 "<link linkend='application-development-workflow-using-eclipse'>Application Development Workflow Using <trademark class='trade'>Eclipse</trademark></link>"
18 section.
Brad Bishop316dfdd2018-06-25 12:45:53 -040019 </para>
20
21 <section id='neon-setting-up-the-eclipse-ide'>
22 <title>Setting Up the Neon Version of the Eclipse IDE</title>
23
24 <para>
25 To develop within the Eclipse IDE, you need to do the following:
26 <orderedlist>
27 <listitem><para>Install the Neon version of the Eclipse
28 IDE.</para></listitem>
29 <listitem><para>Configure the Eclipse IDE.
30 </para></listitem>
31 <listitem><para>Install the Eclipse Yocto Plug-in.
32 </para></listitem>
33 <listitem><para>Configure the Eclipse Yocto Plug-in.
34 </para></listitem>
35 </orderedlist>
36 <note>
37 Do not install Eclipse from your distribution's package
38 repository.
39 Be sure to install Eclipse from the official Eclipse
40 download site as directed in the next section.
41 </note>
42 </para>
43
44 <section id='neon-installing-eclipse-ide'>
45 <title>Installing the Neon Eclipse IDE</title>
46
47 <para>
48 Follow these steps to locate, install, and configure
49 Neon Eclipse:
50 <orderedlist>
51 <listitem><para><emphasis>Locate the Neon Download:</emphasis>
52 Open a browser and go to
53 <ulink url='http://www.eclipse.org/neon/'>http://www.eclipse.org/neon/</ulink>.
54 </para></listitem>
55 <listitem><para><emphasis>Download the Tarball:</emphasis>
Brad Bishopd5ae7d92018-06-14 09:52:03 -070056 Click the "Download" button and look for the
57 "Eclipse IDE for C/C++ Developers" Neon 3 Package.
58 Select the correct platform download link listed at
59 the right.
60 For example, click on "64-bit" next to Linux if your
61 build host is running a 64-bit Linux distribution.
62 Click through the process to save the file.
Brad Bishop316dfdd2018-06-25 12:45:53 -040063 </para></listitem>
64 <listitem><para><emphasis>Unpack the Tarball:</emphasis>
Brad Bishopd5ae7d92018-06-14 09:52:03 -070065 Move to a directory and unpack the tarball.
66 The following commands unpack the tarball into the
67 home directory:
Brad Bishop316dfdd2018-06-25 12:45:53 -040068 <literallayout class='monospaced'>
69 $ cd ~
70 $ tar -xzvf ~/Downloads/eclipse-cpp-neon-3-linux-gtk-x86_64.tar.gz
71 </literallayout>
72 Everything unpacks into a folder named "Eclipse".
73 </para></listitem>
74 <listitem><para><emphasis>Launch Eclipse:</emphasis>
75 The following commands launch Eclipse assuming you
76 unpacked it in your home directory:
77 <literallayout class='monospaced'>
78 $ cd ~/eclipse
79 $ ./eclipse
80 </literallayout>
81 Accept the default "workspace" once Eclipse launches.
82 </para></listitem>
83 </orderedlist>
84 </para>
85 </section>
86
87 <section id='neon-configuring-the-neon-eclipse-ide'>
88 <title>Configuring the Neon Eclipse IDE</title>
89
90 <para>
91 Follow these steps to configure the Neon Eclipse IDE.
Brad Bishopd5ae7d92018-06-14 09:52:03 -070092 <note><title>Notes</title>
93 <itemizedlist>
94 <listitem><para>
95 Depending on how you installed Eclipse and what
96 you have already done, some of the options do
97 not appear.
98 If you cannot find an option as directed by the
99 manual, it has already been installed.
100 </para></listitem>
101 <listitem><para>
102 If you want to see all options regardless of
103 whether they are installed or not, deselect the
104 "Hide items that are already installed"
105 check box.
106 </para></listitem>
107 </itemizedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400108 </note>
109 <orderedlist>
110 <listitem><para>Be sure Eclipse is running and
111 you are in your workbench.
112 </para></listitem>
113 <listitem><para>Select "Install New Software" from
114 the "Help" pull-down menu.
115 </para></listitem>
116 <listitem><para>Select
117 "Neon - http://download.eclipse.org/releases/neon"
118 from the "Work with:" pull-down menu.
119 </para></listitem>
120 <listitem><para>Expand the box next to
121 "Linux Tools" and select the following
122 <literallayout class='monospaced'>
123 C/C++ Remote (Over TCF/TE) Run/Debug Launcher
124 TM Terminal
125 </literallayout>
126 </para></listitem>
127 <listitem><para>Expand the box next to "Mobile and
128 Device Development" and select the following
129 boxes:
130 <literallayout class='monospaced'>
131 C/C++ Remote (Over TCF/TE) Run/Debug Launcher
132 Remote System Explorer User Actions
133 TM Terminal
134 TCF Remote System Explorer add-in
135 TCF Target Explorer
136 </literallayout>
137 </para></listitem>
138 <listitem><para>Expand the box next to
139 "Programming Languages" and select the
140 following box:
141 <literallayout class='monospaced'>
142 C/C++ Development Tools SDK
143 </literallayout>
144 </para></listitem>
145 <listitem><para>
146 Complete the installation by clicking through
147 appropriate "Next" and "Finish" buttons.
148 </para></listitem>
149 </orderedlist>
150 </para>
151 </section>
152
153 <section id='neon-installing-the-eclipse-yocto-plug-in'>
154 <title>Installing or Accessing the Neon Eclipse Yocto Plug-in</title>
155
156 <para>
157 You can install the Eclipse Yocto Plug-in into the Eclipse
158 IDE one of two ways: use the Yocto Project's Eclipse
159 Update site to install the pre-built plug-in or build and
160 install the plug-in from the latest source code.
161 </para>
162
163 <section id='neon-new-software'>
164 <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title>
165
166 <para>
167 To install the Neon Eclipse Yocto Plug-in from the update
168 site, follow these steps:
169 <orderedlist>
170 <listitem><para>Start up the Eclipse IDE.
171 </para></listitem>
172 <listitem><para>In Eclipse, select "Install New
173 Software" from the "Help" menu.
174 </para></listitem>
175 <listitem><para>Click "Add..." in the "Work with:"
176 area.
177 </para></listitem>
178 <listitem><para>Enter
179 <filename>&ECLIPSE_DL_PLUGIN_URL;/neon</filename>
180 in the URL field and provide a meaningful name
181 in the "Name" field.
182 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700183 <listitem><para>
184 Click "OK" to have the entry automatically
185 populate the "Work with:" field and to have
186 the items for installation appear in the window
187 below.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400188 </para></listitem>
189 <listitem><para>Check the boxes next to the following:
190 <literallayout class='monospaced'>
191 Yocto Project SDK Plug-in
192 Yocto Project Documentation plug-in
193 </literallayout>
194 </para></listitem>
195 <listitem><para>Complete the remaining software
196 installation steps and then restart the Eclipse
197 IDE to finish the installation of the plug-in.
198 <note>
199 You can click "OK" when prompted about
200 installing software that contains unsigned
201 content.
202 </note>
203 </para></listitem>
204 </orderedlist>
205 </para>
206 </section>
207
208 <section id='neon-zip-file-method'>
209 <title>Installing the Plug-in Using the Latest Source Code</title>
210
211 <para>
212 To install the Neon Eclipse Yocto Plug-in from the latest
213 source code, follow these steps:
214 <orderedlist>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700215 <listitem><para>
216 Be sure your build host has JDK version 1.8
217 or greater.
218 On a Linux build host you can determine the
219 version using the following command:
220 <literallayout class='monospaced'>
221 $ java -version
222 </literallayout>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400223 </para></listitem>
224 <listitem><para>install X11-related packages:
225 <literallayout class='monospaced'>
226 $ sudo apt-get install xauth
227 </literallayout>
228 </para></listitem>
229 <listitem><para>In a new terminal shell, create a Git
230 repository with:
231 <literallayout class='monospaced'>
232 $ cd ~
233 $ git clone git://git.yoctoproject.org/eclipse-yocto
234 </literallayout>
235 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700236 <listitem><para>
237 Use Git to create the correct tag:
Brad Bishop316dfdd2018-06-25 12:45:53 -0400238 <literallayout class='monospaced'>
239 $ cd ~/eclipse-yocto
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700240 $ git checkout -b neon/&DISTRO_NAME_NO_CAP; remotes/origin/neon/&DISTRO_NAME_NO_CAP;
Brad Bishop316dfdd2018-06-25 12:45:53 -0400241 </literallayout>
242 This creates a local tag named
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700243 <filename>neon/&DISTRO_NAME_NO_CAP;</filename>
244 based on the branch
245 <filename>origin/neon/&DISTRO_NAME_NO_CAP;</filename>.
246 You are put into a detached HEAD state,
247 which is fine since you are only going to
248 be building and not developing.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400249 </para></listitem>
250 <listitem><para>Change to the
251 <filename>scripts</filename>
252 directory within the Git repository:
253 <literallayout class='monospaced'>
254 $ cd scripts
255 </literallayout>
256 </para></listitem>
257 <listitem><para>Set up the local build environment
258 by running the setup script:
259 <literallayout class='monospaced'>
260 $ ./setup.sh
261 </literallayout>
262 When the script finishes execution,
263 it prompts you with instructions on how to run
264 the <filename>build.sh</filename> script, which
265 is also in the <filename>scripts</filename>
266 directory of the Git repository created
267 earlier.
268 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700269 <listitem><para>
270 Run the <filename>build.sh</filename>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400271 script as directed.
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700272 Be sure to provide the tag name,
273 documentation branch, and a release name.</para>
274
275 <para>Following is an example:
Brad Bishop316dfdd2018-06-25 12:45:53 -0400276 <literallayout class='monospaced'>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700277 $ ECLIPSE_HOME=/home/scottrif/eclipse-yocto/scripts/eclipse ./build.sh -l neon/&DISTRO_NAME_NO_CAP; master yocto-&DISTRO; 2>&amp;1 | tee build.log
Brad Bishop316dfdd2018-06-25 12:45:53 -0400278 </literallayout>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700279 The previous example command adds the tag
280 you need for
281 <filename>neon/&DISTRO_NAME_NO_CAP;</filename>
282 to <filename>HEAD</filename>, then tells
283 the build script to use the local (-l) Git
284 checkout for the build.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400285 After running the script, the file
286 <filename>org.yocto.sdk-</filename><replaceable>release</replaceable><filename>-</filename><replaceable>date</replaceable><filename>-archive.zip</filename>
287 is in the current directory.
288 </para></listitem>
289 <listitem><para>If necessary, start the Eclipse IDE
290 and be sure you are in the Workbench.
291 </para></listitem>
292 <listitem><para>Select "Install New Software" from
293 the "Help" pull-down menu.
294 </para></listitem>
295 <listitem><para>Click "Add".
296 </para></listitem>
297 <listitem><para>Provide anything you want in the
298 "Name" field.
299 </para></listitem>
300 <listitem><para>Click "Archive" and browse to the
301 ZIP file you built earlier.
302 This ZIP file should not be "unzipped", and must
303 be the <filename>*archive.zip</filename> file
304 created by running the
305 <filename>build.sh</filename> script.
306 </para></listitem>
307 <listitem><para>Click the "OK" button.
308 </para></listitem>
309 <listitem><para>Check the boxes that appear in
310 the installation window to install the
311 following:
312 <literallayout class='monospaced'>
313 Yocto Project SDK Plug-in
314 Yocto Project Documentation plug-in
315 </literallayout>
316 </para></listitem>
317 <listitem><para>Finish the installation by clicking
318 through the appropriate buttons.
319 You can click "OK" when prompted about
320 installing software that contains unsigned
321 content.
322 </para></listitem>
323 <listitem><para>Restart the Eclipse IDE if
324 necessary.
325 </para></listitem>
326 </orderedlist>
327 </para>
328
329 <para>
330 At this point you should be able to configure the
331 Eclipse Yocto Plug-in as described in the
332 "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>"
333 section.</para>
334 </section>
335 </section>
336
337 <section id='neon-configuring-the-eclipse-yocto-plug-in'>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700338 <title>Configuring the Neon Eclipse Yocto Plug-In</title>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400339
340 <para>
341 Configuring the Neon Eclipse Yocto Plug-in involves setting the
342 Cross Compiler options and the Target options.
343 The configurations you choose become the default settings
344 for all projects.
345 You do have opportunities to change them later when
346 you configure the project (see the following section).
347 </para>
348
349 <para>
350 To start, you need to do the following from within the
351 Eclipse IDE:
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700352 <orderedlist>
353 <listitem><para>
354 Choose "Preferences" from the
Brad Bishop316dfdd2018-06-25 12:45:53 -0400355 "Window" menu to display the Preferences Dialog.
356 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700357 <listitem><para>
358 Click "Yocto Project SDK" to display
Brad Bishop316dfdd2018-06-25 12:45:53 -0400359 the configuration screen.
360 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700361 </orderedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400362 The following sub-sections describe how to configure the
363 the plug-in.
364 <note>
365 Throughout the descriptions, a start-to-finish example for
366 preparing a QEMU image for use with Eclipse is referenced
367 as the "wiki" and is linked to the example on the
368 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'> Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
369 wiki page.
370 </note>
371 </para>
372
373 <section id='neon-configuring-the-cross-compiler-options'>
374 <title>Configuring the Cross-Compiler Options</title>
375
376 <para>
377 Cross Compiler options enable Eclipse to use your specific
378 cross compiler toolchain.
379 To configure these options, you must select
380 the type of toolchain, point to the toolchain, specify
381 the sysroot location, and select the target
382 architecture.
383 <itemizedlist>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700384 <listitem><para>
385 <emphasis>Selecting the Toolchain Type:</emphasis>
386 Choose between "Standalone pre-built toolchain"
Brad Bishop316dfdd2018-06-25 12:45:53 -0400387 and
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700388 "Build system derived toolchain" for Cross Compiler
389 Options.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400390 <itemizedlist>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700391 <listitem><para>
392 <emphasis>Standalone Pre-built Toolchain:</emphasis>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400393 Select this type when you are using
394 a stand-alone cross-toolchain.
395 For example, suppose you are an
396 application developer and do not
397 need to build a target image.
398 Instead, you just want to use an
399 architecture-specific toolchain on
400 an existing kernel and target root
401 filesystem.
402 In other words, you have downloaded
403 and installed a pre-built toolchain
404 for an existing image.
405 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700406 <listitem><para>
407 <emphasis>Build System Derived Toolchain:</emphasis>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400408 Select this type if you built the
409 toolchain as part of the
410 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700411 When you select "Build system derived
412 toolchain", you are using the toolchain
413 built and bundled inside the Build
414 Directory.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400415 For example, suppose you created a
416 suitable image using the steps in the
417 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700418 In this situation, you would select
419 "Build system derived toolchain".
Brad Bishop316dfdd2018-06-25 12:45:53 -0400420 </para></listitem>
421 </itemizedlist>
422 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700423 <listitem><para>
424 <emphasis>Specify the Toolchain Root Location:</emphasis>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400425 If you are using a stand-alone pre-built
426 toolchain, you should be pointing to where it is
427 installed (e.g.
428 <filename>/opt/poky/&DISTRO;</filename>).
429 See the
430 "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
431 section for information about how the SDK is
432 installed.</para>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700433
Brad Bishop316dfdd2018-06-25 12:45:53 -0400434 <para>If you are using a build system derived
435 toolchain, the path you provide for the
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700436 "Toolchain Root Location" field is the
Brad Bishop316dfdd2018-06-25 12:45:53 -0400437 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
438 from which you run the
439 <filename>bitbake</filename> command (e.g
440 <filename>/home/scottrif/poky/build</filename>).</para>
441 <para>For more information, see the
442 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
443 section.
444 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700445 <listitem><para>
446 <emphasis>Specify Sysroot Location:</emphasis>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400447 This location is where the root filesystem for
448 the target hardware resides.
449 </para>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700450
Brad Bishop316dfdd2018-06-25 12:45:53 -0400451 <para>This location depends on where you
452 separately extracted and installed the
453 target filesystem when you either built
454 it or downloaded it.
455 <note>
456 If you downloaded the root filesystem
457 for the target hardware rather than
458 built it, you must download the
459 <filename>sato-sdk</filename> image
460 in order to build any c/c++ projects.
461 </note>
462 As an example, suppose you prepared an image
463 using the steps in the
464 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
465 If so, the <filename>MY_QEMU_ROOTFS</filename>
466 directory is found in the
467 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
468 and you would browse to and select that directory
469 (e.g. <filename>/home/scottrif/build/MY_QEMU_ROOTFS</filename>).
470 </para>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700471
Brad Bishop316dfdd2018-06-25 12:45:53 -0400472 <para>For more information on how to install the
473 toolchain and on how to extract and install the
474 sysroot filesystem, see the
475 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
476 section.
477 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700478 <listitem><para>
479 <emphasis>Select the Target Architecture:</emphasis>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400480 The target architecture is the type of hardware
481 you are going to use or emulate.
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700482 Use the pull-down "Target Architecture" menu
Brad Bishop316dfdd2018-06-25 12:45:53 -0400483 to make your selection.
484 The pull-down menu should have the supported
485 architectures.
486 If the architecture you need is not listed in
487 the menu, you will need to build the image.
488 See the
489 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-building-a-simple-image'>Building a Simple Image</ulink>"
490 section of the Yocto Project Development Tasks
491 Manual for more information.
492 You can also see the
493 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
494 </para></listitem>
495 </itemizedlist>
496 </para>
497 </section>
498
499 <section id='neon-configuring-the-target-options'>
500 <title>Configuring the Target Options</title>
501
502 <para>
503 You can choose to emulate hardware using the QEMU
504 emulator, or you can choose to run your image on actual
505 hardware.
506 <itemizedlist>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700507 <listitem><para>
508 <emphasis>QEMU:</emphasis>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400509 Select this option if you will be using the
510 QEMU emulator.
511 If you are using the emulator, you also need to
512 locate the kernel and specify any custom
513 options.</para>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700514
515 <para>If you selected the Build system derived
516 toolchain, the target kernel you built will be
517 located in the
Brad Bishop316dfdd2018-06-25 12:45:53 -0400518 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
519 in
520 <filename>tmp/deploy/images/<replaceable>machine</replaceable></filename>
521 directory.
522 As an example, suppose you performed the steps in
523 the
524 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
525 In this case, you specify your Build Directory path
526 followed by the image (e.g.
527 <filename>/home/scottrif/poky/build/tmp/deploy/images/qemux86/bzImage-qemux86.bin</filename>).
528 </para>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700529
Brad Bishop316dfdd2018-06-25 12:45:53 -0400530 <para>If you selected the standalone pre-built
531 toolchain, the pre-built image you downloaded is
532 located in the directory you specified when you
533 downloaded the image.</para>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700534
Brad Bishop316dfdd2018-06-25 12:45:53 -0400535 <para>Most custom options are for advanced QEMU
536 users to further customize their QEMU instance.
537 These options are specified between paired
538 angled brackets.
539 Some options must be specified outside the
540 brackets.
541 In particular, the options
542 <filename>serial</filename>,
543 <filename>nographic</filename>, and
544 <filename>kvm</filename> must all be outside the
545 brackets.
546 Use the <filename>man qemu</filename> command
547 to get help on all the options and their use.
548 The following is an example:
549 <literallayout class='monospaced'>
550 serial ‘&lt;-m 256 -full-screen&gt;’
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700551 </literallayout>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400552 Regardless of the mode, Sysroot is already
553 defined as part of the Cross-Compiler Options
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700554 configuration in the "Sysroot Location:" field.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400555 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700556 <listitem><para>
557 <emphasis>External HW:</emphasis>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400558 Select this option if you will be using actual
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700559 hardware.
560 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400561 </itemizedlist>
562 </para>
563
564 <para>
565 Click the "Apply" and "OK" to save your plug-in
566 configurations.
567 </para>
568 </section>
569 </section>
570 </section>
571
572 <section id='neon-creating-the-project'>
573 <title>Creating the Project</title>
574
575 <para>
576 You can create two types of projects: Autotools-based, or
577 Makefile-based.
578 This section describes how to create Autotools-based projects
579 from within the Eclipse IDE.
580 For information on creating Makefile-based projects in a
581 terminal window, see the
582 "<link linkend='makefile-based-projects'>Makefile-Based Projects</link>"
583 section.
584 <note>
585 Do not use special characters in project names
586 (e.g. spaces, underscores, etc.). Doing so can
587 cause the configuration to fail.
588 </note>
589 </para>
590
591 <para>
592 To create a project based on a Yocto template and then display
593 the source code, follow these steps:
594 <orderedlist>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700595 <listitem><para>
596 Select "C Project" from the "File -> New" menu.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400597 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700598 <listitem><para>
599 Expand "Yocto Project SDK Autotools Project".
Brad Bishop316dfdd2018-06-25 12:45:53 -0400600 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700601 <listitem><para>
602 Select "Hello World ANSI C Autotools Projects".
Brad Bishop316dfdd2018-06-25 12:45:53 -0400603 This is an Autotools-based project based on a Yocto
604 template.
605 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700606 <listitem><para>
607 Put a name in the "Project name:" field.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400608 Do not use hyphens as part of the name
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700609 (e.g. "hello").
Brad Bishop316dfdd2018-06-25 12:45:53 -0400610 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700611 <listitem><para>
612 Click "Next".
Brad Bishop316dfdd2018-06-25 12:45:53 -0400613 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700614 <listitem><para>
615 Add appropriate information in the various fields.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400616 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700617 <listitem><para>
618 Click "Finish".
Brad Bishop316dfdd2018-06-25 12:45:53 -0400619 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700620 <listitem><para>
621 If the "open perspective" prompt appears,
Brad Bishop316dfdd2018-06-25 12:45:53 -0400622 click "Yes" so that you are in the C/C++ perspective.
623 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700624 <listitem><para>
625 The left-hand navigation pane shows your project.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400626 You can display your source by double clicking the
627 project's source file.
628 </para></listitem>
629 </orderedlist>
630 </para>
631 </section>
632
633 <section id='neon-configuring-the-cross-toolchains'>
634 <title>Configuring the Cross-Toolchains</title>
635
636 <para>
637 The earlier section,
638 "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>",
639 sets up the default project configurations.
640 You can override these settings for a given project by following
641 these steps:
642 <orderedlist>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700643 <listitem><para>
644 Select "Yocto Project Settings" from
Brad Bishop316dfdd2018-06-25 12:45:53 -0400645 the "Project -> Properties" menu.
646 This selection brings up the Yocto Project Settings
647 Dialog and allows you to make changes specific to an
648 individual project.</para>
649 <para>By default, the Cross Compiler Options and Target
650 Options for a project are inherited from settings you
651 provided using the Preferences Dialog as described
652 earlier in the
653 "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>" section.
654 The Yocto Project Settings Dialog allows you to override
655 those default settings for a given project.
656 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700657 <listitem><para>
658 Make or verify your configurations for the project and
659 click "OK".
Brad Bishop316dfdd2018-06-25 12:45:53 -0400660 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700661 <listitem><para>
662 Right-click in the navigation pane and select
663 "Reconfigure Project" from the pop-up menu.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400664 This selection reconfigures the project by running
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700665 <ulink url='https://en.wikipedia.org/wiki/GNU_Build_System'>Autotools GNU utility programs</ulink>
666 such as Autoconf, Automake, and so forth in the
667 workspace for your project.
668 Click on the "Console" tab beneath your source code
669 to see the results of reconfiguring your project.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400670 </para></listitem>
671 </orderedlist>
672 </para>
673 </section>
674
675 <section id='neon-building-the-project'>
676 <title>Building the Project</title>
677
678 <para>
679 To build the project select "Build All" from the
680 "Project" menu.
681 The console should update and you can note the cross-compiler
682 you are using.
683 <note>
684 When building "Yocto Project SDK Autotools" projects, the
685 Eclipse IDE might display error messages for
686 Functions/Symbols/Types that cannot be "resolved", even when
687 the related include file is listed at the project navigator and
688 when the project is able to build.
689 For these cases only, it is recommended to add a new linked
690 folder to the appropriate sysroot.
691 Use these steps to add the linked folder:
692 <orderedlist>
693 <listitem><para>
694 Select the project.
695 </para></listitem>
696 <listitem><para>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700697 Select "Folder" from the "File > New" menu.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400698 </para></listitem>
699 <listitem><para>
700 In the "New Folder" Dialog, select "Link to alternate
701 location (linked folder)".
702 </para></listitem>
703 <listitem><para>
704 Click "Browse" to navigate to the include folder inside
705 the same sysroot location selected in the Yocto Project
706 configuration preferences.
707 </para></listitem>
708 <listitem><para>
709 Click "OK".
710 </para></listitem>
711 <listitem><para>
712 Click "Finish" to save the linked folder.
713 </para></listitem>
714 </orderedlist>
715 </note>
716 </para>
717 </section>
718
719 <section id='neon-starting-qemu-in-user-space-nfs-mode'>
720 <title>Starting QEMU in User-Space NFS Mode</title>
721
722 <para>
723 To start the QEMU emulator from within Eclipse, follow these
724 steps:
725 <note>
726 See the
727 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
728 chapter in the Yocto Project Development Tasks Manual
729 for more information on using QEMU.
730 </note>
731 <orderedlist>
732 <listitem><para>Expose and select "External Tools
733 Configurations ..." from the "Run -> External Tools" menu.
734 </para></listitem>
735 <listitem><para>
736 Locate and select your image in the navigation panel to
737 the left (e.g. <filename>qemu_i586-poky-linux</filename>).
738 </para></listitem>
739 <listitem><para>
740 Click "Run" to launch QEMU.
741 <note>
742 The host on which you are running QEMU must have
743 the <filename>rpcbind</filename> utility running to be
744 able to make RPC calls on a server on that machine.
745 If QEMU does not invoke and you receive error messages
746 involving <filename>rpcbind</filename>, follow the
747 suggestions to get the service running.
748 As an example, on a new Ubuntu 16.04 LTS installation,
749 you must do the following in order to get QEMU to
750 launch:
751 <literallayout class='monospaced'>
752 $ sudo apt-get install rpcbind
753 </literallayout>
754 After installing <filename>rpcbind</filename>, you
755 need to edit the
756 <filename>/etc/init.d/rpcbind</filename> file to
757 include the following line:
758 <literallayout class='monospaced'>
759 OPTIONS="-i -w"
760 </literallayout>
761 After modifying the file, you need to start the
762 service:
763 <literallayout class='monospaced'>
764 $ sudo service portmap restart
765 </literallayout>
766 </note>
767 </para></listitem>
768 <listitem><para>If needed, enter your host root password in
769 the shell window at the prompt.
770 This sets up a <filename>Tap 0</filename> connection
771 needed for running in user-space NFS mode.
772 </para></listitem>
773 <listitem><para>Wait for QEMU to launch.
774 </para></listitem>
775 <listitem><para>Once QEMU launches, you can begin operating
776 within that environment.
777 One useful task at this point would be to determine the
778 IP Address for the user-space NFS by using the
779 <filename>ifconfig</filename> command.
780 The IP address of the QEMU machine appears in the
781 xterm window.
782 You can use this address to help you see which particular
783 IP address the instance of QEMU is using.
784 </para></listitem>
785 </orderedlist>
786 </para>
787 </section>
788
789 <section id='neon-deploying-and-debugging-the-application'>
790 <title>Deploying and Debugging the Application</title>
791
792 <para>
793 Once the QEMU emulator is running the image, you can deploy
794 your application using the Eclipse IDE and then use
795 the emulator to perform debugging.
796 Follow these steps to deploy the application.
797 <note>
798 Currently, Eclipse does not support SSH port forwarding.
799 Consequently, if you need to run or debug a remote
800 application using the host display, you must create a
801 tunneling connection from outside Eclipse and keep
802 that connection alive during your work.
803 For example, in a new terminal, run the following:
804 <literallayout class='monospaced'>
805 $ ssh -XY <replaceable>user_name</replaceable>@<replaceable>remote_host_ip</replaceable>
806 </literallayout>
807 Using the above form, here is an example:
808 <literallayout class='monospaced'>
809 $ ssh -XY root@192.168.7.2
810 </literallayout>
811 After running the command, add the command to be executed
812 in Eclipse's run configuration before the application
813 as follows:
814 <literallayout class='monospaced'>
815 export DISPLAY=:10.0
816 </literallayout>
817 Be sure to not destroy the connection during your QEMU
818 session (i.e. do not
819 exit out of or close that shell).
820 </note>
821 <orderedlist>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700822 <listitem><para>
823 Select "Debug Configurations..." from the
Brad Bishop316dfdd2018-06-25 12:45:53 -0400824 "Run" menu.</para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700825 <listitem><para>
826 In the left area, expand
827 "C/C++Remote Application".
Brad Bishop316dfdd2018-06-25 12:45:53 -0400828 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700829 <listitem><para>
830 Locate your project and select it to bring
Brad Bishop316dfdd2018-06-25 12:45:53 -0400831 up a new tabbed view in the Debug Configurations Dialog.
832 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700833 <listitem><para>
834 Click on the "Debugger" tab to see the
Brad Bishop316dfdd2018-06-25 12:45:53 -0400835 cross-tool debugger you are using.
836 Be sure to change to the debugger perspective in Eclipse.
837 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700838 <listitem><para>
839 Click on the "Main" tab.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400840 </para></listitem>
841 <listitem><para>Create a new connection to the QEMU instance
842 by clicking on "new".</para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700843 <listitem><para>
844 Select "SSH", which means
Brad Bishop316dfdd2018-06-25 12:45:53 -0400845 Secure Socket Shell.
846 Optionally, you can select a TCF connection instead.
847 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700848 <listitem><para>
849 Click "Next".
Brad Bishop316dfdd2018-06-25 12:45:53 -0400850 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700851 <listitem><para>
852 Clear out the "Connection name" field and
Brad Bishop316dfdd2018-06-25 12:45:53 -0400853 enter any name you want for the connection.
854 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700855 <listitem><para>
856 Put the IP address for the connection in
Brad Bishop316dfdd2018-06-25 12:45:53 -0400857 the "Host" field.
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700858 For QEMU, the default is "192.168.7.2".
Brad Bishop316dfdd2018-06-25 12:45:53 -0400859 However, if a previous QEMU session did not exit
860 cleanly, the IP address increments (e.g.
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700861 "192.168.7.3").
Brad Bishop316dfdd2018-06-25 12:45:53 -0400862 <note>
863 You can find the IP address for the current QEMU
864 session by looking in the xterm that opens when
865 you launch QEMU.
866 </note>
867 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700868 <listitem><para>
869 Enter "root", which
Brad Bishop316dfdd2018-06-25 12:45:53 -0400870 is the default for QEMU, for the "User" field.
871 Be sure to leave the password field empty.
872 </para></listitem>
873 <listitem><para>Click "Finish" to close the
874 New Connections Dialog.
875 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700876 <listitem><para>
877 If necessary, use the drop-down menu now in the
Brad Bishop316dfdd2018-06-25 12:45:53 -0400878 "Connection" field and pick the IP Address you entered.
879 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700880 <listitem><para>
881 Assuming you are connecting as the root user,
Brad Bishop316dfdd2018-06-25 12:45:53 -0400882 which is the default for QEMU x86-64 SDK images provided by
883 the Yocto Project, in the "Remote Absolute File Path for
884 C/C++ Application" field, browse to
885 <filename>/home/root/</filename><replaceable>ProjectName</replaceable>
886 (e.g. <filename>/home/root/hello</filename>).
887 You could also browse to any other path you have write
888 access to on the target such as
889 <filename>/usr/bin</filename>.
890 This location is where your application will be located on
891 the QEMU system.
892 If you fail to browse to and specify an appropriate
893 location, QEMU will not understand what to remotely
894 launch.
895 Eclipse is helpful in that it auto fills your application
896 name for you assuming you browsed to a directory.
897 <note><title>Tips</title>
898 <itemizedlist>
899 <listitem><para>
900 If you are prompted to provide a username
901 and to optionally set a password, be sure
902 you provide "root" as the username and you
903 leave the password field blank.
904 </para></listitem>
905 <listitem><para>
906 If browsing to a directory fails or times
907 out, but you can
908 <filename>ssh</filename> into your QEMU
909 or target from the command line and you
910 have proxies set up, it is likely that
911 Eclipse is sending the SSH traffic to a
912 proxy.
913 In this case, either use TCF , or click on
914 "Configure proxy settings" in the
915 connection dialog and add the target IP
916 address to the "bypass proxy" section.
917 You might also need to change
918 "Active Provider" from Native to Manual.
919 </para></listitem>
920 </itemizedlist>
921 </note>
922 </para></listitem>
923 <listitem><para>
924 Be sure you change to the "Debug" perspective in Eclipse.
925 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700926 <listitem><para>
927 Click "Debug"
Brad Bishop316dfdd2018-06-25 12:45:53 -0400928 </para></listitem>
Brad Bishopd5ae7d92018-06-14 09:52:03 -0700929 <listitem><para>
930 Accept the debug perspective.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400931 </para></listitem>
932 </orderedlist>
933 </para>
934 </section>
935
936 <section id='neon-using-Linuxtools'>
937 <title>Using Linuxtools</title>
938
939 <para>
940 As mentioned earlier in the manual, performance tools exist
941 (Linuxtools) that enhance your development experience.
942 These tools are aids in developing and debugging applications and
943 images.
944 You can run these tools from within the Eclipse IDE through the
945 "Linuxtools" menu.
946 </para>
947
948 <para>
949 For information on how to configure and use these tools, see
950 <ulink url='http://www.eclipse.org/linuxtools/'>http://www.eclipse.org/linuxtools/</ulink>.
951 </para>
952 </section>
953</appendix>
954<!--
955vim: expandtab tw=80 ts=4
956-->