Skip to main content

Crate gaia_types

Crate gaia_types 

Source
Expand description

§gaia-types 维护文档

§项目概述

gaia-types 是 Gaia 项目的核心类型系统库，提供统一的错误处理、架构抽象、编译目标定义等基础功能。作为整个工具链的基础组件，该库采用零依赖设计，确保稳定性和可移植性。

§架构设计

§核心设计原则

  • 零依赖核心: 核心功能不依赖外部 crate，确保最小化依赖树
  • 统一错误模型: 提供一致的错误处理接口，支持详细的错误诊断信息
  • 架构抽象: 支持多架构的统一抽象，便于跨平台开发
  • 类型安全: 利用 Rust 类型系统防止常见编程错误
  • 性能优先: 关键路径零分配，栈上数据结构优先

§技术栈

  • 语言: Rust (Edition 2024)
  • 特性: 使用 #![feature(try_trait_v2)] 提供高级错误处理
  • 序列化: 可选的 serde 支持（通过 feature 控制）
  • 文档: 完整的文档测试覆盖

§模块架构

§模块职责划分

§1. errors 模块 - 统一错误处理系统
  • 职责: 提供统一的错误类型和诊断信息
  • 关键类型: GaiaError, GaiaErrorKind, GaiaDiagnostics
  • 设计考量:
    • 使用 Box 包装减少枚举大小
    • 支持结构化错误信息
    • 集成 tracing 日志系统
    • 提供详细的源代码位置信息
§2. helpers 模块 - 架构和目标抽象
  • 职责: 定义支持的架构和编译目标
  • 关键类型: Architecture, CompilationTarget, AbiCompatible, ApiCompatible
  • 设计考量:
    • 支持物理架构（x86, ARM, RISC-V 等）
    • 支持虚拟机架构（JVM, CLR）
    • 提供架构兼容性检查
    • 序列化支持便于配置存储
§3. reader 模块 - 二进制读取抽象
  • 职责: 提供统一的二进制数据读取接口
  • 关键类型: BinaryReader, SourceLocation, SourcePosition
  • 设计考量:
    • 支持大端和小端字节序
    • 提供详细的错误位置信息
    • 零拷贝设计避免不必要的内存分配
§4. writer 模块 - 文本写入抽象
  • 职责: 提供统一的文本输出接口
  • 关键类型: TextWriter
  • 设计考量:
    • 支持多种输出格式
    • 提供格式化选项
    • 错误处理集成
§5. lexer 模块 - 词法分析基础
  • 职责: 提供通用的词法分析功能
  • 设计考量:
    • 支持多种词法单元类型
    • 提供详细的词法错误信息
§6. parser 模块 - 语法分析基础
  • 职责: 提供通用的语法分析功能
  • 设计考量:
    • 递归下降解析器
    • 错误恢复机制
    • 详细的语法错误信息
§7. assembler 模块 - 汇编器基础
  • 职责: 提供汇编相关的基本功能
  • 关键类型: BinaryWriter
  • 设计考量:
    • 支持多种输出格式
    • 提供汇编错误处理

§核心类型详解

§错误处理系统

§GaiaError 结构

提供统一的错误处理接口，包含错误级别和具体的错误类型。

§GaiaErrorKind 枚举

包含所有可能的错误类型：语法错误、IO 错误、架构错误、编译错误、配置错误等。

§架构抽象系统

§Architecture 枚举

支持多种物理架构（x86, ARM, RISC-V, MIPS, WebAssembly）和虚拟机架构（JVM, CLR）。

§CompilationTarget 结构

定义编译目标，包含架构、ABI、API版本等信息。

§开发环境配置

§必需工具

  • Rust 1.70+ (建议使用 rustup 管理)
  • Cargo (随 Rust 一起安装)

§常用命令

  • cargo build - 构建项目
  • cargo test - 运行测试
  • cargo test --doc - 运行文档测试
  • cargo doc --open - 生成文档
  • cargo clippy - 检查代码质量

§关键设计决策

§错误处理策略

  1. 统一错误类型: 所有错误都通过 GaiaError 表示
  2. 结构化错误信息: 提供机器可读的错误详情
  3. 源代码位置: 每个错误都包含详细的源代码位置信息
  4. 错误级别: 支持错误、警告、信息等不同级别

§架构抽象策略

  1. 枚举表示: 使用枚举确保架构类型的完整性
  2. 显示实现: 提供人类可读的架构名称
  3. 序列化支持: 便于配置文件存储和传输
  4. 扩展性: 支持自定义架构类型

§性能优化考量

  1. 零分配设计: 核心路径避免堆分配
  2. Box包装: 使用Box减少枚举大小，提高缓存效率
  3. 内联优化: 关键函数使用内联属性

§维护指南

§新增错误类型流程

  1. 错误调研: 分析错误发生的场景和影响范围
  2. 类型定义: 在 GaiaErrorKind 中添加新的错误变体
  3. 构造函数: 为新的错误类型创建便捷的构造函数
  4. 错误转换: 实现从其他错误类型的转换
  5. 显示实现: 提供人类可读的错误信息
  6. 测试覆盖: 添加单元测试和文档测试

§新增架构支持流程

  1. 架构调研: 确认新架构的技术规格和ABI
  2. 枚举扩展: 在 Architecture 枚举中添加新架构
  3. 显示实现: 更新 Display trait 实现
  4. 兼容性检查: 添加架构兼容性验证逻辑
  5. 序列化支持: 确保新架构可以正确序列化
  6. 文档更新: 更新相关文档和示例

§常见维护陷阱

  1. 错误大小: 注意控制错误类型的大小，避免栈上分配过大
  2. 架构一致性: 确保所有架构相关的代码都正确处理新架构
  3. 向后兼容: 修改枚举时要考虑序列化兼容性
  4. 文档同步: 代码修改后要及时更新文档测试

§模块详细文档

各子模块包含专门的维护文档：

  • errors/readme.md - 错误处理系统的详细设计
  • helpers/readme.md - 架构抽象的详细说明
  • reader/readme.md - 二进制读取的实现细节
  • writer/readme.md - 文本写入的实现细节

§发布流程

§版本管理

  • 遵循语义化版本控制 (SemVer)
  • 主版本号: 不兼容的 API 修改
  • 次版本号: 向下兼容的功能性新增
  • 修订号: 向下兼容的问题修正

§发布前检查清单

  • 所有测试通过 (cargo test)
  • 文档测试通过 (cargo test --doc)
  • 无警告 (cargo build)
  • 文档完整 (cargo doc)
  • 版本号更新 (Cargo.toml)
  • CHANGELOG 更新

Re-exports§

pub use crate::assembler::BinaryWriter;
pub use crate::reader::BinaryReader;
pub use crate::reader::SourceLocation;
pub use crate::reader::SourcePosition;
pub use crate::writer::TextWriter;

Modules§

assembler
汇编器模块
helpers
Gaia Types - 辅助工具模块
lexer
Gaia Types - 词法分析器模块
neural
神经网络算子定义
parser
Gaia Types - 语法分析器模块
reader
Gaia Types - 读取器模块
writer
Writer 模块

Structs§

GaiaDiagnostics
Gaia 诊断结果容器
GaiaError
Gaia 错误类型，包装了具体的错误类 GaiaErrorKind

Enums§

GaiaErrorKind
Gaia 错误种类枚举，定义了所有可能的错误类型

Type Aliases§

Result
本crate的结果类型，使用GaiaError作为错误类型