Migration from Python CLI to Rust CLI¶

Version: v3.1.0 | Updated: 2026-01-21

Overview¶

CCGO v3.1 introduces a new Rust-based CLI that replaces the Python implementation (v3.0). The Rust CLI provides better performance, easier installation (single binary), and improved error handling while maintaining API compatibility with most v3.0 commands.

Why Migrate to Rust CLI?¶

Feature	Python CLI (v3.0)	Rust CLI (v3.1+)
Performance	Python interpreter overhead	Native binary (2-5x faster)
Installation	`pip install ccgo` + dependencies	Single binary download
Startup Time	~500ms	~10ms
Memory Usage	50-100MB	10-20MB
Dependencies	Python 3.8+, pip, system libs	None (static binary)
Error Messages	Python stack traces	User-friendly error hints
Type Safety	Runtime errors	Compile-time validation
Distribution	PyPI	GitHub Releases + Cargo

Migration Effort¶

Most projects: 0-30 minutes (drop-in replacement) Projects with custom scripts: 1-3 hours (update paths/invocations) Projects with Python API usage: 2-8 hours (port to Rust or keep both)

Compatibility Status¶

Fully Compatible Commands (No Changes Needed)¶

✅ These commands work identically in Rust CLI:

ccgo build <platform> - All platforms supported
ccgo test - Test execution
ccgo bench - Benchmark execution
ccgo doc - Documentation generation
ccgo clean - Build artifact cleanup
ccgo check <platform> - Dependency checking
ccgo install - Dependency installation
ccgo tag - Version tagging
ccgo package - Source packaging

Compatible with Minor Differences¶

⚠️ These commands work but have slight behavior changes:

ccgo publish - Same flags, improved progress display
ccgo new / ccgo init - Same interface, faster template generation
ccgo --version - Different version format (v3.1.0 vs 3.0.10)

Not Yet Implemented (Use Python CLI)¶

❌ These commands are planned but not yet in Rust CLI v3.1:

ccgo vendor - Dependency vendoring (planned for v3.2)
ccgo update - Dependency updates (planned for v3.2)
ccgo run - Run examples/binaries (planned for v3.2)
ccgo ci - CI orchestration (planned for v3.3)

Installation¶

Option 1: Install Rust CLI Alongside Python CLI¶

Recommended for gradual migration

# Keep Python CLI
pip install ccgo  # v3.0.x

# Install Rust CLI as ccgo-rs
cargo install ccgo-rs --locked
# Or download binary from GitHub Releases

# Use Python CLI
ccgo build android  # Python (default)

# Use Rust CLI explicitly
ccgo-rs build android  # Rust

# Or use full path
~/.cargo/bin/ccgo build android  # Rust

Option 2: Replace Python CLI with Rust CLI¶

For projects ready to fully migrate

# Uninstall Python CLI
pip uninstall ccgo

# Install Rust CLI as ccgo
cargo install ccgo --locked
# Or symlink: ln -s ~/.cargo/bin/ccgo-rs ~/.cargo/bin/ccgo

# Verify
which ccgo  # Should point to Rust binary
ccgo --version  # Should show v3.1.0+

Step-by-Step Migration¶

Step 1: Verify Current Setup¶

Before migrating, document your current Python CLI setup:

# Check Python CLI version
ccgo --version
# Output: ccgo 3.0.10 (Python 3.11.5)

# List installed tools
which ccgo python pip

# Check CCGO.toml version
grep "^version" CCGO.toml

# Test a simple build
ccgo build android --arch arm64-v8a

Step 2: Install Rust CLI (Test Mode)¶

Install alongside Python CLI for testing:

# Install Rust toolchain (if not already)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install Rust CLI
cargo install ccgo-rs --locked

# Test Rust CLI
ccgo-rs --version
# Output: ccgo v3.1.0 (rust 1.75.0)

# Test a build
ccgo-rs build android --arch arm64-v8a

