版本管理¶

使用语义化版本控制、git 标签和自动版本注入管理 CCGO 项目版本的完整指南。

概览¶

CCGO 提供全面的版本管理功能：

语义化版本控制 - 遵循 SemVer 2.0.0 规范
自动标签 - 从 CCGO.toml 版本创建 git 标签
版本注入 - 自动将版本信息注入到构建中
多平台支持 - 所有平台的版本保持一致
构建元数据 - 在二进制文件中包含 git commit SHA、构建时间戳
发布管理 - 简化发布工作流

版本格式¶

语义化版本控制¶

主版本号.次版本号.修订号[-预发布版本][+构建元数据]

组成部分： - 主版本号：不兼容的 API 更改 - 次版本号：向后兼容的新功能 - 修订号：向后兼容的问题修正 - 预发布版本：可选的预发布标识符（alpha、beta、rc） - 构建元数据：可选的构建元数据（commit SHA、时间戳）

示例：

1.0.0           # 稳定版本
1.2.3           # 修订更新
2.0.0-alpha.1   # 预发布版
1.5.0+20240115  # 带构建元数据
2.1.0-rc.2+g8f3a  # 预发布版带 git hash

配置¶

CCGO.toml¶

[package]
name = "mylib"
version = "1.2.3"  # SemVer 格式
authors = ["Your Name <you@example.com>"]

[version]
# 版本注入设置
inject_build_metadata = true  # 包含 git SHA 和时间戳
inject_to_code = true          # 生成版本头文件
prerelease_suffix = "beta"     # 可选：alpha、beta、rc

# 平台特定版本覆盖（可选）
[version.android]
version_code = 10203  # Android 整数版本（未设置时自动计算）

[version.ios]
build_number = "123"  # iOS 构建号（默认为 PATCH）

[version.windows]
file_version = "1.2.3.0"  # Windows 4 部分版本

版本自动计算¶

CCGO 自动计算平台特定的版本号：

Android version_code：

version_code = 主版本号 * 10000 + 次版本号 * 100 + 修订号

示例：1.2.3 → 10203

iOS build number：

build_number = 修订号（默认）
或自定义：build_number = "123"

Windows file version：

file_version = 主版本号.次版本号.修订号.0

示例：1.2.3 → 1.2.3.0

创建版本标签¶

使用 ccgo tag¶

# 从 CCGO.toml 版本创建标签
ccgo tag

# 使用自定义版本创建标签
ccgo tag v2.0.0

# 带消息创建标签
ccgo tag --message "发布版本 2.0.0 及新功能"

# 创建注解标签
ccgo tag --annotate

# 推送标签到远程
ccgo tag --push

标签格式¶

# CCGO 创建格式为：v{VERSION} 的标签
v1.0.0
v1.2.3-beta.1
v2.0.0

手动标签¶

# 创建轻量标签
git tag v1.0.0

# 创建注解标签
git tag -a v1.0.0 -m "发布 1.0.0"

# 推送标签到远程
git push origin v1.0.0

# 推送所有标签
git push --tags

版本注入¶

构建时注入¶

CCGO 在构建时自动注入版本信息：

# 版本信息注入到所有构建
ccgo build android

# 禁用版本注入
ccgo build android --no-version-inject

生成的版本头文件¶

C++ 头文件（include/<project>/version.h）：

#pragma once

#define MYLIB_VERSION "1.2.3"
#define MYLIB_VERSION_MAJOR 1
#define MYLIB_VERSION_MINOR 2
#define MYLIB_VERSION_PATCH 3

#define MYLIB_GIT_SHA "8f3a2b1c"
#define MYLIB_GIT_BRANCH "main"
#define MYLIB_BUILD_TIMESTAMP "2024-01-15T10:30:00Z"
#define MYLIB_BUILD_TYPE "Release"

// 平台特定
#ifdef __ANDROID__
#define MYLIB_VERSION_CODE 10203
#elif defined(__APPLE__)
#define MYLIB_BUNDLE_VERSION "123"
#elif defined(_WIN32)
#define MYLIB_FILE_VERSION "1.2.3.0"
#endif

namespace mylib {
    const char* get_version();
    const char* get_git_sha();
    const char* get_build_timestamp();
}

在代码中使用版本¶

#include "mylib/version.h"
#include <iostream>

void print_version() {
    std::cout << "MyLib 版本：" << mylib::get_version() << "\n";
    std::cout << "Git SHA：" << mylib::get_git_sha() << "\n";
    std::cout << "构建时间：" << mylib::get_build_timestamp() << "\n";
}

平台特定版本控制¶

Android¶

版本代码和版本名称：

[package]
version = "1.2.3"

[version.android]
version_code = 10203       # Play Store 的整数
version_name = "1.2.3"     # 显示名称（默认为 package.version）

Gradle 集成：

// 在 build.gradle.kts 中生成
android {
    defaultConfig {
        versionCode = 10203
        versionName = "1.2.3"
    }
}

iOS¶

Bundle 版本：

[package]
version = "1.2.3"

[version.ios]
bundle_short_version = "1.2.3"  # CFBundleShortVersionString
build_number = "123"             # CFBundleVersion

