HACKING

   1 Notes to developers hacking on GObjectIntrospection
   2 ===================================================
   3
   4 updating GLib bindings
   5 ----------------------
   6
   7 Some bindings are not generated by the libraries themselves, usually
   8 for dependency reasons, but are updated through some ad hoc utilities.
   9
  10 Updating GLib, Gio, GModule, GObject bindings:
  11 ```sh
  12 $ git clone https://gitlab.gnome.org/GNOME/glib.git
  13 $ meson _build
  14 $ ninja -C _build
  15 $ ./misc/update-glib-annotations.py glib/
  16 ```
  17
  18 In short, build gobject-introspection in the `_build` directory, and
  19 run the script on a `glib` checkout.
  20
  21 debugging
  22 ---------
  23
  24 * You can use the GI_SCANNER_DEBUG environment variable; see utils.py
  25   for a list of debug flags.
  26
  27 * It is possible to debug the various g-ir-* tools using PyDev's remote debugger.
  28   To do this:
  29     - locate the directory that contains the pydevd.py file matching the PyDev version
  30       running in your Eclipse instance. This might look like:
  31       /usr/lib64/eclipse/dropins/pydev-core/eclipse/plugins/org.python.pydev_4.0.0.201505131500/pysrc/)
  32     - open the "Debug" perspective in your Eclipse instance, open the "PyDev" menu and start the
  33       debug server
  34     - execute the g-ir-* tool setting the GI_SCANNER_DEBUG and PYDEVDPATH environment variables.
  35       For example:
  36       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>
  37     - In the example above, the PyDev debugger will run g-ir-scanner and stop execution in the main
  38       script. You can then set extra breakpoints, step through the code, inspect variables at the
  39       current scope, inspect the stack and so forth.
  40
  41
  42 giscanner
  43 ---------
  44
  45 * If you add a new warning to annotationparser.py, you should add new
  46   tests for it in tests/scanner/annotationparser/gi/
  47
  48 * If you add a new warning elsewhere (maintransformer.py, etc), you
  49   should add a new test for it in tests/warn/
  50
  51 * Before pushing code to the repository, make sure to run 'make check' or
  52   even 'make distcheck'
  53
  54 * While hacking on annotationparser.py it is a good idea to:
  55     1) Update your GLib build to git master.
  56     2) Run the following command from your gobject-introspection source directory before making
  57        changes to annotationparser.py (adapt GLib source and/or build directory as required):
  58        (cd misc && ./update-glib-annotations.py /path/to/gnome.org/checkout/glib/)
  59     3) Ensure changes to the following files are as expected, meaning they are caused by
  60        updated GLib annotations and not by stray modifications to annotationparser.py:
  61          - gir/gio-2.0.c
  62          - gir/glib-2.0.c
  63          - gir/gobject-2.0.c
  64        When satisfied, commit these files adding "Update GLib annotations to master" as the
  65        commit message.
  66     4) Only now start editing annotationparser.py.
  67     5) run make check.
  68     6) Run update-glib-annotations.py again and carefully study the changes (if any) to:
  69          - gir/gio-2.0.c
  70          - gir/glib-2.0.c
  71          - gir/gobject-2.0.c
  72        Ensure changes in these files are as intended and caused by the modifications done to
  73        annotationparser.py. Commit the changes to annotationparser.py and the above
  74        files as a single patch.