更新履历

本文档为 Catboy™ 构建系统的更新履历。

本更新履历格式基于 如何维护更新日志， 版本号命名规则参考 语义化版本。

[v2.2.0] - 2025-10-23

新增

链接包装器语法

• 用于包围链接器标志的字符串前缀语法：优雅地用链接器标志包装库
  • whole:libname → --whole-archive -llibname --no-whole-archive
  • static:libname → -Bstatic -llibname -Bdynamic
  • group:[lib1,lib2,lib3] → --start-group -llib1 -llib2 -llib3 --end-group
  • needed:libname → --as-needed -llibname --no-as-needed
  • dynamic:libname → -Bdynamic -llibname（显式动态链接）
  • 涵盖所有包装器类型的 45+ 个测试用例的综合测试套件
  • doc/link-specification.md 中的完整文档
  • 向后兼容：简单库名称仍像以前一样工作
  • 与 Luna BSP 链接阶段集成

目标依赖系统

• 目标级别构建依赖：基于 DAG 的构建目标依赖解析
  • 在 YAML 中声明目标依赖的 depends_on 字段
  • 循环依赖检测，提供清晰的错误消息
  • 自动包含依赖的选择性构建
  • 与 @build: 路径展开系统集成
  • 涵盖简单和复杂依赖场景的综合测试套件
  • 支持带生成头文件的代码生成工作流

自定义配方系统

• 用户定义的构建过程：用于复杂构建工作流的灵活自定义配方系统
  • 在 YAML 中定义自定义多步骤构建过程
  • 步骤级别依赖和并行执行支持
  • 自定义步骤的环境变量支持
  • 每个步骤的工作目录规范
  • catboy builtin 命令显示内置平台和配方
  • 包含 14 个测试用例的综合测试套件
  • 支持打包、代码生成和多语言构建

构建系统特性

• 预构建和后构建步骤：在主构建之前和之后执行自定义命令
  • 独立步骤的并行执行支持
  • 预构建/后构建阶段内的步骤级别依赖
• 目标级别链接器标志：用于目标特定链接器选项的 linker_flags 字段
  • 覆盖/扩展平台链接器标志
  • 与链接包装器语法完全集成
• Luna BSP 符号控制：Luna BSP 配方的 include_symbols 选项
  • 可选的符号表生成控制
  • 如果未指定则默认为 true
• 试运行模式：构建命令的 --dry-run 标志
  • 预览构建操作而不执行
  • 对调试和验证有用
• 向后兼容性：废弃的 type 字段仍与新的 recipe 字段一起支持
  • 内部自动从 type 转换为 recipe
  • 代码注释中的清晰废弃说明

文档和工具

• macOS 通用二进制支持：为 Apple Silicon 和 Intel 构建通用二进制文件

增强

文档改进

• YAML 规范增强：大幅文档改进
  • 修复构建类型规范和别名
  • 更正高级源规范格式（映射语法）
  • 添加缺失的 C++ 源类型（cxx、c++）
  • 记录自动构建特性（包含、定义、标志）
  • 记录 Windows 平台检测行为
  • 更正 Luna BSP 构建过程描述（6 个步骤，而非 4 个阶段）
  • 记录最大包含深度限制（100 级）
  • 综合 IDE 集成文档
  • 完整的 YPP 命令文档
  • 增强配置验证规则
  • 目标依赖规范
  • 自定义配方文档
  • 链接包装器语法文档

路径展开系统

• 简化的路径展开：基于目录的目标发现
  • 更直观的目标解析
  • 更好的工作区集成
  • 增强的错误消息

变更

配方系统

• 字段重命名：build.type → build.recipe

  • 构建过程的更准确术语
  • 保持与 type 字段的完全向后兼容性
  • 所有内置类型现在称为"配方"
  • 支持用户自定义配方

• 配方名称：标准化为完整描述性名称

  • executable、static_linked_library、dynamic_linked_library、object_files、luna_bsp
  • 所有原始别名仍支持向后兼容
  • 内置配方和自定义配方之间的清晰区分

构建系统

• 自定义配方步骤：字段重命名以保持一致性

  • 在自定义配方步骤中将 dependencies 更改为 depends_on
  • 与目标级别依赖字段命名匹配
  • 相应更新所有测试用例