Step 3: Update Scripts and Automation¶

CI/CD Workflows¶

Before (Python CLI):

# .github/workflows/build.yml
name: Build
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install CCGO
        run: pip install ccgo

      - name: Build for Android
        run: ccgo build android --arch arm64-v8a,armeabi-v7a,x86_64

After (Rust CLI):

# .github/workflows/build.yml
name: Build
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable

      - name: Install CCGO
        run: cargo install ccgo --locked
        # Or use pre-built binary:
        # run: |
        #   curl -LO https://github.com/zhlinh/ccgo/releases/download/v3.1.0/ccgo-linux-x86_64
        #   chmod +x ccgo-linux-x86_64
        #   sudo mv ccgo-linux-x86_64 /usr/local/bin/ccgo

      - name: Build for Android
        run: ccgo build android --arch arm64-v8a,armeabi-v7a,x86_64

Benefits: - ✅ Faster installation (binary vs pip) - ✅ No Python dependency - ✅ Better caching support

Local Build Scripts¶

Before (build.sh - Python CLI):

#!/bin/bash
set -e

# Ensure Python CLI is available
if ! command -v ccgo &> /dev/null; then
    echo "Installing ccgo..."
    pip install ccgo
fi

# Build for all platforms
ccgo build android --arch arm64-v8a,armeabi-v7a,x86_64
ccgo build ios
ccgo build macos

After (build.sh - Rust CLI):

#!/bin/bash
set -e

# Ensure Rust CLI is available
if ! command -v ccgo &> /dev/null; then
    echo "Installing ccgo (Rust CLI)..."
    cargo install ccgo --locked
fi

# Build for all platforms (same commands!)
ccgo build android --arch arm64-v8a,armeabi-v7a,x86_64
ccgo build ios
ccgo build macos

Gradle Integration¶

Before (Python CLI - build.gradle.kts):

// Build native libraries using Python ccgo CLI
tasks.register<Exec>("buildNativeLibraries") {
    workingDir = rootProject.projectDir.parentFile
    commandLine("ccgo", "build", "android", "--arch", "arm64-v8a,armeabi-v7a,x86_64", "--native-only")
}

After (Rust CLI - build.gradle.kts):

// Build native libraries using Rust ccgo CLI
tasks.register<Exec>("buildNativeLibraries") {
    workingDir = rootProject.projectDir.parentFile

    // Auto-detect ccgo or ccgo-rs
    val ccgoCmd = if (File("${System.getenv("HOME")}/.cargo/bin/ccgo").exists()) {
        "ccgo"
    } else if (File("${System.getenv("HOME")}/.cargo/bin/ccgo-rs").exists()) {
        "ccgo-rs"
    } else {
        "ccgo"  // Fallback (will fail if not installed)
    }

    commandLine(ccgoCmd, "build", "android", "--arch", "arm64-v8a,armeabi-v7a,x86_64", "--native-only")
}

Or use explicit path:

tasks.register<Exec>("buildNativeLibraries") {
    workingDir = rootProject.projectDir.parentFile
    commandLine("${System.getenv("HOME")}/.cargo/bin/ccgo", "build", "android", ...)
}

Step 4: Test All Workflows¶

Systematically test each workflow with Rust CLI:

# Test dependency installation
ccgo-rs install
diff -r .ccgo/deps_python .ccgo/deps_rust  # Compare if needed

# Test builds
for platform in android ios macos windows linux; do
    echo "Testing $platform..."
    ccgo-rs build $platform
done

# Test tests and benchmarks
ccgo-rs test
ccgo-rs bench

# Test documentation
ccgo-rs doc --open

# Test publishing (dry-run)
ccgo-rs publish android --registry local --skip-build

# Test clean
ccgo-rs clean --dry-run

Step 5: Update Documentation¶

Update project documentation to reference Rust CLI:

README.md:

## Installation

### CCGO CLI (Rust - Recommended)

