From 108509ec19cd6584e46971118e7c563dfd00fac8 Mon Sep 17 00:00:00 2001
From: "Richard W.M. Jones" <rjones@redhat.com>
Date: Wed, 27 Jul 2016 19:02:49 +0100
Subject: [PATCH] docs: hacking: Add a section describing the build system.

---
 docs/guestfs-hacking.pod | 38 ++++++++++++++++++++++++++++++--------
 1 file changed, 30 insertions(+), 8 deletions(-)

diff --git a/docs/guestfs-hacking.pod b/docs/guestfs-hacking.pod
index 1adf2ca7a..6b7ac1cc8 100644
--- a/docs/guestfs-hacking.pod
+++ b/docs/guestfs-hacking.pod
@@ -18,13 +18,14 @@ run the generator (C<./autogen.sh && make -C generator>) in order to
 create those files.
 
 Libguestfs uses an autotools-based build system, with the main files
-being F<configure.ac> and F<Makefile.am>.  The F<generator>
-subdirectory contains the generator, plus files describing the API.
-The F<src> subdirectory contains source for the library.  The
-F<appliance> and F<daemon> subdirectories contain the source for the
-code that builds the appliance, and the code that runs in the
-appliance respectively.  Other directories are covered in the section
-L<SOURCE CODE SUBDIRECTORIES> below.
+being F<configure.ac> and F<Makefile.am>.  See L</THE BUILD SYSTEM>.
+
+The F<generator> subdirectory contains the generator, plus files
+describing the API.  The F<src> subdirectory contains source for the
+library.  The F<appliance> and F<daemon> subdirectories contain the
+source for the code that builds the appliance, and the code that runs
+in the appliance respectively.  Other directories are covered in the
+section L<SOURCE CODE SUBDIRECTORIES> below.
 
 Apart from the fact that all API entry points go via some generated
 code, the library is straightforward.  (In fact, even the generated
@@ -150,7 +151,7 @@ Logo used on the website.  The fish is called Arthur by the way.
 
 =item F<m4>
 
-M4 macros used by autoconf.
+M4 macros used by autoconf.  See L</THE BUILD SYSTEM>.
 
 =item F<make-fs>
 
@@ -260,6 +261,27 @@ Language bindings.
 
 =back
 
+=head1 THE BUILD SYSTEM
+
+Libguestfs uses the GNU autotools build system (autoconf, automake,
+libtool).
+
+The F<./configure> script is generated from F<configure.ac> and
+F<m4/guestfs_*.m4>.  Most of the configure script is split over many
+m4 macro files by topic, for example F<m4/guestfs_daemon.m4> deals
+with the dependencies of the daemon.
+
+The job of the top level F<Makefile.am> is mainly to list the
+subdirectories (C<SUBDIRS>) in the order they should be compiled.
+
+F<common-rules.mk> is included in every F<Makefile.am> (top level and
+subdirectories).  F<subdir-rules.mk> is included only in subdirectory
+F<Makefile.am> files.
+
+There are many make targets.  Use this command to list them all:
+
+ make help
+
 =head1 ADDING A NEW API
 
 Because large amounts of boilerplate code in libguestfs are generated,