Make C/Python search paths for GIR XML consistent, add $GI_GIR_PATH

My original interest in this was that it was useful for #323, but it also fixes inconsistencies between the C and Python search paths (#455 (closed)).

A good way to debug this is:

• configure gobject-introspection with --prefix=/opt/gnome (or anything else not in /usr) so that you can see the difference between /usr/local, /usr and $prefix;
• configure with -Dgir_dir_prefix=lib64 or similar (from !63 (merged)) so that you can see the difference between share/gir-1.0 and lib64/gir-1.0;
• copy some GIR XML (I used /usr/share/gir-1.0/Flatpak-1.0.gir) and edit it to add <include name="DoesNotExist" version="0"/>;
• to see the Python search path, run g-ir-doc-tool -I /foo -o out Flatpak-1.0.gir and look at the error message;
• to see the C search path, run G_MESSAGES_DEBUG=all g-ir-compiler --debug --includedir /foo -o out.typelib Flatpak-1.0.gir (which requires at least the first commit from here) or use strace

---

• girparser: Emit debug messages to show the GIR XML search path

  This makes it a bit easier to see what is going on than using strace.

  Helps: #323, #455 (closed)

• girparser: Make ownership transfers out of locate_gir() more obvious

• girparser: Use g_clear_pointer() in locate_gir()

  This makes the ownership semantics a bit more obvious.

• Python tools: Don't prepend /usr/share to the search path for GIR XML

  This code was presumably intended to add a relocatable path ${bindir}/../${gir_dir_prefix}/gir-1.0 to the search path, where ${bindir} is computed at runtime and ${gir_dir_prefix} is hard-coded at configure time. However, this didn't work as intended for two reasons:

  • the gir-1.0 suffix was missing, so in practice we would look for GIR XML in a location like /usr/share/Gio-2.0.gir or /usr/lib64/Gio-2.0.gir, not find it, and proceed to the next search path entry;
  • the @gir_dir_prefix@ substituted from the build system is currently an absolute path, so os.path.join would discard ${bindir}/.. and use the compile-time @gir_dir_prefix@ as-is

  If this had worked as intended, its precedence would also have been inconsistent with the C code: the Python code searches GIRDIR before the XDG_DATA_DIRS, but the C code searches its direct equivalent, GIR_DIR, after the XDG_DATA_DIRS.

  Since this doesn't seem to be doing anything useful, discard it. This leaves builtins.GIRDIR set to either empty (normally) or just the ${srcdir}/gir/ (when running uninstalled).

  Helps: #323, #455 (closed)

• Add GI_GIR_PATH environment variable

  This is searched after any command-line includes paths, but before the XDG_DATA_DIRS or any built-in paths. For example, if libraries are installed in /opt/gnome and GObject-Introspection was configured with -Dgir_dir_prefix=lib64, you could set either GI_GIR_PATH=/opt/gnome/lib64/gir-1.0 or XDG_DATA_DIRS=/opt/gnome/lib64:/opt/gnome/share:${XDG_DATA_DIRS}.

  Use this to communicate the ../gir directory to giscanner instead of modifying Python's builtins.

  Helps: #323, #455 (closed)

• build: Leave gir_dir_prefix unexpanded

  This will let us append it to relative paths inside giscanner to get a relocatable path relative to the tools, which seems to have always been the intention.

  Helps: #323, #455 (closed)

• giscanner: Search the same compile-time GIR_DIR used for the C code

  The difference between DATADIR/gir-1.0 and this one is that this one respects the -Dgir_dir_prefix build-time option.

  Helps: #323, #455 (closed)

• girepository: Search the same paths as the Python code

  The Python code historically always searched DATADIR/gir-1.0 (always) and /usr/share/gir-1.0 (only on Unix); since the previous commit, they are searched after the GIR_DIR. Do the same here, to make the C and Python search paths match up.

  With the default gir_dir_prefix, searching both GIR_DIR and DATADIR/gir-1.0 is redundant. However, if gir_dir_prefix is changed to something else, for example -Dgir_dir_prefix=lib64, always searching DATADIR/gir-1.0 provides backwards compatibility with pre-existing GIR that might already be stored in DATADIR/gir-1.0.

  Resolves: #455 (closed) (in conjunction with previous commit)
  Helps: #323

• Search XDG_DATA_HOME/gir-1.0 for GIR XML too

  For completeness. There probably won't be any, but the XDG base directory specification is most useful if it's consistently followed everywhere, and the specification says to look in XDG_DATA_HOME before XDG_DATA_DIRS.