aboutsummaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-common-tasks.xml
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2016-04-19 21:50:16 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2016-04-29 07:48:22 +0100
commit8aebd1cd0aa9647f341afb4c44a1830c36c55c7e (patch)
tree2bbbd894ebca53be71d2c1f88efe7aab7d81f159 /documentation/dev-manual/dev-manual-common-tasks.xml
parentab3147e9959b9975d76d8d6956da8b736e672b5a (diff)
downloadopenembedded-core-contrib-8aebd1cd0aa9647f341afb4c44a1830c36c55c7e.tar.gz
openembedded-core-contrib-8aebd1cd0aa9647f341afb4c44a1830c36c55c7e.tar.bz2
openembedded-core-contrib-8aebd1cd0aa9647f341afb4c44a1830c36c55c7e.zip
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/dev-manual-common-tasks.xml')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml240
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