feat(apollo3): add build orchestrator, toolchain, and board definitions

[zackees]

Summary by CodeRabbit

New Features

• Added Ambiq Apollo3 platform support enabling ARM Cortex-M4F microcontroller builds
• Added board configurations for SparkFun RedBoard Artemis ATP and SparkFun Thing Plus expLoRaBLE
• Added ARM GCC 8 toolchain for embedded program compilation and linking

Documentation

• Added Apollo3 platform configuration and setup documentation

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 57744f7d-1ba4-4238-96eb-c38591dd0df0

📥 Commits

Reviewing files that changed from the base of the PR and between a0e0aee and d57451b.

📒 Files selected for processing (15)

• crates/fbuild-build/src/apollo3/README.md
• crates/fbuild-build/src/apollo3/configs/README.md
• crates/fbuild-build/src/apollo3/configs/apollo3.json
• crates/fbuild-build/src/apollo3/mcu_config.rs
• crates/fbuild-build/src/apollo3/mod.rs
• crates/fbuild-build/src/apollo3/orchestrator.rs
• crates/fbuild-build/src/lib.rs
• crates/fbuild-config/assets/boards/json/SparkFun_RedBoard_Artemis_ATP.json
• crates/fbuild-config/assets/boards/json/SparkFun_Thing_Plus_expLoRaBLE.json
• crates/fbuild-config/src/board.rs
• crates/fbuild-core/src/lib.rs
• crates/fbuild-packages/src/library/apollo3_core.rs
• crates/fbuild-packages/src/library/mod.rs
• crates/fbuild-packages/src/toolchain/arm_gcc8.rs
• crates/fbuild-packages/src/toolchain/mod.rs

---

📝 Walkthrough

Walkthrough

This pull request introduces complete build support for the Apollo3 platform (Ambiq Micro ARM Cortex-M4F MCUs). It adds a new build orchestrator, MCU configuration, ARM GCC8 toolchain package, Apollo3 cores framework manager, and board definitions for SparkFun-based Apollo3 boards.

Changes

Cohort / File(s)	Summary
Apollo3 Platform Core crates/fbuild-core/src/lib.rs, crates/fbuild-build/src/lib.rs	Added Platform::Apollo3 enum variant to core platform definitions; updated platform string matching to recognize "apollo3"; integrated Apollo3 platform support into the main build library.
Apollo3 Build Orchestrator crates/fbuild-build/src/apollo3/mod.rs, crates/fbuild-build/src/apollo3/orchestrator.rs, crates/fbuild-build/src/apollo3/mcu_config.rs	Implemented Apollo3Orchestrator with full build pipeline (toolchain setup, core installation, source discovery, compiler flag/include merging from mbed response files, linker configuration); added MCU config loader supporting apollo3 and ama3b\\* variants; exposed Apollo3PlatformSupport trait implementation.
Apollo3 Package Management crates/fbuild-packages/src/library/apollo3_core.rs, crates/fbuild-packages/src/library/mod.rs, crates/fbuild-packages/src/toolchain/arm_gcc8.rs, crates/fbuild-packages/src/toolchain/mod.rs	Added Apollo3Cores framework package manager for SparkFun Apollo3 Arduino core with variant/library path resolution and mbed response file handling; added ArmGcc8Toolchain package manager for PlatformIO GCC 9.2.1 toolchain with platform-specific archive handling and binary root detection.
Board & MCU Configuration crates/fbuild-config/assets/boards/json/SparkFun_RedBoard_Artemis_ATP.json, crates/fbuild-config/assets/boards/json/SparkFun_Thing_Plus_expLoRaBLE.json, crates/fbuild-config/src/board.rs	Added board definition JSONs for SparkFun Artemis ATP and Thing Plus expLoRaBLE boards (including MCU mapping, clock config, upload settings); extended board MCU detection to map "apollo3" and "ama3b" prefixes to Platform::Apollo3 and emit APOLLO3 architecture define.
Apollo3 Build Configuration & Documentation crates/fbuild-build/src/apollo3/configs/apollo3.json, crates/fbuild-build/src/apollo3/README.md, crates/fbuild-build/src/apollo3/configs/README.md	Added embedded apollo3.json MCU build config specifying Cortex-M4F compiler/linker flags, ABI/FPU options, optimization profiles, linker libraries (supc++, stdc++, m), and preprocessor defines; added documentation for Apollo3 orchestrator and configs directory.

Sequence Diagram(s)

sequenceDiagram
    actor User
    participant Orchestrator as Apollo3Orchestrator
    participant Toolchain as ArmGcc8Toolchain
    participant Cores as Apollo3Cores
    participant Compiler as ArmCompiler
    participant Linker as ArmLinker

    User->>Orchestrator: build(BuildParams)
    activate Orchestrator
    
    Orchestrator->>Toolchain: ensure_installed()
    activate Toolchain
    Toolchain-->>Orchestrator: toolchain_path
    deactivate Toolchain
    
    Orchestrator->>Cores: ensure_installed()
    activate Cores
    Cores-->>Orchestrator: cores_installed
    deactivate Cores
    
    Orchestrator->>Cores: get_variant_dir(variant)
    Cores-->>Orchestrator: variant_path
    
    Orchestrator->>Cores: read_mbed_response_file()
    Cores-->>Orchestrator: defines, includes, ld_flags
    
    Orchestrator->>Compiler: new(config, defines, includes)
    activate Compiler
    Compiler-->>Orchestrator: compiler_ready
    deactivate Compiler
    
    Orchestrator->>Compiler: compile_sources()
    Compiler-->>Orchestrator: object_files
    
    Orchestrator->>Cores: get_mbed_lib(variant)
    Cores-->>Orchestrator: libmbed_os.a
    
    Orchestrator->>Linker: new(toolchain, config)
    activate Linker
    Linker-->>Orchestrator: linker_ready
    deactivate Linker
    
    Orchestrator->>Linker: link(objects, libraries, script)
    Linker-->>Orchestrator: output_binary
    deactivate Orchestrator
    
    User->>User: binary ready

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

The changes introduce a substantial new platform with significant logic density across multiple crates. The Apollo3Orchestrator (~281 lines) and ArmGcc8Toolchain (~212 lines) contain intricate component coordination, mbed response file parsing, and multi-stage build orchestration. While board configurations and documentation are straightforward, the orchestrator's logic for merging defines, parsing response files, and managing library wrapping requires careful verification. The diversity of interacting components (toolchain, cores, MCU config, compiler, linker) across multiple crate layers increases review complexity.

Poem

🐰 A rabbit's verse on Apollo3's arrival:

Through Cortex-M4F circuits, new pathways we've laid,
With SparkFun's bright Artemis, orchestration made!
ARM GCC and mbed-os in harmony play,
Apollo3 now soars—build the future today! 🚀

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/rp2040-orchestrator

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}