配置指南¶

通过 CCGO.toml 和其他配置文件配置 CCGO 项目的完整指南。

概述¶

CCGO 使用基于文件的配置系统：

CCGO.toml：主项目配置
build_config.py：特定于构建的设置（自动生成）
CMakeLists.txt：CMake 集成
.ccgoignore：要从操作中排除的文件
环境变量：运行时配置

CCGO.toml¶

文件位置¶

myproject/
├── CCGO.toml          # 主配置
├── src/
├── include/
└── tests/

基本结构¶

[package]
name = "mylib"
version = "1.0.0"
description = "My cross-platform C++ library"
authors = ["Your Name <you@example.com>"]
license = "MIT"
homepage = "https://github.com/myuser/mylib"
repository = "https://github.com/myuser/mylib"

[library]
type = "both"                    # static、shared 或 both

[build]
cpp_standard = "17"              # C++ 标准版本

[dependencies]
spdlog = { git = "https://github.com/gabime/spdlog.git", tag = "v1.12.0" }

[android]
min_sdk_version = 21

[ios]
deployment_target = "12.0"

包配置¶

必需字段¶

[package]
name = "mylib"                   # 必需：项目名称（小写，无空格）
version = "1.0.0"                # 必需：语义化版本

可选元数据¶

[package]
description = "A powerful C++ library for..."
authors = [
    "John Doe <john@example.com>",
    "Jane Smith <jane@example.com>"
]
license = "MIT"                  # 许可证标识符
license_file = "LICENSE"         # 许可证文件路径
readme = "README.md"             # README 路径
homepage = "https://mylib.dev"
repository = "https://github.com/user/mylib"
documentation = "https://docs.mylib.dev"
keywords = ["networking", "async", "performance"]
categories = ["network", "concurrency"]

版本字段¶

版本必须遵循语义化版本：

[package]
version = "1.0.0"                # 主版本.次版本.修订版本
# version = "1.0.0-alpha"        # 预发布版本
# version = "1.0.0-beta.1"       # 带编号的预发布版本
# version = "1.0.0+build.123"    # 构建元数据

规则： - MAJOR（主版本）：破坏性变更 - MINOR（次版本）：新功能（向后兼容） - PATCH（修订版本）：错误修复 - 预发布：可选的 -alpha、-beta、-rc.N - 构建元数据：可选的 +build.N

库配置¶

库类型¶

[library]
type = "static"                  # 仅静态库
# type = "shared"                # 仅动态库
# type = "both"                  # 静态和动态都构建（默认）

静态库： - 编译到可执行文件中 - 可执行文件体积更大 - 启动更快 - 无运行时依赖

动态库： - 运行时加载 - 可执行文件更小 - 可独立更新 - 需要库在运行时存在

Both（两者）： - 构建两种类型 - 用户在链接时选择

库命名¶

[library]
name = "mylib"                   # 覆盖库名称（可选）
# 默认：使用 package.name

生成的文件： - 静态：libmylib.a（Unix）/ mylib.lib（Windows MSVC） - 动态：libmylib.so（Linux）/ libmylib.dylib（macOS）/ mylib.dll（Windows）

构建配置¶

C++ 标准¶

[build]
cpp_standard = "17"              # C++17（推荐）
# cpp_standard = "11"            # C++11
# cpp_standard = "14"            # C++14
# cpp_standard = "20"            # C++20
# cpp_standard = "23"            # C++23

各平台支持： - C++11：所有平台 - C++14：所有平台 - C++17：所有平台（推荐） - C++20：仅现代编译器 - C++23：仅前沿编译器

构建类型¶

[build]
default_build_type = "release"   # 默认：release
# default_build_type = "debug"   # 用于开发

Debug（调试）： - 无优化 - 调试符号 - 启用断言 - 二进制体积更大

Release（发布）： - 完全优化 - 剥离符号（单独文件） - 禁用断言 - 二进制体积更小

编译器标志¶

[build]
cflags = ["-Wall", "-Wextra"]                    # C 标志
cxxflags = ["-Wall", "-Wextra", "-pedantic"]     # C++ 标志
ldflags = ["-Wl,-rpath,$ORIGIN"]                 # 链接器标志

