CHAPTER 12 Debugging Makefiles - O'Reilly Media

1 This is the Title of the Book, eMatter EditionCopyright 2005 O Reilly & Associates, Inc. All rights 12 CHAPTER 12 Debugging MakefilesDebuggingmakefiles is somewhat of a black art. Unfortunately, there is no suchthing as amakefiledebugger to examine how a particular rule is being evaluated or avariable expanded. Instead, most Debugging is performed with simple print state-ments and by inspection of themakefile. GNUmakeprovides some help with variousbuilt-in functions and command-line of the best ways to debug amakefileis to add Debugging hooks and use defen-sive programming techniques that you can fall back on when things go awry. I llpresent a few basic Debugging techniques and defensive coding practices I ve foundmost Features of makeThewarningfunction is very useful for Debugging waywardmakefiles. Because thewarningfunction expands to the empty string, it can be placed anywhere in amakefile: at the top-level, in target or prerequisite lists, and in command scripts.

2 Thisallows you to print the value of variables wherever it is most convenient to inspectthem. For example:$(warning A top-level warning)FOO := $(warning Right-hand side of a simple variable)barBAZ = $(warning Right-hand side of a recursive variable)boo$(warning A target)target: $(warning In a prerequisite list)makefile $(BAZ) $(warning In a command script) ls$(BAZ):yields the output:$ makemakefile:1: A top-level warningmakefile:2: Right-hand side of a simple variablemakefile:5: A target, Page 229 Friday, March 25, 2005 2:55 PMThis is the Title of the Book, eMatter EditionCopyright 2005 O Reilly & Associates, Inc. All rights | CHAPTER 12: Debugging Makefilesmakefile:5: In a prerequisite listmakefile:5: Right-hand side of a recursive variablemakefile:8: Right-hand side of a recursive variablemakefile:6: In a command scriptlsmakefileNotice that the evaluation of thewarningfunction follows the normalmakealgorithmfor immediate and deferred evaluation.

3 Although the assignment toBAZcontains awarning, the message does not print untilBAZ is evaluated in the prerequisites ability to inject awarning call anywhere makes it an essential Debugging OptionsThere are three command-line options I find most useful for Debugging :--just-print (-n),--print-data-base (-p), first test I perform on a newmakefiletarget is to invokemakewith the--just-print(-n) option. This causesmaketo read themakefileand print every command itwould normally execute to update the target but without executing them. As a con-venience, GNUmake will also echo commands marked with the silent modifier option is supposed to suppress all command execution. While this may be truein one sense, practically speaking, you must take care. Whilemakewill not executecommand scripts, it will evaluateshellfunction calls that occur within an immedi-ate context. For instance:REQUIRED_DIRS =.

4 _MKDIRS := $(shell for d in $(REQUIRED_DIRS); \ do \ [[ -d $$d ]] || mkdir -p $$d; \ done)$(objects) : $(sources)As we ve seen before, the purpose of the_MKDIRS simple variable is to trigger the cre-ation of essential directories. When this is executed with--just-print, the shellcommand will be executed as usual when themakefileis read. Thenmakewill echo(without executing) each compilation command required to update the$(objects)file (-p) option is another one you ll use often. It executes themakefile, displaying the GNU copyright followed by the commands as they are runbymake, then it will dump its internal database. The data is collected into groups of, Page 230 Friday, March 25, 2005 2:55 PMThis is the Title of the Book, eMatter EditionCopyright 2005 O Reilly & Associates, Inc. All rights Features of make|231values: variables, directories, implicit rules, pattern-specific variables, files (explicitrules), and the vpath search path:# GNU Make # Copyright (C) 2002 Free Software Foundation, Inc.

5 # This is free software; see the source for copying conditions.# There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A# PARTICULAR command execution occurs here# Make data base, printed on Thu Apr 29 20:58:13 2004# # # Implicit # Pattern-specific variable # # VPATH Search PathsLet s examine these sections in more variables section lists each variable along with a descriptive comment:# automatic<D = $(patsubst %/,%,$(dir $<))# environmentEMACS_DIR = C:/ # defaultCWEAVE = cweave# makefile (from `../mp3_player/makefile', line 35)CPPFLAGS = $(addprefix -I ,$(include_dirs))# makefile (from `../ch07-separate-binaries/makefile', line 44)RM := rm -f# makefile (from `../mp3_player/makefile', line 14)define make-library libraries += $1 sources += $2 $1: $(call source-to-object,$2) $(AR) $(ARFLAGS) $$@ $$^endefAutomatic variables are not printed, but convenience variables derived from themlike$(<D)are.

