summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-model.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual/dev-manual-model.xml')
-rw-r--r--documentation/dev-manual/dev-manual-model.xml739
1 files changed, 739 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index b5274b8452..3bfd1a3963 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -641,6 +641,745 @@
641 </para> 641 </para>
642 </section> 642 </section>
643 643
644 <section id='adt-eclipse'>
645 <title>Working Within Eclipse</title>
646
647 <para>
648 The Eclipse IDE is a popular development environment and it fully supports
649 development using the Yocto Project.
650 When you install and configure the Eclipse Yocto Project Plug-in into
651 the Eclipse IDE, you maximize your Yocto Project experience.
652 Installing and configuring the Plug-in results in an environment that
653 has extensions specifically designed to let you more easily develop software.
654 These extensions allow for cross-compilation, deployment, and execution of
655 your output into a QEMU emulation session.
656 You can also perform cross-debugging and profiling.
657 The environment also supports a suite of tools that allows you to perform
658 remote profiling, tracing, collection of power data, collection of
659 latency data, and collection of performance data.
660 </para>
661
662 <para>
663 This section describes how to install and configure the Eclipse IDE
664 Yocto Plug-in and how to use it to develop your application.
665 </para>
666
667 <section id='setting-up-the-eclipse-ide'>
668 <title>Setting Up the Eclipse IDE</title>
669
670 <para>
671 To develop within the Eclipse IDE, you need to do the following:
672 <orderedlist>
673 <listitem><para>Install the optimal version of the Eclipse IDE.</para></listitem>
674 <listitem><para>Configure the Eclipse IDE.</para></listitem>
675 <listitem><para>Install the Eclipse Yocto Plug-in.</para></listitem>
676 <listitem><para>Configure the Eclipse Yocto Plug-in.</para></listitem>
677 </orderedlist>
678 <note>
679 Do not install Eclipse from your distribution's package repository.
680 Be sure to install Eclipse from the official Eclipse download site as directed
681 in the next section.
682 </note>
683 </para>
684
685 <section id='installing-eclipse-ide'>
686 <title>Installing the Eclipse IDE</title>
687
688 <para>
689 It is recommended that you have the Indigo 3.7.2 version of the
690 Eclipse IDE installed on your development system.
691 If you don’t have this version, you can find it at
692 <ulink url='&ECLIPSE_MAIN_URL;'></ulink>.
693 From that site, choose the Eclipse Classic version particular to your development
694 host.
695 This version contains the Eclipse Platform, the Java Development
696 Tools (JDT), and the Plug-in Development Environment.
697 </para>
698
699 <para>
700 Once you have downloaded the tarball, extract it into a clean
701 directory.
702 For example, the following commands unpack and install the Eclipse IDE
703 tarball found in the <filename>Downloads</filename> area
704 into a clean directory using the default name <filename>eclipse</filename>:
705 <literallayout class='monospaced'>
706 $ cd ~
707 $ tar -xzvf ~/Downloads/eclipse-SDK-3.7.2-linux-gtk-x86_64.tar.gz
708 </literallayout>
709 </para>
710
711 <para>
712 One issue exists that you need to be aware of regarding the Java
713 Virtual machine’s garbage collection (GC) process.
714 The GC process does not clean up the permanent generation
715 space (PermGen).
716 This space stores metadata descriptions of classes.
717 The default value is set too small and it could trigger an
718 out-of-memory error such as the following:
719 <literallayout class='monospaced'>
720 Java.lang.OutOfMemoryError: PermGen space
721 </literallayout>
722 </para>
723
724 <para>
725 This error causes the application to hang.
726 </para>
727
728 <para>
729 To fix this issue, you can use the <filename>--vmargs</filename>
730 option when you start Eclipse to increase the size of the permanent generation space:
731 <literallayout class='monospaced'>
732 eclipse --vmargs --XX:PermSize=256M
733 </literallayout>
734 </para>
735 </section>
736
737 <section id='configuring-the-eclipse-ide'>
738 <title>Configuring the Eclipse IDE</title>
739
740 <para>
741 Before installing and configuring the Eclipse Yocto Plug-in, you need to configure
742 the Eclipse IDE.
743 Follow these general steps to configure Eclipse:
744 <orderedlist>
745 <listitem><para>Start the Eclipse IDE.</para></listitem>
746 <listitem><para>Make sure you are in your Workbench and select
747 "Install New Software" from the "Help" pull-down menu.
748 </para></listitem>
749 <listitem><para>Select <filename>indigo - &ECLIPSE_INDIGO_URL;</filename>
750 from the "Work with:" pull-down menu.</para></listitem>
751 <listitem><para>Expand the box next to <filename>Programming Languages</filename>
752 and select the <filename>Autotools Support for CDT (incubation)</filename>
753 and <filename>C/C++ Development Tools</filename> boxes.</para></listitem>
754 <listitem><para>Expand the box next to "Linux Tools" and select the
755 "LTTng - Linux Tracing Toolkit(incubation)" boxes.</para></listitem>
756 <listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem>
757 <listitem><para>After the Eclipse IDE restarts and from the Workbench, select
758 "Install New Software" from the "Help" pull-down menu.</para></listitem>
759 <listitem><para>Click the
760 "Available Software Sites" link.</para></listitem>
761 <listitem><para>Check the box next to
762 <filename>&ECLIPSE_UPDATES_URL;</filename>
763 and click "OK".</para></listitem>
764 <listitem><para>Select <filename>&ECLIPSE_UPDATES_URL;</filename>
765 from the "Work with:" pull-down menu.</para></listitem>
766 <listitem><para>Check the box next to <filename>TM and RSE Main Features</filename>.
767 </para></listitem>
768 <listitem><para>Expand the box next to <filename>TM and RSE Optional Add-ons</filename>
769 and select every item except <filename>RSE Unit Tests</filename> and
770 <filename>RSE WinCE Services (incubation)</filename>.</para></listitem>
771 <listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem>
772 <listitem><para>If necessary, select
773 "Install New Software" from the "Help" pull-down menu so you can click the
774 "Available Software Sites" link again.</para></listitem>
775 <listitem><para>After clicking "Available Software Sites", check the box next to
776 <filename>http://download.eclipse.org/tools/cdt/releases/indigo</filename>
777 and click "OK".</para></listitem>
778 <listitem><para>Select <filename>&ECLIPSE_INDIGO_CDT_URL;</filename>
779 from the "Work with:" pull-down menu.</para></listitem>
780 <listitem><para>Check the box next to <filename>CDT Main Features</filename>.
781 </para></listitem>
782 <listitem><para>Expand the box next to <filename>CDT Optional Features</filename>
783 and select <filename>C/C++ Remote Launch</filename> and
784 <filename>Target Communication Framework (incubation)</filename>.</para></listitem>
785 <listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem>
786 </orderedlist>
787 </para>
788 </section>
789
790 <section id='installing-the-eclipse-yocto-plug-in'>
791 <title>Installing or Accessing the Eclipse Yocto Plug-in</title>
792
793 <para>
794 You can install the Eclipse Yocto Plug-in into the Eclipse IDE
795 one of two ways: use the Yocto Project's Eclipse Update site to install the pre-built plug-in,
796 or build and install the plug-in from the latest source code.
797 If you don't want to permanently install the plug-in but just want to try it out
798 within the Eclipse environment, you can import the plug-in project from the
799 Yocto Project source repositories.
800 </para>
801
802 <section id='new-software'>
803 <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title>
804
805 <para>
806 To install the Eclipse Yocto Plug-in from the update site,
807 follow these steps:
808 <orderedlist>
809 <listitem><para>Start up the Eclipse IDE.</para></listitem>
810 <listitem><para>In Eclipse, select "Install New Software" from the "Help" menu.</para></listitem>
811 <listitem><para>Click "Add..." in the "Work with:" area.</para></listitem>
812 <listitem><para>Enter
813 <filename>&ECLIPSE_DL_PLUGIN_URL;</filename>
814 in the URL field and provide a meaningful name in the "Name" field.</para></listitem>
815 <listitem><para>Click "OK" to have the entry added to the "Work with:"
816 drop-down list.</para></listitem>
817 <listitem><para>Select the entry for the plug-in from the "Work with:" drop-down
818 list.</para></listitem>
819 <listitem><para>Check the box next to <filename>Development tools and SDKs for Yocto Linux</filename>.
820 </para></listitem>
821 <listitem><para>Complete the remaining software installation steps and
822 then restart the Eclipse IDE to finish the installation of the plug-in.
823 </para></listitem>
824 </orderedlist>
825 </para>
826 </section>
827
828 <section id='zip-file-method'>
829 <title>Installing the Plug-in Using the Latest Source Code</title>
830
831 <para>
832 To install the Eclipse Yocto Plug-in from the latest source code, follow these steps:
833 <orderedlist>
834 <listitem><para>Open a shell and create a Git repository with:
835 <literallayout class='monospaced'>
836 $ git clone git://git.yoctoproject.org/eclipse-poky yocto-eclipse
837 </literallayout>
838 For this example, the repository is named
839 <filename>~/yocto-eclipse</filename>.</para></listitem>
840 <listitem><para>Locate the <filename>build.sh</filename> script in the
841 Git repository you created in the previous step.
842 The script is located in the <filename>scripts</filename>.</para></listitem>
843 <listitem><para>Be sure to set and export the <filename>ECLIPSE_HOME</filename> environment
844 variable to the top-level directory in which you installed the Indigo
845 version of Eclipse.
846 For example, if your Eclipse directory is <filename>$HOME/eclipse</filename>,
847 use the following:
848 <literallayout class='monospaced'>
849 $ export ECLIPSE_HOME=$HOME/eclipse
850 </literallayout></para></listitem>
851 <listitem><para>Run the <filename>build.sh</filename> script and provide the
852 name of the Git branch along with the Yocto Project release you are
853 using.
854 Here is an example that uses the <filename>master</filename> Git repository
855 and the <filename>1.1M4</filename> release:
856 <literallayout class='monospaced'>
857 $ scripts/build.sh master 1.1M4
858 </literallayout>
859 After running the script, the file
860 <filename>org.yocto.sdk-&lt;release&gt;-&lt;date&gt;-archive.zip</filename>
861 is in the current directory.</para></listitem>
862 <listitem><para>If necessary, start the Eclipse IDE and be sure you are in the
863 Workbench.</para></listitem>
864 <listitem><para>Select "Install New Software" from the "Help" pull-down menu.
865 </para></listitem>
866 <listitem><para>Click "Add".</para></listitem>
867 <listitem><para>Provide anything you want in the "Name" field.</para></listitem>
868 <listitem><para>Click "Archive" and browse to the ZIP file you built
869 in step four.
870 This ZIP file should not be "unzipped", and must be the
871 <filename>*archive.zip</filename> file created by running the
872 <filename>build.sh</filename> script.</para></listitem>
873 <listitem><para>Check the box next to the new entry in the installation window and complete
874 the installation.</para></listitem>
875 <listitem><para>Restart the Eclipse IDE if necessary.</para></listitem>
876 </orderedlist>
877 </para>
878
879 <para>
880 At this point you should be able to configure the Eclipse Yocto Plug-in as described in the
881 "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>"
882 section.</para>
883 </section>
884
885 <section id='yocto-project-source'>
886 <title>Importing the Plug-in Project into the Eclipse Environment</title>
887
888 <para>
889 Importing the Eclipse Yocto Plug-in project from the Yocto Project source repositories
890 is useful when you want to try out the latest plug-in from the tip of plug-in's
891 development tree.
892 It is important to understand when you import the plug-in you are not installing
893 it into the Eclipse application.
894 Rather, you are importing the project and just using it.
895 To import the plug-in project, follow these steps:
896 <orderedlist>
897 <listitem><para>Open a shell and create a Git repository with:
898 <literallayout class='monospaced'>
899 $ git clone git://git.yoctoproject.org/eclipse-poky yocto-eclipse
900 </literallayout>
901 For this example, the repository is named
902 <filename>~/yocto-eclipse</filename>.</para></listitem>
903 <listitem><para>In Eclipse, select "Import" from the "File" menu.</para></listitem>
904 <listitem><para>Expand the "General" box and select "existing projects into workspace"
905 and then click "Next".</para></listitem>
906 <listitem><para>Select the root directory and browse to
907 <filename>~/yocto-eclipse/plugins</filename>.</para></listitem>
908 <listitem><para>Three plug-ins exist: "org.yocto.bc.ui", "org.yocto.sdk.ide", and
909 "org.yocto.sdk.remotetools".
910 Select and import all of them.</para></listitem>
911 </orderedlist>
912 </para>
913
914 <para>
915 The left navigation pane in the Eclipse application shows the default projects.
916 Right-click on one of these projects and run it as an Eclipse application.
917 This brings up a second instance of Eclipse IDE that has the Yocto Plug-in.
918 </para>
919 </section>
920 </section>
921
922 <section id='configuring-the-eclipse-yocto-plug-in'>
923 <title>Configuring the Eclipse Yocto Plug-in</title>
924
925 <para>
926 Configuring the Eclipse Yocto Plug-in involves setting the Cross
927 Compiler options and the Target options.
928 The configurations you choose become the default settings for all projects.
929 You do have opportunities to change them later when
930 you configure the project (see the following section).
931 </para>
932
933 <para>
934 To start, you need to do the following from within the Eclipse IDE:
935 <itemizedlist>
936 <listitem><para>Choose <filename>Windows -&gt; Preferences</filename> to display
937 the <filename>Preferences</filename> Dialog</para></listitem>
938 <listitem><para>Click <filename>Yocto Project ADT</filename></para></listitem>
939 </itemizedlist>
940 </para>
941
942 <section id='configuring-the-cross-compiler-options'>
943 <title>Configuring the Cross-Compiler Options</title>
944
945 <para>
946 To configure the Cross Compiler Options, you must select the type of toolchain,
947 point to the toolchain, specify the sysroot location, and select the target architecture.
948 <itemizedlist>
949 <listitem><para><emphasis>Selecting the Toolchain Type:</emphasis>
950 Choose between <filename>Standalone pre-built toolchain</filename>
951 and <filename>Build system derived toolchain</filename> for Cross
952 Compiler Options.
953 <itemizedlist>
954 <listitem><para><emphasis>
955 <filename>Standalone Pre-built Toolchain:</filename></emphasis>
956 Select this mode when you are using a stand-alone cross-toolchain.
957 For example, suppose you are an application developer and do not
958 need to build a target image.
959 Instead, you just want to use an architecture-specific toolchain on an
960 existing kernel and target root filesystem.
961 </para></listitem>
962 <listitem><para><emphasis>
963 <filename>Build System Derived Toolchain:</filename></emphasis>
964 Select this mode if the cross-toolchain has been installed and built
965 as part of the build directory.
966 When you select <filename>Build system derived toolchain</filename>,
967 you are using the toolchain bundled
968 inside the build directory.
969 </para></listitem>
970 </itemizedlist>
971 </para></listitem>
972 <listitem><para><emphasis>Point to the Toolchain:</emphasis>
973 If you are using a stand-alone pre-built toolchain, you should be pointing to the
974 <filename>&YOCTO_ADTPATH_DIR;</filename> directory.
975 This is the location for toolchains installed by the ADT Installer or by hand.
976 Sections "<ulink url='&YOCTO_DOCS_ADT_URL;#configuring-and-running-the-adt-installer-script'>Configuring
977 and Running the ADT Installer Script</ulink>" and
978 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>"
979 in the Yocto Project Application Developer's Guide
980 describe two ways to install a stand-alone cross-toolchain in the
981 <filename>/opt/poky</filename> directory.
982 <note>It is possible to install a stand-alone cross-toolchain in a directory
983 other than <filename>/opt/poky</filename>.
984 However, doing so is discouraged.</note></para>
985 <para>If you are using a system-derived toolchain, the path you provide
986 for the <filename>Toolchain Root Location</filename>
987 field is the build directory.
988 See the "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-toolchain-from-within-the-build-tree'>Using
989 BitBake and the build directory</ulink>" section in the Yocto Project Application
990 Developer's Guide for information on how to install the toolchain into the build
991directory.</para></listitem>
992 <listitem><para><emphasis>Specify the Sysroot Location:</emphasis>
993 This location is where the root filesystem for the
994 target hardware is created on the development system by the ADT Installer.
995 The QEMU user-space tools, the
996 NFS boot process, and the cross-toolchain all use the sysroot location.
997 </para></listitem>
998 <listitem><para><emphasis>Select the Target Architecture:</emphasis>
999 The target architecture is the type of hardware you are
1000 going to use or emulate.
1001 Use the pull-down <filename>Target Architecture</filename> menu to make
1002 your selection.
1003 The pull-down menu should have the supported architectures.
1004 If the architecture you need is not listed in the menu, you
1005 will need to build the image.
1006 See the "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section
1007 of The Yocto Project Quick Start for more information.</para></listitem>
1008 </itemizedlist>
1009 </para>
1010 </section>
1011
1012 <section id='configuring-the-target-options'>
1013 <title>Configuring the Target Options</title>
1014
1015 <para>
1016 You can choose to emulate hardware using the QEMU emulator, or you
1017 can choose to run your image on actual hardware.
1018 <itemizedlist>
1019 <listitem><para><emphasis><filename>QEMU:</filename></emphasis> Select this option if
1020 you will be using the QEMU emulator.
1021 If you are using the emulator, you also need to locate the kernel
1022 and specify any custom options.</para>
1023 <para>If you selected <filename>Build system derived toolchain</filename>,
1024 the target kernel you built will be located in the
1025 build directory in <filename>tmp/deploy/images</filename> directory.
1026 If you selected <filename>Standalone pre-built toolchain</filename>, the
1027 pre-built image you downloaded is located
1028 in the directory you specified when you downloaded the image.</para>
1029 <para>Most custom options are for advanced QEMU users to further
1030 customize their QEMU instance.
1031 These options are specified between paired angled brackets.
1032 Some options must be specified outside the brackets.
1033 In particular, the options <filename>serial</filename>,
1034 <filename>nographic</filename>, and <filename>kvm</filename> must all
1035 be outside the brackets.
1036 Use the <filename>man qemu</filename> command to get help on all the options
1037 and their use.
1038 The following is an example:
1039 <literallayout class='monospaced'>
1040 serial ‘&lt;-m 256 -full-screen&gt;’
1041 </literallayout></para>
1042 <para>
1043 Regardless of the mode, Sysroot is already defined as part of the
1044 Cross Compiler Options configuration in the
1045 <filename>Sysroot Location:</filename> field.</para></listitem>
1046 <listitem><para><emphasis><filename>External HW:</filename></emphasis> Select this option
1047 if you will be using actual hardware.</para></listitem>
1048 </itemizedlist>
1049 </para>
1050
1051 <para>
1052 Click the <filename>OK</filename> button to save your plug-in configurations.
1053 </para>
1054 </section>
1055 </section>
1056 </section>
1057
1058 <section id='creating-the-project'>
1059 <title>Creating the Project</title>
1060
1061 <para>
1062 You can create two types of projects: Autotools-based, or Makefile-based.
1063 This section describes how to create Autotools-based projects from within
1064 the Eclipse IDE.
1065 For information on creating Makefile-based projects in a terminal window, see the section
1066 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-command-line'>Using the Command Line</ulink>"
1067 in the Yocto Project Application Developer's Guide.
1068 </para>
1069
1070 <para>
1071 To create a project based on a Yocto template and then display the source code,
1072 follow these steps:
1073 <orderedlist>
1074 <listitem><para>Select <filename>File -&gt; New -&gt; Project</filename>.</para></listitem>
1075 <listitem><para>Double click <filename>CC++</filename>.</para></listitem>
1076 <listitem><para>Double click <filename>C Project</filename> to create the project.</para></listitem>
1077 <listitem><para>Expand <filename>Yocto Project ADT Project</filename>.</para></listitem>
1078 <listitem><para>Select <filename>Hello World ANSI C Autotools Project</filename>.
1079 This is an Autotools-based project based on a Yocto template.</para></listitem>
1080 <listitem><para>Put a name in the <filename>Project name:</filename> field.
1081 Do not use hyphens as part of the name.</para></listitem>
1082 <listitem><para>Click <filename>Next</filename>.</para></listitem>
1083 <listitem><para>Add information in the <filename>Author</filename> and
1084 <filename>Copyright notice</filename> fields.</para></listitem>
1085 <listitem><para>Be sure the <filename>License</filename> field is correct.</para></listitem>
1086 <listitem><para>Click <filename>Finish</filename>.</para></listitem>
1087 <listitem><para>If the "open perspective" prompt appears, click "Yes" so that you
1088 in the C/C++ perspective.</para></listitem>
1089 <listitem><para>The left-hand navigation pane shows your project.
1090 You can display your source by double clicking the project's source file.
1091 </para></listitem>
1092 </orderedlist>
1093 </para>
1094 </section>
1095
1096 <section id='configuring-the-cross-toolchains'>
1097 <title>Configuring the Cross-Toolchains</title>
1098
1099 <para>
1100 The earlier section, "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring
1101 the Eclipse Yocto Plug-in</link>", sets up the default project
1102 configurations.
1103 You can override these settings for a given project by following these steps:
1104 <orderedlist>
1105 <listitem><para>Select <filename>Project -&gt; Change Yocto Project Settings</filename>:
1106 This selection brings up the <filename>Yocot Project Settings</filename> Dialog
1107 and allows you to make changes specific to an individual project.
1108 </para>
1109 <para>By default, the Cross Compiler Options and Target Options for a project
1110 are inherited from settings you provide using the <filename>Preferences</filename>
1111 Dialog as described earlier
1112 in the "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse
1113 Yocto Plug-in</link>" section.
1114 The <filename>Yocto Project Settings</filename>
1115 Dialog allows you to override those default settings
1116 for a given project.</para></listitem>
1117 <listitem><para>Make your configurations for the project and click "OK".</para></listitem>
1118 <listitem><para>Select <filename>Project -&gt; Reconfigure Project</filename>:
1119 This selection reconfigures the project by running
1120 <filename>autogen.sh</filename> in the workspace for your project.
1121 The script also runs <filename>libtoolize</filename>, <filename>aclocal</filename>,
1122 <filename>autoconf</filename>, <filename>autoheader</filename>,
1123 <filename>automake --a</filename>, and
1124 <filename>./configure</filename>.
1125 Click on the <filename>Console</filename> tab beneath your source code to
1126 see the results of reconfiguring your project.</para></listitem>
1127 </orderedlist>
1128 </para>
1129 </section>
1130
1131 <section id='building-the-project'>
1132 <title>Building the Project</title>
1133
1134 <para>
1135 To build the project, select <filename>Project -&gt; Build Project</filename>.
1136 The console should update and you can note the cross-compiler you are using.
1137 </para>
1138 </section>
1139
1140 <section id='starting-qemu-in-user-space-nfs-mode'>
1141 <title>Starting QEMU in User Space NFS Mode</title>
1142
1143 <para>
1144 To start the QEMU emulator from within Eclipse, follow these steps:
1145 <orderedlist>
1146 <listitem><para>Expose the <filename>Run -&gt; External Tools</filename> menu.
1147 Your image should appear as a selectable menu item.
1148 </para></listitem>
1149 <listitem><para>Select your image from the menu to launch the
1150 emulator in a new window.</para></listitem>
1151 <listitem><para>If needed, enter your host root password in the shell window at the prompt.
1152 This sets up a <filename>Tap 0</filename> connection needed for running in user-space
1153 NFS mode.</para></listitem>
1154 <listitem><para>Wait for QEMU to launch.</para></listitem>
1155 <listitem><para>Once QEMU launches, you can begin operating within that
1156 environment.
1157 For example, you could determine the IP Address
1158 for the user-space NFS by using the <filename>ifconfig</filename> command.
1159 </para></listitem>
1160 </orderedlist>
1161 </para>
1162 </section>
1163
1164 <section id='deploying-and-debugging-the-application'>
1165 <title>Deploying and Debugging the Application</title>
1166
1167 <para>
1168 Once the QEMU emulator is running the image, using the Eclipse IDE
1169 you can deploy your application and use the emulator to perform debugging.
1170 Follow these steps to deploy the application.
1171 <orderedlist>
1172 <listitem><para>Select <filename>Run -&gt; Debug Configurations...</filename></para></listitem>
1173 <listitem><para>In the left area, expand <filename>C/C++Remote Application</filename>.</para></listitem>
1174 <listitem><para>Locate your project and select it to bring up a new
1175 tabbed view in the <filename>Debug Configurations</filename> Dialog.</para></listitem>
1176 <listitem><para>Enter the absolute path into which you want to deploy
1177 the application.
1178 Use the <filename>Remote Absolute File Path for C/C++Application:</filename> field.
1179 For example, enter <filename>/usr/bin/&lt;programname&gt;</filename>.</para></listitem>
1180 <listitem><para>Click on the <filename>Debugger</filename> tab to see the cross-tool debugger
1181 you are using.</para></listitem>
1182 <listitem><para>Click on the <filename>Main</filename> tab.</para></listitem>
1183 <listitem><para>Create a new connection to the QEMU instance
1184 by clicking on <filename>new</filename>.</para></listitem>
1185 <listitem><para>Select <filename>TCF</filename>, which means Target Communication
1186 Framework.</para></listitem>
1187 <listitem><para>Click <filename>Next</filename>.</para></listitem>
1188 <listitem><para>Clear out the <filename>host name</filename> field and enter the IP Address
1189 determined earlier.</para></listitem>
1190 <listitem><para>Click <filename>Finish</filename> to close the
1191 <filename>New Connections</filename> Dialog.</para></listitem>
1192 <listitem><para>Use the drop-down menu now in the <filename>Connection</filename> field and pick
1193 the IP Address you entered.</para></listitem>
1194 <listitem><para>Click <filename>Debug</filename> to bring up a login screen
1195 and login.</para></listitem>
1196 <listitem><para>Accept the debug perspective.</para></listitem>
1197 </orderedlist>
1198 </para>
1199 </section>
1200
1201 <section id='running-user-space-tools'>
1202 <title>Running User-Space Tools</title>
1203
1204 <para>
1205 As mentioned earlier in the manual, several tools exist that enhance
1206 your development experience.
1207 These tools are aids in developing and debugging applications and images.
1208 You can run these user-space tools from within the Eclipse IDE through the
1209 <filename>YoctoTools</filename> menu.
1210 </para>
1211
1212 <para>
1213 Once you pick a tool, you need to configure it for the remote target.
1214 Every tool needs to have the connection configured.
1215 You must select an existing TCF-based RSE connection to the remote target.
1216 If one does not exist, click <filename>New</filename> to create one.
1217 </para>
1218
1219 <para>
1220 Here are some specifics about the remote tools:
1221 <itemizedlist>
1222 <listitem><para><emphasis><filename>OProfile</filename>:</emphasis> Selecting this tool causes
1223 the <filename>oprofile-server</filename> on the remote target to launch on
1224 the local host machine.
1225 The <filename>oprofile-viewer</filename> must be installed on the local host machine and the
1226 <filename>oprofile-server</filename> must be installed on the remote target,
1227 respectively, in order to use.
1228 You must compile and install the <filename>oprofile-viewer</filename> from the source code
1229 on your local host machine.
1230 Furthermore, in order to convert the target's sample format data into a form that the
1231 host can use, you must have <filename>oprofile</filename> version 0.9.4 or
1232 greater installed on the host.</para>
1233 <para>You can locate both the viewer and server from
1234 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/oprofileui/'></ulink>.
1235 <note>The <filename>oprofile-server</filename> is installed by default on
1236 the <filename>core-image-sato-sdk</filename> image.</note></para></listitem>
1237 <listitem><para><emphasis><filename>Lttng-ust</filename>:</emphasis> Selecting this tool runs
1238 <filename>usttrace</filename> on the remote target, transfers the output data back
1239 to the local host machine, and uses the <filename>lttng</filename> Eclipse plug-in to
1240 graphically display the output.
1241 For information on how to use <filename>lttng</filename> to trace an application, see
1242 <ulink url='http://lttng.org/files/ust/manual/ust.html'></ulink>.</para>
1243 <para>For <filename>Application</filename>, you must supply the absolute path name of the
1244 application to be traced by user mode <filename>lttng</filename>.
1245 For example, typing <filename>/path/to/foo</filename> triggers
1246 <filename>usttrace /path/to/foo</filename> on the remote target to trace the
1247 program <filename>/path/to/foo</filename>.</para>
1248 <para><filename>Argument</filename> is passed to <filename>usttrace</filename>
1249 running on the remote target.</para>
1250 <para>Before you use the <filename>lttng-ust</filename> tool, you need to setup
1251 the <filename>lttng</filename> Eclipse plug-in and create a <filename>lttng</filename>
1252 project.
1253 Do the following:
1254 <orderedlist>
1255 <listitem><para>Follow these
1256 <ulink url='http://wiki.eclipse.org/Linux_Tools_Project/LTTng#Downloading_and_installing_the_LTTng_parser_library'>instructions</ulink>
1257 to download and install the <filename>lttng</filename> parser library.
1258 </para></listitem>
1259 <listitem><para>Select <filename>Window -> Open Perspective -> Other</filename>
1260 and then select <filename>LTTng</filename>.</para></listitem>
1261 <listitem><para>Click <filename>OK</filename> to change the Eclipse perspective
1262 into the <filename>LTTng</filename> perspective.</para></listitem>
1263 <listitem><para>Create a new <filename>LTTng</filename> project by selecting
1264 <filename>File -> New -> Project</filename>.</para></listitem>
1265 <listitem><para>Choose <filename>LTTng -> LTTng Project</filename>.</para></listitem>
1266 <listitem><para>Click <filename>YoctoTools -> lttng-ust</filename> to start user mode
1267 <filename>lttng</filename> on the remote target.</para></listitem>
1268 </orderedlist></para>
1269 <para>After the output data has been transferred from the remote target back to the local
1270 host machine, new traces will be imported into the selected <filename>LTTng</filename> project.
1271 Then you can go to the <filename>LTTng</filename> project, right click the imported
1272 trace, and set the trace type as the <filename>LTTng</filename> kernel trace.
1273 Finally, right click the imported trace and select <filename>Open</filename>
1274 to display the data graphically.</para></listitem>
1275 <listitem><para><emphasis><filename>PowerTOP</filename>:</emphasis> Selecting this tool runs
1276 <filename>powertop</filename> on the remote target machine and displays the results in a
1277 new view called <filename>powertop</filename>.</para>
1278 <para><filename>Time to gather data(sec):</filename> is the time passed in seconds before data
1279 is gathered from the remote target for analysis.</para>
1280 <para><filename>show pids in wakeups list:</filename> corresponds to the
1281 <filename>-p</filename> argument
1282 passed to <filename>powertop</filename>.</para></listitem>
1283 <listitem><para><emphasis><filename>LatencyTOP and Perf</filename>:</emphasis>
1284 <filename>latencytop</filename> identifies system latency, while
1285 <filename>perf</filename> monitors the system's
1286 performance counter registers.
1287 Selecting either of these tools causes an RSE terminal view to appear
1288 from which you can run the tools.
1289 Both tools refresh the entire screen to display results while they run.</para></listitem>
1290 </itemizedlist>
1291 </para>
1292 </section>
1293
1294 <section id='customizing-an-image-using-a-bitbake-commander-project-and-hob'>
1295 <title>Customizing an Image Using a BitBake Commander Project and Hob</title>
1296
1297 <para>
1298 Within Eclipse, you can create a Yocto BitBake Commander project,
1299 edit the metadata, and then use the
1300 <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink> to build a customized
1301 image all within one IDE.
1302 </para>
1303
1304 <section id='creating-the-yocto-bitbake-commander-project'>
1305 <title>Creating the Yocto BitBake Commander Project</title>
1306
1307 <para>
1308 To create a Yocto BitBake Commander project, follow these steps:
1309 <orderedlist>
1310 <listitem><para>Select <filename>Window -> Open Perspective -> Other</filename>
1311 and then choose <filename>Bitbake Commander</filename>.</para></listitem>
1312 <listitem><para>Click <filename>OK</filename> to change the Eclipse perspective into the
1313 Bitbake Commander perspective.</para></listitem>
1314 <listitem><para>Select <filename>File -> New -> Project</filename> to create a new Yocto
1315 Bitbake Commander project.</para></listitem>
1316 <listitem><para>Choose <filename>Yocto Project Bitbake Commander -> New Yocto Project</filename>
1317 and click <filename>Next</filename>.</para></listitem>
1318 <listitem><para>Enter the Project Name and choose the Project Location.
1319 The Yocto project's metadata files will be put under the directory
1320 <filename>&lt;project_location&gt;/&lt;project_name&gt;</filename>.
1321 If that directory does not exist, you need to check
1322 the "Clone from Yocto Git Repository" box, which would execute a
1323 <filename>git clone</filename> command to get the project's metadata files.
1324 </para></listitem>
1325 <listitem><para>Select <filename>Finish</filename> to create the project.</para></listitem>
1326 </orderedlist>
1327 </para>
1328 </section>
1329
1330 <section id='editing-the-metadata-files'>
1331 <title>Editing the Metadata Files</title>
1332
1333 <para>
1334 After you create the Yocto Bitbake Commander project, you can modify the metadata files
1335 by opening them in the project.
1336 When editing recipe files (<filename>.bb</filename> files), you can view BitBake
1337 variable values and information by hovering the mouse pointer over the variable name and
1338 waiting a few seconds.
1339 </para>
1340
1341 <para>
1342 To edit the metadata, follow these steps:
1343 <orderedlist>
1344 <listitem><para>Select your Yocto Bitbake Commander project.</para></listitem>
1345 <listitem><para>Select <filename>File -> New -> Yocto BitBake Commander -> BitBake Recipe</filename>
1346 to open a new recipe wizard.</para></listitem>
1347 <listitem><para>Point to your source by filling in the "SRC_URL" field.
1348 For example, you can add a recipe to your
1349 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>
1350 by defining "SRC_URL" as follows:
1351 <literallayout class='monospaced'>
1352 ftp://ftp.gnu.org/gnu/m4/m4-1.4.9.tar.gz
1353 </literallayout></para></listitem>
1354 <listitem><para>Click "Populate" to calculate the archive md5, sha256,
1355 license checksum values and to auto-generate the recipe filename.</para></listitem>
1356 <listitem><para>Fill in the "Description" field.</para></listitem>
1357 <listitem><para>Be sure values for all required fields exist.</para></listitem>
1358 <listitem><para>Click <filename>Finish</filename>.</para></listitem>
1359 </orderedlist>
1360 </para>
1361 </section>
1362
1363 <section id='buiding-and-customizing-the-image'>
1364 <title>Building and Customizing the Image</title>
1365
1366 <para>
1367 To build and customize the image in Eclipse, follow these steps:
1368 <orderedlist>
1369 <listitem><para>Select your Yocto Bitbake Commander project.</para></listitem>
1370 <listitem><para>Select <filename>Project -> Launch HOB</filename>.</para></listitem>
1371 <listitem><para>Enter the build directory where you want to put your final images.</para></listitem>
1372 <listitem><para>Click <filename>OK</filename> to launch Hob.</para></listitem>
1373 <listitem><para>Use Hob to customize and build your own images.
1374 For information on Hob, see the
1375 <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob Project Page</ulink> on the
1376 Yocto Project website.</para></listitem>
1377 </orderedlist>
1378 </para>
1379 </section>
1380 </section>
1381 </section>
1382
644 <section id='workflow-using-stand-alone-cross-development-toolchains'> 1383 <section id='workflow-using-stand-alone-cross-development-toolchains'>
645 <title>Workflow Using Stand-alone Cross-development Toolchains</title> 1384 <title>Workflow Using Stand-alone Cross-development Toolchains</title>
646 1385