From 7bfc84094d7dc1f03af7314c4a74c216bc5a92f5 Mon Sep 17 00:00:00 2001
From: Nick Bowler <nbowler@draconx.ca>
Date: Wed, 9 May 2012 20:02:29 -0400
Subject: [PATCH] Better document fix-gnulib.

Add a big blurb in the comments describing the main bits required to use
the script in a project.  Also rename the header variables a bit so we
can ensure future compatibility with the documented behaviour.
---
 scripts/fix-gnulib.pl | 40 ++++++++++++++++++++++++++++++++++++----
 snippet/glconfig.mk   |  2 +-
 2 files changed, 37 insertions(+), 5 deletions(-)

diff --git a/scripts/fix-gnulib.pl b/scripts/fix-gnulib.pl
index f2c8cfe..85ae632 100755
--- a/scripts/fix-gnulib.pl
+++ b/scripts/fix-gnulib.pl
@@ -3,6 +3,38 @@
 # Copyright © 2011-2012 Nick Bowler
 #
 # Prepare the Gnulib tree for inclusion into a non-recursive automake build.
+# While the output of gnulib-tool is "include"-able if the --makefile-name
+# option is used, it is still not suitable for non-recursive use for a couple
+# reasons; chief among them is that filenames are not relative to the top
+# source directory.
+#
+# This script postprocesses the gnulib-tool output to produce something that
+# is intended to be suitable for inclusion into such non-recursive build
+# environments.  Since the integration involves both configure.ac and
+# Makefile.am, the output must be included into _both_.  Supposing the output
+# is written to lib/gnulib.mk, you would add:
+#
+#   m4_include([lib/gnulib.mk]) # to configure.ac, after any call to gl_INIT
+#   include $(top_srcdir)/lib/gnulib.mk # to Makefile.am
+#
+# You must also arrange for the Gnulib-generated header files to be built
+# before the object files which depend on them; the most robust way to do this
+# is by explicit prerequisites, for example:
+#
+#   bin_PROGRAMS = foo
+#   $(foo_OBJECTS): $(gnulib_headers)
+#
+# The $(gnulib_headers) variable will expand to GNU-make order-only
+# prerequisites when available, avoiding spurious incremental rebuilds when
+# unused headers are changed.  If this feature is not available, it will
+# expand to ordinary prerequisites.  It is therefore only appropriate for use
+# in target prerequisites; the $(gnulib_raw_headers) variable may be used in
+# other contexts when only the list of header files is required.
+#
+# This script also provides machinery for Gnulib symbol renaming via the
+# glconfig.mk Makefile.am snippet; use of this feature is optional.
+#
+# Most of the specific transformations are documented below.
 #
 # License WTFPL2: Do What The Fuck You Want To Public License, version 2.
 # This is free software: you are free to do what the fuck you want to.
@@ -103,9 +135,9 @@ m4_unquote(m4_argn([2], [
 # This trick should define gnulib_orderonly to | iff we're using GNU make.
 gnulib_have_orderonly = $(findstring order-only,$(.FEATURES))
 gnulib_orderonly = $(gnulib_have_orderonly:order-only=|)
-gnulib_core_headers = $(gnulib_orderonly)
-gnulib_src_headers = $(gnulib_core_headers)
-gnulib_headers = $(gnulib_src_headers)
+gnulib_core_headers =
+gnulib_raw_headers = $(gnulib_core_headers)
+gnulib_headers = $(gnulib_orderonly) $(gnulib_raw_headers)
 EOF
 
 		$printed_header = 1;
@@ -178,7 +210,7 @@ EOF
 
 print <<'EOF';
 gnulib_lt_objects = $(libgnu_la_OBJECTS) $(gl_LTLIBOBJS)
-$(gnulib_lt_objects): $(gnulib_src_headers)
+$(gnulib_lt_objects): $(gnulib_headers)
 EOF
 print @cleanfiles;
 
diff --git a/snippet/glconfig.mk b/snippet/glconfig.mk
index 218eec0..dd999af 100644
--- a/snippet/glconfig.mk
+++ b/snippet/glconfig.mk
@@ -21,7 +21,7 @@ GLSYM_V_  = $(GLSYM_V_$(AM_DEFAULT_VERBOSITY))
 GLSYM_V_0 = @echo "  GLSYM " $<;
 
 gnulib_symfiles = $(gnulib_lt_objects:.lo=.glsym)
-gnulib_src_headers += $(GLCONFIG)
+gnulib_headers += $(GLCONFIG)
 
 # This suffix rule triggers symbol generation only on demand.  Dependencies are
 # not tracked directly, so it must remain phony and thus not create the target.
-- 
2.43.0