Info.plist：

<key>CFBundleShortVersionString</key>
<string>1.2.3</string>
<key>CFBundleVersion</key>
<string>123</string>

OpenHarmony¶

HAR 版本：

[package]
version = "1.2.3"

[version.ohos]
app_version_code = 10203
app_version_name = "1.2.3"

module.json5：

{
  "module": {
    "versionCode": 10203,
    "versionName": "1.2.3"
  }
}

Windows¶

文件版本：

[package]
version = "1.2.3"

[version.windows]
file_version = "1.2.3.0"        # 四部分版本
product_version = "1.2"          # 显示版本
company_name = "您的公司"
copyright = "版权所有 © 2024"

预发布版本¶

Alpha 发布¶

[package]
version = "2.0.0-alpha.1"

[version]
prerelease_suffix = "alpha"

# 标记 alpha 发布
ccgo tag v2.0.0-alpha.1 --message "Alpha 发布 1"

Beta 发布¶

[package]
version = "2.0.0-beta.2"

[version]
prerelease_suffix = "beta"

候选发布¶

[package]
version = "2.0.0-rc.1"

[version]
prerelease_suffix = "rc"

提升为稳定版¶

# 将 RC 提升为稳定版
# 1. 更新 CCGO.toml
version = "2.0.0"  # 移除 -rc.1

# 2. 创建稳定版标签
ccgo tag v2.0.0 --message "稳定版 2.0.0"

构建元数据¶

Git 信息¶

CCGO 自动包含： - Commit SHA：当前 git commit 哈希 - 分支：当前 git 分支名称 - 标签：最近的 git 标签（如果有） - 脏标志：工作目录是否有未提交的更改

时间戳¶

// ISO 8601 格式
#define MYLIB_BUILD_TIMESTAMP "2024-01-15T10:30:00Z"

构建类型¶

// Release 或 Debug
#define MYLIB_BUILD_TYPE "Release"

版本查询¶

检查当前版本¶

# 显示 CCGO.toml 中的版本
ccgo --version

# 显示详细版本信息
ccgo version --detailed

# 输出：
# CCGO 版本：3.0.10
# 项目：mylib
# 版本：1.2.3
# Git SHA：8f3a2b1c
# Git 分支：main
# 已修改：否

运行时版本查询¶

// 在您的应用程序中
#include "mylib/mylib.h"

const char* version = mylib::get_version();
printf("库版本：%s\n", version);

版本控制工作流¶

开发工作流¶

# 1. 开始新功能
git checkout -b feature/new-api
# CCGO.toml：version = "1.2.0"

# 2. 开发和测试
ccgo build --all
ccgo test

# 3. 合并到 main
git checkout main
git merge feature/new-api

# 4. 提升版本
# 更新 CCGO.toml：version = "1.3.0"

# 5. 创建标签
ccgo tag v1.3.0 --message "添加新 API"

# 6. 推送
git push origin main --tags

发布工作流¶

# 1. 创建发布分支
git checkout -b release/2.0
# CCGO.toml：version = "2.0.0-rc.1"

# 2. 测试候选发布
ccgo build --all
ccgo test --all

# 3. 如需修复错误
# ... 错误修复 ...

# 4. 提升为稳定版
# 更新 CCGO.toml：version = "2.0.0"
ccgo tag v2.0.0 --message "发布 2.0.0"

# 5. 合并回 main
git checkout main
git merge release/2.0

# 6. 推送
git push origin main --tags

热修复工作流¶

# 1. 从标签创建热修复分支
git checkout -b hotfix/1.2.4 v1.2.3
# CCGO.toml：version = "1.2.4"

# 2. 修复关键错误
# ... 修复 ...

# 3. 测试
ccgo build --all
ccgo test

# 4. 创建标签
ccgo tag v1.2.4 --message "热修复：关键错误"

# 5. 合并到 main 和发布分支
git checkout main
git cherry-pick hotfix/1.2.4

git checkout release/1.2
git cherry-pick hotfix/1.2.4

# 6. 推送
git push origin main release/1.2 --tags

最佳实践¶

1. 版本编号¶

从 1.0.0 开始作为首个稳定版本
0.y.z 用于初始开发（不稳定 API）
递增主版本号表示破坏性更改
递增次版本号表示新功能
递增修订号表示错误修复

2. 标签管理¶

# 始终使用注解标签发布
git tag -a v1.0.0 -m "发布 1.0.0"

# 轻量标签仅用于内部使用
git tag build-123

# 明确推送标签
git push origin v1.0.0

3. 提交消息中的版本¶

# 良好的提交消息
git commit -m "chore: 提升版本至 1.2.3"
git commit -m "release: v2.0.0"
git commit -m "hotfix: v1.2.4 - 修复关键错误"

故障排除¶

版本不匹配¶

问题：

警告：CCGO.toml 版本（1.2.3）与 git 标签（v1.2.2）不匹配

解决方案：

# 更新 CCGO.toml 以匹配标签
# 或创建匹配 CCGO.toml 的新标签
ccgo tag --force

无效版本格式¶