• Builtin 命令：转换为输出纯 YAML

  • 更好地与工具集成
  • 更容易解析和自动化

修复

文档修复

• 解决多个关键文档不一致问题
• 更正高级源规范格式
• 正确记录构建类型别名
• 记录自动构建特性
• 更正 shell 重定向的文件操作测试
• 使用适当引用增强错误消息

构建系统修复

• 改进自定义配方的错误消息
• 更好的依赖解析
• 测试套件更正和增强

[v2.1.8] - 2025-09-23

修复

• Windows 构建失败：针对 ERR_CHILD_PROCESS_STDIO_MAXBUFFER 错误的综合修复
  • 将响应文件支持从仅归档器扩展到编译器和归档器
  • 将命令行阈值从 6000 字符减少到 4000 字符，以获得更好的安全裕度
  • 防止在 Windows 上大型项目中发生的缓冲区溢出错误

新增

• 大输出缓冲区支持：通过适当的缓冲区管理改进命令执行
  • 实现 1MB 初始缓冲区容量，具有动态增长能力
  • 从 stdout/stderr 并发读取，具有适当的同步
  • 使用高效的 io.Copy 进行流式传输，而不是固定大小的块
  • 防止详细输出命令的 stdio 缓冲区溢出

增强

• 编译器响应文件：编译器命令的智能参数拆分
  • 在命令行中保留源文件和输出规范以便清晰
  • 将所有标志、包含和定义移至响应文件
  • 支持 GCC、G++、Clang 和 MSVC 编译器
  • 保持与现有构建配置的兼容性

技术

• 响应文件系统：编译器和归档器的统一方法
  • 基于命令行长度（>4000 字符）的自动检测
  • 创建具有适当内容的临时 .rsp 文件
  • 将反斜杠转换为正斜杠以支持 GNU 工具
  • 执行后自动清理临时文件
• 缓冲区管理：用自定义实现替换 cmd.CombinedOutput()
  • 基于 goroutine 的 I/O 的 runCommandWithLargeBuffer() 函数
  • 用于并发读取的适当通道同步
  • 应用于所有命令执行路径（正常、归档器、编译器）

测试

• 综合测试覆盖：为所有新功能添加测试
  • 响应文件阈值检测测试
  • 编译器和归档器识别测试
  • 命令行长度计算测试
  • Windows 特定激活测试

[v2.1.7] - 2025-09-14

修复

• Windows 命令行长度限制：在 Windows 上为归档器添加响应文件支持
  • 解决归档许多目标文件时的"文件名或扩展名太长"错误
  • 当命令行超过 6000 字符时自动使用响应文件（@file 语法）
  • 将 Windows 反斜杠转换为正斜杠以兼容 GNU 工具
  • 在 Windows 上启用构建大型项目，如 netx_duo（537 个源文件）
  • 透明实现 - 仅在 Windows 上需要时激活

技术

• 响应文件实现：pkg/step/executor.go 中的智能命令执行处理
  • 在 Windows 平台上检测归档器命令（ar）
  • 计算总参数长度以确定是否需要响应文件
  • 创建包含目标文件路径的临时响应文件
  • 拆分归档器参数：在命令行中保留标志和归档名称
  • 将目标文件列表以正斜杠路径放入响应文件
  • 使用 GNU ar 的 @file 语法引用响应文件
  • 执行后自动清理临时响应文件

文档

• 改进的文档：删除对未实现功能的引用
  • 清理对尚未实现的 v3 功能的引用
  • 确保文档准确反映当前 v2.1.7 功能

[v2.1.6] - 2025-09-10

新增

• 路径展开系统：YAML 配置中的高级跨目标和跨项目路径引用
  • 语法：@[{build|source}:][project.]target-name[@platform][/path] 用于灵活的路径规范
  • 跨目标引用：@source:lib/headers、@build:target-name
  • 跨项目引用：@source:external.target-name 用于工作区级别依赖
  • 上下文感知默认值：includes 部分默认为 @source:，library_dirs 默认为 @build:
  • 平台特定解析：@build:target@linux 用于目标平台构建
  • 路径后缀：@source:target/subfolder 用于细粒度路径控制
  • 工作区项目发现：多级项目层次扫描
  • 环境变量支持：YPP_PROJECT_PATH 用于自定义项目位置

