diff options
Diffstat (limited to 'documentation/dev-manual/gobject-introspection.rst')
-rw-r--r-- | documentation/dev-manual/gobject-introspection.rst | 155 |
1 files changed, 155 insertions, 0 deletions
diff --git a/documentation/dev-manual/gobject-introspection.rst b/documentation/dev-manual/gobject-introspection.rst new file mode 100644 index 0000000000..f7206e6fae --- /dev/null +++ b/documentation/dev-manual/gobject-introspection.rst | |||
@@ -0,0 +1,155 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK | ||
2 | |||
3 | Enabling GObject Introspection Support | ||
4 | ************************************** | ||
5 | |||
6 | `GObject introspection <https://gi.readthedocs.io/en/latest/>`__ | ||
7 | is the standard mechanism for accessing GObject-based software from | ||
8 | runtime environments. GObject is a feature of the GLib library that | ||
9 | provides an object framework for the GNOME desktop and related software. | ||
10 | GObject Introspection adds information to GObject that allows objects | ||
11 | created within it to be represented across different programming | ||
12 | languages. If you want to construct GStreamer pipelines using Python, or | ||
13 | control UPnP infrastructure using Javascript and GUPnP, GObject | ||
14 | introspection is the only way to do it. | ||
15 | |||
16 | This section describes the Yocto Project support for generating and | ||
17 | packaging GObject introspection data. GObject introspection data is a | ||
18 | description of the API provided by libraries built on top of the GLib | ||
19 | framework, and, in particular, that framework's GObject mechanism. | ||
20 | GObject Introspection Repository (GIR) files go to ``-dev`` packages, | ||
21 | ``typelib`` files go to main packages as they are packaged together with | ||
22 | libraries that are introspected. | ||
23 | |||
24 | The data is generated when building such a library, by linking the | ||
25 | library with a small executable binary that asks the library to describe | ||
26 | itself, and then executing the binary and processing its output. | ||
27 | |||
28 | Generating this data in a cross-compilation environment is difficult | ||
29 | because the library is produced for the target architecture, but its | ||
30 | code needs to be executed on the build host. This problem is solved with | ||
31 | the OpenEmbedded build system by running the code through QEMU, which | ||
32 | allows precisely that. Unfortunately, QEMU does not always work | ||
33 | perfectly as mentioned in the ":ref:`dev-manual/gobject-introspection:known issues`" | ||
34 | section. | ||
35 | |||
36 | Enabling the Generation of Introspection Data | ||
37 | ============================================= | ||
38 | |||
39 | Enabling the generation of introspection data (GIR files) in your | ||
40 | library 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 | |||
77 | Disabling the Generation of Introspection Data | ||
78 | ============================================== | ||
79 | |||
80 | You might find that you do not want to generate introspection data. Or, | ||
81 | perhaps QEMU does not work on your build host and target architecture | ||
82 | combination. If so, you can use either of the following methods to | ||
83 | disable 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 | |||
106 | If you disable introspection data, you can still obtain it through other | ||
107 | means such as copying the data from a suitable sysroot, or by generating | ||
108 | it on the target hardware. The OpenEmbedded build system does not | ||
109 | currently provide specific support for these techniques. | ||
110 | |||
111 | Testing that Introspection Works in an Image | ||
112 | ============================================ | ||
113 | |||
114 | Use the following procedure to test if generating introspection data is | ||
115 | working 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 | |||
134 | Known Issues | ||
135 | ============ | ||
136 | |||
137 | Here 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 | |||