[yocto] gobject introspection release notes

[Paul Eggleton]

Hi Alex,

On Tue, 19 Apr 2016 21:39:04 alexander.kanavin at linux.intel.com wrote:
> 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 for this! We might need to pare it down a little for the purposes of 
the relevant manual sections but Scott should be able to take care of that.
I'll work with him to get this added.

Cheers,
Paul