增强

• YPP 集成：路径展开无缝集成到 YAML 预处理器管道
  • 所有路径引用在扁平化输出中自动扩展为绝对路径
  • IDE 友好的输出，具有具体路径以实现最佳工具集成
  • 保持与现有 $include 指令系统的兼容性
  • 适用于所有 YPP 命令：ypp、build、clean、config、compdb
  • 针对无效引用的综合错误处理和验证

技术

• 路径引用解析器：基于正则表达式的健壮解析，具有综合验证
  • 模式：^@(?:([^:@/]+):)?(?:([^.@/]+)\.)?([^@/]*?)(?:@([^@/]+))?(/.*)?$
  • 完全支持可选组件（类型、项目、目标、平台、后缀）
  • 跨工作区层次的项目发现，具有回退机制
  • 平台特定路径解析，具有自动原生平台检测
  • 与现有项目模型和构建系统架构集成

测试

• 综合测试套件：路径展开功能的完整覆盖
  • 15 个测试用例，涵盖所有语法变体和边缘情况
  • 具有跨项目依赖的多项目工作区场景
  • 上下文感知默认行为验证
  • 错误处理和验证测试
  • tests/ypp/path-expansion/ 下的有组织的测试结构

文档

• 增强的 YAML 规范：路径展开系统的广泛文档
  • 完整的语法参考，包含示例和最佳实践
  • 不同项目结构的集成模式
  • 跨项目依赖管理指南
  • 最佳开发体验的 IDE 集成建议

[v2.1.5] - 2025-09-09

修复

• 符号生成器：修复 Luna BSP 符号表生成中的关键错误
  • 更正符号排序以完全匹配 C# 实现
  • 修复地址和偏移部分以使用排序的符号顺序
  • 修复名称部分以使用原始解析顺序（按照 C# 行为）
  • 符号生成器现在生成完整输出（C# 版本在 344KB 处被截断）
  • Luna BSP 构建现在具有正确格式的符号表用于内核调试

技术

• 符号表架构：增强 pkg/util/symbol_generator.go 中的符号生成逻辑
  • 添加具有适当部分排序的 generateSymbolAssemblyFromSorted() 函数
  • 在解析阶段实现名称部分预构建（匹配 C# 方法）
  • 修复偏移计算以对应排序的地址顺序
  • 改进双重排序（排序 vs 原始）的符号条目处理
  • 增强汇编输出格式以实现更好的兼容性

[v2.1.4] - 2025-09-02

增强

• 错误输出格式：大幅改进构建错误报告以提供更好的开发者体验

  • 直接编译器输出，无包装器消息（像原生工具链一样显示 gcc 错误）
  • Java 风格的错误回溯，具有清晰的缩进和结构化层次
  • 在编译器输出和错误回溯之间添加分隔线以便清晰
  • 智能错误展开在"退出状态"消息处停止以避免冗余
  • 维护完整的错误链：目标 → 阶段 → 工作器 → 步骤 → 命令

• 多错误支持：针对并行编译失败的综合错误报告

  • 显示并行构建中的所有编译错误（不仅仅是第一个）
  • 每个错误编号为 [1]、[2] 等，带有单独的回溯
  • 在错误后继续处理以收集所有失败
  • 清楚指示总错误数

• 冗余消除：智能错误消息去重

  • 检测并跳过冗余的工作器/步骤错误消息
  • 在减少噪音的同时保持适当的缩进层次
  • 清洁的错误链，无重复信息

开发者体验

• 专业错误显示：构建失败现在显示清洁、可读的错误输出
  • 编译器错误完全按照开发者期望显示（像 make/gcc）
  • 不同类型错误信息之间的清晰视觉分离
  • 结构化回溯使快速识别失败点成为可能
  • 在保持完整调试上下文的同时减少噪音
  • 适当的缩进，错误编号正确对齐

技术

