path: root/tools/ng/README.md

# RT-Thread Next Generation Build System

## 概述

RT-Thread NG（Next Generation）构建系统是对现有构建系统的面向对象重构，在保持完全向后兼容的同时，提供了更清晰的架构和更强的可扩展性。

## 特性

- ✅ **完全向后兼容**：现有的SConscript无需修改
- ✅ **面向对象设计**：清晰的类层次结构和职责分离
- ✅ **SCons最佳实践**：充分利用SCons的Environment对象
- ✅ **可扩展架构**：易于添加新的工具链和项目生成器
- ✅ **类型安全**：更好的类型提示和错误处理

## 架构设计

### 核心模块

```
ng/
├── __init__.py          # 包初始化
├── core.py              # 核心类：BuildContext
├── environment.py       # 环境扩展：RTEnv类，注入到SCons Environment
├── config.py            # 配置管理：解析rtconfig.h
├── project.py           # 项目管理：ProjectGroup和Registry
├── toolchain.py         # 工具链抽象：GCC、Keil、IAR等
├── generator.py         # 项目生成器：VS Code、CMake等
├── utils.py             # 工具函数：路径、版本等
├── adapter.py           # 适配器：与building.py集成
└── building_ng.py       # 示例：最小化修改的building.py
```

### 类图

```mermaid
classDiagram
    class BuildContext {
        +root_directory: str
        +config_manager: ConfigManager
        +project_registry: ProjectRegistry
        +toolchain_manager: ToolchainManager
        +prepare_environment(env)
        +get_dependency(depend): bool
    }
    
    class ConfigManager {
        +load_from_file(filepath)
        +get_dependency(depend): bool
        +get_option(name): ConfigOption
    }
    
    class ProjectGroup {
        +name: str
        +sources: List[str]
        +dependencies: List[str]
        +build(env): List[Object]
    }
    
    class Toolchain {
        <<abstract>>
        +get_name(): str
        +detect(): bool
        +configure_environment(env)
    }
    
    class ProjectGenerator {
        <<abstract>>
        +generate(context, info): bool
        +clean(): bool
    }
    
    BuildContext --> ConfigManager
    BuildContext --> ProjectRegistry
    BuildContext --> ToolchainManager
    ProjectRegistry --> ProjectGroup
    ToolchainManager --> Toolchain
```

## 使用方法

### 1. 最小化集成（推荐）

在building.py中添加少量代码即可集成新系统：

```python
# 在building.py的开头添加
try:
    from ng.adapter import (
        init_build_context,
        inject_environment_methods,
        load_rtconfig as ng_load_rtconfig
    )
    USE_NG = True
except ImportError:
    USE_NG = False

# 在PrepareBuilding函数中添加
def PrepareBuilding(env, root_directory, has_libcpu=False, remove_components=[]):
    # ... 原有代码 ...
    
    # 集成新系统
    if USE_NG:
        context = init_build_context(root_directory)
        inject_environment_methods(env)
        ng_load_rtconfig('rtconfig.h')
    
    # ... 继续原有代码 ...
```

### 2. 使用新的环境方法

集成后，SCons Environment对象会自动获得新方法：

```python
# 在SConscript中使用新方法
Import('env')

# 使用环境方法（推荐）
src = env.GlobFiles('*.c')
group = env.DefineGroup('MyComponent', src, depend=['RT_USING_XXX'])

# 也可以使用传统方式（保持兼容）
from building import *
group = DefineGroup('MyComponent', src, depend=['RT_USING_XXX'])
```

### 3. 新的项目生成器

新系统提供了改进的项目生成器：

```bash
# 生成VS Code项目
scons --target=vscode

# 生成CMake项目
scons --target=cmake
```

## API参考

### 环境方法

所有方法都被注入到SCons Environment对象中：

#### env.DefineGroup(name, src, depend, **kwargs)
定义一个组件组。

**参数：**
- `name`: 组名称
- `src`: 源文件列表
- `depend`: 依赖条件（字符串或列表）
- `**kwargs`: 额外参数
  - `CPPPATH`: 头文件路径
  - `CPPDEFINES`: 宏定义
  - `CFLAGS`/`CXXFLAGS`: 编译选项
  - `LOCAL_CFLAGS`/`LOCAL_CPPPATH`: 仅对当前组有效的选项
  - `LIBS`/`LIBPATH`: 库配置

