1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
2
3Working With Libraries
4**********************
5
6Libraries are an integral part of your system. This section describes
7some common practices you might find helpful when working with libraries
8to build your system:
9
10-  :ref:`How to include static library files
11   <dev-manual/libraries:including static library files>`
12
13-  :ref:`How to use the Multilib feature to combine multiple versions of
14   library files into a single image
15   <dev-manual/libraries:combining multiple versions of library files into one image>`
16
17-  :ref:`How to install multiple versions of the same library in parallel on
18   the same system
19   <dev-manual/libraries:installing multiple versions of the same library>`
20
21Including Static Library Files
22==============================
23
24If you are building a library and the library offers static linking, you
25can control which static library files (``*.a`` files) get included in
26the built library.
27
28The :term:`PACKAGES` and
29:term:`FILES:* <FILES>` variables in the
30``meta/conf/bitbake.conf`` configuration file define how files installed
31by the :ref:`ref-tasks-install` task are packaged. By default, the :term:`PACKAGES`
32variable includes ``${PN}-staticdev``, which represents all static
33library files.
34
35.. note::
36
37   Some previously released versions of the Yocto Project defined the
38   static library files through ``${PN}-dev``.
39
40Here is the part of the BitBake configuration file, where you can see
41how the static library files are defined::
42
43   PACKAGE_BEFORE_PN ?= ""
44   PACKAGES = "${PN}-src ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}"
45   PACKAGES_DYNAMIC = "^${PN}-locale-.*"
46   FILES = ""
47
48   FILES:${PN} = "${bindir}/* ${sbindir}/* ${libexecdir}/* ${libdir}/lib*${SOLIBS} \
49               ${sysconfdir} ${sharedstatedir} ${localstatedir} \
50               ${base_bindir}/* ${base_sbindir}/* \
51               ${base_libdir}/*${SOLIBS} \
52               ${base_prefix}/lib/udev ${prefix}/lib/udev \
53               ${base_libdir}/udev ${libdir}/udev \
54               ${datadir}/${BPN} ${libdir}/${BPN}/* \
55               ${datadir}/pixmaps ${datadir}/applications \
56               ${datadir}/idl ${datadir}/omf ${datadir}/sounds \
57               ${libdir}/bonobo/servers"
58
59   FILES:${PN}-bin = "${bindir}/* ${sbindir}/*"
60
61   FILES:${PN}-doc = "${docdir} ${mandir} ${infodir} ${datadir}/gtk-doc \
62               ${datadir}/gnome/help"
63   SECTION:${PN}-doc = "doc"
64
65   FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}"
66   FILES:${PN}-dev = "${includedir} ${FILES_SOLIBSDEV} ${libdir}/*.la \
67                   ${libdir}/*.o ${libdir}/pkgconfig ${datadir}/pkgconfig \
68                   ${datadir}/aclocal ${base_libdir}/*.o \
69                   ${libdir}/${BPN}/*.la ${base_libdir}/*.la \
70                   ${libdir}/cmake ${datadir}/cmake"
71   SECTION:${PN}-dev = "devel"
72   ALLOW_EMPTY:${PN}-dev = "1"
73   RDEPENDS:${PN}-dev = "${PN} (= ${EXTENDPKGV})"
74
75   FILES:${PN}-staticdev = "${libdir}/*.a ${base_libdir}/*.a ${libdir}/${BPN}/*.a"
76   SECTION:${PN}-staticdev = "devel"
77   RDEPENDS:${PN}-staticdev = "${PN}-dev (= ${EXTENDPKGV})"
78
79Combining Multiple Versions of Library Files into One Image
80===========================================================
81
82The build system offers the ability to build libraries with different
83target optimizations or architecture formats and combine these together
84into one system image. You can link different binaries in the image
85against the different libraries as needed for specific use cases. This
86feature is called "Multilib".
87
88An example would be where you have most of a system compiled in 32-bit
89mode using 32-bit libraries, but you have something large, like a
90database engine, that needs to be a 64-bit application and uses 64-bit
91libraries. Multilib allows you to get the best of both 32-bit and 64-bit
92libraries.
93
94While the Multilib feature is most commonly used for 32 and 64-bit
95differences, the approach the build system uses facilitates different
96target optimizations. You could compile some binaries to use one set of
97libraries and other binaries to use a different set of libraries. The
98libraries could differ in architecture, compiler options, or other
99optimizations.
100
101There are several examples in the ``meta-skeleton`` layer found in the
102:term:`Source Directory`:
103
104-  :oe_git:`conf/multilib-example.conf </openembedded-core/tree/meta-skeleton/conf/multilib-example.conf>`
105   configuration file.
106
107-  :oe_git:`conf/multilib-example2.conf </openembedded-core/tree/meta-skeleton/conf/multilib-example2.conf>`
108   configuration file.
109
110-  :oe_git:`recipes-multilib/images/core-image-multilib-example.bb </openembedded-core/tree/meta-skeleton/recipes-multilib/images/core-image-multilib-example.bb>`
111   recipe
112
113Preparing to Use Multilib
114-------------------------
115
116User-specific requirements drive the Multilib feature. Consequently,
117there is no one "out-of-the-box" configuration that would
118meet your needs.
119
120In order to enable Multilib, you first need to ensure your recipe is
121extended to support multiple libraries. Many standard recipes are
122already extended and support multiple libraries. You can check in the
123``meta/conf/multilib.conf`` configuration file in the
124:term:`Source Directory` to see how this is
125done using the
126:term:`BBCLASSEXTEND` variable.
127Eventually, all recipes will be covered and this list will not be
128needed.
129
130For the most part, the :ref:`Multilib <ref-classes-multilib*>`
131class extension works automatically to
132extend the package name from ``${PN}`` to ``${MLPREFIX}${PN}``, where
133:term:`MLPREFIX` is the particular multilib (e.g. "lib32-" or "lib64-").
134Standard variables such as
135:term:`DEPENDS`,
136:term:`RDEPENDS`,
137:term:`RPROVIDES`,
138:term:`RRECOMMENDS`,
139:term:`PACKAGES`, and
140:term:`PACKAGES_DYNAMIC` are
141automatically extended by the system. If you are extending any manual
142code in the recipe, you can use the ``${MLPREFIX}`` variable to ensure
143those names are extended correctly.
144
145Using Multilib
146--------------
147
148After you have set up the recipes, you need to define the actual
149combination of multiple libraries you want to build. You accomplish this
150through your ``local.conf`` configuration file in the
151:term:`Build Directory`. An example configuration would be as follows::
152
153   MACHINE = "qemux86-64"
154   require conf/multilib.conf
155   MULTILIBS = "multilib:lib32"
156   DEFAULTTUNE:virtclass-multilib-lib32 = "x86"
157   IMAGE_INSTALL:append = " lib32-glib-2.0"
158
159This example enables an additional library named
160``lib32`` alongside the normal target packages. When combining these
161"lib32" alternatives, the example uses "x86" for tuning. For information
162on this particular tuning, see
163``meta/conf/machine/include/ia32/arch-ia32.inc``.
164
165The example then includes ``lib32-glib-2.0`` in all the images, which
166illustrates one method of including a multiple library dependency. You
167can use a normal image build to include this dependency, for example::
168
169   $ bitbake core-image-sato
170
171You can also build Multilib packages
172specifically with a command like this::
173
174   $ bitbake lib32-glib-2.0
175
176Additional Implementation Details
177---------------------------------
178
179There are generic implementation details as well as details that are specific to
180package management systems. Here are implementation details
181that exist regardless of the package management system:
182
183-  The typical convention used for the class extension code as used by
184   Multilib assumes that all package names specified in
185   :term:`PACKAGES` that contain
186   ``${PN}`` have ``${PN}`` at the start of the name. When that
187   convention is not followed and ``${PN}`` appears at the middle or the
188   end of a name, problems occur.
189
190-  The :term:`TARGET_VENDOR`
191   value under Multilib will be extended to "-vendormlmultilib" (e.g.
192   "-pokymllib32" for a "lib32" Multilib with Poky). The reason for this
193   slightly unwieldy contraction is that any "-" characters in the
194   vendor string presently break Autoconf's ``config.sub``, and other
195   separators are problematic for different reasons.
196
197Here are the implementation details for the RPM Package Management System:
198
199-  A unique architecture is defined for the Multilib packages, along
200   with creating a unique deploy folder under ``tmp/deploy/rpm`` in the
201   :term:`Build Directory`. For example, consider ``lib32`` in a
202   ``qemux86-64`` image. The possible architectures in the system are "all",
203   "qemux86_64", "lib32:qemux86_64", and "lib32:x86".
204
205-  The ``${MLPREFIX}`` variable is stripped from ``${PN}`` during RPM
206   packaging. The naming for a normal RPM package and a Multilib RPM
207   package in a ``qemux86-64`` system resolves to something similar to
208   ``bash-4.1-r2.x86_64.rpm`` and ``bash-4.1.r2.lib32_x86.rpm``,
209   respectively.
210
211-  When installing a Multilib image, the RPM backend first installs the
212   base image and then installs the Multilib libraries.
213
214-  The build system relies on RPM to resolve the identical files in the
215   two (or more) Multilib packages.
216
217Here are the implementation details for the IPK Package Management System:
218
219-  The ``${MLPREFIX}`` is not stripped from ``${PN}`` during IPK
220   packaging. The naming for a normal RPM package and a Multilib IPK
221   package in a ``qemux86-64`` system resolves to something like
222   ``bash_4.1-r2.x86_64.ipk`` and ``lib32-bash_4.1-rw:x86.ipk``,
223   respectively.
224
225-  The IPK deploy folder is not modified with ``${MLPREFIX}`` because
226   packages with and without the Multilib feature can exist in the same
227   folder due to the ``${PN}`` differences.
228
229-  IPK defines a sanity check for Multilib installation using certain
230   rules for file comparison, overridden, etc.
231
232Installing Multiple Versions of the Same Library
233================================================
234
235There are be situations where you need to install and use multiple versions
236of the same library on the same system at the same time. This
237almost always happens when a library API changes and you have
238multiple pieces of software that depend on the separate versions of the
239library. To accommodate these situations, you can install multiple
240versions of the same library in parallel on the same system.
241
242The process is straightforward as long as the libraries use proper
243versioning. With properly versioned libraries, all you need to do to
244individually specify the libraries is create separate, appropriately
245named recipes where the :term:`PN` part of
246the name includes a portion that differentiates each library version
247(e.g. the major part of the version number). Thus, instead of having a
248single recipe that loads one version of a library (e.g. ``clutter``),
249you provide multiple recipes that result in different versions of the
250libraries you want. As an example, the following two recipes would allow
251the two separate versions of the ``clutter`` library to co-exist on the
252same system:
253
254.. code-block:: none
255
256   clutter-1.6_1.6.20.bb
257   clutter-1.8_1.8.4.bb
258
259Additionally, if
260you have other recipes that depend on a given library, you need to use
261the :term:`DEPENDS` variable to
262create the dependency. Continuing with the same example, if you want to
263have a recipe depend on the 1.8 version of the ``clutter`` library, use
264the following in your recipe::
265
266   DEPENDS = "clutter-1.8"
267
268