Makefile 验证器

概览

这项技能提供了全面的 Makefile 验证，检查语法错误、格式一致性、最佳实践、安全漏洞和优化机会。它使用 mbake 工具（Makefile 格式化器和 linter）以及自定义验证检查，以确保高质量的构建配置。

何时使用这项技能

在以下情况下使用这项技能：

验证 Makefile（Makefile、makefile、*.mk 文件）
检查构建配置中的语法错误
确保一致的 Makefile 格式
在构建食谱中识别安全漏洞
寻找构建性能的优化机会
调试 Makefile 问题
强制执行 .PHONY 目标声明
验证食谱中的制表符缩进
学习 Makefile 最佳实践
构建配置的代码审查
CI/CD 管道验证

验证能力

1. 关键最佳实践

.DELETE_ON_ERROR 验证：检查这个关键的 GNU Make 声明
确保在配方失败时删除部分构建的文件
防止被重用的损坏构建
参考：GNU Make 特殊目标

2. 语法验证

GNU make 验证：使用 make -n --dry-run 进行验证
在构建时间之前捕获语法错误
报告语法问题的行号
验证目标依赖关系和先决条件

3. mbake 集成

全面的格式化验证
食谱的制表符缩进验证
变量赋值一致性
行续行标准化
尾随空格检测
智能 .PHONY 检测和组织
在格式化前后使用 GNU make 进行验证

4. 格式检查

赋值周围的一致空格
冒号后的适当空格
制表符与空格验证（食谱必须使用制表符）
行续字符清理
组织的 .PHONY 声明
专业的格式化标准

5. 安全检查

危险命令中的不安全变量扩展（rm、sudo、curl、wget）
硬编码凭据检测（密码、API 密钥、令牌）
命令注入漏洞
未引用变量在 shell 命令中的使用
不安全的 shell 命令模式
.EXPORT_ALL_VARIABLES 使用警告（潜在的数据泄露）

6. 最佳实践

非文件目标的 .PHONY 声明
制表符缩进执行（不是空格）
食谱中的错误处理（set -e、||、@ 前缀）
默认目标文档
变量赋值操作符（=、:=、?=、+=）
VPATH/vpath 用于源组织
适当的依赖项规范
.ONESHELL 安全性：当 .ONESHELL 没有适当的错误处理（-e 标志）时发出警告
$(MAKE) 使用：当直接使用 make 而不是 $(MAKE) 进行递归调用时发出警告

7. 优化机会

并行构建安全性（.NOTPARALLEL 使用）
中间文件清理（.INTERMEDIATE、.SECONDARY）
增量构建效率
防止不必要的重新编译
依赖项跟踪优化

快速开始

基本验证

# 验证 Makefile
bash scripts/validate_makefile.sh Makefile

# 验证器将：
# 1. 检查依赖关系（python3、pip3、make）
# 2. 创建隔离的 venv 并安装 mbake
# 3. 使用 GNU make 运行语法验证
# 4. 运行 mbake 验证
# 5. 检查格式一致性
# 6. 执行自定义安全/最佳实践检查
# 7. 自动清理 venv 退出
# 8. 生成详细报告

示例输出

========================================
MAKEFILE VALIDATOR
========================================
文件：Makefile

[环境设置]
在：/tmp/makefile-validator-venv-12345 创建临时 venv
安装 mbake...
✓ 环境就绪

[语法检查（GNU make）]
✓ 未发现语法错误

[MBAKE 验证]
运行 mbake validate...
✓ mbake 验证通过

[MBAKE 格式检查]
检查格式一致性...
⚠ 发现格式问题

运行 'mbake format Makefile' 修复格式问题
或运行 'mbake format --diff Makefile' 预览更改

[自定义检查]
⚠ 未发现 .PHONY 声明
  考虑为目标添加 .PHONY，这些目标不创建文件
  示例：.PHONY: clean test install

✗ 检测到食谱中可能使用了空格而不是制表符
   Makefiles 需要 TAB 字符进行食谱缩进

ℹ 未发现 VPATH/vpath 声明
  考虑使用 VPATH 以获得更好的源文件组织

[清理]
移除临时 venv...

========================================
验证摘要
========================================
文件：Makefile

错误：1
警告：2
信息：1

⚠ 验证通过，但有警告

在 Claude 代码中的使用

当验证 Makefiles 时，Claude 将自动：

在 Makefile 文件上调用验证器
分析结果以识别问题
参考文档以获得详细解释
提供修复建议，带有代码示例
解释包含指南中的最佳实践
使用 mbake 格式化建议

