CCGO.toml 配置参考¶

版本：v3.1.0 | 更新时间：2026-01-21

本文档提供 CCGO.toml 配置文件的完整参考，该文件控制 CCGO 中 C++ 跨平台项目的所有方面。

目录¶

概述
文件结构
Package 部分
Workspace 部分
依赖项
特性
构建配置
平台配置
二进制和示例目标
发布配置
完整示例

概述¶

CCGO 使用基于 TOML 的配置文件，类似于 Rust 项目的 Cargo.toml。CCGO.toml 文件应放置在项目的根目录中。

基本要求¶

每个 CCGO.toml 必须包含以下至少一项： - [package] 部分 - 用于单个包/库 - [workspace] 部分 - 用于管理多个相关包

配置可以同时包含两个部分（工作区根目录也是一个包）。

文件结构¶

最小包配置¶

[package]
name = "mylib"
version = "1.0.0"

最小工作区配置¶

[workspace]
members = ["core", "utils"]

Package 部分¶

[package] 部分定义单个包的元数据。

字段¶

字段	类型	必需	描述
`name`	字符串	是	包名称（必须是有效的 C++ 标识符）
`version`	字符串	是	语义化版本（例如 "1.0.0"）
`description`	字符串	否	包的简要描述
`authors`	字符串数组	否	作者列表
`license`	字符串	否	SPDX 许可证标识符（例如 "MIT"、"Apache-2.0"）
`repository`	字符串	否	Git 仓库 URL

示例¶

[package]
name = "mylib"
version = "1.2.3"
description = "我的超棒 C++ 库"
authors = ["张三 <zhangsan@example.com>", "李四"]
license = "MIT"
repository = "https://github.com/user/mylib"

旧版别名¶

为了向后兼容，[project] 被接受为 [package] 的别名：

[project]  # 与 [package] 相同
name = "mylib"
version = "1.0.0"

Workspace 部分¶

[workspace] 部分使管理多个相关包成为可能。

字段¶

字段	类型	必需	描述
`members`	字符串数组	是	工作区成员路径（支持 glob 模式）
`exclude`	字符串数组	否	要排除的路径
`resolver`	字符串	否	依赖解析器版本（"1" 或 "2"，默认："1"）
`default_members`	字符串数组	否	工作区命令的默认成员

工作区依赖¶

可以定义工作区级别的依赖并由成员继承：

[[workspace.dependencies]]
name = "fmt"
version = "^10.0"
git = "https://github.com/fmtlib/fmt.git"

成员路径模式¶

members 数组支持 glob 模式：

[workspace]
members = [
    "core",              # 精确路径
    "utils",             # 精确路径
    "examples/*",        # 所有直接子目录
    "plugins/**"         # 所有子目录（递归）
]
exclude = ["examples/deprecated"]

解析器版本¶

"1"（默认）：旧版解析器
"2"：新解析器，具有更好的特性统一和冲突解决

完整工作区示例¶

