Notes to developers hacking on GObjectIntrospection
===================================================

updating GLib bindings
----------------------

Some bindings are not generated by the libraries themselves, usually
for dependency reasons, but are updated through some ad hoc utilities.

Updating GLib, Gio, GModule, GObject bindings:
```sh
$ git clone https://gitlab.gnome.org/GNOME/glib.git
$ meson _build
$ ninja -C _build
$ ./misc/update-glib-annotations.py glib/
```

In short, build gobject-introspection in the `_build` directory, and
run the script on a `glib` checkout.

debugging
---------

* You can use the GI_SCANNER_DEBUG environment variable; see utils.py
  for a list of debug flags.

* It is possible to debug the various g-ir-* tools using PyDev's remote debugger.
  To do this:
    - locate the directory that contains the pydevd.py file matching the PyDev version
      running in your Eclipse instance. This might look like:
      /usr/lib64/eclipse/dropins/pydev-core/eclipse/plugins/org.python.pydev_4.0.0.201505131500/pysrc/)
    - open the "Debug" perspective in your Eclipse instance, open the "PyDev" menu and start the
      debug server
    - execute the g-ir-* tool setting the GI_SCANNER_DEBUG and PYDEVDPATH environment variables.
      For example:
      GI_SCANNER_DEBUG="pydevd" PYDEVDPATH="/usr/lib64/eclipse/dropins/pydev-core/eclipse/plugins/org.python.pydev_4.0.0.201505131500/pysrc/" g-ir-scanner <parameters>
    - In the example above, the PyDev debugger will run g-ir-scanner and stop execution in the main
      script. You can then set extra breakpoints, step through the code, inspect variables at the
      current scope, inspect the stack and so forth.


giscanner
---------

* If you add a new warning to annotationparser.py, you should add new
  tests for it in tests/scanner/annotationparser/gi/

* If you add a new warning elsewhere (maintransformer.py, etc), you
  should add a new test for it in tests/warn/

* Before pushing code to the repository, make sure to run 'make check' or
  even 'make distcheck'

* While hacking on annotationparser.py it is a good idea to:
    1) Update your GLib build to the tip of the `main` branch.
    2) Run the following command from your gobject-introspection source directory before making
       changes to annotationparser.py (adapt GLib source and/or build directory as required):
       (cd misc && ./update-glib-annotations.py /path/to/gnome.org/checkout/glib/)
    3) Ensure changes to the following files are as expected, meaning they are caused by
       updated GLib annotations and not by stray modifications to annotationparser.py:
         - gir/gio-2.0.c
         - gir/glib-2.0.c
         - gir/gobject-2.0.c
       When satisfied, commit these files adding "Update GLib annotations to ${commit}" as the
       commit message. Fill out the `${commit}` with the GLib commit at the tip of the `main`
       development branch
    4) Only now start editing annotationparser.py.
    5) run make check.
    6) Run update-glib-annotations.py again and carefully study the changes (if any) to:
         - gir/gio-2.0.c
         - gir/glib-2.0.c
         - gir/gobject-2.0.c
       Ensure changes in these files are as intended and caused by the modifications done to
       annotationparser.py. Commit the changes to annotationparser.py and the above
       files as a single patch.
