summaryrefslogtreecommitdiffstats
path: root/documentation/sdk-manual
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2016-03-09 13:30:27 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2016-03-23 21:56:08 +0000
commit4c5157f7dcfecab3b4e4483cd122e0ae74b377ee (patch)
tree03c0812d79db78ebfd454b540338b66e2dc20521 /documentation/sdk-manual
parent4306f7f97a2ea05ebf141947294729584795d832 (diff)
downloadpoky-4c5157f7dcfecab3b4e4483cd122e0ae74b377ee.tar.gz
ref-manual: Resolving a conflict
(From yocto-docs rev: b364516928d04da38ef3188f07f190ffac64762b) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/sdk-manual')
-rw-r--r--documentation/sdk-manual/sdk-intro.xml58
-rw-r--r--documentation/sdk-manual/sdk-using.xml1053
2 files changed, 1102 insertions, 9 deletions
diff --git a/documentation/sdk-manual/sdk-intro.xml b/documentation/sdk-manual/sdk-intro.xml
index 5b12fcff64..ccc71c8cf4 100644
--- a/documentation/sdk-manual/sdk-intro.xml
+++ b/documentation/sdk-manual/sdk-intro.xml
@@ -14,6 +14,9 @@
14 This manual provides information that lets you use both the standard 14 This manual provides information that lets you use both the standard
15 Yocto Project SDK and an extensible SDK to develop applications and 15 Yocto Project SDK and an extensible SDK to develop applications and
16 images using the Yocto Project. 16 images using the Yocto Project.
17 Additionally, the manual also provides information on how to use
18 the popular <trademark class='trade'>Eclipse</trademark> IDE as part
19 of your application development workflow.
17 </para> 20 </para>
18 21
19 <para> 22 <para>
@@ -64,6 +67,61 @@
64 </para> 67 </para>
65 68
66 <para> 69 <para>
70 You just need to follow these general steps:
71 <orderedlist>
72 <listitem><para><emphasis>Install the SDK for your target hardware:</emphasis>
73 For information on how to install the SDK, see the
74 "<link url='sdk-installing-the-sdk'>Installing the SDK</link>"
75 section.</para></listitem>
76 <listitem><para><emphasis>Download the Target Image:</emphasis>
77 The Yocto Project supports several target architectures
78 and has many pre-built kernel images and root filesystem
79 images.</para>
80 <para>If you are going to develop your application on
81 hardware, go to the
82 <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink>
83 download area and choose a target machine area
84 from which to download the kernel image and root filesystem.
85 This download area could have several files in it that
86 support development using actual hardware.
87 For example, the area might contain
88 <filename>.hddimg</filename> files that combine the
89 kernel image with the filesystem, boot loaders, and
90 so forth.
91 Be sure to get the files you need for your particular
92 development process.</para>
93 <para>If you are going to develop your application and
94 then run and test it using the QEMU emulator, go to the
95 <ulink url='&YOCTO_QEMU_DL_URL;'><filename>machines/qemu</filename></ulink>
96 download area.
97 From this area, go down into the directory for your
98 target architecture (e.g. <filename>qemux86_64</filename>
99 for an <trademark class='registered'>Intel</trademark>-based
100 64-bit architecture).
101 Download kernel, root filesystem, and any other files you
102 need for your process.
103 <note>In order to use the root filesystem in QEMU, you
104 need to extract it.
105 See the
106 "<link url='sdk-extracting-the-root-filesystem'>Extracting the Root Filesystem</link>"
107 section for information on how to extract the root
108 filesystem.</note></para></listitem>
109 <listitem><para><emphasis>Develop and Test your
110 Application:</emphasis> At this point, you have the tools
111 to develop your application.
112 If you need to separately install and use the QEMU
113 emulator, you can go to
114 <ulink url='http://wiki.qemu.org/Main_Page'>QEMU Home Page</ulink>
115 to download and learn about the emulator.
116 You can see the
117 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
118 chapter in the Yocto Project Development Manual
119 for information on using QEMU within the Yocto
120 Project.</para></listitem>
121 </orderedlist>
122 </para>
123
124 <para>
67 The remainder of this manual describes how to use both the standard 125 The remainder of this manual describes how to use both the standard
68 SDK and the extensible SDK. 126 SDK and the extensible SDK.
69 Information also exists in appendix form that describes how you can 127 Information also exists in appendix form that describes how you can
diff --git a/documentation/sdk-manual/sdk-using.xml b/documentation/sdk-manual/sdk-using.xml
index f2acaa7fc4..1403632db1 100644
--- a/documentation/sdk-manual/sdk-using.xml
+++ b/documentation/sdk-manual/sdk-using.xml
@@ -273,7 +273,7 @@
273 <listitem><para><emphasis>Source the cross-toolchain 273 <listitem><para><emphasis>Source the cross-toolchain
274 environment setup file:</emphasis> 274 environment setup file:</emphasis>
275 Installation of the cross-toolchain creates a cross-toolchain 275 Installation of the cross-toolchain creates a cross-toolchain
276 environment setup script in the directory that the ADT 276 environment setup script in the directory that the SDK
277 was installed. 277 was installed.
278 Before you can use the tools to develop your project, you must 278 Before you can use the tools to develop your project, you must
279 source this setup script. 279 source this setup script.
@@ -281,7 +281,7 @@
281 the machine architecture, which is followed by the string 281 the machine architecture, which is followed by the string
282 "poky-linux". 282 "poky-linux".
283 Here is an example that sources a script from the 283 Here is an example that sources a script from the
284 default ADT installation directory that uses the 284 default SDK installation directory that uses the
285 32-bit Intel x86 Architecture and the 285 32-bit Intel x86 Architecture and the
286 &DISTRO_NAME; Yocto Project release: 286 &DISTRO_NAME; Yocto Project release:
287 <literallayout class='monospaced'> 287 <literallayout class='monospaced'>
@@ -439,15 +439,1050 @@
439 </para> 439 </para>
440</section> 440</section>
441 441
442<section id='sdk-using-the-sdk-to-task-1'> 442<section id='sdk-developing-applications-using-eclipse'>
443 <title>Using the SDK to <replaceable>item 1</replaceable></title> 443 <title>Devloping Applications Using <trademark class='trade'>Eclipse</trademark></title>
444 444
445 <para role='writernotes'> 445 <para>
446 Describe the specific task you are going to accomplish with the SDK. 446 If you are familiar with the popular Eclipse IDE, you can use an
447 Provide a diagram showing the rough flow of the task. 447 Eclipse Yocto Plug-in to allow you to develop, deploy, and test your
448 Provide specific steps using a real example that works through the 448 application all from within Eclipse.
449 task. 449 This section describes general workflow using the SDK and Eclipse
450 and how to configure and set up Eclipse.
450 </para> 451 </para>
452
453 <section id='workflow-using-eclipse'>
454
455 <title>Workflow Using <trademark class='trade'>Eclipse</trademark></title>
456
457 <para>
458 The following figure and supporting list summarize the application
459 development general workflow that employs both the SDK Eclipse.
460 </para>
461
462 <para>
463 <imagedata fileref="figures/sdk-eclipse-dev-flow.png"
464 width="7in" depth="7in" align="center" scale="100" />
465 </para>
466
467 <para>
468 <orderedlist>
469 <listitem><para><emphasis>Prepare the host system for the Yocto Project</emphasis>:
470 See
471 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
472 and
473 "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" sections both
474 in the Yocto Project Reference Manual for requirements.
475 In particular, be sure your host system has the
476 <filename>xterm</filename> package installed.
477 </para></listitem>
478 <listitem><para><emphasis>Secure the Yocto Project kernel target image</emphasis>:
479 You must have a target kernel image that has been built using the OpenEmbedded
480 build system.</para>
481 <para>Depending on whether the Yocto Project has a pre-built image that matches your target
482 architecture and where you are going to run the image while you develop your application
483 (QEMU or real hardware), the area from which you get the image differs.
484 <itemizedlist>
485 <listitem><para>Download the image from
486 <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink>
487 if your target architecture is supported and you are going to develop
488 and test your application on actual hardware.</para></listitem>
489 <listitem><para>Download the image from
490 <ulink url='&YOCTO_QEMU_DL_URL;'>
491 <filename>machines/qemu</filename></ulink> if your target architecture is supported
492 and you are going to develop and test your application using the QEMU
493 emulator.</para></listitem>
494 <listitem><para>Build your image if you cannot find a pre-built image that matches
495 your target architecture.
496 If your target architecture is similar to a supported architecture, you can
497 modify the kernel image before you build it.
498 See the
499 "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>"
500 section in the Yocto Project Development
501 manual for an example.</para></listitem>
502 </itemizedlist></para>
503 <para>For information on pre-built kernel image naming schemes for images
504 that can run on the QEMU emulator, see the
505 <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-manual'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>.
506 </para></listitem>
507 <listitem><para><emphasis>Install the SDK</emphasis>:
508 The SDK provides a target-specific cross-development toolchain, the root filesystem,
509 the QEMU emulator, and other tools that can help you develop your application.
510 For information on how to install the SDK, see the
511 "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
512 section.
513 </para></listitem>
514 <listitem><para><emphasis>Secure the target root filesystem
515 and the Cross-development toolchain</emphasis>:
516 You need to find and download the appropriate root filesystem and
517 the cross-development toolchain.</para>
518 <para>You can find the tarballs for the root filesystem in the same area used
519 for the kernel image.
520 Depending on the type of image you are running, the root filesystem you need differs.
521 For example, if you are developing an application that runs on an image that
522 supports Sato, you need to get a root filesystem that supports Sato.</para>
523 <para>You can find the cross-development toolchains at
524 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'><filename>toolchains</filename></ulink>.
525 Be sure to get the correct toolchain for your development host and your
526 target architecture.
527 See the "<link linkend='sdk-locating-pre-built-sdk-installers'>Locating Pre-Built SDK Installers</link>"
528 section for information and the
529 "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
530 section for installation information.
531 </para></listitem>
532 <listitem><para><emphasis>Create and build your application</emphasis>:
533 At this point, you need to have source files for your application.
534 Once you have the files, you can use the Eclipse IDE to import them and build the
535 project.
536 If you are not using Eclipse, you need to use the cross-development tools you have
537 installed to create the image.</para></listitem>
538 <listitem><para><emphasis>Deploy the image with the application</emphasis>:
539 If you are using the Eclipse IDE, you can deploy your image to the hardware or to
540 QEMU through the project's preferences.
541 If you are not using the Eclipse IDE, then you need to deploy the application
542 to the hardware using other methods.
543 Or, if you are using QEMU, you need to use that tool and
544 load your image in for testing.
545 See the
546 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
547 chapter in the Yocto Project Development Manual
548 for information on using QEMU.
549 </para></listitem>
550 <listitem><para><emphasis>Test and debug the application</emphasis>:
551 Once your application is deployed, you need to test it.
552 Within the Eclipse IDE, you can use the debugging environment along with the
553 set of installed user-space tools to debug your application.
554 Of course, the same user-space tools are available separately if you choose
555 not to use the Eclipse IDE.</para></listitem>
556 </orderedlist>
557 </para>
558 </section>
559
560 <section id='adt-eclipse'>
561 <title>Working Within Eclipse</title>
562
563 <para>
564 The Eclipse IDE is a popular development environment and it fully
565 supports development using the Yocto Project.
566 <note>
567 This release of the Yocto Project supports both the Luna
568 and Kepler versions of the Eclipse IDE.
569 Thus, the following information provides setup information for
570 both versions.
571 </note>
572 </para>
573
574 <para>
575 When you install and configure the Eclipse Yocto Project Plug-in
576 into the Eclipse IDE, you maximize your Yocto Project experience.
577 Installing and configuring the Plug-in results in an environment
578 that has extensions specifically designed to let you more easily
579 develop software.
580 These extensions allow for cross-compilation, deployment, and
581 execution of your output into a QEMU emulation session as well as
582 actual target hardware.
583 You can also perform cross-debugging and profiling.
584 The environment also supports a suite of tools that allows you
585 to perform remote profiling, tracing, collection of power data,
586 collection of latency data, and collection of performance data.
587 </para>
588
589 <para>
590 This section describes how to install and configure the Eclipse IDE
591 Yocto Plug-in and how to use it to develop your application.
592 </para>
593
594 <section id='setting-up-the-eclipse-ide'>
595 <title>Setting Up the Eclipse IDE</title>
596
597 <para>
598 To develop within the Eclipse IDE, you need to do the following:
599 <orderedlist>
600 <listitem><para>Install the optimal version of the Eclipse
601 IDE.</para></listitem>
602 <listitem><para>Configure the Eclipse IDE.
603 </para></listitem>
604 <listitem><para>Install the Eclipse Yocto Plug-in.
605 </para></listitem>
606 <listitem><para>Configure the Eclipse Yocto Plug-in.
607 </para></listitem>
608 </orderedlist>
609 <note>
610 Do not install Eclipse from your distribution's package
611 repository.
612 Be sure to install Eclipse from the official Eclipse
613 download site as directed in the next section.
614 </note>
615 </para>
616
617 <section id='installing-eclipse-ide'>
618 <title>Installing the Eclipse IDE</title>
619
620 <para>
621 It is recommended that you have the Luna SR2 (4.4.2)
622 version of the Eclipse IDE installed on your development
623 system.
624 However, if you currently have the Kepler 4.3.2 version
625 installed and you do not want to upgrade the IDE, you can
626 configure Kepler to work with the Yocto Project.
627 </para>
628
629 <para>
630 If you do not have the Luna SR2 (4.4.2) Eclipse IDE
631 installed, you can find the tarball at
632 <ulink url='&ECLIPSE_MAIN_URL;'></ulink>.
633 From that site, choose the appropriate download from the
634 "Eclipse IDE for C/C++ Developers".
635 This version contains the Eclipse Platform, the Java
636 Development Tools (JDT), and the Plug-in Development
637 Environment.
638 </para>
639
640 <para>
641 Once you have downloaded the tarball, extract it into a
642 clean directory.
643 For example, the following commands unpack and install the
644 downloaded Eclipse IDE tarball into a clean directory
645 using the default name <filename>eclipse</filename>:
646 <literallayout class='monospaced'>
647 $ cd ~
648 $ tar -xzvf ~/Downloads/eclipse-cpp-luna-SR2-linux-gtk-x86_64.tar.gz
649 </literallayout>
650 </para>
651 </section>
652
653 <section id='configuring-the-eclipse-ide'>
654 <title>Configuring the Eclipse IDE</title>
655
656 <para>
657 This section presents the steps needed to configure the
658 Eclipse IDE.
659 </para>
660
661 <para>
662 Before installing and configuring the Eclipse Yocto Plug-in,
663 you need to configure the Eclipse IDE.
664 Follow these general steps:
665 <orderedlist>
666 <listitem><para>Start the Eclipse IDE.</para></listitem>
667 <listitem><para>Make sure you are in your Workbench and
668 select "Install New Software" from the "Help"
669 pull-down menu.</para></listitem>
670 <listitem><para>Select
671 <filename>Luna - &ECLIPSE_LUNA_URL;</filename>
672 from the "Work with:" pull-down menu.
673 <note>
674 For Kepler, select
675 <filename>Kepler - &ECLIPSE_KEPLER_URL;</filename>
676 </note>
677 </para></listitem>
678 <listitem><para>Expand the box next to "Linux Tools"
679 and select the
680 <filename>Linux Tools LTTng Tracer Control</filename>,
681 <filename>Linux Tools LTTng Userspace Analysis</filename>,
682 and
683 <filename>LTTng Kernel Analysis</filename> boxes.
684 If these selections do not appear in the list,
685 that means the items are already installed.
686 <note>
687 For Kepler, select
688 <filename>LTTng - Linux Tracing Toolkit</filename>
689 box.
690 </note>
691 </para></listitem>
692 <listitem><para>Expand the box next to "Mobile and
693 Device Development" and select the following boxes.
694 Again, if any of the following items are not
695 available for selection, that means the items are
696 already installed:
697 <itemizedlist>
698 <listitem><para><filename>C/C++ Remote Launch (Requires RSE Remote System Explorer)</filename></para></listitem>
699 <listitem><para><filename>Remote System Explorer End-user Runtime</filename></para></listitem>
700 <listitem><para><filename>Remote System Explorer User Actions</filename></para></listitem>
701 <listitem><para><filename>Target Management Terminal (Core SDK)</filename></para></listitem>
702 <listitem><para><filename>TCF Remote System Explorer add-in</filename></para></listitem>
703 <listitem><para><filename>TCF Target Explorer</filename></para></listitem>
704 </itemizedlist></para></listitem>
705 <listitem><para>Expand the box next to "Programming
706 Languages" and select the
707 <filename>C/C++ Autotools Support</filename>
708 and <filename>C/C++ Development Tools</filename>
709 boxes.
710 For Luna, these items do not appear on the list
711 as they are already installed.
712 </para></listitem>
713 <listitem><para>Complete the installation and restart
714 the Eclipse IDE.</para></listitem>
715 </orderedlist>
716 </para>
717 </section>
718
719 <section id='installing-the-eclipse-yocto-plug-in'>
720 <title>Installing or Accessing the Eclipse Yocto Plug-in</title>
721
722 <para>
723 You can install the Eclipse Yocto Plug-in into the Eclipse
724 IDE one of two ways: use the Yocto Project's Eclipse
725 Update site to install the pre-built plug-in or build and
726 install the plug-in from the latest source code.
727 </para>
728
729 <section id='new-software'>
730 <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title>
731
732 <para>
733 To install the Eclipse Yocto Plug-in from the update
734 site, follow these steps:
735 <orderedlist>
736 <listitem><para>Start up the Eclipse IDE.
737 </para></listitem>
738 <listitem><para>In Eclipse, select "Install New
739 Software" from the "Help" menu.
740 </para></listitem>
741 <listitem><para>Click "Add..." in the "Work with:"
742 area.</para></listitem>
743 <listitem><para>Enter
744 <filename>&ECLIPSE_DL_PLUGIN_URL;/luna</filename>
745 in the URL field and provide a meaningful name
746 in the "Name" field.
747 <note>
748 If you are using Kepler, use
749 <filename>&ECLIPSE_DL_PLUGIN_URL;/kepler</filename>
750 in the URL field.
751 </note></para></listitem>
752 <listitem><para>Click "OK" to have the entry added
753 to the "Work with:" drop-down list.
754 </para></listitem>
755 <listitem><para>Select the entry for the plug-in
756 from the "Work with:" drop-down list.
757 </para></listitem>
758 <listitem><para>Check the boxes next to
759 <filename>Yocto Project ADT Plug-in</filename>,
760 <filename>Yocto Project Bitbake Commander Plug-in</filename>,
761 and
762 <filename>Yocto Project Documentation plug-in</filename>.
763 </para></listitem>
764 <listitem><para>Complete the remaining software
765 installation steps and then restart the Eclipse
766 IDE to finish the installation of the plug-in.
767 <note>
768 You can click "OK" when prompted about
769 installing software that contains unsigned
770 content.
771 </note>
772 </para></listitem>
773 </orderedlist>
774 </para>
775 </section>
776
777 <section id='zip-file-method'>
778 <title>Installing the Plug-in Using the Latest Source Code</title>
779
780 <para>
781 To install the Eclipse Yocto Plug-in from the latest
782 source code, follow these steps:
783 <orderedlist>
784 <listitem><para>Be sure your development system
785 is not using OpenJDK to build the plug-in
786 by doing the following:
787 <orderedlist>
788 <listitem><para>Use the Oracle JDK.
789 If you don't have that, go to
790 <ulink url='http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html'></ulink>
791 and download the latest appropriate
792 Java SE Development Kit tarball for
793 your development system and
794 extract it into your home directory.
795 </para></listitem>
796 <listitem><para>In the shell you are going
797 to do your work, export the location of
798 the Oracle Java.
799 The previous step creates a new folder
800 for the extracted software.
801 You need to use the following
802 <filename>export</filename> command
803 and provide the specific location:
804 <literallayout class='monospaced'>
805 export PATH=~/<replaceable>extracted_jdk_location</replaceable>/bin:$PATH
806 </literallayout>
807 </para></listitem>
808 </orderedlist>
809 </para></listitem>
810 <listitem><para>In the same shell, create a Git
811 repository with:
812 <literallayout class='monospaced'>
813 $ cd ~
814 $ git clone git://git.yoctoproject.org/eclipse-poky
815 </literallayout>
816 </para></listitem>
817 <listitem><para>Be sure to checkout the correct
818 tag.
819 For example, if you are using Luna, do the
820 following:
821 <literallayout class='monospaced'>
822 $ git checkout luna/yocto-&DISTRO;
823 </literallayout>
824 This puts you in a detached HEAD state, which
825 is fine since you are only going to be building
826 and not developing.
827 <note>
828 If you are building kepler, checkout the
829 <filename>kepler/yocto-&DISTRO;</filename>
830 branch.
831 </note>
832 </para></listitem>
833 <listitem><para>Change to the
834 <filename>scripts</filename>
835 directory within the Git repository:
836 <literallayout class='monospaced'>
837 $ cd scripts
838 </literallayout>
839 </para></listitem>
840 <listitem><para>Set up the local build environment
841 by running the setup script:
842 <literallayout class='monospaced'>
843 $ ./setup.sh
844 </literallayout>
845 </para></listitem>
846 <listitem><para>When the script finishes execution,
847 it prompts you with instructions on how to run
848 the <filename>build.sh</filename> script, which
849 is also in the <filename>scripts</filename>
850 directory of the Git repository created
851 earlier.
852 </para></listitem>
853 <listitem><para>Run the <filename>build.sh</filename>
854 script as directed.
855 Be sure to provide the tag name, documentation
856 branch, and a release name.
857 Here is an example that uses the
858 <filename>luna/yocto-&DISTRO;</filename> tag, the
859 <filename>master</filename> documentation
860 branch, and
861 <filename>&DISTRO_NAME;</filename> for the
862 release name:
863 <literallayout class='monospaced'>
864 $ ECLIPSE_HOME=/home/scottrif/eclipse-poky/scripts/eclipse ./build.sh luna/yocto-&DISTRO; master &DISTRO_NAME; 2>&amp;1 | tee -a build.log
865 </literallayout>
866 After running the script, the file
867 <filename>org.yocto.sdk-</filename><replaceable>release</replaceable><filename>-</filename><replaceable>date</replaceable><filename>-archive.zip</filename>
868 is in the current directory.
869 </para></listitem>
870 <listitem><para>If necessary, start the Eclipse IDE
871 and be sure you are in the Workbench.
872 </para></listitem>
873 <listitem><para>Select "Install New Software" from
874 the "Help" pull-down menu.
875 </para></listitem>
876 <listitem><para>Click "Add".</para></listitem>
877 <listitem><para>Provide anything you want in the
878 "Name" field.
879 </para></listitem>
880 <listitem><para>Click "Archive" and browse to the
881 ZIP file you built in step eight.
882 This ZIP file should not be "unzipped", and must
883 be the <filename>*archive.zip</filename> file
884 created by running the
885 <filename>build.sh</filename> script.
886 </para></listitem>
887 <listitem><para>Click the "OK" button.
888 </para></listitem>
889 <listitem><para>Check the boxes that appear in
890 the installation window to install the
891 <filename>Yocto Project ADT Plug-in</filename>,
892 <filename>Yocto Project Bitbake Commander Plug-in</filename>,
893 and the
894 <filename>Yocto Project Documentation plug-in</filename>.
895 </para></listitem>
896 <listitem><para>Finish the installation by clicking
897 through the appropriate buttons.
898 You can click "OK" when prompted about
899 installing software that contains unsigned
900 content.
901 </para></listitem>
902 <listitem><para>Restart the Eclipse IDE if
903 necessary.
904 </para></listitem>
905 </orderedlist>
906 </para>
907
908 <para>
909 At this point you should be able to configure the
910 Eclipse Yocto Plug-in as described in the
911 "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>"
912 section.</para>
913 </section>
914 </section>
915
916 <section id='configuring-the-eclipse-yocto-plug-in'>
917 <title>Configuring the Eclipse Yocto Plug-in</title>
918
919 <para>
920 Configuring the Eclipse Yocto Plug-in involves setting the
921 Cross Compiler options and the Target options.
922 The configurations you choose become the default settings
923 for all projects.
924 You do have opportunities to change them later when
925 you configure the project (see the following section).
926 </para>
927
928 <para>
929 To start, you need to do the following from within the
930 Eclipse IDE:
931 <itemizedlist>
932 <listitem><para>Choose "Preferences" from the
933 "Window" menu to display the Preferences Dialog.
934 </para></listitem>
935 <listitem><para>Click "Yocto Project ADT" to display
936 the configuration screen.
937 </para></listitem>
938 </itemizedlist>
939 </para>
940
941 <section id='configuring-the-cross-compiler-options'>
942 <title>Configuring the Cross-Compiler Options</title>
943
944 <para>
945 To configure the Cross Compiler Options, you must select
946 the type of toolchain, point to the toolchain, specify
947 the sysroot location, and select the target
948 architecture.
949 <itemizedlist>
950 <listitem><para><emphasis>Selecting the Toolchain Type:</emphasis>
951 Choose between
952 <filename>Standalone pre-built toolchain</filename>
953 and
954 <filename>Build system derived toolchain</filename>
955 for Cross Compiler Options.
956 <itemizedlist>
957 <listitem><para><emphasis>
958 <filename>Standalone Pre-built Toolchain:</filename></emphasis>
959 Select this mode when you are using
960 a stand-alone cross-toolchain.
961 For example, suppose you are an
962 application developer and do not
963 need to build a target image.
964 Instead, you just want to use an
965 architecture-specific toolchain on
966 an existing kernel and target root
967 filesystem.</para></listitem>
968 <listitem><para><emphasis>
969 <filename>Build System Derived Toolchain:</filename></emphasis>
970 Select this mode if the
971 cross-toolchain has been installed
972 and built as part of the
973 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
974 When you select
975 <filename>Build system derived toolchain</filename>,
976 you are using the toolchain bundled
977 inside the Build Directory.
978 </para></listitem>
979 </itemizedlist>
980 </para></listitem>
981 <listitem><para><emphasis>Point to the Toolchain:</emphasis>
982 If you are using a stand-alone pre-built
983 toolchain, you should be pointing to where it is
984 installed.
985 See the
986 "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
987 section for information about how the SDK is
988 installed.</para>
989 <para>If you are using a system-derived
990 toolchain, the path you provide for the
991 <filename>Toolchain Root Location</filename>
992 field is the
993 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
994 See the
995 "<link linkend='sdk-optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</link>"
996 section.</para></listitem>
997 <listitem><para><emphasis>Specify the Sysroot Location:</emphasis>
998 This location is where the root filesystem for
999 the target hardware resides.
1000 </para>
1001 <para>The location of
1002 the sysroot filesystem depends on where you
1003 separately extracted and installed the
1004 filesystem.</para>
1005 <para>For information on how to install the
1006 toolchain and on how to extract and install the
1007 sysroot filesystem, see the
1008 "<link linkend='sdk-optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</link>"
1009 section.
1010 </para></listitem>
1011 <listitem><para><emphasis>Select the Target Architecture:</emphasis>
1012 The target architecture is the type of hardware
1013 you are going to use or emulate.
1014 Use the pull-down
1015 <filename>Target Architecture</filename> menu
1016 to make your selection.
1017 The pull-down menu should have the supported
1018 architectures.
1019 If the architecture you need is not listed in
1020 the menu, you will need to build the image.
1021 See the
1022 "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
1023 section of the Yocto Project Quick Start for
1024 more information.</para></listitem>
1025 </itemizedlist>
1026 </para>
1027 </section>
1028
1029 <section id='configuring-the-target-options'>
1030 <title>Configuring the Target Options</title>
1031
1032 <para>
1033 You can choose to emulate hardware using the QEMU
1034 emulator, or you can choose to run your image on actual
1035 hardware.
1036 <itemizedlist>
1037 <listitem><para><emphasis>QEMU:</emphasis>
1038 Select this option if you will be using the
1039 QEMU emulator.
1040 If you are using the emulator, you also need to
1041 locate the kernel and specify any custom
1042 options.</para>
1043 <para>If you selected
1044 <filename>Build system derived toolchain</filename>,
1045 the target kernel you built will be located in
1046 the Build Directory in
1047 <filename>tmp/deploy/images/<replaceable>machine</replaceable></filename>
1048 directory.
1049 If you selected
1050 <filename>Standalone pre-built toolchain</filename>,
1051 the pre-built image you downloaded is located
1052 in the directory you specified when you
1053 downloaded the image.</para>
1054 <para>Most custom options are for advanced QEMU
1055 users to further customize their QEMU instance.
1056 These options are specified between paired
1057 angled brackets.
1058 Some options must be specified outside the
1059 brackets.
1060 In particular, the options
1061 <filename>serial</filename>,
1062 <filename>nographic</filename>, and
1063 <filename>kvm</filename> must all be outside the
1064 brackets.
1065 Use the <filename>man qemu</filename> command
1066 to get help on all the options and their use.
1067 The following is an example:
1068 <literallayout class='monospaced'>
1069 serial ‘&lt;-m 256 -full-screen&gt;’
1070 </literallayout></para>
1071 <para>
1072 Regardless of the mode, Sysroot is already
1073 defined as part of the Cross-Compiler Options
1074 configuration in the
1075 <filename>Sysroot Location:</filename> field.
1076 </para></listitem>
1077 <listitem><para><emphasis>External HW:</emphasis>
1078 Select this option if you will be using actual
1079 hardware.</para></listitem>
1080 </itemizedlist>
1081 </para>
1082
1083 <para>
1084 Click the "OK" to save your plug-in configurations.
1085 </para>
1086 </section>
1087 </section>
1088 </section>
1089
1090 <section id='creating-the-project'>
1091 <title>Creating the Project</title>
1092
1093 <para>
1094 You can create two types of projects: Autotools-based, or
1095 Makefile-based.
1096 This section describes how to create Autotools-based projects
1097 from within the Eclipse IDE.
1098 For information on creating Makefile-based projects in a
1099 terminal window, see the
1100 "<link linkend='makefile-based-projects'>Makefile-Based Projects</link>"
1101 section.
1102 <note>
1103 Do not use special characters in project names
1104 (e.g. spaces, underscores, etc.). Doing so can
1105 cause configuration to fail.
1106 </note>
1107 </para>
1108
1109 <para>
1110 To create a project based on a Yocto template and then display
1111 the source code, follow these steps:
1112 <orderedlist>
1113 <listitem><para>Select "Project" from the "File -> New" menu.
1114 </para></listitem>
1115 <listitem><para>Double click <filename>CC++</filename>.
1116 </para></listitem>
1117 <listitem><para>Double click <filename>C Project</filename>
1118 to create the project.</para></listitem>
1119 <listitem><para>Expand <filename>Yocto Project ADT Autotools Project</filename>.
1120 </para></listitem>
1121 <listitem><para>Select <filename>Hello World ANSI C Autotools Project</filename>.
1122 This is an Autotools-based project based on a Yocto
1123 template.</para></listitem>
1124 <listitem><para>Put a name in the <filename>Project name:</filename>
1125 field.
1126 Do not use hyphens as part of the name.
1127 </para></listitem>
1128 <listitem><para>Click "Next".</para></listitem>
1129 <listitem><para>Add information in the
1130 <filename>Author</filename> and
1131 <filename>Copyright notice</filename> fields.
1132 </para></listitem>
1133 <listitem><para>Be sure the <filename>License</filename>
1134 field is correct.</para></listitem>
1135 <listitem><para>Click "Finish".</para></listitem>
1136 <listitem><para>If the "open perspective" prompt appears,
1137 click "Yes" so that you in the C/C++ perspective.
1138 </para></listitem>
1139 <listitem><para>The left-hand navigation pane shows your
1140 project.
1141 You can display your source by double clicking the
1142 project's source file.</para></listitem>
1143 </orderedlist>
1144 </para>
1145 </section>
1146
1147 <section id='configuring-the-cross-toolchains'>
1148 <title>Configuring the Cross-Toolchains</title>
1149
1150 <para>
1151 The earlier section,
1152 "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>",
1153 sets up the default project configurations.
1154 You can override these settings for a given project by following
1155 these steps:
1156 <orderedlist>
1157 <listitem><para>Select "Change Yocto Project Settings" from
1158 the "Project" menu.
1159 This selection brings up the Yocto Project Settings
1160 Dialog and allows you to make changes specific to an
1161 individual project.</para>
1162 <para>By default, the Cross Compiler Options and Target
1163 Options for a project are inherited from settings you
1164 provided using the Preferences Dialog as described
1165 earlier in the
1166 "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>" section.
1167 The Yocto Project Settings Dialog allows you to override
1168 those default settings for a given project.
1169 </para></listitem>
1170 <listitem><para>Make your configurations for the project
1171 and click "OK".
1172 </para></listitem>
1173 <listitem><para>Right-click in the navigation pane and
1174 select "Reconfigure Project" from the pop-up menu.
1175 This selection reconfigures the project by running
1176 <filename>autogen.sh</filename> in the workspace for
1177 your project.
1178 The script also runs <filename>libtoolize</filename>,
1179 <filename>aclocal</filename>,
1180 <filename>autoconf</filename>,
1181 <filename>autoheader</filename>,
1182 <filename>automake --a</filename>, and
1183 <filename>./configure</filename>.
1184 Click on the "Console" tab beneath your source code to
1185 see the results of reconfiguring your project.
1186 </para></listitem>
1187 </orderedlist>
1188 </para>
1189 </section>
1190
1191 <section id='building-the-project'>
1192 <title>Building the Project</title>
1193
1194 <para>
1195 To build the project select "Build Project" from the
1196 "Project" menu.
1197 The console should update and you can note the cross-compiler
1198 you are using.
1199 <note>
1200 When building "Yocto Project ADT Autotools" projects, the Eclipse
1201 IDE might display error messages for Functions/Symbols/Types
1202 that cannot be "resolved", even when the related include file
1203 is listed at the project navigator and when the project is
1204 able to build.
1205 For these cases only, it is recommended to add a new linked
1206 folder to the appropriate sysroot.
1207 Use these steps to add the linked folder:
1208 <orderedlist>
1209 <listitem><para>
1210 Select the project.
1211 </para></listitem>
1212 <listitem><para>
1213 Select "Folder" from the
1214 <filename>File > New</filename> menu.
1215 </para></listitem>
1216 <listitem><para>
1217 In the "New Folder" Dialog, select "Link to alternate
1218 location (linked folder)".
1219 </para></listitem>
1220 <listitem><para>
1221 Click "Browse" to navigate to the include folder inside
1222 the same sysroot location selected in the Yocto Project
1223 configuration preferences.
1224 </para></listitem>
1225 <listitem><para>
1226 Click "OK".
1227 </para></listitem>
1228 <listitem><para>
1229 Click "Finish" to save the linked folder.
1230 </para></listitem>
1231 </orderedlist>
1232 </note>
1233 </para>
1234 </section>
1235
1236 <section id='starting-qemu-in-user-space-nfs-mode'>
1237 <title>Starting QEMU in User-Space NFS Mode</title>
1238
1239 <para>
1240 To start the QEMU emulator from within Eclipse, follow these
1241 steps:
1242 <note>
1243 See the
1244 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
1245 chapter in the Yocto Project Development Manual
1246 for more information on using QEMU.
1247 </note>
1248 <orderedlist>
1249 <listitem><para>Expose and select "External Tools" from
1250 the "Run" menu.
1251 Your image should appear as a selectable menu item.
1252 </para></listitem>
1253 <listitem><para>Select your image from the menu to launch
1254 the emulator in a new window.
1255 </para></listitem>
1256 <listitem><para>If needed, enter your host root password in
1257 the shell window at the prompt.
1258 This sets up a <filename>Tap 0</filename> connection
1259 needed for running in user-space NFS mode.
1260 </para></listitem>
1261 <listitem><para>Wait for QEMU to launch.</para></listitem>
1262 <listitem><para>Once QEMU launches, you can begin operating
1263 within that environment.
1264 One useful task at this point would be to determine the
1265 IP Address for the user-space NFS by using the
1266 <filename>ifconfig</filename> command.
1267 </para></listitem>
1268 </orderedlist>
1269 </para>
1270 </section>
1271
1272 <section id='deploying-and-debugging-the-application'>
1273 <title>Deploying and Debugging the Application</title>
1274
1275 <para>
1276 Once the QEMU emulator is running the image, you can deploy
1277 your application using the Eclipse IDE and then use
1278 the emulator to perform debugging.
1279 Follow these steps to deploy the application.
1280 <orderedlist>
1281 <listitem><para>Select "Debug Configurations..." from the
1282 "Run" menu.</para></listitem>
1283 <listitem><para>In the left area, expand
1284 <filename>C/C++Remote Application</filename>.
1285 </para></listitem>
1286 <listitem><para>Locate your project and select it to bring
1287 up a new tabbed view in the Debug Configurations Dialog.
1288 </para></listitem>
1289 <listitem><para>Enter the absolute path into which you want
1290 to deploy the application.
1291 Use the "Remote Absolute File Path for
1292 C/C++Application:" field.
1293 For example, enter
1294 <filename>/usr/bin/<replaceable>programname</replaceable></filename>.
1295 </para></listitem>
1296 <listitem><para>Click on the "Debugger" tab to see the
1297 cross-tool debugger you are using.</para></listitem>
1298 <listitem><para>Click on the "Main" tab.</para></listitem>
1299 <listitem><para>Create a new connection to the QEMU instance
1300 by clicking on "new".</para></listitem>
1301 <listitem><para>Select <filename>TCF</filename>, which means
1302 Target Communication Framework.</para></listitem>
1303 <listitem><para>Click "Next".</para></listitem>
1304 <listitem><para>Clear out the "host name" field and enter
1305 the IP Address determined earlier.</para></listitem>
1306 <listitem><para>Click "Finish" to close the
1307 New Connections Dialog.</para></listitem>
1308 <listitem><para>Use the drop-down menu now in the
1309 "Connection" field and pick the IP Address you entered.
1310 </para></listitem>
1311 <listitem><para>Click "Debug" to bring up a login screen
1312 and login.</para></listitem>
1313 <listitem><para>Accept the debug perspective.
1314 </para></listitem>
1315 </orderedlist>
1316 </para>
1317 </section>
1318
1319 <section id='running-user-space-tools'>
1320 <title>Running User-Space Tools</title>
1321
1322 <para>
1323 As mentioned earlier in the manual, several tools exist that
1324 enhance your development experience.
1325 These tools are aids in developing and debugging applications
1326 and images.
1327 You can run these user-space tools from within the Eclipse
1328 IDE through the "YoctoProjectTools" menu.
1329 </para>
1330
1331 <para>
1332 Once you pick a tool, you need to configure it for the remote
1333 target.
1334 Every tool needs to have the connection configured.
1335 You must select an existing TCF-based RSE connection to the
1336 remote target.
1337 If one does not exist, click "New" to create one.
1338 </para>
1339
1340 <para>
1341 Here are some specifics about the remote tools:
1342 <itemizedlist>
1343 <listitem><para><emphasis><filename>OProfile</filename>:</emphasis>
1344 Selecting this tool causes the
1345 <filename>oprofile-server</filename> on the remote
1346 target to launch on the local host machine.
1347 The <filename>oprofile-viewer</filename> must be
1348 installed on the local host machine and the
1349 <filename>oprofile-server</filename> must be installed
1350 on the remote target, respectively, in order to use.
1351 You must compile and install the
1352 <filename>oprofile-viewer</filename> from the source
1353 code on your local host machine.
1354 Furthermore, in order to convert the target's sample
1355 format data into a form that the host can use, you must
1356 have OProfile version 0.9.4 or greater installed on the
1357 host.</para>
1358 <para>You can locate both the viewer and server from
1359 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/oprofileui/'></ulink>.
1360 You can also find more information on setting up and
1361 using this tool in the
1362 "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-oprofile'>oprofile</ulink>"
1363 section of the Yocto Project Profiling and Tracing
1364 Manual.
1365 <note>The <filename>oprofile-server</filename> is
1366 installed by default on the
1367 <filename>core-image-sato-sdk</filename> image.</note>
1368 </para></listitem>
1369 <listitem><para><emphasis><filename>Lttng2.0 trace import</filename>:</emphasis>
1370 Selecting this tool transfers the remote target's
1371 <filename>Lttng</filename> tracing data back to the
1372 local host machine and uses the Lttng Eclipse plug-in
1373 to graphically display the output.
1374 For information on how to use Lttng to trace an
1375 application,
1376 see <ulink url='http://lttng.org/documentation'></ulink>
1377 and the
1378 "<ulink url='&YOCTO_DOCS_PROF_URL;#lttng-linux-trace-toolkit-next-generation'>LTTng (Linux Trace Toolkit, next generation)</ulink>"
1379 section, which is in the Yocto Project Profiling and
1380 Tracing Manual.
1381 <note>Do not use
1382 <filename>Lttng-user space (legacy)</filename> tool.
1383 This tool no longer has any upstream support.</note>
1384 </para>
1385 <para>Before you use the
1386 <filename>Lttng2.0 trace import</filename> tool,
1387 you need to setup the Lttng Eclipse plug-in and create a
1388 Tracing project.
1389 Do the following:
1390 <orderedlist>
1391 <listitem><para>Select "Open Perspective" from the
1392 "Window" menu and then select "Other..." to
1393 bring up a menu of other perspectives.
1394 Choose "Tracing".
1395 </para></listitem>
1396 <listitem><para>Click "OK" to change the Eclipse
1397 perspective into the Tracing perspective.
1398 </para></listitem>
1399 <listitem><para>Create a new Tracing project by
1400 selecting "Project" from the "File -> New" menu.
1401 </para></listitem>
1402 <listitem><para>Choose "Tracing Project" from the
1403 "Tracing" menu and click "Next".
1404 </para></listitem>
1405 <listitem><para>Provide a name for your tracing
1406 project and click "Finish".
1407 </para></listitem>
1408 <listitem><para>Generate your tracing data on the
1409 remote target.</para></listitem>
1410 <listitem><para>Select "Lttng2.0 trace import"
1411 from the "Yocto Project Tools" menu to
1412 start the data import process.</para></listitem>
1413 <listitem><para>Specify your remote connection name.
1414 </para></listitem>
1415 <listitem><para>For the Ust directory path, specify
1416 the location of your remote tracing data.
1417 Make sure the location ends with
1418 <filename>ust</filename> (e.g.
1419 <filename>/usr/mysession/ust</filename>).
1420 </para></listitem>
1421 <listitem><para>Click "OK" to complete the import
1422 process.
1423 The data is now in the local tracing project
1424 you created.</para></listitem>
1425 <listitem><para>Right click on the data and then use
1426 the menu to Select "Generic CTF Trace" from the
1427 "Trace Type... -> Common Trace Format" menu to
1428 map the tracing type.</para></listitem>
1429 <listitem><para>Right click the mouse and select
1430 "Open" to bring up the Eclipse Lttng Trace
1431 Viewer so you view the tracing data.
1432 </para></listitem>
1433 </orderedlist></para></listitem>
1434 <listitem><para><emphasis><filename>PowerTOP</filename>:</emphasis>
1435 Selecting this tool runs PowerTOP on the remote target
1436 machine and displays the results in a new view called
1437 PowerTOP.</para>
1438 <para>The "Time to gather data(sec):" field is the time
1439 passed in seconds before data is gathered from the
1440 remote target for analysis.</para>
1441 <para>The "show pids in wakeups list:" field corresponds
1442 to the <filename>-p</filename> argument passed to
1443 <filename>PowerTOP</filename>.</para></listitem>
1444 <listitem><para><emphasis><filename>LatencyTOP and Perf</filename>:</emphasis>
1445 LatencyTOP identifies system latency, while
1446 Perf monitors the system's performance counter
1447 registers.
1448 Selecting either of these tools causes an RSE terminal
1449 view to appear from which you can run the tools.
1450 Both tools refresh the entire screen to display results
1451 while they run.
1452 For more information on setting up and using
1453 <filename>perf</filename>, see the
1454 "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-perf'>perf</ulink>"
1455 section in the Yocto Project Profiling and Tracing
1456 Manual.
1457 </para></listitem>
1458 <listitem><para><emphasis><filename>SystemTap</filename>:</emphasis>
1459 Systemtap is a tool that lets you create and reuse
1460 scripts to examine the activities of a live Linux
1461 system.
1462 You can easily extract, filter, and summarize data
1463 that helps you diagnose complex performance or
1464 functional problems.
1465 For more information on setting up and using
1466 <filename>SystemTap</filename>, see the
1467 <ulink url='https://sourceware.org/systemtap/documentation.html'>SystemTap Documentation</ulink>.
1468 </para></listitem>
1469 <listitem><para><emphasis><filename>yocto-bsp</filename>:</emphasis>
1470 The <filename>yocto-bsp</filename> tool lets you
1471 quickly set up a Board Support Package (BSP) layer.
1472 The tool requires a Metadata location, build location,
1473 BSP name, BSP output location, and a kernel
1474 architecture.
1475 For more information on the
1476 <filename>yocto-bsp</filename> tool outside of Eclipse,
1477 see the
1478 "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a new BSP Layer Using the yocto-bsp Script</ulink>"
1479 section in the Yocto Project Board Support Package
1480 (BSP) Developer's Guide.
1481 </para></listitem>
1482 </itemizedlist>
1483 </para>
1484 </section>
1485 </section>
451</section> 1486</section>
452 1487
453<section id='sdk-using-the-sdk-to-task-2'> 1488<section id='sdk-using-the-sdk-to-task-2'>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-09 23:31:16 +0000