🐦 buck2-cpp-cpm

Transform CMake projects to Buck2 with confidence - A CPM-aware migration tool

---

🚀 What is buck2-cpp-cpm?

buck2-cpp-cpm is a powerful migration tool that automatically converts CMake projects to Buck2, with special support for CPM.cmake package manager. Born from the flight-core team's need to modernize build systems across diverse platforms—from cutting-edge servers to retro gaming consoles like the Sega Dreamcast. buck2-cpp-cpm makes build system migration painless and reliable.

✨ Features

• ✅ Smart CMake Analysis - Understands complex CMake configurations and dependencies
• ✅ CPM.cmake Support - First-class support for CPM package manager migrations
• ✅ Buck2 Code Generation - Generates clean, maintainable Buck2 BUCK files
• ✅ Cross-Platform Ready - Works with projects targeting everything from embedded systems to modern platforms
• ✅ C++20 Compatible - Modern C++ with robust error handling and logging
• ✅ Dependency Resolution - Intelligently maps CMake dependencies to Buck2 equivalents
• ✅ Template System - Flexible rule generation with customizable templates
• ✅ Starlark Output - Generates properly formatted Buck2 Starlark files
• 🔧 CLI Interface - Command-line tool for easy integration (in final testing)
• 🔧 Interactive Mode - Guided migration with user prompts (planned)
• 🔧 Incremental Migration - Supports gradual migration of large projects (planned)

Legend: ✅ Implemented | 🔧 In Development

🎯 Why buck2-cpp-cpm?

The Problem

Migrating from CMake to Buck2 is traditionally a manual, error-prone process that can take weeks or months for complex projects. The challenge becomes even greater when dealing with CPM.cmake dependencies or projects targeting specialized platforms.

The Solution

buck2-cpp-cpm automates this migration process, handling the complexity of:

• Parsing CMake syntax and understanding project structure
• Converting CMake targets (add_library, add_executable) to Buck2 rules
• Converting CPM package declarations to Buck2 dependencies
• Generating appropriate BUCK files with correct dependency graphs
• Maintaining compatibility across diverse build targets

🚀 Quick Start

Prerequisites

• CMake 3.20+ - For building the project
• C++20 compatible compiler - GCC 10+, Clang 12+, or MSVC 2019+
• Git - For cloning and submodule management

Installation

# Clone the repository
git clone https://github.com/punk1290/buck2-cpp-cpm.git
cd buck2-cpp-cpm

# Quick setup (automated)
./scripts/setup-dev.sh

# Or manual setup
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

# The buck2-cpp-cpm binary will be in build/bin/buck2-cpp-cpm

Your First Migration

Let's migrate a simple CMake project:

# Example CMake project structure
mkdir my-project
cd my-project

# Create a simple CMakeLists.txt
cat > CMakeLists.txt << 'EOF'
cmake_minimum_required(VERSION 3.20)
project(calculator VERSION 1.0.0)

add_library(calculator STATIC
    src/calculator.cpp
)

target_include_directories(calculator PUBLIC include)
EOF

# Create source files
mkdir -p src include/calculator
echo '#include "calculator.h"
int add(int a, int b) { return a + b; }' > src/calculator.cpp
echo 'int add(int a, int b);' > include/calculator/calculator.h

# Run buck2-cpp-cpm migration
/path/to/buck2-cpp-cpm/build/bin/buck2-cpp-cpm migrate .

# Check the generated BUCK file
cat BUCK

Expected output:

load("@prelude//cxx:cxx.bzl", "cxx_library")

cxx_library(
    name = "calculator",
    srcs = [
        "src/calculator.cpp",
    ],
    headers = glob(["**/*.h", "**/*.hpp"]),
    visibility = ["PUBLIC"],
    header_namespace = "calculator",
)

📚 Usage

Basic Migration

# Migrate current directory
buck2-cpp-cpm migrate .

# Migrate specific directory with custom output
buck2-cpp-cpm migrate /path/to/cmake/project --output /path/to/buck2/project

# Dry run to preview changes
buck2-cpp-cpm migrate . --dry-run

# Interactive mode with guidance
buck2-cpp-cpm migrate . --interactive

Advanced Options

# Target specific platforms
buck2-cpp-cpm migrate . --platform linux --platform macos

# Enable verbose output
buck2-cpp-cpm migrate . --verbose

# Use custom configuration
buck2-cpp-cpm migrate . --config custom.buck2-cpp-cpm.toml