常用标志：

[build]
# 警告
cxxflags = [
    "-Wall",                     # 所有警告
    "-Wextra",                   # 额外警告
    "-Werror",                   # 将警告视为错误
    "-pedantic"                  # 严格 ISO C++
]

# 优化
cxxflags = [
    "-O3",                       # 最大优化
    "-march=native",             # CPU 特定优化
    "-flto"                      # 链接时优化
]

# 安全
cxxflags = [
    "-fstack-protector-strong",  # 栈保护
    "-D_FORTIFY_SOURCE=2",       # 缓冲区溢出检测
    "-fPIC"                      # 位置无关代码
]

宏定义¶

[build]
defines = [
    "USE_FEATURE_X",             # 简单定义
    "MAX_CONNECTIONS=100",       # 带值的定义
    "DEBUG_LOGGING"              # 仅调试定义
]

平台特定定义：

[build.android]
defines = ["ANDROID_PLATFORM"]

[build.ios]
defines = ["IOS_PLATFORM"]

[build.windows]
defines = ["WINDOWS_PLATFORM", "_WIN32_WINNT=0x0601"]

包含目录¶

[build]
include_dirs = [
    "include",                   # 公共头文件
    "src/internal",              # 私有头文件
    "third_party/lib/include"    # 第三方包含
]

源文件¶

默认情况下，CCGO 编译 src/ 中的所有 .cpp/.cc/.cxx 文件。覆盖：

[build]
sources = [
    "src/**/*.cpp",              # src/ 中的所有 .cpp
    "src/core/*.cc",             # 特定目录
    "src/platform/linux/*.cpp"   # 平台特定
]

exclude = [
    "src/experimental/**",       # 排除目录
    "src/**/*_test.cpp"          # 排除测试文件
]

依赖配置¶

Git 依赖¶

[dependencies]
# 标签（推荐用于稳定性）
spdlog = { git = "https://github.com/gabime/spdlog.git", tag = "v1.12.0" }

# 分支（用于最新功能）
fmt = { git = "https://github.com/fmtlib/fmt.git", branch = "master" }

# 提交哈希（用于精确可重现性）
json = { git = "https://github.com/nlohmann/json.git", rev = "9cca280a" }

路径依赖¶

[dependencies]
# 相对路径
myutils = { path = "../myutils" }

# 绝对路径
common = { path = "/opt/libs/common" }

# 工作区依赖
core = { path = "./libs/core" }

注册表依赖¶

在 [registries] 中声明一个 Git 索引，然后用名称 + 版本在 [[dependencies]] 中引用其中的包：

[registries]
# map 的键 = 注册表名称，值 = 索引仓库 URL
mna = "git@git.example.com:org/ccgo-index.git"
public = "https://github.com/example-org/ccgo-packages.git"

[[dependencies]]
name = "stdcomm"
version = "25.2.9519653"
registry = "mna"          # 把查找钉到指定注册表

[[dependencies]]
name = "fmt"
version = "10.2.1"
# 不写 `registry = ...` —— ccgo 按 TOML 声明顺序遍历所有注册表，
# 命中即取

ccgo fetch 会把每个注册表索引克隆到 ~/.ccgo/registries/<name>/，在该包的 JSON 条目里找指定 version，下载记录的 archive_url，校验 SHA-256，再把归档解压到 .ccgo/deps/<name>/。消费方的 CCGO.toml 不再需要 git URL 或 zip URL —— 索引会把这些信息送过来。

字段参考：

键	位置	类型	说明
`[registries]`	顶层表	`name = "git-url"` map	每个条目是一个 Git 索引仓库。
`[[dependencies]].registry`	单个依赖	可选 `String`	把查找钉到具名注册表。如果该名称不在 `[registries]` 里会报错。
`[[dependencies]].version`	单个依赖	通过注册表解析时必填	与索引中 `VersionEntry.version` 做字符串精确匹配。当前不解析 `^1.0`、`~2.1` 这类区间语法。

索引 JSON schema、发布方 CI 片段、解析优先级见包注册表。

