summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2011-10-03 07:42:20 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2011-10-04 13:46:44 +0100
commit47b82c7db8ec96a81e7bec196b218d16345b1e4c (patch)
treec12ca463cb50f328345f66572039b651f7b8d3cc /documentation
parent00f99ccfe81038ed6dc517306582c27416b14a80 (diff)
downloadpoky-47b82c7db8ec96a81e7bec196b218d16345b1e4c.tar.gz
documentation/poky-ref-manual/extendpoky.xml: multilib edits
Feedback from Richard Purdie inserted. I made an edit pass for style to Richard's re-write. (From yocto-docs rev: e5bb08e966614c610e6357642b3b2d1522332f7f) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/poky-ref-manual/extendpoky.xml222
1 files changed, 133 insertions, 89 deletions
diff --git a/documentation/poky-ref-manual/extendpoky.xml b/documentation/poky-ref-manual/extendpoky.xml
index 1f14d7c9b0..33e397a5f5 100644
--- a/documentation/poky-ref-manual/extendpoky.xml
+++ b/documentation/poky-ref-manual/extendpoky.xml
@@ -1073,14 +1073,36 @@
1073 </section> 1073 </section>
1074 1074
1075 <section id="building-multiple-architecture-libraries-into-one-image"> 1075 <section id="building-multiple-architecture-libraries-into-one-image">
1076 <title>Building Multiple Architecture Libraries into One Image</title> 1076 <title>Combining Multiple versions of Library Files into One Image</title>
1077 1077
1078 <para>
1079 The build system offers the ability to build libraries with different
1080 target optimizations or architecture formats and combine these together
1081 into one system image.
1082 You can link different binaries in the image
1083 against the different libraries as needed for specific use cases.
1084 This feature is called "Multilib."
1085 </para>
1086
1087 <para>
1088 An example would be where you have most of a system compiled in 32-bit
1089 mode using 32-bit libraries, but you have something large, like a database
1090 engine, that needs to be a 64-bit application and use 64-bit libraries.
1091 Multilib allows you to get the best of both 32-bit and 64-bit libraries.
1092 </para>
1093
1094 <para>
1095 While the Multilib feature is most commonly used for 32 and 64-bit differences,
1096 the approach the build system uses facilitates different target optimizations.
1097 You could compile some binaries to use one set of libraries and other binaries
1098 to use other different sets of libraries.
1099 The libraries could differ in architecture, compiler options, or other
1100 optimizations.
1101 </para>
1102
1078 <para> 1103 <para>
1079 By taking steps you can create a single image that contains more than 1104 This section overviews the Multilib process only.
1080 one library for different architectures. 1105 For more details on how to implement Multilib, see the
1081 This feature is called "Multilib".
1082 This section overviews the process only.
1083 For more detail on how to implement this feature, see the
1084 <ulink url='https://wiki.yoctoproject.org/wiki/Multilib'>Multilib</ulink> wiki 1106 <ulink url='https://wiki.yoctoproject.org/wiki/Multilib'>Multilib</ulink> wiki
1085 page. 1107 page.
1086 </para> 1108 </para>
@@ -1089,107 +1111,129 @@
1089 <title>Preparing to use Multilib</title> 1111 <title>Preparing to use Multilib</title>
1090 1112
1091 <para> 1113 <para>
1092 In order to implement Multilib, you need to prepare your recipes and packages as 1114 User-specific requirements drive the Multilib feature,
1093 follows: 1115 Consequently, there is no one "out-of-the-box" configuration that likely
1094 <itemizedlist> 1116 exists to meet your needs.
1095 <listitem><para>Use the <filename>BBCLASSEXTEND</filename> variable to enable
1096 a recipe for Multilib.
1097 See the <filename>meta/conf/multilib.conf</filename> configuration file
1098 in the Yocto Project Files directory to see how this variable is used.
1099 </para></listitem>
1100 <listitem><para>Define a global variable <filename>${MLPREFIX}</filename>
1101 to specify the libraries (e.g. "<filename>lib32-'</filename>" or
1102 "<filename>lib64-</filename>").</para></listitem>
1103 <listitem><para>Rename your recipe to be <filename>${MLPREFIX}${PN}</filename>.
1104 </para></listitem>
1105 <listitem><para>For any recipe that uses Multilib and specifies lists of
1106 recipes or packages with variables such as <filename>DEPENDS</filename>,
1107 <filename>RDEPENDS</filename>,
1108 <filename>RPROVIDES</filename>, <filename>RRECOMMENDS</filename>,
1109 <filename>PACKAGES</filename>, <filename>PACKAGES_DYNAMIC</filename>,
1110 map those recipes or packages with <filename>${MLPREFIX}</filename>.
1111 </para></listitem>
1112 </itemizedlist>
1113 </para> 1117 </para>
1114 1118
1115 <para> 1119 <para>
1116 Next, be sure that the correct cross-toolchain parameters are used 1120 In order to enable Multilib, you first need to ensure your recipe is
1117 by setting <filename>DEFAULTTUNE_virtclass-multilib-xxx</filename> 1121 extended to support multiple libraries.
1118 in the <filename>local.conf</filename> configuration file in the 1122 Many standard recipes are already extended and support multiple libraries.
1119 Yocto Project build directory. 1123 You can check in the <filename>meta/conf/multilib.conf</filename>
1124 configuration file in the Yocto Project files directory to see how this is
1125 done using the <filename>BBCLASSEXTEND</filename> variable.
1126 Eventually, all recipes will be covered and this list will be unneeded.
1127 </para>
1128
1129 <para>
1130 For the most part, the Multilib class extension works automatically to
1131 extend the package name from <filename>${PN}</filename> to
1132 <filename>${MLPREFIX}${PN}</filename>, where <filename>MLPREFIX</filename>
1133 is the particular multilib (e.g. "lib32-" or "lib64-").
1134 Standard variables such as <filename>DEPENDS</filename>,
1135 <filename>RDEPENDS</filename>, <filename>RPROVIDES</filename>,
1136 <filename>RRECOMMENDS</filename>, <filename>PACKAGES</filename>, and
1137 <filename>PACKAGES_DYNAMIC</filename> are automatically extended by the system.
1138 If you are extending any manual code in the recipe, you can use the
1139 <filename>${MLPREFIX}</filename> variable to ensure those names are extended
1140 correctly.
1141 This automatic extension code resides in <filename>multilib.bbclass</filename>.
1120 </para> 1142 </para>
1143 </section>
1144
1145 <section id='using-multilib'>
1146 <title>Using Multilib</title>
1121 1147
1122 <para> 1148 <para>
1123 If you are using the RPM Package Management System, you need to consider the 1149 After you have set up the recipes, you need to define the actual
1124 following: 1150 combination of multiple libraries you want to build.
1151 You accomplish this through your <filename>local.conf</filename>
1152 configuration file in the Yocto Project build directory.
1153 An example configuration would be as follows:
1154 <literallayout class='monospaced'>
1155 MACHINE = "qemux86-64"
1156 require conf/multilib.conf
1157 MULTILIBS = "multilib:lib32"
1158 DEFAULTTUNE_virtclass-multilib-lib32 = "x86"
1159 MULTILIB_IMAGE_INSTALL = "lib32-connman"
1160 </literallayout>
1161 This example enables an
1162 additional library named <filename>lib32</filename> alongside the
1163 normal target packages.
1164 When combining these "lib32" alternatives, the example uses "x86" for tuning.
1165 For information on this particular tuning, see
1166 <filename>meta/conf/machine/include/ia32/arch-ia32.inc</filename>.
1167 </para>
1168
1169 <para>
1170 The example then includes <filename>lib32-connman</filename>
1171 in all the images, which illustrates one method of including a
1172 multiple library dependency.
1173 You can use a normal image build to include this dependency,
1174 for example:
1175 <literallayout class='monospaced'>
1176 $ bitbake core-image-sato
1177 </literallayout>
1178 You can also build Multilib packages specifically with a command like this:
1179 <literallayout class='monospaced'>
1180 $ bitbake lib32-connman
1181 </literallayout>
1182 </para>
1183 </section>
1184
1185 <section id='additional-implementation-details'>
1186 <title>Additional Implementation Details</title>
1187
1188 <para>
1189 Different packaging systems have different levels of native Multilib
1190 support.
1191 For the RPM Package Management System, the following implementation details
1192 exist:
1125 <itemizedlist> 1193 <itemizedlist>
1126 <listitem><para>Define the unique architecure for the Multilib packages, along with 1194 <listitem><para>A unique architecture is defined for the Multilib packages,
1127 creating a unique deploy folder under <filename>tmp/deploy/rpm</filename> in 1195 along with creating a unique deploy folder under
1128 the Yocto Project build directory. 1196 <filename>tmp/deploy/rpm</filename> in the Yocto
1197 Project build directory.
1129 For example, consider <filename>lib32</filename> in a 1198 For example, consider <filename>lib32</filename> in a
1130 <filename>qemux86-64</filename> image. 1199 <filename>qemux86-64</filename> image.
1131 The possible architectures in the system are "all", "qemux86_64", "lib32_qemux86_64", 1200 The possible architectures in the system are "all", "qemux86_64",
1132 and "lib32_x86".</para></listitem> 1201 "lib32_qemux86_64", and "lib32_x86".</para></listitem>
1133 <listitem><para>Because the <filename>${MLPREFIX}</filename> is stripped from 1202 <listitem><para>The <filename>${MLPREFIX}</filename> variable is stripped from
1134 <filename>${PN}</filename> during RPM packaging, the naming for a normal 1203 <filename>${PN}</filename> during RPM packaging.
1135 RPM package and a Multilib RPM package in a <filename>qemux86-64</filename> 1204 The naming for a normal RPM package and a Multilib RPM package in a
1136 system resolves to something similar to <filename>bash-4.1-r2.x86_64.rpm</filename> and 1205 <filename>qemux86-64</filename> system resolves to something similar to
1137 <filename>bash-4.1.r2.lib32_x86.rpm</filename>, respectively.</para></listitem> 1206 <filename>bash-4.1-r2.x86_64.rpm</filename> and
1138 <listitem><para>When installing a Multilib image, the RPM backend first installs 1207 <filename>bash-4.1.r2.lib32_x86.rpm</filename>, respectively.
1139 the base image and then installs the Multilib libraries.</para></listitem> 1208 </para></listitem>
1209 <listitem><para>When installing a Multilib image, the RPM backend first
1210 installs the base image and then installs the Multilib libraries.
1211 </para></listitem>
1212 <listitem><para>The build system relies on RPM to resolve the identical files in the
1213 two (or more) Multilib packages.</para></listitem>
1140 </itemizedlist> 1214 </itemizedlist>
1141 </para> 1215 </para>
1142 1216
1143 <para> 1217 <para>
1144 If you are using the IPK Package Management System, you need to consider the 1218 For the IPK Package Management System, the following implementation details exist:
1145 following:
1146 <itemizedlist> 1219 <itemizedlist>
1147 <listitem><para><filename>${MLPREFIX}</filename> is not stripped from 1220 <listitem><para>The <filename>${MLPREFIX}</filename> is not stripped from
1148 <filename>${PN}</filename> during IPK packaging, the naming for a normal 1221 <filename>${PN}</filename> during IPK packaging.
1149 RPM package and a Multilib IPK package in a <filename>qemux86-64</filename> 1222 The naming for a normal RPM package and a Multilib IPK package in a
1150 system resolves to something like <filename>bash_4.1-r2.x86_64.ipk</filename> and 1223 <filename>qemux86-64</filename> system resolves to something like
1151 <filename>lib32-bash_4.1-rw_x86.ipk</filename>, respectively.</para></listitem> 1224 <filename>bash_4.1-r2.x86_64.ipk</filename> and
1225 <filename>lib32-bash_4.1-rw_x86.ipk</filename>, respectively.
1226 </para></listitem>
1152 <listitem><para>The IPK deploy folder is not modified with 1227 <listitem><para>The IPK deploy folder is not modified with
1153 <filename>${MLPREFIX}</filename> because packages with and without 1228 <filename>${MLPREFIX}</filename> because packages with and without
1154 the Multilib feature can exist in the same folder due to the 1229 the Multilib feature can exist in the same folder due to the
1155 <filename>${PN}</filename> differences.</para></listitem> 1230 <filename>${PN}</filename> differences.</para></listitem>
1156 <listitem><para>IPK defines a sanity check for Multilib installation using certain 1231 <listitem><para>IPK defines a sanity check for Multilib installation
1157 rules for file comparison, overridden, etc.</para></listitem> 1232 using certain rules for file comparison, overridden, etc.
1233 </para></listitem>
1158 </itemizedlist> 1234 </itemizedlist>
1159 </para> 1235 </para>
1160 </section> 1236 </section>
1161
1162 <section id='using-multilib'>
1163 <title>Using Multilib</title>
1164
1165 <para>
1166 After you have set up the recipies and configurations to use the Multilib feature,
1167 you are ready to build the image.
1168 Follow these steps:
1169 <orderedlist>
1170 <listitem><para>Make changes in your <filename>local.conf</filename>
1171 configuration file in the Yocto Project build directory.
1172 Here is an example:
1173 <literallayout class='monospaced'>
1174 MULTILIB_IMAGE(INSTALL = "lib32-connman"
1175 require conf/multilib.con
1176 MULTILIBS = "multilib:lib32"
1177 DEFAULTTUNE_virtclass-multilib-lib32 = "x86"
1178 </literallayout></para></listitem>
1179 <listitem><para>Build the image using the BitBake command.
1180 For example:
1181 <literallayout class='monospaced'>
1182 $ bitbake core-image-sato
1183 </literallayout>
1184 If you want to build a particular recipe only,
1185 use the BitBake command and specify the recipe only.
1186 For example:
1187 <literallayout class='monospaced'>
1188 $ bitbake lib32-connman
1189 </literallayout></para></listitem>
1190 </orderedlist>
1191 </para>
1192 </section>
1193 </section> 1237 </section>
1194 1238
1195 <section id="usingpoky-configuring-LIC_FILES_CHKSUM"> 1239 <section id="usingpoky-configuring-LIC_FILES_CHKSUM">