• 错误处理架构：增强错误传播和格式化
  • 更新 executeCommand() 以通过 fmt.Print() 显示直接编译器输出
  • 添加具有 Java 风格缩进的 printErrorBacktrace() 函数
  • 改进错误展开逻辑，具有冗余防止
  • 增强项目构建器错误处理，具有视觉分隔符
  • 添加 MultiError 类型以收集并行编译错误
  • 使用 isRedundantError() 函数进行智能冗余检测

[v2.1.3] - 2025-09-02

新增

• 自定义构件命名：可选的 artifact 属性以覆盖默认构建构件名称
  • 自定义可执行文件名称（例如，artifact: my-custom-app）
  • 自定义库名称（例如，artifact: libcustom.a）
  • 在需要时自动应用平台特定扩展名
  • 与默认命名方案的完全向后兼容性

增强

• 工具系统架构：在源构建器和构建工具之间进行适当分离的重大改进

  • 源编译器的 source_type：源构建工具指定支持的源类型（c、cpp、asm、dts）
  • 构建工具的 tool_type：构建实用程序指定工具类型（archiver、linker、objcopy、objdump、nm、size、strip）
  • 互斥性：工具必须指定 source_type 或 tool_type，但不能同时指定两者
  • 使用 Platform.GetToolBySourceType() 和 Platform.GetToolByType() 方法进行智能工具查找
  • 运行时工具发现，仅在实际需要工具时才出错

• 平台选择智能：通过 YPP 集成改进平台选择逻辑

  • 仅在 YAML 中未指定平台时使用内置原生平台
  • 用户定义的平台在存在时具有完全优先权
  • 对包含的平台文件进行适当的 YPP 处理的 YAML 集成
  • 原生构建和交叉编译构建之间的清晰分离
  • 修复了原生平台干扰 aarch64 交叉编译的 Luna BSP 构建

变更

• 项目字段重命名：配置文件现在使用 project: 而不是 name: 以更好地识别命名空间
  • 改进的项目命名空间系统兼容性
  • 更好的跨项目依赖解析
  • 所有示例和文档已更新

修复

• 工具系统验证：更正所有文档示例以使用适当的 source_type/tool_type 语法
• 平台选择错误：修复 catboy 未正确使用 YPP 处理的 YAML 进行平台选择的问题
• 交叉编译可靠性：消除在不兼容平台上的失败构建尝试

技术

• 增强的类型系统：使用适当的工具类型分离和构件支持更新结构
• GetOutputFileName 逻辑：改进的构件命名逻辑，具有自定义名称覆盖支持
• 测试覆盖：用于构件属性和工具系统增强的综合测试套件
• 文档同步：所有文档已更新以反映当前实现

[v2.1.2] - 2025-08-28

新增

• YPP 命令：用于构建分析和 IDE 集成的 YAML 预处理器命令
  • catboy ypp 命令以扁平化 YAML 配置并生成目标元数据
  • 将所有 $include 指令递归展开到 build/flattened.yaml
  • 生成包含 IDE 工具的综合目标元数据的 build/flattened.json
  • 支持 -f 标志以指定自定义构建文件（默认为 build.yaml）
  • 跟踪目标定义的源位置，包括包含的文件
  • 提供目标名称、类型、绝对文件路径和行号信息

增强

• 目标位置跟踪：用于 IDE 集成的高级元数据收集
  • 扫描主构建文件和包含的文件以获取目标定义
  • 在任何 YAML 层次级别检测目标（根级和嵌套）
  • 支持常见的包含目录模式（targets/、configs/、platforms/）
  • 用于调试和 IDE 导航的准确行号跟踪
  • 综合错误处理和验证

技术

• YPP 元数据系统：具有位置跟踪的复杂 YAML 处理
  • ProcessorWithMetadata 用于跟踪文件处理和目标位置
  • 具有关键字过滤的增强目标检测算法
  • 用于跨平台兼容性的绝对路径解析
  • 与现有 YPP 包含指令系统集成

[v2.1.1] - 2025-08-27

变更

• IDE 集成优化：更新 VS Code + clangd 的 compile_commands.json 放置
  • 将默认位置从 build/compile_commands.json 更改为项目根目录 compile_commands.json
  • 针对 VS Code 和 clangd 扩展自动发现进行优化
  • 仍通过 -o 标志支持自定义输出位置
  • 改进所有基于 clang 的工具的 IDE 集成可靠性

