# 生成文件生成器 ## 概述使用 C/C++、Python、Go、Java 和通用项目的最佳实践生成生产就绪的 Makefile。具有 GNU 编码标准合规性、标准目标、安全强化以及通过 devops-skills:makefile-validator 技能进行自动验证。 ## 何时使用 * 从头开始创建新的 Makefile * 为项目设置构建系统（C/C++、Python、Go、Java） * 实施构建自动化和 CI/CD 集成 * 将手动构建过程转换为 Makefile * 用户要求“创建”、“生成”或“编写”Makefile **请勿用于：** 验证现有 Makefile（使用 devops-skills:makefile-validator）、调试（使用 `make -d`）或运行构建。 ## 触发短语当提示如下时使用此技能： *“为 Go 服务生成 Makefile” *“使用安装/测试/帮助目标创建生产 Makefile” *“为具有依赖性跟踪的 C 项目编写 Makefile” *“将标准 GNU 目标添加到现有的 Makefile” ## 生成工作流程 ### 第 1 阶段：收集需求收集以下类别的信息。 **当信息丢失或不明确时使用 AskUserQuestion：** 类别 |所需信息 ---|--- **项目** |语言（C/C++/Python/Go/Java）、结构（单/多目录） **构建** |源文件、输出工件、依赖项、构建顺序 **安装** | PREFIX 位置、目录 (bin/lib/share)、要安装的文件 **目标** | all、install、clean、test、dist、help（需要哪些？） **配置** |编译器、标志、pkg-config 依赖项、交叉编译 **何时使用 AskUserQuestion（必须询问是否适用）：** 状况 |示例问题 ---|--- 未指定语言 | “这个项目是什么编程语言？（C/C++/Go/Python/Java）” 项目结构尚不清楚| “这是单目录还是多目录项目？” Docker 已请求但注册表未知 | “应该使用哪个容器注册表？(docker.io/ghcr.io/custom)” 可能有多个二进制文件 | “这应该构建一个二进制文件还是多个可执行文件？” 安装需要的目标但路径不清楚 | “二进制文件应该安装在哪里？（默认：/usr/local/bin）” 提到交叉编译| “目标平台/架构是什么？” **何时跳过 AskUserQuestion（使用默认值继续）：** * 用户明确提供所有必需的信息 * 具有明显默认值的标准项目类型（例如，“使用 Docker 进行项目”→ 使用标准 Go+Docker 模式） * 用户说“使用默认值”或“标准设置” **默认假设（未询问时）：** * 单目录项目结构 * 前缀=/usr/local * 标准目标：全部、构建、测试、清理、安装、帮助 * 无交叉编译 ### 第 2 阶段：文档查找 **需要时（必须执行查找）：** * 用户请求与不熟悉的工具、框架或构建系统集成 * 第 3 阶段示例中未涵盖的复杂构建模式（例如 Bazel、Meson、自定义工具链） * **Docker/容器集成**（Dockerfile 构建、多阶段、注册表推送） * CI/CD 平台特定集成（GitHub Actions、GitLab CI、Jenkins） * 针对异常目标或嵌入式系统的交叉编译 * 包管理器集成（Conan、vcpkg、Homebrew 公式） * **多二进制或多库项目** * **通过 ldflags 或构建时变量嵌入版本** **当可选时（可以跳过外部查找）：** * 第 3 阶段已涵盖标准语言模式（C/C++、Go、Python、Java） * 简单的单二进制项目，没有外部依赖项 * 用户提供完整的要求，没有歧义 * 内部文档已经全面涵盖了所需的模式 **查找过程（按顺序进行）：** 1. **始终首先使用显式文件打开命令查阅内部文档**（主要事实来源）： **完整的文档路径图（首选完整路径以获得确定性访问）：** 文档 |完整路径 ---|--- 结构指南| `devops-skills-plugin/skills/makefile-generator/docs/makefile-struct.md` 变量指南 | `devops-skills-plugin/skills/makefile-generator/docs/variables-guide.md` 目标指南| `devops-skills-plugin/skills/makefile-generator/docs/targets-guide.md` 图案指南 | `devops-skills-plugin/skills/makefile-generator/docs/patterns-guide.md` 优化指南| `devops-skills-plugin/skills/makefile-generator/docs/optimization-guide.md` 安全指南| `devops-skills-plugin/skills/makefile-generator/docs/security-guide.md` 要求|阅读本文档 ---|--- Docker/容器目标 | `.../docs/patterns-guide.md`（模式 8：Docker 集成）多二进制项目 | `.../docs/patterns-guide.md`（模式 7：多二进制项目）具有版本嵌入的 Go 项目 | `.../docs/patterns-guide.md`（模式 5：Go 项目）并行构建、缓存、ccache | `.../docs/optimization-guide.md` 凭证、秘密、API 密钥 | `.../docs/security-guide.md` 复杂的依赖关系、模式规则 | `.../docs/patterns-guide.md` 仅限订购先决条件 | `.../docs/optimization-guide.md` 或 `.../docs/targets-guide.md` 变量、赋值运算符 | `.../docs/variables-guide.md` **确定性打开/读取命令：** # 从存储库根目录： sed -n '1,220p' devops-skills-plugin/skills/makefile-generator/docs/patterns-guide.md rg -n "模式 5|模式 8" devops-skills-plugin/skills/makefile-generator/docs/patterns-guide.md # 来自技能目录： sed -n '1,220p' 文档/security-guide.md 如果 shell 命令不可用，请在相同路径上使用环境的文件打开/读取功能。 **所需的工作流程示例（带有版本嵌入的 Docker + Go）：** # 第 1 步：阅读 Go 模式 rg -n“模式 5”devops-skills-plugin/skills/makefile-generator/docs/patterns-guide.md # 第二步：阅读 Docker 模式 rg -n“模式 8”devops-skills-plugin/skills/makefile-generator/docs/patterns-guide.md # 第 3 步：阅读安全指南 sed -n '1,220p' devops-skills-plugin/skills/makefile-generator/docs/security-guide.md 然后生成 Makefile 并在标题注释中列出参考的文档。 2. **尝试使用 context7 获取外部工具文档**（当内部文档不涵盖特定工具时）： # 仅内部文档未涵盖的工具/框架需要 mcp__context7__resolve-library-id：“<工具名称>” mcp__context7__query-docs：查询 =“<集成主题>” # 查询示例： # - 对于 Docker：query="dockerfile 最佳实践" # - 对于 Go：query="go build ldflags" # - 对于特定工具：query="<工具> makefile 集成" **后备：** 如果 context7 不可用或返回任何有用信息，请记录下来并继续执行步骤 3。 3. **回退到 WebSearch**（仅当在内部文档或上下文中未找到模式7时）： “<特定功能>”makefile 最佳实践 2025 示例：“2025 年 docker makefile 最佳实践” 示例：“go ldflags 版本 makefile 2025” **在以下情况下触发 WebSearch：** 内部文档未涵盖特定集成并且 context7 未返回相关结果。 **注意：** 记录您在回复中查阅的内部文档（在生成的 Makefile 标头中添加注释）。 ### 第 3 阶段：生成 Makefile **可选的帮助脚本快速路径（用于标准布局）：** # 生成模板：类型名称输出 bash 脚本/generate_makefile_template.sh 转到 myservice Makefile # 仅添加选定的标准目标 bash 脚本/add_standard_targets.sh Makefile 安装清理帮助当需求复杂时（Docker 发布流程、多二进制矩阵、自定义工具链），请使用手动创作。 #### 标题（选择一种样式） **传统（POSIX 兼容）：** .DELETE_ON_ERROR： .后缀： **现代（GNU Make 4.0+，推荐）：** 外壳 := bash .ONESHELL： .SHELLFLAGS := -eu -o pipelinefail -c .DELETE_ON_ERROR： .后缀： MAKEFLAGS += --警告未定义变量 MAKEFLAGS += --no-builtin-rules #### 标准变量 # 用户可重写（使用 ?=） CC ?= 海湾合作委员会 CFLAGS ?= -Wall -Wextra -O2 前缀 ?= /usr/local 目标目录？= # GNU 安装目录 BINDIR ?= $(前缀)/bin LIBDIR ?= $(PREFIX)/lib INCLUDEDIR ?= $(前缀)/包括 # 项目特定（使用 :=）项目 := 我的项目版本：= 1.0.0 SRCDIR := src BUILDDIR := 构建来源 := $(通配符 $(SRCDIR)/*.c) 对象 := $(源:$(SRCDIR)/%.c=$(BUILDDIR)/%.o) #### 特定于语言的构建规则 **C/C++：** $（目标）：$（对象） $(CC) $(LDFLAGS) $^ $(LDLIBS) -o $@ $(BUILDDIR)/%.o: $(SRCDIR)/%.c @mkdir -p $(@D) $(CC) $(CPPFLAGS) $(CFLAGS) -MMD -MP -c $< -o $@ -包括$(对象:.o=.d) **去：** $(TARGET): $(shell find .-name '*.go') go.mod go build -o $@ ./cmd/$(项目) **Python：** .PHONY：构建构建：蟒蛇-m构建 .PHONY：开发开发： pip install -e .[dev] **Java：** $(BUILDDIR)/%.class: $(SRCDIR)/%.java @mkdir -p $(@D) javac -d $(BUILDDIR) -sourcepath $(SRCDIR) $< #### 标准目标 .PHONY：所有全新安装卸载测试帮助 ## 构建所有目标全部：$(目标) ## 安装到 PREFIX 安装：全部安装-d $(DESTDIR)$(BINDIR) 安装-m 755 $(目标)$(DESTDIR)$(BINDIR)/ ## 删除构建的文件干净： $(RM) -r $(BUILDDIR) $(目标) ## 运行测试测试： # 添加测试命令 ## 显示帮助帮助： @echo“$（项目）v$（版本）” @echo“目标：所有、安装、清理、测试、帮助” @echo“覆盖：使 CC=clang PREFIX=/opt” ### 第 4 阶段：验证和格式化每个生成的 Makefile 都需要验证。 #### 验证工具预检（默认 + 后备） 1. **首选路径：**运行 `devops-skills:makefile-validator`。 2. **如果验证器技能不可用：** 运行本地回退检查： # 必需的后备检查（如果 make 存在） make -f -n --dry-run # 结构回退检查 rg -n '^ {1,}\S' # 可疑的空格缩进配方行 rg -n '^\.PHONY:' 3. **如果`make`不可用：**仅运行结构检查，报告“由于缺少make二进制文件而部分验证”，并在声明生产准备就绪之前请求用户确认。 #### 所需的验证循环 1.按照上述步骤生成Makefile 2. 运行验证器技能（如果不可用则进行回退检查） 3.修复所有错误（完成前必须有0个错误） 4. 应用格式修复（请参阅下面的“格式设置步骤”） 5. 在可行的情况下修复警告（应该修复；如果跳过则解释） 6. 大型/生产项目的地址信息项 7. 重新运行验证直至检查通过 8. 输出结构化验证报告（必需 - 参见下面的格式） #### 格式化步骤（必需）当 mbake 报告格式问题时，您必须： 1. **自动应用格式**（对于小问题首选）： mbake 格式 2. **解释为什么不应用**（如果格式化会破坏功能）：未应用格式，因为： - [具体原因，例如“heredoc 语法将被损坏”] - 建议手动审核：[特定行] 如果“mbake”未安装或不可执行，则跳过格式化程序执行并记录：“跳过格式化：当前环境中 mbake 不可用。” **格式化决策指南：** 姆贝克报告|行动 ---|--- “将重新格式化”，没有具体问题 |使用“mbake 格式”自动应用特定的空格/缩进问题 |使用“mbake 格式”自动应用复杂的heredocs或多行字符串中的问题|跳过格式化，在输出中解释 “#bake-format off”部分中的问题 |跳过（故意禁用） `mbake` 命令不可用 |跳过格式化，记录工具-不可用原因 **验证通过标准：** 水平|要求|行动 ---|---|--- **错误（需要 0 个）** |语法错误、缺少选项卡、无效目标 |必须在完成之前修复 **警告（如果可行，请修复）** |格式问题、缺少优化 |应该修复；解释是否跳过 **信息（生产地址）** |增强建议、风格偏好 |应该解决生产 Makefiles **已知的 mbake 误报（可以安全地忽略）：** mbake 验证器可能会报告有效 GNU Make 特殊目标的警告。这些是误报，可以忽略： mbake 警告 |实际状况 |说明 ---|---|--- “未知的特殊目标'.DELETE_ON_ERROR'”| ✅ 有效 |删除失败构建工件的关键 GNU Make 目标 “未知的特殊目标‘.SUFFIXES’” | ✅ 有效 |用于禁用/设置后缀规则的标准 GNU Make 目标 “未知的特殊目标‘.ONESHELL’” | ✅ 有效 |用于单 shell 配方执行的 GNU Make 3.82+ 功能 “未知的特殊目标'.POSIX'”| ✅ 有效 | POSIX 合规声明 #### 验证报告输出（必需）验证完成后，您必须按以下格式输出结构化报告。这不是可选的。 **所需报告格式：** ## 验证报告 **结果：** [通过/通过但有警告/失败] **错误：** [计数] **警告：** [计数] **信息：** [计数] ### 已修复错误 - [列出每个错误及其修复方法，如果有 0 个错误，则显示“无”] ### 警告已解决 - [列出已修复的每个警告] ### 跳过警告（有原因） - [列出每个未修复的警告并解释原因] - 示例：“mbake 将 '.DELETE_ON_ERROR' 报告为未知 - 这是有效的 GNU Make 特殊目标（误报）" ### 应用格式 - [是/否] - [如果否，请解释为什么跳过格式] ### 已解决的信息项 - [列出为生产 Makefile 处理的信息项] - [或“N/A - 简单项目”（如果不适用）] ### 剩余问题（如果有） - [列出任何需要用户注意的问题] - [或“无 - Makefile 已准备好用于生产”] **完整报告示例：** ## 验证报告 **结果：** 通过，但有警告 **错误：** 0 **警告：** 2 **信息：** 1 ### 已修复错误 - 无 ### 警告已解决 - 修正：添加了安装目标的错误处理（|| exit 1） ### 跳过警告（有原因） - mbake 将“.DELETE_ON_ERROR”报告为未知 - 这是有效且关键的 GNU Make 特殊目标可确保失败的构建不会留下损坏的文件。请参阅：https://www.gnu.org/software/make/manual/html_node/Special-Targets.html ### 应用格式 - 是 - 应用“mbake format”来修复空格问题 ### 已解决的信息项 - 为 Docker 目标添加了 .NOTPARALLEL（并行安全） - 添加了 docker-push 目标的错误处理 ### 剩余问题 - 无 - Makefile 已准备好用于生产 **要解决的常见信息项：** 信息项|何时修复 |如何修复 ---|---|--- “mkdir 没有仅订单先决条件”|大型项目（>10 个目标）|使用`目标：先决条件| $(BUILDDIR)` 模式 “配方命令缺乏错误处理”|关键操作（安装、部署）|在 .SHELLFLAGS 中添加 `set -e` 或使用 `&&` 链接 “考虑使用 ccache”|编译时间长 |添加 `CC := ccache $(CC)` 模式 “检测到并行敏感命令” | Docker/npm/pip 目标 |为受影响的目标或适当的依赖项添加“.NOTPARALLEL:” **生产质量要求（必须解决 Docker/部署目标）：** 使用 Docker 或部署目标生成 Makefile 时，必须应用以下生产模式： 1. **docker-push 的错误处理：** ## 将 Docker 镜像推送到注册表（带有错误处理） docker-push: docker-build @echo“推$(IMAGE)...” docker 推送 $(IMAGE) || { echo "推送 $(IMAGE) 失败"; 1号出口； } docker 推送 $(IMAGE_LATEST) || { echo "推送 $(IMAGE_LATEST) 失败"; 1号出口； } 2. **Docker 目标的并行安全性：** # 防止 Docker 目标并行执行（竞争条件） .NOTPARALLEL：docker-build docker-push docker-run 或者使用适当的依赖项来序列化： docker-push: docker-build # 确保构建在推送之前完成 docker-run: docker-build # 确保构建在运行前完成 3. **安装目标错误处理：** 安装：$(目标) 安装-d $(DESTDIR)$(PREFIX)/bin || 1号出口安装-m 755 $(TARGET) $(DESTDIR)$(PREFIX)/bin/ || 1号出口 **注意：** 当验证显示有关错误处理或并行安全性的信息项时，您必须为包含 Docker、部署或安装目标的任何 Makefile 处理它们。在您的回复中解释应用了哪些模式。 **验证清单：** * 语法正确（`make -n` 通过） * 所有非文件目标都有 .PHONY * 制表符缩进（不是空格） * 无硬编码凭证 * 用户可重写的变量使用 `?=` * .DELETE_ON_ERROR 存在 * 包括 MAKEFLAGS 优化（现代标头） * 构建目录（大型项目）的仅订购先决条件 * 关键配方中的错误处理（安装、部署、docker-push） ## 最佳实践 ### 变量 * `?=` 用于用户可覆盖（CC、CFLAGS、PREFIX） * `:=` 用于特定于项目的（源、对象） * 使用 pkg-config: `CFLAGS += $(shell pkg-config --cflags lib)` ### 目标 * 始终为非文件目标声明 `.PHONY` * 默认目标应该是`all` * 为了安全起见，使用`.DELETE_ON_ERROR` * 带有“##”注释的文档用于帮助目标 ### 目录创建创建构建目录的两种方法： **简单（内联 mkdir）：** $(BUILDDIR)/%.o: $(SRCDIR)/%.c @mkdir -p $(@D) $(CC) $(CFLAGS) -c $< -o $@ **优化（仅限订单先决条件）：** 当目录时间戳更改时防止不必要的重建。 $(构建目录): @mkdir -p $@ $(BUILDDIR)/%.o: $(SRCDIR)/%.c | $(构建目录) $(CC) $(CFLAGS) -c $< -o $@ 对于具有多个目标的大型项目，使用仅订单先决条件 (`|`)。 ### 食谱 * 使用制表符，不要使用空格 * 在 shell 中引用变量：`$(RM) "$(TARGET)"` * 使用“@”前缀来执行安静命令 * 首先使用 `make -n` 进行测试 ## 帮助脚本（可选）这些脚本是用于快速生成模板的**可选便利工具**。 ### 何时使用脚本与手动生成场景|推荐 ---|--- 简单、标准项目（单个二进制文件，无特殊功能）| ✅ 使用 `generate_makefile_template.sh` 来提高速度复杂项目（Docker、多二进制、自定义模式）| ❌ 使用手动生成进行完全控制将目标添加到现有 Makefile | ✅ 使用 `add_standard_targets.sh` 用户有特定的格式/样式要求 | ❌ 使用手动生成快速原型设计/概念验证| ✅ 使用脚本，稍后定制生产就绪的 Makefile | ⚠️ 从脚本开始，然后手动自定义 ### 生成_makefile_template.sh 为特定项目类型生成完整的 Makefile 模板。脚本路径：`scripts/generate_makefile_template.sh` bash 脚本/generate_makefile_template.sh [类型] [名称] [输出文件] 类型：c、c-lib、cpp、go、python、java、通用 **示例：** bash 脚本/generate_makefile_template.sh 转到 myservice # 使用 Go 模式、版本嵌入、标准目标创建 Makefile bash 脚本/generate_makefile_template.sh 转到 myservice build/Makefile # 将模板写入构建/Makefile（类型名称输出） ### add_standard_targets.sh 将缺少的标准 GNU 目标添加到现有 Makefile。脚本路径：`scripts/add_standard_targets.sh` bash 脚本/add_standard_targets.sh [MAKEFILE] [目标...] bash 脚本/add_standard_targets.sh [TARGETS...] # 使用 ./Makefile 目标：全部、安装、卸载、清理、distclean、测试、检查、帮助、dist **示例：** bash脚本/add_standard_targets.sh Makefile安装卸载帮助 # 添加安装、卸载、帮助目标（如果它们不存在） bash 脚本/add_standard_targets.sh 干净测试 # 显式目标模式：修改./Makefile bash 脚本/add_standard_targets.sh -n Makefile dist # 试运行模式：显示计划的更改，无需编辑文件 **注意：** 按照第 3 阶段模式进行手动生成会产生相同的结果，但允许更多自定义。 ### 辅助脚本回归冒烟测试修改帮助程序脚本或模板后运行： bash 测试/test_helper_scripts.sh ## 完成标准仅当满足以下所有检查时才认为任务完成： * 澄清了触发器匹配和缺失的要求（或应用了记录的默认值）。 * 相关内部文档在生成之前通过显式文件路径打开。 * 生成的 Makefile 对非文件目标具有完整的“.PHONY”覆盖。 * Go 模板包括可选的“go.sum”处理和可配置的“GO_MAIN”入口点。 * 使用“makefile-validator”（首选）或记录的后备检查运行验证。 * 格式化是通过“mbake”应用的，或者由于明确的工具不可用/兼容性原因而跳过。 * 最终回复包括所需的结构化验证报告。 ## 文档 `docs/` 中的详细指南： * **makefile-struct.md** \- 组织、布局、包括 * **variables-guide.md** \- 赋值运算符、自动变量 * **targets-guide.md** \- 标准目标、.PHONY、先决条件 * **patterns-guide.md** \- 模式规则、依赖关系 * **optimization-guide.md** \- 并行构建、缓存 * **security-guide.md** \- 安全扩展、凭证处理 ## 资源 * [GNU Make 手册]() * [GNU 编码标准]() * [Makefile 约定]()

生成文件生成器

包含技能