summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2013-09-09 13:36:30 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2013-09-12 16:50:09 +0100
commit7b70da93bc86b5aa6a9907c7e9f370932ff709ec (patch)
tree00fbad6db626ce0231d4816ce1332b22e0820d9f
parentb359e9a981047976a48889e1f030db7f9b06b7e4 (diff)
downloadpoky-7b70da93bc86b5aa6a9907c7e9f370932ff709ec.tar.gz
ref-manual: Re-ordered flow for detailed process sections.
Fixes [YOCTO #2808] Based on feedback from Dave Stewart, I have rearranged the sub- section flow of the topics to match that of an actual build. This meant moving the BitBake section higher up in the order. (From yocto-docs rev: 3e62dd70dab596c3a55815c1ad3f1578a9f3400f) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/ref-manual/technical-details.xml434
1 files changed, 217 insertions, 217 deletions
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index 4a6c3b2a6e..bfab8a6c68 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -743,223 +743,6 @@
743 </section> 743 </section>
744 </section> 744 </section>
745 745
746 <section id="package-feeds-dev-environment">
747 <title>Package Feeds</title>
748
749 <para>
750 When the OpenEmbedded build system generates an image or an SDK,
751 it gets the packages from a package feed area located in the
752 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
753 The main
754 <link linkend='a-closer-look-at-the-yocto-project-development-environment'>Yocto Project Development Environment</link>
755 figure shows this package feeds area in the upper-right corner.
756 </para>
757
758 <para>
759 This section looks a little closer into the package feeds area used
760 by the build system.
761 Here is a more detailed look at the area:
762 <imagedata fileref="figures/package-feeds.png" align="center" width="7in" depth="6in" />
763 </para>
764
765 <para>
766 Package feeds are an intermediary step in the build process.
767 BitBake generates packages whose type is defined by the
768 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
769 variable.
770 Before placing the packages into package feeds,
771 the build process validates them with generated output quality
772 assurance checks through the
773 <link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>
774 class.
775 </para>
776
777 <para>
778 The package feed area resides in
779 <filename>tmp/deploy</filename> of the Build Directory.
780 Folders are created that correspond to the package type
781 (IPK, DEB, or RPM) created.
782 Further organization is derived through the value of the
783 <link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link>
784 variable for each package.
785 For example, packages can exist for the i586 or qemux86
786 architectures.
787 The package files themselves reside within the appropriate
788 architecture folder.
789 </para>
790
791 <para>
792 BitBake uses the <filename>do_package_write_*</filename> task to
793 place generated packages into the package holding area (e.g.
794 <filename>do_package_write_ipk</filename> for IPK packages).
795 </para>
796 </section>
797
798 <section id='images-dev-environment'>
799 <title>Images</title>
800
801 <para>
802 The images produced by the OpenEmbedded build system
803 are compressed forms of the
804 root filesystems that are ready to boot on a target device.
805 You can see from the main
806 <link linkend='a-closer-look-at-the-yocto-project-development-environment'>Yocto Project Development Environment</link>
807 figure that BitBake output in part consists of images.
808 This section is going to look more closely at this output:
809 <imagedata fileref="figures/images.png" align="center" width="6in" depth="5in" />
810 </para>
811
812 <para>
813 For a list of example images that the Yocto Project provides,
814 the
815 "<link linkend='ref-images'>Images</link>" chapter.
816 </para>
817
818 <para>
819 Images are written out to the
820 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
821 inside the <filename>deploy/images</filename> folder as shown
822 in the figure.
823 This folder contains any files expected to be loaded on the
824 target device.
825 The
826 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
827 variable points to the <filename>deploy</filename> directory.
828 <itemizedlist>
829 <listitem><para><filename>&lt;kernel-image&gt;</filename>:
830 A kernel binary file.
831 The <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>
832 variable setting determines the naming scheme for the
833 kernel image file.
834 Depending on that variable, the file could begin with
835 a variety of naming strings.
836 The <filename>deploy/images</filename> directory can
837 contain multiple image files.</para></listitem>
838 <listitem><para><filename>&lt;root-filesystem-image&gt;</filename>:
839 Root filesystems for the target device (e.g.
840 <filename>*.ext3</filename> or <filename>*.bz2</filename>
841 files).
842 The <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
843 variable setting determines the root filesystem image
844 type.
845 The <filename>deploy/images</filename> directory can
846 contain multiple root filesystems.</para></listitem>
847 <listitem><para><filename>&lt;kernel-modules&gt;</filename>:
848 Tarballs that contain all the modules built for the kernel.
849 Kernel module tarballs exist for legacy purposes and
850 can be suppressed by setting the
851 <link linkend='var-MODULE_TARBALL_DEPLOY'><filename>MODULE_TARBALL_DEPLOY</filename></link>
852 variable to "0".
853 The <filename>deploy/images</filename> directory can
854 contain multiple kernel module tarballs.
855 </para></listitem>
856 <listitem><para><filename>&lt;bootloaders&gt;</filename>:
857 Bootloaders supporting the image, if applicable to the
858 target machine.
859 The <filename>deploy/images</filename> directory can
860 contain multiple bootloaders.
861 </para></listitem>
862 <listitem><para><filename>&lt;symlinks&gt;</filename>:
863 The <filename>deploy/images</filename> folder contains
864 a symbolic link that points to the most recently built file
865 for each machine.
866 These links might be useful for external scripts that
867 need to obtain the latest version of each file.
868 </para></listitem>
869 </itemizedlist>
870 </para>
871 </section>
872
873 <section id='sdk-dev-environment'>
874 <title>Application Development SDK</title>
875
876 <para>
877 In the overview figure of the
878 <link linkend='a-closer-look-at-the-yocto-project-development-environment'>Yocto Project Development Environment</link>
879 the output labeled "Application Development SDK" represents an
880 SDK.
881 This section is going to take a closer look at this output:
882 <imagedata fileref="figures/sdk.png" align="center" width="5in" depth="4in" />
883 </para>
884
885 <para>
886 The specific form of this output is a self-extracting
887 SDK installer (<filename>*.sh</filename>) that, when run,
888 installs the SDK, which consists of a cross-development
889 toolchain, a set of libraries and headers, and an SDK
890 environment setup script.
891 Running this installer essentially sets up your
892 cross-development environment.
893 You can think of the cross-toolchain as the "host"
894 part because it runs on the SDK machine.
895 You can think of the libraries and headers as the "target"
896 part because they are built for the target hardware.
897 The setup script is added so that you can initialize the
898 environment before using the tools.
899 </para>
900
901 <note>
902 <para>
903 The Yocto Project supports several methods by which you can
904 set up this cross-development environment.
905 These methods include downloading pre-built SDK installers,
906 building and installing your own SDK installer, or running
907 an Application Development Toolkit (ADT) installer to
908 install not just cross-development toolchains
909 but also additional tools to help in this type of
910 development.
911 </para>
912
913 <para>
914 For background information on cross-development toolchains
915 in the Yocto Project development environment, see the
916 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
917 section.
918 For information on setting up a cross-development
919 environment, see the
920 "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
921 section in the Yocto Project Application Developer's Guide.
922 </para>
923 </note>
924
925 <para>
926 Once built, the SDK installers are written out to the
927 <filename>deploy/sdk</filename> folder inside the
928 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
929 as shown in the figure at the beginning of this section.
930 Several variables exist that help configure these files:
931 <itemizedlist>
932 <listitem><para><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
933 Points to the <filename>deploy</filename>
934 directory.</para></listitem>
935 <listitem><para><link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>:
936 Specifies the architecture of the machine
937 on which the cross-development tools are run to
938 create packages for the target hardware.
939 </para></listitem>
940 <listitem><para><link linkend='var-SDKIMAGE_FEATURES'><filename>SDKIMAGE_FEATURES</filename></link>:
941 Lists the features to include in the "target" part
942 of the SDK.
943 </para></listitem>
944 <listitem><para><link linkend='var-TOOLCHAIN_HOST_TASK'><filename>TOOLCHAIN_HOST_TASK</filename></link>:
945 Lists packages that make up the host
946 part of the SDK (i.e. the part that runs on
947 the <filename>SDKMACHINE</filename>).
948 When you use
949 <filename>bitbake -c populate_sdk &lt;imagename&gt;</filename>
950 to create the SDK, a set of default packages
951 apply.
952 This variable allows you to add more packages.
953 </para></listitem>
954 <listitem><para><link linkend='var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></link>:
955 Lists packages that make up the target part
956 of the SDK (i.e. the part built for the
957 target hardware).
958 </para></listitem>
959 </itemizedlist>
960 </para>
961 </section>
962
963 <section id='bitbake-dev-environment'> 746 <section id='bitbake-dev-environment'>
964 <title>BitBake</title> 747 <title>BitBake</title>
965 748
@@ -1190,6 +973,223 @@
1190 </para> 973 </para>
1191 </section> 974 </section>
1192 </section> 975 </section>
976
977 <section id="package-feeds-dev-environment">
978 <title>Package Feeds</title>
979
980 <para>
981 When the OpenEmbedded build system generates an image or an SDK,
982 it gets the packages from a package feed area located in the
983 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
984 The main
985 <link linkend='a-closer-look-at-the-yocto-project-development-environment'>Yocto Project Development Environment</link>
986 figure shows this package feeds area in the upper-right corner.
987 </para>
988
989 <para>
990 This section looks a little closer into the package feeds area used
991 by the build system.
992 Here is a more detailed look at the area:
993 <imagedata fileref="figures/package-feeds.png" align="center" width="7in" depth="6in" />
994 </para>
995
996 <para>
997 Package feeds are an intermediary step in the build process.
998 BitBake generates packages whose type is defined by the
999 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
1000 variable.
1001 Before placing the packages into package feeds,
1002 the build process validates them with generated output quality
1003 assurance checks through the
1004 <link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>
1005 class.
1006 </para>
1007
1008 <para>
1009 The package feed area resides in
1010 <filename>tmp/deploy</filename> of the Build Directory.
1011 Folders are created that correspond to the package type
1012 (IPK, DEB, or RPM) created.
1013 Further organization is derived through the value of the
1014 <link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link>
1015 variable for each package.
1016 For example, packages can exist for the i586 or qemux86
1017 architectures.
1018 The package files themselves reside within the appropriate
1019 architecture folder.
1020 </para>
1021
1022 <para>
1023 BitBake uses the <filename>do_package_write_*</filename> task to
1024 place generated packages into the package holding area (e.g.
1025 <filename>do_package_write_ipk</filename> for IPK packages).
1026 </para>
1027 </section>
1028
1029 <section id='images-dev-environment'>
1030 <title>Images</title>
1031
1032 <para>
1033 The images produced by the OpenEmbedded build system
1034 are compressed forms of the
1035 root filesystems that are ready to boot on a target device.
1036 You can see from the main
1037 <link linkend='a-closer-look-at-the-yocto-project-development-environment'>Yocto Project Development Environment</link>
1038 figure that BitBake output in part consists of images.
1039 This section is going to look more closely at this output:
1040 <imagedata fileref="figures/images.png" align="center" width="6in" depth="5in" />
1041 </para>
1042
1043 <para>
1044 For a list of example images that the Yocto Project provides,
1045 the
1046 "<link linkend='ref-images'>Images</link>" chapter.
1047 </para>
1048
1049 <para>
1050 Images are written out to the
1051 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1052 inside the <filename>deploy/images</filename> folder as shown
1053 in the figure.
1054 This folder contains any files expected to be loaded on the
1055 target device.
1056 The
1057 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
1058 variable points to the <filename>deploy</filename> directory.
1059 <itemizedlist>
1060 <listitem><para><filename>&lt;kernel-image&gt;</filename>:
1061 A kernel binary file.
1062 The <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>
1063 variable setting determines the naming scheme for the
1064 kernel image file.
1065 Depending on that variable, the file could begin with
1066 a variety of naming strings.
1067 The <filename>deploy/images</filename> directory can
1068 contain multiple image files.</para></listitem>
1069 <listitem><para><filename>&lt;root-filesystem-image&gt;</filename>:
1070 Root filesystems for the target device (e.g.
1071 <filename>*.ext3</filename> or <filename>*.bz2</filename>
1072 files).
1073 The <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
1074 variable setting determines the root filesystem image
1075 type.
1076 The <filename>deploy/images</filename> directory can
1077 contain multiple root filesystems.</para></listitem>
1078 <listitem><para><filename>&lt;kernel-modules&gt;</filename>:
1079 Tarballs that contain all the modules built for the kernel.
1080 Kernel module tarballs exist for legacy purposes and
1081 can be suppressed by setting the
1082 <link linkend='var-MODULE_TARBALL_DEPLOY'><filename>MODULE_TARBALL_DEPLOY</filename></link>
1083 variable to "0".
1084 The <filename>deploy/images</filename> directory can
1085 contain multiple kernel module tarballs.
1086 </para></listitem>
1087 <listitem><para><filename>&lt;bootloaders&gt;</filename>:
1088 Bootloaders supporting the image, if applicable to the
1089 target machine.
1090 The <filename>deploy/images</filename> directory can
1091 contain multiple bootloaders.
1092 </para></listitem>
1093 <listitem><para><filename>&lt;symlinks&gt;</filename>:
1094 The <filename>deploy/images</filename> folder contains
1095 a symbolic link that points to the most recently built file
1096 for each machine.
1097 These links might be useful for external scripts that
1098 need to obtain the latest version of each file.
1099 </para></listitem>
1100 </itemizedlist>
1101 </para>
1102 </section>
1103
1104 <section id='sdk-dev-environment'>
1105 <title>Application Development SDK</title>
1106
1107 <para>
1108 In the overview figure of the
1109 <link linkend='a-closer-look-at-the-yocto-project-development-environment'>Yocto Project Development Environment</link>
1110 the output labeled "Application Development SDK" represents an
1111 SDK.
1112 This section is going to take a closer look at this output:
1113 <imagedata fileref="figures/sdk.png" align="center" width="5in" depth="4in" />
1114 </para>
1115
1116 <para>
1117 The specific form of this output is a self-extracting
1118 SDK installer (<filename>*.sh</filename>) that, when run,
1119 installs the SDK, which consists of a cross-development
1120 toolchain, a set of libraries and headers, and an SDK
1121 environment setup script.
1122 Running this installer essentially sets up your
1123 cross-development environment.
1124 You can think of the cross-toolchain as the "host"
1125 part because it runs on the SDK machine.
1126 You can think of the libraries and headers as the "target"
1127 part because they are built for the target hardware.
1128 The setup script is added so that you can initialize the
1129 environment before using the tools.
1130 </para>
1131
1132 <note>
1133 <para>
1134 The Yocto Project supports several methods by which you can
1135 set up this cross-development environment.
1136 These methods include downloading pre-built SDK installers,
1137 building and installing your own SDK installer, or running
1138 an Application Development Toolkit (ADT) installer to
1139 install not just cross-development toolchains
1140 but also additional tools to help in this type of
1141 development.
1142 </para>
1143
1144 <para>
1145 For background information on cross-development toolchains
1146 in the Yocto Project development environment, see the
1147 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
1148 section.
1149 For information on setting up a cross-development
1150 environment, see the
1151 "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
1152 section in the Yocto Project Application Developer's Guide.
1153 </para>
1154 </note>
1155
1156 <para>
1157 Once built, the SDK installers are written out to the
1158 <filename>deploy/sdk</filename> folder inside the
1159 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1160 as shown in the figure at the beginning of this section.
1161 Several variables exist that help configure these files:
1162 <itemizedlist>
1163 <listitem><para><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
1164 Points to the <filename>deploy</filename>
1165 directory.</para></listitem>
1166 <listitem><para><link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>:
1167 Specifies the architecture of the machine
1168 on which the cross-development tools are run to
1169 create packages for the target hardware.
1170 </para></listitem>
1171 <listitem><para><link linkend='var-SDKIMAGE_FEATURES'><filename>SDKIMAGE_FEATURES</filename></link>:
1172 Lists the features to include in the "target" part
1173 of the SDK.
1174 </para></listitem>
1175 <listitem><para><link linkend='var-TOOLCHAIN_HOST_TASK'><filename>TOOLCHAIN_HOST_TASK</filename></link>:
1176 Lists packages that make up the host
1177 part of the SDK (i.e. the part that runs on
1178 the <filename>SDKMACHINE</filename>).
1179 When you use
1180 <filename>bitbake -c populate_sdk &lt;imagename&gt;</filename>
1181 to create the SDK, a set of default packages
1182 apply.
1183 This variable allows you to add more packages.
1184 </para></listitem>
1185 <listitem><para><link linkend='var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></link>:
1186 Lists packages that make up the target part
1187 of the SDK (i.e. the part built for the
1188 target hardware).
1189 </para></listitem>
1190 </itemizedlist>
1191 </para>
1192 </section>
1193</section> 1193</section>
1194 1194
1195<section id="cross-development-toolchain-generation"> 1195<section id="cross-development-toolchain-generation">