summaryrefslogtreecommitdiffstats
path: root/documentation/sdk-manual/sdk-working-projects.xml
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/sdk-manual/sdk-working-projects.xml
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/sdk-manual/sdk-working-projects.xml')
-rw-r--r--documentation/sdk-manual/sdk-working-projects.xml1210
1 files changed, 3 insertions, 1207 deletions
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-17 13:28:17 +0000