[PATCH/RFC] Makefile: document ground rules for target-specific dependencies

[Jonathan Nieder <jrnieder@gmail.com>]

When a source file makes use of a makefile variable, there should be a
corresponding dependency on a file that changes when that variable
changes to ensure the build output is not left stale when the variable
changes.

Document this, even though we are not following the rule perfectly
yet.  Based on an explanation from Jeff King.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
Jeff King wrote:
> On Wed, Jun 20, 2012 at 04:12:25PM -0500, Jonathan Nieder wrote:

>> Wouldn't it be simpler to put the ground rules in a comment or a
>> document somewhere under Documentation/ where they can be easily
>> found?
>
> I think a comment in the Makefile might make sense (especially if it
> introduces the section as "and this is the place to put weird
> target-specific cppflags and dependencies").

How about something like this?

 Makefile |   34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/Makefile b/Makefile
index 3f82b51b..542856f0 100644
--- a/Makefile
+++ b/Makefile
@@ -1970,6 +1970,40 @@ shell_compatibility_test: please_set_SHELL_PATH_to_a_more_modern_shell
 strip: $(PROGRAMS) git$X
 	$(STRIP) $(STRIP_OPTS) $(PROGRAMS) git$X
 
+
+### Target-specific flags and dependencies
+
+# The generic compilation pattern rule and automatically
+# computed header dependencies (falling back to a dependency on
+# LIB_H) are enough to describe how most targets should be built,
+# but some targets are special enough to need something a little
+# different.
+#
+# - When a source file "foo.c" #includes a generated header file,
+#   we need to list that dependency for the "foo.o" target.
+#
+#   We also list it from other targets that are built from foo.c
+#   like "foo.sp" and "foo.s", even though that is easy to forget
+#   to do because the generated header is already present around
+#   after a regular build attempt.
+#
+# - Some code depends on configuration kept in makefile
+#   variables. The target-specific variable EXTRA_CPPFLAGS can
+#   be used to convey that information to the C preprocessor
+#   using -D options.
+#
+#   The "foo.o" target should have a corresponding dependency on
+#   a file that changes when the value of the makefile variable
+#   changes.  For example, targets making use of the
+#   $(GIT_VERSION) variable depend on GIT-VERSION-FILE.
+#
+#   Technically the ".sp" and ".s" targets do not need this
+#   dependency because they are force-built, but they get the
+#   same dependency for consistency. This way, you do not have to
+#   know how each target is implemented. And it means the
+#   dependencies here will not need to change if the force-build
+#   details change some day.
+
 git.sp git.s git.o: EXTRA_CPPFLAGS = \
 	'-DGIT_HTML_PATH="$(htmldir_SQ)"' \
 	'-DGIT_MAN_PATH="$(mandir_SQ)"' \
-- 
1.7.10.4