ccgo

A cross-platform C++ build system designed to simplify and accelerate multi-platform development.

Features

• 🚀 Fast cross-platform C++ builds for Android, iOS, macOS, Windows, Linux, and OpenHarmony (OHOS)
• 🗂️ Kotlin Multiplatform (KMP) support
• 📦 Conan C/C++ package manager integration
• 🎛️ Conditional compilation with Features system (similar to Cargo)
• 🧪 Integrated testing with GoogleTest
• 📊 Benchmarking support with Google Benchmark
• 📚 Documentation generation
• 🛠️ Project scaffolding from templates
• ✅ Environment dependency checking
• 🧹 Smart build artifact cleaning

Installation

# 1. Install from PyPI via uv (recommended)
pip install uv
uv tool install ccgo
# or via pip
pip install ccgo

# 2. Install via Homebrew
brew tap zhlinh/ccgo
brew trust --formula zhlinh/ccgo/ccgo
brew install ccgo

# 3. Install from crates.io
cargo install ccgo

Quick Start

# Create a new C++ library project
ccgo new my-awesome-lib

# Navigate to the project directory
cd my-awesome-lib/<project_relative_path>

# Build for Android
ccgo build android

# Run tests
ccgo test

# Build documentation
ccgo doc --open

Commands Reference

1. Project Creation

ccgo new - Create New Project

Create a new library project in a new directory.

ccgo new <project-name> [options]

Options:

• --template-url <url> - Custom template repository URL
• --data <key>=<value> - Template variables (repeatable)
• --defaults - Use default values for all prompts

Examples:

# Create with interactive prompts
ccgo new my-project

# Create with all defaults
ccgo new my-project --defaults

# Use custom template
ccgo new my-project --template-url https://github.com/user/template.git
ccgo new my-project --template-url /path/to/user/template

# Set template variables
ccgo new my-project --data cpy_project_version=2.0.0

ccgo init - Initialize in Current Directory

Initialize a library project in the current directory.

ccgo init [options]

Options:

• --template-url <url> - Custom template repository URL
• --data <key>=<value> - Template variables (repeatable)
• --defaults - Use default values for all prompts
• --force - Skip confirmation prompt

Examples:

ccgo init
ccgo init --defaults --force

2. Build Commands

ccgo build - Build for Platforms

Build your library for specific platforms.

ccgo build <target> [options]

Targets:

• android - Build for Android (supports --arch)
• ios - Build for iOS
• macos - Build for macOS
• windows - Build for Windows
• linux - Build for Linux
• ohos - Build for OpenHarmony (supports --arch)
• kmp - Build Kotlin Multiplatform library
• conan - Build Conan C/C++ package
• include - Build include headers

Options:

• --arch <architectures> - Comma-separated architecture list (Android/OHOS only)
  • Android: armeabi-v7a, arm64-v8a, x86_64
  • OHOS: armeabi-v7a, arm64-v8a, x86_64
• --build-as <type> - Library link type: static, shared, or both (default: both)
• --toolchain <toolchain> - Windows toolchain: auto, msvc, or mingw (default: auto)
• --ide-project - Generate IDE project files
• --docker - Build using Docker (cross-platform builds)
• -F, --features <features> - Comma-separated list of features to enable
• --no-default-features - Disable default features
• --all-features - Enable all available features

Examples:

# Build for Android with specific architectures
ccgo build android --arch armeabi-v7a,arm64-v8a

# Build for OHOS with all architectures
ccgo build ohos --arch armeabi-v7a,arm64-v8a,x86_64

# Build for iOS
ccgo build ios

# Build for macOS
ccgo build macos

# Build for Windows
ccgo build windows

# Build for Windows with specific toolchain
ccgo build windows --toolchain msvc
ccgo build windows --toolchain mingw

# Build for Linux
ccgo build linux

# Build static libraries only
ccgo build linux --build-as static

# Build shared libraries only
ccgo build macos --build-as shared

# Build both static and shared libraries (default)
ccgo build ios --build-as both

# Build Kotlin Multiplatform library
ccgo build kmp

# Build Conan C/C++ package
ccgo build conan

# Generate IDE project for Android
ccgo build android --ide-project

# Cross-platform build using Docker
ccgo build linux --docker
ccgo build windows --docker

# Build with specific features enabled
ccgo build android --features networking,advanced

# Build without default features
ccgo build linux --no-default-features --features minimal

