diff options
Diffstat (limited to 'documentation/dev-manual/gobject-introspection.rst')
-rw-r--r-- | documentation/dev-manual/gobject-introspection.rst | 157 |
1 files changed, 157 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..89f21b7d10 --- /dev/null +++ b/documentation/dev-manual/gobject-introspection.rst | |||
@@ -0,0 +1,157 @@ | |||
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 | 1. Inherit the | ||
43 | :ref:`gobject-introspection <ref-classes-gobject-introspection>` | ||
44 | class. | ||
45 | |||
46 | 2. Make sure introspection is not disabled anywhere in the recipe or | ||
47 | from anything the recipe includes. Also, make sure that | ||
48 | "gobject-introspection-data" is not in | ||
49 | :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` | ||
50 | and that "qemu-usermode" is not in | ||
51 | :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`. | ||
52 | In either of these conditions, nothing will happen. | ||
53 | |||
54 | 3. Try to build the recipe. If you encounter build errors that look like | ||
55 | something is unable to find ``.so`` libraries, check where these | ||
56 | libraries are located in the source tree and add the following to the | ||
57 | recipe:: | ||
58 | |||
59 | GIR_EXTRA_LIBS_PATH = "${B}/something/.libs" | ||
60 | |||
61 | .. note:: | ||
62 | |||
63 | See recipes in the ``oe-core`` repository that use that | ||
64 | :term:`GIR_EXTRA_LIBS_PATH` variable as an example. | ||
65 | |||
66 | 4. Look for any other errors, which probably mean that introspection | ||
67 | support in a package is not entirely standard, and thus breaks down | ||
68 | in a cross-compilation environment. For such cases, custom-made fixes | ||
69 | are needed. A good place to ask and receive help in these cases is | ||
70 | the :ref:`Yocto Project mailing | ||
71 | lists <resources-mailinglist>`. | ||
72 | |||
73 | .. note:: | ||
74 | |||
75 | Using a library that no longer builds against the latest Yocto | ||
76 | Project release and prints introspection related errors is a good | ||
77 | candidate for the previous procedure. | ||
78 | |||
79 | Disabling the Generation of Introspection Data | ||
80 | ============================================== | ||
81 | |||
82 | You might find that you do not want to generate introspection data. Or, | ||
83 | perhaps QEMU does not work on your build host and target architecture | ||
84 | combination. If so, you can use either of the following methods to | ||
85 | disable GIR file generations: | ||
86 | |||
87 | - Add the following to your distro configuration:: | ||
88 | |||
89 | DISTRO_FEATURES_BACKFILL_CONSIDERED = "gobject-introspection-data" | ||
90 | |||
91 | Adding this statement disables generating introspection data using | ||
92 | QEMU but will still enable building introspection tools and libraries | ||
93 | (i.e. building them does not require the use of QEMU). | ||
94 | |||
95 | - Add the following to your machine configuration:: | ||
96 | |||
97 | MACHINE_FEATURES_BACKFILL_CONSIDERED = "qemu-usermode" | ||
98 | |||
99 | Adding this statement disables the use of QEMU when building packages for your | ||
100 | machine. Currently, this feature is used only by introspection | ||
101 | recipes and has the same effect as the previously described option. | ||
102 | |||
103 | .. note:: | ||
104 | |||
105 | Future releases of the Yocto Project might have other features | ||
106 | affected by this option. | ||
107 | |||
108 | If you disable introspection data, you can still obtain it through other | ||
109 | means such as copying the data from a suitable sysroot, or by generating | ||
110 | it on the target hardware. The OpenEmbedded build system does not | ||
111 | currently provide specific support for these techniques. | ||
112 | |||
113 | Testing that Introspection Works in an Image | ||
114 | ============================================ | ||
115 | |||
116 | Use the following procedure to test if generating introspection data is | ||
117 | working in an image: | ||
118 | |||
119 | 1. Make sure that "gobject-introspection-data" is not in | ||
120 | :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` | ||
121 | and that "qemu-usermode" is not in | ||
122 | :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`. | ||
123 | |||
124 | 2. Build ``core-image-sato``. | ||
125 | |||
126 | 3. Launch a Terminal and then start Python in the terminal. | ||
127 | |||
128 | 4. Enter the following in the terminal:: | ||
129 | |||
130 | >>> from gi.repository import GLib | ||
131 | >>> GLib.get_host_name() | ||
132 | |||
133 | 5. For something a little more advanced, enter the following see: | ||
134 | https://python-gtk-3-tutorial.readthedocs.io/en/latest/introduction.html | ||
135 | |||
136 | Known Issues | ||
137 | ============ | ||
138 | |||
139 | Here are know issues in GObject Introspection Support: | ||
140 | |||
141 | - ``qemu-ppc64`` immediately crashes. Consequently, you cannot build | ||
142 | introspection data on that architecture. | ||
143 | |||
144 | - x32 is not supported by QEMU. Consequently, introspection data is | ||
145 | disabled. | ||
146 | |||
147 | - musl causes transient GLib binaries to crash on assertion failures. | ||
148 | Consequently, generating introspection data is disabled. | ||
149 | |||
150 | - Because QEMU is not able to run the binaries correctly, introspection | ||
151 | is disabled for some specific packages under specific architectures | ||
152 | (e.g. ``gcr``, ``libsecret``, and ``webkit``). | ||
153 | |||
154 | - QEMU usermode might not work properly when running 64-bit binaries | ||
155 | under 32-bit host machines. In particular, "qemumips64" is known to | ||
156 | not work under i686. | ||
157 | |||