# Overwrite existing BUCK files
buck2-cpp-cpm migrate . --overwrite

CPM Support

For projects using CPM.cmake:

# Input CMakeLists.txt with CPM
include(CPM.cmake)

CPMAddPackage(
    NAME fmt
    GITHUB_REPOSITORY fmtlib/fmt
    GIT_TAG 10.0.0
)

add_executable(app main.cpp)
target_link_libraries(app fmt::fmt)

Generated BUCK file:

load("@prelude//cxx:cxx.bzl", "cxx_binary")

cxx_binary(
    name = "app",
    srcs = ["main.cpp"],
    deps = ["@fmt//:fmt"],
)

Validation and Analysis

# Analyze project complexity before migration
buck2-cpp-cpm analyze /path/to/cmake/project

# Validate existing CMake files
buck2-cpp-cpm validate /path/to/cmake/project

# Initialize buck2-cpp-cpm configuration
buck2-cpp-cpm init /path/to/project

🏗️ Project Architecture

finch-buck2/
├── include/finch/           # Public API headers
│   ├── core/               # Core utilities (logging, errors, result types)
│   ├── parser/             # CMake and CPM parsing
│   ├── analyzer/           # Semantic analysis
│   ├── generator/          # Buck2 code generation
│   ├── cli/                # Command-line interface
│   └── testing/            # Testing utilities
├── src/                    # Implementation source files
├── test/                   # Unit and integration tests
│   ├── projects/           # Test CMake projects
│   └── integration/        # End-to-end tests
├── examples/               # Example migrations
├── docs/                   # Documentation
├── tools/                  # Build scripts and utilities
└── proompts/               # Development documentation

🔨 Development Environment

Quick Setup

We provide an automated setup script that configures the entire development environment:

# Clone and setup
git clone https://github.com/punk1290/finch-buck2.git
cd finch-buck2
./scripts/setup-dev.sh

The setup script will:

• ✅ Verify required tools (CMake 3.20+, C++20 compiler, Python 3.8+)
• ✅ Install and configure pre-commit hooks
• ✅ Set up the build directory with optimal settings
• ✅ Build the project and run tests
• ✅ Create IDE integration files (VSCode support included)

Manual Development Setup

# Install dependencies
cmake --version  # Ensure 3.20+
g++ --version    # Ensure C++20 support

# Setup pre-commit hooks
pip3 install pre-commit
pre-commit install

# Configure build
cmake -B build \
  -DCMAKE_BUILD_TYPE=Debug \
  -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
  -DFINCH_BUILD_TESTS=ON \
  -DFINCH_BUILD_EXAMPLES=ON

# Build and test
cmake --build build --parallel
cd build && ctest --output-on-failure

IDE Support

VSCode (Recommended):

• Pre-configured settings in .vscode/
• IntelliSense with compile commands
• Integrated debugging and testing
• Code formatting and linting

CLion:

• CMake integration works out of the box
• Import project and select build directory

Vim/Neovim:

• Use compile_commands.json for LSP support

Code Quality Tools

# Format all code
find src include -name "*.cpp" -o -name "*.hpp" | xargs clang-format -i

# Run static analysis
clang-tidy src/**/*.cpp -p build

# Run all quality checks
pre-commit run --all-files

🧪 Testing

Running Tests

# All tests
cmake --build build && cd build && ctest

# Specific test categories
ctest -R unit        # Unit tests only
ctest -R integration # Integration tests only
ctest -R parser      # Parser tests only

# Verbose test output
ctest --output-on-failure --verbose

Test Structure

• Unit Tests: Test individual components (parser, analyzer, generator)
• Integration Tests: End-to-end migration tests with real projects
• Golden File Tests: Compare generated output with expected results
• Performance Tests: Ensure migration speed meets requirements

Adding New Tests

# Create test project
mkdir test/projects/my-test-case
# Add CMakeLists.txt and source files
# Add expected BUCK file as BUCK.expected

# Run integration test
./build/bin/finch migrate test/projects/my-test-case
diff test/projects/my-test-case/BUCK test/projects/my-test-case/BUCK.expected

🛠️ Configuration

Project Configuration (.buck2-cpp-cpm.toml)

[migration]
default_platforms = ["linux", "macos", "windows"]
preserve_comments = true
generate_tests = true
output_style = "pretty"

[templates]
cxx_library = "default"
cxx_binary = "default"
custom_template_dir = "./templates"

[dependencies]
auto_resolve_unknowns = true

