Configuration Guide¶

Complete guide to configuring CCGO projects through CCGO.toml and other configuration files.

Overview¶

CCGO uses a file-based configuration system with:

CCGO.toml: Main project configuration
build_config.py: Build-specific settings (generated)
CMakeLists.txt: CMake integration
.ccgoignore: Files to exclude from operations
Environment variables: Runtime configuration

CCGO.toml¶

File Location¶

myproject/
├── CCGO.toml          # Main configuration
├── src/
├── include/
└── tests/

Basic Structure¶

[package]
name = "mylib"
version = "1.0.0"
description = "My cross-platform C++ library"
authors = ["Your Name <you@example.com>"]
license = "MIT"
homepage = "https://github.com/myuser/mylib"
repository = "https://github.com/myuser/mylib"

[library]
type = "both"                    # static, shared, or both

[build]
cpp_standard = "17"              # C++ standard version

[dependencies]
spdlog = { git = "https://github.com/gabime/spdlog.git", tag = "v1.12.0" }

[android]
min_sdk_version = 21

[ios]
deployment_target = "12.0"

Package Configuration¶

Required Fields¶

[package]
name = "mylib"                   # REQUIRED: Project name (lowercase, no spaces)
version = "1.0.0"                # REQUIRED: Semantic version

Optional Metadata¶

[package]
description = "A powerful C++ library for..."
authors = [
    "John Doe <john@example.com>",
    "Jane Smith <jane@example.com>"
]
license = "MIT"                  # License identifier
license_file = "LICENSE"         # Path to license file
readme = "README.md"             # Path to README
homepage = "https://mylib.dev"
repository = "https://github.com/user/mylib"
documentation = "https://docs.mylib.dev"
keywords = ["networking", "async", "performance"]
categories = ["network", "concurrency"]

Version Field¶

Version must follow Semantic Versioning:

[package]
version = "1.0.0"                # Major.Minor.Patch
# version = "1.0.0-alpha"        # Pre-release
# version = "1.0.0-beta.1"       # Pre-release with number
# version = "1.0.0+build.123"    # Build metadata

Rules: - MAJOR: Breaking changes - MINOR: New features (backward compatible) - PATCH: Bug fixes - Pre-release: Optional -alpha, -beta, -rc.N - Build metadata: Optional +build.N

Library Configuration¶

Library Type¶

[library]
type = "static"                  # Static library only
# type = "shared"                # Shared library only
# type = "both"                  # Both static and shared (default)

Static library: - Compiled into executable - Larger executable size - Faster startup - No runtime dependencies

Shared library: - Loaded at runtime - Smaller executable - Can be updated independently - Requires library at runtime

Both: - Builds both types - Users choose at link time

Library Naming¶

[library]
name = "mylib"                   # Override library name (optional)
# Default: uses package.name

Generated files: - Static: libmylib.a (Unix) / mylib.lib (Windows MSVC) - Shared: libmylib.so (Linux) / libmylib.dylib (macOS) / mylib.dll (Windows)

Build Configuration¶

C++ Standard¶

[build]
cpp_standard = "17"              # C++17 (recommended)
# cpp_standard = "11"            # C++11
# cpp_standard = "14"            # C++14
# cpp_standard = "20"            # C++20
# cpp_standard = "23"            # C++23

Support by platform: - C++11: All platforms - C++14: All platforms - C++17: All platforms (recommended) - C++20: Modern compilers only - C++23: Cutting-edge compilers

Build Types¶

[build]
default_build_type = "release"   # Default: release
# default_build_type = "debug"   # For development

Debug: - No optimization - Debug symbols - Assertions enabled - Larger binary size

Release: - Full optimization - Stripped symbols (separate file) - Assertions disabled - Smaller binary size

Compiler Flags¶

[build]
cflags = ["-Wall", "-Wextra"]                    # C flags
cxxflags = ["-Wall", "-Wextra", "-pedantic"]     # C++ flags
ldflags = ["-Wl,-rpath,$ORIGIN"]                 # Linker flags

