# CCGO.toml 配置参考
> 版本：v3.1.0 | 更新时间：2026-01-21
本文档提供 `CCGO.toml` 配置文件的完整参考，该文件控制 CCGO 中 C++ 跨平台项目的所有方面。
## 目录
1. [概述](#概述)
2. [文件结构](#文件结构)
3. [Package 部分](#package-部分)
4. [Workspace 部分](#workspace-部分)
5. [依赖项](#依赖项)
6. [特性](#特性)
7. [构建配置](#构建配置)
8. [平台配置](#平台配置)
9. [二进制和示例目标](#二进制和示例目标)
10. [发布配置](#发布配置)
11. [完整示例](#完整示例)
---
## 概述
CCGO 使用基于 TOML 的配置文件，类似于 Rust 项目的 Cargo.toml。`CCGO.toml` 文件应放置在项目的根目录中。
### 基本要求
每个 `CCGO.toml` 必须包含以下**至少一项**：
- `[package]` 部分 - 用于单个包/库
- `[workspace]` 部分 - 用于管理多个相关包
配置可以同时包含两个部分（工作区根目录也是一个包）。
---
## 文件结构
### 最小包配置
```toml
[package]
name = "mylib"
version = "1.0.0"
```
### 最小工作区配置
```toml
[workspace]
members = ["core", "utils"]
```
---
## Package 部分
`[package]` 部分定义单个包的元数据。
### 字段
| `name` | 字符串 | **是** | 包名称（必须是有效的 C++ 标识符）|
| `version` | 字符串 | **是** | 语义化版本（例如 "1.0.0"）|
| `description` | 字符串 | 否 | 包的简要描述 |
| `authors` | 字符串数组 | 否 | 作者列表 |
| `license` | 字符串 | 否 | SPDX 许可证标识符（例如 "MIT"、"Apache-2.0"）|
| `repository` | 字符串 | 否 | Git 仓库 URL |
### 示例
```toml
[package]
name = "mylib"
version = "1.2.3"
description = "我的超棒 C++ 库"
authors = ["张三 <zhangsan@example.com>", "李四"]
license = "MIT"
repository = "https://github.com/user/mylib"
```
### 旧版别名
为了向后兼容，`[project]` 被接受为 `[package]` 的别名：
```toml
[project] # 与 [package] 相同
name = "mylib"
version = "1.0.0"
```
---
## Workspace 部分
`[workspace]` 部分使管理多个相关包成为可能。
### 字段
| `members` | 字符串数组 | **是** | 工作区成员路径（支持 glob 模式）|
| `exclude` | 字符串数组 | 否 | 要排除的路径 |
| `resolver` | 字符串 | 否 | 依赖解析器版本（"1" 或 "2"，默认："1"）|
| `default_members` | 字符串数组 | 否 | 工作区命令的默认成员 |
### 工作区依赖
可以定义工作区级别的依赖并由成员继承：
```toml
[[workspace.dependencies]]
name = "fmt"
version = "^10.0"
git = "https://github.com/fmtlib/fmt.git"
```
### 成员路径模式
`members` 数组支持 glob 模式：
```toml
[workspace]
members = [
"core", # 精确路径
"utils", # 精确路径
"examples/*", # 所有直接子目录
"plugins/**" # 所有子目录（递归）
]
exclude = ["examples/deprecated"]
```
### 解析器版本
- **"1"**（默认）：旧版解析器
- **"2"**：新解析器，具有更好的特性统一和冲突解决
### 完整工作区示例
```toml
[workspace]
members = ["core", "utils", "examples/*"]
exclude = ["examples/old"]
resolver = "2"
default_members = ["core", "utils"]
[[workspace.dependencies]]
name = "fmt"
version = "^10.0"
git = "https://github.com/fmtlib/fmt.git"
features = ["std"]
[[workspace.dependencies]]
name = "spdlog"
version = "^1.12"
```
### 工作区成员继承
成员可以从工作区继承依赖：
**工作区根目录（CCGO.toml）：**
```toml
[workspace]
members = ["core"]
[[workspace.dependencies]]
name = "fmt"
version = "^10.0"
git = "https://github.com/fmtlib/fmt.git"
features = ["std"]
```
**成员（core/CCGO.toml）：**
```toml
[package]
name = "mylib-core"
version = "1.0.0"
[[dependencies]]
name = "fmt"
workspace = true # 从工作区继承
features = ["extra"] # 添加额外特性（与工作区特性合并）
```
解析后，成员的 fmt 依赖将具有：
- `version = "^10.0"`（来自工作区）
- `git = "..."`（来自工作区）
- `features = ["std", "extra"]`（已合并）
---
## 依赖项
依赖项使用 `[[dependencies]]` 定义为表数组。
### 依赖来源
CCGO 支持多种依赖来源：
#### 1. 基于版本的依赖（未来）
```toml
[[dependencies]]
name = "fmt"
version = "^10.0" # 语义化版本要求
```
#### 2. Git 依赖
```toml
[[dependencies]]
name = "spdlog"
version = "^1.12"
git = "https://github.com/gabime/spdlog.git"
branch = "v1.x" # 可选：特定分支
```
```toml
[[dependencies]]
name = "json"
version = "^3.11"
git = "https://github.com/nlohmann/json.git"
tag = "v3.11.2" # 可选：特定标签
```
```toml
[[dependencies]]
name = "pinned"
version = "1.0.0"
git = "https://github.com/user/pinned.git"
rev = "abc123" # 可选：特定提交哈希
```
#### 3. 路径依赖
```toml
[[dependencies]]
name = "local-utils"
version = "1.0.0"
path = "../utils" # 相对或绝对路径
```
### 依赖字段
| `name` | 字符串 | **是** | 依赖名称 |
| `version` | 字符串 | 条件 | 版本要求（除非 `workspace = true` 则必需）|
| `git` | 字符串 | 否 | Git 仓库 URL |
| `branch` | 字符串 | 否 | Git 分支名称 |
| `tag` | 字符串 | 否 | Git 标签 |
| `rev` | 字符串 | 否 | Git 修订版本（提交哈希）|
| `path` | 字符串 | 否 | 本地文件路径 |
| `optional` | 布尔值 | 否 | 依赖是否可选（默认：false）|
| `features` | 字符串数组 | 否 | 为此依赖启用的特性 |
| `default_features` | 布尔值 | 否 | 是否启用默认特性（默认：true）|
| `workspace` | 布尔值 | 否 | 从工作区依赖继承（默认：false）|
### 版本要求
CCGO 支持语义化版本范围：
| `^1.2.3` | 与 1.2.3 兼容（>=1.2.3, <2.0.0）| `^10.0` |
| `~1.2.3` | 合理接近 1.2.3（>=1.2.3, <1.3.0）| `~1.12.0` |
| `>=1.2.3` | 大于或等于 | `>=1.0,<2.0` |
| `1.2.*` | 通配符版本 | `1.*` |
| `1.2.3` | 精确版本 | `10.2.1` |
### 可选依赖
可选依赖仅在特性启用时包含：
```toml
[[dependencies]]
name = "http-client"
version = "^1.0"
optional = true # 仅在特性启用时包含
[features]
networking = ["http-client"] # 启用可选依赖的特性
```
### 依赖特性
为依赖启用特定特性：
```toml
[[dependencies]]
name = "serde"
version = "^1.0"
features = ["derive", "std"]
default_features = false # 禁用默认特性
```
### 工作区依赖继承
成员可以从工作区继承依赖：
```toml
[[dependencies]]
name = "fmt"
workspace = true # 必需：从工作区继承
features = ["extra-feature"] # 可选：添加额外特性
```
### 完整依赖示例
```toml
# 来自 git 的常规依赖
[[dependencies]]
name = "fmt"
version = "^10.0"
git = "https://github.com/fmtlib/fmt.git"
tag = "10.2.1"
# 本地路径依赖
[[dependencies]]
name = "utils"
version = "1.0.0"
path = "../shared/utils"
# 特性的可选依赖
[[dependencies]]
name = "openssl"
version = "^1.1"
optional = true
# 带特性的依赖
[[dependencies]]
name = "spdlog"
version = "^1.12"
features = ["std", "fmt_external"]
default_features = false
# 工作区继承的依赖
[[dependencies]]
name = "googletest"
workspace = true
```
---
## 特性
`[features]` 部分定义条件编译和可选依赖。
### 默认特性
```toml
[features]
default = ["std"] # 默认启用的特性
```
### 特性定义
特性可以依赖于：
1. 其他特性
2. 可选依赖名称
3. 依赖特性语法（`dep/feature`）
```toml
[features]
default = ["std"]
std = [] # 空特性（只是一个标志）
networking = ["http-client"] # 启用可选依赖
advanced = ["networking", "async"] # 依赖于其他特性
full = ["networking", "advanced"] # 传递依赖
derive = ["serde/derive"] # 在依赖中启用特性
```
### 特性解析
特性递归解析：
```toml
[features]
default = ["std"]
std = []
networking = ["http-client"]
advanced = ["networking"] # 也启用 "http-client"
full = ["advanced"] # 启用 "advanced"、"networking" 和 "http-client"
```
### 使用特性
#### 构建时启用特性：
```bash
ccgo build android --features networking,advanced
```
#### 禁用默认特性：
```bash
ccgo build ios --no-default-features
```
#### 启用特定特性而不启用默认特性：
```bash
ccgo build linux --no-default-features --features networking
```
### 完整特性示例
```toml
[features]
default = ["std"]
std = []
networking = ["http-client", "tls"]
async = ["async-runtime"]
full = ["networking", "async", "logging"]
logging = ["spdlog-dep"]
# 由特性启用的可选依赖
[[dependencies]]
name = "http-client"
version = "^1.0"
optional = true
[[dependencies]]
name = "async-runtime"
version = "^2.0"
optional = true
[[dependencies]]
name = "spdlog-dep"
version = "^1.12"
optional = true
# 依赖特性语法
[[dependencies]]
name = "serde"
version = "^1.0"
# 特性可以启用 serde 的 derive 特性
[features]
derive = ["serde/derive"]
```
---
## 构建配置
`[build]` 部分配置构建系统行为。
### 字段
| `parallel` | 布尔值 | 否 | 启用并行构建（默认：false）|
| `jobs` | 整数 | 否 | 并行作业数 |
| `symbol_visibility` | 布尔值 | 否 | 符号可见性（默认：false 为隐藏）|
| `submodule_deps` | 表 | 否 | 用于共享链接的子模块内部依赖 |
### 示例
```toml
[build]
parallel = true
jobs = 4
symbol_visibility = false # 默认隐藏
# 对于具有多个子模块/组件的项目
[build.submodule_deps]
api = ["base"] # API 依赖于 base
feature = ["base", "core"] # Feature 依赖于 base 和 core
```
`submodule_deps` 映射到 `CCGO_CONFIG_DEPS_MAP` CMake 变量用于共享库链接。
---
## 平台配置
平台特定配置在 `[platforms.<platform>]` 下定义。
### 支持的平台
- `android`
- `ios`
- `macos`
- `windows`
- `linux`
- `ohos`（OpenHarmony）
### Android 配置
```toml
[platforms.android]
min_sdk = 21 # 最小 SDK 版本
architectures = [ # 目标架构
"armeabi-v7a",
"arm64-v8a",
"x86_64"
]
```
### iOS 配置
```toml
[platforms.ios]
min_version = "13.0" # 最小 iOS 部署目标
```
### macOS 配置
```toml
[platforms.macos]
min_version = "10.15" # 最小 macOS 部署目标
```
### Windows 配置
```toml
[platforms.windows]
toolchain = "auto" # auto、msvc 或 mingw
```
工具链选项：
- `"auto"`：使用 MSVC 和 MinGW 构建（默认）
- `"msvc"`：仅 MSVC
- `"mingw"`：仅 MinGW
### Linux 配置
```toml
[platforms.linux]
architectures = ["x86_64", "aarch64"]
```
### OpenHarmony (OHOS) 配置
```toml
[platforms.ohos]
min_api = 9 # 最小 API 级别
architectures = [
"armeabi-v7a",
"arm64-v8a"
]
```
### 完整平台示例
```toml
[platforms.android]
min_sdk = 21
architectures = ["arm64-v8a", "x86_64"]
[platforms.ios]
min_version = "13.0"
[platforms.macos]
min_version = "10.15"
[platforms.windows]
toolchain = "auto"
[platforms.linux]
architectures = ["x86_64"]
[platforms.ohos]
min_api = 9
architectures = ["arm64-v8a"]
```
---
## 二进制和示例目标
### 二进制目标
使用 `[[bin]]` 定义可执行二进制文件：
```toml
[[bin]]
name = "my-cli" # 二进制名称
path = "src/bin/cli.cpp" # 主源文件路径
[[bin]]
name = "my-server"
path = "src/bin/server.cpp"
```
运行二进制文件：
```bash
ccgo run my-cli
ccgo run my-server -- --help
```
### 示例目标
使用 `[[example]]` 定义示例程序：
```toml
[[example]]
name = "basic-usage"
path = "examples/basic.cpp" # 可选：默认为 examples/{name}.cpp
[[example]]
name = "advanced"
# path 默认为 examples/advanced.cpp 或 examples/advanced/main.cpp
```
运行示例：
```bash
ccgo run --example basic-usage
ccgo run --example advanced
```
---
## 发布配置
发布配置当前采用 Python 实现的旧版 `[project]` 格式。当 Rust 实现添加发布支持时，本部分将更新。
### Maven 发布（Android/KMP）
```toml
[publish.android.maven]
group_id = "com.example.mylib"
artifact_id = "mylib" # 可选，默认为包名
channel_desc = "" # 例如 "beta"、"release"
dependencies = [
{ group = "com.example", artifact = "dep1", version = "1.0.0" },
{ group = "com.example", artifact = "dep2", version = "2.0.0" }
]
```
### Apple 发布（CocoaPods/SPM）
```toml
[publish.apple]
pod_name = "MyLib"
platforms = ["ios", "macos"]
min_ios_version = "13.0"
min_macos_version = "10.15"
summary = "我的库描述"
[publish.apple.cocoapods]
enabled = true
repo = "trunk" # 或 "private" 带 spec_repo URL
license = "MIT"
homepage = "https://github.com/user/mylib"
static_framework = true
[publish.apple.spm]
enabled = true
git_url = "https://github.com/user/mylib"
use_local_path = false
```
### OHOS 发布（OHPM）
```toml
[publish.ohos.ohpm]
registry = "official" # official、private 或 local
dependencies = []
```
---
## 完整示例
### 单包库
```toml
[package]
name = "mylib"
version = "1.0.0"
description = "我的 C++ 库"
authors = ["开发者 <dev@example.com>"]
license = "MIT"
repository = "https://github.com/user/mylib"
[[dependencies]]
name = "fmt"
version = "^10.0"
git = "https://github.com/fmtlib/fmt.git"
[[dependencies]]
name = "spdlog"
version = "^1.12"
optional = true
[features]
default = ["std"]
std = []
logging = ["spdlog"]
[build]
parallel = true
jobs = 4
symbol_visibility = false
[platforms.android]
min_sdk = 21
architectures = ["arm64-v8a", "x86_64"]
[platforms.ios]
min_version = "13.0"
```
### 多包工作区
**工作区根目录（CCGO.toml）：**
```toml
[workspace]
members = ["core", "utils", "examples/*"]
exclude = ["examples/old"]
resolver = "2"
[[workspace.dependencies]]
name = "fmt"
version = "^10.0"
git = "https://github.com/fmtlib/fmt.git"
features = ["std"]
[[workspace.dependencies]]
name = "googletest"
version = "^1.14"
git = "https://github.com/google/googletest.git"
# 可选：工作区根也可以是一个包
[package]
name = "myproject"
version = "1.0.0"
```
**成员包（core/CCGO.toml）：**
```toml
[package]
name = "myproject-core"
version = "1.0.0"
description = "核心库"
[[dependencies]]
name = "fmt"
workspace = true # 从工作区继承
[[dependencies]]
name = "spdlog"
version = "^1.12"
git = "https://github.com/gabime/spdlog.git"
```
**成员包（utils/CCGO.toml）：**
```toml
[package]
name = "myproject-utils"
version = "1.0.0"
description = "实用工具库"
[[dependencies]]
name = "fmt"
workspace = true
features = ["chrono"] # 向工作区依赖添加额外特性
[[dependencies]]
name = "myproject-core"
path = "../core" # 依赖于另一个工作区成员
```
### 带二进制和示例的库
```toml
[package]
name = "advanced-lib"
version = "2.0.0"
description = "带 CLI 工具的高级 C++ 库"
license = "Apache-2.0"
[[dependencies]]
name = "fmt"
version = "^10.0"
[[dependencies]]
name = "argparse"
version = "^2.9"
optional = true
[features]
default = []
cli = ["argparse"]
[[bin]]
name = "mytool"
path = "src/bin/tool.cpp"
[[bin]]
name = "converter"
path = "src/bin/converter.cpp"
[[example]]
name = "basic"
# 默认为 examples/basic.cpp
[[example]]
name = "advanced"
path = "examples/advanced/main.cpp"
[build]
parallel = true
[platforms.android]
min_sdk = 21
architectures = ["arm64-v8a"]
[platforms.linux]
architectures = ["x86_64", "aarch64"]
```
---
## 版本迁移说明
### 从 Python CLI (v3.0) 到 Rust CLI (v3.1+)
CCGO.toml 格式的主要变化：
1. **部分名称：**
- `[project]` 现在是 `[package]`（但 `[project]` 仍作为别名工作）
2. **新特性：**
- 用于多包项目的 `[workspace]` 部分
- 用于条件编译的 `[features]` 部分
- 用于可执行文件的 `[[bin]]` 和 `[[example]]` 部分
- 用于依赖继承的 `workspace = true`
- 工作区配置中的 `resolver` 字段
3. **依赖项：**
- 从字典格式更改为表数组（`[[dependencies]]`）
- 添加了对工作区依赖继承的支持
- 添加了 `optional`、`features`、`default_features` 字段
4. **平台配置：**
- 移至 `[platforms.<name>]` 部分
- 简化字段名称（例如 `min_sdk` 而不是 Android 特定名称）
5. **构建配置：**
- 新增 `[build]` 部分
- 添加了 `parallel`、`jobs`、`submodule_deps` 字段
---
## 最佳实践
1. **版本控制**：始终将 `CCGO.toml` 提交到版本控制
2. **语义化版本**：使用正确的 semver（MAJOR.MINOR.PATCH）
3. **包名称**：使用不带空格的小写名称（推荐 kebab-case）
4. **工作区组织**：
- 对相关包使用工作区
- 在工作区根目录定义共享依赖
- 使用 `resolver = "2"` 以获得更好的依赖解析
5. **特性**：
- 保持 `default` 特性最小化
- 使用特性使依赖可选
- 在 README 中记录特性
6. **平台支持**：仅配置实际支持的平台
7. **依赖项**：
- 在生产中固定版本（git 依赖使用 `tag` 或 `rev`）
- 在开发中使用 `^` 版本范围以获得灵活性
- 使用锁文件（`CCGO.toml.lock`）进行可重现构建
---
## 验证
CCGO 在解析时验证 `CCGO.toml`。常见错误：
| "must contain either [package] or [workspace]" | 缺少两个部分 | 至少添加一个部分 |
| "Invalid version requirement" | semver 语法错误 | 修复版本字符串（例如 "^1.0.0"）|
| "Unknown feature" | 请求未定义的特性 | 检查 `[features]` 部分 |
| "workspace dependency not found" | `workspace = true` 但不在工作区依赖中 | 添加到 `[[workspace.dependencies]]` |
| "Failed to parse CCGO.toml" | TOML 语法错误 | 检查 TOML 语法 |
---
## 另请参阅
- [CLI 参考](cli.zh.md) - CCGO 命令行界面
- [快速入门](../getting-started/quickstart.zh.md) - 快速入门指南
- [项目结构](../getting-started/project-structure.zh.md) - 项目组织结构
- [依赖管理](../features/dependency-management.zh.md) - 管理依赖