makefile-validator

name	makefile-validator
description	Comprehensive toolkit for validating, linting, and optimizing Makefiles. Use this skill when working with Makefiles (Makefile, makefile, *.mk files), validating build configurations, checking for best practices, identifying security issues, or debugging Makefile problems.

Makefile Validator

Overview

This skill provides comprehensive validation for Makefiles, checking for syntax errors, formatting consistency, best practices, security vulnerabilities, and optimization opportunities. It uses the mbake tool (Makefile formatter and linter) along with custom validation checks to ensure high-quality build configurations.

When to Use This Skill

Use this skill when:

• Validating Makefiles (Makefile, makefile, *.mk files)
• Checking build configuration for syntax errors
• Ensuring consistent Makefile formatting
• Identifying security vulnerabilities in build recipes
• Finding optimization opportunities for build performance
• Debugging Makefile issues
• Enforcing .PHONY target declarations
• Verifying tab indentation in recipes
• Learning Makefile best practices
• Code review of build configurations
• CI/CD pipeline validation

Validation Capabilities

1. Critical Best Practices

• .DELETE_ON_ERROR validation: Checks for this critical GNU Make declaration
• Ensures partially built files are deleted on recipe failure
• Prevents corrupt builds from being reused
• References: GNU Make Special Targets

2. Syntax Validation

• GNU make validation: Validates using make -n --dry-run
• Catches syntax errors before build time
• Reports line numbers for syntax issues
• Validates target dependencies and prerequisites

3. mbake Integration

• Comprehensive formatting validation
• Tab indentation verification for recipes
• Variable assignment consistency
• Line continuation normalization
• Trailing whitespace detection
• Smart .PHONY detection and organization
• Validates with GNU make before/after formatting

4. Format Checking

• Consistent spacing around assignments
• Proper spacing after colons
• Tab vs spaces verification (recipes MUST use tabs)
• Line continuation character cleanup
• Organized .PHONY declarations
• Professional formatting standards

5. Security Checks

• Unsafe variable expansion in dangerous commands (rm, sudo, curl, wget)
• Hardcoded credentials detection (passwords, API keys, tokens)
• Command injection vulnerabilities
• Unquoted variable usage in shell commands
• Unsafe shell command patterns
• .EXPORT_ALL_VARIABLES usage warning (potential data leakage)

6. Best Practices

• .PHONY declarations for non-file targets
• Tab indentation enforcement (not spaces)
• Error handling in recipes (set -e, ||, @ prefix)
• Default target documentation
• Variable assignment operators (=, :=, ?=, +=)
• VPATH/vpath usage for source organization
• Proper dependency specification
• .ONESHELL safety: Warns when .ONESHELL is used without proper error handling (-e flag)
• $(MAKE) usage: Warns when make is used directly instead of $(MAKE) for recursive calls

7. Optimization Opportunities

• Parallel build safety (.NOTPARALLEL usage)
• Intermediate file cleanup (.INTERMEDIATE, .SECONDARY)
• Incremental build efficiency
• Unnecessary recompilation prevention
• Dependency tracking optimization

Quick Start

Basic Validation

# Validate a Makefile
bash scripts/validate_makefile.sh Makefile

# The validator will:
# 1. Check dependencies (python3, pip3, make)
# 2. Create isolated venv and install mbake
# 3. Run syntax validation with GNU make
# 4. Run mbake validation
# 5. Check formatting consistency
# 6. Perform custom security/best practice checks
# 7. Auto-cleanup venv on exit
# 8. Generate detailed report

Example Output

========================================
MAKEFILE VALIDATOR
========================================
File: Makefile

[ENVIRONMENT SETUP]
Creating temporary venv at: /tmp/makefile-validator-venv-12345
Installing mbake...
✓ Environment ready

[SYNTAX CHECK (GNU make)]
✓ No syntax errors found

[MBAKE VALIDATION]
Running mbake validate...
✓ mbake validation passed