[v2.1.0] - 2025-08-27

新增

• YAML 包含指令系统：综合模块化配置支持

  • 通用放置：$include 指令在 YAML 层次的任何级别都有效
  • 多种包含类型：单个文件、文件数组、glob 模式
  • 高级功能：嵌套包含、带混合内容的数组包含
  • 循环依赖检测和防止，带清晰的错误消息
  • 跨平台路径解析，具有相对/绝对路径支持
  • 快速路径优化：对无包含的文件无性能影响

• IDE 集成：自动生成 clang compile_commands.json

  • 在 build 和 rebuild 命令期间自动生成
  • 仅用于编译数据库的独立 catboy compdb 命令
  • VS Code + clangd 优化：默认情况下文件放置在项目根目录
  • --no-compdb 标志在需要时禁用生成
  • 通过 -o 标志支持自定义输出位置
  • 完全符合 clang JSON 编译数据库规范

增强

• 文档套件：完整的阶段 6 文档实现
  • 向 yaml-specification.md 添加综合 YAML 包含指令系统部分
  • 使用详细的模块化配置指南和实际示例增强 users.md
  • 使用阶段 6 完成状态更新实现文档
  • 添加具有函数级注释的综合代码文档
  • 包含故障排除指南和包含使用的最佳实践

技术

• 合并语义：复杂的 YAML 结构合并
  • 映射：具有覆盖语义的深度递归合并
  • 数组：连接（将包含的数组附加到基础数组）
  • 标量：包含的值替换基础值
  • 类型冲突：包含的内容类型优于基础内容类型
• 性能：O(1) 包含检测，O(V + E) 处理复杂度
• 错误处理：具有文件上下文和包含链的描述性错误消息

[v2.0.12] - 2025-08-26

新增

• 目标规范支持：所有 CLI 命令现在支持选择性目标规范
  • catboy build [targets...] - 仅构建指定的目标
  • catboy clean [targets...] - 仅清理指定的目标构件
  • catboy rebuild [targets...] - 仅重建指定的目标
  • 多目标支持：可以在单个命令中指定多个目标
  • 目标验证：命令在继续之前验证目标存在
  • 向后兼容性：不带目标参数时命令完全按照以前的方式工作

修复

• Luna BSP DTB 依赖解析：修复设备树 blob（DTB）目标特定路径
  • 汇编文件现在通过预处理器条件使用目标特定的 DTB 路径
  • 向所有编译添加自动 CONFIG_TARGET_<TARGETNAME> 定义
  • DTB 编译现在在依赖它的汇编文件之前发生
  • 修复目标选择逻辑以正确处理命令行目标参数

增强

• CLI 一致性：所有构建相关命令使用一致的 [targets...] 语法
• 帮助文档：更新所有命令的使用字符串和帮助文本
• 错误处理：不存在的目标的清晰错误消息
• 开发工作流：通过选择性操作加快开发周期

[v2.0.11] - 2025-08-26

修复

• 关键 glob 模式匹配错误：修复 ** 模式的递归 glob 模式匹配
  • 模式 arch/**/*.c 现在正确匹配像 arch/aarch64/common.c 这样的文件
  • 简单文件名模式（如 *.c）现在与相对路径的 filepath.Base() 匹配
  • 路径模式（如 dir/*.c）仍与完整相对路径匹配
  • Luna 内核构建现在找到所有 40+ 个源文件（7 个汇编 + 33+ 个 C 文件）
  • 通过适当的源发现将构建时间改进到约 340ms

文档

• 使用 v2.0.11 glob 模式错误修复详细信息更新 README.md
• 将 HTML 文档文件移至 doc 目录以更好地组织

[v2.0.10] - 2025-08-26

修复

• 汇编文件发现错误：修复 Luna BSP 构建中的关键源文件发现问题
  • Go 的 filepath.Glob() 回退逻辑对递归模式不完整
  • 模式 arch/**/*.S 现在正确找到子目录中的所有汇编文件
  • 所有 7 个汇编文件现在正确发现和编译
  • 完成 arch_spin_lock、set_bit、clear_bit 等的符号解析
