fbuild 1.1.0__py3-none-any.whl

fbuild/build/orchestrator_esp32.py

@@ -0,0 +1,797 @@
+"""
+ESP32-specific build orchestration for Fbuild projects.
+
+This module handles ESP32 platform builds separately from AVR builds,
+providing cleaner separation of concerns and better maintainability.
+"""
+
+import _thread
+import time
+from pathlib import Path
+from typing import List, Optional
+from dataclasses import dataclass
+
+from ..packages import Cache
+from ..packages.platform_esp32 import PlatformESP32
+from ..packages.toolchain_esp32 import ToolchainESP32
+from ..packages.framework_esp32 import FrameworkESP32
+from ..packages.library_manager_esp32 import LibraryManagerESP32
+from ..cli_utils import BannerFormatter
+from .configurable_compiler import ConfigurableCompiler
+from .configurable_linker import ConfigurableLinker
+from .linker import SizeInfo
+from .orchestrator import IBuildOrchestrator, BuildResult
+from .build_utils import safe_rmtree
+from .build_state import BuildStateTracker
+
+
+@dataclass
+class BuildResultESP32:
+    """Result of an ESP32 build operation (internal use)."""
+
+    success: bool
+    firmware_bin: Optional[Path]
+    firmware_elf: Optional[Path]
+    bootloader_bin: Optional[Path]
+    partitions_bin: Optional[Path]
+    size_info: Optional[SizeInfo]
+    build_time: float
+    message: str
+
+
+class OrchestratorESP32(IBuildOrchestrator):
+    """
+    Orchestrates ESP32-specific build process.
+
+    Handles platform initialization, toolchain setup, framework preparation,
+    library compilation, and firmware generation for ESP32 targets.
+    """
+
+    def __init__(self, cache: Cache, verbose: bool = False):
+        """
+        Initialize ESP32 orchestrator.
+
+        Args:
+            cache: Cache instance for package management
+            verbose: Enable verbose output
+        """
+        self.cache = cache
+        self.verbose = verbose
+
+    def build(
+        self,
+        project_dir: Path,
+        env_name: Optional[str] = None,
+        clean: bool = False,
+        verbose: Optional[bool] = None
+    ) -> BuildResult:
+        """Execute complete build process (BaseBuildOrchestrator interface).
+
+        Args:
+            project_dir: Project root directory containing platformio.ini
+            env_name: Environment name to build (defaults to first/default env)
+            clean: Clean build (remove all artifacts before building)
+            verbose: Override verbose setting
+
+        Returns:
+            BuildResult with build status and output paths
+
+        Raises:
+            BuildOrchestratorError: If build fails at any phase
+        """
+        from ..config import PlatformIOConfig
+
+        verbose_mode = verbose if verbose is not None else self.verbose
+
+        # Parse platformio.ini to get environment configuration
+        ini_path = project_dir / "platformio.ini"
+        if not ini_path.exists():
+            return BuildResult(
+                success=False,
+                hex_path=None,
+                elf_path=None,
+                size_info=None,
+                build_time=0.0,
+                message=f"platformio.ini not found in {project_dir}"
+            )
+
+        try:
+            config = PlatformIOConfig(ini_path)
+
+            # Determine environment to build
+            if env_name is None:
+                env_name = config.get_default_environment()
+                if env_name is None:
+                    return BuildResult(
+                        success=False,
+                        hex_path=None,
+                        elf_path=None,
+                        size_info=None,
+                        build_time=0.0,
+                        message="No environment specified and no default found in platformio.ini"
+                    )
+
+            env_config = config.get_env_config(env_name)
+            board_id = env_config.get("board", "")
+            build_flags = config.get_build_flags(env_name)
+            lib_deps = config.get_lib_deps(env_name)
+
+            # Call internal build method
+            esp32_result = self._build_esp32(
+                project_dir, env_name, board_id, env_config, build_flags, lib_deps, clean, verbose_mode
+            )
+
+            # Convert BuildResultESP32 to BuildResult
+            return BuildResult(
+                success=esp32_result.success,
+                hex_path=esp32_result.firmware_bin,
+                elf_path=esp32_result.firmware_elf,
+                size_info=esp32_result.size_info,
+                build_time=esp32_result.build_time,
+                message=esp32_result.message
+            )
+
+        except KeyboardInterrupt:
+            _thread.interrupt_main()
+            raise
+        except Exception as e:
+            return BuildResult(
+                success=False,
+                hex_path=None,
+                elf_path=None,
+                size_info=None,
+                build_time=0.0,
+                message=f"Failed to parse configuration: {e}"
+            )
+
+    def _build_esp32(
+        self,
+        project_dir: Path,
+        env_name: str,
+        board_id: str,
+        env_config: dict,
+        build_flags: List[str],
+        lib_deps: List[str],
+        clean: bool = False,
+        verbose: bool = False
+    ) -> BuildResultESP32:
+        """
+        Execute complete ESP32 build process (internal implementation).
+
+        Args:
+            project_dir: Project directory
+            env_name: Environment name
+            board_id: Board ID (e.g., esp32-c6-devkitm-1)
+            env_config: Environment configuration dict
+            build_flags: User build flags from platformio.ini
+            lib_deps: Library dependencies from platformio.ini
+            clean: Whether to clean before build
+            verbose: Verbose output mode
+
+        Returns:
+            BuildResultESP32 with build status and output paths
+        """
+        start_time = time.time()
+
+        try:
+            # Get platform URL from env_config
+            platform_url = env_config.get('platform')
+            if not platform_url:
+                return self._error_result(
+                    start_time,
+                    "No platform URL specified in platformio.ini"
+                )
+
+            # Initialize platform
+            if verbose:
+                print("[3/10] Initializing ESP32 platform...")
+            else:
+                print("Initializing ESP32 platform...")
+
+            platform = PlatformESP32(self.cache, platform_url, show_progress=True)
+            platform.ensure_platform()
+
+            # Get board configuration
+            board_json = platform.get_board_json(board_id)
+            mcu = board_json.get("build", {}).get("mcu", "esp32c6")
+
+            if verbose:
+                print(f"      Board: {board_id}")
+                print(f"      MCU: {mcu}")
+
+            # Get required packages
+            packages = platform.get_required_packages(mcu)
+
+            # Initialize toolchain
+            toolchain = self._setup_toolchain(packages, start_time, verbose)
+            if toolchain is None:
+                return self._error_result(
+                    start_time,
+                    "Failed to initialize toolchain"
+                )
+
+            # Initialize framework
+            framework = self._setup_framework(packages, start_time, verbose)
+            if framework is None:
+                return self._error_result(
+                    start_time,
+                    "Failed to initialize framework"
+                )
+
+            # Setup build directory
+            build_dir = self._setup_build_directory(env_name, clean, verbose)
+
+            # Check build state and invalidate cache if needed
+            if verbose:
+                print("[6.5/10] Checking build configuration state...")
+
+            state_tracker = BuildStateTracker(build_dir)
+            needs_rebuild, reasons, current_state = state_tracker.check_invalidation(
+                platformio_ini_path=project_dir / "platformio.ini",
+                platform="esp32",
+                board=board_id,
+                framework=env_config.get('framework', 'arduino'),
+                toolchain_version=toolchain.version,
+                framework_version=framework.version,
+                platform_version=platform.version,
+                build_flags=build_flags,
+                lib_deps=lib_deps,
+            )
+
+            if needs_rebuild:
+                if verbose:
+                    print("      Build cache invalidated:")
+                    for reason in reasons:
+                        print(f"        - {reason}")
+                    print("      Cleaning build artifacts...")
+                # Clean build artifacts to force rebuild
+                from .build_utils import safe_rmtree
+                if build_dir.exists():
+                    safe_rmtree(build_dir)
+                # Recreate build directory
+                build_dir.mkdir(parents=True, exist_ok=True)
+            else:
+                if verbose:
+                    print("      Build configuration unchanged, using cached artifacts")
+
+            # Initialize compilation executor early to show sccache status
+            from .compilation_executor import CompilationExecutor
+            compilation_executor = CompilationExecutor(
+                build_dir=build_dir,
+                show_progress=verbose
+            )
+
+            # Try to get compilation queue from daemon for async compilation
+            # TODO: Implement get_compilation_queue() in daemon module
+            compilation_queue = None
+            # try:
+            #     from ..daemon import daemon
+            #     compilation_queue = daemon.get_compilation_queue()
+            #     if compilation_queue and verbose:
+            #         num_workers = getattr(compilation_queue, 'num_workers', 'unknown')
+            #         print(f"[Async Mode] Using daemon compilation queue with {num_workers} workers")
+            # except (ImportError, AttributeError):
+            #     # Daemon not available or not running - use synchronous compilation
+            #     if verbose:
+            #         print("[Sync Mode] Daemon not available, using synchronous compilation")
+
+            # Initialize compiler
+            if verbose:
+                print("[7/10] Compiling Arduino core...")
+            else:
+                print("Compiling Arduino core...")
+
+            compiler = ConfigurableCompiler(
+                platform,
+                toolchain,
+                framework,
+                board_id,
+                build_dir,
+                platform_config=None,
+                show_progress=verbose,
+                user_build_flags=build_flags,
+                compilation_executor=compilation_executor,
+                compilation_queue=compilation_queue
+            )
+
+            # Compile Arduino core with progress bar
+            if verbose:
+                core_obj_files = compiler.compile_core()
+            else:
+                # Use tqdm progress bar for non-verbose mode
+                from tqdm import tqdm
+
+                # Get number of core source files for progress tracking
+                core_sources = framework.get_core_sources(compiler.core)
+                total_files = len(core_sources)
+
+                # Create progress bar
+                with tqdm(
+                    total=total_files,
+                    desc='Compiling Arduino core',
+                    unit='file',
+                    ncols=80,
+                    leave=False
+                ) as pbar:
+                    core_obj_files = compiler.compile_core(progress_bar=pbar)
+
+                # Print completion message
+                print(f"Compiled {len(core_obj_files)} core files")
+
+            # Add Bluetooth stub for non-ESP32 targets (ESP32-C6, ESP32-S3, etc.)
+            # where esp32-hal-bt.c fails to compile but btInUse() is still referenced
+            bt_stub_obj = self._create_bt_stub(build_dir, compiler, verbose)
+            if bt_stub_obj:
+                core_obj_files.append(bt_stub_obj)
+
+            core_archive = compiler.create_core_archive(core_obj_files)
+
+            if verbose:
+                print(f"      Compiled {len(core_obj_files)} core source files")
+
+            # Handle library dependencies
+            library_archives, library_include_paths = self._process_libraries(
+                env_config, build_dir, compiler, toolchain, verbose
+            )
+
+            # Add library include paths to compiler
+            if library_include_paths:
+                compiler.add_library_includes(library_include_paths)
+
+            # Find and compile sketch
+            sketch_obj_files = self._compile_sketch(project_dir, compiler, start_time, verbose)
+            if sketch_obj_files is None:
+                return self._error_result(
+                    start_time,
+                    f"No .ino sketch file found in {project_dir}"
+                )
+
+            # Initialize linker
+            if verbose:
+                print("[9/10] Linking firmware...")
+            else:
+                print("Linking firmware...")
+
+            linker = ConfigurableLinker(
+                platform,
+                toolchain,
+                framework,
+                board_id,
+                build_dir,
+                platform_config=None,
+                show_progress=verbose
+            )
+
+            # Link firmware
+            firmware_elf = linker.link(sketch_obj_files, core_archive, library_archives=library_archives)
+
+            # Generate binary
+            if verbose:
+                print("[10/10] Generating firmware binary...")
+            else:
+                print("Generating firmware binary...")
+
+            firmware_bin = linker.generate_bin(firmware_elf)
+
+            # Generate bootloader and partition table
+            bootloader_bin, partitions_bin = self._generate_boot_components(
+                linker, mcu, verbose
+            )
+
+            build_time = time.time() - start_time
+
+            if verbose:
+                self._print_success(
+                    build_time, firmware_elf, firmware_bin,
+                    bootloader_bin, partitions_bin
+                )
+
+            # Save build state for future cache validation
+            if verbose:
+                print("[10.5/10] Saving build state...")
+            state_tracker.save_state(current_state)
+
+            return BuildResultESP32(
+                success=True,
+                firmware_bin=firmware_bin,
+                firmware_elf=firmware_elf,
+                bootloader_bin=bootloader_bin,
+                partitions_bin=partitions_bin,
+                size_info=None,  # TODO: Add size info for ESP32
+                build_time=build_time,
+                message="Build successful (native ESP32 build)"
+            )
+
+        except KeyboardInterrupt as ke:
+            from fbuild.interrupt_utils import handle_keyboard_interrupt_properly
+            handle_keyboard_interrupt_properly(ke)
+            raise  # Never reached, but satisfies type checker
+        except Exception as e:
+            build_time = time.time() - start_time
+            import traceback
+            error_trace = traceback.format_exc()
+            return BuildResultESP32(
+                success=False,
+                firmware_bin=None,
+                firmware_elf=None,
+                bootloader_bin=None,
+                partitions_bin=None,
+                size_info=None,
+                build_time=build_time,
+                message=f"ESP32 native build failed: {e}\n\n{error_trace}"
+            )
+
+    def _setup_toolchain(
+        self,
+        packages: dict,
+        start_time: float,
+        verbose: bool
+    ) -> Optional['ToolchainESP32']:
+        """
+        Initialize ESP32 toolchain.
+
+        Args:
+            packages: Package URLs dictionary
+            start_time: Build start time for error reporting
+            verbose: Verbose output mode
+
+        Returns:
+            ToolchainESP32 instance or None on failure
+        """
+        if verbose:
+            print("[4/10] Initializing ESP32 toolchain...")
+        else:
+            print("Initializing ESP32 toolchain...")
+
+        toolchain_url = packages.get("toolchain-riscv32-esp") or packages.get("toolchain-xtensa-esp-elf")
+        if not toolchain_url:
+            return None
+
+        # Determine toolchain type
+        toolchain_type = "riscv32-esp" if "riscv32" in toolchain_url else "xtensa-esp-elf"
+        toolchain = ToolchainESP32(
+            self.cache,
+            toolchain_url,
+            toolchain_type,
+            show_progress=True
+        )
+        toolchain.ensure_toolchain()
+        return toolchain
+
+    def _setup_framework(
+        self,
+        packages: dict,
+        start_time: float,
+        verbose: bool
+    ) -> Optional[FrameworkESP32]:
+        """
+        Initialize ESP32 framework.
+
+        Args:
+            packages: Package URLs dictionary
+            start_time: Build start time for error reporting
+            verbose: Verbose output mode
+
+        Returns:
+            FrameworkESP32 instance or None on failure
+        """
+        if verbose:
+            print("[5/10] Initializing ESP32 framework...")
+        else:
+            print("Initializing ESP32 framework...")
+
+        framework_url = packages.get("framework-arduinoespressif32")
+        libs_url = packages.get("framework-arduinoespressif32-libs", "")
+
+        if not framework_url:
+            return None
+
+        # Find skeleton library if present (e.g., framework-arduino-esp32c2-skeleton-lib)
+        skeleton_lib_url = None
+        for package_name, package_url in packages.items():
+            if package_name.startswith("framework-arduino-") and package_name.endswith("-skeleton-lib"):
+                skeleton_lib_url = package_url
+                break
+
+        framework = FrameworkESP32(
+            self.cache,
+            framework_url,
+            libs_url,
+            skeleton_lib_url=skeleton_lib_url,
+            show_progress=True
+        )
+        framework.ensure_framework()
+        return framework
+
+    def _setup_build_directory(self, env_name: str, clean: bool, verbose: bool) -> Path:
+        """
+        Setup build directory with optional cleaning.
+
+        Args:
+            env_name: Environment name
+            clean: Whether to clean before build
+            verbose: Verbose output mode
+
+        Returns:
+            Build directory path
+        """
+        build_dir = self.cache.get_build_dir(env_name)
+
+        if clean and build_dir.exists():
+            if verbose:
+                print("[6/10] Cleaning build directory...")
+            else:
+                print("Cleaning build directory...")
+            safe_rmtree(build_dir)
+
+        build_dir.mkdir(parents=True, exist_ok=True)
+        return build_dir
+
+    def _process_libraries(
+        self,
+        env_config: dict,
+        build_dir: Path,
+        compiler: ConfigurableCompiler,
+        toolchain: ToolchainESP32,
+        verbose: bool
+    ) -> tuple[List[Path], List[Path]]:
+        """
+        Process and compile library dependencies.
+
+        Args:
+            env_config: Environment configuration
+            build_dir: Build directory
+            compiler: Configured compiler instance
+            toolchain: ESP32 toolchain instance
+            verbose: Verbose output mode
+
+        Returns:
+            Tuple of (library_archives, library_include_paths)
+        """
+        lib_deps = env_config.get('lib_deps', '')
+        library_archives = []
+        library_include_paths = []
+
+        if not lib_deps:
+            return library_archives, library_include_paths
+
+        if verbose:
+            print("[7.5/10] Processing library dependencies...")
+
+        # Parse lib_deps (can be string or list)
+        if isinstance(lib_deps, str):
+            lib_specs = [dep.strip() for dep in lib_deps.split('\n') if dep.strip()]
+        else:
+            lib_specs = lib_deps
+
+        if not lib_specs:
+            return library_archives, library_include_paths
+
+        # Initialize library manager
+        lib_manager = LibraryManagerESP32(build_dir)
+
+        # Get compiler flags for library compilation
+        lib_compiler_flags = compiler.get_base_flags()
+
+        # Get include paths for library compilation
+        lib_include_paths = compiler.get_include_paths()
+
+        # Get toolchain bin path
+        toolchain_bin_path = toolchain.get_bin_path()
+        if toolchain_bin_path is None:
+            if verbose:
+                print("      Warning: Toolchain bin directory not found, skipping libraries")
+            return library_archives, library_include_paths
+
+        # Ensure libraries are downloaded and compiled
+        libraries = lib_manager.ensure_libraries(
+            lib_specs,
+            toolchain_bin_path,
+            lib_compiler_flags,
+            lib_include_paths,
+            show_progress=verbose
+        )
+
+        # Get library archives and include paths
+        library_archives = [lib.archive_file for lib in libraries if lib.is_compiled]
+        library_include_paths = lib_manager.get_library_include_paths()
+
+        if verbose:
+            print(f"      Compiled {len(libraries)} library dependencies")
+
+        return library_archives, library_include_paths
+
+    def _compile_sketch(
+        self,
+        project_dir: Path,
+        compiler: ConfigurableCompiler,
+        start_time: float,
+        verbose: bool
+    ) -> Optional[List[Path]]:
+        """
+        Find and compile sketch files.
+
+        Args:
+            project_dir: Project directory
+            compiler: Configured compiler instance
+            start_time: Build start time for error reporting
+            verbose: Verbose output mode
+
+        Returns:
+            List of compiled object files or None if no sketch found
+        """
+        if verbose:
+            print("[8/10] Compiling sketch...")
+
+        # Look for .ino files in the project directory
+        sketch_files = list(project_dir.glob("*.ino"))
+        if not sketch_files:
+            return None
+
+        sketch_path = sketch_files[0]
+        sketch_obj_files = compiler.compile_sketch(sketch_path)
+
+        if verbose:
+            print(f"      Compiled {len(sketch_obj_files)} sketch file(s)")
+
+        return sketch_obj_files
+
+    def _create_bt_stub(
+        self,
+        build_dir: Path,
+        compiler: ConfigurableCompiler,
+        verbose: bool
+    ) -> Optional[Path]:
+        """
+        Create a Bluetooth stub for ESP32 targets where esp32-hal-bt.c fails to compile.
+
+        On non-ESP32 targets (ESP32-C6, ESP32-S3, etc.), the esp32-hal-bt.c file may
+        fail to compile due to SDK incompatibilities, but initArduino() still references
+        btInUse(). This creates a stub implementation that returns false.
+
+        Args:
+            build_dir: Build directory
+            compiler: Configured compiler instance
+            verbose: Whether to print verbose output
+
+        Returns:
+            Path to compiled stub object file, or None on error
+        """
+        try:
+            # Create stub source file
+            stub_dir = build_dir / "stubs"
+            stub_dir.mkdir(parents=True, exist_ok=True)
+            stub_file = stub_dir / "bt_stub.c"
+
+            # Write minimal btInUse() implementation
+            stub_content = """// Bluetooth stub for ESP32 targets where esp32-hal-bt.c fails to compile
+// This provides a fallback implementation of btInUse() that always returns false
+
+#include <stdbool.h>
+
+// Weak attribute allows this to be overridden if the real implementation links
+__attribute__((weak)) bool btInUse(void) {
+    return false;
+}
+"""
+            stub_file.write_text(stub_content)
+
+            # Compile the stub
+            stub_obj = stub_dir / "bt_stub.o"
+            compiled_obj = compiler.compile_source(stub_file, stub_obj)
+
+            if verbose:
+                print(f"      Created Bluetooth stub: {compiled_obj.name}")
+
+            return compiled_obj
+
+        except KeyboardInterrupt as ke:
+            from fbuild.interrupt_utils import handle_keyboard_interrupt_properly
+
+            handle_keyboard_interrupt_properly(ke)
+            raise  # Never reached, but satisfies type checker
+        except Exception as e:
+            if verbose:
+                print(f"Warning: Failed to create Bluetooth stub: {e}")
+            return None
+
+    def _generate_boot_components(
+        self,
+        linker: ConfigurableLinker,
+        mcu: str,
+        verbose: bool
+    ) -> tuple[Optional[Path], Optional[Path]]:
+        """
+        Generate bootloader and partition table for ESP32.
+
+        Args:
+            linker: Configured linker instance
+            mcu: MCU identifier
+            verbose: Verbose output mode
+
+        Returns:
+            Tuple of (bootloader_bin, partitions_bin)
+        """
+        bootloader_bin = None
+        partitions_bin = None
+
+        if not mcu.startswith("esp32"):
+            return bootloader_bin, partitions_bin
+
+        if verbose:
+            print("[11/12] Generating bootloader...")
+        try:
+            bootloader_bin = linker.generate_bootloader()
+        except KeyboardInterrupt as ke:
+            from fbuild.interrupt_utils import handle_keyboard_interrupt_properly
+            handle_keyboard_interrupt_properly(ke)
+            raise  # Never reached, but satisfies type checker
+        except Exception as e:
+            if verbose:
+                print(f"Warning: Could not generate bootloader: {e}")
+
+        if verbose:
+            print("[12/12] Generating partition table...")
+        try:
+            partitions_bin = linker.generate_partition_table()
+        except KeyboardInterrupt as ke:
+            from fbuild.interrupt_utils import handle_keyboard_interrupt_properly
+            handle_keyboard_interrupt_properly(ke)
+            raise  # Never reached, but satisfies type checker
+        except Exception as e:
+            if verbose:
+                print(f"Warning: Could not generate partition table: {e}")
+
+        return bootloader_bin, partitions_bin
+
+    def _print_success(
+        self,
+        build_time: float,
+        firmware_elf: Path,
+        firmware_bin: Path,
+        bootloader_bin: Optional[Path],
+        partitions_bin: Optional[Path]
+    ) -> None:
+        """
+        Print build success message.
+
+        Args:
+            build_time: Total build time
+            firmware_elf: Path to firmware ELF
+            firmware_bin: Path to firmware binary
+            bootloader_bin: Optional path to bootloader
+            partitions_bin: Optional path to partition table
+        """
+        # Build success message
+        message_lines = ["BUILD SUCCESSFUL!"]
+        message_lines.append(f"Build time: {build_time:.2f}s")
+        message_lines.append(f"Firmware ELF: {firmware_elf}")
+        message_lines.append(f"Firmware BIN: {firmware_bin}")
+        if bootloader_bin:
+            message_lines.append(f"Bootloader: {bootloader_bin}")
+        if partitions_bin:
+            message_lines.append(f"Partitions: {partitions_bin}")
+
+        BannerFormatter.print_banner("\n".join(message_lines), width=60, center=False)
+
+    def _error_result(self, start_time: float, message: str) -> BuildResultESP32:
+        """
+        Create an error result.
+
+        Args:
+            start_time: Build start time
+            message: Error message
+
+        Returns:
+            BuildResultESP32 indicating failure
+        """
+        return BuildResultESP32(
+            success=False,
+            firmware_bin=None,
+            firmware_elf=None,
+            bootloader_bin=None,
+            partitions_bin=None,
+            size_info=None,
+            build_time=time.time() - start_time,
+            message=message
+        )