示例工作流程

用户："检查这个 Makefile 是否有问题"

Claude：
1. 在 Makefile 上运行 validate_makefile.sh
2. 识别问题（例如，缺少 .PHONY，空格而不是制表符）
3. 参考 best-practices.md 标准
4. 提出具体修复建议，带有更正的代码
5. 解释每个修复如何改善构建
6. 推荐 mbake format 进行自动修复

全面文档

核心参考

best-practices.md

Makefile 组织和结构
变量命名约定
.PHONY 目标使用
食谱中的错误处理
依赖项规范
并行构建考虑
VPATH 和 include 使用
专业的 Makefile 模式

common-mistakes.md

食谱中的空格与制表符
缺少 .PHONY 声明
不正确的依赖项规范
变量扩展问题
硬编码路径和凭据
低效的构建模式
安全漏洞
可移植性问题

bake-tool.md

mbake 安装和配置
格式命令选项
验证能力
CI/CD 集成
配置文件设置（~/.bake.toml）
智能 .PHONY 检测
格式禁用注释
mbake 使用的最佳实践

验证脚本功能

自动 venv 隔离

验证器创建一个隔离的 Python 虚拟环境：

每次调用都有唯一的临时 venv
自动 mbake 安装
没有系统范围的包污染
与项目依赖项的干净分离

基于 Trap 的清理

强大的清理机制：

trap cleanup EXIT INT TERM 确保清理始终运行
在正常退出时移除 venv
在脚本中断（Ctrl+C）时移除 venv
在错误终止时移除 venv
防止临时目录遗留

多层验证

依赖项检查：验证 python3、pip3、make 的可用性
文件验证：检查文件存在和可读性
语法检查：GNU make 语法验证
mbake 验证：官方 mbake 验证器
格式检查：格式一致性验证
自定义检查：安全和最佳实践模式
报告生成：彩色编码的详细输出

退出代码

0：未发现问题（成功）
1：发现警告（通过警告）
2：发现错误（验证失败）

安装要求

必需

python3：用于 venv 和 mbake 安装
pip3：用于安装 mbake
bash：用于运行验证脚本

GNU make：用于语法验证（make -n）

# macOS
brew install make

# Ubuntu/Debian
apt-get install make

# Fedora
dnf install make

可选（推荐）

checkmake：用于额外的 linting 覆盖
```
# 用 Go（1.16+）
go install github.com/checkmake/checkmake/cmd/checkmake@latest
```
checkmake 规则包括：
- minphony：检查所需的最小 phony 目标（all, test, clean）
- phonydeclared：确保目标被正确声明为 .PHONY
- 通过 checkmake.ini 配置的其他规则
unmake：用于 POSIX 可移植性检查
```
# 见：https://github.com/mcandre/unmake
```
unmake 功能：
- POSIX make 合规性检查
- 可移植性警告（MAKEFILE_PRECEDENCE, SIMPLIFY_AT, STRICT_POSIX）
- 使用多个 make 实现进行干运行验证（bmake, gmake）

自动安装

mbake：在隔离的 venv 中自动安装
- 不需要手动安装
- 验证后自动清理
- 内部使用 pip3 install mbake

常见验证场景

场景 1：预提交验证

# 提交前验证 Makefile
bash .claude/skills/makefile-validator/scripts/validate_makefile.sh Makefile

# 修复发现的任何错误
# 重新验证直到干净

场景 2：格式一致性

# 检查格式
mbake format --check Makefile

# 预览格式更改
mbake format --diff Makefile

# 应用格式
mbake format Makefile

# 重新验证
bash .claude/skills/makefile-validator/scripts/validate_makefile.sh Makefile

场景 3：安全审计

验证器自动检查：

变量中的硬编码凭据
危险命令中的不安全变量扩展
命令注入漏洞
食谱中的未经验证的用户输入

参考 common-mistakes.md 以获取详细解释。

场景 4：构建优化

识别：

缺少 .PHONY 声明（性能影响）
可以并行的顺序目标
缺少 .INTERMEDIATE/.SECONDARY 用于临时文件
低效的依赖项模式

参考 best-practices.md 以获取优化技术。

场景 5：转换遗留 Makefiles

# 1. 验证当前 Makefile
bash scripts/validate_makefile.sh legacy.mk

# 2. 修复关键错误（制表符、语法）
# 3. 应用 mbake 格式化
mbake format legacy.mk

# 4. 添加 .PHONY 声明
mbake format --auto-insert-phony-declarations legacy.mk

