05_17_08: Compatibility Matrix - AudioLab Version Compatibility¶

Executive Summary¶

Comprehensive version compatibility tracking across the AudioLab ecosystem. Ensures all components, dependencies, platforms, and tools work together correctly.

Key Features: - Layer compatibility tracking (L0-L3) - External dependency compatibility - Platform and compiler compatibility - Plugin format compatibility - Automated compatibility checking - Version constraint validation

Tools¶

compatibility_checker.py¶

Checks version compatibility across ecosystem.

Usage:

# Check layer compatibility
python compatibility_checker.py \
  --kernels 2.1.0 \
  --atoms 2.1.0 \
  --cells 2.1.0 \
  --engines 2.1.0

# Check external dependencies
python compatibility_checker.py \
  --juce 7.0.5 \
  --eigen 3.4.0 \
  --fftw3 3.3.10

# Check platform compatibility
python compatibility_checker.py \
  --platform windows \
  --compiler msvc \
  --compiler-version 17.8

# Full compatibility check
python compatibility_checker.py \
  --kernels 2.1.0 --atoms 2.1.0 --cells 2.1.0 --engines 2.1.0 \
  --juce 7.0.5 --eigen 3.4.0 \
  --platform windows --compiler msvc --compiler-version 17.8

Example Output:

======================================================================
Compatibility Check Report
======================================================================

✓ All compatibility checks passed!

======================================================================
Summary: 0 errors, 0 warnings, 0 info
======================================================================

With Issues:

======================================================================
Compatibility Check Report
======================================================================

❌ ERRORS (1):

  Component: juce
  Version:   6.1.6
  Issue:     Version below minimum 7.0.0
  Fix:       Upgrade to 7.0.5+

⚠️  WARNINGS (2):

  Component: layers
  Version:   mixed
  Issue:     Layers have different versions
  Fix:       Consider coordinated release

  Component: eigen
  Version:   3.4.0
  Note:      Version not explicitly tested
  Suggest:   Test thoroughly before production

======================================================================
Summary: 1 errors, 2 warnings, 0 info
======================================================================

version_validator.py¶

Validates semantic versions and constraints.

Usage:

# Validate version format
python version_validator.py validate --version 2.1.0

# Check version against constraint
python version_validator.py check --version 2.1.0 --constraint "^2.0.0"

# Compare versions
python version_validator.py compare --v1 2.1.0 --v2 2.0.0

# Validate lock file
python version_validator.py validate --lock-file audiolab-lock.yaml

# Validate manifest
python version_validator.py validate --manifest dependency_management.yaml

Examples:

# Valid version
$ python version_validator.py validate --version 2.1.0
✓ '2.1.0' is a valid semantic version

  Major:      2
  Minor:      1
  Patch:      0

# Version satisfies constraint
$ python version_validator.py check --version 2.1.0 --constraint "^2.0.0"
✓ Version '2.1.0' satisfies constraint '^2.0.0'

# Compare versions
$ python version_validator.py compare --v1 2.1.0 --v2 2.0.0
2.1.0 > 2.0.0

Compatibility Matrix¶

Layer Compatibility (L0-L3)¶

Coordinated Versioning: All layers use same version

kernels (L0) = 2.1.0
atoms (L1)   = 2.1.0  (requires kernels >= 2.0.0)
cells (L2)   = 2.1.0  (requires kernels, atoms >= 2.0.0)
engines (L3) = 2.1.0  (requires kernels, atoms, cells >= 2.0.0)

Benefits: - Simplified dependency management - Clear compatibility guarantees - Easy testing and deployment

External Dependencies¶

JUCE Framework¶

Current: 7.0.5
Minimum: 7.0.0
Status: Recommended
Tested: 7.0.3, 7.0.4, 7.0.5
Deprecated: 6.x (EOL June 2025)

Known Issues: - 7.0.0-7.0.1: Audio buffer alignment bug (upgrade to 7.0.2+)

Breaking Changes: - 6.x → 7.0: Graphics API and audio processor lifecycle changes

Eigen¶

Current: 3.4.0
Minimum: 3.3.7
Status: Recommended
Tested: 3.3.9, 3.4.0

Platform Notes: - Windows: Requires AVX2 support - macOS: ARM64 optimization available - Linux: Uses system BLAS if available

FFTW3¶

Current: 3.3.10
Minimum: 3.3.8
Status: Recommended
License: GPL (provide alternative for proprietary use)

Platform Compatibility¶

Windows¶

Supported: Windows 10 (21H2+), Windows 11 (22H2+)
Minimum: Windows 10 version 1909
Compiler: MSVC 2022 (17.8+) or 2019 (16.11+)
Architecture: x64
Requirements: Visual C++ Redistributable 2022, AVX2

