Makefile Debugging: Tracing Macro Values

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)

When run it prints

dog dog
cat cat
dogs hate cats

Tracing Macro Use

Now try to trace through and see wherethe macro $(Y) is used. It's actually used on lines 8, 9, 11, and 12 (twice). It's amazing how often macros get used! That's because Make defaults to only getting the value of a macro when needed and macros are frequently deeply nested.

Tracing such use for any real Makefile would be an impossible task, but it's possible to get Make to do the work for you. Take a look at the code which should be added to the start of the Makefile to be traced (it'll only get used when explicitly called).

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

Before diving into understanding how it works, here's an example of using it to trace the value of $(Y) in our example Makefile. To use the tracer you tell GNU Make to run the trace target by setting the TRACE macro to the name of the macro you wanted tracked. In this example we want to watch use of the macro Y:

% 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

From the lines containing the word TRACE you can see Y being used first on line 8 (the definition of the all target references Y via the $(YS)), then on line 11(the definition of the cats target is using $(YS) which uses Y), then twice on line 12 (the two references to $(Y) itself as we execute the rule) and finally on line 9 ($(X) references $(YS) which references $(Y)).

With the power of the tracer we can try another task: finding out where $(S) is used:

% 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

How the Macro Tracer Works

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