From 8aebd1cd0aa9647f341afb4c44a1830c36c55c7e Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Tue, 19 Apr 2016 21:50:16 -0700 Subject: dev-manual: Added Gobject Introspection section. (From yocto-docs rev: be442bcb971c8685f8a2c6dde92b64479a211e2e) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 240 ++++++++++++++++++++- 1 file changed, 232 insertions(+), 8 deletions(-) diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 7aff0bc0d5..a634ef16c7 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -3726,6 +3726,230 @@ +
+ Enabling GObject Introspection Support + + + GObject introspection + 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 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 xxx section. + + +
+ Enabling the Generation of Introspection Data + + + Enabling the generation of introspection data (GIR files) + in your library package involves the following: + + + Inherit the + 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 + DISTRO_FEATURES_BACKFILL_CONSIDERED + and that "qemu-usermode" is not in + MACHINE_FEATURES_BACKFILL_CONSIDERED. + If either of these conditions exist, 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" + + + See recipes in the oe-core + repository that use that + 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 + Yocto Project mailing lists. + + + + 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. + + 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 + DISTRO_FEATURES_BACKFILL_CONSIDERED + and that "qemu-usermode" is not in + 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: + + http://python-gtk-3-tutorial.readthedocs.org/en/latest/introduction.html + + + + +
+ +
+ Known Issues + + + The following know issues exist for + 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). + + + +
+
+
Optionally Using an External Toolchain @@ -3802,10 +4026,10 @@ it is based on is by definition incomplete. Its purpose is to allow the generation of customized images, and as such was designed to be completely extensible through a - plugin interface. + plug-in interface. See the - "Plugins" - section for information on these plugins. + "Plug-ins" + section for information on these plug-ins. @@ -4367,21 +4591,21 @@
- Plugins + Plug-ins - Plugins allow wic functionality to + Plug-ins allow wic functionality to be extended and specialized by users. This section documents the plugin interface, which is - currently restricted to source plugins. + currently restricted to source plug ins. - Source plugins provide a mechanism to customize + Source plug ins provide a mechanism to customize various aspects of the image generation process in wic, mainly the contents of partitions. - The plugins provide a mechanism for mapping values + The plug ins provide a mechanism for mapping values specified in .wks files using the --source keyword to a particular plugin implementation that populates a -- cgit 1.2.3-korg