构建分析¶

概述¶

CCGO 提供构建分析功能，用于跟踪和分析构建性能随时间的变化。它有助于识别瓶颈、跟踪改进效果并优化构建配置。

优势¶

📊 性能跟踪 —— 监控构建时间并识别趋势
🎯 瓶颈识别 —— 找出最耗时的阶段
📈 缓存有效性 —— 跟踪编译器缓存命中/未命中率
🔍 构建历史 —— 查看历史构建并对比性能
📉 优化洞察 —— 数据驱动的构建优化决策

快速开始¶

构建分析数据在构建过程中自动收集，并存储在本地的 ~/.ccgo/analytics/。

查看分析数据¶

# 显示最近的构建（默认 10 条）
ccgo analytics show

# 显示更多构建
ccgo analytics show -n 20

# 显示汇总统计
ccgo analytics summary

# 列出所有有分析数据的项目
ccgo analytics list

命令¶

`ccgo analytics show`¶

显示包含关键指标的最近构建历史：

$ ccgo analytics show

================================================================================
Build Analytics for myproject
================================================================================

Build #1 - linux (2026-01-21T15:30:00+08:00)
  Duration:    45.30s
  Jobs:        8
  Success:     ✓
  Cache Tool:  sccache
  Cache Rate:  78.5%

Build #2 - linux (2026-01-21T16:00:00+08:00)
  Duration:    12.50s
  Jobs:        8
  Success:     ✓
  Cache Tool:  sccache
  Cache Rate:  95.2%

Build #3 - macos (2026-01-21T16:15:00+08:00)
  Duration:    38.70s
  Jobs:        8
  Success:     ✓
  Cache Tool:  ccache
  Cache Rate:  82.3%

选项： - -n, --count <NUM> —— 显示的构建数量（默认 10）

`ccgo analytics summary`¶

显示所有构建的聚合统计信息：

$ ccgo analytics summary

================================================================================
Build Analytics Summary for myproject
================================================================================

Total Builds:      25
Successful:        24 (96.0%)

Build Duration:
  Average:         32.45s
  Fastest:         11.20s
  Slowest:         58.90s

Cache Statistics:
  Builds with cache: 23
  Avg Hit Rate:      85.3%

Platform Breakdown:
  linux............... 15
  macos............... 8
  ios................. 2

================================================================================

`ccgo analytics clear`¶

清除当前项目的分析历史：

$ ccgo analytics clear

This will delete 25 build analytics entries for 'myproject'
Continue? [y/N] y
✓ Cleared analytics for 'myproject'

选项： - -y, --yes —— 跳过确认提示

`ccgo analytics export`¶

将分析数据导出到 JSON 文件：

$ ccgo analytics export -o builds.json

✓ Exported 25 build analytics to builds.json

选项： - -o, --output <FILE> —— 输出文件路径

`ccgo analytics list`¶

列出所有有分析数据的项目：

$ ccgo analytics list

================================================================================
Projects with Analytics
================================================================================

  myproject.................................... 25 builds
  another-lib.................................. 12 builds
  experimental................................. 5 builds

Use 'ccgo analytics show' from a project directory to view details.
================================================================================

收集的指标¶

构建概览¶

项目名称 —— 正在构建的项目
平台 —— 目标平台（linux、macos、windows 等）
时间戳 —— 构建开始时间（ISO 8601）
总时长 —— 完整构建耗时（秒）
并行 Job 数 —— 并行编译任务数
成功状态 —— 构建是否成功
错误/警告 —— 编译诊断计数

阶段分解¶

构建被划分为多个阶段，每个阶段单独计时：

依赖解析 —— 安装并解析依赖
CMake 配置 —— CMake configure 步骤
编译 —— C/C++ 源文件编译
链接 —— 链接库
归档 —— 创建 ZIP 归档
后处理 —— 额外的打包步骤

每个阶段会跟踪： - 时长（秒） - 占总构建时间的百分比

缓存统计¶

对于使用 ccache/sccache 的构建：

缓存工具 —— 正在使用的工具（ccache、sccache）
缓存命中 —— 从缓存重用的编译产物
缓存未命中 —— 新增到缓存的编译结果
命中率 —— 缓存命中百分比（0-100%）

文件统计¶

源文件 —— .c/.cc/.cpp 文件数量
头文件 —— .h/.hpp 文件数量
总行数 —— 代码总行数
产物大小 —— 最终输出大小（字节）

数据存储¶

分析数据存储在本地：