# Build with all features enabled
ccgo build ios --all-features

3. Testing & Benchmarking

ccgo test - Run Tests

Build and run GoogleTest-based unit tests.

ccgo test [options]

Options:

• --build-only - Only build tests without running
• --run-only - Only run tests (assumes already built)
• --filter <pattern> - GoogleTest filter (e.g., 'MyTest*')
• --ide-project - Generate IDE project for tests
• --gtest-args <args> - Additional GoogleTest arguments

Examples:

# Build and run all tests
ccgo test

# Only build tests
ccgo test --build-only

# Run specific tests
ccgo test --filter "MyTest*"

# Run tests multiple times
ccgo test --gtest-args "--gtest_repeat=3"

# Generate IDE project for debugging tests
ccgo test --ide-project

ccgo bench - Run Benchmarks

Build and run Google Benchmark-based performance benchmarks.

ccgo bench [options]

Options:

• --build-only - Only build benchmarks without running
• --run-only - Only run benchmarks (assumes already built)
• --filter <pattern> - Google Benchmark filter (e.g., 'BM_Sort*')
• --ide-project - Generate IDE project for benchmarks
• --benchmark-args <args> - Additional Google Benchmark arguments
• --format <format> - Output format: console, json, csv (default: console)

Examples:

# Build and run all benchmarks
ccgo bench

# Only build benchmarks
ccgo bench --build-only

# Run specific benchmarks
ccgo bench --filter "BM_Sort*"

# Output results as JSON
ccgo bench --format json

# Output results as CSV
ccgo bench --format csv

4. Documentation

ccgo doc - Build Documentation

Generate project documentation (typically using Doxygen).

ccgo doc [options]

Options:

• --open - Open documentation in browser after building
• --serve - Start local web server to view documentation
• --port <port> - Port for web server (default: 8000)
• --clean - Clean build before generating

Examples:

# Build documentation
ccgo doc

# Build and open in browser
ccgo doc --open

# Build and serve on localhost:8000
ccgo doc --serve

# Serve on custom port
ccgo doc --serve --port 3000

# Clean build
ccgo doc --clean

5. Publishing

ccgo publish - Publish Libraries

Publish your library to package repositories.

ccgo publish <target>

Targets:

• android - Publish to Maven repository
• ohos - Publish to OHPM repository
• kmp - Publish KMP library to Maven (local or remote)

Examples:

# Publish Android library to Maven
ccgo publish android

# Publish OHOS library to OHPM
ccgo publish ohos

# Publish Kotlin Multiplatform library
ccgo publish kmp

6. Maintenance Commands

ccgo check - Check Dependencies

Verify that platform-specific development dependencies are installed.

ccgo check [target] [options]

Targets:

• all - Check all platforms (default)
• android - Check Android development environment
• ios - Check iOS development environment
• macos - Check macOS development environment
• windows - Check Windows development environment
• linux - Check Linux development environment
• ohos - Check OpenHarmony development environment

Options:

• --verbose - Show detailed information

Examples:

# Check all platforms
ccgo check

# Check Android environment
ccgo check android

# Check with verbose output
ccgo check ios --verbose

ccgo clean - Clean Build Artifacts

Remove build artifacts and caches.

ccgo clean [target] [options]

Targets:

• all - Clean all platforms (default)
• android - Clean Android build caches
• ios - Clean iOS build caches
• macos - Clean macOS build caches
• ohos - Clean OpenHarmony build caches
• kmp - Clean Kotlin Multiplatform build caches
• examples - Clean examples build caches

Options:

• --native-only - Clean only cmake_build/ (native CMake builds)
• --dry-run - Show what would be cleaned without deleting
• -y, --yes - Skip confirmation prompts

Examples:

# Clean all (with confirmation)
ccgo clean

# Clean only Android
ccgo clean android

# Preview what will be deleted
ccgo clean --dry-run

# Clean all without confirmation
ccgo clean -y

# Clean only native CMake builds
ccgo clean --native-only

7. Help

ccgo help - Show Help

Display comprehensive help information.

ccgo help

# Or get help for specific command
ccgo <command> --help

Environment Variables

Android

• ANDROID_HOME - Android SDK location
• ANDROID_NDK_HOME - Android NDK location
• JAVA_HOME - Java Development Kit location

OpenHarmony (OHOS)