Common flags:

[build]
# Warnings
cxxflags = [
    "-Wall",                     # All warnings
    "-Wextra",                   # Extra warnings
    "-Werror",                   # Treat warnings as errors
    "-pedantic"                  # Strict ISO C++
]

# Optimization
cxxflags = [
    "-O3",                       # Maximum optimization
    "-march=native",             # CPU-specific optimization
    "-flto"                      # Link-time optimization
]

# Security
cxxflags = [
    "-fstack-protector-strong",  # Stack protection
    "-D_FORTIFY_SOURCE=2",       # Buffer overflow detection
    "-fPIC"                      # Position independent code
]

Defines¶

[build]
defines = [
    "USE_FEATURE_X",             # Simple define
    "MAX_CONNECTIONS=100",       # Define with value
    "DEBUG_LOGGING"              # Debug-only define
]

Platform-specific defines:

[build.android]
defines = ["ANDROID_PLATFORM"]

[build.ios]
defines = ["IOS_PLATFORM"]

[build.windows]
defines = ["WINDOWS_PLATFORM", "_WIN32_WINNT=0x0601"]

Include Directories¶

[build]
include_dirs = [
    "include",                   # Public headers
    "src/internal",              # Private headers
    "third_party/lib/include"    # Third-party includes
]

Source Files¶

By default, CCGO compiles all .cpp/.cc/.cxx files in src/. Override:

[build]
sources = [
    "src/**/*.cpp",              # All .cpp in src/
    "src/core/*.cc",             # Specific directory
    "src/platform/linux/*.cpp"   # Platform-specific
]

exclude = [
    "src/experimental/**",       # Exclude directory
    "src/**/*_test.cpp"          # Exclude test files
]

Dependency Configuration¶

Git Dependencies¶

[dependencies]
# Tag (recommended for stability)
spdlog = { git = "https://github.com/gabime/spdlog.git", tag = "v1.12.0" }

# Branch (for latest features)
fmt = { git = "https://github.com/fmtlib/fmt.git", branch = "master" }

# Commit hash (for exact reproducibility)
json = { git = "https://github.com/nlohmann/json.git", rev = "9cca280a" }

Path Dependencies¶

[dependencies]
# Relative path
myutils = { path = "../myutils" }

# Absolute path
common = { path = "/opt/libs/common" }

# Workspace dependency
core = { path = "./libs/core" }

Registry Dependencies¶

Declare a Git-backed package index in [registries], then reference its packages by name + version in [[dependencies]]:

[registries]
# Map key = registry name, value = index repository URL
mna = "git@git.example.com:org/ccgo-index.git"
public = "https://github.com/example-org/ccgo-packages.git"

[[dependencies]]
name = "stdcomm"
version = "25.2.9519653"
registry = "mna"          # Pin lookup to a specific registry

[[dependencies]]
name = "fmt"
version = "10.2.1"
# No `registry = ...` — ccgo walks all declared registries in
# TOML declaration order; first match wins.

ccgo fetch clones each registry index into ~/.ccgo/registries/<name>/, finds the requested version in the package's JSON entry, downloads the recorded archive_url, verifies the SHA-256 checksum, and extracts the archive into .ccgo/deps/<name>/. The consumer's CCGO.toml needs no git URL or zip URL — the index supplies them.

Field reference:

Key	Where	Type	Notes
`[registries]`	top-level table	`name = "git-url"` map	Each entry is a Git index repo.
`[[dependencies]].registry`	per-dep	optional `String`	Pins lookup to one named registry. Errors if the name is not in `[registries]`.
`[[dependencies]].version`	per-dep	required when using a registry	Exact-string match against `VersionEntry.version` in the index. Range syntax (`^1.0`, `~2.1`) is not yet parsed.

See Package Registry for the index JSON schema, the publisher CI snippet, and the resolution priority list.

