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.
+
+