可选依赖¶

[dependencies]
# 必需的依赖项
spdlog = { git = "https://github.com/gabime/spdlog.git", tag = "v1.12.0" }

# 可选依赖项
[dependencies.optional]
networking = { git = "https://github.com/user/networking.git", tag = "v1.0.0" }
database = { git = "https://github.com/user/database.git", tag = "v2.0.0" }

通过特性启用：

[features]
default = ["basic"]
basic = []
network = ["networking"]        # 启用 networking 依赖项
db = ["database"]               # 启用 database 依赖项
full = ["basic", "network", "db"]

使用特性构建：

ccgo build android --features network,db

平台特定依赖¶

[dependencies]
common = { git = "https://github.com/user/common.git", tag = "v1.0.0" }

# 仅 Android
[target.'cfg(target_os = "android")'.dependencies]
android-log = { git = "https://github.com/user/android-log.git", tag = "v1.0.0" }

# 仅 iOS
[target.'cfg(target_os = "ios")'.dependencies]
ios-utils = { path = "./ios-utils" }

# 仅 Windows
[target.'cfg(target_os = "windows")'.dependencies]
win32-api = { git = "https://github.com/user/win32-api.git", tag = "v1.0.0" }

平台特定配置¶

Android¶

[android]
min_sdk_version = 21             # 最低 API 级别
target_sdk_version = 34          # 目标 API 级别
ndk_version = "26.1.10909125"    # NDK 版本（可选）
stl = "c++_shared"               # STL 类型：c++_static、c++_shared
package_name = "com.example.mylib"  # Java 包名

iOS¶

[ios]
deployment_target = "12.0"       # 最低 iOS 版本
enable_bitcode = false           # Bitcode 支持（已弃用）
enable_arc = true                # 自动引用计数
frameworks = [                   # 系统框架
    "Foundation",
    "UIKit",
    "CoreGraphics"
]

macOS¶

[macos]
deployment_target = "10.15"      # 最低 macOS 版本
enable_hardened_runtime = true   # 加固运行时
frameworks = [                   # 系统框架
    "Foundation",
    "AppKit"
]

Windows¶

[windows]
subsystem = "console"            # 子系统：console、windows
runtime_library = "MD"           # 运行时：MT、MD、MTd、MDd
windows_sdk_version = "10.0"     # Windows SDK 版本

Linux¶

[linux]
min_glibc_version = "2.17"       # 最低 glibc 版本
link_pthread = true              # 链接 pthread
link_dl = true                   # 链接 libdl
link_rt = true                   # 链接 librt

OpenHarmony¶

[ohos]
api_version = 9                  # API 版本
package_name = "com.example.mylib"  # 包名

特性配置¶

定义特性¶

[features]
# 默认特性（自动启用）
default = ["std"]

# 无依赖的特性
std = []

# 启用依赖项的特性
network = ["cpp-httplib", "openssl"]

# 启用其他特性的特性
full = ["std", "network", "database"]

# 特性组合
web = ["network", "json"]

使用特性¶

在代码中：

#ifdef CCGO_FEATURE_NETWORK
    // 网络代码
    #include <httplib.h>
#endif

#ifdef CCGO_FEATURE_DATABASE
    // 数据库代码
    #include <sqlite3.h>
#endif

在构建时：

# 使用特定特性构建
ccgo build android --features network

# 使用多个特性构建
ccgo build android --features network,database

# 使用所有特性构建
ccgo build android --all-features

# 不使用默认特性构建
ccgo build android --no-default-features

# 组合标志
ccgo build android --no-default-features --features network

测试配置¶

测试设置¶

[test]
# 测试框架（默认：catch2）
framework = "catch2"             # catch2、gtest 或自定义

# 测试源
sources = [
    "tests/**/*.cpp"
]

# 测试依赖项
[test.dependencies]
catch2 = { git = "https://github.com/catchorg/Catch2.git", tag = "v3.4.0" }

运行测试¶

# 运行所有测试
ccgo test

# 运行特定测试
ccgo test --filter "MyTest"

# 使用详细输出运行
ccgo test --verbose

