UmbraCore: Bazel and SPM Integration Brief

Overview

This document outlines our strategy for integrating Bazel build system while maintaining Swift Package Manager (SPM) compatibility in the UmbraCore project.

1. Integration Goals

• Maintain existing SPM dependencies
• Leverage Bazel's build caching
• Optimise CI/CD performance
• Support future scalability

2. Technical Architecture

2.1 Build System Components

UmbraCore/
├── WORKSPACE
├── MODULE.bazel          # Bazel module configuration
├── Package.swift         # SPM dependencies
├── Package.resolved      # SPM version lock
├── .bazelrc             # Bazel settings
├── BUILD.bazel          # Root build file
├── Sources/             # Source files
│   └── */
│       ├── BUILD       # Generated by Gazelle
│       └── *.swift
└── Tests/              # Test files
    └── */
        ├── BUILD       # Generated by Gazelle
        └── *.swift

2.2 Key Configuration Files

MODULE.bazel

bazel_dep(name = "rules_swift_package_manager", version = "0.46.0")

swift_deps = use_extension(
    "@rules_swift_package_manager//:extensions.bzl",
    "swift_deps",
)

swift_deps.configure_swift_package(
    build_path = "spm-build",
    cache_path = "spm-cache",
    dependency_caching = "true",
    manifest_cache = "local",
    manifest_caching = "true",
)

swift_deps.from_package(
    declare_swift_deps_info = True,
    declare_swift_package = True,
    resolved = "//:Package.resolved",
    swift = "//:Package.swift",
)

.bazelrc

# Enable bzlmod
build --enable_bzlmod

# SPM integration
build --experimental_enable_swift_package_manager

# Caching configuration
build --remote_cache=grpcs://cache.buildbuddy.io
build --remote_timeout=3600

3. Dependency Management

3.1 SPM Dependencies

• CryptoSwift (v1.8.0+)
• SwiftyBeaver (v2.0.0+)

3.2 Bazel Dependencies

• rules_swift_package_manager
• rules_swift
• rules_apple (optional)
• Gazelle

4. Caching Strategy

4.1 Cache Locations

• spm-cache/: SPM dependency cache
• spm-build/: SPM build artifacts
• bazel-*/: Bazel build outputs
• ~/.cache/bazel: Bazel system cache

4.2 CI/CD Caching

cache:
  paths:
    - ~/.cache/bazel
    - spm-cache
    - spm-build
  key: ${CI_COMMIT_REF_SLUG}

5. Common Operations

5.1 Dependency Management

# Update all dependencies
bazel run @swift_package//:update

# Update specific package
bazel run @swift_package//:update -- SwiftyBeaver

# Resolve dependencies
bazel run @swift_package//:resolve

5.2 Build Operations

# Build entire project
bazel build //...

# Run tests
bazel test //...

# Generate BUILD files
bazel run //:update_build_files

6. Best Practices

6.1 Development Workflow

1. Use Bazel commands for all build operations
2. Keep Package.swift minimal and focused
3. Regularly update cached dependencies
4. Monitor cache size and performance

6.2 Code Organisation

1. Follow module structure in Sources/
2. Maintain clear dependency boundaries
3. Use proper visibility declarations
4. Keep BUILD files organised

6.3 Language Standards

1. Use British English in:
2. Documentation
3. Comments
4. User-facing text
5. Use American English in:
6. Code
7. Build files
8. Configuration

7. Performance Considerations

7.1 Local Development

• Use local caching
• Enable parallel builds
• Monitor resource usage
• Regular cache cleanup

7.2 CI/CD Pipeline

• Optimise cache sharing
• Use remote caching
• Enable parallel testing
• Monitor build times

8. Migration Timeline

Phase 1: Initial Setup (1 week)

• [ ] Configure Bazel
• [ ] Set up SPM integration
• [ ] Configure caching
• [ ] Update documentation

Phase 2: Build Migration (2 weeks)

• [ ] Generate BUILD files
• [ ] Test build system
• [ ] Validate dependencies
• [ ] Performance testing

Phase 3: CI/CD Integration (1 week)

• [ ] Configure GitHub Actions
• [ ] Set up caching
• [ ] Test workflows
• [ ] Monitor performance

9. Support and Maintenance

9.1 Regular Tasks

• Weekly dependency updates
• Monthly cache cleanup
• Quarterly performance review
• Regular documentation updates

9.2 Monitoring

• Build times
• Cache hit rates
• Dependency updates
• Resource usage

10. References

1. Bazel Documentation
2. rules_swift_package_manager
3. Swift Package Manager
4. GitHub Actions Documentation