Makefile Debugging and Optimization

Overview

Teach systematic debugging first using Make's built-in diagnostic flags. When users report issues (slow builds, incorrect behavior, mysterious rebuilds), start with debugging methodology, not immediate solutions. Make's debugging flags reveal the root cause - use them proactively.

Core Anti-Pattern to Avoid

❌ Jump to Solutions Without Diagnosis

User: "My build is slow"
Agent: "Here are 8 optimizations to try:
  1. Use ccache
  2. Enable parallel builds
  3. Optimize compiler flags
  ..."

Problems:

• Guessing: No diagnosis of actual problem
• Shotgun approach: Try many things, hope one works
• Misses root cause: May not address actual issue
• Not educational: User doesn't learn debugging approach
• Wastes time: Implementing irrelevant fixes

Even if suggestions are good, this misses teaching opportunity.

Correct Pattern: Systematic Debugging

✅ Debug First, Then Fix

User: "My build is slow"
Agent: "Let's debug systematically to find the root cause.

First, let's see what Make is actually doing:

1. Dry-run to see planned actions:
   make -n all

2. Check what's being rebuilt and why:
   make -d all 2>&1 | grep 'File.*is newer'

3. Time different scenarios:
   make clean && time make all    # Full build
   touch file.c && time make all  # Incremental

This will show us exactly what's slow. Then we can fix the specific issue.

[After seeing output:]
The debug output shows Make is rebuilding everything because...
Here's the specific fix..."

Benefits:

• Accurate diagnosis: See actual problem
• Educational: User learns debugging approach
• Targeted fix: Address root cause
• Reproducible: User can debug future issues
• Professional: This is how experts debug

Make's Essential Debugging Flags

Always Suggest These First

make -n (Dry-Run)

Purpose: Show what would be executed without running commands

make -n all

# See what would run for specific target
make -n install

# Check if Make thinks rebuild is needed
make all && make -n all  # Should show "nothing to be done"

When to use:

• "What will this Makefile do?"
• "Why is Make rebuilding?"
• Verify Makefile logic before running

make -d (Debug Mode)

Purpose: Show Make's decision-making process

make -d all 2>&1 | less

# Filter for specific insights
make -d all 2>&1 | grep "Considering\|File.*is newer"

# See why target rebuilt
make -d mytarget 2>&1 | grep mytarget

When to use:

• "Why did Make rebuild this?"
• "How is Make resolving dependencies?"
• "Why is Make not rebuilding when it should?"

make -p (Print Database)

Purpose: Show all rules, variables, and values

make -p | less

# See specific variable value
make -p | grep "^CC ="

# See all pattern rules
make -p | grep "^%"

# See automatic variables
make -p | grep "automatic"

When to use:

• "What's the value of this variable?"
• "What implicit rules exist?"
• "Why is this variable not what I expect?"

make --trace (GNU Make 4.0+)

Purpose: Show rule executions in real-time

make --trace all

# See what triggered rebuild
touch file.c
make --trace all

When to use:

• "What's the execution order?"
• "What triggered this rebuild?"
• More readable than -d for basic tracing

Quick Reference Card

Flag	Purpose	Common Use
-n	Dry-run (what would run)	"Will this work?"
-d	Debug (why decisions made)	"Why rebuilt?"
-p	Database (all rules/vars)	"What's the value?"
--trace	Trace execution	"What ran and why?"

Always mention these when user has Makefile problems.

Systematic Debugging Approach

Step 1: Understand What's Happening

# What commands would run?
make -n target

# Is Make seeing what you expect?
make -p | grep VARIABLE_NAME

# What's the current state?
make --question target; echo $?  # 0=up-to-date, 1=outdated, 2=error

Step 2: Identify the Problem

# For "it's slow" issues:
time make clean && time make all  # Baseline
touch one_file.c && time make all # Incremental
# Should be fast! If not, debug why

# For "it rebuilds everything" issues:
make all
make -n all  # Should say "nothing to be done"
# If not, something's wrong with dependencies

# For "it doesn't rebuild" issues:
touch dependency.h
make -d target 2>&1 | grep dependency.h
# Should show it considers the file

Step 3: Find Root Cause

# Why is this file being rebuilt?
make -d target.o 2>&1 | grep -A5 "target.o"

# What triggered this?
make --trace all

# What does Make think this variable is?
make -p | grep "^VARNAME\s*="

Step 4: Implement Targeted Fix

Now suggest specific solutions based on diagnosis, not guesses.

