Add .PHONY rules and documentation to preemptively stop trouble that plagued

Tk from hitting Tcl too, and to make the overall makefile easier to understand.
Some reorganization too to move related rules closer together.

2 files changed, 149 insertions, 88 deletions

diff --git a/ChangeLog b/ChangeLog
index dde921d..0e5bf08 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,18 +1,25 @@
+2009-11-26  Donal K. Fellows  <dkf@users.sf.net>
+
+	* unix/Makefile.in: Add .PHONY rules and documentation to preemptively
+	stop trouble that plagued Tk from hitting Tcl too, and to make the
+	overall makefile easier to understand. Some reorganization too to move
+	related rules closer together.
+
 2009-11-26  Jan Nijtmans  <nijtmans@users.sf.net>
 
-	* win/Makefile.in      Fix [Bug 2902965] stub related changes
-	* win/makefile.vc      cause tclkit built to break
+	* win/Makefile.in:	[Bug 2902965]: Fix stub related changes that
+	* win/makefile.vc:	caused tclkit build to break.
 	* win/tclAppInit.c
 	* unix/tcl.m4
 	* unix/Makefile.in
 	* unix/tclAppInit.c
-	* unix/configure       (regenerated)
+	* unix/configure:	(regenerated)
 
 2009-11-25  Kevin B. Kenny  <kennykb@acm.org>
 
-	* win/Makefile.in:	Added a 'test-tcl' rule that is identical
-	to 'test' except that it does not go spelunking in 'pkgs/'. (This
-	rule has existed in unix/Makefile.in for some time.)
+	* win/Makefile.in:	Added a 'test-tcl' rule that is identical to
+	'test' except that it does not go spelunking in 'pkgs/'. (This rule
+	has existed in unix/Makefile.in for some time.)
 	
 2009-11-25  Stuart Cassoff  <stwo@users.sf.net>
 
@@ -24,19 +31,18 @@
 
 2009-11-24  Andreas Kupries  <andreask@activestate.com>
 
-	* library/tclIndex: Manually redone the part of tclIndex dealing
-	with safe.tcl and tm.tcl. This part passes the testsuite. Note
-	that automatic regeneration of this part is not possible because
-	it wrongly puts 'safe::Setup' on the list, and wrongly leaves out
-	'safe::Log' which is more dynamically created than the generator
-	expects.
+	* library/tclIndex: Manually redone the part of tclIndex dealing with
+	safe.tcl and tm.tcl. This part passes the testsuite. Note that
+	automatic regeneration of this part is not possible because it wrongly
+	puts 'safe::Setup' on the list, and wrongly leaves out 'safe::Log'
+	which is more dynamically created than the generator expects.
 
 	Further note that the file "clock.tcl" is explicitly loaded by
-	"init.tcl", the first time the clock command is invoked. The
-	relevant code can be found at line 172ff, roughly, the definition
-	of the procedure 'clock'. This means none of the procedures of
-	this file belong in the tclIndex. Another indicator that automatic
-	regeneration of tclIndex is ill-advised.
+	"init.tcl", the first time the clock command is invoked. The relevant
+	code can be found at line 172ff, roughly, the definition of the
+	procedure 'clock'. This means none of the procedures of this file
+	belong in the tclIndex. Another indicator that automatic regeneration
+	of tclIndex is ill-advised.
 
 2009-11-24  Donal K. Fellows  <dkf@users.sf.net>
 
diff --git a/unix/Makefile.in b/unix/Makefile.in
index d42a0e5..b4a4566 100644
--- a/unix/Makefile.in
+++ b/unix/Makefile.in
@@ -4,7 +4,7 @@
 # "./configure", which is a configuration script generated by the "autoconf"
 # program (constructs like "@foo@" will get replaced in the actual Makefile.
 #
-# RCS: @(#) $Id: Makefile.in,v 1.282 2009/11/26 07:01:47 nijtmans Exp $
+# RCS: @(#) $Id: Makefile.in,v 1.283 2009/11/26 09:40:32 dkf Exp $
 
 VERSION 		= @TCL_VERSION@
 MAJOR_VERSION		= @TCL_MAJOR_VERSION@