Optional Dependencies¶

[dependencies]
# Required dependencies
spdlog = { git = "https://github.com/gabime/spdlog.git", tag = "v1.12.0" }

# Optional dependencies
[dependencies.optional]
networking = { git = "https://github.com/user/networking.git", tag = "v1.0.0" }
database = { git = "https://github.com/user/database.git", tag = "v2.0.0" }

Enable with features:

[features]
default = ["basic"]
basic = []
network = ["networking"]        # Enables networking dependency
db = ["database"]               # Enables database dependency
full = ["basic", "network", "db"]

Build with features:

ccgo build android --features network,db

Platform-Specific Dependencies¶

[dependencies]
common = { git = "https://github.com/user/common.git", tag = "v1.0.0" }

# Android-only
[target.'cfg(target_os = "android")'.dependencies]
android-log = { git = "https://github.com/user/android-log.git", tag = "v1.0.0" }

# iOS-only
[target.'cfg(target_os = "ios")'.dependencies]
ios-utils = { path = "./ios-utils" }

# Windows-only
[target.'cfg(target_os = "windows")'.dependencies]
win32-api = { git = "https://github.com/user/win32-api.git", tag = "v1.0.0" }

Platform-Specific Configuration¶

Android¶

[android]
min_sdk_version = 21             # Minimum API level
target_sdk_version = 34          # Target API level
ndk_version = "26.1.10909125"    # NDK version (optional)
stl = "c++_shared"               # STL type: c++_static, c++_shared
package_name = "com.example.mylib"  # Java package name

iOS¶

[ios]
deployment_target = "12.0"       # Minimum iOS version
enable_bitcode = false           # Bitcode support (deprecated)
enable_arc = true                # Automatic Reference Counting
frameworks = [                   # System frameworks
    "Foundation",
    "UIKit",
    "CoreGraphics"
]

macOS¶

[macos]
deployment_target = "10.15"      # Minimum macOS version
enable_hardened_runtime = true   # Hardened runtime
frameworks = [                   # System frameworks
    "Foundation",
    "AppKit"
]

Windows¶

[windows]
subsystem = "console"            # Subsystem: console, windows
runtime_library = "MD"           # Runtime: MT, MD, MTd, MDd
windows_sdk_version = "10.0"     # Windows SDK version

Linux¶

[linux]
min_glibc_version = "2.17"       # Minimum glibc version
link_pthread = true              # Link pthread
link_dl = true                   # Link libdl
link_rt = true                   # Link librt

OpenHarmony¶

[ohos]
api_version = 9                  # API version
package_name = "com.example.mylib"  # Package name

Features Configuration¶

Defining Features¶

[features]
# Default features (enabled automatically)
default = ["std"]

# Feature with no dependencies
std = []

# Feature that enables dependencies
network = ["cpp-httplib", "openssl"]

# Feature that enables other features
full = ["std", "network", "database"]

# Feature combinations
web = ["network", "json"]

Using Features¶

In code:

#ifdef CCGO_FEATURE_NETWORK
    // Network code
    #include <httplib.h>
#endif

#ifdef CCGO_FEATURE_DATABASE
    // Database code
    #include <sqlite3.h>
#endif

At build time:

# Build with specific features
ccgo build android --features network

# Build with multiple features
ccgo build android --features network,database

# Build with all features
ccgo build android --all-features

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

# Combine flags
ccgo build android --no-default-features --features network

Test Configuration¶

Test Settings¶

[test]
# Test framework (default: catch2)
framework = "catch2"             # catch2, gtest, or custom

# Test sources
sources = [
    "tests/**/*.cpp"
]

# Test dependencies
[test.dependencies]
catch2 = { git = "https://github.com/catchorg/Catch2.git", tag = "v3.4.0" }

Running Tests¶

# Run all tests
ccgo test

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

# Run with verbose output
ccgo test --verbose

Benchmark Configuration¶

Benchmark Settings¶

