1# RT-Thread Next Generation Build System
2
3## 概述
4
5RT-Thread NG（Next Generation）构建系统是对现有构建系统的面向对象重构，在保持完全向后兼容的同时，提供了更清晰的架构和更强的可扩展性。
6
7## 特性
8
9- ✅ **完全向后兼容**：现有的SConscript无需修改
10- ✅ **面向对象设计**：清晰的类层次结构和职责分离
11- ✅ **SCons最佳实践**：充分利用SCons的Environment对象
12- ✅ **可扩展架构**：易于添加新的工具链和项目生成器
13- ✅ **类型安全**：更好的类型提示和错误处理
14
15## 架构设计
16
17### 核心模块
18
19```
20ng/
21├── __init__.py          # 包初始化
22├── core.py              # 核心类：BuildContext
23├── environment.py       # 环境扩展：RTEnv类，注入到SCons Environment
24├── config.py            # 配置管理：解析rtconfig.h
25├── project.py           # 项目管理：ProjectGroup和Registry
26├── toolchain.py         # 工具链抽象：GCC、Keil、IAR等
27├── generator.py         # 项目生成器：VS Code、CMake等
28├── utils.py             # 工具函数：路径、版本等
29├── adapter.py           # 适配器：与building.py集成
30└── building_ng.py       # 示例：最小化修改的building.py
31```
32
33### 类图
34
35```mermaid
36classDiagram
37    class BuildContext {
38        +root_directory: str
39        +config_manager: ConfigManager
40        +project_registry: ProjectRegistry
41        +toolchain_manager: ToolchainManager
42        +prepare_environment(env)
43        +get_dependency(depend): bool
44    }
45
46    class ConfigManager {
47        +load_from_file(filepath)
48        +get_dependency(depend): bool
49        +get_option(name): ConfigOption
50    }
51
52    class ProjectGroup {
53        +name: str
54        +sources: List[str]
55        +dependencies: List[str]
56        +build(env): List[Object]
57    }
58
59    class Toolchain {
60        <<abstract>>
61        +get_name(): str
62        +detect(): bool
63        +configure_environment(env)
64    }
65
66    class ProjectGenerator {
67        <<abstract>>
68        +generate(context, info): bool
69        +clean(): bool
70    }
71
72    BuildContext --> ConfigManager
73    BuildContext --> ProjectRegistry
74    BuildContext --> ToolchainManager
75    ProjectRegistry --> ProjectGroup
76    ToolchainManager --> Toolchain
77```
78
79## 使用方法
80
81### 1. 最小化集成（推荐）
82
83在building.py中添加少量代码即可集成新系统：
84
85```python
86# 在building.py的开头添加
87try:
88    from ng.adapter import (
89        init_build_context,
90        inject_environment_methods,
91        load_rtconfig as ng_load_rtconfig
92    )
93    USE_NG = True
94except ImportError:
95    USE_NG = False
96
97# 在PrepareBuilding函数中添加
98def PrepareBuilding(env, root_directory, has_libcpu=False, remove_components=[]):
99    # ... 原有代码 ...
100
101    # 集成新系统
102    if USE_NG:
103        context = init_build_context(root_directory)
104        inject_environment_methods(env)
105        ng_load_rtconfig('rtconfig.h')
106
107    # ... 继续原有代码 ...
108```
109
110### 2. 使用新的环境方法
111
112集成后，SCons Environment对象会自动获得新方法：
113
114```python
115# 在SConscript中使用新方法
116Import('env')
117
118# 使用环境方法（推荐）
119src = env.GlobFiles('*.c')
120group = env.DefineGroup('MyComponent', src, depend=['RT_USING_XXX'])
121
122# 也可以使用传统方式（保持兼容）
123from building import *
124group = DefineGroup('MyComponent', src, depend=['RT_USING_XXX'])
125```
126
127### 3. 新的项目生成器
128
129新系统提供了改进的项目生成器：
130
131```bash
132# 生成VS Code项目
133scons --target=vscode
134
135# 生成CMake项目
136scons --target=cmake
137```
138
139## API参考
140
141### 环境方法
142
143所有方法都被注入到SCons Environment对象中：
144
145#### env.DefineGroup(name, src, depend, **kwargs)
146定义一个组件组。
147
148**参数：**
149- `name`: 组名称
150- `src`: 源文件列表
151- `depend`: 依赖条件（字符串或列表）
152- `**kwargs`: 额外参数
153  - `CPPPATH`: 头文件路径
154  - `CPPDEFINES`: 宏定义
155  - `CFLAGS`/`CXXFLAGS`: 编译选项
156  - `LOCAL_CFLAGS`/`LOCAL_CPPPATH`: 仅对当前组有效的选项
157  - `LIBS`/`LIBPATH`: 库配置
158
159**返回：** 构建对象列表
160
161**示例：**
162```python
163src = ['driver.c', 'hal.c']
164group = env.DefineGroup('Driver',
165    src,
166    depend=['RT_USING_DEVICE'],
167    CPPPATH=[env.GetCurrentDir()],
168    LOCAL_CFLAGS='-O3'
169)
170```
171
172#### env.GetDepend(depend)
173检查依赖是否满足。
174
175**参数：**
176- `depend`: 依赖名称或列表
177
178**返回：** True如果依赖满足
179
180**示例：**
181```python
182if env.GetDepend('RT_USING_SERIAL'):
183    src += ['serial.c']
184
185if env.GetDepend(['RT_USING_SERIAL', 'RT_SERIAL_USING_DMA']):
186    src += ['serial_dma.c']
187```
188
189#### env.SrcRemove(src, remove)
190从源文件列表中移除文件。
191
192**参数：**
193- `src`: 源文件列表（就地修改）
194- `remove`: 要移除的文件
195
196**示例：**
197```python
198src = env.GlobFiles('*.c')
199env.SrcRemove(src, ['test.c', 'debug.c'])
200```
201
202#### env.BuildPackage(package_path)
203从package.json构建软件包。
204
205**参数：**
206- `package_path`: package.json路径
207
208**返回：** 构建对象列表
209
210**示例：**
211```python
212objs = env.BuildPackage('package.json')
213```
214
215#### env.GetContext()
216获取当前构建上下文。
217
218**返回：** BuildContext实例
219
220**示例：**
221```python
222context = env.GetContext()
223if context:
224    context.logger.info("Building component...")
225```
226
227## 高级特性
228
229### 1. 自定义工具链
230
231创建自定义工具链：
232
233```python
234from ng.toolchain import Toolchain
235
236class MyToolchain(Toolchain):
237    def get_name(self):
238        return "mycc"
239
240    def detect(self):
241        # 检测工具链
242        return shutil.which("mycc") is not None
243
244    def configure_environment(self, env):
245        env['CC'] = 'mycc'
246        env['CFLAGS'] = '-O2 -Wall'
247
248# 注册工具链
249context = env.GetContext()
250context.toolchain_manager.register_toolchain('mycc', MyToolchain())
251```
252
253### 2. 自定义项目生成器
254
255创建自定义项目生成器：
256
257```python
258from ng.generator import ProjectGenerator
259
260class MyGenerator(ProjectGenerator):
261    def get_name(self):
262        return "myide"
263
264    def generate(self, context, project_info):
265        # 生成项目文件
266        self._ensure_output_dir()
267        # ... 生成逻辑 ...
268        return True
269
270# 注册生成器
271context.generator_registry.register('myide', MyGenerator)
272```
273
274### 3. 构建钩子
275
276使用构建上下文添加钩子：
277
278```python
279context = env.GetContext()
280
281# 添加日志
282context.logger.info("Starting build...")
283
284# 访问配置
285if context.config_manager.get_option('RT_THREAD_PRIORITY_MAX'):
286    print("Max priority:", context.config_manager.get_value('RT_THREAD_PRIORITY_MAX'))
287
288# 获取项目信息
289info = context.project_registry.get_project_info()
290print(f"Total sources: {len(info['all_sources'])}")
291```
292
293## 迁移指南
294
295### 从旧版本迁移
296
2971. **无需修改**：现有的SConscript文件无需任何修改即可工作
2982. **可选升级**：可以逐步将`DefineGroup`调用改为`env.DefineGroup`
2993. **新功能**：可以开始使用新的特性如`env.BuildPackage`
300
301### 最佳实践
302
3031. **使用环境方法**：优先使用`env.DefineGroup`而不是全局函数
3042. **类型提示**：在Python 3.5+中使用类型提示
3053. **错误处理**：使用context.logger记录错误和警告
3064. **路径处理**：使用PathService处理跨平台路径
307
308## 性能优化
309
310新系统包含多项性能优化：
311
3121. **配置缓存**：依赖检查结果会被缓存
3132. **延迟加载**：工具链和生成器按需加载
3143. **并行支持**：项目生成可以并行执行
315
316## 测试
317
318运行测试套件：
319
320```bash
321cd tools/ng
322python -m pytest tests/
323```
324
325## 贡献
326
327欢迎贡献代码！请遵循以下准则：
328
3291. 保持向后兼容性
3302. 添加类型提示
3313. 编写单元测试
3324. 更新文档
333
334## 路线图
335
336- [ ] 完整的测试覆盖
337- [ ] 性能基准测试
338- [ ] 插件系统
339- [ ] 更多项目生成器（Eclipse、Qt Creator等）
340- [ ] 构建缓存系统
341- [ ] 分布式构建支持
342
343## 许可证
344
345本项目遵循RT-Thread的Apache License 2.0许可证。