@@ -582,6 +582,10 @@ ZLIB_SRCS = \
 SRCS = $(GENERIC_SRCS) $(TOMMATH_SRCS) $(UNIX_SRCS) $(NOTIFY_SRCS) \
 	$(OO_SRCS) $(STUB_SRCS) @PLAT_SRCS@ @ZLIB_SRCS@
 
+#--------------------------------------------------------------------------
+# Start of rules
+#--------------------------------------------------------------------------
+
 all: binaries libraries doc packages
 
 binaries: ${LIB_FILE} $(STUB_LIB_FILE) $(TCL_BUILD_EXP_FILE) tclsh
@@ -610,11 +614,44 @@ tclLibObjs:
 # This targets actually build the objects needed for the lib in the above case
 objs: ${OBJS}
 
-
 tclsh: ${TCLSH_OBJS} ${TCL_LIB_FILE}
 	${CC} ${CFLAGS} ${LDFLAGS} ${TCLSH_OBJS} @TCL_BUILD_LIB_SPEC@ ${TCL_STUB_LIB_FILE} ${LIBS} @EXTRA_TCLSH_LIBS@ \
 		${CC_SEARCH_FLAGS} -o tclsh
 
+Makefile: $(UNIX_DIR)/Makefile.in $(DLTEST_DIR)/Makefile.in
+	$(SHELL) config.status
+#tclConfig.h: $(UNIX_DIR)/tclConfig.h.in
+#	$(SHELL) config.status
+
+clean: clean-packages
+	rm -f *.a *.o libtcl* core errs *~ \#* TAGS *.E a.out \
+		errors tclsh tcltest lib.exp Tcl @DTRACE_HDR@
+	cd dltest ; $(MAKE) clean
+
+distclean: distclean-packages clean
+	rm -rf Makefile config.status config.cache config.log tclConfig.sh \
+		tclConfig.h *.plist Tcl.framework tcl.pc
+	cd dltest ; $(MAKE) distclean
+
+depend:
+	makedepend -- $(DEPEND_SWITCHES) -- $(SRCS)
+
+#--------------------------------------------------------------------------
+# The following target outputs the name of the top-level source directory for
+# Tcl (it is used by Tk's configure script, for example). The .NO_PARALLEL
+# line is needed to avoid problems under Sun's "pmake". Note: this target is
+# now obsolete (use the autoconf variable TCL_SRC_DIR from tclConfig.sh
+# instead).
+#--------------------------------------------------------------------------
+
+.NO_PARALLEL: topDirName
+topDirName:
+	@cd $(TOP_DIR); pwd
+
+#--------------------------------------------------------------------------
+# Rules for testing
+#--------------------------------------------------------------------------
+
 # Resetting the LIB_RUNTIME_DIR below is required so that the generated
 # tcltest executable gets the build directory burned into its ld search path.
 # This keeps tcltest from picking up an already installed version of the Tcl
@@ -659,6 +696,19 @@ runtest: tcltest
 ro-test: tcltest
 	echo 'exec chmod -w .;package require tcltest;tcltest::temporaryDirectory /tmp;source ../tests/all.tcl;exec chmod +w .' | $(SHELL_ENV) ./tcltest
 
+# The following target generates the shared libraries in dltest/ that are used
+# for testing; they are included as part of the "tcltest" target (via the
+# BUILD_DLTEST variable) if dynamic loading is supported on this platform. The
+# Makefile in the dltest subdirectory creates the dltest.marker file in this
+# directory after a successful build.
+
+dltest.marker: ${STUB_LIB_FILE}
+	cd dltest ; $(MAKE)
+
+#--------------------------------------------------------------------------
+# Rules for running a shell before installation
+#--------------------------------------------------------------------------
+
 # This target can be used to run tclsh from the build directory
 # via `make shell SCRIPT=/tmp/foo.tcl`
 shell: tclsh
