构建系统与依赖

相关源文件

• .github/workflows/ci.yml
• .github/workflows/gh-pages.yml
• .github/workflows/scripts/verify_tag.sh
• Cargo.lock
• Cargo.toml
• forc-pkg/Cargo.toml
• forc-plugins/forc-client/Cargo.toml
• forc-plugins/forc-doc/README.md
• forc-plugins/forc-doc/src/cli.rs
• forc-plugins/forc-doc/src/lib.rs
• forc-plugins/forc-doc/tests/lib.rs
• forc-plugins/forc-fmt/Cargo.toml
• forc-plugins/forc-fmt/src/main.rs
• forc-plugins/forc-lsp/Cargo.toml
• forc-util/Cargo.toml
• forc/Cargo.toml
• forc/src/ops/forc_clean.rs
• sway-core/Cargo.toml
• sway-ir/Cargo.toml
• sway-lib-std/Forc.toml
• sway-lsp/Cargo.toml
• sway-parse/Cargo.toml
• sway-types/Cargo.toml
• sway-utils/Cargo.toml
• sway-utils/src/helpers.rs
• test/src/sdk-harness/Cargo.lock
• test/src/sdk-harness/Cargo.toml
• test/src/sdk-harness/test_projects/block/mod.rs
• test/src/sdk-harness/test_projects/contract_bytecode/mod.rs
• test/src/sdk-harness/test_projects/ec_recover/mod.rs
• test/src/sdk-harness/test_projects/ec_recover_and_match_predicate/mod.rs
• test/src/sdk-harness/test_projects/evm_ec_recover/mod.rs
• test/src/sdk-harness/test_projects/generics_in_abi/mod.rs
• test/src/sdk-harness/test_projects/low_level_call/mod.rs
• test/src/sdk-harness/test_projects/messages/mod.rs
• test/src/sdk-harness/test_projects/parsing_logs/mod.rs
• test/src/sdk-harness/test_projects/predicate_data_simple/mod.rs
• test/src/sdk-harness/test_projects/predicate_data_struct/mod.rs
• test/src/sdk-harness/test_projects/script_data/mod.rs
• test/src/sdk-harness/test_projects/vec_in_abi/mod.rs

本文档概述了 Sway 编程语言的构建系统结构、依赖管理和 CI/CD 管道。它解释了 Sway 存储库如何组织为 Rust 工作区，如何管理依赖项，以及持续集成管道如何确保代码质量。

存储库结构作为 Rust 工作区

Sway 代码库被组织成一个 Rust 工作区，允许同时高效地开发多个相关包。这种结构有利于共享依赖项、协调版本控制和优化编译。

工作区在根目录的 Cargo.toml 文件中定义，该文件列出了所有成员 crate 并配置了共享依赖项和版本。这种方法可确保整个代码库的版本一致性。

来源： Cargo.toml1-259

版本管理

工作区中的所有 crate 都共享相同的版本，该版本在工作区的 Cargo.toml 文件中定义。这简化了版本管理并确保了保持一致性。

发布新版本时，所有 crate 会同时更新，并且版本一致性通过 CI 检查进行验证。

来源： Cargo.toml35-42 .github/workflows/scripts/verify_tag.sh1-73

依赖管理

内部依赖

内部依赖项是指 Sway 工作区内的各种 crate。这些依赖项通过工作区的 Cargo.toml 文件进行管理。

内部依赖项版本通过根目录 Cargo.toml 中的 workspace.dependencies 部分进行同步，确保所有 crate 使用一致的版本。

来源： Cargo.toml44-78 forc/Cargo.toml19-48 sway-lsp/Cargo.toml11-54

外部依赖

外部依赖项是 Sway 代码库使用的第三方库。这些依赖项在根目录 Cargo.toml 的 workspace.dependencies 部分定义。

以下是按用途分类的关键外部依赖项：

类别	依赖项	目的
核心工具	anyhow、thiserror、tracing	错误处理和日志记录
CLI	clap、clap_complete	命令行界面
序列化	serde、serde_json、toml	数据序列化/反序列化
Fuel 生态系统	fuel-asm、fuel-crypto、fuel-tx、fuel-vm	与 Fuel VM 集成
语言服务器	tower-lsp、lsp-types	语言服务器协议实现
测试	criterion、insta、pretty_assertions	测试和基准测试
异步	tokio、async-trait	异步编程