[bench]
# Benchmark framework
framework = "google-benchmark"   # google-benchmark or custom

# Benchmark sources
sources = [
    "benches/**/*.cpp"
]

# Benchmark dependencies
[bench.dependencies]
benchmark = { git = "https://github.com/google/benchmark.git", tag = "v1.8.3" }

Running Benchmarks¶

# Run all benchmarks
ccgo bench

# Run specific benchmark
ccgo bench --filter "MyBenchmark"

# With iterations
ccgo bench --iterations 1000

Documentation Configuration¶

Documentation Settings¶

[doc]
# Documentation generator
generator = "doxygen"            # doxygen or custom

# Source directories
source_dirs = [
    "include",
    "src",
    "docs"
]

# Output directory
output_dir = "target/doc"

Generating Documentation¶

# Generate documentation
ccgo doc

# Generate and open in browser
ccgo doc --open

Publishing Configuration¶

Package Metadata¶

[package]
name = "mylib"
version = "1.0.0"
authors = ["Your Name <you@example.com>"]
license = "MIT"
description = "My cross-platform library"
homepage = "https://github.com/user/mylib"
repository = "https://github.com/user/mylib"
documentation = "https://docs.mylib.dev"

Publishing Settings¶

[publish]
# Registries
registry = "default"             # Registry name

# Maven (Android)
[publish.maven]
group_id = "com.example"
artifact_id = "mylib"

# CocoaPods (Apple)
[publish.cocoapods]
pod_name = "MyLib"
swift_version = "5.0"

# OHPM (OpenHarmony)
[publish.ohpm]
package_name = "@example/mylib"

build_config.py¶

Generated file with build-specific configuration:

# build_config.py (auto-generated)

# Project information
PROJECT_NAME = "mylib"
PROJECT_VERSION = "1.0.0"

# Build settings
BUILD_TYPE = "release"
CPP_STANDARD = "17"
LIBRARY_TYPE = "both"

# Platforms
ANDROID_MIN_SDK = 21
IOS_DEPLOYMENT_TARGET = "12.0"

# Custom settings
CUSTOM_DEFINES = []
CUSTOM_FLAGS = []

Usage in build scripts:

from build_config import PROJECT_NAME, PROJECT_VERSION

print(f"Building {PROJECT_NAME} v{PROJECT_VERSION}")

.ccgoignore¶

Exclude files from CCGO operations:

# .ccgoignore

# Build directories
cmake_build/
target/
bin/

# IDE files
.vscode/
.idea/
*.swp

# OS files
.DS_Store
Thumbs.db

# Dependencies
vendor/
node_modules/

# Generated files
*.pyc
__pycache__/

Syntax: - # for comments - * wildcard for files - ** wildcard for directories - / to match from root - ! to negate (include)

Example:

# Ignore all .log files
*.log

# But include important.log
!important.log

# Ignore build/ in root only
/build/

# Ignore all build/ directories
**/build/

Environment Variables¶

Build-Time Variables¶

# Build type
export BUILD_TYPE=debug          # debug or release

# Verbosity
export CCGO_VERBOSE=1            # Verbose output

# Parallel builds
export CMAKE_BUILD_PARALLEL_LEVEL=8  # Use 8 cores

# Architecture
export ANDROID_ARCH=arm64-v8a    # Android architecture

Platform-Specific Variables¶

Android:

export ANDROID_HOME=/path/to/android-sdk
export ANDROID_NDK_HOME=/path/to/ndk
export ANDROID_MIN_SDK=21

iOS:

export CODE_SIGN_IDENTITY="Apple Development"
export DEVELOPMENT_TEAM="TEAM123456"
export IOS_DEPLOYMENT_TARGET="12.0"

Windows:

export MSVC_VERSION=2022         # Visual Studio version
export WINDOWS_SDK_VERSION=10.0.22621.0

Docker Variables¶

# Docker build
export USE_DOCKER=1              # Enable Docker builds