[dependencies.package_mappings]
"fmt::fmt" = "@fmt//:fmt"
"spdlog::spdlog" = "@spdlog//:spdlog"

Custom Templates

Create custom Buck2 rule templates:

# templates/custom_library.template
load("@prelude//cxx:cxx.bzl", "cxx_library")

cxx_library(
    name = "{{name}}",
    srcs = {{srcs}},
    headers = {{headers}},
    visibility = ["PUBLIC"],
    # Custom attributes
    linker_flags = ["-static"],
)

🤝 Contributing

We welcome contributions! Here's how to get started:

Quick Contribution Guide

1. Fork the repository on GitHub
2. Clone your fork locally
3. Run the setup script: ./scripts/setup-dev.sh
4. Create a feature branch: git checkout -b feature/amazing-feature
5. Make your changes and add tests
6. Run tests: cmake --build build && cd build && ctest
7. Run quality checks: pre-commit run --all-files
8. Commit and push your changes
9. Open a Pull Request with description of changes

Areas for Contribution

• 🔧 CMake Feature Support: Add support for new CMake commands and patterns
• 🔧 Buck2 Rules: Expand Buck2 rule generation capabilities
• 🔧 Platform Support: Improve cross-platform compatibility
• 📚 Documentation: Improve guides and examples
• 🧪 Testing: Add test cases for edge cases and real projects
• 🚀 Performance: Optimize parsing and generation speed
• 🎨 User Experience: Improve CLI interface and error messages

Development Workflow

# Start new feature
git checkout -b feature/my-feature

# Make changes and test
vim src/parser/new_feature.cpp
cmake --build build && cd build && ctest

# Check code quality
pre-commit run --all-files

# Commit changes
git add .
git commit -m "Add support for new CMake feature"

# Push and create PR
git push origin feature/my-feature

See CONTRIBUTING.md for detailed guidelines.

📊 Current Status

What's Working ✅

• Core Parser: CMake and CPM.cmake parsing
• Semantic Analysis: Project structure understanding
• Buck2 Generation: BUCK file generation with proper Starlark syntax
• Target Mapping: add_library → cxx_library, add_executable → cxx_binary
• Dependency Resolution: Basic CMake to Buck2 dependency mapping
• File I/O: Writing generated files with proper formatting
• Build System: Complete CMake build with dependencies
• Testing Framework: Unit and integration tests

In Progress 🔧

• CLI Polish: Final CLI integration and error handling
• Advanced Templates: Custom rule templates
• Platform Logic: Cross-platform select() generation
• Interactive Mode: User-guided migration
• Documentation: Complete user guides

Planned 📋

• Buck2 Validation: Verify generated files build with Buck2
• Complex Projects: Support for larger, more complex CMake projects
• Plugin System: Extensible architecture for custom transformations
• Performance Optimization: Faster processing of large projects

🎮 Platform Support

finch-buck2 is designed to work with projects targeting a wide range of platforms:

• Modern Platforms: Linux, macOS, Windows
• Embedded Systems: ARM Cortex, ESP32, Arduino
• Specialized Hardware: Custom silicon, FPGA targets
• Retro Gaming: Sega Dreamcast, PlayStation, Nintendo platforms

The C++20 standard ensures compatibility with modern toolchains while providing powerful language features for robust parsing and generation.

📈 Performance

Current benchmarks on real projects:

• Small Projects (1-5 targets): < 100ms
• Medium Projects (10-50 targets): < 1 second
• Large Projects (100+ targets): < 10 seconds
• Memory Usage: < 100MB for most projects

🐛 Troubleshooting

Common Issues

Build Errors:

# Ensure C++20 support
g++ -std=c++20 -E - < /dev/null

# Clean rebuild
rm -rf build && cmake -B build && cmake --build build

Migration Issues:

# Enable verbose output
finch migrate . --verbose

# Check CMake parsing
finch analyze . --debug

Buck2 Validation:

# Install Buck2
buck2 --version

# Validate generated files
buck2 query //... --target-hash

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• flight-core team within birbparty organization for the initial vision
• Buck2 community for the excellent build system
• CMake community for comprehensive documentation
• Contributors who help make finch-buck2 better

📚 Learn More

• Buck2 Documentation
• CMake Documentation
• CPM.cmake Documentation
• finch-buck2 Examples

---

🐦 Ready to migrate? Let finch-buck2 handle the complexity while you focus on building amazing software.

Need help? Open an issue on GitHub or join our discussion forum!