• OHOS_SDK_HOME or HOS_SDK_HOME - OHOS Native SDK location

iOS/macOS

• Requires Xcode and command-line tools

Project Structure

Projects created with ccgo follow this structure:

my-project/
├── CCGO.toml                   # CCGO project config
├── CMakeLists.txt              # Root CMake configuration
├── src/                        # Source code
├── include/                    # Public headers
├── docs/                       # docs files
├── tests/                      # GoogleTest unit tests
├── benches/                    # Benchmark tests
├── android/                    # Android-specific files (Gradle)
├── ohos/                       # OHOS-specific files (hvigor)
├── kmp/                        # Kotlin Multiplatform files (Gradle)

SDK Archive Structure

When you run ccgo build <target>, the output is placed in target/{debug|release}/<platform>/ with a unified archive structure.

Archive Naming Convention

{PROJECT}_{PLATFORM}_SDK-{version}[-{suffix}].zip        # Main SDK archive
{PROJECT}_{PLATFORM}_SDK-{version}[-{suffix}]-SYMBOLS.zip  # Debug symbols archive

Examples:

• MYLIB_ANDROID_SDK-1.0.0-release.zip
• MYLIB_IOS_SDK-1.0.0-beta.5-dirty.zip
• MYLIB_LINUX_SDK-2.1.0-SYMBOLS.zip

Unified SDK Archive Structure

All platforms follow the same archive structure:

{PROJECT}_{PLATFORM}_SDK-{version}.zip
├── lib/{platform}/
│   ├── static/                    # Static libraries (.a, .lib)
│   │   └── [{arch}/]              # Architecture subdirectory (if multi-arch)
│   │       └── lib{name}.a
│   └── shared/                    # Shared libraries (.so, .dylib, .dll)
│       └── [{arch}/]
│           └── lib{name}.so
├── include/{project}/             # Public header files
│   └── **/*.h
├── haars/{platform}/              # Platform packages (Android AAR / OHOS HAR)
│   └── {PROJECT}_{PLATFORM}_SDK-{version}.aar
└── meta/{platform}/               # Metadata files
    ├── build_info.json            # Build information
    └── archive_info.json          # Archive file listing

Platform-Specific Build Artifacts

Android

ccgo build android [--arch armeabi-v7a,arm64-v8a,x86_64]

Output: target/{debug|release}/android/

SDK Contents:

├── lib/android/static/{arch}/lib{name}.a
├── lib/android/shared/{arch}/lib{name}.so
├── include/{project}/**/*.h
├── haars/android/*.aar
└── meta/android/build_info.json

iOS

ccgo build ios

Output: target/{debug|release}/ios/

SDK Contents:

├── lib/ios/static/{name}.xcframework/
├── lib/ios/shared/{name}.xcframework/
├── include/{project}/**/*.h
└── meta/ios/build_info.json

Architectures: arm64 (device), arm64-simulator, x86_64-simulator

macOS

ccgo build macos

Output: target/{debug|release}/macos/

SDK Contents:

├── lib/macos/static/{name}.xcframework/
├── lib/macos/shared/{name}.xcframework/
├── include/{project}/**/*.h
└── meta/macos/build_info.json

Architectures: Universal binary (arm64 + x86_64)

tvOS

ccgo build tvos

Output: target/{debug|release}/tvos/

SDK Contents:

├── lib/tvos/static/{name}.xcframework/
├── lib/tvos/shared/{name}.xcframework/
├── include/{project}/**/*.h
└── meta/tvos/build_info.json

Architectures: arm64 (device), arm64-simulator

watchOS

ccgo build watchos

Output: target/{debug|release}/watchos/

SDK Contents:

├── lib/watchos/static/{name}.xcframework/
├── lib/watchos/shared/{name}.xcframework/
├── include/{project}/**/*.h
└── meta/watchos/build_info.json

Architectures: arm64_32, armv7k (device), arm64-simulator

Linux

ccgo build linux

Output: target/{debug|release}/linux/

SDK Contents:

├── lib/linux/static/lib{name}.a
├── lib/linux/shared/lib{name}.so
├── include/{project}/**/*.h
└── meta/linux/build_info.json

Architecture: x86_64

Windows

ccgo build windows [--toolchain auto|msvc|mingw]

Output: target/{debug|release}/windows/

SDK Contents (MinGW):