# Docker image
export DOCKER_IMAGE=ccgo-builder-linux:latest

Configuration Validation¶

Check Configuration¶

# Validate CCGO.toml
ccgo check

# Validate for specific platform
ccgo check android

# Verbose validation
ccgo check --verbose

Common Issues¶

Invalid version format:

Error: Invalid version '1.0' in CCGO.toml

Solution: Use semantic versioning (e.g., 1.0.0)

Missing required field:

Error: Missing required field 'name' in [package]

Solution: Add required field to CCGO.toml

Invalid dependency:

Error: Invalid dependency format for 'spdlog'

Solution: Check dependency syntax

Configuration Templates¶

Minimal Configuration¶

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

[library]
type = "static"

Standard Configuration¶

[package]
name = "mylib"
version = "1.0.0"
description = "My library"
authors = ["Your Name <you@example.com>"]
license = "MIT"

[library]
type = "both"

[build]
cpp_standard = "17"

[dependencies]
spdlog = { git = "https://github.com/gabime/spdlog.git", tag = "v1.12.0" }

[android]
min_sdk_version = 21

[ios]
deployment_target = "12.0"

Advanced Configuration¶

[package]
name = "mylib"
version = "1.0.0"
description = "Advanced C++ library"
authors = ["Team <team@example.com>"]
license = "MIT"
homepage = "https://mylib.dev"
repository = "https://github.com/user/mylib"

[library]
type = "both"

[build]
cpp_standard = "20"
cxxflags = ["-Wall", "-Wextra", "-Werror"]
defines = ["USE_ADVANCED_FEATURES"]

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

[dependencies.optional]
networking = { git = "https://github.com/user/networking.git", tag = "v1.0.0" }

[features]
default = ["basic"]
basic = []
network = ["networking"]
full = ["basic", "network"]

[android]
min_sdk_version = 21
target_sdk_version = 34
package_name = "com.example.mylib"

[ios]
deployment_target = "12.0"
frameworks = ["Foundation", "UIKit"]

[test]
framework = "catch2"

[test.dependencies]
catch2 = { git = "https://github.com/catchorg/Catch2.git", tag = "v3.4.0" }

Best Practices¶

1. Use Semantic Versioning¶

[package]
version = "1.0.0"                # Good: Major.Minor.Patch
# version = "1.0"                # Bad: Missing patch
# version = "v1.0.0"             # Bad: Don't include 'v' prefix

2. Pin Dependencies¶

[dependencies]
# Good: Specific tag
spdlog = { git = "https://github.com/gabime/spdlog.git", tag = "v1.12.0" }

# Bad: Tracking branch
# spdlog = { git = "https://github.com/gabime/spdlog.git", branch = "master" }

3. Organize Sections¶

# Good: Logical order
[package]
[library]
[build]
[dependencies]
[android]
[ios]

# Bad: Random order
[ios]
[package]
[dependencies]
[build]

4. Comment Your Config¶

[build]
# Enable all warnings
cxxflags = ["-Wall", "-Wextra"]

# Platform-specific optimization
defines = [
    "USE_SSE=1",                 # Enable SSE instructions
    "MAX_THREADS=8"              # Limit thread pool size
]

5. Keep It Simple¶

Only configure what you need:

# Good: Only necessary config
[package]
name = "mylib"
version = "1.0.0"

[library]
type = "static"

# Bad: Unnecessary config
# [build]
# cpp_standard = "17"            # Default is 17
# [library]
# name = "mylib"                 # Same as package.name

Migration Guide¶

From CMakeLists.txt¶

CMakeLists.txt:

project(mylib VERSION 1.0.0)
set(CMAKE_CXX_STANDARD 17)
add_library(mylib src/mylib.cpp)

CCGO.toml:

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

[build]
cpp_standard = "17"

From Conan¶

conanfile.txt:

[requires]
spdlog/1.12.0
fmt/10.1.1

[options]
spdlog:shared=False