From 2a68be025b143a201c2ec9684c8088d169c8b4d4 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 3 Oct 2011 07:42:20 -0700 Subject: [PATCH] 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 Signed-off-by: Richard Purdie --- documentation/poky-ref-manual/extendpoky.xml | 228 +++++++++++-------- 1 file changed, 136 insertions(+), 92 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 @@
- Building Multiple Architecture Libraries into One Image - + Combining Multiple versions of Library Files into One Image + - By taking steps you can create a single image that contains more than - one library for different architectures. - This feature is called "Multilib". - This section overviews the process only. - For more detail on how to implement this feature, see the + The build system offers the ability to build libraries with different + target optimizations or architecture formats and combine these together + into one system image. + You can link different binaries in the image + against the different libraries as needed for specific use cases. + This feature is called "Multilib." + + + + An example would be where you have most of a system compiled in 32-bit + mode using 32-bit libraries, but you have something large, like a database + engine, that needs to be a 64-bit application and use 64-bit libraries. + Multilib allows you to get the best of both 32-bit and 64-bit libraries. + + + + While the Multilib feature is most commonly used for 32 and 64-bit differences, + the approach the build system uses facilitates different target optimizations. + You could compile some binaries to use one set of libraries and other binaries + to use other different sets of libraries. + The libraries could differ in architecture, compiler options, or other + optimizations. + + + + This section overviews the Multilib process only. + For more details on how to implement Multilib, see the Multilib wiki page. @@ -1089,105 +1111,127 @@ Preparing to use Multilib - In order to implement Multilib, you need to prepare your recipes and packages as - follows: - - Use the BBCLASSEXTEND variable to enable - a recipe for Multilib. - See the meta/conf/multilib.conf configuration file - in the Yocto Project Files directory to see how this variable is used. - - Define a global variable ${MLPREFIX} - to specify the libraries (e.g. "lib32-'" or - "lib64-"). - Rename your recipe to be ${MLPREFIX}${PN}. - - For any recipe that uses Multilib and specifies lists of - recipes or packages with variables such as DEPENDS, - RDEPENDS, - RPROVIDES, RRECOMMENDS, - PACKAGES, PACKAGES_DYNAMIC, - map those recipes or packages with ${MLPREFIX}. - - + User-specific requirements drive the Multilib feature, + Consequently, there is no one "out-of-the-box" configuration that likely + exists to meet your needs. - Next, be sure that the correct cross-toolchain parameters are used - by setting DEFAULTTUNE_virtclass-multilib-xxx - in the local.conf configuration file in the - Yocto Project build directory. + In order to enable Multilib, you first need to ensure your recipe is + extended to support multiple libraries. + Many standard recipes are already extended and support multiple libraries. + You can check in the meta/conf/multilib.conf + configuration file in the Yocto Project files directory to see how this is + done using the BBCLASSEXTEND variable. + Eventually, all recipes will be covered and this list will be unneeded. - + - If you are using the RPM Package Management System, you need to consider the - following: - - Define the unique architecure for the Multilib packages, along with - creating a unique deploy folder under tmp/deploy/rpm in - the Yocto Project build directory. - For example, consider lib32 in a - qemux86-64 image. - The possible architectures in the system are "all", "qemux86_64", "lib32_qemux86_64", - and "lib32_x86". - Because the ${MLPREFIX} is stripped from - ${PN} during RPM packaging, the naming for a normal - RPM package and a Multilib RPM package in a qemux86-64 - system resolves to something similar to bash-4.1-r2.x86_64.rpm and - bash-4.1.r2.lib32_x86.rpm, respectively. - When installing a Multilib image, the RPM backend first installs - the base image and then installs the Multilib libraries. - + For the most part, the Multilib class extension works automatically to + extend the package name from ${PN} to + ${MLPREFIX}${PN}, where MLPREFIX + is the particular multilib (e.g. "lib32-" or "lib64-"). + Standard variables such as DEPENDS, + RDEPENDS, RPROVIDES, + RRECOMMENDS, PACKAGES, and + PACKAGES_DYNAMIC are automatically extended by the system. + If you are extending any manual code in the recipe, you can use the + ${MLPREFIX} variable to ensure those names are extended + correctly. + This automatic extension code resides in multilib.bbclass. - - - If you are using the IPK Package Management System, you need to consider the - following: - - ${MLPREFIX} is not stripped from - ${PN} during IPK packaging, the naming for a normal - RPM package and a Multilib IPK package in a qemux86-64 - system resolves to something like bash_4.1-r2.x86_64.ipk and - lib32-bash_4.1-rw_x86.ipk, respectively. - The IPK deploy folder is not modified with - ${MLPREFIX} because packages with and without - the Multilib feature can exist in the same folder due to the - ${PN} differences. - IPK defines a sanity check for Multilib installation using certain - rules for file comparison, overridden, etc. - - -
+
Using Multilib - After you have set up the recipies and configurations to use the Multilib feature, - you are ready to build the image. - Follow these steps: - - Make changes in your local.conf - configuration file in the Yocto Project build directory. - Here is an example: - - MULTILIB_IMAGE(INSTALL = "lib32-connman" - require conf/multilib.con + After you have set up the recipes, you need to define the actual + combination of multiple libraries you want to build. + You accomplish this through your local.conf + configuration file in the Yocto Project build directory. + An example configuration would be as follows: + + MACHINE = "qemux86-64" + require conf/multilib.conf MULTILIBS = "multilib:lib32" DEFAULTTUNE_virtclass-multilib-lib32 = "x86" - - Build the image using the BitBake command. - For example: - + MULTILIB_IMAGE_INSTALL = "lib32-connman" + + This example enables an + additional library named lib32 alongside the + normal target packages. + When combining these "lib32" alternatives, the example uses "x86" for tuning. + For information on this particular tuning, see + meta/conf/machine/include/ia32/arch-ia32.inc. + + + + The example then includes lib32-connman + in all the images, which illustrates one method of including a + multiple library dependency. + You can use a normal image build to include this dependency, + for example: + $ bitbake core-image-sato - - If you want to build a particular recipe only, - use the BitBake command and specify the recipe only. - For example: - - $ bitbake lib32-connman - - + + You can also build Multilib packages specifically with a command like this: + + $ bitbake lib32-connman + + +
+ +
+ Additional Implementation Details + + + Different packaging systems have different levels of native Multilib + support. + For the RPM Package Management System, the following implementation details + exist: + + A unique architecture is defined for the Multilib packages, + along with creating a unique deploy folder under + tmp/deploy/rpm in the Yocto + Project build directory. + For example, consider lib32 in a + qemux86-64 image. + The possible architectures in the system are "all", "qemux86_64", + "lib32_qemux86_64", and "lib32_x86". + The ${MLPREFIX} variable is stripped from + ${PN} during RPM packaging. + The naming for a normal RPM package and a Multilib RPM package in a + qemux86-64 system resolves to something similar to + bash-4.1-r2.x86_64.rpm and + bash-4.1.r2.lib32_x86.rpm, respectively. + + When installing a Multilib image, the RPM backend first + installs the base image and then installs the Multilib libraries. + + The build system relies on RPM to resolve the identical files in the + two (or more) Multilib packages. + + + + + For the IPK Package Management System, the following implementation details exist: + + The ${MLPREFIX} is not stripped from + ${PN} during IPK packaging. + The naming for a normal RPM package and a Multilib IPK package in a + qemux86-64 system resolves to something like + bash_4.1-r2.x86_64.ipk and + lib32-bash_4.1-rw_x86.ipk, respectively. + + The IPK deploy folder is not modified with + ${MLPREFIX} because packages with and without + the Multilib feature can exist in the same folder due to the + ${PN} differences. + IPK defines a sanity check for Multilib installation + using certain rules for file comparison, overridden, etc. + +