[MBAKE FORMAT CHECK]
Checking formatting consistency...
⚠ Formatting issues found

Run 'mbake format Makefile' to fix formatting issues
Or run 'mbake format --diff Makefile' to preview changes

[CUSTOM CHECKS]
⚠ No .PHONY declarations found
   Consider adding .PHONY for targets that don't create files
   Example: .PHONY: clean test install

✗ Potential spaces instead of tabs in recipes detected
   Makefiles require TAB characters for recipe indentation

ℹ No VPATH/vpath declarations found
   Consider using VPATH for better source file organization

[CLEANUP]
Removing temporary venv...

========================================
VALIDATION SUMMARY
========================================
File: Makefile

Errors:   1
Warnings: 2
Info:     1

⚠ Validation PASSED with warnings

Usage in Claude Code

When validating Makefiles, Claude will automatically:

1. Invoke the validator on Makefile files
2. Analyze results to identify issues
3. Reference documentation for detailed explanations
4. Suggest fixes with code examples
5. Explain best practices from included guides
6. Format suggestions using mbake

Example Workflow

User: "Check this Makefile for issues"

Claude:
1. Runs validate_makefile.sh on the Makefile
2. Identifies issues (e.g., missing .PHONY, spaces instead of tabs)
3. References best-practices.md for standards
4. Suggests specific fixes with corrected code
5. Explains why each fix improves the build
6. Recommends mbake format for automatic fixes

Comprehensive Documentation

Core References

best-practices.md

• Makefile organization and structure
• Variable naming conventions
• .PHONY target usage
• Error handling in recipes
• Dependency specification
• Parallel build considerations
• VPATH and include usage
• Professional Makefile patterns

common-mistakes.md

• Spaces vs tabs in recipes
• Missing .PHONY declarations
• Improper dependency specification
• Variable expansion issues
• Hardcoded paths and credentials
• Inefficient build patterns
• Security vulnerabilities
• Portability problems

bake-tool.md

• mbake installation and configuration
• Format command options
• Validation capabilities
• CI/CD integration
• Configuration file setup (~/.bake.toml)
• Smart .PHONY detection
• Format disable comments
• Best practices for mbake usage

Validation Script Features

Automatic venv Isolation

The validator creates an isolated Python virtual environment:

• Unique temporary venv for each invocation
• Automatic mbake installation
• No system-wide package pollution
• Clean separation from project dependencies

Trap-Based Cleanup

Robust cleanup mechanism:

• trap cleanup EXIT INT TERM ensures cleanup always runs
• Removes venv on normal exit
• Removes venv on script interruption (Ctrl+C)
• Removes venv on error termination
• Prevents leftover temporary directories

Multi-Layer Validation

1. Dependency Check: Verifies python3, pip3, make availability
2. File Validation: Checks file existence and readability
3. Syntax Check: GNU make syntax validation
4. mbake Validation: Official mbake validator
5. Format Check: Formatting consistency verification
6. Custom Checks: Security and best practice patterns
7. Report Generation: Color-coded, detailed output

Exit Codes

• 0: No issues found (success)
• 1: Warnings found (passed with warnings)
• 2: Errors found (failed validation)

Installation Requirements

Required

• python3: For venv and mbake installation
• pip3: For installing mbake
• bash: For running validation script
• GNU make: For syntax validation (make -n)

  # macOS
  brew install make
  
  # Ubuntu/Debian
  apt-get install make
  
  # Fedora
  dnf install make
  

Optional (Recommended)

• checkmake: For additional linting coverage

  # With Go (1.16+)
  go install github.com/checkmake/checkmake/cmd/checkmake@latest
  

  checkmake rules include:

  • minphony: Checks for minimum required phony targets (all, test, clean)
  • phonydeclared: Ensures targets are properly declared as .PHONY
  • Other configurable rules via checkmake.ini