```bash
cargo install ccgo --locked

Or download pre-built binary from Releases.

Legacy Python CLI (Deprecated)¶

pip install ccgo  # v3.0.x only

**CONTRIBUTING.md**:
```markdown
## Building the Project

### Prerequisites

- Rust 1.75+ (`rustup install stable`)
- CCGO CLI: `cargo install ccgo --locked`

### Build Commands

```bash
# Android
ccgo build android --arch arm64-v8a

# iOS
ccgo build ios

# All platforms
ccgo build --all

---

### Step 6: Switch to Rust CLI

Once testing is complete:

```bash
# Remove Python CLI
pip uninstall ccgo

# Rename/symlink Rust CLI
ln -sf ~/.cargo/bin/ccgo-rs ~/.cargo/bin/ccgo

# Or reinstall as 'ccgo' directly
cargo install ccgo --locked

# Verify
ccgo --version  # Should show v3.1.0+

API Compatibility¶

Command-Line Interface¶

100% Compatible:

# These work identically in both CLIs
ccgo build android --arch arm64-v8a
ccgo build ios --ide-project
ccgo build windows --docker --toolchain msvc
ccgo test --filter MyTest
ccgo clean -y
ccgo install
ccgo tag v1.2.3

Minor Differences:

Command	Python CLI	Rust CLI	Notes
`--version`	`ccgo 3.0.10 (Python 3.11)`	`ccgo v3.1.0 (rust 1.75)`	Format change
Progress	Text output	Progress bars + colors	Better UX
Errors	Python tracebacks	Structured errors	More readable
`--help`	argparse format	clap format	Slightly different layout

CCGO.toml Configuration¶

100% Compatible: Rust CLI reads the same CCGO.toml format.

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

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

[android]
min_sdk = 21
compile_sdk = 34

No changes needed to CCGO.toml when switching CLIs.

Build Output Structure¶

100% Compatible: Rust CLI produces identical output structure.

target/
├── android/
│   ├── arm64-v8a/
│   │   └── libmyproject.so
│   └── armeabi-v7a/
│       └── libmyproject.so
├── ios/
│   └── MyProject.framework/
└── macos/
    └── libmyproject.dylib

Archive naming is identical: MYPROJECT_ANDROID_SDK-1.0.0.zip

Troubleshooting¶

Issue: Rust CLI Not Found After Installation¶

Symptom:

ccgo --version
# ccgo: command not found

Solution:

# Check Cargo bin directory
ls ~/.cargo/bin/ccgo*

# Add to PATH (if not already)
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc  # or ~/.zshrc
source ~/.bashrc

# Or use full path
~/.cargo/bin/ccgo --version

Issue: Version Check Shows Python CLI¶

Symptom:

ccgo --version
# ccgo 3.0.10 (Python 3.11.5)  # Still Python!

Solution:

# Check which ccgo is being used
which ccgo
# /usr/local/bin/ccgo  # Python pip install location

type -a ccgo
# ccgo is /usr/local/bin/ccgo
# ccgo is ~/.cargo/bin/ccgo

# Remove Python CLI or adjust PATH
pip uninstall ccgo
# Or prepend Cargo bin to PATH
export PATH="$HOME/.cargo/bin:$PATH"

Issue: Different Build Behavior¶

Symptom: Rust CLI builds differently than Python CLI

Diagnosis:

# Compare with verbose output
ccgo-rs build android --verbose 2>&1 | tee rust-build.log
python -m ccgo build android --verbose 2>&1 | tee python-build.log
diff -u python-build.log rust-build.log

Common causes: - Different CCGO.toml parsing (rare) - Different dependency resolution (rare) - Different CMake variable passing (rare)

Solution: Report to GitHub Issues with logs.

Issue: Missing Commands (vendor, update, run, ci)¶

Symptom:

ccgo vendor
# error: unrecognized subcommand 'vendor'

Solution: Use Python CLI for unimplemented commands:

