From 059f795ebea9d919db50b3fd675d055f92d45c16 Mon Sep 17 00:00:00 2001 From: Antonin Godard Date: Mon, 6 Oct 2025 15:03:05 +0200 Subject: [PATCH] ref-manual/classes.rst: extend the uninative class documentation Extend the documentation of the uninative class based on [1]. [1]: https://lore.kernel.org/r/061e6150ce177221f7b6ee8754b03a20347a92c3.camel@linuxfoundation.org Co-developed-by: Richard Purdie (From yocto-docs rev: 0193bfa7966f301e46253e25eaa0482aeb21d9d4) Signed-off-by: Antonin Godard (cherry picked from commit 68996f0f3bf882714e8d96a0aa7b2492fe16d0c3) Signed-off-by: Antonin Godard Signed-off-by: Steve Sakoman --- documentation/ref-manual/classes.rst | 59 +++++++++++++++++++++------- 1 file changed, 44 insertions(+), 15 deletions(-) diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst index 2d560bd7ee..e238575a15 100644 --- a/documentation/ref-manual/classes.rst +++ b/documentation/ref-manual/classes.rst @@ -3363,22 +3363,51 @@ imitates. ``uninative`` ============= -Attempts to isolate the build system from the host distribution's C -library in order to make re-use of native shared state artifacts across -different host distributions practical. With this class enabled, a -tarball containing a pre-built C library is downloaded at the start of -the build. In the Poky reference distribution this is enabled by default -through ``meta/conf/distro/include/yocto-uninative.inc``. Other -distributions that do not derive from poky can also -"``require conf/distro/include/yocto-uninative.inc``" to use this. -Alternatively if you prefer, you can build the uninative-tarball recipe -yourself, publish the resulting tarball (e.g. via HTTP) and set -``UNINATIVE_URL`` and ``UNINATIVE_CHECKSUM`` appropriately. For an -example, see the ``meta/conf/distro/include/yocto-uninative.inc``. +The :ref:`ref-classes-uninative` class allows binaries to run on systems with +older or newer :wikipedia:`Glibc ` versions. This means +:ref:`ref-classes-native` recipe :ref:`overview-manual/concepts:shared state +cache` can be shared among different host distributions of different versions, +i.e. the :ref:`overview-manual/concepts:shared state cache` is "universal". -The :ref:`ref-classes-uninative` class is also used unconditionally by the extensible -SDK. When building the extensible SDK, ``uninative-tarball`` is built -and the resulting tarball is included within the SDK. +To allow this to work, the dynamic loader is changed to our own :manpage:`ld.so +` when binaries are compiled using the +``--dynamic-linker`` option. This means when the binary is executed, it finds +our own :manpage:`ld.so ` and that loader has a modified search path +which finds a newer Glibc version. + +The linking of the binaries is not changed at link time since the +headers on the system wouldn't match the newer Glibc and this causes +obtuse failures. Changing the loader is effectively the same as if the +system had a Glibc upgrade after the binary was compiled, so it is a +mechanism supported by upstream. + +One caveat to this approach is that the uninative Glibc binary must be +equal to or newer in version to the versions on all the systems using +the common :ref:`overview-manual/concepts:shared state cache`. This is why +:ref:`ref-classes-uninative` is regularly changed on the development and stable +branches. + +Another potential issue is static linking: static libraries created on +a system with a new Glibc version may have symbols not present in older +versions, which would then fail during linking on older systems. This +is one reason we don't use static linking for our :ref:`ref-classes-native` +binaries. + +With this class enabled, a tarball containing a pre-built C library is +downloaded at the start of the build. In the Poky reference distribution this is +enabled by default through :oe_git:`meta/conf/distro/include/yocto-uninative.inc +`. Other distributions that do +not derive from Poky can also "``require conf/distro/include/yocto-uninative.inc``" +to use this. Alternatively if you prefer, you can build the uninative-tarball +recipe yourself, publish the resulting tarball (e.g. via HTTP) and set +:term:`UNINATIVE_URL` and :term:`UNINATIVE_CHECKSUM` appropriately. For an +example, see :oe_git:`meta/conf/distro/include/yocto-uninative.inc +`. + +The :ref:`ref-classes-uninative` class is also used unconditionally by the +:doc:`extensible SDK `. When building the extensible +SDK, ``uninative-tarball`` is built and the resulting tarball is included within +the SDK. .. _ref-classes-update-alternatives: