Re: [PATCH 1/4] Makefile: move "Platform specific tweaks" above LIB_{H,OBJS}

[Jonathan Nieder <jrnieder@gmail.com>]

Ævar Arnfjörð Bjarmason wrote:

> That listing should be in a comment at the start of the
> Makefile. Please submit a patch for that!

How about this?  An annoying piece of GNU makefile syntax makes this
uglier than it needs to be (search for HACK for details).

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
diff --git a/Makefile b/Makefile
index 1f1ce04..38edd65 100644
--- a/Makefile
+++ b/Makefile
@@ -1,6 +1,8 @@
 # The default target of this Makefile is...
 all::
 
+outline:: ; @echo "Configuration."
+
 # Define V=1 to have a more verbose compile.
 #
 # Define SHELL_PATH to a POSIX shell if your /bin/sh is broken.
@@ -238,6 +240,12 @@ all::
 #
 # Define NATIVE_CRLF if your platform uses CRLF for line endings.
 
+outline::
+	@echo " Basic configuration section."
+	@echo "  -include GIT-VERSION-FILE and recipe to generate it."
+	@echo "  uname_S and similar variables."
+	@echo "  user-facing compilation variables: CFLAGS, LDFLAGS, STRIP"
+
 GIT-VERSION-FILE: FORCE
 	@$(SHELL_PATH) ./GIT-VERSION-GEN
 -include GIT-VERSION-FILE
@@ -263,6 +271,7 @@ ALL_CFLAGS = $(CPPFLAGS) $(CFLAGS)
 ALL_LDFLAGS = $(LDFLAGS)
 STRIP ?= strip
 
+outline:: ; @echo "  User-facing paths: prefix, bindir_relative, etc."
 # Among the variables below, these:
 #   gitexecdir
 #   template_dir
@@ -301,6 +310,7 @@ pathsep = :
 
 export prefix bindir sharedir sysconfdir gitwebdir
 
+outline:: ; @echo "  Program names: CC, AR, etc."
 CC = gcc
 AR = ar
 RM = rm -f
@@ -325,6 +335,7 @@ SPARSE_FLAGS = -D__BIG_ENDIAN__ -D__powerpc__
 
 ### --- END CONFIGURATION SECTION ---
 
+outline:: ; @echo " Basic cflags and ldflags (almost configurable)"
 # Those must not be GNU-specific; they are shared with perl/ which may
 # be built by a different compiler. (Note that this is an artifact now
 # but it still might be nice to keep that distinction.)
@@ -353,6 +364,11 @@ TEST_PROGRAMS_NEED_X =
 # interactive shell sessions without exporting it.
 unexport CDPATH
 
+outline::
+	@echo " Main list of program targets:"
+	@echo "  SCRIPTS, PROGRAMS, TEST_PROGRAMS, BUILT_INS,"
+	@echo "  OTHER_PROGRAMS, BINDIR_PROGRAMS"
+
 SCRIPT_SH += git-am.sh
 SCRIPT_SH += git-bisect.sh
 SCRIPT_SH += git-difftool--helper.sh
@@ -465,6 +481,10 @@ BINDIR_PROGRAMS_NEED_X += git-shell
 
 BINDIR_PROGRAMS_NO_X += git-cvsserver
 
+outline:: ; @echo " Defaults for SHELL_PATH, PERL_PATH, PYTHON_PATH"
+# HACK: end of outline recipe
+reset =
+
 # Set paths to tools early so that they can be used for version tests.
 ifndef SHELL_PATH
 	SHELL_PATH = /bin/sh
@@ -479,6 +499,9 @@ endif
 export PERL_PATH
 export PYTHON_PATH
 
+outline::
+	@echo " Main list of library targets:"
+	@echo "  LIB_FILE, XDIFF_LIB, LIB_H, LIB_OBJS, BUILTIN_OBJS"
 LIB_FILE=libgit.a
 XDIFF_LIB=xdiff/lib.a
 VCSSVN_LIB=vcs-svn/lib.a
@@ -758,9 +781,12 @@ GITLIBS = $(LIB_FILE) $(XDIFF_LIB)
 EXTLIBS =
 
 #
-# Platform specific tweaks
+outline:: ; @echo " Platform specific tweaks"
 #
 
+# HACK: end of outline recipe
+reset =
+
 # We choose to avoid "if .. else if .. else .. endif endif"
 # because maintaining the nesting to match is a pain.  If
 # we had "elif" things would have been much nicer...
@@ -1147,9 +1173,14 @@ else
 endif
 endif
 
+outline:: ; @echo " -include config.mak and config.mak.autogen"
 -include config.mak.autogen
 -include config.mak
 
+#
+outline:: ; @echo "Preparations"
+#
+
 ifdef CHECK_HEADER_DEPENDENCIES
 COMPUTE_HEADER_DEPENDENCIES =
 USE_COMPUTED_HEADER_DEPENDENCIES =
@@ -1159,6 +1190,12 @@ ifdef COMPUTE_HEADER_DEPENDENCIES
 USE_COMPUTED_HEADER_DEPENDENCIES = YesPlease
 endif
 
+outline::
+	@echo " Handling of the various NO_THIS_OR_THAT options"
+	@echo "  This affects BASIC_CFLAGS, COMPAT_CFLAGS,"
+	@echo "  COMPAT_OBJS, PROGRAMS, EXTLIBS, LIB_OBJ, LIB_H, etc"
+reset =
+
 ifdef SANE_TOOL_PATH
 SANE_TOOL_PATH_SQ = $(subst ','\'',$(SANE_TOOL_PATH))
 BROKEN_PATH_FIX = 's|^\# @@BROKEN_PATH_FIX@@$$|git_broken_path_fix $(SANE_TOOL_PATH_SQ)|'
@@ -1491,6 +1528,7 @@ ifeq ($(PYTHON_PATH),)
 NO_PYTHON=NoThanks
 endif
 
+outline:: ; @echo " Machinery for non-noisy build"
 QUIET_SUBDIR0  = +$(MAKE) -C # space to separate -C and subdir
 QUIET_SUBDIR1  =
 
@@ -1522,7 +1560,8 @@ ifdef ASCIIDOC8
 	export ASCIIDOC8
 endif
 
-# Shell quote (do not use $(call) to accommodate ancient setups);
+outline:: ; @echo " Shell-quoted and C-quoted variables"
+# Do not use $(call) to accommodate ancient setups.
 
 SHA1_HEADER_SQ = $(subst ','\'',$(SHA1_HEADER))
 ETC_GITCONFIG_SQ = $(subst ','\'',$(ETC_GITCONFIG))
@@ -1545,12 +1584,6 @@ PYTHON_PATH_SQ = $(subst ','\'',$(PYTHON_PATH))
 TCLTK_PATH_SQ = $(subst ','\'',$(TCLTK_PATH))
 DIFF_SQ = $(subst ','\'',$(DIFF))
 
-LIBS = $(GITLIBS) $(EXTLIBS)
-
-BASIC_CFLAGS += -DSHA1_HEADER='$(SHA1_HEADER_SQ)' \
-	$(COMPAT_CFLAGS)
-LIB_OBJS += $(COMPAT_OBJS)
-
 # Quote for C
 
 ifdef DEFAULT_EDITOR
@@ -1567,16 +1600,25 @@ DEFAULT_PAGER_CQ_SQ = $(subst ','\'',$(DEFAULT_PAGER_CQ))
 BASIC_CFLAGS += -DDEFAULT_PAGER='$(DEFAULT_PAGER_CQ_SQ)'
 endif
 
+outline:: ; @echo " ALL_CFLAGS, ALL_LDFLAGS"
+LIBS = $(GITLIBS) $(EXTLIBS)
+
+BASIC_CFLAGS += -DSHA1_HEADER='$(SHA1_HEADER_SQ)' \
+	$(COMPAT_CFLAGS)
+LIB_OBJS += $(COMPAT_OBJS)
+
 ALL_CFLAGS += $(BASIC_CFLAGS)
 ALL_LDFLAGS += $(BASIC_LDFLAGS)
 
 export DIFF TAR INSTALL DESTDIR SHELL_PATH
 
-
-### Build rules
+#
+outline:: ; @echo "Main build rules"
+#
 
 SHELL = $(SHELL_PATH)
 
+outline:: ; @echo " all:: targets for the main build, subdirs"
 all:: shell_compatibility_test $(ALL_PROGRAMS) $(SCRIPT_LIB) $(BUILT_INS) $(OTHER_PROGRAMS) GIT-BUILD-OPTIONS
 ifneq (,$X)
 	$(QUIET_BUILT_IN)$(foreach p,$(patsubst %$X,%,$(filter %$X,$(ALL_PROGRAMS) $(BUILT_INS) git$X)), test -d '$p' -o '$p' -ef '$p$X' || $(RM) '$p';)
@@ -1598,11 +1640,13 @@ endif
 please_set_SHELL_PATH_to_a_more_modern_shell:
 	@$$(:)
 
+outline:: ; @echo " Shell sanity check"
 shell_compatibility_test: please_set_SHELL_PATH_to_a_more_modern_shell
 
 strip: $(PROGRAMS) git$X
 	$(STRIP) $(STRIP_OPTS) $(PROGRAMS) git$X
 
+outline:: ; @echo " Git binary and built-ins"
 git.o: common-cmds.h
 git.s git.o: EXTRA_CPPFLAGS = -DGIT_VERSION='"$(GIT_VERSION)"' \
 	'-DGIT_HTML_PATH="$(htmldir_SQ)"'
@@ -1628,6 +1672,7 @@ common-cmds.h: ./generate-cmdlist.sh command-list.txt
 common-cmds.h: $(wildcard Documentation/git-*.txt)
 	$(QUIET_GEN)./generate-cmdlist.sh > $@+ && mv $@+ $@
 
+outline:: ; @echo " Scripts and gitweb"
 define cmd_munge_script
 $(RM) $@ $@+ && \
 sed -e '1s|#!.*/sh|#!$(SHELL_PATH_SQ)|' \
@@ -1743,6 +1788,7 @@ $(patsubst %.py,%,$(SCRIPT_PYTHON)): % : unimplemented.sh
 	mv $@+ $@
 endif # NO_PYTHON
 
