Implement Cross-Platform Build System and PyPI Distribution

[tjdcs]

Currently the project uses a Mac-specific Makefile for building the C++ DeckLink wrapper library. We need a robust cross-platform build system that supports Windows, macOS, and Linux, with proper wheel packaging and PyPI distribution.

Current State

• Uses simple Makefile with hardcoded Mac paths (cpp/Makefile)
• Manual build process: cd cpp && make clean && make && cd ..
• C++ library built to bmd_sg/decklink/libdecklink.dylib (Mac-specific)
• Uses Hatchling as build backend in pyproject.toml
• Basic uv build for Python packaging
• No GitHub Actions for CI/CD
• No PyPI distribution setup

Proposed Implementation

Phase 1: Research and Select Build System

Evaluate modern build systems for Hatchling integration:

Research and compare options including:

• CMake + scikit-build-core: Modern CMake integration with Python packaging
• Meson + meson-python: Fast, modern build system with Python bindings
• pybind11 + setuptools-cpp: If considering Python bindings in future
• Hatchling plugins: Custom build hooks and extensions
• cibuildwheel: Cross-platform wheel building regardless of build system

Evaluation criteria:

• Hatchling compatibility and integration quality
• Cross-platform support (Windows, macOS, Linux)
• DeckLink SDK integration ease
• Wheel building and distribution support
• Maintenance overhead and community support
• Migration complexity from current Makefile

Deliverable: Technical decision document with recommended approach

Phase 2: Build System Implementation

Based on Phase 1 research, implement chosen system:

• Cross-platform build configuration
• Platform-specific library naming:
  • macOS: libdecklink.dylib
  • Windows: decklink.dll
  • Linux: libdecklink.so
• Automatic DeckLink SDK detection per platform:
  • Mac: Blackmagic DeckLink SDK 14.4/Mac/include
  • Windows: Blackmagic DeckLink SDK 14.4/Win/include
  • Linux: Blackmagic DeckLink SDK 14.4/Linux/include
• Platform-specific linking requirements

Phase 3: Python Build Integration

Extend pyproject.toml for cross-platform builds:

• Integrate chosen build system with Hatchling
• Custom build hooks to invoke C++ build before Python packaging
• Platform-specific wheel naming and content
• Update tasks.py build command to use new system

Phase 4: GitHub Actions CI/CD Pipeline

Create .github/workflows/ with multiple workflows:

Build & Test Workflow (.github/workflows/build-test.yml):

• Matrix strategy for Windows, macOS, Linux
• Install DeckLink SDK dependencies per platform
• C++ build verification with chosen system
• Python package build with mock device testing
• Store built wheels as artifacts

Release Workflow (.github/workflows/release.yml):

• Triggered on version tags (v*.*.*)
• Build wheels for all platforms using cibuildwheel or equivalent
• Run comprehensive test suite
• Upload to PyPI (Test PyPI first, then production)

Quality Workflow (.github/workflows/quality.yml):

• Run uv run invoke ai-developer-quality
• Ensure code quality standards across platforms

Phase 5: PyPI Distribution Setup

Package Registration and Distribution:

1. PyPI Account Setup:

   • Register project namespace on PyPI: bmd-signal-generator
   • Configure PyPI organization/team for maintainers
   • Set up API tokens for GitHub Actions

2. Distribution Configuration:

   • Update pyproject.toml with complete metadata
   • Configure trusted publishing with GitHub Actions
   • Set up Test PyPI for validation

3. Versioning Strategy:

   • Implement semantic versioning
   • Automatic version bumping in CI
   • Git tag-based releases

Phase 6: Platform-Specific Dependencies

Handle platform differences:

• Windows: MSVC compiler requirements, Windows SDK
• macOS: Xcode command line tools, framework linking
• Linux: GCC/Clang, appropriate library paths
• DeckLink SDK installation per platform

Acceptance Criteria

Phase 1 (Research):

• Comprehensive evaluation of modern build systems
• Technical decision document with rationale
• Proof-of-concept builds with top 2 candidates

Phase 2-6 (Implementation):

• Chosen build system works successfully on Windows, macOS, Linux
• Generated libraries work with existing Python code
• Seamless Hatchling integration
• GitHub Actions build matrix covers all target platforms
• Wheels can be installed via pip install bmd-signal-generator
• PyPI distribution includes all necessary platform libraries
• Build system handles DeckLink SDK path detection automatically
• All existing functionality works through packaged wheels
• Comprehensive build documentation in DEVELOPERS.md

Dependencies

• DeckLink SDK 14.4 for all target platforms
• Modern build system (TBD in Phase 1)
• Platform-specific compilers (MSVC, Clang, GCC)
• GitHub Actions runner access for all platforms
• PyPI project registration and API tokens

Migration Strategy

1. Research Phase: Evaluate options without disrupting current workflow
2. Parallel Implementation: Build new system alongside existing Makefile
3. Validation: Ensure new system produces identical libraries
4. CI Integration: Update automation to use new build system
5. Wheel Testing: Validate wheel generation and installation
6. PyPI Setup: Test PyPI validation before production
7. Production Release: Enable production PyPI distribution
8. Legacy Cleanup: Remove Makefile after full verification

This phased approach ensures we select the most appropriate modern tooling while maintaining development velocity and system reliability.