@@ -680,55 +730,9 @@ valgrind: tclsh tcltest
 valgrindshell: tclsh
 	$(SHELL_ENV) valgrind $(VALGRINDARGS) ./tclsh $(SCRIPT)
 
-# The following target outputs the name of the top-level source directory for
-# Tcl (it is used by Tk's configure script, for example). The .NO_PARALLEL
-# line is needed to avoid problems under Sun's "pmake". Note: this target is
-# now obsolete (use the autoconf variable TCL_SRC_DIR from tclConfig.sh
-# instead).
-
-.NO_PARALLEL: topDirName
-topDirName:
-	@cd $(TOP_DIR); pwd
-
-# The following target generates the file generic/tclDate.c from the yacc
-# grammar found in generic/tclGetDate.y. This is only run by hand as yacc is
-# not available in all environments. The name of the .c file is different than
-# the name of the .y file so that make doesn't try to automatically regenerate
-# the .c file.
-
-gendate:
-	bison --output-file=$(GENERIC_DIR)/tclDate.c \
-	--no-lines \
-	--name-prefix=TclDate \
-	$(GENERIC_DIR)/tclGetDate.y
-
-#	yacc -l $(GENERIC_DIR)/tclGetDate.y
-#	sed -e 's/yy/TclDate/g' -e '/^#include <values.h>/d' \
-#	    -e 's?SCCSID?RCS: @(#) ?' \
-#	    -e '/#ifdef __STDC__/,/#endif/d' -e '/TclDateerrlab:/d' \
-#	    -e '/TclDatenewstate:/d' -e '/#pragma/d' \
-#	    -e '/#include <inttypes.h>/d' -e 's/const /CONST /g' \
-#           -e '/#define YYNEW/s/malloc/TclDateAlloc/g' \
-#	    -e '/#define YYENLARGE/,/realloc/s/realloc/TclDateRealloc/g' \
-#	    <y.tab.c >$(GENERIC_DIR)/tclDate.c
-#	rm y.tab.c
-
-# The following target generates the file generic/tclTomMath.h. It needs to be
-# run (and the results checked) after updating to a new release of libtommath.
-
-gentommath_h:
-	$(TCL_EXE) "$(TOOL_DIR)/fix_tommath_h.tcl" \
-		"$(TOMMATH_DIR)/tommath.h" \
-		> "$(GENERIC_DIR)/tclTomMath.h"
-
-# The following target generates the shared libraries in dltest/ that are used
-# for testing; they are included as part of the "tcltest" target (via the
-# BUILD_DLTEST variable) if dynamic loading is supported on this platform. The
-# Makefile in the dltest subdirectory creates the dltest.marker file in this
-# directory after a successful build.
-
-dltest.marker: ${STUB_LIB_FILE}
-	cd dltest ; $(MAKE)
+#--------------------------------------------------------------------------
+# Installation rules
+#--------------------------------------------------------------------------
 
 INSTALL_TARGETS = install-binaries install-libraries install-doc install-packages @EXTRA_INSTALL@
 
@@ -915,23 +919,9 @@ install-private-headers: libraries
 	    $(INSTALL_DATA) tclConfig.h "$(PRIVATE_INCLUDE_INSTALL_DIR)"; \
 	    fi;
 
-Makefile: $(UNIX_DIR)/Makefile.in $(DLTEST_DIR)/Makefile.in
-	$(SHELL) config.status
-#tclConfig.h: $(UNIX_DIR)/tclConfig.h.in
-#	$(SHELL) config.status
-
-clean: clean-packages
-	rm -f *.a *.o libtcl* core errs *~ \#* TAGS *.E a.out \
-		errors tclsh tcltest lib.exp Tcl @DTRACE_HDR@
-	cd dltest ; $(MAKE) clean
-
-distclean: distclean-packages clean
-	rm -rf Makefile config.status config.cache config.log tclConfig.sh \
-		tclConfig.h *.plist Tcl.framework tcl.pc
-	cd dltest ; $(MAKE) distclean
-
-depend:
-	makedepend -- $(DEPEND_SWITCHES) -- $(SRCS)
+#--------------------------------------------------------------------------
+# Rules for how to compile C files
+#--------------------------------------------------------------------------
 
 # Test binaries. The rules for tclTestInit.o and xtTestInit.o are complicated
 # because they are compiled from tclAppInit.c. Can't use the "-o" option