+outline:: ; @echo " Autoconf"
 configure: configure.ac
 	$(QUIET_GEN)$(RM) $@ $<+ && \
 	sed -e 's/@@GIT_VERSION@@/$(GIT_VERSION)/g' \
@@ -1756,6 +1802,10 @@ git.o git.spec \
 	$(patsubst %.perl,%,$(SCRIPT_PERL)) \
 	: GIT-VERSION-FILE
 
+outline::
+	@echo " Building objects"
+	@echo "  %.o: %.c rule, header deps, dependency checking"
+
 TEST_OBJS := $(patsubst test-%$X,test-%.o,$(TEST_PROGRAMS))
 GIT_OBJS := $(LIB_OBJS) $(BUILTIN_OBJS) $(PROGRAM_OBJS) $(TEST_OBJS) \
 	git.o
@@ -1895,6 +1945,7 @@ $(VCSSVN_OBJS): \
 	vcs-svn/svndump.h
 endif
 
+outline:: ; @echo "  Target-specific -D flags"
 exec_cmd.s exec_cmd.o: EXTRA_CPPFLAGS = \
 	'-DGIT_EXEC_PATH="$(gitexecdir_SQ)"' \
 	'-DBINDIR="$(bindir_relative_SQ)"' \
@@ -1922,6 +1973,7 @@ compat/nedmalloc/nedmalloc.o: EXTRA_CPPFLAGS = \
 	-DNDEBUG -DOVERRIDE_STRDUP -DREPLACE_SYSTEM_ALLOCATOR
 endif
 
+outline:: ; @echo " Non-builtin programs, remote-curl"
 git-%$X: %.o $(GITLIBS)
 	$(QUIET_LINK)$(CC) $(ALL_CFLAGS) -o $@ $(ALL_LDFLAGS) $(filter %.o,$^) $(LIBS)
 
@@ -1946,6 +1998,7 @@ $(REMOTE_CURL_PRIMARY): remote-curl.o http.o http-walker.o $(GITLIBS)
 	$(QUIET_LINK)$(CC) $(ALL_CFLAGS) -o $@ $(ALL_LDFLAGS) $(filter %.o,$^) \
 		$(LIBS) $(CURL_LIBCURL) $(EXPAT_LIBEXPAT)
 
+outline:: ; @echo " Libraries"
 $(LIB_FILE): $(LIB_OBJS)
 	$(QUIET_AR)$(RM) $@ && $(AR) rcs $@ $(LIB_OBJS)
 
@@ -1955,6 +2008,7 @@ $(XDIFF_LIB): $(XDIFF_OBJS)
 $(VCSSVN_LIB): $(VCSSVN_OBJS)
 	$(QUIET_AR)$(RM) $@ && $(AR) rcs $@ $(VCSSVN_OBJS)
 
+outline:: ; @echo " Subdirs"
 doc:
 	$(MAKE) -C Documentation all
 
@@ -1982,6 +2036,10 @@ cscope:
 	$(RM) cscope*
 	$(FIND) . -name '*.[hcS]' -print | xargs cscope -b
 
+#
+outline:: ; @echo "GIT-CFLAGS, GIT-BUILD-OPTIONS, GIT-GUI-VARS"
+#
+
 ### Detect prefix changes
 TRACK_CFLAGS = $(CC):$(subst ','\'',$(ALL_CFLAGS)):\
              $(bindir_SQ):$(gitexecdir_SQ):$(template_dir_SQ):$(prefix_SQ)
@@ -2024,6 +2082,9 @@ GIT-GUI-VARS: FORCE
             fi
 endif
 
+#
+outline:: ; @echo "Wrappers for running built git in place"
+#
 test_bindir_programs := $(patsubst %,bin-wrappers/%,$(BINDIR_PROGRAMS_NEED_X) $(BINDIR_PROGRAMS_NO_X) $(TEST_PROGRAMS_NEED_X))
 
 all:: $(TEST_PROGRAMS) $(test_bindir_programs)
@@ -2041,8 +2102,9 @@ bin-wrappers/%: wrap-for-bin.sh
 
 export NO_SVN_TESTS
 
-### Testing rules
-
+#
+outline:: ; @echo "Testing rules"
+#
 test: all
 	$(MAKE) -C t/ all
 
@@ -2083,7 +2145,9 @@ check: common-cmds.h
 remove-dashes:
 	./fixup-builtins $(BUILT_INS) $(PROGRAMS) $(SCRIPTS)
 
-### Installation rules
+#
+outline:: ; @echo "Installation rules"
+#
 
 ifneq ($(filter /%,$(firstword $(template_dir))),)
 template_instdir = $(template_dir)
@@ -2183,8 +2247,9 @@ quick-install-html:
 	$(MAKE) -C Documentation quick-install-html
 
 
-
-### Maintainer's dist rules
+#
+outline:: ; @echo "Maintainer's dist rules, check-doc, coverage testing"
+#
 
 git.spec: git.spec.in
 	sed -e 's/@@VERSION@@/$(GIT_VERSION)/g' < $< > $@+