~/.ccgo/analytics/
├── myproject.json      # myproject 的分析数据
├── another-lib.json    # another-lib 的分析数据
└── ...

每个项目文件包含： - 最近 100 次构建（更早的构建会被自动裁剪） - JSON 格式，便于解析和导出 - 不包含任何可识别个人身份的信息

分析 API（Rust）¶

在 CCGO 内部以编程方式访问：

use ccgo::build::analytics::{BuildAnalytics, AnalyticsCollector, BuildPhase};

// 创建收集器
let mut collector = AnalyticsCollector::new(
    "myproject".to_string(),
    "linux".to_string(),
    8, // 并行 job 数
);

// 阶段计时
collector.start_phase(BuildPhase::Compilation);
// ... 编译工作 ...
collector.end_phase(BuildPhase::Compilation);

// 记录诊断
collector.add_diagnostics(2, 15); // 2 个错误，15 个警告

// 设置成功状态
collector.set_success(true);

// 完成并保存
let analytics = collector.finalize(cache_stats, file_stats);
analytics.save()?;

// 加载历史
let history = BuildAnalytics::load_history("myproject")?;

// 获取平均构建时间
let avg = BuildAnalytics::average_build_time("myproject")?;

使用场景¶

性能回归检测¶

# 改动后
ccgo build linux

# 检查构建是否变慢
ccgo analytics summary

# 期望：平均时长不应显著增加

缓存有效性¶

# 第一次构建（冷缓存）
ccgo build linux --cache sccache
# 记录耗时

# 第二次构建（热缓存）
ccgo build linux --cache sccache
# 应快 50-80%

# 检查缓存命中率
ccgo analytics show -n 1
# 期望：高缓存命中率（>80%）

CI/CD 监控¶

# .github/workflows/build.yml
- name: Build
  run: ccgo build linux

- name: Show Analytics
  run: ccgo analytics show -n 1

- name: Export Analytics
  run: ccgo analytics export -o build-stats.json

- name: Upload Analytics
  uses: actions/upload-artifact@v3
  with:
    name: build-analytics
    path: build-stats.json

跨平台对比¶

# 构建多个平台
ccgo build linux
ccgo build macos
ccgo build windows

# 查看汇总
ccgo analytics summary

# Platform Breakdown 部分展示相对性能

最佳实践¶

DO¶

✅ 定期查看 —— 在重大变更后检查分析数据 ✅ 跟踪趋势 —— 监控构建是否随时间变慢 ✅ 优化热点路径 —— 聚焦占比最高的阶段 ✅ 启用缓存 —— 编译器缓存可显著改善指标 ✅ 导出报告 —— 使用 JSON 导出进行趋势分析

DON'T¶

❌ 不要提交分析数据 —— 数据仅在本地机器 ❌ 不要手动编辑 —— 分析文件由系统自动生成 ❌ 不要依赖首次构建 —— 冷缓存构建总是更慢 ❌ 不要跨机器对比 —— 硬件会影响计时

故障排除¶

没有分析数据¶

症状：ccgo analytics show 提示 "No build analytics available"

解决：分析收集是自动的，但需要：

# 先运行一次构建
ccgo build linux

# 然后查看分析数据
ccgo analytics show

分析数据未更新¶

症状：新构建未出现在分析数据中

解决：检查构建是否成功完成：

# 验证构建成功
ccgo build linux

# 查看最近的分析数据
ccgo analytics show -n 1

看到错误项目的分析数据¶

症状：看到的是其他项目的分析数据

解决：分析数据按 CCGO.toml 中的项目名称关联：

# 检查当前项目
grep "name =" CCGO.toml

# 确认在正确目录中
pwd

存储位置¶

分析数据存储在： - Linux：~/.ccgo/analytics/ - macOS：~/.ccgo/analytics/ - Windows：%USERPROFILE%\.ccgo\analytics\

未来增强¶

未来版本计划的功能：

另请参阅¶

构建缓存 —— 通过缓存改善构建时间
构建系统 —— 通用构建系统概览
增量构建 —— 更快的重建策略

更新日志¶

v3.0.11 (2026-01-21)¶

✅ 实现构建分析系统
✅ 添加 ccgo analytics 命令及其 show/summary/clear/export/list 子命令
✅ 自动收集构建指标
✅ 阶段计时分解
✅ 缓存统计集成
✅ 文件与错误/警告跟踪
✅ 本地存储于 ~/.ccgo/analytics/
✅ 每项目最多保留最近 100 次构建（自动裁剪）

构建分析帮助你基于数据做出关于构建优化与配置的决策。