Allow checking for GDK backends

Now that a single shared object can contain multiple backends we also
need to provide a simple way for third party code to verify that the
copy of GDK they are linking to supports their backend.

The simplest way to verify is an m4 macro, GTK_CHECK_BACKEND(), shipped
with the gtk+ m4 macros.

The usage is pretty basic:

  GTK_CHECK_BACKEND([x11], [gtk_has_x11=yes], [gtk_has_x11=no])
  AM_CONDITIONAL(BUILD_X11_CODE, test "x$gtk_has_x11" = "xno")

https://bugzilla.gnome.org/show_bug.cgi?id=642479

3 files changed, 73 insertions, 0 deletions

diff --git a/docs/reference/gtk/compiling.sgml b/docs/reference/gtk/compiling.sgml
index 58d97edbce..6f593a0d60 100644
--- a/docs/reference/gtk/compiling.sgml
+++ b/docs/reference/gtk/compiling.sgml
@@ -69,5 +69,33 @@ define the preprocessor symbol GDK_MULTIDEVICE_SAFE by using the command
 line option <literal>-DGTK_MULTIDEVICE_SAFE=1</literal>.
 </para>
 
+  <refsect2>
+    <title>Useful autotools macros</title>
+
+    <para>
+      GTK+ provides various macros for easily checking version and backends
+      supported. The macros are
+      <variablelist>
+        <varlistentry>
+          <term>AM_PATH_GTK_3_0([minimum-version], [if-found], [if-not-found], [modules])</term>
+          <listitem>This macro should be used to check that GTK+ is installed
+          and available for compilation. The four arguments are optional, and
+          they are: <emphasis>minimum-version</emphasis>, the minimum version
+          of GTK+ required for compilation; <emphasis>if-found</emphasis>, the
+          action to perform if a valid version of GTK+ has been found;
+          <emphasis>if-not-found</emphasis>, the action to perform if a valid
+          version of GTK+ has not been found; <emphasis>modules</emphasis>, a
+          list of modules to be checked along with GTK+.</listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>GTK_CHECK_BACKEND([backend-name], [if-found], [if-not-found])</term>
+          <listitem>This macro should be used to check if a specific backend
+          is supported by GTK+. The <emphasis>if-found</emphasis> and the
+          <emphasis>if-not-found</emphasis> arguments are optional.</listitem>
+        </varlistentry>
+      </variablelist>
+    </para>
+  </refsect2>
+
 </refsect1>
 </refentry>
diff --git a/docs/reference/gtk/migrating-2to3.xml b/docs/reference/gtk/migrating-2to3.xml
index 98a700abab..8be399639d 100644
--- a/docs/reference/gtk/migrating-2to3.xml
+++ b/docs/reference/gtk/migrating-2to3.xml
@@ -891,6 +891,19 @@ gdk_window_add_filter (NULL, message_filter, NULL);
        }
       </programlisting></informalexample>
     </para>
+    <para>
+      If you used the pkg-config variable <varname>target</varname> to
+      conditionally build part of your project depending on the GDK backend,
+      for instance like this:
+      <informalexample><programlisting>
+AM_CONDITIONAL(BUILD_X11, test `$PKG_CONFIG --variable=target gtk+-2.0` = "x11")
+      </programlisting></informalexample>
+      then you should now use the M4 macro provided by GTK+ itself:
+      <informalexample><programlisting>
+GTK_CHECK_BACKEND([x11], [have_x11=yes], [have_x11=no])
+AM_CONDITIONAL(BUILD_x11, [test "x$have_x11" = "xyes"])
+      </programlisting></informalexample>
+    </para>
   </section>
 
   <section>
diff --git a/m4macros/gtk-3.0.m4 b/m4macros/gtk-3.0.m4
index 7d00bc1f6c..3147a76920 100644
--- a/m4macros/gtk-3.0.m4
+++ b/m4macros/gtk-3.0.m4
@@ -194,3 +194,35 @@ main ()
   AC_SUBST(GTK_LIBS)
   rm -f conf.gtktest
 ])
+
+dnl GTK_CHECK_BACKEND(BACKEND-NAME [, ACTION-IF-FOUND [, ACTION-IF-NOT-FOUND]])
+dnl   Tests for BACKEND-NAME in the GTK targets list
+dnl
+AC_DEFUN([GTK_CHECK_BACKEND],
+[
+  backend=$1
+  if test "x$backend" = "x"; then
+    AC_MSG_ERROR([A backend must be specified])
+  fi
+
+  PKG_PROG_PKG_CONFIG([0.16])
+  GDK_TARGETS=`$PKG_CONFIG --variable=targets gdk-3.0`
+  if test "x$GDK_TARGETS" = "x"; then
+    ifelse([$3],,[AC_MSG_ERROR([GDK targets not found.])],[$3])
+  else
+    ifelse([$2],,[:],[$2])
+  fi
+
+  target_found=no
+  for target in $GDK_TARGETS; do
+    if test "x$target" = "x$backend"; then
+      target_found=yes
+    fi
+  done
+
+  if test "x$target_found" = "xno"; then
+    ifelse([$3],,[AC_MSG_ERROR([Backend $backend not found.])],[$3])
+  else
+    ifelse([$2],,[:],[$2])
+  fi
+])