



GObject Introspection

[GObject Introspection](#) 

* [Changelog](index.html#document-changelog)

* [Goals](index.html#document-goals)

* [Architecture](index.html#document-architecture)

* [Users](index.html#document-users)

* [Build & Test](index.html#document-build_test)

* [Writing Bindable APIs](index.html#document-writingbindableapis)

* [Build System Integration](index.html#document-buildsystems/index)

* [Annotations](index.html#document-annotations/index)

* [Writing Bindings](index.html#document-writingbindings/index)

* [Command Line Tools](index.html#document-tools/index)

[GObject Introspection](#)

* 

* GObject Introspection

* 

---

GObject Introspection[](#gobject-introspection "Permalink to this heading")

============================================================================

Changelog[](#changelog "Permalink to this heading")

----------------------------------------------------

Versions with an odd minor version are unstable releases (e.g. 1.57.x) while

versions with even minor version are stable releases (e.g. 1.58.x). This list

is sorted by release date.

For more details see the GIT log:

<https://gitlab.gnome.org/GNOME/gobject-introspection>

### 1.78.1 - 2023-09-16[](#id1 "Permalink to this heading")

* Avoid undefined behaviour in the Regress test suite [#458]

### 1.78.0 - 2023-09-08[](#id2 "Permalink to this heading")

* Update the GIR data for GLib, GObject, and GIO

* Add GObject as a dependency for the Cairo GIR

* Add more tests for GI marshalling

* Update regression test suite

* Fix build on Windows for paths using ‘' as a separator

* Support different prefix for finding GIR data

* Add GI\_GIR\_PATH environment variable for controlling GIR paths

### 1.76.1 - 2023-03-22[](#id3 "Permalink to this heading")

* Handle null default values [#457]

* Documentation fixes

### 1.76.0 - 2023-03-13[](#id4 "Permalink to this heading")

* Documentation fixes

* Update the GIR data for GLib

### 1.75.6 - 2023-02-13[](#id5 "Permalink to this heading")

* Documentation fixes

* Fix build when using GLib as a subproject

* Update the GIR data for GLib

### 1.75.4 - 2023-01-09[](#id6 "Permalink to this heading")

* Brown-paper bag release to fix the GLib dependency.

### 1.75.2 - 2023-01-09[](#id7 "Permalink to this heading")

* Split ‘disguised’ attribute into two separate attributes [#101]

* Add copy/free function annotations for plain-old data types [#14]

* Include the default value of GObject properties in the GIR data [#4]

* Drop wrap files for recursive dependencies

* Add more marshalling tests [Marco Trevisan]

* Update the GIR data for GLib, GObject, GModule, and GIO [Sebastian Dröge, Rico Tzschichholz]

### 1.74.0 - 2022-09-17[](#id8 "Permalink to this heading")

* Update the GIR data for GLib, GObject, GModule, and GIO

### 1.73.1 - 2022-09-03[](#id9 "Permalink to this heading")

* Update the GIR data for GLib, GObject, GModule, and GIO

* Disable rpath on Windows [Christoph Reiter]

* Add llvm/mingw support on Windows [Christoph Reiter]

* Fix annotations in libgirepository [Philip Chimento]

* Support C99 designated initializers when parsing C declarations [Jan Tojnar]

* Add some more types to win32 GIR [Marc-André Lureau]

* Let doctool prepend emitting objects in GJS signals [Andy Holmes]

* Require a C99 toolchain like GLib

### 1.73.0 - 2022-07-13[](#id10 "Permalink to this heading")

* Update the GIR data for GLib, GObject, GModule, and GIO

* scanner: Support pre-processor macros with zero arguments [Philip Withnall]

* scanner: Support ISO C varargs in macros [Philip Withnall]

* Fix subproject build [Andoni Morales Alastruey]

### 1.72.0 - 2022-03-18[](#id11 "Permalink to this heading")

* Add new utility API to libgirepository for bindings implementing an argument

cache [Philip Chimento]

* Update the GIR data for GLib, GObject, GModule, and GIO

### 1.71.0 - 2022-02-14[](#id12 "Permalink to this heading")

* Create new API for libffi closures [Sergei Trofimovich, Cimbali]

* Treat @-prefixed shlib paths as absolute on macOS [Rok Mandeljc]

* Add new forever scope [#49]

* Build fixes with newer Meson [#414]

* Improve regression test suite [Marco Trevisan (Treviño)]

* Avoid a segfault when using an invalid GType [Lukas Oberhuber]

* Build fixes on Windows when using g-i as a subproject [Andoni Morales Alastruey]

* Warn about property name collisions [#386]

* Add “strict” warnings to g-ir-scanner

* Add the “emitter” annotation for signal emitters

* Add a command line option to g-ir-scanner to specify the compiler

* Add new convenience API to libgirepository [Philip Chimento]

* Build fixes on Windows when using MSVC [Chun-wei Fan]

* Documentation fixes [#211, #327]

* Update the GIR data for GLib, GObject, and GIO

### 1.70.0 - 2021-09-17[](#id13 "Permalink to this heading")

* Update the GIR data for GLib, GObject, and GIO

### 1.69.0 - 2021-08-24[](#id14 "Permalink to this heading")

* Fix build when gobject-introspection is a subproject [!266](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/266)

* Add more float types [#384](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/384), [!269](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/269)

* Make test suite work with cross-related options [#227](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/227)

* Fix several leaks found by Coverity [!272](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/272)

* Fix enum member c:identifier [!264](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/264)

* Add g-ir-doc-tool man page [!284](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/284)

* Export warnlib sources as variables [!287](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/287)

* Update the GLib annotations [!288](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/288)

* Add “final” class attribute [!257](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/257), [!291](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/291)

* Add option to make .gir files installation paths configurable [!63](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/63)

* Handle constructors with mismatched GTypes [#399](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/399), [!292](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/292)

* Add property accessors annotations [#13](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/13), [!279](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/279)

### 1.68.0 - 2021-03-19[](#id15 "Permalink to this heading")

* Update GLib annotations [!262](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/262)

* docs: cleanup [!261](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/261)

* Fix syntax errors in gir-1.2.rnc [!256](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/256)

### 1.67.1 - 2021-03-12[](#id16 "Permalink to this heading")

* Requires Python 3.6+

* Update GLib annotations

* Fix compatibility with Python 3.10 [#358](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/358)

* Fix build with GIR data disabled [!248](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/248)

* Add test object for signal marshallers [!259](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/259)

### 1.66.1 - 2020-10-03[](#id17 "Permalink to this heading")

* Update glib annotations

* Windows: Fix running on different drives [!239](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/239)

* gimarshallingtests: Add more tests for flags [!235](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/235)

* Revert “giscanner: Fix section matching for documentation [!237](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/237)” see [#360](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/360)

### 1.66.0 - 2020-09-12[](#id18 "Permalink to this heading")

* Support the gtk-doc action syntax [!203](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/203)

* Meson fixes with glib and/or g-i is a subproject [!206](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/206) [!208](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/208)

* GITypeInfo storage type utility API [!205](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/205)

* Meson: Fix build as subproject [!214](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/214)

* Fixing XDG\_DATA\_DIRS logic [!215](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/215)

* libgirepository: Add a couple missing nullable annotations [!217](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/217) [!225](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/225)

* dumper: Fix missing symbols in LTO case or with overridden symbol visibility settings [!216](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/216)

* Documentation improvements: [!220](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/220) [!232](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/232)

* Remove old autoconf fallback code for the python tools [!221](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/221)

* meson: Rename option gi\_cross\_use\_{host -> prebuilt}\_gi mr:211

* meson: Don’t override finding executables when using pre-built tools. [!212](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/212)

* meson: gir: add a dependency for g-ir-compiler for building .girs [!228](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/228)

* meson: Use pkgconfig generator [!207](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/207)

* Fix gi-dump-types.c to build on Windows [!218](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/218)

* giscanner: parse block comments for members and fields [!230](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/230)

* Add the notion of standalone doc sections [!226](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/226)

* giscanner: Add support for using clang-cl [!234](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/234)

* giscanner: Fix section matching for documentation [!237](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/237)

### 1.64.1 - 2020-04-05[](#id19 "Permalink to this heading")

* Replace calls to deprecated xml.etree.cElementTree removed in Python 3.9 [!202](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/202) ([Stephen Gallagher](https://gitlab.gnome.org/sgallagher))

* gimarshallingtests: Use g\_assert\_cmpfloat\_with\_epsilon. Fixes tests on some architectures [!200](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/200) ([Iain Lane](https://gitlab.gnome.org/iainl))

### 1.64.0 - 2020-03-07[](#id20 "Permalink to this heading")

* Update glib annotations ([Rico Tzschichholz](https://gitlab.gnome.org/ricotz))

* Fix regress scanner tests for non-gcc/clang compilers [!197](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/197) ([Chun-wei Fan](https://gitlab.gnome.org/fanc999))

* Document how to update glib GIR [!199](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/199) ([Bastien Nocera](https://gitlab.gnome.org/hadess))

### 1.63.2 - 2020-01-17[](#id21 "Permalink to this heading")

* Update glib annotations ([Rico Tzschichholz](https://gitlab.gnome.org/ricotz))

* Add GMemoryMonitor to glib annotations [!193](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/193) ([Bastien Nocera](https://gitlab.gnome.org/hadess))

* Fix build reproducibility [!192](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/192) ([Joshua Watt](https://gitlab.gnome.org/jpewhacker))

* Drop deprecated xml.etree.ElementTree.Element.getchildren() calls [!194](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/194) ([Miro Hrončok](https://gitlab.gnome.org/hroncok))

* Support Python 3.8.x+ on Windows [!195](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/195) ([Chun-wei Fan](https://gitlab.gnome.org/fanc999))

* Cross compile support [!64](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/64) ([Alexander Kanavin](https://gitlab.gnome.org/alex.kanavin))

* meson: Visual Studio builds: Use -utf-8 where available [!196](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/196) ([Chun-wei Fan](https://gitlab.gnome.org/fanc999))

### 1.63.1 - 2019-11-24[](#id22 "Permalink to this heading")

* Update glib annotations ([Rico Tzschichholz](https://gitlab.gnome.org/ricotz))

* build: require meson 0.50.1

* build: use proper dylib versioning on macOS [!177](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/177) ([Tom Schoonjans](https://gitlab.gnome.org/tschoonj))

* scanner: Support array arguments with static keyword [!176](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/176) ([Emmanuele Bassi](https://gitlab.gnome.org/ebassi))

* website: Add Ruby-GNOME to user list [!178](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/178) ([kojix2](https://gitlab.gnome.org/kojix2))

* Fix non-libtool code being run with no nob-libtool dependencies [!179](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/179) ([Alistair Buxton](https://gitlab.gnome.org/ali1234))

* meson: change “cairo” from a boolean to a feature option [!180](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/180)

* meson: change “doctool” from a boolean to a feature option [!181](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/181)

* Fix a memory leak in g\_irepository\_get\_object\_gtype\_interfaces() [!182](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/182) ([Philip Chimento](https://gitlab.gnome.org/ptomato))

* ccompiler.py: Fix macro defines with quotes on MSVC [!183](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/183) ([Chun-wei Fan](https://gitlab.gnome.org/fanc999))

* tests: Actually test libregress by specifying the LD\_LIBRARY\_PATH [!174](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/174) ([Corentin Noël](https://gitlab.gnome.org/tintou))

* examples: Make self contained and add build system integration examples [!189](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/189)

* autotools: Make INTROSPECTION\_GIRDIR/INTROSPECTION\_TYPELIBDIR respect prefix/datadir/libdir [!190](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/190)

* girepository: Also store GType cache misses [!191](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/191) ([Carlos Garnacho](https://gitlab.gnome.org/carlosg))

* docs: Document GI\_CROSS\_LAUNCHER envvar [!175](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/175) ([Emmanuele Bassi](https://gitlab.gnome.org/ebassi))

### 1.62.0 - 2019-09-09[](#id23 "Permalink to this heading")

* No changes since 1.61.2

### 1.61.2 - 2019-08-17[](#id24 "Permalink to this heading")

* dumper: Use the distutils linker [!170](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/170) ([David Demelier](https://gitlab.gnome.org/markand))

* structinfo: Fix offset in find\_method() [!171](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/171) ([Florian Müllner](https://gitlab.gnome.org/fmuellner))

* tests: Don’t include “config.h” in installed files [!172](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/172) ([Philip Chimento](https://gitlab.gnome.org/ptomato))

* meson: Make meson.override\_find\_program working on more complex use cases [!173](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/173) ([Thibault Saunier](https://gitlab.gnome.org/thiblahute))

### 1.61.1 - 2019-08-07[](#id25 "Permalink to this heading")

* Drop autotools build system [!143](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/143)

* meson: require 0.49.2

* Update glib annotations ([Rico Tzschichholz](https://gitlab.gnome.org/ricotz))

* Add documentation to the RelaxNG schema [!139](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/139) ([David Bellot](https://gitlab.gnome.org/yimyom))

* Unused variable fixes [!147](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/147) ([Philip Chimento](https://gitlab.gnome.org/ptomato))

* cachestore: handle cache getting deleted while loading it [!148](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/148)

* Visual Studio builds: Use msvc\_recommended\_pragmas.h from GLib [!150](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/150) ([Chun-wei Fan](https://gitlab.gnome.org/fanc999))

* Add Vulkan gir [!155](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/155) ([Matthew Waters](https://gitlab.gnome.org/ystreet00))

* Make g\_irepository\_get\_object\_gtype\_interfaces actually work [!157](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/157) ([Philip Chimento](https://gitlab.gnome.org/ptomato))

* gimarshallingtests: Add a marshalling test case for GPtrArrays and GArrays of structures [!160](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/160) ([Stéphane Seng](https://gitlab.gnome.org/stephaneseng))

* scanner: parse and expose function macros [!159](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/159) ([Mathieu Duponchelle](https://gitlab.gnome.org/mathieudu))

* meson: use pkg-config directly for libffi cflags and libs [!162](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/162) ([Aaron Boxer](https://gitlab.gnome.org/boxerab))

* meson: Fix wrong dependency type check for gio-unix [#166](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/166) ([Brook Milligan](https://gitlab.gnome.org/brook-milligan))

* regress: Add regression test for signal with GError param [!169](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/169) ([Philip Chimento](https://gitlab.gnome.org/ptomato))

### 1.60.2 - 2019-06-15[](#id26 "Permalink to this heading")

* docwriter: Fix Exception message attribute [!146](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/146) ([Philip Chimento](https://gitlab.gnome.org/ptomato))

* meson: fix default cairo DLL name on Windows

* scanner: Fix error on Windows in case source files are on different drives

* gi-test: Fix gir file tests with MSVC [!151](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/151) ([Chun-wei Fan](https://gitlab.gnome.org/fanc999))

* MSVC.README.rst: Update VS 2008/x64 build notes [!152](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/152) ([Chun-wei Fan](https://gitlab.gnome.org/fanc999))

* giscanner/scannerlexer.l: Include io.h on Windows ([Chun-wei Fan](https://gitlab.gnome.org/fanc999))

* build: Force-include msvc\_recommended\_pragmas.h on Visual Studio [!152](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/152) ([Chun-wei Fan](https://gitlab.gnome.org/fanc999))

* Update glib annotations (2.60.4)

### 1.60.1 - 2019-04-07[](#id27 "Permalink to this heading")

* Update glib annotations (glib-2-60)

* shlibs: fall back to basename on macOS for relative paths [#222](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/222)

* meson: always pass –quiet to g-ir-scanner

* docs: include ‘–c-include’ in g-ir-scanner man page [#275](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/275)

* tests: Fix compatibility with Python 3.5 [#274](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/274) ([Tomasz Miąsko](https://gitlab.gnome.org/tmiasko))

### 1.60.0 - 2019-03-10[](#id28 "Permalink to this heading")

NOTE: This is the last release supporting autotools. Please try building with

meson instead and report any problems. This does not affect projects using

autotools + g-i, only the build of g-i itself.

* gir: Update glib annotations [!142](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/142) [!141](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/141) ([Andrea Azzarone](https://gitlab.gnome.org/azzaronea))

### 1.59.5 - 2019-03-04[](#id29 "Permalink to this heading")

* gir: Include C header in cairo gir file [!138](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/138) ([Tomasz Miąsko](https://gitlab.gnome.org/tmiasko))

* ccompiler: restore customize\_compiler() setup for macOS. [#268](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/268)

* gir: skip glib-enumtypes.h for GObject-2.0 [!140](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/140)

### 1.59.4 - 2019-02-04[](#id30 "Permalink to this heading")

* tests: Add functions using flat struct arrays. [!130](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/130) ([Tomasz Miąsko](https://gitlab.gnome.org/tmiasko))

* Clean shebangs out of non-executable scripts and drop exec perm from xmlwriter.py. [!131](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/131) ([Dominique Leuenberger](https://gitlab.gnome.org/DimStar77))

* maintransformer: parse deprecation annotations for section blocks. [#213](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/213) [!132](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/132)

* repository: g\_irepository\_get\_object\_gtype\_interfaces. [!30](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/30) ([Colin Walters](https://gitlab.gnome.org/walters), [Philip Chimento](https://gitlab.gnome.org/ptomato))

* message: handle fatal errors even if warnings are disabled. [#229](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/229) [!126](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/126)

* autotools: Fix build with `-Wl,--as-needed`. [#226](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/226) [!134](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/134)

* maintransformer: Don’t warn on (optional) annotations on (inout) [!135](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/135) ([Guido Günther](https://gitlab.gnome.org/guidog))

* girepository: Fix a possible use-after-free if g\_mapped\_file\_new() fails

and fix possible leak of transitive dependency names. [!136](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/136) ([Elliott Sales de Andrade](https://gitlab.gnome.org/QuLogic))

### 1.59.3 - 2019-01-08[](#id31 "Permalink to this heading")

* meson: use underscore as a separator in build options (gtk-doc -> gtk\_doc etc)

[!129](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/129)

* website: add cppgir C++ binding

[!124](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/124) ([Mark Nauwelaerts](https://gitlab.gnome.org/mnauw))

* scanner: Merge specifiers and qualifiers when merging basic types.

Fixes “unsigned char” being wrongly parsed as “unsigned” etc.

[!125](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/125) ([Tomasz Miąsko](https://gitlab.gnome.org/tmiasko))

* meson: warn that not all tests will be run if building without cairo/doctool

* scanner: rework source root directory guessing code to not depend on the

build directory

* scanner: Remove incorrect c:type generated for array of synthesized unions

[!127](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/127) ([Tomasz Miąsko](https://gitlab.gnome.org/tmiasko))

* scanner: Flatten multi-dimensional arrays fields

[!128](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/128) ([Tomasz Miąsko](https://gitlab.gnome.org/tmiasko))

### 1.59.2 - 2019-01-04[](#id32 "Permalink to this heading")

* Everything included in 1.58.3

* meson: Various fixes and all tests have been ported (0.47+ is required now)

[!114](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/114) [!110](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/110) etc.

([Tomasz Miąsko](https://gitlab.gnome.org/tmiasko), [Emmanuele Bassi](https://gitlab.gnome.org/ebassi),

[Christoph Reiter](https://gitlab.gnome.org/creiter))

* scanner: Save preprocessor input and output files with `save-temps`

[!107](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/107) ([Tomasz Miąsko](https://gitlab.gnome.org/tmiasko))

* automake: Use the wildcard function where needed

[!100](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/100) ([William Hua](https://gitlab.gnome.org/williamhua))

* build: extend `PYTHONPATH` instead of replacing it [!101](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/101)

* gir/cairo: add `cairo\_rectangle\_t` [#74](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/74) [!103](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/103) (Yeti)

* Add a `--version` option to g-ir-compiler and g-ir-generate

[#55](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/55) [!106](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/106)

* tests: various test improvements

[!111](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/111) [!117](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/117) [!119](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/119) ([Tomasz Miąsko](https://gitlab.gnome.org/tmiasko))

* ccompiler: don’t use Python compiler flags

[#150](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/150) [!118](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/118) [!120](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/120)

([Tomasz Miąsko](https://gitlab.gnome.org/tmiasko), [Christoph Reiter](https://gitlab.gnome.org/creiter))

* parser: Do not bail out when parsing GIR files without doc positions

[!121](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/121) ([Emmanuele Bassi](https://gitlab.gnome.org/ebassi))

* gimarshallingtests: Remove declarations of nonexistent functions

[!123](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/123) ([Philip Chimento](https://gitlab.gnome.org/ptomato))

### 1.58.3 - 2018-12-30[](#id33 "Permalink to this heading")

* docwriter: Support python-markdown 3.x

[#250](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/250)

* scanner: Define grefcount and gatomicrefcount as aliases to gint

[#254](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/254) ([Tomasz Miąsko](https://gitlab.gnome.org/tmiasko))

* scanner: make using bool without stdbool include work again

[#247](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/247)

* gir: Update glib annotations for glib 2.58.2

### 1.59.1 - 2018-12-16[](#id34 "Permalink to this heading")

* Everything included in 1.58.2

* build: Drop Python 2 support, require Python 3.4+ [!69](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/69)

* build: Add option to make .gir files installation paths configurable

[!63](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/63) ([Kai Kang](https://gitlab.gnome.org/kai.7.kang))

* build: Skip gobject/gvaluecollector.h when constructing GObject GIR

[!20](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/20) ([Tomasz Miąsko](https://gitlab.gnome.org/tmiasko))

* build: Port various tests to work with meson

[!92](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/92) [!94](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/94) [!95](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/95) ([Tomasz Miąsko](https://gitlab.gnome.org/tmiasko))

* regress: Add test for write-only property

[!67](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/67) ([Philip Chimento](https://gitlab.gnome.org/ptomato))

* regress: Implement interface and override properties

[!59](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/59) ([Philip Chimento](https://gitlab.gnome.org/ptomato))

* writer: Include documentation and symbol position in source files

[!75](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/75) ([Thibault Saunier](https://gitlab.gnome.org/thiblahute))

* giscanner: Print relative filename paths when warning

[!74](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/74) ([Jonas Ådahl](https://gitlab.gnome.org/jadahl))

* giscanner: Define grefcount and gatomicrefcount as aliases to gint

[!76](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/76) ([Tomasz Miąsko](https://gitlab.gnome.org/tmiasko))

* giscanner: Allow empty declarations. Fixes warnings with mingw headers.

[#216](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/216) [!89](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/89) ([Christoph Reiter](https://gitlab.gnome.org/creiter))

* giscanner: Replace linked lists with arrays in source scanner

[!90](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/90) ([Tomasz Miąsko](https://gitlab.gnome.org/tmiasko))

* girepository: Various docs cleanups and fixes

[!96](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/96) [!97](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/97) [#66](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/66) ([Tomasz Miąsko](https://gitlab.gnome.org/tmiasko),

[Christoph Reiter](https://gitlab.gnome.org/creiter), Jasper St. Pierre)

* girepository: Don’t abort when calling g\_base\_info\_get\_name() on a GITypeInfo

[#96](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/96) [!99](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/99) ([Christoph Reiter](https://gitlab.gnome.org/creiter))

* girepository: Add version macros and functions

[#200](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/200) [!98](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/98) ([Christoph Reiter](https://gitlab.gnome.org/creiter))

### 1.58.2 - 2018-12-09[](#id35 "Permalink to this heading")

* meson: Fix random build errors (mostly MSVC)

[!88](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/88) ([Tomasz Miąsko](https://gitlab.gnome.org/tmiasko))

* scanner: Fix parsing of \_\_typeof\_\_ that is part of a cast expression

[!78](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/78) ([Tomasz Miąsko](https://gitlab.gnome.org/tmiasko))

* scanner: Ignore \_\_pragma keyword used by MSVC

[!87](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/87) ([Tomasz Miąsko](https://gitlab.gnome.org/tmiasko))

### 1.58.1 - 2018-11-17[](#id36 "Permalink to this heading")

* meson: Install warnlib [!62](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/62) ([Jan Tojnar](https://gitlab.gnome.org/jtojnar))

* scanner: Parse \_\_typeof\_\_ and discard it

[!71](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/71) ([Jan Alexander Steffens](https://gitlab.gnome.org/heftig))

* meson: add back /usr/bin/env to the python-cmd

[#237](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/237) [!70](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/70) ([Håvard Graff](https://gitlab.gnome.org/hgr))

* Fix non libtool build

[!72](https://gitlab.gnome.org/GNOME/gobject-introspection/merge_requests/72) ([Olivier Crête](https://gitlab.gnome.org/ocrete))

### 1.58.0 - 2018-08-31[](#id37 "Permalink to this heading")

```

• Changes:

  - Update annotations imported from GLib, and require GLib 2.58

  - Ensure that G-I builds on macOS

  - Add a --version argument to the Python-based tools

  - Allow selecting the output format for g-ir-doc-tool

  - Drop the Visual Studio templates

  - Use Sphinx to generate the user documentation; gtk-doc is still

    required for the girepository-1.0 C API reference

  - Support all _Float* C types from ISO/IEC TS 18661-3:2015

  - The autotools build now uses autoconf-archive

  - g-ir-doc-tool: Add DevDocs formatting for GJS (--format=devdocs)

    This adds a dependency on the Python markdown package

• Issues resolved on gitlab.gnome.org:

  - #139 - make check fails for gobject-introspection 1.44.0 on

           OS X 10.10.4

  - #184 - Default element-type not set for GByteArray object

           properties

  - #189 - c:type missing pointer/array information in GIR for

           C array parameters

  - #134 - Allow multiple output formats

  - #218 - gtk2 hits unreachable code after enable -Wswitch-default

  - #113 - Memory leaks in GI regress and marshalling tests property

           setters

• Bugs resolved on bugzilla.gnome.org:

  - #702788 - The girepository DLL is acquiring pointers incorrectly

              on Windows/x64

• Contributors:

  Tomasz Miąsko, Emmanuele Bassi, Rico Tzschichholz, Chun-wei Fan,

  Philip Chimento, Tom Schoonjans, Christoph Reiter, Ray Donnelly,

  Marcus Calhoun-Lopez, Florian Müllner, Evan Welsh, Mathieu Duponchelle

```

### 1.56 - 2018-03-13[](#id38 "Permalink to this heading")

```

• Changes:

  - Add _Float128 to the base C types

  - Update annotations imported from GLib, and require GLib 2.56

• Issues resolved on gitlab.gnome.org:

  - #173 - Fails to parse flag-constants

  - #175 - writer: Include documentation and symbol position in

           source files

  - #120 - adding subdir-objects to AM_INIT_AUTOMAKE

  - #190 - const qualifier dropped from c:type on (type filename)

           parameters

  - #188 - giscanner: don't print "suppressed N warnings" if --quiet

           was specified

• Bugs resolved on bugzilla.gnome.org:

  - #764791 - gitypelib.c: increase #define MAX_NAME_LEN from 200 to 255

  - #756921 - g-ir-scanner does not recognize _Thread_local

  - #791991 - Broken shared-library value in gir files on *BSD when

              builddir includes the name of the library

  - #791902 - Building using non-libtool (e.g., meson) on MinGW

  - #629667 - MY_ENUM_VALUE = <constant> only works for last member

  - #699354 - g-ir-compiler man page for --shared-library incorrectly

              says "lib" and ".so" should be removed

  - #761985 - os.name can be wrong in some context

  - #699328 - GI_TYPELIB_PATH is undocumented

• Contributors:

  Ting-Wei Lan, Leslie Giles, Rico Tzschichholz, Christoph Reiter,

  Nicola Fontana, Tomasz Miąsko, Emmanuele Bassi, Philip Chimento,

  Karl-Philipp Richter

```

Note

For older releases, see the Git log

Goals[](#goals "Permalink to this heading")

--------------------------------------------

The introspection project has two major goals, and a variety of more minor

ones.

### Two level applications - C and <your favorite runtime>[](#two-level-applications-c-and-your-favorite-runtime "Permalink to this heading")

It makes sense to build many kinds of applications using (at least) two

different levels and languages — one for the low level elements, interfacing

with the OS and/or the hardware; and one for the high level application logic.

C is good for graphics, multimedia, and lower level systems work. However,

writing complex software in C is difficult and error-prone. A managed runtime

such as [JavaScript](https://wiki.gnome.org/JavaScript), Python, Perl,

Java, Lua, .NET, Scheme etc. makes a lot of sense for non-fast-path

application logic such as configuration, layout, dialogs, etc.

Note

To achieve this goal you need to write your code using GObject convention.

For more information about that, see the [GObject tutorial](https://docs.gtk.org/gobject/tutorial.html)

Thus, one of the major goals of the GObject introspection project is to be a

convenient bridge between these two worlds, and allow you to choose the right

tool for the job, rather than being limited inside one or the other. With the

introspection project, you can write for example a ClutterActor or GtkWidget

subclass in C, and then without any additional work use that class inside the

high level language of your choice.

### Sharing binding infrastructure work, and making the platform even more binding-friendly[](#sharing-binding-infrastructure-work-and-making-the-platform-even-more-binding-friendly "Permalink to this heading")

Historically in GNOME, the core platform has been relatively binding-friendly,

but there are several details not captured in the C+GObject layer that

bindings have needed. For example, reference counting semantics and the item

type inside GList’s. Up until now various language bindings such as Python,

Mono, java-gnome etc. had duplicated copies of hand-maintained metadata, and

this led to a situation where bindings tended to lag behind until these manual

fixups were done, or were simply wrong, and your application would crash when

calling a more obscure function.

The introspection project solves this by putting all of the metadata inside

the GObject library itself, using annotations in the comments. This will lead

to less duplicate work from binding authors, and a more reliable experience

for binding consumers.

Additionally, because the introspection build process will occur inside the

GObject libraries themselves, a goal is to encourage GObject authors to

consider shaping their APIs to be more binding friendly from the start, rather

than as an afterthought.

### Additional goals and uses[](#additional-goals-and-uses "Permalink to this heading")

* API verification - Sometimes the API of a library in our stack changes by

accident. Usually by a less experienced developer making a change without

realizing it will break applications. Introspecting the available API in

each release of the library and comparing it to the last one makes it easy

to see what changed

* Documentation tools - The tools written inside of the GObjectIntrospection

can easily be reused to improve that problem. Essentially; replacing

gtk-doc. We want to document what we export so it makes sense to glue this

together with API verification mentioned above

* UI Designer infrastructure

* Serialization/RPC/DBus

Architecture[](#architecture "Permalink to this heading")

----------------------------------------------------------

![_images/architecture.svg](_images/architecture.svg)

```

BUILD TIME:

          +-----------------------------------------------------------+

          |   foo.c                                                   |

          |   foo.h                                                   |

          |                                                           |

          | Library sources, with type annotations                    |

          +-----------------------------------------------------------+

              |                                      |

             gcc                                 g-ir-scanner

              |                                      |

              |                                      V

              |                              +------------------------+

              |                              |    Foo.gir             |

              |                              |                        |

              |                              |    <GI-name>.gir       |

              |                              |                        |

              |                              | XML file               |

              |                              |                        |

              |                              | Invocation information |

              |                              | Required .gir files    |

              |                              | API docs               |

              |                              |                        |

              |                              +------------------------+

              |                                          |

              |                                     g-ir-compiler

              |                                          |

  DEPLOYMENT TIME:                                       |

              |                                          |

              V                                          V

        +-----------------------------+      +---------------------------+

        |   libfoo.so                 |      |    Foo.typelib            |

        |                             |      |                           |

        |                             |      | Binary version of the     |

        |  ELF file                   |      | invocation info and       |

        |                             |      | required .typelib files   |

        |  Machine code, plus         |      +---------------------------+

        | dynamic linkage information |                  A

        | (DWARF debug data, etc)     |                  |

        +-----------------------------+                  |

                     A                                   |

                     |                       +---------------------------+

                     |                       |  libgirepository.so       |

                +-----------+                |                           |

                | libffi.so |                |  Can read typelibs and    |

                |           |<-------+------>|  present them in a        |

                +-----------+        |       |  libffi-based way         |

                                     |       |                           |

                                     |       +---------------------------+

                                     |

                                     |

                           +----------------------------+

                           | Specific language bindings |

                           +----------------------------+

```

Users[](#users "Permalink to this heading")

--------------------------------------------

### Bindings based on GObject-Introspection[](#bindings-based-on-gobject-introspection "Permalink to this heading")

* [Vala](https://wiki.gnome.org/Projects/Vala) - Compiler for the GObject type system (compile time)

* [Genie](https://wiki.gnome.org/Projects/Genie) - Genie Language (compile time)

* [PyGObject](https://wiki.gnome.org/Projects/PyGObject) - Python bindings (runtime)

* [pygir-ctypes](http://code.google.com/p/pygir-ctypes/) - Pure Python GObject Introspection Repository (GIR) wrapper using ctypes (runtime)

* [pgi](http://github.com/lazka/pgi) - Pure Python GObject Introspection Bindings (runtime)

* [GTK2-Perl/Introspection](https://wiki.gnome.org/GTK2-Perl/Introspection) - Perl bindings (runtime)

* [JGIR](https://wiki.gnome.org/Projects/JGIR) - Java/JVM bindings (compile time, using typelib)

* [GJS](https://wiki.gnome.org/Projects/Gjs) - Javascript (spidermonkey) bindings (runtime)

* [Seed](https://wiki.gnome.org/Projects/Seed) - Javascript (JSCore, WebKit JS engine) bindings (runtime)

* [sbank](https://wiki.gnome.org/sbank) - Scheme binding for gobject-introspection (runtime)

* [GObjectIntrospection/GObjectConsume](https://wiki.gnome.org/Projects/GObjectIntrospection/GObjectConsume) - Qt bindings (compile time)

* [GirFFI](http://github.com/mvz/ruby-gir-ffi) - Ruby bindings (runtime)

* [Ruby-GNOME](https://github.com/ruby-gnome/ruby-gnome) - Ruby bindings (runtime)

* [lgob](http://oproj.tuxfamily.org/wiki/doku.php?id=lgob) - Lua bindings (compile time?)

* [guile-gir](http://gitorious.org/guile-gir) - Guile bindings (runtime)

* [factor-gir](http://github.com/ex-rzr/factor-gir) - Factor bindings (runtime)

* [lgi](http://www.github.com/pavouk/lgi) - Lua bindings (runtime)

* [GObject for PHP](https://github.com/megous/gobject-for-php)

* [cl-gir](http://bazaar.launchpad.net/~scymtym/+junk/cl-gir/files) GIR for Common Lisp (work in progress)

* [GNU Smalltalk](http://www.gitorious.org/gst-gobject-introspection) - A branch of GNU Smalltalk which adds GObject Introspection bindings.

* [node-gir](https://github.com/creationix/node-gir) - Node.js bindings to the girepository

* [go-gir-generator](https://github.com/linuxdeepin/go-gir-generator) - Go bindings (compile time) (Forked from [gogobject](https://github.com/nsf/gogobject/) which is unmaintained)

* [haskell-gi](http://www.haskell.org/haskellwiki/GObjectIntrospection) - a Haskell binding for the GIRepository C library, and a Haskell code generator built upon it. It is very much a work in progress.

* [cl-gobject-introspection](https://github.com/andy128k/cl-gobject-introspection) - A bridge between Common Lisp and GObject.

* [ocaml-gir](http://git.ocamlcore.org/cgi-bin/gitweb.cgi?p=ocaml-gir/ocaml-gir.git) - An automatic binding generator for gtk-related libraries

* [gir2pascal](http://wiki.freepascal.org/gir2pascal) - gir2pascal is a program to convert gir files into into pascal files

* [PLGI](https://github.com/keriharris/plgi) - Prolog bindings (runtime)

* [hbgi](https://github.com/tuffnatty/hbgi) - Harbour bindings for GObject Introspection (runtime)

* [cppgir](https://www.gitlab.com/mnauw/cppgir) - C++ bindings (compile time, using typelib)

* [crystal-gobject](https://github.com/jhass/crystal-gobject) - gobject-introspection for Crystal (compile time)

### Projects using GObject Introspection[](#projects-using-gobject-introspection "Permalink to this heading")

> 

> * [Folks](http://telepathy.freedesktop.org/wiki/Folks) - the Gnome contact aggregator

> * [GnomeShell](https://wiki.gnome.org/Projects/GnomeShell) - prototyping the future gnome shell

> * [Midgard2](http://www.midgard2.org/) - language bindings to the Midgard content repository

> * [libpeas](http://git.gnome.org/browse/libpeas/tree/) - library providing a generic plugin framework

> * [telepathy-glib](http://telepathy.freedesktop.org/wiki/Telepathy%20GLib) - GLib bindings for Telepathy

> * [gir2xmi](https://github.com/jralls/gir2xmi) - UML model generator for GObject-Introspection Gir files.

> * [playerctl](https://github.com/acrisci/playerctl) - a library and cli for controlling media players that implement the MPRIS DBus interface

> * [i3ipc-glib](https://github.com/acrisci/i3ipc-glib) - a library for extensions to the i3 window manager

> * [gabi](https://gitlab.gnome.org/tmiasko/gabi) - a C/typelib ABI cross-validator

> 

> 

> 

### Projects that could use GObject-Introspection[](#projects-that-could-use-gobject-introspection "Permalink to this heading")

> 

> * [Mono GAPI](http://www.mono-project.com/GAPI) could replace its gapi2-parser by using GOject-Introspection.

> * [gtkmm](http://www.gtkmm.org/) could use GObject-Introspection in its [gmmproc](http://www.gtkmm.org/docs/gtkmm-2.4/docs/tutorial/html/chapter-wrapping-c-libraries.html) to generate C++ library bindings

> 

> 

> 

Build & Test[](#build-test "Permalink to this heading")

--------------------------------------------------------

Clone gobject-introspection with git:

```

git clone https://gitlab.gnome.org/GNOME/gobject-introspection.git

cd gobject-introspection

```

### Meson[](#meson "Permalink to this heading")

Build:

```

meson setup _build

cd _build

# To see the build options run "meson configure"

meson compile

```

Test:

```

meson test # run tests

flake8 .. # run code quality checks

```

### Dependencies[](#dependencies "Permalink to this heading")

gobject-introspection depends on a row of other packages, either strictly,

optionally or only for testing. The following installation instructions should

over all cases for some common Distributions.

Debian/Ubuntu:

```

sudo apt install pkg-config python3-dev flex bison libglib2.0-dev \

 libcairo2-dev libffi-dev python3-mako \

 python3-markdown python3-distutils meson build-essential \

 gtk-doc-tools

```

Fedora:

```

sudo dnf install pkg-config flex bison cairo-devel

 cairo-gobject-devel python3-mako gcc \

 python3-markdown meson libffi-devel python3-devel \

 python3 gtk-doc

```

Writing Bindable APIs[](#writing-bindable-apis "Permalink to this heading")

----------------------------------------------------------------------------

### Things to avoid[](#things-to-avoid "Permalink to this heading")

#### Structures with custom memory management[](#structures-with-custom-memory-management "Permalink to this heading")

Avoid creating C structures with custom memory management unless they are

registered as a [boxed type](https://docs.gtk.org/gobject/boxed.html).

If you don’t register them as a boxed type bindings will fall back to

simple memory copying, which might not be what you want.

Also consider using a full [GObject](https://docs.gtk.org/gobject/class.Object.html)

as that allows bindings to better integrate those objects with the binding

language, like for example preserve user defined state across language

boundaries.

Example to avoid:

```

struct \_GstMiniObject {

 GTypeInstance instance;

 /\*< public >\*/ /\* with COW \*/

 gint refcount;

 guint flags;

```

#### Functionality only accessible through a C macro or inline function[](#functionality-only-accessible-through-a-c-macro-or-inline-function "Permalink to this heading")

The scanner does not support C macros as API. Solution - add a function

accessor rather than a macro. This also has the side effect of making

debugging in C code easier.

Example:

```

#define GTK\_WIDGET\_FLAGS(wid) (GTK\_OBJECT\_FLAGS (wid))

GtkWidgetFlags gtk\_widget\_get\_flags (GtkWidget \*widget); /\* Actually, see http://bugzilla.gnome.org/show\_bug.cgi?id=69872 \*/

```

Likewise, inline functions cannot be loaded from a dynamic library. Make sure to

provide a non-inline equivalent.

#### Direct C structure access for objects[](#direct-c-structure-access-for-objects "Permalink to this heading")

Having GObjects also have fields can be difficult to bind. Create accessor

functions.

Example:

```

struct \_SoupMessage {

 GObject parent;

 /\*< public >\*/

 const char \*method;

 guint status\_code;

...

}

const char \* soup\_message\_get\_method (SoupMessage \*message); /\* Or use a GObject property \*/

```

#### va\_list[](#va-list "Permalink to this heading")

Using varargs can be convenient for C, but they are difficult to bind.

Solution: Keep the C function for the convenience of C programmers, but add an

another function which takes an array (either zero terminated or with a length

parameter).

**Good** example:

```

GtkListStore \*gtk\_list\_store\_new (gint n\_columns,

 ...);

GtkListStore \*gtk\_list\_store\_newv (gint n\_columns,

 GType \*types);

```

You can also expose the array variant under the name of the varargs variant

using the `rename-to` annotation:

`gtk\_list\_store\_newv: (rename-to gtk\_list\_store\_new)`

Also consider using C99’s compound literals and designated initializers to avoid

`va\_list` even in the C API, which is more type-safe.

#### Multiple out parameters[](#multiple-out-parameters "Permalink to this heading")

Multiple out parameters are supported by introspection, but not all languages

have an obvious mapping for multiple out values. A boxed structure could serve

as an alternative.

Example to think about (here, there could be a boxed `struct GtkCoordinate {

gint x; gint y; }` structure).

```

void gtk\_widget\_get\_pointer (GtkWidget \*widget,

 gint \*x,

 gint \*y);

```

#### In-out parameters[](#in-out-parameters "Permalink to this heading")

Don’t use in-out arguments, especially not for non-scalar values. It’s difficult

to enforce or validate the conventions for in-out arguments, which can easily

lead to crashes.

Instead, pass the input as an in argument, and receive the output as either a

return value or an out argument.

```

FooBoxed \*foo\_bar\_scale\_boxed(FooBar \*self,

 FooBoxed \*boxed);

void foo\_bar\_scale\_boxed(FooBar \*self,

 FooBoxed \*boxed\_in,

 FooBoxed \*\*boxed\_out);

```

In particular, do not require the caller to pass an initialized `GValue` to

avoid the in-out annotation; instead, pass a `GValue` as an out argument, and

have the function initialize it.

#### Arrays[](#arrays "Permalink to this heading")

For reference types, zero-terminated arrays are the easiest to work with.

Arrays of primitive type such as “int” will require length metadata.

In a general-purpose library, it’s best not to expose GLib array and hash types

such as `GArray`, `GPtrArray`, `GByteArray`, `GList`, `GSList`,

`GQueue`, and `GHashTable` in the public API. They are fine for internal

libraries, but difficult in general for consumers of introspected libraries to

deal with.

#### Strings[](#strings "Permalink to this heading")

C treats strings as zero-terminated arrays of bytes, but many other languages do not. So don’t

write APIs that treat `const char \*` parameters as arrays that need an

`array length` annotation.

Treat all `const char \*` parameters as zero-terminated strings. Don’t use the

same entry point for zero-terminated strings as for byte arrays which may

contain embedded zeroes.

```

void foo\_bar\_snarf\_string(FooBar \*self,

 const char \*str);

void foo\_bar\_snarf\_bytes(FooBar \*self,

 const uint8\_t \*bytes,

 size\_t length);

```

In particular, avoid functions taking a `const char \*` with a signed length

that can be set to a negative value to let the function compute the string

length in bytes. These functions are hard to bind, and require manual overrides.

#### Callbacks[](#callbacks "Permalink to this heading")

Callbacks are hard to support for introspection bindings because of their

complex life-cycle. Try to avoid having more than one callback in the same

function, and consider using GClosure when you need more.

#### Using a different name for error domain quarks from the enum name[](#using-a-different-name-for-error-domain-quarks-from-the-enum-name "Permalink to this heading")

Error domain quarks should always be named in the form

<namespace>\_<module>\_error\_quark() for an error enum called

<Namespace><Module>Error. Example to avoid:

```

typedef enum FooBarError {

 FOO\_BAR\_ERROR\_MOO,

 FOO\_BAR\_ERROR\_BLEAT

};

GQuark foo\_bar\_errors\_quark();

```

#### Don’t have properties and methods with the same name[](#don-t-have-properties-and-methods-with-the-same-name "Permalink to this heading")

Some bindings for dynamic languages expose GObject properties and methods in the

same way, as properties on an object instance. So don’t make a GObject property

with the same name as a method, e.g. a property named `add-feature` on a class

named `SoupSession` which also has a method `soup\_session\_add\_feature()`.

#### Custom code in constructors[](#custom-code-in-constructors "Permalink to this heading")

Creating an object via `foo\_bar\_new()` shouldn’t execute any code

differently than creating the same object via `g\_object\_new()`, since many

bindings (and also GtkBuilder/Glade) create objects using `g\_object\_new()`.

That is, don’t do this:

```

FooBar \*

foo\_bar\_new (void)

{

 FooBar \*retval = FOO\_BAR (g\_object\_new (FOO\_TYPE\_BAR, NULL));

 retval->priv->some\_variable = 5; /\* Don't do this! \*/

 return retval;

}

```

Instead, put initialization code in the `foo\_bar\_init()` function or the

`foo\_bar\_constructed()` virtual function.

#### Transfer-none return values from the binding[](#transfer-none-return-values-from-the-binding "Permalink to this heading")

If your library expects to call a function from C which may be implemented in

another language and exposed through the binding (for example, a signal handler,

or a GObject vfunc), it’s best not to return transfer-none values, because what

you assume about storage lifetime in C may not apply in other languages.

For example,

```

typedef struct {

 GTypeInterface iface;

 const char \* (\*my\_vfunc) (FooBaz \*self); /\* Don't do this! \*/

 char \* (\*my\_better\_vfunc) (FooBaz \*self); /\* Do this instead! \*/

} FooBazIface;

```

A class that implements `FooBazIface` in another programming language may not

be able to return a static string here, because the language may not have a

concept of static storage lifetime, or it may not store strings as

zero-terminated UTF-8 bytes as C code would expect. This can cause memory leaks.

Instead, duplicate the string before returning it, and use transfer-full. This

recommendation applies to any data type with an ownership, including boxed and

object types.

Build System Integration[](#build-system-integration "Permalink to this heading")

----------------------------------------------------------------------------------

### Meson Integration[](#meson-integration "Permalink to this heading")

Support for generating GObject introspection data is included in Meson

directly and accessible through the `gnome.generate\_gir()` function. See

the [meson documentation](https://mesonbuild.com/Gnome-module.html#gnomegenerate_gir) for details.

For some real examples, see the meson build definitions of various GNOME

modules:

Pango:<https://gitlab.gnome.org/GNOME/pango/blob/master/pango/meson.build>

```

pango\_gir = gnome.generate\_gir(

  libpango,

  sources: pango\_sources + pango\_headers + [ pango\_enum\_h ],

  namespace: 'Pango',

  nsversion: pango\_api\_version,

  identifier\_prefix: 'Pango',

  symbol\_prefix: 'pango',

  export\_packages: 'pango',

  includes: [ 'GObject-2.0', 'cairo-1.0', ],

  header: 'pango/pango.h',

  install: true,

  extra\_args: gir\_args,

)

```

json-glib:<https://gitlab.gnome.org/GNOME/json-glib/blob/master/json-glib/meson.build>

```

json\_glib\_gir = gnome.generate\_gir(

  json\_lib,

  sources: source\_c + source\_h + json\_glib\_enums + [ json\_version\_h ],

  namespace: 'Json',

  nsversion: json\_api\_version,

  identifier\_prefix: 'Json',

  symbol\_prefix: 'json',

  export\_packages: json\_api\_name,

  includes: [ 'GObject-2.0', 'Gio-2.0', ],

  header: 'json-glib/json-glib.h',

  install: true,

  extra\_args: gir\_args,

)

```

### Autotools Integration[](#autotools-integration "Permalink to this heading")

The gobject-introspection package provides the following two macros for use in

your configure.ac file:

GOBJECT\_INTROSPECTION\_CHECK([version])This macro adds a `--enable-introspection=yes|no|auto` configure

option which defaults to `auto`.

* `auto` - Will set `HAVE\_INTROSPECTION` if gobject-introspection is available

and the version requirement is satisfied.

* `yes` - Will error out if gobject-introspection is missing or the version

requirement is not satisfied. `HAVE\_INTROSPECTION` will always be true.

* `no` - Will never error out and `HAVE\_INTROSPECTION` will always be false.

GOBJECT\_INTROSPECTION\_REQUIRE([version])This macro does not add a configure option and behaves as if

`--enable-introspection=yes`.

#### Example[](#example "Permalink to this heading")

You’ll need to adapt this for the library you’re adding introspection support

to.

* configure.ac (or configure.in if no .ac file is used)

```

GOBJECT_INTROSPECTION_CHECK([1.40.0])

```

* Makefile.am

```

DISTCHECK_CONFIGURE_FLAGS = --enable-introspection

```

or just add to the existing DISTCHECK\_CONFIGURE\_FLAGS

* foo/Makefile.am - must be near the end (after CLEANFILES has been set)

```

-include $(INTROSPECTION_MAKEFILE)

INTROSPECTION_GIRS =

INTROSPECTION_SCANNER_ARGS = --add-include-path=$(srcdir) --warn-all

INTROSPECTION_COMPILER_ARGS = --includedir=$(srcdir)

if HAVE_INTROSPECTION

introspection_sources = $(libfoo_1_0_la_SOURCES)

Foo-1.0.gir: libfoo-1.0.la

Foo_1_0_gir_INCLUDES = GObject-2.0

Foo_1_0_gir_CFLAGS = $(INCLUDES)

Foo_1_0_gir_LIBS = libfoo-1.0.la

Foo_1_0_gir_FILES = $(introspection_sources)

INTROSPECTION_GIRS += Foo-1.0.gir

girdir = $(datadir)/gir-1.0

gir_DATA = $(INTROSPECTION_GIRS)

typelibdir = $(libdir)/girepository-1.0

typelib_DATA = $(INTROSPECTION_GIRS:.gir=.typelib)

CLEANFILES += $(gir_DATA) $(typelib_DATA)

endif

```

You can also check out a complete example at

<https://gitlab.gnome.org/GNOME/gtk/blob/c0ba041c73214f82d2c32b2ca1fa8f3c388c6170/gtk/Makefile.am#L1571>

#### Makefile variable documentation[](#makefile-variable-documentation "Permalink to this heading")

`INTROSPECTION\_GIRS` is the entry point, you should list all the gir files

you want to build there in the XXX-Y.gir format where X is the name of the gir

(for example Gtk) and Y is the version (for example 2.0).

If output is Gtk-3.0.gir then you should name the variables like

`Gtk\_3\_0\_gir\_NAMESPACE`, `Gtk\_3\_0\_gir\_VERSION` etc.

* Required variables:

	+ `FILES` - C sources and headers which should be scanned

* One of these variables are required:

	+ `LIBS` - Library where the symbol represented in the gir can be found

	+ `PROGRAM` - Program where the symbol represented in the gir can be found

* Optional variables, commonly used:

	+ `INCLUDES` - Gir files to include without the .gir suffix, for instance

	GLib-2.0, Gtk-3.0. This is needed for all libraries which you depend on

	that provides introspection information.

	+ `SCANNERFLAGS` - Flags to pass in to the scanner, see g-ir-scanner(1)

	for a list

	+ `PACKAGES` - list of pkg-config names which cflags are required to parse

	the headers of this gir. Note that `INCLUDES` will already fetch the

	packages and thus the cflags for all dependencies.

	+ `EXPORT\_PACKAGES` - List of pkg-config names which are provided by this

	Gir.

	+ `CFLAGS` - Flags to pass in to the parser when scanning headers.

	Normally `INCLUDES` and `PACKAGES` will fetch the cflags for all

	dependencies. This is normally used for project specific CFLAGS.

	+ `LDFLAGS` - Linker flags used by the scanner. Normally `INCLUDES` and

	`PACKAGES` will fetch the ldflags for all dependencies. This is normally

	used for project-specific LDFLAGS (for instance if you’re building several

	libraries and typelibs).

* Optional variables, seldomly used:

	+ `NAMESPACE` - Namespace of the gir, first letter capital, rest should be

	lower case, for instance: ‘Gtk’, ‘Clutter’, ‘ClutterGtk’. If not present

	the namespace will be fetched from the gir filename, the part before the

	first dash. For ‘Gtk-3.0’, namespace will be ‘Gtk’.

	+ `VERSION` - Version of the gir, if not present, will be fetched from gir

	filename, the part after the first dash. For ‘Gtk-3.0’, version will be

	‘3.0’.

Annotations[](#annotations "Permalink to this heading")

--------------------------------------------------------

### GTK-Doc Format Primer[](#gtk-doc-format-primer "Permalink to this heading")

GObject-Introspection annotations are built on top of GTK-Doc comment

blocks. These are plain old C comment blocks, but formatted in a special

way. Each GTK-Doc comment block starts with a `/\*\*` on its own line

end ends with `\*/`, again on its own line.

The basic format of a GTK-Doc comment block looks like this:

```

/\*\*

 \* identifier\_name: (annotations)

 \* @parameter\_name: (annotations): description

 \*

 \* symbol description

 \*

 \* tag\_name: (annotations): description

 \*/

```

As we can see, a GTK-Doc comment block can be broken down into a couple of

parts. Each part is built out of one or more fields, separated by a `:`

character. Each part has to start on its own line. Fields cannot span multiple

lines except the various `description` fields.

The order in which parts are written is important. For example, putting a

`tag` part before the `symbol description` part is invalid as it would

result in the symbol description to be mistaken for the tag description.

In the above example we have:

* the start of a GTK-Doc comment block on line 1

* the identifier part on line 2

* a parameter part on line 3

* the symbol description on line 5

* a tag part on line 7

* the end of the comment block on line 8

#### identifier part[](#identifier-part "Permalink to this heading")

```

/\*\*

 \* identifier\_name: (annotations)

 \* ...

 \*/

```

The identifier part is required as it identifies the symbol you want to

annotate. It is always written on the line immediately following the start of

your GTK-Doc comment block (`/\*\*`).

The `identifier` part is constructed from:

* a required `identifier\_name` field

	+ different kinds of symbols that can be documented and annotated are

	described in the GTK-Doc manual.

* an optional `annotations` field

#### parameter part[](#parameter-part "Permalink to this heading")

```

/\*\*

 \* ...

 \* @parameter\_name: (annotations): description

 \* ...

 \*/

```

The `parameter` part is optional. This means that there can be 0 or more

parameters, depending on the symbol you are annotating.

`parameter` parts are constructed from:

* a required `parameter\_name` which starts with a `@` character

	+ this name should correspond with the parameter name of you function’s

	signature.

* an optional `annotations` field

* a required description field (can be “empty”)

	+ can contain a single paragraph (multiple lines but no empty lines) of

	text.

Note that multiple `parameter` parts are never separated by an empty line.

#### symbol description part[](#symbol-description-part "Permalink to this heading")

```

/\*\*

 \* ...

 \*

 \* symbol description

 \* ...

 \*/

```

The `symbol description` part is optional. When present, it must always be

preceded with an empty line. It can contain multiple paragraphs (multiple

lines and empty lines) describing what the function, property, signal, enum or

constant does.

#### tag part[](#tag-part "Permalink to this heading")

```

/\*\*

 \* ...

 \* tag\_name: (annotations)||value: description

 \* ...

 \*/

```

The `tag` part is optional. There can be 0 or more tags, depending on the

symbol you are annotating.

`tag` parts are constructed from:

* a required `tag\_name`

	+ There are only four valid tags: `Returns`, `Since`, `Deprecated`,

	and `Stability`.

* an optional `annotations` field (`Returns`)

**OR**

an optional `value` field (`Since`, `Deprecated`, and `Stability`)

* a required description field (can be “empty”)

	+ can contain multiple paragraphs (multiple lines and empty lines) of text.

`tag` parts can safely be preceded or followed by an empty line.

Tags taking an optional `value` field accept the following values:

| Tag | Value field | Description |

| --- | --- | --- |

| `Since` | `VERSION` | This symbol was added in version `VERSION`. |

| `Deprecated` | `VERSION` | This symbol has been deprecated since version `VERSION`. |

| `Stability` | `Stable`, `Unstable`, or `Private` | An informal description of the stability level of this symbol. |

##### GTK-Doc support[](#gtk-doc-support "Permalink to this heading")

If GTK-Doc doesn’t seem to understand your introspection annotations, you may

need to do two things:

1. make sure you are running GTK-Doc >= v1.12 (also try latest version from

git)

2. add `<xi:include href="xml/annotation-glossary.xml"><xi:fallback/></xi:include>`

to your master GTK-Doc document; e.g. see the end of [tester-docs.xml](https://gitlab.gnome.org/GNOME/gtk-doc/blob/master/tests/gobject/docs/tester-docs.xml)

### GObject-Introspection annotations[](#gobject-introspection-annotations "Permalink to this heading")

#### Symbol visibility[](#symbol-visibility "Permalink to this heading")

| Annotation | Applies to | Description | Since |

| --- | --- | --- | --- |

| `(skip)` | identifier | Omit the symbol from the introspected output. | [v0.6.4](https://gitlab.gnome.org/GNOME/gobject-introspection/commit/7549c8053d0229a12d9196cc8abae54a01a555d0)

[bz#556628](https://bugzilla.gnome.org/show_bug.cgi?id=556628) |

|  | paremeters, return value | Indicate that the parameter or return value is only useful in C and

should be skipped. | [v1.29.0](https://gitlab.gnome.org/GNOME/gobject-introspection/commit/9c6797e0478b5025c3f2f37b1331c1328cf34f4d)

[bz#649657](https://bugzilla.gnome.org/show_bug.cgi?id=649657) |

| `(rename-to SYMBOL)` | identifier | Rename the original symbol’s name to `SYMBOL`. If `SYMBOL` resolves

to a symbol name that is already used, the original binding for that

name is removed. | [v0.6.3](https://gitlab.gnome.org/GNOME/gobject-introspection/commit/23e6fa6993c046de032598127ea48d4a7ee00935)

[bz#556475](https://bugzilla.gnome.org/show_bug.cgi?id=556475) |

#### Memory and lifecycle management[](#memory-and-lifecycle-management "Permalink to this heading")

| Annotation | Applies to | Description | Since |

| --- | --- | --- | --- |

| `(transfer MODE)` | identifier (only properties) | Transfer ownership for the property, (see below) | [v0.9.0](https://gitlab.gnome.org/GNOME/gobject-introspection/commit/22ae017ffd3052c0b81822b2ca6e41626b76b9c4)

[bz#620484](https://bugzilla.gnome.org/show_bug.cgi?id=620484) |

|  | parameters, return value | Transfer mode for the parameter or return value (see below). | v0.5.0 unknown |

Transfer modes:

* `none`: the recipient does not own the value

* `container`: the recipient owns the container, but not the elements.

(Only meaningful for container types.)

* `full`: the recipient owns the entire value. For a refcounted type,

this means the recipient owns a ref on the value. For a container type,

this means the recipient owns both container and elements.

* `floating`: alias for none, can be used for floating objects.

`container` is usually a pointer to a list or hash table, eg GList, GSList,

GHashTable etc.

`elements` is what is contained inside the list: integers, strings, GObjects

etc.

#### Support for GObject objects[](#support-for-gobject-objects "Permalink to this heading")

| Annotation | Applies to | Description | Since |

| --- | --- | --- | --- |

| `(constructor)` | identifier | The annotated symbol should not become available as a static methods

but as a constructor. | [v0.10.2](https://gitlab.gnome.org/GNOME/gobject-introspection/commit/2c36790c)

[bz#561264](https://bugzilla.gnome.org/show_bug.cgi?id=561264) |

| `(method)` | identifier | This function is a method. | [v0.10.2](https://gitlab.gnome.org/GNOME/gobject-introspection/commit/09bca85d)

[bz#639945](https://bugzilla.gnome.org/show_bug.cgi?id=639945) |

| `(virtual SLOT)` | identifier | This function is the invoker for a virtual method. | [v0.6.3](https://gitlab.gnome.org/GNOME/gobject-introspection/commit/fdbe3cc3)

[bz#557383](https://bugzilla.gnome.org/show_bug.cgi?id=557383) |

| `(set-property NAME)` | identifier (only applies to methods) | This function is the setter method for the given GObject property.

A setter function is defined as being the public function that is

called by the `GObjectClass.set\_property` implementation in a

class. | [#13](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/13) |

| `(get-property NAME)` | identifier (only applies to methods) | This function is the getter method for the given GObject property.

A getter function is defined as being the public function that is

called by the `GObjectClass.get\_property` implementation in a

class. | [#13](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/13) |

| `(setter SYMBOL)` | identifier (only applies to properties) | This GObject property is accessed by the given setter function.

A setter function is defined as being the public function that is

called by the `GObjectClass.set\_property` implementation in a

class. | [#13](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/13) |

| `(getter SYMBOL)` | identifier (only applies to properties) | This GObject property is accessed by the given getter function.

A getter function is defined as being the public function that is

called by the `GObjectClass.get\_property` implementation in a

class. | [#13](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/13) |

| `(emitter METHOD)` | identifier (only applies to methods) | This signal is emitted by the given method |  |

| `(default-value VALUE)` | identifier (only applies to properties) | The default value of a GObject property, as a freeform string | [#4](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/4) |

#### Support for GObject closures[](#support-for-gobject-closures "Permalink to this heading")

| Annotation | Applies to | Description | Since |

| --- | --- | --- | --- |

| `(destroy)` | parameters | The parameter is part of a callback type and containing the `destroy\_data`. | [v0.6.3](https://gitlab.gnome.org/GNOME/gobject-introspection/commit/cf7621f3)

[bz#574284](https://bugzilla.gnome.org/show_bug.cgi?id=574284) |

| `(destroy DESTROY)` | parameters | The parameter defines the `destroy\_data` for a given callback. The

`DESTROY` option points to the parameter that is the actual callback. |  |

| `(closure)` | parameters | The parameter is part of a callback type and containing the `user\_data`. |  |

| `(closure CLOSURE)` | parameters | The parameter defines the `user\_data` for a given callback. The `CLOSURE` option

points to the parameter that is the actual callback. Many bindings can pass `NULL` here. |  |

#### Support for non-GObject fundamental objects[](#support-for-non-gobject-fundamental-objects "Permalink to this heading")

| Annotation | Applies to | Description | Since |

| --- | --- | --- | --- |

| `(ref-func FUNC)` | identifier | `FUNC` is the function used to ref a struct, must be a GTypeInstance | [v0.9.2](https://gitlab.gnome.org/GNOME/gobject-introspection/commit/1e9822c7)

[bz#568913](https://bugzilla.gnome.org/show_bug.cgi?id=568913) |

| `(unref-func FUNC)` | identifier | `FUNC` is the function used to unref a struct, must be a GTypeInstance |  |

| `(get-value-func FUNC)` | identifier | `FUNC` is the function used to convert a struct from a GValue,

must be a GTypeInstance |  |

| `(set-value-func FUNC)` | identifier | `FUNC` is the function used to convert from a struct to a GValue,

must be a GTypeInstance |  |

| `(copy-func FUNC)` | identifier | `FUNC` is the function used to copy a struct or a union | 1.76 |

| `(free-func FUNC)` | identifier | `FUNC` is the function used to free a struct or a union | 1.76 |

#### Type signature[](#type-signature "Permalink to this heading")

| Annotation | Applies to | Description | Since |

| --- | --- | --- | --- |

| `(nullable)` | parameters, return value | Indicates that `NULL` may be a valid value for a parameter

(in, out, inout), or return value (though note that return and out values which

are only `NULL` when throwing an error should not be annotated as

`(nullable)`). | [1.42](https://gitlab.gnome.org/GNOME/gobject-introspection/commit/1459ff3e)

[bz#660879](https://bugzilla.gnome.org/show_bug.cgi?id=660879) |

| `(not nullable)` | parameters, return value | Indicates that `NULL` is not a valid value for a parameter

(in, out, inout), or return value. | [1.48](https://gitlab.gnome.org/GNOME/gobject-introspection/commit/10cb665f)

[bz#729660](https://bugzilla.gnome.org/show_bug.cgi?id=729660) |

| `(optional)` | parameters | For `(out)` or `(inout)` parameters, signifies that the caller

can pass `NULL` to ignore this output parameter. | [1.42](https://gitlab.gnome.org/GNOME/gobject-introspection/commit/1459ff3e)

[bz#660879](https://bugzilla.gnome.org/show_bug.cgi?id=660879) |

| `(in)` | parameters | In parameter. | v0.5.0

unknown |

| `(out)` | parameters | Out parameter (automatically determine allocation). | v0.5.0

unknown |

| `(out caller-allocates)` | parameters | Out parameter, where the calling code must allocate storage. | [v0.6.13](https://gitlab.gnome.org/GNOME/gobject-introspection/commit/5589687a)

[bz#604749](https://bugzilla.gnome.org/show_bug.cgi?id=604749) |

| `(out callee-allocates)` | parameters | Out parameter, where the receiving function must allocate storage. |  |

| `(inout)` | parameters | In/out parameter. | v0.5.0

unknown |

| `(type TYPE)` | identifier | Override the default type, used for properties | [v0.6.2](https://gitlab.gnome.org/GNOME/gobject-introspection/commit/6de1b296)

[bz#546739](https://bugzilla.gnome.org/show_bug.cgi?id=546739) |

|  | parameters, return value | override the parsed C type with given type |  |

| `(array)` | parameters, return value | Arrays. | v0.5.0

unknown |

| `(array fixed-size=N)` | parameters, return value | array of fixed length N | v0.5.0

unknown |

| `(array length=PARAM)` | parameters, return value | array, fetch the length from parameter PARAM | v0.5.0

unknown |

| `(array zero-terminated=1)` | parameters, return value | array which is NULL terminated | [v0.6.0](https://gitlab.gnome.org/GNOME/gobject-introspection/commit/d15f8cde)

[bz#557786](https://bugzilla.gnome.org/show_bug.cgi?id=557786) |

| `(element-type TYPE)` | parameters, return value | Specify the type of the element inside a container.

Can be used in combination with (array). | v0.5.0

unknown |

| `(element-type KTYPE VTYPE)` | parameters, return value | Specify the types of the keys and values in a dictionary-like container

(eg, `GHashTable`). | v0.5.0

unknown |

| `(foreign)` | identifier | The annotated symbol is a foreign struct, meaning it is not available

in a g-i supported library. | [v0.6.12](https://gitlab.gnome.org/GNOME/gobject-introspection/commit/1edeccd2)

[bz#619450](https://bugzilla.gnome.org/show_bug.cgi?id=619450) |

| `(scope TYPE)` | parameters | The parameter is a callback, the `TYPE` option indicates the lifetime

of the call. It is mainly used by language bindings wanting to know when

the resources required to do the call (for instance ffi closures) can be

freed. | [v0.6.2](https://gitlab.gnome.org/GNOME/gobject-introspection/commit/bc88ef7b)

[bz#556489](https://bugzilla.gnome.org/show_bug.cgi?id=556489) |

Scope types:

* `call` (default) - Only valid for the duration of the call.

Can be called multiple times during the call.

* `async` - Only valid for the duration of the first callback invocation.

Can only be called once.

* `notified` - valid until the GDestroyNotify argument is called.

Can be called multiple times before the GDestroyNotify is called.

* `forever` - valid until the process terminates.

An example of a function using the `call` scope is `g\_slist\_foreach()`.

For `async` there is `g\_file\_read\_async()` and for notified

`g\_idle\_add\_full()`.

Default Annotations: To avoid having the developers annotate everything the

introspection framework is providing sane default annotation values for a

couple of situations:

* `(in)` parameters: `(transfer none)`

* `(inout)` and `(out)` parameters: `(transfer full)`

	+ if `(caller allocates)` is set: `(transfer none)`

* `gchar\*` means `(type utf8)`

* return values: `(transfer full)`

	+ `gchar\*` means `(type utf8) (transfer full)`

	+ `const gchar\*` means `(type utf8) (transfer none)`

	+ `GObject\*` defaults to `(transfer full)`

#### Data annotations[](#data-annotations "Permalink to this heading")

| Annotation | Applies to | Description | Since |

| --- | --- | --- | --- |

| `(value VALUE)` | identifier | Used to override constants for defined values,

VALUE contains the evaluated value | v0.5.0

unknown |

| `(attributes my.key=val my.key2)` | identifier, parameters, return value | Attributes are free-form “key=value” annotations. When present, at least

one key has to be specified. Assigning values to keys is optional. | [v0.9.0](https://gitlab.gnome.org/GNOME/gobject-introspection/commit/11cfe386)

[bz#571548](https://bugzilla.gnome.org/show_bug.cgi?id=571548) |

#### Deprecated GObject-Introspection annotations[](#deprecated-gobject-introspection-annotations "Permalink to this heading")

| Annotation | Description | Since |

| --- | --- | --- |

| `(null-ok)` | Replaced by `(allow-none)` | [v0.6.0](https://gitlab.gnome.org/GNOME/gobject-introspection/commit/dc651812)

[bz#557405](https://bugzilla.gnome.org/show_bug.cgi?id=557405) |

| `(in-out)` | Replaced by `(inout)` | [1.39.0](https://gitlab.gnome.org/GNOME/gobject-introspection/commit/a2b22ce7)

[bz#688897](https://bugzilla.gnome.org/show_bug.cgi?id=688897) |

| `(allow-none)` | Replaced by `(nullable)` and `(optional)` | [1.42](https://gitlab.gnome.org/GNOME/gobject-introspection/commit/1459ff3e)

[bz#660879](https://bugzilla.gnome.org/show_bug.cgi?id=660879) |

#### Possible future GObject-Introspection annotations[](#possible-future-gobject-introspection-annotations "Permalink to this heading")

These proposed additions are currently being discussed and in various stages

of development.

| Annotation | Applies to | Description | Since |

| --- | --- | --- | --- |

| `(default VALUE)` | parameters | Default value for a parameter. | [bz#558620](https://bugzilla.gnome.org/show_bug.cgi?id=558620) |

| `(error-domains DOM1 DOM2)` | parameters | Typed errors, similar to `throws` in Java. | unknown |

### Default Basic Types[](#default-basic-types "Permalink to this heading")

Basic types:

* gpointer: pointer to anything

* gboolean:boolean

* gint[8,16,32,64]: integer

* guint[8,16,32,64]: unsigned integer

* glong: long

* gulong: unsigned long

* GType: a gtype

* gfloat: float

* gdouble: double

* utf8: string encoded in UTF-8, not containing any embedded nuls

* filename: filename string (see below)

* guint8 array: binary data

Filename type:

The filename type represents an utf-8 string on Windows and a zero terminated

guint8 array on Unix. It should be used for filenames, environment variables

and process arguments.

### Reference to Object Instances[](#reference-to-object-instances "Permalink to this heading")

Instances:

* Object: a GObject instance

* Gtk.Button: a Gtk.Button instance

### Examples[](#examples "Permalink to this heading")

#### Transfer[](#transfer "Permalink to this heading")

```

/\*\*

 \* mylib\_get\_constant1:

 \*

 \* Returns: (transfer full): a constant, free when you used it

 \*/

gchar \*

mylib\_get\_constant1 (void)

{

   return g\_strdup("a constant");

}

```

```

/\*\*

 \* mylib\_get\_constant2:

 \*

 \* Returns: (transfer none): another constant

 \*/

const gchar \*

mylib\_get\_string2 (void)

{

   return "another constant";

}

```

```

/\*\*

 \* mylib\_get\_string\_list1:

 \*

 \* Returns: (element-type utf8) (transfer full): list of constants,

 \*          free the list with g\_slist\_free and the elements with g\_free when done.

 \*/

GSList \*

mylib\_get\_string\_list1 (void)

{

   GSList \*l = NULL;

   l = g\_slist\_append (l, g\_strdup ("foo"));

   l = g\_slist\_append (l, g\_strdup ("bar"));

   return l;

}

```

```

/\*\*

 \* mylib\_get\_string\_list2:

 \*

 \* Returns: (element-type utf8) (transfer container): list of constants

 \*          free the list with g\_slist\_free when done.

 \*/

GSList \*

mylib\_get\_string\_list2 (void)

{

   GSList \*l = NULL;

   l = g\_slist\_append (l, "foo");

   l = g\_slist\_append (l, "bar");

   return l;

}

```

#### Array length[](#array-length "Permalink to this heading")

```

/\*\*

 \* gtk\_list\_store\_set\_column\_types:

 \* @store: a #GtkListStore

 \* @n\_columns: Length of @types

 \* @types: (array length=n\_columns): List of types

 \*/

void

gtk\_list\_store\_set\_column\_types (GtkListStore \*list\_store,

                                 gint          n\_columns,

                                 GType        \*types);

```

#### Nullable parameters[](#nullable-parameters "Permalink to this heading")

A number of things are nullable by convention, which means that you do not

have to add a `(nullable)` annotation to your code for them to be marked as

nullable in a GIR file. If you need to mark a parameter or return value as not

nullable, use `(not nullable)` to override the convention. Conventionally,

the following are automatically nullable:

* `(closure)` parameters and their corresponding user data parameters

* `gpointer` parameters and return types, unless also annotated with

`(type)`

```

/\*\*

 \* gtk\_link\_button\_new\_with\_label:

 \* @uri: A URI

 \* @label: (nullable): A piece of text or NULL

 \*/

GtkWidget \*

gtk\_link\_button\_new\_with\_label (const gchar \*uri,

                                const gchar \*label);

```

```

/\*\*

 \* g\_source\_add\_unix\_fd:

 \* @source: a #GSource

 \* @fd: the fd to monitor

 \* @events: an event mask

 \*

 \* Returns: (not nullable): an opaque tag

 \*/

gpointer

g\_source\_add\_unix\_fd (GSource      \*source,

                      gint          fd,

                      GIOCondition  events);

/\*\*

 \* g\_source\_remove\_unix\_fd:

 \* @source: a #GSource

 \* @tag: (not nullable): the tag from g\_source\_add\_unix\_fd()

 \*/

void

g\_source\_remove\_unix\_fd (GSource  \*source,

                         gpointer  tag);

```

#### G(S)List contained types[](#g-s-list-contained-types "Permalink to this heading")

```

/\*\*

 \* gtk\_container\_get\_children:

 \* @container: A #GtkContainer

 \*

 \* Returns: (element-type Gtk.Widget) (transfer container): List of #GtkWidget

 \*/

GList\*

gtk\_container\_get\_children (GtkContainer \*container);

```

```

/\*\*

 \* FooBar:alist: (type GSList(NiceObj))

 \*

 \* This property is a GSList of NiceObj GOjects.

 \*/

    g\_object\_class\_install\_property (object\_class,

                                     FOO\_BAR\_PROP\_ALIST,

                                     g\_param\_spec\_pointer ("alist",

                                                           "Alist",

                                                           "A list of nice objects",

                                                           G\_PARAM\_READWRITE));

```

#### Direction[](#direction "Permalink to this heading")

```

/\*\*

 \* gtk\_widget\_get\_size\_request:

 \* @width: (out): Int to store width in

 \* @height: (out): Int to store height in

 \*/

```

#### Out parameters[](#out-parameters "Permalink to this heading")

This is a callee-allocates example; the (out) annotation automatically infers

this from the fact that there’s a double indirection on a structure parameter.

```

typedef struct \_FooSubObj FooSubObj

/\*\*

 \* foo\_obj\_get\_sub\_obj:

 \* @obj: A #FooObj

 \* @subobj: (out): A #FooSubObj

 \*

 \* Get a sub object.

 \*/

void

foo\_obj\_get\_sub\_obj (FooObj     \*obj,

                     FooSubObj \*\*subobj)

{

  \*subobj = foo\_sub\_object\_new ();

}

```

This is a caller-allocates example; the (out) annotation automatically infers

this from the fact that there’s only a single indirection on a structure

parameter.

```

typedef struct \_FooIter FooIter;

/\*\*

 \* foo\_obj\_get\_iter:

 \* @obj: A #FooObj

 \* @iter: (out): An iterator, will be initialized

 \*

 \* Get an iterator.

 \*/

void

foo\_obj\_get\_iter (FooObj \*obj,

                  FooIter \*iter)

{

  iter->state = 0;

}

```

An example which demonstrates an (optional) parameter: an (out) parameter

where the caller can pass NULL if they don’t want to receive the (out) value.

Note that if the GError is returned set, the value of contents and length might

be unspecified and should therefore not be used or freed.

```

/\*\*

 \* g\_file\_get\_contents:

 \* @filename: name of a file to read contents from, in the GLib file name encoding

 \* @contents: (out): location to store an allocated string, use g\_free() to free the returned string

 \* @length: (out) (optional): location to store length in bytes of the contents, or NULL

 \* @error: return location for a GError, or NULL

 \*

 \* [...]

 \*

 \* Returns: TRUE on success, FALSE if an error occurred

 \*/

gboolean g\_file\_get\_contents (const gchar \*filename,

                              gchar \*\*contents,

                              gsize \*length,

                              GError \*\*error);

/\* this is valid because length has (optional) \*/

g\_file\_get\_contents ("/etc/motd", &motd, NULL, &error); // VALID

/\* but this is not valid, according to those annotations \*/

g\_file\_get\_contents ("/etc/motd", NULL, NULL, &error); // NOT VALID

```

mylib\_hash\_table\_iter\_next() demonstrates the difference between (nullable) and

(optional) for (out) parameters. For an (out) parameter, (optional) indicates

that NULL may be passed by the caller to indicate they don’t want to receive

the (out) value. (nullable) indicates that NULL may be passed out by the

callee as the returned value.

```

/\*\*

 \* mylib\_hash\_table\_iter\_next:

 \* @iter: an initialized #MylibHashTableIter

 \* @key: (out) (optional): a location to store the key

 \* @value: (out) (optional) (nullable): a location to store the value

 \*

 \* [...]

 \*

 \* Returns: %FALSE if the end of the #MylibHashTable has been reached.

 \*/

gboolean

mylib\_hash\_table\_iter\_next (MylibHashTableIter \*iter,

                            gpointer           \*key,

                            gpointer           \*value);

/\* this is valid because value and key have (optional) \*/

mylib\_hash\_table\_iter\_next (iter, NULL, NULL);

gpointer key, value;

mylib\_hash\_table\_iter\_next (iter, &key, &value);

if (value == NULL)

  /\* this is valid because value has (nullable) \*/

if (key == NULL)

  /\* this is NOT VALID because key does not have (nullable) \*/

```

#### Rename to[](#rename-to "Permalink to this heading")

Rename to is an advisory annotation. It’s not required to fulfill the advisory

when generating or making a language binding. The way it is currently

implemented, if you rename a function to a name already in use, it will remove

the other binding. This is useful to eliminate unwanted/deprecated functions

from the binding.

Another (currently unimplemented) use for the rename annotation would be

overloading; for example, overloading of constructors or, like in this

example, overloading a method to be both an asynchronous and a synchronous one

(depending on the amount and what kind of parameters).

```

/\*\*

 \* my\_type\_perform\_async: (rename-to my\_type\_perform)

 \* @self: The this ptr

 \* @data: data

 \* @callback: callback when async operation finished

 \* @user\_data: user\_data for @callback

 \*

 \* Asynchronously perform

 \*\*/

void

my\_type\_perform\_async (MyType \*self, gpointer data,

                       GFunc callback,

                       gpointer user\_data);

/\*\*

 \* my\_type\_perform:

 \* @self: The this ptr

 \* @data: data

 \*

 \* Perform

 \*\*/

void

my\_type\_perform (MyType \*self, gpointer data);

```

In a language supporting method overloading, because we advised to rename to

perform, and because we have another perform already, this could be bound like

this:

```

class MyType {

  public void perform (Pointer data) { }

  public void perform (Pointer data, GFunc callback, Pointer user\_data) { }

}

```

However, currently the generated gir/typelib will only contain information

about my\_type\_perform\_async, which will shadow (ie, remove) the binding of

my\_type\_perform.

#### Attributes[](#attributes "Permalink to this heading")

Attributes are arbitrary key/value pairs that can be attached to almost any

item including classes, methods, signals, properties, parameters and return

values. These attributes appear in both the .gir and the .typelib files.

Attributes can serve as a mechanism for software higher in the toolchain.

Attributes are name-spaced using dot as a separator. At least one dot must

appear in the key name.

```

/\*\*

 \* my\_frobnicator\_poke\_path: (attributes gdbus.method PokePath)

 \* @frobnicator: A #MyFrobnicator

 \* @object\_path: (gdbus.signature o): An object path.

 \*

 \* Manipulate an object path.

 \*

 \* Returns: (gdbus.signature o): A new object path. Free with g\_free().

 \*/

gchar \*

my\_frobnicator\_poke\_path (MyFrobnicator \*frobnicator,

                          const gchar   \*object\_path)

```

#### Constants[](#constants "Permalink to this heading")

```

/\*\*

 \* MY\_CONSTANT: (value 100)

 \* A constant.

 \*/

#define MY\_CONSTANT 10 \* 10

```

Writing Bindings[](#writing-bindings "Permalink to this heading")

------------------------------------------------------------------

### Guidelines[](#guidelines "Permalink to this heading")

This page is intended as a guide describing the process of writing a language

binding for the GObject Introspection framework.

* Decide if you want to make a language binding which is implementation

agnostic or implementation specific. Some languages such as Python have

libraries which are available across implementations. The Python module

`ctypes` is a binding for the libffi language binding, which is

implemented in a couple of different Python implementations. It’s usually

easier to target a specific interpreter or compiler implementation so if you

unsure, write a specific one.

* For interpreted language implementations, construct the language binding on

top of the [libgirepository](index.html#document-writingbindings/libgirepository) library instead of writing a code generator.

It’ll make it easier for developers to use your language binding as they

will be able to read the typelibs in runtime without having an extra

intermediate step to generate the language specific metadata. The

libgirepository library can also be used for bindings based upon code

generators as an optimization, its a lot faster to read metadata from the

typelib than it is to extract the metadata from the GIR XML files.

* Use the Everything library in your unittests, aim at testing all functions

there. Do testing as early as possible in the development of the binding, as

the code is likely to be more complex than you anticipate.

* Use the same coding style as your language. If libraries for your language

normally uses underscores do that as well. For instance, Java bindings

should have a method on it’s GtkButton wrapper called `setLabel` and not

`set\_label`.

* If there are existing GObject bindings, reuse them for improved

compatibility. It’s a nice feature being able to use static bindings and

introspected bindings together. The Perl & Python bindings does that.

* Try to stay close to the C language semantics, for instance

GObject should be mapped to a class and gtk\_button\_set\_label to a method of

that class:

> 

> 

> 	+ java: `button.setLabel("foo")`

> 	+ javascript/python/vala: `button.set\_label("foo")`

> 	+ perl: `$button->set\_label("foo")`

> 	+ scheme: `(send button (set-label "foo"))`

>

### libgirepository[](#libgirepository "Permalink to this heading")

libgirepository is a C library which provides a C API for accessing the

typelib data and for interacting with the corresponding GObject based

libraries.

For more information about libgirepository see the [API documentation](https://gnome.pages.gitlab.gnome.org/gobject-introspection/girepository/).

The following example shows how to call the `g\_assertion\_message()` function

from libglib-2.0:

```

#include <girepository.h>

int

main (void)

{

 GIRepository \*repository;

 GError \*error = NULL;

 GIBaseInfo \*base\_info;

 GIArgument in\_args[5];

 GIArgument retval;

 repository = g\_irepository\_get\_default ();

 g\_irepository\_require (repository, "GLib", "2.0", 0, &error);

 if (error)

 {

 g\_error ("ERROR: %s\n", error->message);

 return 1;

 }

 base\_info = g\_irepository\_find\_by\_name (repository, "GLib", "assertion\_message");

 if (!base\_info)

 {

 g\_error ("ERROR: %s\n", "Could not find GLib.assertion\_message");

 return 1;

 }

 in\_args[0].v\_pointer = (gpointer)"domain";

 in\_args[1].v\_pointer = (gpointer)"glib-print.c";

 in\_args[2].v\_int = 42;

 in\_args[3].v\_pointer = (gpointer)"main";

 in\_args[4].v\_pointer = (gpointer)"hello world";

 if (!g\_function\_info\_invoke ((GIFunctionInfo \*) base\_info,

 (const GIArgument \*) &in\_args,

 5,

 NULL,

 0,

 &retval,

 &error))

 {

 g\_error ("ERROR: %s\n", error->message);

 return 1;

 }

 g\_base\_info\_unref (base\_info);

 return 0;

}

```

Command Line Tools[](#command-line-tools "Permalink to this heading")

----------------------------------------------------------------------

### g-ir-compiler[](#g-ir-compiler "Permalink to this heading")

#### Typelib compiler[](#typelib-compiler "Permalink to this heading")

Manual section:

1

##### SYNOPSIS[](#synopsis "Permalink to this heading")

**g-ir-compiler** [OPTION…] GIRFILE

##### DESCRIPTION[](#description "Permalink to this heading")

g-ir-compiler converts one or more GIR files into one or more typelib. The

output will be written to standard output unless the `--output` is

specified.

##### OPTIONS[](#options "Permalink to this heading")

`--help`

Show help options

`--output=FILENAME`

Save the resulting output in FILENAME.

`--verbose`

Show verbose messages

`--debug`

Show debug messages

`--includedir=DIRECTORY`

Adds a directory which will be used to find includes inside the GIR format.

`--module=MODULE`

FIXME

`--shared-library=FILENAME`

Specifies the shared library where the symbols in the typelib can be

found. The name of the library should not contain the ending shared

library suffix.

`--version`

Show program’s version number and exit

##### BUGS[](#bugs "Permalink to this heading")

Report bugs at <https://gitlab.gnome.org/GNOME/gobject-introspection/issues>

##### HOMEPAGE and CONTACT[](#homepage-and-contact "Permalink to this heading")

<https://gi.readthedocs.io/>

##### AUTHORS[](#authors "Permalink to this heading")

Mattias Clasen

### g-ir-doc-tool[](#g-ir-doc-tool "Permalink to this heading")

#### Documentation builder[](#documentation-builder "Permalink to this heading")

Manual section:

1

##### SYNOPSIS[](#synopsis "Permalink to this heading")

**g-ir-doc-tool** [OPTION…] GIRFILE

##### DESCRIPTION[](#description "Permalink to this heading")

g-ir-doc-tool builds library documentation directly from .gir files. The output

is adjusted according to which programming language you’re generating docs for.

##### OPTIONS[](#options "Permalink to this heading")

`--help`

Show help options

`--output=DIRECTORY`

Save the resulting output in DIRECTORY.

`--format=FORMAT`

Output format. One of devdocs, mallard or sections.

`--language=LANGUAGE`

Output language. One of c, python, or gjs.

`--add-include-path=DIRECTORY`

Adds a directory which will be used to find includes inside the GIR format.

`--version`

Show program’s version number and exit

`--write-sections-file`

Backwards-compatible equivalent to -f sections.

##### BUGS[](#bugs "Permalink to this heading")

Report bugs at <https://gitlab.gnome.org/GNOME/gobject-introspection/issues>

##### HOMEPAGE and CONTACT[](#homepage-and-contact "Permalink to this heading")

<https://gi.readthedocs.io/>

##### AUTHORS[](#authors "Permalink to this heading")

David King

### g-ir-generate[](#g-ir-generate "Permalink to this heading")

#### Typelib generator[](#typelib-generator "Permalink to this heading")

Manual section:

1

##### SYNOPSIS[](#synopsis "Permalink to this heading")

**g-ir-generate** [OPTION…] FILES…

##### DESCRIPTION[](#description "Permalink to this heading")

g-ir-generate is an GIR generator, using the repository API. It generates GIR

files from a raw typelib or in a shared library (`--shlib`). The output will

be written to standard output unless the `--output` is specified.

##### OPTIONS[](#options "Permalink to this heading")

`--help`

Show help options

`--shlib=FILENAME`

The shared library to read the symbols from.

`--output=FILENAME`

Save the resulting output in FILENAME.

`--version`

Show program’s version number and exit

##### BUGS[](#bugs "Permalink to this heading")

Report bugs at <https://gitlab.gnome.org/GNOME/gobject-introspection/issues>

##### HOMEPAGE and CONTACT[](#homepage-and-contact "Permalink to this heading")

<https://gi.readthedocs.io/>

##### AUTHORS[](#authors "Permalink to this heading")

Mattias Clasen

### g-ir-scanner[](#g-ir-scanner "Permalink to this heading")

#### Extracting C metadata from sources and headers[](#extracting-c-metadata-from-sources-and-headers "Permalink to this heading")

Manual section:

1

##### SYNOPSIS[](#synopsis "Permalink to this heading")

**g-ir-scanner** [OPTION…] FILES…

##### DESCRIPTION[](#description "Permalink to this heading")

g-ir-scanner is a tool which generates GIR XML files by parsing headers and

introspecting GObject based libraries. It is usually invoked during the normal

build step for a project and the information is saved to disk and later

installed, so that language bindings and other applications can use it. Header

files and source files are passed in as arguments on the command line. The

suffix determines whether a file be treated as a source file (.c) or a header

file (.h). Currently only C based libraries are supported by the scanner.

##### OPTIONS[](#options "Permalink to this heading")

`--help`

Show help options

`--quiet`

If passed, do not print details of normal operation.

`--warn-all`

Display warnings for public API which is not introspectable.

`--warn-error`

Make warnings be fatal errors.

`--strict`

Display warnings for introspectable API that may present issues when

consumed by known language bindings.

`--format=FORMAT`

This parameters decides which the resulting format will be used. The

default value is gir.

`--include=NAME`

Add the specified introspection dependency to the scanned namespace.

NAME is of the form NAMESPACE-VERSION, like Gtk-3.0.

`--include-uninstalled=PATH`

Add the specified introspection dependency to the scanned namespace.

This differs from `--include` in that it takes a file path, and does not

process the pkg-config dependencies (since they may not be installed yet).

`--add-include-path=PATH`

Add a directory to the path which the scanner uses to find GIR files. Can

be used multiple times to specify multiple directories

`-i, --library=LIBRARY`

Specifies a library that will be introspected. This means that the

\*\_get\_type() functions in it will be called for GObject data types. The

name of the library should not contain the leading lib prefix nor the

ending shared library suffix.

`-L, --library-path=PATH`

Include this directory when searching for a library. This option can be

specified multiple times to include more than one directory to look for

libraries in.

`-Idirectory`

Include this directory in the list of directories to be searched for

header files. You need to pass to the scanner all the directories you’d

normally pass to the compiler when using the specified source files.

`--c-include=C\_INCLUDES`

Headers which should be included in C programs. This option can be

specified multiple times to include more than one header.

`-n, --namespace=NAME`

The namespace name. This name should be capitalized, eg the first letter

should be upper case. Examples: Gtk, Clutter, WebKit.

`--no-libtool`

Disable usage of libtool for compiling stub introspection binary. Use this

if your build system does not require libtool.

`--libtool`

Full path to libtool executable. Typically used for Automake systems.

`--nsversion=VERSION`

The namespace version. For instance 1.0. This is usually the platform

version, eg 2.0 for Gtk+, not 2.12.7.

`-p, --program=PROGRAM`

Specifies a binary that will be introspected. This means that the

\*\_get\_type() functions in it will be called for GObject data types. The

binary must be modified to take a `--introspect-dump=` option, and to pass

the argument to this function to g\_irepository\_dump.

`--program-arg=ARG`

Additional argument to pass to program for introspection.

`--identifier-prefix=PREFIX`

This option may be specified multiple times. Each one gives a prefix that

will be stripped from all C identifiers. If none specified, the namespace

will be used. Eg, an identifier prefix of Foo will export the identifier

typdef struct \_FooBar FooBar; as Foo.Bar.

`--symbol-prefix=PREFIX`

This option may be specified multiple times. Each one gives a

prefix that will be stripped from all C symbols. Eg, an symbol

prefix of foo will export the symbol foo\_bar\_do\_something as

Foo.Bar.do\_something.

`--accept-unprefixed`

If specified, the scanner will accept identifiers and symbols which do not

match the namespace prefix. Try to avoid using this if possible.

`--output=FILENAME`

Name of the file to output. Normally namespace + format extension. Eg,

GLib-2.0.gir.

`--pkg=PACKAGE`

List of pkg-config packages to get compiler and linker flags from. This

option can be specified multiple times to include flags from several

pkg-config packages.

`--pkg-export=PACKAGE`

List of pkg-config packages that are provided by the generated gir. This

option can be specified multiple times if the gir provides more packages.

If not specified, the packages specified with `--pkg=` will be used.

`--compiler=COMPILER`

The C compiler to be used internally by g-ir-scanner when introspecting

the run time type information, like properties, signals, ancestors, and

implemented interfaces. It has the same semantics as the `CC` environment

variable.

`--verbose`

Be verbose, include some debugging information.

##### ENVIRONMENT VARIABLES[](#environment-variables "Permalink to this heading")

The g-ir-scanner uses the `XDG\_DATA\_DIRS` variable to check for dirs, the

girs are located in `XDG\_DATA\_DIRS/gir-1.0`. It is normally set on a

distribution so you shouldn’t need to set it yourself.

The variable `GI\_SCANNER\_DISABLE\_CACHE` ensures that the scanner will not

write cache data to `$HOME`.

The variable `GI\_SCANNER\_DEBUG` can be used to debug issues in the

build-system that involve g-ir-scanner. When it is set to `save-temps`, then

g-ir-scanner will not remove temporary files and directories after it

terminates.

The variable `GI\_HOST\_OS` can be used to control the OS name on the host

that runs the scanner. It has the same semantics as the Python `os.name`

property.

##### BUGS[](#bugs "Permalink to this heading")

Report bugs at <https://gitlab.gnome.org/GNOME/gobject-introspection/issues>

##### HOMEPAGE and CONTACT[](#homepage-and-contact "Permalink to this heading")

<https://gi.readthedocs.io/>

##### AUTHORS[](#authors "Permalink to this heading")

Johan Dahlin

[g-ir-compiler](index.html#document-tools/g-ir-compiler)Typelib compiler

[g-ir-doc-tool](index.html#document-tools/g-ir-doc-tool)Documentation builder

[g-ir-generate](index.html#document-tools/g-ir-generate)Typelib generator

[g-ir-scanner](index.html#document-tools/g-ir-scanner)Extracting C metadata from sources and headers

GObject introspection is a middleware layer between C libraries (using

GObject) and language bindings. The C library can be scanned at compile time

and generate metadata files, in addition to the actual native C library. Then

language bindings can read this metadata and automatically provide bindings to

call into the C library.

[![_images/overview.svg](_images/overview.svg)](_images/overview.svg)

The GI project consists of:

* an XML format called GIR containing introspection information in a machine parseable format

* a Python package to create and parse the GIR format

* a scanner to generate GIR format from C source and headers

* a typelib similar to xpcom/msole which stores the information on disk in a binary format

* a compiler to compile the typelib from a xml format (and vice versa)

* C library to read the typelib, [libgirepository](index.html#document-writingbindings/libgirepository).

Getting the code[](#getting-the-code "Permalink to this heading")

------------------------------------------------------------------

The latest stable release is available from

<https://download.gnome.org/sources/gobject-introspection>

GObject Introspection is stored in git and can be fetched:

```

git clone https://gitlab.gnome.org/GNOME/gobject-introspection.git

```

You can browse the repository online [here](https://gitlab.gnome.org/GNOME/gobject-introspection/).

Reporting bugs[](#reporting-bugs "Permalink to this heading")

--------------------------------------------------------------

For a list of existing bugs and feature requests, see the [issues page](https://gitlab.gnome.org/GNOME/gobject-introspection/issues). You can also

[open an issue](https://gitlab.gnome.org/GNOME/gobject-introspection/issues/new).

Contact[](#contact "Permalink to this heading")

------------------------------------------------

For questions or additional information, please use:

* Discourse: <https://discourse.gnome.org/tag/introspection>

* IRC: #introspection on irc.gnome.org

