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>

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