基准测试配置¶

基准测试设置¶

[bench]
# 基准测试框架
framework = "google-benchmark"   # google-benchmark 或自定义

# 基准测试源
sources = [
    "benches/**/*.cpp"
]

# 基准测试依赖项
[bench.dependencies]
benchmark = { git = "https://github.com/google/benchmark.git", tag = "v1.8.3" }

运行基准测试¶

# 运行所有基准测试
ccgo bench

# 运行特定基准测试
ccgo bench --filter "MyBenchmark"

# 指定迭代次数
ccgo bench --iterations 1000

文档配置¶

文档设置¶

[doc]
# 文档生成器
generator = "doxygen"            # doxygen 或自定义

# 源目录
source_dirs = [
    "include",
    "src",
    "docs"
]

# 输出目录
output_dir = "target/doc"

生成文档¶

# 生成文档
ccgo doc

# 生成并在浏览器中打开
ccgo doc --open

发布配置¶

包元数据¶

[package]
name = "mylib"
version = "1.0.0"
authors = ["Your Name <you@example.com>"]
license = "MIT"
description = "My cross-platform library"
homepage = "https://github.com/user/mylib"
repository = "https://github.com/user/mylib"
documentation = "https://docs.mylib.dev"

发布设置¶

[publish]
# 仓库
registry = "default"             # 仓库名称

# Maven（Android）
[publish.maven]
group_id = "com.example"
artifact_id = "mylib"

# CocoaPods（Apple）
[publish.cocoapods]
pod_name = "MyLib"
swift_version = "5.0"

# OHPM（OpenHarmony）
[publish.ohpm]
package_name = "@example/mylib"

build_config.py¶

生成的包含构建特定配置的文件：

# build_config.py（自动生成）

# 项目信息
PROJECT_NAME = "mylib"
PROJECT_VERSION = "1.0.0"

# 构建设置
BUILD_TYPE = "release"
CPP_STANDARD = "17"
LIBRARY_TYPE = "both"

# 平台
ANDROID_MIN_SDK = 21
IOS_DEPLOYMENT_TARGET = "12.0"

# 自定义设置
CUSTOM_DEFINES = []
CUSTOM_FLAGS = []

在构建脚本中使用：

from build_config import PROJECT_NAME, PROJECT_VERSION

print(f"Building {PROJECT_NAME} v{PROJECT_VERSION}")

.ccgoignore¶

从 CCGO 操作中排除文件：

# .ccgoignore

# 构建目录
cmake_build/
target/
bin/

# IDE 文件
.vscode/
.idea/
*.swp

# 操作系统文件
.DS_Store
Thumbs.db

# 依赖项
vendor/
node_modules/

# 生成的文件
*.pyc
__pycache__/

语法： - # 表示注释 - * 通配符匹配文件 - ** 通配符匹配目录 - / 从根目录匹配 - ! 取反（包含）

示例：

# 忽略所有 .log 文件
*.log

# 但包含 important.log
!important.log

# 仅忽略根目录中的 build/
/build/

# 忽略所有 build/ 目录
**/build/

环境变量¶

构建时变量¶

# 构建类型
export BUILD_TYPE=debug          # debug 或 release

# 详细程度
export CCGO_VERBOSE=1            # 详细输出

# 并行构建
export CMAKE_BUILD_PARALLEL_LEVEL=8  # 使用 8 个核心

# 架构
export ANDROID_ARCH=arm64-v8a    # Android 架构

平台特定变量¶

Android：

export ANDROID_HOME=/path/to/android-sdk
export ANDROID_NDK_HOME=/path/to/ndk
export ANDROID_MIN_SDK=21

iOS：

export CODE_SIGN_IDENTITY="Apple Development"
export DEVELOPMENT_TEAM="TEAM123456"
export IOS_DEPLOYMENT_TARGET="12.0"

Windows：

export MSVC_VERSION=2022         # Visual Studio 版本
export WINDOWS_SDK_VERSION=10.0.22621.0

Docker 变量¶

# Docker 构建
export USE_DOCKER=1              # 启用 Docker 构建