• unmake: For POSIX portability checks

  # See: https://github.com/mcandre/unmake
  

  unmake features:

  • POSIX make compliance checking
  • Portability warnings (MAKEFILE_PRECEDENCE, SIMPLIFY_AT, STRICT_POSIX)
  • Dry-run validation with multiple make implementations (bmake, gmake)

Automatic Installation

• mbake: Automatically installed in isolated venv
  • No manual installation required
  • Automatic cleanup after validation
  • Uses pip3 install mbake internally

Common Validation Scenarios

Scenario 1: Pre-commit Validation

# Validate Makefile before committing
bash .claude/skills/makefile-validator/scripts/validate_makefile.sh Makefile

# Fix any errors found
# Re-validate until clean

Scenario 2: Formatting Consistency

# Check formatting
mbake format --check Makefile

# Preview formatting changes
mbake format --diff Makefile

# Apply formatting
mbake format Makefile

# Re-validate
bash .claude/skills/makefile-validator/scripts/validate_makefile.sh Makefile

Scenario 3: Security Audit

The validator automatically checks for:

• Hardcoded credentials in variables
• Unsafe variable expansion in dangerous commands
• Command injection vulnerabilities
• Unvalidated user input in recipes

Reference common-mistakes.md for detailed explanations.

Scenario 4: Build Optimization

Identifies:

• Missing .PHONY declarations (performance impact)
• Sequential targets that could be parallel
• Missing .INTERMEDIATE/.SECONDARY for temp files
• Inefficient dependency patterns

Reference best-practices.md for optimization techniques.

Scenario 5: Converting Legacy Makefiles

# 1. Validate current Makefile
bash scripts/validate_makefile.sh legacy.mk

# 2. Fix critical errors (tabs, syntax)
# 3. Apply mbake formatting
mbake format legacy.mk

# 4. Add .PHONY declarations
mbake format --auto-insert-phony-declarations legacy.mk

# 5. Re-validate
bash scripts/validate_makefile.sh legacy.mk

# 6. Reference best-practices.md for modernization

Integration with Development Workflow

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

for file in $(git diff --cached --name-only --diff-filter=ACM | grep -E '(Makefile|makefile|.*\.mk)$'); do
    if ! bash .claude/skills/makefile-validator/scripts/validate_makefile.sh "$file"; then
        echo "Validation failed for $file"
        exit 1
    fi
done

CI/CD Integration

# GitHub Actions example
name: Validate Makefiles
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'
      - name: Validate Makefiles
        run: |
          find . -type f \( -name "Makefile" -o -name "makefile" -o -name "*.mk" \) \
            -exec bash .claude/skills/makefile-validator/scripts/validate_makefile.sh {} \;

Make Target for Self-Validation

.PHONY: validate-makefile
validate-makefile:
	@bash .claude/skills/makefile-validator/scripts/validate_makefile.sh $(MAKEFILE_LIST)

.PHONY: format-makefile
format-makefile:
	@mbake format --diff $(MAKEFILE_LIST)
	@read -p "Apply formatting? [y/N] " -n 1 -r; \
	echo; \
	if [[ $$REPLY =~ ^[Yy]$$ ]]; then \
		mbake format $(MAKEFILE_LIST); \
	fi

Learning Resources

Use the included documentation to:

1. Learn Makefile syntax: Start with best-practices.md
2. Understand build systems: Study GNU Make patterns
3. Avoid common mistakes: Review common-mistakes.md
4. Master mbake tool: Reference bake-tool.md
5. Optimize builds: Learn dependency management and parallel builds
6. Secure builds: Understand security implications

Best Practices

For Makefile Authors

1. Always declare .PHONY for non-file targets
2. Use tabs for recipe indentation (not spaces)
3. Add error handling with set -e or ||
4. Document default target and complex rules
5. Use := for variables to avoid recursive expansion
6. Organize with VPATH for multi-directory projects
7. Validate before committing to catch issues early
8. Format consistently using mbake