[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）：

[workspace]
members = ["core"]

[[workspace.dependencies]]
name = "fmt"
version = "^10.0"
git = "https://github.com/fmtlib/fmt.git"
features = ["std"]

成员（core/CCGO.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. 基于版本的依赖（未来）¶

[[dependencies]]
name = "fmt"
version = "^10.0"  # 语义化版本要求

2. Git 依赖¶

[[dependencies]]
name = "spdlog"
version = "^1.12"
git = "https://github.com/gabime/spdlog.git"
branch = "v1.x"    # 可选：特定分支

[[dependencies]]
name = "json"
version = "^3.11"
git = "https://github.com/nlohmann/json.git"
tag = "v3.11.2"    # 可选：特定标签

[[dependencies]]
name = "pinned"
version = "1.0.0"
git = "https://github.com/user/pinned.git"
rev = "abc123"     # 可选：特定提交哈希

3. 路径依赖¶

[[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`

可选依赖¶

可选依赖仅在特性启用时包含：

[[dependencies]]
name = "http-client"
version = "^1.0"
optional = true  # 仅在特性启用时包含

[features]
networking = ["http-client"]  # 启用可选依赖的特性

依赖特性¶

为依赖启用特定特性：

[[dependencies]]
name = "serde"
version = "^1.0"
features = ["derive", "std"]
default_features = false  # 禁用默认特性

工作区依赖继承¶

成员可以从工作区继承依赖：

[[dependencies]]
name = "fmt"
workspace = true              # 必需：从工作区继承
features = ["extra-feature"]  # 可选：添加额外特性

完整依赖示例¶

# 来自 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] 部分定义条件编译和可选依赖。

默认特性¶

[features]
default = ["std"]  # 默认启用的特性

特性定义¶

特性可以依赖于： 1. 其他特性 2. 可选依赖名称 3. 依赖特性语法（dep/feature）

[features]
default = ["std"]
std = []                           # 空特性（只是一个标志）
networking = ["http-client"]       # 启用可选依赖
advanced = ["networking", "async"] # 依赖于其他特性
full = ["networking", "advanced"]  # 传递依赖
derive = ["serde/derive"]          # 在依赖中启用特性

特性解析¶

特性递归解析：

[features]
default = ["std"]
std = []
networking = ["http-client"]
advanced = ["networking"]  # 也启用 "http-client"
full = ["advanced"]        # 启用 "advanced"、"networking" 和 "http-client"

使用特性¶

构建时启用特性：¶

ccgo build android --features networking,advanced

禁用默认特性：¶

ccgo build ios --no-default-features

启用特定特性而不启用默认特性：¶

ccgo build linux --no-default-features --features networking

完整特性示例¶

[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`	表	否	用于共享链接的子模块内部依赖

示例¶

[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 配置¶

[platforms.android]
min_sdk = 21                        # 最小 SDK 版本
architectures = [                    # 目标架构
    "armeabi-v7a",
    "arm64-v8a",
    "x86_64"
]

iOS 配置¶

[platforms.ios]
min_version = "13.0"  # 最小 iOS 部署目标

macOS 配置¶

[platforms.macos]
min_version = "10.15"  # 最小 macOS 部署目标

Windows 配置¶

[platforms.windows]
toolchain = "auto"  # auto、msvc 或 mingw

工具链选项： - "auto"：使用 MSVC 和 MinGW 构建（默认） - "msvc"：仅 MSVC - "mingw"：仅 MinGW

Linux 配置¶

[platforms.linux]
architectures = ["x86_64", "aarch64"]

OpenHarmony (OHOS) 配置¶

[platforms.ohos]
min_api = 9                          # 最小 API 级别
architectures = [
    "armeabi-v7a",
    "arm64-v8a"
]

完整平台示例¶

[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]] 定义可执行二进制文件：

[[bin]]
name = "my-cli"              # 二进制名称
path = "src/bin/cli.cpp"     # 主源文件路径

[[bin]]
name = "my-server"
path = "src/bin/server.cpp"

运行二进制文件：

ccgo run my-cli
ccgo run my-server -- --help

示例目标¶

使用 [[example]] 定义示例程序：

[[example]]
name = "basic-usage"
path = "examples/basic.cpp"  # 可选：默认为 examples/{name}.cpp

[[example]]
name = "advanced"
# path 默认为 examples/advanced.cpp 或 examples/advanced/main.cpp

运行示例：

ccgo run --example basic-usage
ccgo run --example advanced

发布配置¶

发布配置当前采用 Python 实现的旧版 [project] 格式。当 Rust 实现添加发布支持时，本部分将更新。

Maven 发布（Android/KMP）¶

[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）¶

[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）¶

[publish.ohos.ohpm]
registry = "official"  # official、private 或 local
dependencies = []

完整示例¶

单包库¶

[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）：

[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）：

[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）：

[package]
name = "myproject-utils"
version = "1.0.0"
description = "实用工具库"

[[dependencies]]
name = "fmt"
workspace = true
features = ["chrono"]  # 向工作区依赖添加额外特性

[[dependencies]]
name = "myproject-core"
path = "../core"  # 依赖于另一个工作区成员

带二进制和示例的库¶

[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 格式的主要变化：

部分名称：
[project] 现在是 [package]（但 [project] 仍作为别名工作）
新特性：
用于多包项目的 [workspace] 部分
用于条件编译的 [features] 部分
用于可执行文件的 [[bin]] 和 [[example]] 部分
用于依赖继承的 workspace = true
工作区配置中的 resolver 字段
依赖项：
从字典格式更改为表数组（[[dependencies]]）
添加了对工作区依赖继承的支持
添加了 optional、features、default_features 字段
平台配置：
移至 [platforms.<name>] 部分
简化字段名称（例如 min_sdk 而不是 Android 特定名称）
构建配置：
新增 [build] 部分
添加了 parallel、jobs、submodule_deps 字段

最佳实践¶

版本控制：始终将 CCGO.toml 提交到版本控制
语义化版本：使用正确的 semver（MAJOR.MINOR.PATCH）
包名称：使用不带空格的小写名称（推荐 kebab-case）
工作区组织：
对相关包使用工作区
在工作区根目录定义共享依赖
使用 resolver = "2" 以获得更好的依赖解析
特性：
保持 default 特性最小化
使用特性使依赖可选
在 README 中记录特性
平台支持：仅配置实际支持的平台
依赖项：
在生产中固定版本（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 参考 - CCGO 命令行界面
快速入门 - 快速入门指南
项目结构 - 项目组织结构
依赖管理 - 管理依赖