来源： Cargo.toml83-259 sway-core/Cargo.toml11-52 forc-pkg/Cargo.toml11-51

构建系统组件

Sway 的构建系统由几个相互关联的组件组成，这些组件处理构建过程的不同方面。

forc CLI

forc (Fuel Orchestrator) CLI 是构建 Sway 项目的主要入口点。它负责命令解析、项目初始化和协调构建过程。

来源： forc/Cargo.toml1-56 forc/src/ops/forc_clean.rs1-44

包管理

包管理由 forc-pkg crate 处理，该 crate 管理项目依赖项、源解析和构建计划。

包管理器使用 Forc.toml 清单文件（类似于 Rust 的 Cargo.toml）来定义项目元数据和依赖项。它支持各种依赖项来源，包括本地路径、Git 存储库和 IPFS 源。

来源： forc-pkg/Cargo.toml1-52 sway-utils/src/helpers.rs96-119 sway-lib-std/Forc.toml1-16

CI/CD 流水线

Sway 的 CI/CD 管道在 GitHub Actions 工作流中定义，并确保代码质量、运行测试和自动化发布。

主要 CI 作业

CI 管道包含各种作业以确保代码质量：

1. 构建作业：构建标准库、示例和整个工作区。
2. 测试作业：运行单元测试、端到端测试和语言服务器测试。
3. 格式化作业：使用 cargo fmt 和 forc fmt 确保代码符合格式标准。
4. Linting 作业：使用 cargo clippy 检查代码质量。
5. 依赖项作业：验证依赖项版本格式和兼容性。

文档

Sway 的文档使用 forc-doc 构建，它为 Sway 包生成 HTML 文档，类似于 Rust 的 cargo doc。

来源： .github/workflows/ci.yml1-737 .github/workflows/gh-pages.yml1-169 forc-plugins/forc-doc/src/cli.rs1-57 forc-plugins/forc-doc/src/lib.rs1-48 forc-plugins/forc-doc/README.md1-24

测试基础设施

测试基础设施包括用于测试 Sway 项目的各种组件：

1. 单元测试：在 Sway 内部使用标准库的测试工具。
2. SDK Harness：用于测试 Sway 代码与 Fuel VM 的交互。
3. E2E 测试：端到端测试，编译并运行 Sway 代码。

SDK Harness 测试会将 Sway 代码编译为 Fuel VM 字节码，并在运行的 Fuel Core 节点上执行它，从而验证编译和运行时行为。

来源： test/src/sdk-harness/Cargo.toml1-38 test/src/sdk-harness/Cargo.lock1-3705 test/src/sdk-harness/test_projects/predicate_data_simple/mod.rs1-202 test/src/sdk-harness/test_projects/predicate_data_struct/mod.rs1-237

构建工具和实用程序

forc 插件

Sway 生态系统包含几个用于 forc CLI 的插件。

插件	目的
forc-fmt	Sway 的代码格式化工具
forc-lsp	语言服务器协议实现
forc-doc	文档生成器
forc-client	与 Fuel 节点交互
forc-debug	调试实用程序
forc-crypto	加密实用程序
forc-node	运行本地 Fuel 节点

来源： forc-plugins/forc-fmt/Cargo.toml1-22 forc-plugins/forc-lsp/Cargo.toml1-17 forc-plugins/forc-fmt/src/main.rs1-408 forc-plugins/forc-client/Cargo.toml1-87

实用工具箱

几个实用工具箱提供了代码库中的通用功能

1. sway-utils：Sway 生态系统的通用实用工具
2. forc-util：forc 箱之间共享的实用工具
3. forc-tracing：跟踪和日志记录实用工具

来源： sway-utils/Cargo.toml1-17 forc-util/Cargo.toml1-45 sway-utils/src/helpers.rs1-119

结论

Sway 构建系统提供了一套全面的工具，用于构建、测试和部署 Sway 项目。它利用 Rust 的工作区功能来有效管理依赖关系，并通过强大的 CI/CD 管道确保代码质量。理解这个构建系统对于为 Sway 代码库做贡献或开发复杂的 Sway 项目至关重要。