CaROS/poky
3
1
Fork 0
mirror of https://git.yoctoproject.org/git/poky synced 2026-01-01 13:58:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

ref-manual/classes.rst: extend the uninative class documentation

Browse Source 
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 <richard.purdie@linuxfoundation.org>
(From yocto-docs rev: 0193bfa7966f301e46253e25eaa0482aeb21d9d4)

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
(cherry picked from commit 68996f0f3bf882714e8d96a0aa7b2492fe16d0c3)
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
Signed-off-by: Steve Sakoman <steve@sakoman.com>
This commit is contained in:
Antonin Godard 2025-10-06 15:03:05 +02:00 committed by Steve Sakoman
parent 9019056557
commit 059f795ebe
1 changed files with 44 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
documentation/ref-manual/classes.rst
View File

@ -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 <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
<ld.so.8>` when binaries are compiled using the
``--dynamic-linker`` option. This means when the binary is executed, it finds
our own :manpage:`ld.so <ld.so.8>` 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
</openembedded-core/tree/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
</openembedded-core/tree/meta/conf/distro/include/yocto-uninative.inc>`.
The :ref:`ref-classes-uninative` class is also used unconditionally by the
:doc:`extensible SDK </sdk-manual/extensible>`. When building the extensible
SDK, ``uninative-tarball`` is built and the resulting tarball is included within
the SDK.
.. _ref-classes-update-alternatives: