build: add site.h as a place to put environment-specific defines

Most people consume Gluster in one of two ways:

 * From packages provided by their OS/distribution vendor

 * By building themselves from source

For the first group it doesn't matter whether configuration is done in
a configure script, via command-line options to that configure script,
or in a header file.  All of these end up as edits to some file under
the packager's control, which is then run through their tools and
process (e.g. rpmbuild) to create the packages that users will
install.

For the second group, convenience matters.  Such users might not even
have a script wrapped around the configure process, and editing one
line in a header file is a lot easier than editing several in the
configure script.  This also prevents a messy profusion of configure
options, dozens of which might need to be added to support a single
such user's preferences.  This comes back around as greater simplicity
for packagers as well.

This patch defines site.h as the header file for options and
parameters that someone building the code for themselves might want to
tweak.  The project can ship one version to reflect the developers'
guess at the best defaults for most users, and sophisticated users
with unusual needs can override many options at once just by
maintaining their own version of that file.  Everybody wins.  Further
guidelines for how to determine whether an option should go in
configure.ac or site.h are explained within site.h itself.

Change-Id: I2663a7dcbdf2f7066cd8eef19ad9eb30a2e72e74
Signed-off-by: Jeff Darcy <jdarcy@fb.com>
Reviewed-on: https://review.gluster.org/17300
Tested-by: Jeff Darcy <jeff@pl.atyp.us>
CentOS-regression: Gluster Build System <jenkins@build.gluster.org>
NetBSD-regression: NetBSD Build System <jenkins@build.gluster.org>
Smoke: Gluster Build System <jenkins@build.gluster.org>
Reviewed-by: Kevin Vigor <kvigor@fb.com>

3 files changed, 30 insertions, 2 deletions

diff --git a/Makefile.am b/Makefile.am
index d36f53055ea..c6f5618b541 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,3 +1,4 @@
+SOURCES = site.h
 EXTRA_DIST = autogen.sh \
 	COPYING-GPLV2 COPYING-LGPLV3 \
 	INSTALL README.md AUTHORS THANKS NEWS \
diff --git a/configure.ac b/configure.ac
index b045333e825..59a3f865709 100644
--- a/configure.ac
+++ b/configure.ac
@@ -33,7 +33,7 @@ if libtool --help 2>&1 | grep -q quiet; then
    AM_LIBTOOLFLAGS="--quiet";
 fi
 
-AC_CONFIG_HEADERS([config.h])
+AC_CONFIG_HEADERS([config.h site.h])
 
 AC_CONFIG_FILES([Makefile
                 libglusterfs/Makefile
@@ -1376,7 +1376,7 @@ CONTRIBDIR='$(top_srcdir)/contrib'
 AC_SUBST(CONTRIBDIR)
 
 GF_CPPDEFINES='-D_FILE_OFFSET_BITS=64 -D_GNU_SOURCE -D$(GF_HOST_OS)'
-GF_CPPINCLUDES='-include $(top_builddir)/config.h -I$(top_srcdir)/libglusterfs/src -I$(top_builddir)/libglusterfs/src'
+GF_CPPINCLUDES='-include $(top_builddir)/config.h -include $(top_builddir)/site.h -I$(top_srcdir)/libglusterfs/src -I$(top_builddir)/libglusterfs/src'
 GF_CPPFLAGS="$GF_CPPFLAGS $GF_CPPDEFINES $GF_CPPINCLUDES"
 AC_SUBST([GF_CPPFLAGS])
 
diff --git a/site.h.in b/site.h.in
new file mode 100644
index 00000000000..d917d78e59b
--- /dev/null
+++ b/site.h.in
@@ -0,0 +1,27 @@
+/*
+ * Guidelines for using this file vs. configure.ac
+ *
+ * (1) If it already exists in configure.ac, leave it there.
+ *
+ * (2) If it needs to take effect at configure (not compile) time, it *needs*
+ * to go in configure.ac.
+ *
+ * (3) If it affects file paths, which are the things most likely to be based
+ * on an OS or distribution's generic filesystem hierarchy and not on a
+ * particular package's definition (e.g. an RPM specfile), it should probably
+ * go in configure.ac.
+ *
+ * (4) If it affects default sizes, limits, thresholds, or modes of operation
+ * (e.g. IPv4 vs. IPv6), it should probably go here.
+ *
+ * (5) For anything else, is it more like the things in 3 or the things in 4?
+ * Which approach is more convenient for the people who are likely to use the
+ * new option(s)?  Make your best guesses, confirm with others, and go with
+ * what works.
+ */
+
+/*
+ * This is just an example, and a way to check whether site.h is actually being
+ * included automatically.
+ */
+#define SITE_DOT_H_TEST		9987