[yocto] [Fwd: gobject introspection release notes]

[alexander.kanavin at linux.intel.com]

Hello,

here is the information about gobject introspection that should be placed
to the release notes of the upcoming yocto release.

1. Introduction

This Yocto release adds 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 that framework's
GObject mechanism in particular. 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, then executing the binary and
processing its output. Making this work 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 in Yocto by running the code through Qemu emulator which allows
precisely that, but unfortunately Qemu does not always work perfectly (see
known issues list below).

2. Why all this trouble?

GObject introspection is nowadays the standard mechanism for accessing
GObject-based software from runtime environments. If you want to construct

GStreamer pipelines using Python, or control UPnP infrastructure using
Javascript and GUPnP, this is the only way to do it.

3. Where does generated introspection data go?

Gir files go to -dev packages, typelib files go to main packages
(they are packaged together with libraries that are introspected).

4. I don't need introspection data (or Qemu does not work on my
combination of build host and target architecture), how can I switch it
off?

You have two options:
a) add
DISTRO_FEATURES_BACKFILL_CONSIDERED = "gobject-introspection-data" to your
distro configuration. This will disable building introspection data using
qemu, but will still enable building introspection tools and  libraries
(building them does not require the use of qemu).

b) add
MACHINE_FEATURES_BACKFILL_CONSIDERED = "qemu-usermode"
to your machine configuration. This will disable the use of qemu when
building packages for your machine; at the moment this feature is
used only by introspection recipes and has the same effect as option a),
but in the future there may be other features that this affects.

If introspection data is disabled, it can still be obtained through other
means (for example, by copying the data from a suitable sysroot, or
generating it on the target hardware). Yocto currently does not provide
specific support for these techniques.

5. How do I enable generating introspection data in my library package?
(variant: I have a library that no longer builds against latest Yocto
release, and build process prints introspection related errors, how to fix
it?)

a. Inherit gobject-introspection class.

b. Make sure introspection is not disabled anywhere in the recipe or its
includes. Also, make sure that 'gobject-introspection-data' is neither

in DISTRO_FEATURES_BACKFILL_CONSIDERED, and 'qemu-usermode is not in
MACHINE_FEATURES_BACKFILL_CONSIDERED, or nothing will happen.

c. Try to build the recipe; if this results in build errors that look like
something is unable to find .so libraries, check where these
libraries
are in the source tree and add GIR_EXTRA_LIBS_PATH=${B}/something/.libs to
the recipe (look at recipes in oe-core which have that variable for a
template).

c. Any other errors probably mean that introspection support in a package
is not entirely standard, and breaks down in a cross-compilation
environment. Custom-made fixing is needed then - please come to the yocto
mailing list for help.

6. How do I test that introspection works in an image?

a. Make sure that 'gobject-introspection-data' is not in
DISTRO_FEATURES_BACKFILL_CONSIDERED and 'qemu-usermode' is not in
MACHINE_FEATURES_BACKFILL_CONSIDERED.

b. Build core-image-sato.

c. Start terminal, start python in the terminal.

d. Type out something like:

>>> from gi.repository import GLib
>>> GLib.get_host_name()

e. Also, try something more advanced, for example:
http://python-gtk-3-tutorial.readthedocs.org/en/latest/introduction.html

7. Known issues:

- qemu-ppc64 crashes out immediately; so introspection data
cannot be built on that architecture

- x32 is not supported by qemu; therefore introspection data is disabled
there.

- musl is causing transient glib binaries to crash on assertion failures,
so generating introspection data is disabled there as well

- introspection is disabled for some specific packages under specific
arhcitectures (such as gcr, libsecret, webkit), because qemu is not able
to run the binaries correctly


Thanks,
Alex