# 5. 重新验证
bash scripts/validate_makefile.sh legacy.mk

# 6. 参考 best-practices.md 进行现代化

集成到开发工作流程中

预提交钩子

#!/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 集成

# GitHub Actions 示例
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 目标

.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

学习资源

使用包含的文档：

学习 Makefile 语法：从 best-practices.md 开始
了解构建系统：研究 GNU Make 模式
避免常见错误：查看 common-mistakes.md
掌握 mbake 工具：参考 bake-tool.md
优化构建：学习依赖项管理和并行构建
保护构建：了解安全影响

最佳实践

针对 Makefile 作者

始终声明 .PHONY 用于非文件目标
使用制表符 进行食谱缩进（不是空格）
添加错误处理 使用 set -e 或 ||
记录默认目标 和复杂规则
使用 := 用于变量 以避免递归扩展
使用 VPATH 组织 多目录项目
提交前验证 以尽早发现问题
使用 mbake 一致格式化

针对审核者

在所有 Makefiles 上运行验证器
首先检查安全问题（凭据、注入）
验证 .PHONY 声明 以提高性能
确保适当的依赖项 以实现增量构建
寻找优化 机会
验证格式 一致性
检查关键食谱中的错误处理

技术细节

目录结构

makefile-validator/
├── skill.md                    # 此文件
├── scripts/
│   └── validate_makefile.sh    # 主验证脚本
├── docs/
│   ├── best-practices.md       # Makefile 最佳实践
│   ├── common-mistakes.md      # 常见 Makefile 错误
│   └── bake-tool.md            # mbake 工具参考
└── examples/
    ├── good-makefile.mk        # 编写良好的示例
    └── bad-makefile.mk         # 反模式示例

验证逻辑流程

参数解析 → 验证输入文件路径
依赖项检查 → 验证 python3、pip3、make
文件验证 → 检查存在和可读性
Venv 设置 → 创建隔离环境
mbake 安装 → 在 venv 中安装
语法检查 → GNU make -n --dry-run
mbake 验证 → 官方验证
mbake 格式检查 → 一致性检查
自定义检查 → 安全和最佳实践
摘要生成 → 彩色编码报告
清理 → 通过 trap 移除 venv

自定义检查类别

安全检查：

硬编码凭据模式匹配
危险命令中的不安全命令变量扩展
壳注入漏洞模式

最佳实践检查：

.PHONY 声明的存在
制表符与空格缩进
错误处理模式
默认目标文档
变量赋值操作符使用

优化检查：

.NOTPARALLEL 声明
用于临时文件的 .INTERMEDIATE/.SECONDARY
VPATH/vpath 使用
依赖项规范模式

高级功能

mbake 配置

创建 ~/.bake.toml 用于项目范围设置：

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

格式禁用注释

# bake-format off
legacy-target:
    # 保留旧版格式
    echo "custom spacing"
# bake-format on

modern-target:
	@echo "Standard formatting applies"

选择性验证

# 验证特定的 Makefile
bash scripts/validate_makefile.sh src/Makefile

# 验证所有 .mk 文件
find . -name "*.mk" -exec bash scripts/validate_makefile.sh {} \;

# 仅在特定目录中验证
find src/ -type f -name "Makefile" -exec bash scripts/validate_makefile.sh {} \;

已知限制

mbake 工具限制

mbake 工具有一些已知限制，此验证器处理：

未知特殊目标：mbake 不识别一些有效的 GNU Make 特殊目标：
- .DELETE_ON_ERROR - 报告为未知，但有效且关键
- .SUFFIXES - 报告为未知，但有效
- .ONESHELL - 报告为未知，但有效
- .POSIX - 报告为未知，但有效
验证器过滤这些误报 并将它们显示为信息性消息，而不是错误。
format --check 与 format 一致性：mbake format --check 命令可能报告与 mbake format 实际修复的问题不同。这是一个已知的上游问题。
POSIX Make 兼容性：mbake 为 GNU Make 设计，可能无法正确处理纯 POSIX make 语法。

对于额外的 linting 覆盖，考虑安装 checkmake 与 mbake 一起。

资源

官方文档

网络资源

内部参考

所有文档都包含在 `docs/` 目录中，供离线参考和上下文加载。

注：此技能根据验证结果自动加载相关文档，为 Claude 提供必要的上下文以有效解释问题并提出修复建议。venv 隔离和基于 trap 的清理确保了干净、安全的验证，不影响您的系统或项目依赖项。