**返回：** 构建对象列表

**示例：**
```python
src = ['driver.c', 'hal.c']
group = env.DefineGroup('Driver', 
    src, 
    depend=['RT_USING_DEVICE'],
    CPPPATH=[env.GetCurrentDir()],
    LOCAL_CFLAGS='-O3'
)
```

#### env.GetDepend(depend)
检查依赖是否满足。

**参数：**
- `depend`: 依赖名称或列表

**返回：** True如果依赖满足

**示例：**
```python
if env.GetDepend('RT_USING_SERIAL'):
    src += ['serial.c']

if env.GetDepend(['RT_USING_SERIAL', 'RT_SERIAL_USING_DMA']):
    src += ['serial_dma.c']
```

#### env.SrcRemove(src, remove)
从源文件列表中移除文件。

**参数：**
- `src`: 源文件列表（就地修改）
- `remove`: 要移除的文件

**示例：**
```python
src = env.GlobFiles('*.c')
env.SrcRemove(src, ['test.c', 'debug.c'])
```

#### env.BuildPackage(package_path)
从package.json构建软件包。

**参数：**
- `package_path`: package.json路径

**返回：** 构建对象列表

**示例：**
```python
objs = env.BuildPackage('package.json')
```

#### env.GetContext()
获取当前构建上下文。

**返回：** BuildContext实例

**示例：**
```python
context = env.GetContext()
if context:
    context.logger.info("Building component...")
```

## 高级特性

### 1. 自定义工具链

创建自定义工具链：

```python
from ng.toolchain import Toolchain

class MyToolchain(Toolchain):
    def get_name(self):
        return "mycc"
        
    def detect(self):
        # 检测工具链
        return shutil.which("mycc") is not None
        
    def configure_environment(self, env):
        env['CC'] = 'mycc'
        env['CFLAGS'] = '-O2 -Wall'
        
# 注册工具链
context = env.GetContext()
context.toolchain_manager.register_toolchain('mycc', MyToolchain())
```

### 2. 自定义项目生成器

创建自定义项目生成器：

```python
from ng.generator import ProjectGenerator

class MyGenerator(ProjectGenerator):
    def get_name(self):
        return "myide"
        
    def generate(self, context, project_info):
        # 生成项目文件
        self._ensure_output_dir()
        # ... 生成逻辑 ...
        return True
        
# 注册生成器
context.generator_registry.register('myide', MyGenerator)
```

### 3. 构建钩子

使用构建上下文添加钩子：

```python
context = env.GetContext()

# 添加日志
context.logger.info("Starting build...")

# 访问配置
if context.config_manager.get_option('RT_THREAD_PRIORITY_MAX'):
    print("Max priority:", context.config_manager.get_value('RT_THREAD_PRIORITY_MAX'))

# 获取项目信息
info = context.project_registry.get_project_info()
print(f"Total sources: {len(info['all_sources'])}")
```

## 迁移指南

### 从旧版本迁移

1. **无需修改**：现有的SConscript文件无需任何修改即可工作
2. **可选升级**：可以逐步将`DefineGroup`调用改为`env.DefineGroup`
3. **新功能**：可以开始使用新的特性如`env.BuildPackage`

### 最佳实践

1. **使用环境方法**：优先使用`env.DefineGroup`而不是全局函数
2. **类型提示**：在Python 3.5+中使用类型提示
3. **错误处理**：使用context.logger记录错误和警告
4. **路径处理**：使用PathService处理跨平台路径

## 性能优化

新系统包含多项性能优化：

1. **配置缓存**：依赖检查结果会被缓存
2. **延迟加载**：工具链和生成器按需加载
3. **并行支持**：项目生成可以并行执行

## 测试

运行测试套件：

```bash
cd tools/ng
python -m pytest tests/
```

## 贡献

欢迎贡献代码！请遵循以下准则：

1. 保持向后兼容性
2. 添加类型提示
3. 编写单元测试
4. 更新文档

## 路线图

- [ ] 完整的测试覆盖
- [ ] 性能基准测试
- [ ] 插件系统
- [ ] 更多项目生成器（Eclipse、Qt Creator等）
- [ ] 构建缓存系统
- [ ] 分布式构建支持

## 许可证

本项目遵循RT-Thread的Apache License 2.0许可证。