ccgo 3.4.1

# 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**

```bash
# 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**

```bash
# 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:

```bash
# 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:

```bash
# 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)**:
```yaml
# .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)**:
```yaml
# .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)**:
```bash
#!/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)**:
```bash
#!/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)**:
```kotlin
// 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)**:
```kotlin
// 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**:
```kotlin
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:

```bash
# 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**:
```markdown
## Installation

### CCGO CLI (Rust - Recommended)

```bash
cargo install ccgo --locked
```

Or download pre-built binary from [Releases](https://github.com/zhlinh/ccgo/releases).

### Legacy Python CLI (Deprecated)

```bash
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**:
```bash
# 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.

```toml
[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**:
```bash
ccgo --version
# ccgo: command not found
```

**Solution**:
```bash
# 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**:
```bash
ccgo --version
# ccgo 3.0.10 (Python 3.11.5)  # Still Python!
```

**Solution**:
```bash
# 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**:
```bash
# 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](https://github.com/zhlinh/ccgo/issues) with logs.

---

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

**Symptom**:
```bash
ccgo vendor
# error: unrecognized subcommand 'vendor'
```

**Solution**: Use Python CLI for unimplemented commands:
```bash
# 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**:
```kotlin
// 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
```bash
# 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
```bash
# Bad - ambiguous
ccgo build android  # Could be Python or Rust
```

---

### 2. Document CLI Version in README

**✅ Do**: Specify minimum version
```markdown
## 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
```bash
# 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
```yaml
- name: Install CCGO
  run: |
    cargo install ccgo --locked --version 3.1.0
    ccgo --version
```

**Or use pre-built binary for speed**:
```yaml
- 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:
```bash
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:
```bash
# 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

- [CCGO Rust CLI Source](https://github.com/zhlinh/ccgo/tree/main/ccgo-rs)
- [CCGO Releases](https://github.com/zhlinh/ccgo/releases)
- [CCGO CLI Reference](../reference/cli.md)
- [CCGO GitHub Issues](https://github.com/zhlinh/ccgo/issues)

---

*This guide is part of the CCGO documentation. For questions or improvements, open an issue on [GitHub](https://github.com/zhlinh/ccgo/issues).*