# Docker 镜像
export DOCKER_IMAGE=ccgo-builder-linux:latest

配置验证¶

检查配置¶

# 验证 CCGO.toml
ccgo check

# 验证特定平台
ccgo check android

# 详细验证
ccgo check --verbose

常见问题¶

无效的版本格式：

Error: Invalid version '1.0' in CCGO.toml

解决方案： 使用语义化版本（例如 1.0.0）

缺少必需字段：

Error: Missing required field 'name' in [package]

解决方案： 将必需字段添加到 CCGO.toml

无效的依赖项：

Error: Invalid dependency format for 'spdlog'

解决方案： 检查依赖项语法

配置模板¶

最小配置¶

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

[library]
type = "static"

标准配置¶

[package]
name = "mylib"
version = "1.0.0"
description = "My library"
authors = ["Your Name <you@example.com>"]
license = "MIT"

[library]
type = "both"

[build]
cpp_standard = "17"

[dependencies]
spdlog = { git = "https://github.com/gabime/spdlog.git", tag = "v1.12.0" }

[android]
min_sdk_version = 21

[ios]
deployment_target = "12.0"

高级配置¶

[package]
name = "mylib"
version = "1.0.0"
description = "Advanced C++ library"
authors = ["Team <team@example.com>"]
license = "MIT"
homepage = "https://mylib.dev"
repository = "https://github.com/user/mylib"

[library]
type = "both"

[build]
cpp_standard = "20"
cxxflags = ["-Wall", "-Wextra", "-Werror"]
defines = ["USE_ADVANCED_FEATURES"]

[dependencies]
spdlog = { git = "https://github.com/gabime/spdlog.git", tag = "v1.12.0" }
fmt = { git = "https://github.com/fmtlib/fmt.git", tag = "10.1.1" }

[dependencies.optional]
networking = { git = "https://github.com/user/networking.git", tag = "v1.0.0" }

[features]
default = ["basic"]
basic = []
network = ["networking"]
full = ["basic", "network"]

[android]
min_sdk_version = 21
target_sdk_version = 34
package_name = "com.example.mylib"

[ios]
deployment_target = "12.0"
frameworks = ["Foundation", "UIKit"]

[test]
framework = "catch2"

[test.dependencies]
catch2 = { git = "https://github.com/catchorg/Catch2.git", tag = "v3.4.0" }

最佳实践¶

1. 使用语义化版本¶

[package]
version = "1.0.0"                # 好：主版本.次版本.修订版本
# version = "1.0"                # 差：缺少修订版本
# version = "v1.0.0"             # 差：不要包含 'v' 前缀

2. 固定依赖项¶

[dependencies]
# 好：特定标签
spdlog = { git = "https://github.com/gabime/spdlog.git", tag = "v1.12.0" }

# 差：跟踪分支
# spdlog = { git = "https://github.com/gabime/spdlog.git", branch = "master" }

3. 组织章节¶

# 好：逻辑顺序
[package]
[library]
[build]
[dependencies]
[android]
[ios]

# 差：随机顺序
[ios]
[package]
[dependencies]
[build]

4. 为配置添加注释¶

[build]
# 启用所有警告
cxxflags = ["-Wall", "-Wextra"]

# 平台特定优化
defines = [
    "USE_SSE=1",                 # 启用 SSE 指令
    "MAX_THREADS=8"              # 限制线程池大小
]

5. 保持简单¶

只配置您需要的：

# 好：仅必要的配置
[package]
name = "mylib"
version = "1.0.0"

[library]
type = "static"

# 差：不必要的配置
# [build]
# cpp_standard = "17"            # 默认为 17
# [library]
# name = "mylib"                 # 与 package.name 相同

迁移指南¶

从 CMakeLists.txt¶

CMakeLists.txt：

project(mylib VERSION 1.0.0)
set(CMAKE_CXX_STANDARD 17)
add_library(mylib src/mylib.cpp)

CCGO.toml：

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

[build]
cpp_standard = "17"

从 Conan¶

conanfile.txt：

[requires]
spdlog/1.12.0
fmt/10.1.1

[options]
spdlog:shared=False