Consider this simple Makefile:

X=$(YS) hate $(ZS)
Y=dog
YS=$(Y)$(S)
Z=cat
ZS=$(Z)$(S)
S=s
all: $(YS) $(ZS)
@echo $(X)
$(YS):
@echo $(Y) $(Y)
$(ZS):
@echo $(Z) $(Z)

dog dog
cat cat
dogs hate cats

ifdef TRACE
.PHONY: _trace _value
_trace: ; @$(MAKE) --no-print-directory TRACE= $(TRACE) ='$$(warning TRACE $(TRACE))$(shell $(MAKE) TRACE=$(TRACE) _value)'
_value: ; @echo '$(value $(TRACE))'
endif

% gmake TRACE=Y

Makefile:8: TRACE Y
Makefile:11: TRACE Y
Makefile:12: TRACE Y
Makefile:12: TRACE Y
dog dog
cat cat
Makefile:9: TRACE Y
dogs hate cats

% gmake TRACE=S

Makefile:8: TRACE S
Makefile:8: TRACE S
Makefile:11: TRACE S
Makefile:14: TRACE S
dog dog
cat cat
Makefile:9: TRACE S
Makefile:9: TRACE S
dogs hate cats

GNU Make has a special function called $(warning) that outputs a warning message to STDERR and returns the empty string. Conceptually the tracer changes the value of the macro to be traced to include a $(warning) message. Every time the macro is expanded the warning is printed; when a warning message is output GNU Make prints the name of the Makefile in use and the line number.

For example, if we changed the definition of Y from

Y=dog

to

Y=$(warning TRACE Y)dog

then whenever Y were expanded we would see a warning and Y would have the resulting value dog.

The trace code automates this process: it first obtains the unexpanded value of the macro to be traced, prepends it with an appropriate warning and then runs the desired Make with the specially modified value of the macro being examined. To do this it uses a Make function introduced in GNU Make 3.80 that enables you to get the unexpanded value of a macro: $(value).

In our example Makefile the macro YS is defined to be $(Y)$(S). If we ask for its value in a Makefile using the form $(YS) we get dogs, if we do $(value YS) then we'll get $(Y)$(S). $(value) returns the literal string used to define YS.

Now let's break down the tracer to understand what it does. If TRACE is defined then the block of definitions associated with the tracer is used and the first rule that the Makefile contains is the rule for _trace. Since _trace is the first target encountered, when TRACE is defined its rule will be run by default.

The _trace rule contains a single, complex command:

@$(MAKE) --no-print-directory TRACE= $(TRACE)='$$(warning TRACE $(TRACE))$(shell $(MAKE) TRACE=$(TRACE) _value)'

On the right-hand side of the command is a $(shell) invocation rerunning the Makefile with a different goal. If we are tracing YS then this $(shell) runs the command

make TRACE=YS _value

which will cause the _value rule to get run, which in turn will echo the definition of YS. _value simply echoes the definition of the macro specified by the TRACE macro. So the $(shell) ends up evaluating to $(Y)$(S).

The $(shell) is in fact inside a command-line macro definition (usually called a command-line override):

$(TRACE)='$$(warning TRACE $(TRACE))$(shell $(MAKE)TRACE=$(TRACE) _value)'

which adds the $(warning) needed to output the 'TRACE X' messages. Notice how the name of the macro being defined is a computed value: its name is contained in $(TRACE). When tracing YS this definition turns into:

YS='$(warning TRACE YS)$(Y)$(S)'

The single quotes are used to prevent the shell from seeing the $ sign, the double $ is used to prevent Make from seeing the $: in either case a macro expansion would be prevented which we want to delay until YS is actually used.

Finally the _trace rule runs

make TRACE= YS='$(warning TRACE YS)$(Y)$(S)'

which resets the value of TRACE (since this invocation of Make should actually run the real rules) and overrides the value of YS as defined in the Makefile. Recall that macros defined on the command-line override definitions in the Makefile (see article URL): even though YS is defined in the Makefile the command-line definition will be used.

Now every time $(YS) is expanded a warning is printed.

Notes
This technique doesn't work for a macro that is target-specific. GNU Make allows you to define a macro as specific to a target in the following manner:

all: FOO=foo
all: a
@echo $(FOO)

a:
@echo $(FOO)

The macro FOO will have value foo in the rule that builds all and in any prerequisites of all. The Makefile above will print foo and then foo because $(FOO) is defined in the all rule and in the a rule. The tracer is unable to obtain the value of $(FOO) and would in fact cause this Makefile to behave incorrectly.

$(warning) sends its output to STDERR which makes it possible to separate normal Make output from the tracer. Simply redirect STDERR to a trace log file. For example the following command will result in normal Make output being seen and the trace going to the log file:

% gmake TRACE=S 2> trace.log

dog dog
cat cat
dogs hate cats

Conclusion

Next month I'll return with a GNU Make trick that let's you see exactly which rules are run when you type 'make' and in what order.

Trackback(0)

TrackBack URI for this entry

Comments (1)

Subscribe to this comment's feed

ZZTech said:

	... Good article, thank you! For those that like to cut and paste - you need to remove the space after $(TRACE) (so "$(TRACE) =" becomes "$(TRACE)=" - in order to avoid this error make: *** empty variable name. Stop. make: *** [_trace] Error 2 (using gmake 3.80) Also, (small point) as soon as you include the TRACE code, you change the line numbers in the example.
	report abuse vote down vote up

July 21, 2007
Votes: +0

Write comment