├── lib/windows/static/lib{name}.a
├── lib/windows/shared/{name}.dll
├── lib/windows/shared/lib{name}.dll.a    # Import library
├── include/{project}/**/*.h
└── meta/windows/build_info.json

SDK Contents (MSVC):

├── lib/windows/static/{name}.lib
├── lib/windows/shared/{name}.dll
├── lib/windows/shared/{name}.lib         # Import library
├── include/{project}/**/*.h
└── meta/windows/build_info.json

Architecture: x86_64

OpenHarmony (OHOS)

ccgo build ohos [--arch armeabi-v7a,arm64-v8a,x86_64]

Output: target/{debug|release}/ohos/

SDK Contents:

├── lib/ohos/static/{arch}/lib{name}.a
├── lib/ohos/shared/{arch}/lib{name}.so
├── include/{project}/**/*.h
├── haars/ohos/*.har
└── meta/ohos/build_info.json

Conan

ccgo build conan

Output: target/{debug|release}/conan/

SDK Contents:

├── lib/conan/static/lib{name}.a
├── lib/conan/shared/lib{name}.so
├── include/{project}/**/*.h
└── meta/conan/build_info.json

Metadata Files

build_info.json

Contains build metadata:

{
  "project": "mylib",
  "platform": "android",
  "version": "1.0.0",
  "link_type": "both",
  "build_time": "2024-01-15T10:30:00.123456",
  "build_host": "Darwin",
  "architectures": ["arm64-v8a", "armeabi-v7a", "x86_64"],
  "git_commit": "abc1234",
  "git_branch": "main"
}

archive_info.json

Contains file listing with sizes:

{
  "archive_metadata": {
    "version": "1.0",
    "generated_at": "2024-01-15T10:30:00Z",
    "archive_name": "MYLIB_ANDROID_SDK-1.0.0.zip",
    "archive_size": 1234567
  },
  "files": [
    {"path": "lib/android/shared/arm64-v8a/libmylib.so", "size": 123456}
  ],
  "summary": {
    "total_files": 10,
    "total_size": 500000,
    "library_count": 6,
    "platforms": ["android"],
    "architectures": ["arm64-v8a", "armeabi-v7a", "x86_64"]
  }
}

Excluded Files

The following files are automatically excluded from archives:

• CPPLINT.cfg
• .clang-format
• .clang-tidy

Features System

CCGO supports a features system similar to Cargo's, enabling conditional compilation and optional dependencies. This allows you to:

• Enable/disable parts of your library at build time
• Make dependencies optional and only include them when needed
• Define feature groups that enable multiple sub-features

Defining Features in CCGO.toml

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

[features]
# Default features enabled when none are specified
default = ["std"]

# Feature definitions
std = []
networking = ["http-client"]        # Enables optional dependency
advanced = ["networking", "async"]  # Enables other features
full = ["networking", "advanced", "logging"]

# Dependency feature syntax
derive = ["serde/derive"]           # Enables feature on dependency

[[dependencies]]
name = "http-client"
version = "^1.0"
optional = true                     # Only included when enabled by a feature

[[dependencies]]
name = "async"
version = "^2.0"
optional = true

[[dependencies]]
name = "serde"
version = "^1.0"
features = ["std"]                  # Features to enable on this dependency
default_features = false            # Disable dependency's default features

Using Features in Builds

# Build with default features
ccgo build android

# Build with specific features
ccgo build android --features networking,advanced

# Build without default features
ccgo build linux --no-default-features

# Build with specific features, no defaults
ccgo build linux --no-default-features --features minimal

# Build with all available features
ccgo build ios --all-features

CMake Integration

Features are passed to CMake as compile definitions with the CCGO_FEATURE_ prefix:

# In your CMakeLists.txt, check for features:
if(DEFINED CCGO_FEATURE_DEFINITIONS)
    foreach(def ${CCGO_FEATURE_DEFINITIONS})
        target_compile_definitions(${PROJECT_NAME} PRIVATE ${def})
    endforeach()
endif()

In your C++ code:

#ifdef CCGO_FEATURE_NETWORKING
#include "networking/http_client.h"
#endif

#ifdef CCGO_FEATURE_ADVANCED
void advanced_function() {
    // Advanced implementation
}
#endif

Feature Resolution

Features are resolved transitively:

1. Default features are enabled unless --no-default-features is specified
2. Requested features from --features are added
3. Transitive features are resolved (e.g., full enables advanced which enables networking)
4. Optional dependencies are included only if enabled by an active feature