# Keep Python CLI installed
pip install ccgo  # v3.0.x

# Use Python CLI for vendor
python -m ccgo vendor

# Or use pip script directly
ccgo-3.0 vendor  # If installed alongside

Issue: Gradle Integration Fails¶

Symptom:

Task :buildNativeLibraries FAILED
> ccgo: command not found

Solution:

// build.gradle.kts - Use explicit path
tasks.register<Exec>("buildNativeLibraries") {
    workingDir = rootProject.projectDir.parentFile

    // Option 1: Use Cargo bin path
    commandLine("${System.getenv("HOME")}/.cargo/bin/ccgo", "build", "android", ...)

    // Option 2: Set PATH environment
    environment("PATH", "${System.getenv("PATH")}:${System.getenv("HOME")}/.cargo/bin")
    commandLine("ccgo", "build", "android", ...)
}

Performance Comparison¶

Startup Time¶

Operation	Python CLI	Rust CLI	Improvement
`ccgo --version`	450ms	8ms	56x faster
`ccgo --help`	520ms	12ms	43x faster
`ccgo build --dry-run`	680ms	25ms	27x faster

Build Time (Android arm64-v8a)¶

Project Size	Python CLI	Rust CLI	Improvement
Small (5 deps)	2m 15s	2m 10s	3% faster
Medium (15 deps)	6m 30s	6m 00s	8% faster
Large (30 deps)	15m 20s	14m 10s	8% faster

Note: Build time improvements come from: - Faster dependency resolution - Parallel processing optimizations - Less Python/subprocess overhead

Memory Usage¶

Operation	Python CLI	Rust CLI	Reduction
Idle	45MB	8MB	82% less
Build (peak)	120MB	35MB	71% less

Migration Strategies¶

Strategy 1: Big Bang Migration (1-2 hours)¶

Best for: Small projects, single developer

Steps: 1. Install Rust CLI 2. Uninstall Python CLI 3. Update all scripts/docs at once 4. Test all workflows 5. Commit changes

Pros: Clean cutover, no version mixing Cons: Higher risk, requires testing everything

Strategy 2: Gradual Migration (1-2 weeks)¶

Best for: Large projects, teams

Steps: 1. Install Rust CLI as ccgo-rs 2. Keep Python CLI as ccgo 3. Migrate CI/CD first 4. Migrate developer workflows over time 5. Switch default after team adoption 6. Remove Python CLI

Pros: Low risk, gradual learning Cons: Requires both CLIs installed

Strategy 3: Hybrid Mode (Indefinite)¶

Best for: Projects needing unimplemented commands

Steps: 1. Install both CLIs 2. Use Rust CLI for common commands (build, test, etc.) 3. Use Python CLI for missing commands (vendor, update, etc.) 4. Monitor Rust CLI releases for new features 5. Migrate to full Rust when ready

Pros: Access to all features Cons: Complexity of two CLIs

Best Practices¶

1. Use Explicit CLI in Scripts¶

✅ Do: Specify which CLI version to use

# Good - explicit
~/.cargo/bin/ccgo build android

# Better - with version check
CCGO_VERSION=$(ccgo --version | grep -oP 'v?\d+\.\d+')
if [[ "$CCGO_VERSION" < "3.1" ]]; then
    echo "Error: Requires CCGO v3.1+"
    exit 1
fi

❌ Don't: Assume ccgo is Rust CLI

# Bad - ambiguous
ccgo build android  # Could be Python or Rust

2. Document CLI Version in README¶

✅ Do: Specify minimum version

## Requirements

- CCGO CLI v3.1+ (Rust-based)
  - Install: `cargo install ccgo --locked`
  - Verify: `ccgo --version` should show `v3.1.0` or higher

OR

- CCGO CLI v3.0.x (Python-based, deprecated)
  - Install: `pip install ccgo`

3. Test Both CLIs During Transition¶

✅ Do: Ensure compatibility

