156 lines
6.1 KiB
ReStructuredText
156 lines
6.1 KiB
ReStructuredText
.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
|
|
|
|
Enabling GObject Introspection Support
|
|
**************************************
|
|
|
|
`GObject introspection <https://gi.readthedocs.io/en/latest/>`__
|
|
is the standard mechanism for accessing GObject-based software from
|
|
runtime environments. GObject is a feature of the GLib library that
|
|
provides an object framework for the GNOME desktop and related software.
|
|
GObject Introspection adds information to GObject that allows objects
|
|
created within it to be represented across different programming
|
|
languages. If you want to construct GStreamer pipelines using Python, or
|
|
control UPnP infrastructure using Javascript and GUPnP, GObject
|
|
introspection is the only way to do it.
|
|
|
|
This section describes the Yocto Project support for generating and
|
|
packaging GObject introspection data. GObject introspection data is a
|
|
description of the API provided by libraries built on top of the GLib
|
|
framework, and, in particular, that framework's GObject mechanism.
|
|
GObject Introspection Repository (GIR) files go to ``-dev`` packages,
|
|
``typelib`` files go to main packages as they are packaged together with
|
|
libraries that are introspected.
|
|
|
|
The data is generated when building such a library, by linking the
|
|
library with a small executable binary that asks the library to describe
|
|
itself, and then executing the binary and processing its output.
|
|
|
|
Generating this data in a cross-compilation environment is difficult
|
|
because the library is produced for the target architecture, but its
|
|
code needs to be executed on the build host. This problem is solved with
|
|
the OpenEmbedded build system by running the code through QEMU, which
|
|
allows precisely that. Unfortunately, QEMU does not always work
|
|
perfectly as mentioned in the ":ref:`dev-manual/gobject-introspection:known issues`"
|
|
section.
|
|
|
|
Enabling the Generation of Introspection Data
|
|
=============================================
|
|
|
|
Enabling the generation of introspection data (GIR files) in your
|
|
library package involves the following:
|
|
|
|
#. Inherit the :ref:`ref-classes-gobject-introspection` class.
|
|
|
|
#. Make sure introspection is not disabled anywhere in the recipe or
|
|
from anything the recipe includes. Also, make sure that
|
|
"gobject-introspection-data" is not in
|
|
:term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`
|
|
and that "qemu-usermode" is not in
|
|
:term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`.
|
|
In either of these conditions, nothing will happen.
|
|
|
|
#. Try to build the recipe. If you encounter build errors that look like
|
|
something is unable to find ``.so`` libraries, check where these
|
|
libraries are located in the source tree and add the following to the
|
|
recipe::
|
|
|
|
GIR_EXTRA_LIBS_PATH = "${B}/something/.libs"
|
|
|
|
.. note::
|
|
|
|
See recipes in the ``oe-core`` repository that use that
|
|
:term:`GIR_EXTRA_LIBS_PATH` variable as an example.
|
|
|
|
#. Look for any other errors, which probably mean that introspection
|
|
support in a package is not entirely standard, and thus breaks down
|
|
in a cross-compilation environment. For such cases, custom-made fixes
|
|
are needed. A good place to ask and receive help in these cases is
|
|
the :ref:`Yocto Project mailing
|
|
lists <resources-mailinglist>`.
|
|
|
|
.. note::
|
|
|
|
Using a library that no longer builds against the latest Yocto
|
|
Project release and prints introspection related errors is a good
|
|
candidate for the previous procedure.
|
|
|
|
Disabling the Generation of Introspection Data
|
|
==============================================
|
|
|
|
You might find that you do not want to generate introspection data. Or,
|
|
perhaps QEMU does not work on your build host and target architecture
|
|
combination. If so, you can use either of the following methods to
|
|
disable GIR file generations:
|
|
|
|
- Add the following to your distro configuration::
|
|
|
|
DISTRO_FEATURES_BACKFILL_CONSIDERED = "gobject-introspection-data"
|
|
|
|
Adding this statement disables generating introspection data using
|
|
QEMU but will still enable building introspection tools and libraries
|
|
(i.e. building them does not require the use of QEMU).
|
|
|
|
- Add the following to your machine configuration::
|
|
|
|
MACHINE_FEATURES_BACKFILL_CONSIDERED = "qemu-usermode"
|
|
|
|
Adding this statement disables the use of QEMU when building packages for your
|
|
machine. Currently, this feature is used only by introspection
|
|
recipes and has the same effect as the previously described option.
|
|
|
|
.. note::
|
|
|
|
Future releases of the Yocto Project might have other features
|
|
affected by this option.
|
|
|
|
If you disable introspection data, you can still obtain it through other
|
|
means such as copying the data from a suitable sysroot, or by generating
|
|
it on the target hardware. The OpenEmbedded build system does not
|
|
currently provide specific support for these techniques.
|
|
|
|
Testing that Introspection Works in an Image
|
|
============================================
|
|
|
|
Use the following procedure to test if generating introspection data is
|
|
working in an image:
|
|
|
|
#. Make sure that "gobject-introspection-data" is not in
|
|
:term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`
|
|
and that "qemu-usermode" is not in
|
|
:term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`.
|
|
|
|
#. Build ``core-image-sato``.
|
|
|
|
#. Launch a Terminal and then start Python in the terminal.
|
|
|
|
#. Enter the following in the terminal::
|
|
|
|
>>> from gi.repository import GLib
|
|
>>> GLib.get_host_name()
|
|
|
|
#. For something a little more advanced, enter the following see:
|
|
https://python-gtk-3-tutorial.readthedocs.io/en/latest/introduction.html
|
|
|
|
Known Issues
|
|
============
|
|
|
|
Here are know issues in GObject Introspection Support:
|
|
|
|
- ``qemu-ppc64`` immediately crashes. Consequently, you cannot build
|
|
introspection data on that architecture.
|
|
|
|
- x32 is not supported by QEMU. Consequently, introspection data is
|
|
disabled.
|
|
|
|
- musl causes transient GLib binaries to crash on assertion failures.
|
|
Consequently, generating introspection data is disabled.
|
|
|
|
- Because QEMU is not able to run the binaries correctly, introspection
|
|
is disabled for some specific packages under specific architectures
|
|
(e.g. ``gcr``, ``libsecret``, and ``webkit``).
|
|
|
|
- QEMU usermode might not work properly when running 64-bit binaries
|
|
under 32-bit host machines. In particular, "qemumips64" is known to
|
|
not work under i686.
|
|
|