• 重建命令路径解析：修复清理后重建命令失败的问题
  • 配置文件路径现在在操作前解析为绝对路径
  • 在工作目录更改时保留文件路径

文档

• 更新 v2.0.10 重建命令修复的文档
• 添加综合 Luna BSP 支持文档

[v2.0.9] - 2025-08-19

新增

• 完整的 Luna BSP 目标支持：匹配 C# 实现的完整 4 阶段构建过程
  • 设备树编译：使用 dtc 工具集成的 .dts 到 .dtb 编译
  • 符号表生成：将 C# 符号生成算法移植到 Go
  • 多阶段 DAG 集成：Luna 步骤正确集成到基于步骤的架构
  • 跨平台 BSP 构建：使用 aarch64-luna-elf 工具链的 ARM64 交叉编译

修复

• Luna BSP 构建：YAML glob 展开和对象路径
• 更新 Luna 构建配置

[v2.0.8] - 2025-08-22

文档

• 添加自定义步骤设计文档

[v2.0.7] - 2025-07-27

修复

• 删除重复的打印语句

[v2.0.6] - 2025-07-26

新增

• 构建时间测量和显示
• 命令帮助系统

[v2.0.5] - 2025-07-23

新增

• 单目标 TUI 高度调整

[v2.0.4] - 2025-07-23

修复

• 内存管理改进
• 多目标 TUI 上的回车键处理
• 添加适当的行插入格式

[v2.0.3] - 2025-07-23

新增

• 多目标 TUI 支持：专业的基于树的配置界面
  • 带视觉指示器的可展开目标文件夹（▼📂 / ▶📁）
  • 跨平台键盘导航（方向键 + vim 风格的 hjkl）
  • 带基于状态的图标的动态视觉反馈

[v2.0.2] - 2025-07-22

新增

• 完整的 V2 实现：KConfig 风格的配置系统
  • 类似 Linux 内核的配置管理
  • 基于 DAG 的依赖解析，重用构建步骤架构
  • 配置持久化，从 build/{target}/build.conf 自动保存/加载
  • 专业的 TUI 界面，具有类似 menuconfig 的导航
  • 带宏定义的自动 C 头文件生成
  • 带自动包含路径的无缝构建集成

变更

• 更新 git 忽略模式

[v2.0.1] - 2025-07-22

文档

• 添加综合 V2 和 V3 规划文档
• 记录 KConfig 风格的配置系统架构
• 添加 TUI 界面设计规范

[v2.0.0] - 2025-07-20

新增

• 初始 Golang 实现：在 Go 中完全重写 Catboy 构建系统
  • 基于步骤的 DAG 架构，具有数学死锁防止
  • 拓扑排序执行，具有基于阶段的并行性
  • 跨平台支持（Linux、macOS、Windows）
  • 原生平台检测，具有自动工具链选择
• 核心构建特性：
  • 具有最佳并行性的多线程构建
  • 单线程构建（-j 1 标志）
  • 清理和重建命令
  • 详细输出，具有 Makefile 风格的命令显示
  • 带 CATBOY_DEBUG_ENABLE 环境变量的调试模式
• 构建系统架构：
  • 用于所有操作的统一 BuildStep 接口
  • 带循环检测的 DependencyGraph
  • 带基于阶段的执行的 BuildEngine
  • 支持编译、链接、归档和自定义步骤
• 项目配置：
  • 基于 YAML 的构建配置
  • 平台特定的工具链设置
  • 目标级别的构建配置
  • 文件级别的编译标志覆盖
• 输出类型：
  • 可执行文件
  • 共享库
  • 静态库
  • 对象文件
• 性能：
  • Luna 内核（40 个文件）在 279ms 内构建
  • 原生测试项目（6 个文件）在 87ms 内构建
  • 带数学保证的零死锁

技术细节

• 使用 Go 模块进行依赖管理
• 使用 YAML 解析进行配置
• 实现 Kahn 算法进行拓扑排序
• 带基于阶段的并行性的并发执行
• 跨平台文件路径处理
• 综合错误处理和报告