diff options
author | Scott Rifenbark <srifenbark@gmail.com> | 2016-04-19 21:50:16 -0700 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2016-04-29 07:48:22 +0100 |
commit | 8aebd1cd0aa9647f341afb4c44a1830c36c55c7e (patch) | |
tree | 2bbbd894ebca53be71d2c1f88efe7aab7d81f159 /documentation/dev-manual | |
parent | ab3147e9959b9975d76d8d6956da8b736e672b5a (diff) | |
download | openembedded-core-contrib-8aebd1cd0aa9647f341afb4c44a1830c36c55c7e.tar.gz |
dev-manual: Added Gobject Introspection section.
(From yocto-docs rev: be442bcb971c8685f8a2c6dde92b64479a211e2e)
Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.xml | 240 |
1 files 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 @@ </section> </section> + <section id='enabling-gobject-introspection-support'> + <title>Enabling GObject Introspection Support</title> + + <para> + <ulink url='https://wiki.gnome.org/Projects/GObjectIntrospection'>GObject introspection</ulink> + 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. + </para> + + <para> + 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 + <filename>-dev</filename> packages, + <filename>typelib</filename> files go to main packages as they + are packaged together with libraries that are introspected. + </para> + + <para> + 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. + </para> + + <para> + 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. + </para> + + <section id='enabling-the-generation-of-introspection-data'> + <title>Enabling the Generation of Introspection Data</title> + + <para> + Enabling the generation of introspection data (GIR files) + in your library package involves the following: + <orderedlist> + <listitem><para> + Inherit the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-gobject-introspection'><filename>gobject-introspection</filename></ulink> + class. + </para></listitem> + <listitem><para> + 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 + <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></ulink> + and that "qemu-usermode" is not in + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></ulink>. + If either of these conditions exist, nothing will + happen. + </para></listitem> + <listitem><para> + Try to build the recipe. + If you encounter build errors that look like + something is unable to find + <filename>.so</filename> libraries, check where these + libraries are located in the source tree and add + the following to the recipe: + <literallayout class='monospaced'> + GIR_EXTRA_LIBS_PATH = "${B}/<replaceable>something</replaceable>/.libs" + </literallayout> + <note> + See recipes in the <filename>oe-core</filename> + repository that use that + <filename>GIR_EXTRA_LIBS_PATH</filename> variable + as an example. + </note> + </para></listitem> + <listitem><para> + 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 + <ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Yocto Project mailing lists</ulink>. + </para></listitem> + </orderedlist> + <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. + </note> + </para> + </section> + + <section id='disabling-the-generation-of-introspection-data'> + <title>Disabling the Generation of Introspection Data</title> + + <para> + 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: + <itemizedlist> + <listitem><para> + Add the following to your distro configuration: + <literallayout class='monospaced'> + DISTRO_FEATURES_BACKFILL_CONSIDERED = "gobject-introspection-data" + </literallayout> + 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). + </para></listitem> + <listitem><para> + Add the following to your machine configuration: + <literallayout class='monospaced'> + MACHINE_FEATURES_BACKFILL_CONSIDERED = "qemu-usermode" + </literallayout> + 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. + </note> + </para></listitem> + </itemizedlist> + 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. + </para> + </section> + + <section id='testing-that-introspection-works-in-an-image'> + <title>Testing that Introspection Works in an Image</title> + + <para> + Use the following procedure to test if generating + introspection data is working in an image: + <orderedlist> + <listitem><para> + Make sure that "gobject-introspection-data" is not in + <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></ulink> + and that "qemu-usermode" is not in + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></ulink>. + </para></listitem> + <listitem><para> + Build <filename>core-image-sato</filename>. + </para></listitem> + <listitem><para> + Launch a Terminal and then start Python in the + terminal. + </para></listitem> + <listitem><para> + Enter the following in the terminal: + <literallayout class='monospaced'> + >>> from gi.repository import GLib + >>> GLib.get_host_name() + </literallayout> + </para></listitem> + <listitem><para> + For something a little more advanced, enter the + following: + <literallayout class='monospaced'> + http://python-gtk-3-tutorial.readthedocs.org/en/latest/introduction.html + </literallayout> + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='known-issues'> + <title>Known Issues</title> + + <para> + The following know issues exist for + GObject Introspection Support: + <itemizedlist> + <listitem><para> + <filename>qemu-ppc64</filename> immediately crashes. + Consequently, you cannot build introspection data on + that architecture. + </para></listitem> + <listitem><para> + x32 is not supported by QEMU. + Consequently, introspection data is disabled. + </para></listitem> + <listitem><para> + musl causes transient GLib binaries to crash on + assertion failures. + Consequently, generating introspection data is + disabled. + </para></listitem> + <listitem><para> + Because QEMU is not able to run the binaries correctly, + introspection is disabled for some specific packages + under specific architectures (e.g. + <filename>gcr</filename>, + <filename>libsecret</filename>, and + <filename>webkit</filename>). + </para></listitem> + </itemizedlist> + </para> + </section> + </section> + <section id='dev-optionally-using-an-external-toolchain'> <title>Optionally Using an External Toolchain</title> @@ -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 - "<link linkend='openembedded-kickstart-plugins'>Plugins</link>" - section for information on these plugins. + "<link linkend='openembedded-kickstart-plugins'>Plug-ins</link>" + section for information on these plug-ins. </para> <para> @@ -4367,21 +4591,21 @@ </section> <section id='openembedded-kickstart-plugins'> - <title>Plugins</title> + <title>Plug-ins</title> <para> - Plugins allow <filename>wic</filename> functionality to + Plug-ins allow <filename>wic</filename> 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. </para> <para> - Source plugins provide a mechanism to customize + Source plug ins provide a mechanism to customize various aspects of the image generation process in <filename>wic</filename>, mainly the contents of partitions. - The plugins provide a mechanism for mapping values + The plug ins provide a mechanism for mapping values specified in <filename>.wks</filename> files using the <filename>--source</filename> keyword to a particular plugin implementation that populates a |