hwloc: allow frameworks to have alternate header filenames

Frameworks are usually required to have a framework/framework.h file.
However, this is sometimes problematic (see the hwloc use case/problem
description, below).

This commit allows frameworks to have an "autogen.options" file (i.e.,
project/mca/framework/autogen.options) that specifies things that
autogen needs to know about the framework.  Currently, the only option
recognized in autogen.options is "framework_header", which allows a
framework to specify that its header file is named something other
than "framework.h" (the framework header file must still be in the
project/mca/framework directory; it simply may be named something
other than framework.h).  More options may be introduced over time.

The use case that motivated this is the hwloc framework
(https://github.com/open-mpi/ompi/issues/2616).

Per MCA framework rules, the hwloc framework is required to have an
opal/mca/hwloc/hwloc.h file.  However, the hwloc library itself *also*
has an hwloc.h file.  This causes a problem when configuring Open MPI
with --with-hwloc=external (meaning: do not use the hwloc embedded
within the Open MPI source code tree -- instead, use an hwloc
installation from outside the Open MPI source code tree).
Specifically, when in the opal/mca/hwloc directory, the presence of
"-I." in DEFAULT_INCLUDES (put there by Automake) causes a confusion
between the hwloc.h in opal/mca/hwloc/hwloc.h and the system-installed
hwloc.h.  Chaos ensues (see the GitHub issue for more detail).

The solution is to rename the opal/mca/hwloc/hwloc.h to something else
(e.g., hwloc-internal.h), and extend autogen.pl to allow frameworks to
have an alternate name for their framework header file.

This commit introduces the autogen.pl mechanism to allow the alternate
header file name.  A follow-on commit will effect this change in the
hwloc framework (and update all the places in the code base to use the
new filename).

Signed-off-by: Jeff Squyres <jsquyres@cisco.com>

autogen.pl

@@ -1,6 +1,6 @@
 #!/usr/bin/env perl
 #
-# Copyright (c) 2009-2016 Cisco Systems, Inc.  All rights reserved.
+# Copyright (c) 2009-2017 Cisco Systems, Inc.  All rights reserved
 # Copyright (c) 2010      Oracle and/or its affiliates.  All rights reserved.
 # Copyright (c) 2013      Mellanox Technologies, Inc.
 #                         All rights reserved.
@@ -432,11 +432,28 @@ sub mca_process_project {
             next
                 if (! -d "$dir/$d" || $d eq "base" || substr($d, 0, 1) eq ".");
 
-            # If this directory has a $dir.h file and a base/
+            my $framework_header = "$dir/$d/$d.h";
+
+            # If there's a $dir/$d/autogen.options file, read it
+            my $ao_file = "$dir/$d/autogen.options";
+            if (-r $ao_file) {
+                verbose "\n>>> Found $dir/$d/autogen.options file\n";
+                open(IN, $ao_file) ||
+                    die "$ao_file present, but cannot open it";
+                while (<IN>) {
+                    if (m/\s*framework_header\s*=\s*(.+?)\s*$/) {
+                        verbose "    Framework header entry: $1\n";
+                        $framework_header = "$dir/$d/$1";
+                    }
+                }
+                close(IN);
+            }
+
+            # If this directory has a framework header and a base/
             # subdirectory, or its name is "common", then it's a
             # framework.
             if ("common" eq $d || !$project->{need_base} ||
-                (-f "$dir/$d/$d.h" && -d "$dir/$d/base")) {
+                (-f $framework_header && -d "$dir/$d/base")) {
                 verbose "\n=== Found $pname / $d framework\n";
                 mca_process_framework($topdir, $project, $d);
             }