Tested: - Windows 11 22H2 + MSVC 2022 17.8 ✓ - Windows 10 21H2 + MSVC 2022 17.8 ✓

macOS¶

Supported: macOS 12-14 (Monterey, Ventura, Sonoma)
Minimum: macOS 12.0
Compiler: Clang 15+ (Xcode 15+)
Architecture: arm64, x86_64 (Universal Binary)
Requirements: Xcode Command Line Tools, macOS SDK 12.0+

Tested: - macOS 14.2 Sonoma (arm64) + Xcode 15.2 ✓ - macOS 13.5 Ventura (x86_64) + Xcode 15.1 ✓

Linux¶

Supported: Ubuntu 20.04+, Debian 12, Fedora 38+
Minimum: Ubuntu 20.04 or equivalent
Compiler: GCC 11+ or Clang 15+
Architecture: x86_64
Requirements: ALSA dev libs, X11 dev libs, CMake 3.20+

Tested: - Ubuntu 22.04 + GCC 12.3 ✓ - Ubuntu 20.04 + GCC 11.4 ✓

Plugin Format Compatibility¶

VST3¶

SDK: 3.7.7
Platforms: Windows, macOS, Linux
Hosts: Ableton Live, FL Studio, Cubase, Studio One, Reaper

AU (Audio Unit)¶

Versions: v2, v3
Platforms: macOS only
Hosts: Logic Pro, GarageBand, Ableton Live
Requirements: Code signing, notarization (macOS 10.15+)

AAX¶

SDK: 2.4.1
Platforms: Windows, macOS
Hosts: Pro Tools 2023+
Requirements: Avid developer account, AAX code signing

CLAP¶

Version: 1.1.9
Platforms: Windows, macOS, Linux
Hosts: Bitwig Studio, Reaper
Status: Emerging format

Version Constraints¶

Constraint Syntax¶

Exact version:

version: "=2.1.0"

Range:

version: ">=2.0.0"
version: "<=2.2.0"
version: ">2.0.0"
version: "<3.0.0"

Caret (compatible with):

version: "^2.0.0"  # Allows 2.x.x (same major)

Tilde (patch updates):

version: "~2.1.0"  # Allows 2.1.x (same major.minor)

Wildcard:

version: "7.0.x"   # Allows any 7.0.x
version: "7.*"     # Allows any 7.x.x

Compatibility Rules¶

Major Version¶

Breaking changes: No backward compatibility
Example: 1.x.x → 2.0.0
Actions: Update all dependents, migration guide required

Minor Version¶

New features: Backward compatible
Example: 2.0.x → 2.1.0
Actions: Optional upgrade, feature documentation

Patch Version¶

Bug fixes: Backward compatible
Example: 2.1.0 → 2.1.1
Actions: Recommended upgrade, regression testing

Deprecation Policy¶

Timeline¶

Warning Period: 6 months
Removal After: 12 months (total)

Process¶

Deprecation Warning (Month 0-6)
Add deprecation warnings
Update documentation
Announce in changelog
Provide migration path
Grace Period (Month 6-12)
Continue support with warnings
Assist migrations
Monitor usage
Removal (Month 12+)
Remove deprecated feature
Major version bump
Update documentation

CI/CD Integration¶

Pre-build Check¶

# .github/workflows/build.yml
- name: Check compatibility
  run: |
    python compatibility_checker.py \
      --kernels $(cat VERSION) \
      --juce 7.0.5 \
      --platform ${{ matrix.os }} \
      --compiler ${{ matrix.compiler }}

Lock File Validation¶

- name: Validate lock file
  run: python version_validator.py validate --lock-file audiolab-lock.yaml

Configuration Files¶

compatibility_matrix.yaml¶

Complete compatibility configuration (~12 KB): - Layer compatibility definitions - External dependency tracking - Platform and compiler requirements - Plugin format compatibility - Version constraints - Deprecation tracking

Best Practices¶

Use coordinated versioning for internal layers
Pin external dependencies in lock file
Test on all platforms before release
Document breaking changes clearly
Provide migration guides for major versions
Check compatibility in CI/CD
Update matrix regularly with new versions

Quick Reference¶

# Full compatibility check
python compatibility_checker.py \
  --kernels 2.1.0 --atoms 2.1.0 --cells 2.1.0 --engines 2.1.0 \
  --juce 7.0.5 --eigen 3.4.0 --fftw3 3.3.10 \
  --platform windows --compiler msvc --compiler-version 17.8

# Validate version
python version_validator.py validate --version 2.1.0

# Check constraint
python version_validator.py check --version 2.1.0 --constraint "^2.0.0"

# Validate lock file
python version_validator.py validate --lock-file audiolab-lock.yaml

Part of AudioLab Version Control System (05_17_VERSION_CONTROL)