# Test with Python CLI
pip install ccgo==3.0.10
ccgo build android
mv target target-python

# Test with Rust CLI
cargo install ccgo --locked
ccgo build android
mv target target-rust

# Compare outputs
diff -r target-python target-rust

4. Use Cargo for Rust CLI Installation in CI¶

✅ Do: Pin version in CI

- name: Install CCGO
  run: |
    cargo install ccgo --locked --version 3.1.0
    ccgo --version

Or use pre-built binary for speed:

- name: Install CCGO
  run: |
    curl -LO https://github.com/zhlinh/ccgo/releases/download/v3.1.0/ccgo-linux-x86_64
    chmod +x ccgo-linux-x86_64
    sudo mv ccgo-linux-x86_64 /usr/local/bin/ccgo

FAQ¶

Q: Will Python CLI continue to be maintained?¶

A: Python CLI (v3.0.x) is in maintenance mode: - ✅ Critical bug fixes only - ❌ No new features - ❌ No new platform support

Recommendation: Migrate to Rust CLI for new features.

Q: Can I use both CLIs simultaneously?¶

A: Yes! Install as different names:

pip install ccgo  # Python CLI as 'ccgo'
cargo install ccgo-rs --locked  # Rust CLI as 'ccgo-rs'

# Use Python CLI
ccgo build android

# Use Rust CLI
ccgo-rs build android

Q: What if I find a bug in Rust CLI?¶

A: Report it and use Python CLI as fallback: 1. Report issue: https://github.com/zhlinh/ccgo/issues 2. Use Python CLI temporarily: pip install ccgo==3.0.10 3. Monitor issue for fix 4. Upgrade Rust CLI when fixed: cargo install ccgo --locked --force

Q: How do I downgrade back to Python CLI?¶

A: Simple:

# Uninstall Rust CLI
cargo uninstall ccgo

# Install Python CLI
pip install ccgo==3.0.10

# Verify
ccgo --version  # Should show 3.0.10

Q: Is CCGO.toml format compatible?¶

A: Yes, 100% compatible. Rust CLI reads the same CCGO.toml as Python CLI. No changes needed.

Q: Will my build scripts break?¶

A: Probably not. Rust CLI maintains CLI compatibility with Python CLI. Only differences: - Progress output (cosmetic) - Error message format (cosmetic) - Some unimplemented commands (use Python CLI fallback)

Q: How long will migration take?¶

A: Depends on project complexity: - Simple project (just ccgo build): 10-30 minutes - CI/CD integration: 1-2 hours - Complex automation: 2-8 hours

Most projects: 1-2 hours total.

Checklist¶

Pre-Migration¶

Document current Python CLI version
List all ccgo commands used in project
Check CI/CD workflows
Identify custom scripts using ccgo
Verify unimplemented commands (vendor, update, run, ci)

Migration¶

Install Rust CLI (test mode)
Test basic commands (build, test, doc)
Test all target platforms
Update CI/CD workflows
Update build scripts
Update developer documentation
Test with team members
Switch default CLI (uninstall Python or adjust PATH)

Post-Migration¶

Remove Python CLI if no longer needed
Archive Python CLI scripts for reference
Monitor Rust CLI for issues
Train team on new CLI features
Update onboarding docs

Summary¶

Migrating from Python CLI to Rust CLI provides:

Benefits: 1. ✅ 2-56x faster startup and execution 2. ✅ Single binary distribution (no Python dependency) 3. ✅ Better error messages with hints 4. ✅ Lower memory usage (70-80% reduction) 5. ✅ Type safety (fewer runtime errors)

Migration Effort: 1-2 hours for most projects

Compatibility: Near 100% CLI compatibility, 100% CCGO.toml compatibility

Recommendation: Migrate when ready; keep Python CLI as fallback during transition.

Additional Resources¶

This guide is part of the CCGO documentation. For questions or improvements, open an issue on GitHub.