6 The comment indicates the type of the variable as returned by theoriginfunction (see the section Less Important Miscellaneous Functions inChapter 4). If the variable is defined in a file, the filename and line number of thedefinition is given. Simple and recursive variables are distinguished by the, Page 231 Friday, March 25, 2005 2:55 PMThis is the Title of the Book, eMatter EditionCopyright 2005 O Reilly & Associates, Inc. All rights | CHAPTER 12: Debugging Makefilesassignment operator. The value of a simple variable will be displayed as the evalu-ated form of the righthand next section, labeled Directories, is more useful tomakedevelopers than tomakeusers. It lists the directories being examined bymake, including SCCS and RCS subdi-rectories that might exist, but usually do not. For each directory,makedisplays imple-mentation details, such as the device number, inode, and statistics on file Implicit Rules section follows.

7 This contains all the built-in and user-definedpattern rules inmake s database. Again, for those rules defined in a file, a commentindicates the file and line number:%.c %.h: %.y# commands to execute (from `../mp3_player/makefile', line 73): $( ) --defines $< $(MV) $*.c $(MV) $*.h%: %.c# commands to execute (built-in): $( ) $^ $(LOADLIBES) $(LDLIBS) -o %.c# commands to execute (built-in): $( ) $(OUTPUT_OPTION) $<Examining this section is a great way to become familiar with the variety and struc-ture ofmake s built-in rules. Of course, not all built-in rules are implemented as pat-tern rules. If you don t find the rule you re looking for, check in the Files sectionwhere the old-style suffix rules are next section catalogs the pattern-specific variables defined in themakefile. Recallthat pattern-specific variables are variable definitions whose scope is precisely theexecution time of their associated pattern rule.

8 For example, the pattern variableYYLEXFLAG, defined as:%.c %.h: YYLEXFLAG := -d%.c %.h: %.y $( ) --defines $< $(MV) $*.c $(MV) $*.hwould be displayed as:# Pattern-specific variable values%.c :# makefile (from `Makefile', line 1)# YYLEXFLAG := -d# variable set hash-table stats:# Load=1/16=6%, Rehash=0, Collisions=0/1=0%, Page 232 Friday, March 25, 2005 2:55 PMThis is the Title of the Book, eMatter EditionCopyright 2005 O Reilly & Associates, Inc. All rights Features of make|233%.h :# makefile (from `Makefile', line 1)# YYLEXFLAG := -d# variable set hash-table stats:# Load=1/16=6%, Rehash=0, Collisions=0/1=0%# 2 pattern-specific variable valuesThe Files section follows and lists all the explicit and suffix rules that relate tospecific files:# Not a target:. :# Implicit rule search has not been done.# Modification time never checked.# File has not been updated.

9 # commands to execute (built-in): $( ) $(OUTPUT_OPTION) $<lib/ : lib/ # Implicit rule search has not been done.# Last modified 2004-04-01 22:04 # File has been updated.# Successfully updated.# commands to execute (from `../mp3_player/lib/ ', line 3): ar rv $@ $^lib/ : ../mp3_player/lib/ ../mp3_player/lib/ ../mp3_player/include/ # Implicit rule search has been done.# Implicit/static pattern stem: `lib/codec/codec'# Last modified 2004-04-01 22:04 # File has been updated.# Successfully updated.# commands to execute (built-in): $( ) $(OUTPUT_OPTION) $<Intermediate files and suffix rules are labeled Not a target ; the remainder are tar-gets. Each file includes comments indicating howmakehas processed the rule. Filesthat are found through the normalvpath search have their resolved path last section is labeled VPATH Search Paths and lists the value ofVPATHand allthevpath that make extensive use of user-defined functions andevalto createcomplex variables and rules, examining this output is often the only way to verifythat macro expansion has generated the expected option causesmaketo display a warning whenever an undefined variable isexpanded.

10 Since undefined variables expand to the empty string, it is common fortypographical errors in variable names to go undetected for long periods. The problem, Page 233 Friday, March 25, 2005 2:55 PMThis is the Title of the Book, eMatter EditionCopyright 2005 O Reilly & Associates, Inc. All rights | CHAPTER 12: Debugging Makefileswith this option, and why I use it only rarely, is that many built-in rules include unde-fined variables as hooks for user-defined values. So runningmakewith this option willinevitably produce many warnings that are not errors and have no useful relationshipto the user smakefile. For example:$make --warn-undefined-variables -nmakefile:35: warning: undefined variable MAKECMDGOALS makefile:45: warning: undefined variable CFLAGS makefile:45: warning: undefined variable :35: warning: undefined variable MAKECMDGOALS make: warning: undefined variable CFLAGS make: warning: undefined variable TARGET_ARCH make: warning: undefined variable CFLAGS make: warning: undefined variable : warning: undefined variable LDFLAGS make: warning: undefined variable TARGET_ARCH make: warning: undefined variable LOADLIBES make: warning: undefined variable LDLIBSN evertheless, this command can be extremely valuable on occasion in catching thesekinds of -- debug OptionWhen you need to know howmakeanalyzes your dependency graph, use the--debugoption.