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>
This commit is contained in:
Scott Rifenbark
Richard Purdie
parent
ab3147e995
commit
8aebd1cd0a
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue