build: Source 'localenv' in top-level Makefile.

Also document 'local*' files.

2 files changed, 37 insertions, 0 deletions

diff --git a/Makefile.am b/Makefile.am
index 5c33076e..153a7e37 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -15,6 +15,8 @@
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
+-include $(top_builddir)/localenv
+
 include $(top_srcdir)/subdir-rules.mk
 
 ACLOCAL_AMFLAGS = -I m4
diff --git a/src/guestfs.pod b/src/guestfs.pod
index 60664e7f..f6a759d8 100644
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -3267,6 +3267,41 @@ functions in files under C<daemon>.
 
 To build from source, first read the C<README> file.
 
+=head2 C<local*> FILES
+
+Files in the top source directory that begin with the prefix C<local*>
+are ignored by git.  These files can contain local configuration or
+scripts that you need to build libguestfs.
+
+By convention, I have a file called C<localconfigure> which is a
+simple wrapper around C<autogen.sh> containing local configure
+customizations that I need:
+
+ . localenv
+ ./autogen.sh \
+     --with-default-attach-method=libvirt \
+     --enable-gcc-warnings \
+     --enable-gtk-doc \
+     -C \
+     "$@"
+
+So I can use this to build libguestfs:
+
+ ./localconfigure && make
+
+If there is a file in the top build directory called C<localenv>, then
+it will be sourced by C<make>.  This file can contain any local
+environment variables needed, eg. for skipping tests:
+
+ # Use an alternate python binary.
+ export PYTHON=python3
+ # Skip this test, it is broken.
+ export SKIP_TEST_BTRFS_FSCK=1
+
+Note that C<localenv> is included by the top Makefile (so it's a
+Makefile fragment).  But if it is also sourced by your
+C<localconfigure> script then it is used as a shell script.
+
 =head2 ADDING A NEW API ACTION
 
 Because large amounts of boilerplate code in libguestfs are generated,