buildsys: add some comments (#5602)

aclocal.m4

@@ -1,4 +1,7 @@
 # Make sure to include any M4 files needed by configure.ac here
+#
+# This file is manually maintained and *not* generated by aclocal.
+# See configure.ac for further information.
 m4_include([cnf/m4/ax_append_compile_flags.m4])
 m4_include([cnf/m4/ax_append_flag.m4])
 m4_include([cnf/m4/ax_check_compile_flag.m4])

autogen.sh

@@ -1,6 +1,8 @@
 #!/bin/sh
 #
 # Regenerate configure from configure.ac. Requires GNU autoconf.
+# We do not use autoreconf because it is only part of GNU automake,
+# and also because it had various other issues in the past.
 set -ex
 autoconf -Wall -f
 autoheader -Wall -f

configure.ac

@@ -37,6 +37,10 @@ AC_INIT([GAP],
 AC_CONFIG_SRCDIR([src/gap.c])
 AC_CONFIG_AUX_DIR([cnf])
 
+dnl we do not use AC_CONFIG_MACRO_DIR but rather a manually created aclocal.m4;
+dnl this is in parts because autoreconf and aclocal are only available via GNU automake,
+dnl which we do not use; but also because there is no obvious benefit to using it.
+
 AC_CONFIG_HEADERS([build/config.h:src/config.h.in])
 AC_CONFIG_COMMANDS([build/stamp-h], [echo timestamp > build/stamp-h])