Makefile: document ground rules for target-specific dependencies
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> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jonathan Nieder committed
Jul 6, 2012 at 23:19 UTC
7b63c77eeea7cc4bf3d29793bcb95dcf659e5126
1 file changed
+33
Makefile
+33
@@ -1973,6 +1973,39 @@ shell_compatibility_test: please_set_SHELL_PATH_to_a_more_modern_shell
1973
strip: $(PROGRAMS) git$X
1974
$(STRIP) $(STRIP_OPTS) $(PROGRAMS) git$X
1975
1976
+### Target-specific flags and dependencies
1977
+
1978
+# The generic compilation pattern rule and automatically
1979
+# computed header dependencies (falling back to a dependency on
1980
+# LIB_H) are enough to describe how most targets should be built,
1981
+# but some targets are special enough to need something a little
1982
+# different.
1983
+#
1984
+# - When a source file "foo.c" #includes a generated header file,
1985
+# we need to list that dependency for the "foo.o" target.
1986
+#
1987
+# We also list it from other targets that are built from foo.c
1988
+# like "foo.sp" and "foo.s", even though that is easy to forget
1989
+# to do because the generated header is already present around
1990
+# after a regular build attempt.
1991
+#
1992
+# - Some code depends on configuration kept in makefile
1993
+# variables. The target-specific variable EXTRA_CPPFLAGS can
1994
+# be used to convey that information to the C preprocessor
1995
+# using -D options.
1996
+#
1997
+# The "foo.o" target should have a corresponding dependency on
1998
+# a file that changes when the value of the makefile variable
1999
+# changes. For example, targets making use of the
2000
+# $(GIT_VERSION) variable depend on GIT-VERSION-FILE.
2001
+#
2002
+# Technically the ".sp" and ".s" targets do not need this
2003
+# dependency because they are force-built, but they get the
2004
+# same dependency for consistency. This way, you do not have to
2005
+# know how each target is implemented. And it means the
2006
+# dependencies here will not need to change if the force-build
2007
+# details change some day.
2008
+
2009
git.sp git.s git.o: GIT-PREFIX
2010
git.sp git.s git.o: EXTRA_CPPFLAGS = \
2011
'-DGIT_HTML_PATH="$(htmldir_SQ)"' \