1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
2
3Enabling GObject Introspection Support
4**************************************
5
6`GObject introspection <https://gi.readthedocs.io/en/latest/>`__
7is the standard mechanism for accessing GObject-based software from
8runtime environments. GObject is a feature of the GLib library that
9provides an object framework for the GNOME desktop and related software.
10GObject Introspection adds information to GObject that allows objects
11created within it to be represented across different programming
12languages. If you want to construct GStreamer pipelines using Python, or
13control UPnP infrastructure using Javascript and GUPnP, GObject
14introspection is the only way to do it.
15
16This section describes the Yocto Project support for generating and
17packaging GObject introspection data. GObject introspection data is a
18description of the API provided by libraries built on top of the GLib
19framework, and, in particular, that framework's GObject mechanism.
20GObject Introspection Repository (GIR) files go to ``-dev`` packages,
21``typelib`` files go to main packages as they are packaged together with
22libraries that are introspected.
23
24The data is generated when building such a library, by linking the
25library with a small executable binary that asks the library to describe
26itself, and then executing the binary and processing its output.
27
28Generating this data in a cross-compilation environment is difficult
29because the library is produced for the target architecture, but its
30code needs to be executed on the build host. This problem is solved with
31the OpenEmbedded build system by running the code through QEMU, which
32allows precisely that. Unfortunately, QEMU does not always work
33perfectly as mentioned in the ":ref:`dev-manual/gobject-introspection:known issues`"
34section.
35
36Enabling the Generation of Introspection Data
37=============================================
38
39Enabling the generation of introspection data (GIR files) in your
40library package involves the following:
41
42#. Inherit the :ref:`ref-classes-gobject-introspection` class.
43
44#. Make sure introspection is not disabled anywhere in the recipe or
45   from anything the recipe includes. Also, make sure that
46   "gobject-introspection-data" is not in
47   :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`
48   and that "qemu-usermode" is not in
49   :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`.
50   In either of these conditions, nothing will happen.
51
52#. Try to build the recipe. If you encounter build errors that look like
53   something is unable to find ``.so`` libraries, check where these
54   libraries are located in the source tree and add the following to the
55   recipe::
56
57      GIR_EXTRA_LIBS_PATH = "${B}/something/.libs"
58
59   .. note::
60
61      See recipes in the ``oe-core`` repository that use that
62      :term:`GIR_EXTRA_LIBS_PATH` variable as an example.
63
64#. Look for any other errors, which probably mean that introspection
65   support in a package is not entirely standard, and thus breaks down
66   in a cross-compilation environment. For such cases, custom-made fixes
67   are needed. A good place to ask and receive help in these cases is
68   the :ref:`Yocto Project mailing
69   lists <resources-mailinglist>`.
70
71.. note::
72
73   Using a library that no longer builds against the latest Yocto
74   Project release and prints introspection related errors is a good
75   candidate for the previous procedure.
76
77Disabling the Generation of Introspection Data
78==============================================
79
80You might find that you do not want to generate introspection data. Or,
81perhaps QEMU does not work on your build host and target architecture
82combination. If so, you can use either of the following methods to
83disable GIR file generations:
84
85-  Add the following to your distro configuration::
86
87      DISTRO_FEATURES_BACKFILL_CONSIDERED = "gobject-introspection-data"
88
89   Adding this statement disables generating introspection data using
90   QEMU but will still enable building introspection tools and libraries
91   (i.e. building them does not require the use of QEMU).
92
93-  Add the following to your machine configuration::
94
95      MACHINE_FEATURES_BACKFILL_CONSIDERED = "qemu-usermode"
96
97   Adding this statement disables the use of QEMU when building packages for your
98   machine. Currently, this feature is used only by introspection
99   recipes and has the same effect as the previously described option.
100
101   .. note::
102
103      Future releases of the Yocto Project might have other features
104      affected by this option.
105
106If you disable introspection data, you can still obtain it through other
107means such as copying the data from a suitable sysroot, or by generating
108it on the target hardware. The OpenEmbedded build system does not
109currently provide specific support for these techniques.
110
111Testing that Introspection Works in an Image
112============================================
113
114Use the following procedure to test if generating introspection data is
115working in an image:
116
117#. Make sure that "gobject-introspection-data" is not in
118   :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`
119   and that "qemu-usermode" is not in
120   :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`.
121
122#. Build ``core-image-sato``.
123
124#. Launch a Terminal and then start Python in the terminal.
125
126#. Enter the following in the terminal::
127
128      >>> from gi.repository import GLib
129      >>> GLib.get_host_name()
130
131#. For something a little more advanced, enter the following see:
132   https://python-gtk-3-tutorial.readthedocs.io/en/latest/introduction.html
133
134Known Issues
135============
136
137Here are know issues in GObject Introspection Support:
138
139-  ``qemu-ppc64`` immediately crashes. Consequently, you cannot build
140   introspection data on that architecture.
141
142-  x32 is not supported by QEMU. Consequently, introspection data is
143   disabled.
144
145-  musl causes transient GLib binaries to crash on assertion failures.
146   Consequently, generating introspection data is disabled.
147
148-  Because QEMU is not able to run the binaries correctly, introspection
149   is disabled for some specific packages under specific architectures
150   (e.g. ``gcr``, ``libsecret``, and ``webkit``).
151
152-  QEMU usermode might not work properly when running 64-bit binaries
153   under 32-bit host machines. In particular, "qemumips64" is known to
154   not work under i686.
155
156