@@ -1524,9 +1514,11 @@ $(DTRACE_HDR): $(DTRACE_SRC)
 $(DTRACE_OBJ): $(DTRACE_SRC) $(TCL_OBJS)
 	$(DTRACE) -G $(DTRACE_SWITCHES) -o $@ -s $(DTRACE_SRC) $(TCL_OBJS)
 
+#--------------------------------------------------------------------------
 # The following targets are not completely general. They are provide purely
 # for documentation purposes so people who are interested in the Xt based
 # notifier can modify them to suit their own installation.
+#--------------------------------------------------------------------------
 
 xttest:  ${XTTEST_OBJS} ${GENERIC_OBJS} ${UNIX_OBJS} ${COMPAT_OBJS} ${TCL_STUB_LIB_FILE} \
 	@DL_OBJS@ ${BUILD_DLTEST}
@@ -1542,10 +1534,12 @@ tclXtTest.o: $(UNIX_DIR)/tclXtTest.c
 	$(CC) -c $(APP_CC_SWITCHES) -I/usr/openwin/include \
 		$(UNIX_DIR)/tclXtTest.c
 
+#--------------------------------------------------------------------------
 # Compat binaries, these must be compiled for use in a shared library even
 # though they may be placed in a static executable or library. Since they are
 # included in both the tcl library and the stub library, they need to be
 # relocatable.
+#--------------------------------------------------------------------------
 
 fixstrtod.o: $(COMPAT_DIR)/fixstrtod.c
 	$(CC) -c $(STUB_CC_SWITCHES) $(COMPAT_DIR)/fixstrtod.c
@@ -1603,8 +1597,10 @@ Zuncompr.o:  $(ZLIB_DIR)/uncompr.c
 Zzutil.o:    $(ZLIB_DIR)/zutil.c
 	$(CC) -c -o $@ $(CC_SWITCHES) -I$(ZLIB_DIR) $(ZLIB_DIR)/zutil.c
 
+#--------------------------------------------------------------------------
 # Stub library binaries, these must be compiled for use in a shared library
 # even though they will be placed in a static archive
+#--------------------------------------------------------------------------
 
 tclStubLib.o: $(GENERIC_DIR)/tclStubLib.c
 	$(CC) -c $(STUB_CC_SWITCHES) $(GENERIC_DIR)/tclStubLib.c
@@ -1615,9 +1611,9 @@ tclOOStubLib.o: $(GENERIC_DIR)/tclOOStubLib.c
 .c.o:
 	$(CC) -c $(CC_SWITCHES) $<
 
-#
+#--------------------------------------------------------------------------
 # Bundled Package targets
-#
+#--------------------------------------------------------------------------
 
 # propagate configure args like --enable-64bit to package configure
 PKG_CFG_ARGS		= @PKG_CFG_ARGS@
@@ -1717,6 +1713,41 @@ dist-packages: configure-packages
 	  fi; \
 	done
 
