# builder **Repository Path**: agrui/builder ## Basic Information - **Project Name**: builder - **Description**: 一个基于 SCons 的项目编译系统，功能类似于 Android.mk 的编译系统，支持多种编译目标和复杂的依赖关系。 - **Primary Language**: Python - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-07-26 - **Last Updated**: 2025-08-30 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # SCons 构建系统 ## 项目概述 这是一个基于 SCons 的现代化 C/C++ 构建系统，提供了简洁的配置语法、自动依赖管理、多目标类型支持和美观的构建过程显示。该系统通过 Module 文件来定义构建目标，支持可执行文件、静态库、动态库等多种目标类型的构建。 ## 🌟 核心特性 ### 🚀 现代化构建体验 - **五阶段构建流程**：项目初始化 → Module扫描 → 依赖分析 → 构建执行 → 构建结果 - **美观的界面显示**：使用 Unicode 双线边框展示构建阶段 - **精确时间统计**：毫秒级构建时间统计，支持分.秒.毫秒格式显示 - **智能日志系统**：统一的日志输出，支持不同级别的信息显示 ### 🎯 灵活的目标管理 - **多种目标类型**：可执行文件、静态库、动态库、目标文件、预编译库 - **自动依赖解析**：智能分析目标间的依赖关系 - **传递依赖支持**：自动处理间接依赖关系 - **目标分组管理**：支持将相关目标组织成组 ### 📁 智能项目结构 - **自动Module扫描**：递归扫描项目中的所有 Module 文件 - **分层输出目录**：中间文件和最终发布文件分离管理 - **目标专用目录**：每个目标拥有独立的构建目录 - **自动库拷贝**：动态库和预编译库自动拷贝到发布目录 ### ⚙️ 丰富的配置选项 - **编译选项配置**：支持 C/C++ 编译标志、预处理宏定义 - **链接配置**：库搜索路径、链接库、链接标志 - **头文件管理**：包含路径、导出头文件路径 - **条件编译**：支持基于条件的编译配置 ### 🔧 预编译库支持 - **预编译静态库**：支持添加已编译的静态库文件 - **预编译动态库**：支持添加已编译的动态库文件 - **头文件导出**：预编译库可导出头文件路径供其他目标使用 - **自动依赖管理**：预编译库可作为其他目标的依赖 ## 项目架构 ``` builder/ ├── build.sh # 构建脚本入口 ├── build_tools/ # 构建系统核心 │ ├── SConstruct # SCons 主配置文件 │ ├── build_manager.py # 构建管理器 │ ├── target_registry.py # 目标注册表 │ ├── module_scanner.py # Module 文件扫描器 │ ├── module_helpers.py # Module 辅助函数 │ ├── default.py # 默认构建逻辑 │ └── option.py # 命令行选项处理 ├── examples/ # 示例项目 │ ├── hello_world/ # 简单可执行文件示例 │ ├── math_lib/ # 静态库示例 │ ├── calculator_app/ # 依赖库的可执行文件示例 │ ├── utils_lib/ # 动态库示例 │ ├── utils_demo/ # 使用动态库的示例 │ └── prebuilt_lib_test/ # 预编译库使用示例 ├── out/ # 构建输出目录 │ ├── intermediate/ # 中间文件 │ │ ├── bin/ # 可执行文件中间产物 │ │ ├── lib/ # 库文件中间产物 │ │ └── obj/ # 目标文件 │ └── release/ # 最终发布文件 ├── docs/ # 文档目录 │ ├── Home.md # 项目概述和特性介绍 │ ├── GetStarted.md # 快速开始和典型案例 │ └── Tutorials.md # 详细使用教程 └── README.md # 项目说明文档 ``` ## 核心组件说明 ### 1. 构建管理器 (BuildManager) 负责实际的编译过程和目标构建，主要功能包括： - 管理构建环境配置 - 处理目标间的依赖关系 - 执行具体的编译和链接操作 - 管理输出目录结构 - 处理动态库和预编译库的拷贝 ### 2. 目标注册表 (TargetRegistry) 管理所有编译目标的注册和查询，提供： - 目标注册和查询接口 - 依赖关系解析算法 - 目标分组管理 - 依赖关系验证 - 支持预编译库目标类型 ### 3. Module 扫描器 (ModuleScanner) 自动发现和解析项目中的 Module 文件： - 递归扫描项目目录 - 支持文件名模式匹配 - Module 文件有效性验证 - 提取 Module 基本信息 ### 4. Module 辅助函数 (module_helpers) 为 Module 文件提供便捷的配置接口： - `AddExecutable()` - 添加可执行文件目标 - `AddStaticLibrary()` - 添加静态库目标 - `AddSharedLibrary()` - 添加动态库目标 - `AddObjectFiles()` - 添加目标文件 - `AddPrebuiltStaticLibrary()` - 添加预编译静态库 - `AddPrebuiltSharedLibrary()` - 添加预编译动态库 ## 构建过程详解 ### 五阶段构建流程 1. **Phase1 - 项目初始化** - 设置构建环境 - 初始化目标注册表 - 配置构建选项 2. **Phase2 - Module扫描** - 递归扫描项目目录 - 发现所有 Module 文件 - 验证 Module 文件有效性 3. **Phase3 - 依赖分析** - 解析目标间依赖关系 - 构建依赖图 - 检测循环依赖 4. **Phase4 - 构建执行** - 按依赖顺序构建目标 - 编译源文件 - 链接生成最终产物 - 拷贝动态库到发布目录 5. **Phase5 - 构建结果** - 显示构建状态 - 统计构建时间 - 报告错误信息 ### 目录结构说明 - **中间文件目录** (`out/intermediate/`) - `bin/[target_name]/` - 可执行文件的中间产物 - `lib/[target_name]/` - 库文件的中间产物 - `obj/` - 目标文件 - **发布目录** (`out/release/`) - 存放最终的可执行文件 - 存放动态库文件（包括预编译动态库） - 静态库不会复制到此目录（编译时链接） ## 性能特点 ### 并行编译支持 - 支持多线程并行编译 - 自动检测系统CPU核心数 - 可手动指定编译线程数 ### 增量编译 - 自动检测文件变更 - 只重新编译修改过的文件 - 智能依赖关系更新 ### 构建缓存 - SCons 自动管理构建缓存 - 避免不必要的重复编译 - 提高构建效率 ## 扩展性 ### 自定义目标类型 - 支持添加新的目标类型 - 灵活的构建规则定义 - 可扩展的构建流程 ### 插件机制 - 支持自定义构建插件 - 可扩展的Module辅助函数 - 灵活的构建环境配置 --- **开始使用**：查看 [GetStarted.md](docs/Get%20Started.md) 了解如何快速开始使用本构建系统。 **详细教程**：查看 [Tutorials.md](docs/Tutorials.md) 了解详细的使用方法和高级功能。