Common Issues and How to Debug Them

Issue: "Build is Slow"

Start by measuring: time make clean && time make all for baseline, touch src/main.c && time make all for incremental. Identify whether compilation or linking is slow before suggesting optimizations.

Issue: "Everything Rebuilds"

Verify with make all && make -n all (should say "nothing to be done"). If it wants to rebuild, use make -d all 2>&1 | grep 'File.*is newer' to find the timestamp causing it.

Issue: "Target Doesn't Rebuild When It Should"

Check known dependencies with make -p | grep -A10 "^target:". Then touch dependency.h && make -d target 2>&1 | grep dependency.h to verify Make sees the file change.

When to Suggest Optimizations

After Understanding the Problem

Timing showed slow compilation: → Suggest ccache, -j flag, optimize flags

Timing showed slow linking: → Suggest split debug info, reduce -O level for dev

Debug showed all files rebuild: → Fix timestamp issue, check .d file generation

Debug showed no parallelism: → Suggest .NOTPARALLEL removal, add -j flag

Debug showed expensive wildcard: → Cache results, use immediate expansion :=

Proactive Debugging Education

When User Reports Issue

Template response structure:

1. Acknowledge issue
2. Suggest debugging approach (flags to use)
3. Wait for or request output
4. Analyze output
5. Provide targeted fix

Example:

"That rebuild behavior sounds incorrect. Let's debug it systematically:

# First, let's see what Make is actually doing:
make all
make -n all  # Should say 'nothing to be done'

# If it wants to rebuild, let's see why:
make -d all 2>&1 | grep 'File.*is newer'

Can you run these and share the output? That will show us exactly what's causing unnecessary rebuilds.

[After seeing output:] Ah, I see the issue. Make thinks config.h is newer than the targets because... Here's how to fix it..."

When Creating Makefiles

Proactively include debugging support:

# Debug and optimization targets
.PHONY: debug-make help-debug

debug-make:
	@echo "==> Dry-run (what would be executed):"
	@$(MAKE) -n all
	@echo ""
	@echo "==> Variable values:"
	@$(MAKE) -p | grep "^CC\|^CFLAGS\|^LDFLAGS"

help-debug:
	@echo "Debugging targets:"
	@echo "  make -n target     - Show what would run"
	@echo "  make -d target     - Show decision-making"
	@echo "  make -p | grep VAR - Show variable value"
	@echo "  make --trace       - Trace execution"

Mention in help target:

help: ## Show this help
	@echo "Debugging:"
	@echo "  make -n all        - Dry-run to see planned commands"
	@echo "  make -d all        - Debug why Make is rebuilding"
	@echo "  make debug-make    - Show Makefile diagnostics"

Common Debugging Scenarios

Step-by-step debugging procedures for mysterious rebuilds, targets that never rebuild, wrong variable values, and slow incremental builds are in references/debugging-scenarios.md.

Optimization Principles

Measure Before Optimizing

# Don't guess - measure
time make clean && time make all

# Measure incremental
touch src/main.c
time make all

# Profile with timestamps
make all
stat target dependencies

Common Optimizations (After Diagnosis)

1. Parallel Builds (if compilation is slow)

MAKEFLAGS += -j$(shell nproc)

2. Compiler Cache (if recompiling same files)

CC := ccache gcc

3. Optimize Dev Flags (if dev build is slow)

# Development
CFLAGS := -g -Og  # Not -O0

# Conditional sanitizers
ifdef SANITIZE
  CFLAGS += -fsanitize=address
endif

4. Lazy Wildcard (if startup is slow)

# Faster: immediate expansion
SRCS := $(wildcard src/*.c)

# Not: recursive expansion
SRCS = $(wildcard src/*.c)  # Re-evaluates every time

5. Conditional Dependency Inclusion

# Don't parse .d files for clean
ifneq ($(MAKECMDGOALS),clean)
  -include $(DEPS)
endif

The Bottom Line

Don't guess - debug. Make has powerful diagnostic flags that reveal exactly what's happening. Use them first:

1. Problem reported → Suggest debugging flags
2. Run flags, see output → Understand root cause
3. Root cause identified → Provide targeted fix
4. User learns → Can debug future issues themselves

Teaching debugging methodology is more valuable than providing quick fixes. Users who learn make -n, make -d, and make -p can solve their own problems.

Always frame debugging as first step, not afterthought.

Quick Diagnostic Commands

See references/debugging-scenarios.md for a copy-paste-ready cheat sheet of diagnostic commands.