+#--------------------------------------------------------------------------
+# Maintainer-only targets
+#--------------------------------------------------------------------------
+
+# The following target generates the file generic/tclDate.c from the yacc
+# grammar found in generic/tclGetDate.y. This is only run by hand as yacc is
+# not available in all environments. The name of the .c file is different than
+# the name of the .y file so that make doesn't try to automatically regenerate
+# the .c file.
+
+gendate:
+	bison --output-file=$(GENERIC_DIR)/tclDate.c \
+	--no-lines \
+	--name-prefix=TclDate \
+	$(GENERIC_DIR)/tclGetDate.y
+
+#	yacc -l $(GENERIC_DIR)/tclGetDate.y
+#	sed -e 's/yy/TclDate/g' -e '/^#include <values.h>/d' \
+#	    -e 's?SCCSID?RCS: @(#) ?' \
+#	    -e '/#ifdef __STDC__/,/#endif/d' -e '/TclDateerrlab:/d' \
+#	    -e '/TclDatenewstate:/d' -e '/#pragma/d' \
+#	    -e '/#include <inttypes.h>/d' -e 's/const /CONST /g' \
+#           -e '/#define YYNEW/s/malloc/TclDateAlloc/g' \
+#	    -e '/#define YYENLARGE/,/realloc/s/realloc/TclDateRealloc/g' \
+#	    <y.tab.c >$(GENERIC_DIR)/tclDate.c
+#	rm y.tab.c
+
+# The following target generates the file generic/tclTomMath.h. It needs to be
+# run (and the results checked) after updating to a new release of libtommath.
+
+gentommath_h:
+	$(TCL_EXE) "$(TOOL_DIR)/fix_tommath_h.tcl" \
+		"$(TOMMATH_DIR)/tommath.h" \
+		> "$(GENERIC_DIR)/tclTomMath.h"
+
 #
 # Target to regenerate header files and stub files from the *.decls tables.
 #
@@ -1790,6 +1821,10 @@ checkexports: $(TCL_LIB_FILE)
 	| awk '$$2 ~ /^[TDBCS]$$/ { sub("^_", "", $$3); print $$3 }' \
 	| sort -n | grep -E -v '^[Tt]cl' || true
 
+#--------------------------------------------------------------------------
+# Distribution building rules
+#--------------------------------------------------------------------------
+
 #
 # Target to create a Tcl RPM for Linux. Requires that you be on a Linux
 # system.
@@ -1964,12 +1999,17 @@ allpatch: dist
 	mv $(DISTROOT)/tcl${VERSION} $(DISTROOT)/$(DISTNAME)
 	mv $(DISTROOT)/old $(DISTROOT)/tcl${VERSION}
 
-#
+#--------------------------------------------------------------------------
 # This target creates the HTML folder for Tcl & Tk and places it in
 # DISTDIR/html. It uses the tcltk-man2html.tcl tool from the Tcl group's tool
 # workspace. It depends on the Tcl & Tk being in directories called tcl8.* &
 # tk8.* up two directories from the TOOL_DIR.
 #
+# Note that for platforms where this is important, it is more common to use a
+# build of this HTML documentation that has already been placed online. As
+# such, this rule is not guaranteed to work well on all systems; it only needs
+# to function on those of the Tcl/Tk maintainers.
+#--------------------------------------------------------------------------
 
 html: tclsh
 	$(BUILD_HTML)
@@ -1987,4 +2027,19 @@ BUILD_HTML = \
 	./tclsh $(TOOL_DIR)/tcltk-man2html.tcl --htmldir="$(HTML_INSTALL_DIR)" \
 		--srcdir=$(TOP_DIR)/.. $(BUILD_HTML_FLAGS)
 
+#--------------------------------------------------------------------------
+# The list of all the targets that do not correspond to real files. This stops
+# 'make' from getting confused when someone makes an error in a rule.
+#--------------------------------------------------------------------------
+
+.PHONY: all binaries libraries doc packages tclLibObjs objs tcltest-real test
+.PHONY: test-tcl gdb-test runtest ro-test shell gdb ddd valgrind valgrindshell
+.PHONY: topDirName gendate gentommath_h install install-strip install-binaries
+.PHONY: install-libraries install-tzdata install-msgs install-doc clean dist
+.PHONY: install-private-headers distclean depend xttest configure-packages rpm
+.PHONY: packages install-packages test-packages clean-packages dist-packages
+.PHONY: distclean-packages genstubs checkstubs checkdoc checkuchar dist html
+.PHONY: checkexports alldist allpatch html-tcl html-tk
+
+#--------------------------------------------------------------------------
 # DO NOT DELETE THIS LINE -- make depend depends on it.