For Reviewers

1. Run validator on all Makefiles
2. Check security issues first (credentials, injection)
3. Verify .PHONY declarations for performance
4. Ensure proper dependencies for incremental builds
5. Look for optimization opportunities
6. Validate formatting consistency
7. Check error handling in critical recipes

Technical Details

Directory Structure

makefile-validator/
├── skill.md                    # This file
├── scripts/
│   └── validate_makefile.sh    # Main validation script
├── docs/
│   ├── best-practices.md       # Makefile best practices
│   ├── common-mistakes.md      # Common Makefile mistakes
│   └── bake-tool.md            # mbake tool reference
└── examples/
    ├── good-makefile.mk        # Well-written example
    └── bad-makefile.mk         # Anti-patterns example

Validation Logic Flow

1. Argument parsing → Validate input file path
2. Dependency check → Verify python3, pip3, make
3. File validation → Check existence and readability
4. Venv setup → Create isolated environment
5. mbake installation → Install in venv
6. Syntax check → GNU make -n --dry-run
7. mbake validate → Official validation
8. mbake format check → Consistency check
9. Custom checks → Security and best practices
10. Summary generation → Color-coded report
11. Cleanup → Remove venv via trap

Custom Check Categories

Security Checks:

• Hardcoded credentials pattern matching
• Unsafe command variable expansion
• Shell injection vulnerability patterns

Best Practice Checks:

• .PHONY declaration presence
• Tab vs space indentation
• Error handling patterns
• Default target documentation
• Variable assignment operator usage

Optimization Checks:

• .NOTPARALLEL declaration
• .INTERMEDIATE/.SECONDARY for temp files
• VPATH/vpath usage
• Dependency specification patterns

Advanced Features

mbake Configuration

Create ~/.bake.toml for project-wide settings:

space_around_assignment = true
space_after_colon = true
normalize_line_continuations = true
remove_trailing_whitespace = true
fix_missing_recipe_tabs = true
auto_insert_phony_declarations = true
group_phony_declarations = true
phony_at_top = false

Format Disable Comments

# bake-format off
legacy-target:
    # Preserve legacy formatting
    echo "custom spacing"
# bake-format on

modern-target:
	@echo "Standard formatting applies"

Selective Validation

# Validate specific Makefile
bash scripts/validate_makefile.sh src/Makefile

# Validate all .mk files
find . -name "*.mk" -exec bash scripts/validate_makefile.sh {} \;

# Validate only in specific directories
find src/ -type f -name "Makefile" -exec bash scripts/validate_makefile.sh {} \;

Known Limitations

mbake Tool Limitations

The mbake tool has some known limitations that this validator handles:

1. Unknown Special Targets: mbake doesn't recognize some valid GNU Make special targets:

   • .DELETE_ON_ERROR - Reported as unknown but is valid and critical
   • .SUFFIXES - Reported as unknown but is valid
   • .ONESHELL - Reported as unknown but is valid
   • .POSIX - Reported as unknown but is valid

   The validator filters these false positives and shows them as informational messages instead of errors.

2. format --check vs format inconsistency: The mbake format --check command may report different issues than what mbake format actually fixes. This is a known upstream issue.

3. POSIX Make compatibility: mbake is designed for GNU Make and may not work correctly with pure POSIX make syntax.

For additional linting coverage, consider installing checkmake alongside mbake.

Resources

Official Documentation

• GNU Make Manual
• mbake GitHub Repository
• mbake PyPI Package
• checkmake GitHub

Web Resources

• Makefile Best Practices
• Common Makefile Mistakes
• Makefile Optimization

Internal References

All documentation is included in the docs/ directory for offline reference and context loading.

---

Note: This skill automatically loads relevant documentation based on validation results, providing Claude with the necessary context to explain issues and suggest fixes effectively. The venv isolation and trap-based cleanup ensure clean, safe validation without affecting your system or project dependencies.