Add more comments to configure.

configure

@@ -13,20 +13,27 @@
 # If you have problems, try without defining CC and CFLAGS before reporting
 # an error.
 
+# start off configure.log
 echo -------------------- >> configure.log
 echo $0 $* >> configure.log
 date >> configure.log
 
+# set command prefix for cross-compilation
 if [ -n "${CHOST}" ]; then
     uname="`echo "${CHOST}" | sed -e 's/^[^-]*-\([^-]*\)$/\1/' -e 's/^[^-]*-[^-]*-\([^-]*\)$/\1/' -e 's/^[^-]*-[^-]*-\([^-]*\)-.*$/\1/'`"
     CROSS_PREFIX="${CHOST}-"
 fi
 
+# destination name for static library
 STATICLIB=libz.a
+
+# extract zlib version numbers from zlib.h
 VER=`sed -n -e '/VERSION "/s/.*"\(.*\)".*/\1/p' < zlib.h`
 VER3=`sed -n -e '/VERSION "/s/.*"\([0-9]*\\.[0-9]*\\.[0-9]*\).*/\1/p' < zlib.h`
 VER2=`sed -n -e '/VERSION "/s/.*"\([0-9]*\\.[0-9]*\)\\..*/\1/p' < zlib.h`
 VER1=`sed -n -e '/VERSION "/s/.*"\([0-9]*\)\\..*/\1/p' < zlib.h`
+
+# establish commands for library building
 if "${CROSS_PREFIX}ar" --version >/dev/null 2>/dev/null || test $? -lt 126; then
     AR=${AR-"${CROSS_PREFIX}ar"}
     test -n "${CROSS_PREFIX}" && echo Using ${AR} | tee -a configure.log
@@ -47,6 +54,8 @@ if "${CROSS_PREFIX}nm" --version >/dev/null 2>/dev/null || test $? -lt 126; then
 else
     NM=${NM-"nm"}
 fi
+
+# set defaults before processing command line options
 LDCONFIG=${LDCONFIG-"ldconfig"}
 LDSHAREDLIBC="${LDSHAREDLIBC--lc}"
 ARCHS=
@@ -68,6 +77,7 @@ old_cflags="$CFLAGS"
 OBJC='$(OBJZ) $(OBJG)'
 PIC_OBJC='$(PIC_OBJZ) $(PIC_OBJG)'
 
+# process command line options
 while test $# -ge 1
 do
 case "$1" in
@@ -100,6 +110,7 @@ case "$1" in
     esac
 done
 
+# define functions for testing compiler and library characteristics and logging the results
 test=ztest$$
 
 show()
@@ -150,6 +161,7 @@ tryboth()
 
 echo >> configure.log
 
+# check for gcc vs. cc and set compile and link flags based on the system identified by uname
 cat > $test.c <<EOF
 extern int getchar();
 int hello() {return getchar();}
@@ -302,12 +314,14 @@ else
   esac
 fi
 
+# destination names for shared library if not defined above
 SHAREDLIB=${SHAREDLIB-"libz$shared_ext"}
 SHAREDLIBV=${SHAREDLIBV-"libz$shared_ext.$VER"}
 SHAREDLIBM=${SHAREDLIBM-"libz$shared_ext.$VER1"}
 
 echo >> configure.log
 
+# see if shared library build supported
 if test $shared -eq 1; then
   echo Checking for shared library support... | tee -a configure.log
   # we must test in two steps (cc then ld), required at least on SunOS 4.x
@@ -335,6 +349,9 @@ else
   TEST="all teststatic testshared"
 fi
 
+echo >> configure.log
+
+# check for underscores in external names for use by assembler code
 CPP=${CPP-"$CC -E"}
 case $CFLAGS in
   *ASMV*)
@@ -350,6 +367,7 @@ esac
 
 echo >> configure.log
 
+# check for large file support, and if none, check for fseeko()
 cat > $test.c <<EOF
 #include <sys/types.h>
 off64_t dummy = 0;
@@ -382,6 +400,7 @@ fi
 
 echo >> configure.log
 
+# check for strerror() for use by gz* functions
 cat > $test.c <<EOF
 #include <string.h>
 #include <errno.h>
@@ -395,10 +414,12 @@ else
   echo "Checking for strerror... No." | tee -a configure.log
 fi
 
+# copy clean zconf.h for subsequent edits
 cp -p zconf.h.in zconf.h
 
 echo >> configure.log
 
+# check for unistd.h and save result in zconf.h
 cat > $test.c <<EOF
 #include <unistd.h>
 int main() { return 0; }
@@ -413,6 +434,7 @@ fi
 
 echo >> configure.log
 
+# check for stdarg.h and save result in zconf.h
 cat > $test.c <<EOF
 #include <stdarg.h>
 int main() { return 0; }
@@ -425,6 +447,7 @@ else
   echo "Checking for stdarg.h... No." | tee -a configure.log
 fi
 
+# if the z_ prefix was requested, save that in zconf.h
 if test $zprefix -eq 1; then
   sed < zconf.h "/#ifdef Z_PREFIX.* may be/s/def Z_PREFIX\(.*\) may be/ 1\1 was/" > zconf.temp.h
   mv zconf.temp.h zconf.h
@@ -432,6 +455,7 @@ if test $zprefix -eq 1; then
   echo "Using z_ prefix on all symbols." | tee -a configure.log
 fi
 
+# if --solo compilation was requested, save that in zconf.h and remove gz stuff from object lists
 if test $solo -eq 1; then
   sed '/#define ZCONF_H/a\
 #define Z_SOLO
@@ -442,6 +466,7 @@ OBJC='$(OBJZ)'
 PIC_OBJC='$(PIC_OBJZ)'
 fi
 
+# if code coverage testing was requested, use older gcc if defined, e.g. "gcc-4.2" on Mac OS X
 if test $cover -eq 1; then
   CFLAGS="${CFLAGS} -fprofile-arcs -ftest-coverage"
   if test -n "$GCC_CLASSIC"; then
@@ -451,6 +476,10 @@ fi
 
 echo >> configure.log
 
+# conduct a series of tests to resolve eight possible cases of using "vs" or "s" printf functions
+# (using stdarg or not), with or without "n" (proving size of buffer), and with or without a
+# return value.  The most secure result is vsnprintf() with a return value.  snprintf() with a
+# return value is secure as well, but then gzprintf() will be limited to 20 arguments.
 cat > $test.c <<EOF
 #include <stdio.h>
 #include <stdarg.h>
@@ -636,6 +665,7 @@ EOF
   fi
 fi
 
+# see if we can hide zlib internal symbols that are linked between separate source files
 if test "$gcc" -eq 1; then
   echo >> configure.log
   cat > $test.c <<EOF
@@ -655,6 +685,7 @@ EOF
   fi
 fi
 
+# clean up files produced by running the compiler and linker
 rm -f $test.[co] $test $test$shared_ext $test.gcno
 
 # show the results in the log
@@ -691,7 +722,7 @@ echo -------------------- >> configure.log
 echo >> configure.log
 echo >> configure.log
 
-# udpate Makefile
+# udpate Makefile with the configure results
 sed < Makefile.in "
 /^CC *=/s#=.*#=$CC#
 /^CFLAGS *=/s#=.*#=$CFLAGS#
@@ -721,6 +752,7 @@ sed < Makefile.in "
 /^test: */s#:.*#: $TEST#
 " > Makefile
 
+# create zlib.pc with the configure results
 sed < zlib.pc.in "
 /^CC *=/s#=.*#=$CC#
 /^CFLAGS *=/s#=.*#=$CFLAGS#