Example resolution for --features full:

full → advanced, networking, logging
advanced → networking, async
networking → http-client (optional dep)

Result: full, advanced, networking, logging, async, http-client are all enabled.

Workspaces

CCGO supports workspaces for managing multiple related packages in a single repository. Workspaces provide:

• Unified dependency management across packages
• Shared configuration and settings
• Single-command builds for all packages

Creating a Workspace

Create a root CCGO.toml with a [workspace] section:

# Root CCGO.toml (workspace root)
[workspace]
members = [
    "core",
    "utils",
    "examples/*"      # Glob patterns supported
]
exclude = ["examples/deprecated"]
resolver = "2"        # Dependency resolver version

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

[[workspace.dependencies]]
name = "spdlog"
version = "^1.12"

Workspace Member Configuration

Member packages can inherit dependencies from the workspace:

# core/CCGO.toml
[package]
name = "my-core"
version = "1.0.0"

[[dependencies]]
name = "fmt"
workspace = true          # Inherit from workspace
features = ["extra"]      # Additional features (merged with workspace)

[[dependencies]]
name = "spdlog"
workspace = true

Workspace Structure

my-workspace/
├── CCGO.toml              # Workspace root configuration
├── core/
│   ├── CCGO.toml          # Member package
│   ├── CMakeLists.txt
│   └── src/
├── utils/
│   ├── CCGO.toml          # Member package
│   ├── CMakeLists.txt
│   └── src/
└── examples/
    ├── demo1/
    │   └── CCGO.toml      # Member (matched by glob)
    └── deprecated/
        └── CCGO.toml      # Excluded member

Workspace with Root Package

A workspace root can also be a package itself (virtual workspace):

[workspace]
members = ["crates/*"]

[package]
name = "my-workspace-root"
version = "1.0.0"

Dependency Inheritance

When a member uses workspace = true:

1. Version is inherited from workspace if not specified locally
2. Git/Path sources are inherited from workspace
3. Features are merged (workspace features + local features)
4. default_features uses workspace setting if not specified locally

# Workspace defines:
[[workspace.dependencies]]
name = "fmt"
version = "^10.0"
features = ["std"]

# Member uses:
[[dependencies]]
name = "fmt"
workspace = true
features = ["color"]  # Results in: ["std", "color"]

Resolver Versions

• resolver = "1" - Legacy resolver (default)
• resolver = "2" - New resolver with better feature unification across packages

Advanced Usage

Using Custom Templates

You can create projects from custom templates:

# From GitHub repository
ccgo new my-project --template-url=https://github.com/user/my-template.git

# From local directory
ccgo new my-project --template-url=/path/to/local/template

CI/CD Integration

The generated build.py script supports CI/CD workflows with environment variables:

• CI_IS_RELEASE - Build as release vs beta
• CI_BUILD_<PLATFORM> - Enable/disable platform builds

Example:

export CI_IS_RELEASE=1
export CI_BUILD_ANDROID=1
export CI_BUILD_IOS=1
python3 build.py

Multi-Architecture Builds

Build for multiple architectures simultaneously:

# Android: build for 32-bit ARM, 64-bit ARM, and x86_64
ccgo build android --arch armeabi-v7a,arm64-v8a,x86_64

# OHOS: build for all supported architectures
ccgo build ohos --arch armeabi-v7a,arm64-v8a,x86_64

Troubleshooting

Common Issues

1. "Command not found" after installation

   • Ensure the install directory is in your PATH
   • For pip: typically ~/.local/bin (Linux/macOS) or %APPDATA%\Python\Scripts (Windows)
   • For uv tool: typically ~/.local/bin
   • For cargo: typically ~/.cargo/bin

2. Android build fails

   • Verify ANDROID_HOME, ANDROID_NDK_HOME, and JAVA_HOME are set
   • Run ccgo check android --verbose to diagnose

3. OHOS build fails

   • Verify OHOS_SDK_HOME or HOS_SDK_HOME is set
   • Run ccgo check ohos --verbose to diagnose

4. iOS/macOS build fails

   • Ensure Xcode and command-line tools are installed
   • Run xcode-select --install if needed

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

ccgo is available under the MIT license. See the LICENSE file for the full license text.

Links

• GitHub Repository
• Crates.io Package
• PyPI Package
• Issue Tracker