# 🔨 PMAT Makefile Linting & Analysis - Comprehensive Guide
## Table of Contents
1. [Overview](#overview)
2. [Features](#features)
3. [Usage Examples](#usage-examples)
4. [Rules and Checks](#rules-and-checks)
5. [Auto-Fix Capabilities](#auto-fix-capabilities)
6. [CI/CD Integration](#cicd-integration)
7. [Output Formats](#output-formats)
8. [Best Practices](#best-practices)
## Overview
PMAT provides comprehensive Makefile analysis and linting capabilities to ensure maintainable, portable, and efficient build configurations. The system detects common issues, suggests improvements, and can automatically fix many problems.
### Key Features
- **🎯 Rule-Based Analysis**: 20+ configurable rules for Makefile quality
- **🔧 Auto-Fix Support**: Automatic correction of common issues
- **📊 Quality Scoring**: Overall quality score with detailed breakdowns
- **🔄 GNU Make Compatibility**: Version-specific compatibility checking
- **🌍 Portability Analysis**: Cross-platform compatibility detection
- **📈 Complexity Metrics**: Recipe complexity and target dependency analysis
## Features
### Core Capabilities
1. **Structural Analysis**
- Target dependency mapping
- Recipe complexity measurement
- Variable usage tracking
- Include file resolution
2. **Quality Checks**
- PHONY target declarations
- Recipe body length limits
- Pattern rule optimization
- Variable naming conventions
3. **Portability Analysis**
- GNU Make specific features
- POSIX compliance checking
- Shell compatibility
- Path separator issues
4. **Performance Optimization**
- Parallel execution opportunities
- Redundant recipe detection
- Variable expansion efficiency
- Dependency optimization
## Usage Examples
### Basic Analysis
```bash
# Analyze a Makefile with default settings
pmat analyze makefile Makefile
# Analyze with specific GNU Make version
pmat analyze makefile Makefile --gnu-version 3.82
# Auto-fix detected issues
pmat analyze makefile Makefile --fix
```
### Advanced Workflows
#### 1. CI/CD Integration
```bash
# Generate machine-readable output for CI
pmat analyze makefile Makefile --format json > makefile-report.json
# GCC-style output for editor integration
pmat analyze makefile Makefile --format gcc
# SARIF format for GitHub Actions
pmat analyze makefile Makefile --format sarif > makefile.sarif
```
#### 2. Rule-Specific Analysis
```bash
# Check only specific rules
pmat analyze makefile Makefile --rules phonydeclared,maxbodylength
# Focus on portability issues
pmat analyze makefile Makefile --rules portability,posix
# Performance optimization
pmat analyze makefile Makefile --rules parallel,redundant
```
#### 3. MCP Tool Integration
```javascript
// Using PMAT MCP tools for Makefile analysis
const response = await mcp.callTool('pmat', 'analyze_makefile', {
path: 'Makefile',
rules: ['all'],
fix: true,
gnu_version: '4.4'
});
console.log(`Quality Score: ${response.quality_score}%`);
console.log(`Violations: ${response.violations.length}`);
```
## Rules and Checks
### Critical Rules (Errors)
| **syntax** | Syntax errors and malformed lines | ❌ |
| **undefined** | Undefined variable references | ❌ |
| **circular** | Circular dependency detection | ❌ |
| **missing** | Missing required targets (.PHONY) | ✅ |
### Quality Rules (Warnings)
| **phonydeclared** | Non-file targets should be .PHONY | ✅ | On |
| **maxbodylength** | Recipe exceeds line limit (10) | ⚠️ | On |
| **indentation** | Inconsistent tab/space usage | ✅ | On |
| **trailing** | Trailing whitespace | ✅ | On |
| **variable** | Variable naming conventions | ❌ | On |
| **duplicate** | Duplicate target definitions | ❌ | On |
### Portability Rules (Info)
| **portability** | GNU Make specific features | ❌ | Cross-platform |
| **posix** | POSIX compliance issues | ❌ | Unix systems |
| **shell** | Shell-specific commands | ❌ | Windows/Unix |
| **pathsep** | Path separator issues | ✅ | Windows/Unix |
### Performance Rules (Optimization)
| **parallel** | Parallelization opportunities | ⚠️ | Speed |
| **redundant** | Redundant recipes | ✅ | Maintenance |
| **expansion** | Inefficient variable expansion | ✅ | Performance |
| **wildcard** | Suboptimal wildcard usage | ⚠️ | Speed |
## Auto-Fix Capabilities
### Automatic Fixes (Safe)
```makefile
# Before: Missing .PHONY declaration
test:
cargo test
# After: Automatic fix applied
.PHONY: test
test:
cargo test
```
```makefile
# Before: Trailing whitespace
build:
cargo build
# After: Automatic fix applied
build:
cargo build
```
### Suggested Fixes (Manual Review)
```makefile
# Before: Long recipe body
deploy:
@echo "Starting deployment..."
cargo build --release
cargo test --release
# ... 20 more lines ...
@echo "Deployment complete"
# Suggestion: Split into smaller targets
.PHONY: deploy
deploy: build-release test-release deploy-artifacts notify-complete
build-release:
cargo build --release
test-release:
cargo test --release
deploy-artifacts:
# deployment logic
notify-complete:
@echo "Deployment complete"
```
## CI/CD Integration
### GitHub Actions Example
```yaml
name: Makefile Quality Check
on: [push, pull_request]
jobs:
makefile-lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Install PMAT
run: cargo install pmat --locked
- name: Analyze Makefile
run: |
pmat analyze makefile Makefile \
--format sarif \
> makefile-analysis.sarif
- name: Upload SARIF
uses: github/codeql-action/upload-sarif@v2
with:
sarif_file: makefile-analysis.sarif
- name: Auto-fix Issues
run: |
pmat analyze makefile Makefile --fix
- name: Create PR with fixes
if: github.event_name == 'push'
uses: peter-evans/create-pull-request@v5
with:
commit-message: 'fix: Auto-fix Makefile issues'
title: '[Auto] Fix Makefile quality issues'
body: |
## Automatic Makefile Fixes
This PR contains automatic fixes for Makefile quality issues.
Generated by PMAT Makefile linting.
branch: auto/makefile-fixes
```
### Pre-commit Hook
```bash
#!/bin/bash
# .git/hooks/pre-commit
# Check Makefile quality
if [ -f "Makefile" ]; then
echo "🔨 Checking Makefile quality..."
pmat analyze makefile Makefile --format gcc
if [ $? -ne 0 ]; then
echo "❌ Makefile has quality issues. Run 'pmat analyze makefile Makefile --fix' to auto-fix."
exit 1
fi
echo "✅ Makefile quality check passed"
fi
```
## Output Formats
### Human-Readable (Default)
```
# Makefile Analysis Report
**File**: Makefile
**Quality Score**: 85.5%
**GNU Make Version**: 4.4
## Violations
| 169 | phonydeclared | ℹ️ Info | Target 'test' should be declared .PHONY |
| 256 | maxbodylength | ⚠️ Warning | Recipe has 14 lines (max: 10) |
```
### JSON Format
```json
{
"file": "Makefile",
"quality_score": 85.5,
"gnu_version": "4.4",
"violations": [
{
"line": 169,
"rule": "phonydeclared",
"severity": "info",
"message": "Target 'test' should be declared .PHONY",
"fix_available": true
}
],
"metrics": {
"total_targets": 45,
"phony_targets": 38,
"variables": 23,
"includes": 2
}
}
```
### GCC Format (Editor Integration)
```
Makefile:169:1: info: Target 'test' should be declared .PHONY [phonydeclared]
Makefile:256:1: warning: Recipe has 14 lines (max: 10) [maxbodylength]
```
### SARIF Format (CI/CD)
```json
{
"$schema": "https://json.schemastore.org/sarif-2.1.0.json",
"version": "2.1.0",
"runs": [{
"tool": {
"driver": {
"name": "PMAT Makefile Linter",
"version": "2.71.0"
}
},
"results": [
{
"ruleId": "phonydeclared",
"level": "note",
"message": {
"text": "Target 'test' should be declared .PHONY"
},
"locations": [{
"physicalLocation": {
"artifactLocation": {
"uri": "Makefile"
},
"region": {
"startLine": 169
}
}
}]
}
]
}]
}
```
## Best Practices
### 1. Structure and Organization
```makefile
# Good: Clear sections with comments
#############################################
# Variables
#############################################
CC := gcc
CFLAGS := -Wall -Wextra -O2
#############################################
# Targets
#############################################
.PHONY: all build test clean
all: build test
build:
$(CC) $(CFLAGS) -o app main.c
test:
./test.sh
clean:
rm -f app *.o
```
### 2. PHONY Declarations
```makefile
# Always declare non-file targets as .PHONY
.PHONY: test clean install deploy help
# Group related PHONY targets
.PHONY: test test-unit test-integration test-e2e
test: test-unit test-integration test-e2e
```
### 3. Recipe Length Management
```makefile
# Bad: Long monolithic recipe
deploy:
@echo "Building..."
cargo build --release
@echo "Testing..."
cargo test --release
@echo "Packaging..."
tar czf release.tar.gz target/release/app
@echo "Uploading..."
scp release.tar.gz server:/opt/
@echo "Installing..."
ssh server "cd /opt && tar xzf release.tar.gz"
@echo "Restarting..."
ssh server "systemctl restart app"
@echo "Done!"
# Good: Modular targets
.PHONY: deploy
deploy: build-release test-release package upload install restart
@echo "Deployment complete!"
.PHONY: build-release
build-release:
@echo "Building..."
cargo build --release
.PHONY: package
package:
@echo "Packaging..."
tar czf release.tar.gz target/release/app
```
### 4. Portability Considerations
```makefile
# Use portable constructs when possible
# Bad: GNU Make specific
SOURCES := $(wildcard src/*.c)
OBJECTS := $(SOURCES:.c=.o)
# Better: More portable
SOURCES = src/main.c src/util.c src/config.c
OBJECTS = $(SOURCES:.c=.o)
# Handle OS differences
ifeq ($(OS),Windows_NT)
RM = del /Q
PATHSEP = \\
else
RM = rm -f
PATHSEP = /
endif
```
### 5. Performance Optimization
```makefile
# Enable parallel execution
.PHONY: test-all
test-all: test-unit test-integration test-doc
@echo "All tests complete"
# Mark independent targets
.PHONY: test-unit test-integration test-doc
test-unit:
cargo test --lib
test-integration:
cargo test --test '*'
test-doc:
cargo test --doc
```
## Integration with PMAT Ecosystem
### Quality Gate Integration
```toml
# pmat.toml
[quality.gates.makefile]
enabled = true
auto_fix = true
max_violations = 5
required_score = 80.0
rules = ["phonydeclared", "maxbodylength", "portability"]
```
### MCP Tool Composition
```javascript
// Combine with other PMAT tools
await mcp.callTool('pmat', 'analyze_complexity');
await mcp.callTool('pmat', 'analyze_makefile', {
path: 'Makefile',
fix: true
});
await mcp.callTool('pmat', 'quality_gate');
```
### Roadmap Integration
The Makefile linting feature is part of PMAT's broader build system quality initiative:
- **Current**: Basic linting and auto-fix
- **Sprint 88**: Advanced pattern detection
- **Sprint 89**: Cross-build-system support (CMake, Bazel)
- **Future**: AI-powered optimization suggestions
---