fbuild 1.1.0__py3-none-any.whl

fbuild/packages/platform_esp32.py

@@ -0,0 +1,383 @@
+"""ESP32 Platform Package Management.
+
+This module handles downloading, extracting, and managing ESP32 platform packages
+from GitHub releases. It provides access to the Arduino-ESP32 core, toolchains,
+and platform-specific tools needed for ESP32 builds.
+
+Platform Structure (after extraction):
+    platform-espressif32/
+    ├── platform.json           # Package metadata with download URLs
+    ├── boards/                 # Board definitions (JSON files)
+    │   └── esp32-c6-devkitm-1.json
+    ├── builder/                # PlatformIO build scripts
+    │   └── frameworks/
+    │       └── arduino.py
+    └── ...                     # Other platform files
+
+Key Packages (from platform.json):
+    - framework-arduinoespressif32: Arduino core (cores/, variants/)
+    - framework-arduinoespressif32-libs: Pre-built ESP-IDF libraries
+    - toolchain-riscv32-esp: RISC-V GCC (for C3, C6, H2)
+    - toolchain-xtensa-esp-elf: Xtensa GCC (for ESP32, S2, S3)
+    - tool-esptoolpy: Upload tool
+"""
+
+import json
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from .cache import Cache
+from .downloader import DownloadError, ExtractionError, PackageDownloader
+from .package import IPackage, PackageError
+
+
+class PlatformErrorESP32(PackageError):
+    """Raised when ESP32 platform operations fail."""
+
+    pass
+
+
+class PlatformESP32(IPackage):
+    """Manages ESP32 platform package download, extraction, and access.
+
+    This class handles the pioarduino/platform-espressif32 package which contains:
+    - Arduino core for ESP32 family (C3, C6, S2, S3, H2, etc.)
+    - Toolchains (riscv32-esp-elf-gcc, xtensa-esp-elf-gcc)
+    - Platform tools (esptool, mkspiffs, etc.)
+    - Board definitions and variants
+    """
+
+    def __init__(self, cache: Cache, platform_url: str, show_progress: bool = True):
+        """Initialize ESP32 platform manager.
+
+        Args:
+            cache: Cache manager instance
+            platform_url: URL to platform package (e.g., GitHub release ZIP)
+            show_progress: Whether to show download/extraction progress
+        """
+        self.cache = cache
+        self.platform_url = platform_url
+        self.show_progress = show_progress
+        self.downloader = PackageDownloader()
+
+        # Extract version from URL (e.g., "55.03.34" from release tag)
+        self.version = self._extract_version_from_url(platform_url)
+
+        # Get platform path from cache
+        self.platform_path = cache.get_platform_path(platform_url, self.version)
+
+    @staticmethod
+    def _extract_version_from_url(url: str) -> str:
+        """Extract version string from platform URL.
+
+        Args:
+            url: Platform URL (e.g., https://github.com/.../55.03.34/platform.zip)
+
+        Returns:
+            Version string (e.g., "55.03.34")
+        """
+        # URL format: .../releases/download/{version}/platform-espressif32.zip
+        parts = url.split("/")
+        for i, part in enumerate(parts):
+            if part == "download" and i + 1 < len(parts):
+                return parts[i + 1]
+
+        # Fallback: use URL hash if version extraction fails
+        from .cache import Cache
+
+        return Cache.hash_url(url)[:8]
+
+    def ensure_package(self) -> Path:
+        """Ensure platform is downloaded and extracted.
+
+        Returns:
+            Path to the extracted platform directory
+
+        Raises:
+            PlatformErrorESP32: If download or extraction fails
+        """
+        return self.ensure_platform()
+
+    def ensure_platform(self) -> Path:
+        """Ensure platform is downloaded and extracted.
+
+        Returns:
+            Path to the extracted platform directory
+
+        Raises:
+            PlatformErrorESP32: If download or extraction fails
+        """
+        if self.is_installed():
+            if self.show_progress:
+                print(f"Using cached ESP32 platform {self.version}")
+            return self.platform_path
+
+        try:
+            if self.show_progress:
+                print(f"Downloading ESP32 platform {self.version}...")
+
+            # Download and extract platform package
+            self.cache.ensure_directories()
+
+            # Use downloader to handle download and extraction
+            archive_name = Path(self.platform_url).name
+            archive_path = self.platform_path.parent / archive_name
+
+            # Download if not cached
+            if not archive_path.exists():
+                archive_path.parent.mkdir(parents=True, exist_ok=True)
+                self.downloader.download(self.platform_url, archive_path, show_progress=self.show_progress)
+            else:
+                if self.show_progress:
+                    print(f"Using cached archive {archive_name}")
+
+            # Extract to platform directory
+            if self.show_progress:
+                print(f"Extracting platform to {self.platform_path}...")
+
+            # Create temp extraction directory
+            temp_extract = self.platform_path.parent / "temp_extract"
+            temp_extract.mkdir(parents=True, exist_ok=True)
+
+            self.downloader.extract_archive(archive_path, temp_extract, show_progress=self.show_progress)
+
+            # Find the platform directory in the extracted content
+            # Usually it's a subdirectory like "platform-espressif32/"
+            extracted_dirs = list(temp_extract.glob("platform-*"))
+            if not extracted_dirs:
+                # Maybe it extracted directly
+                extracted_dirs = [temp_extract]
+
+            source_dir = extracted_dirs[0]
+
+            # Move to final location
+            if self.platform_path.exists():
+                import shutil
+
+                shutil.rmtree(self.platform_path)
+
+            source_dir.rename(self.platform_path)
+
+            # Clean up temp directory
+            if temp_extract.exists() and temp_extract != self.platform_path:
+                import shutil
+
+                shutil.rmtree(temp_extract, ignore_errors=True)
+
+            if self.show_progress:
+                print(f"ESP32 platform installed to {self.platform_path}")
+
+            return self.platform_path
+
+        except (DownloadError, ExtractionError) as e:
+            raise PlatformErrorESP32(f"Failed to install ESP32 platform: {e}")
+        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:
+            raise PlatformErrorESP32(f"Unexpected error installing platform: {e}")
+
+    def is_installed(self) -> bool:
+        """Check if platform is already installed.
+
+        Returns:
+            True if platform directory exists with key files
+        """
+        if not self.platform_path.exists():
+            return False
+
+        # Verify essential platform files exist
+        required_files = [
+            self.platform_path / "platform.json",
+            self.platform_path / "boards",
+        ]
+
+        return all(f.exists() for f in required_files)
+
+    def get_platform_json(self) -> Dict[str, Any]:
+        """Load and parse platform.json metadata.
+
+        Returns:
+            Dictionary containing platform metadata
+
+        Raises:
+            PlatformErrorESP32: If platform.json doesn't exist or is invalid
+        """
+        platform_json_path = self.platform_path / "platform.json"
+
+        if not platform_json_path.exists():
+            raise PlatformErrorESP32(f"platform.json not found at {platform_json_path}. " + "Ensure platform is downloaded first.")
+
+        try:
+            with open(platform_json_path, "r") as f:
+                return json.load(f)
+        except json.JSONDecodeError as e:
+            raise PlatformErrorESP32(f"Failed to parse platform.json: {e}")
+        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:
+            raise PlatformErrorESP32(f"Failed to read platform.json: {e}")
+
+    def get_package_url(self, package_name: str) -> Optional[str]:
+        """Get download URL for a specific package.
+
+        Args:
+            package_name: Name of the package (e.g., "toolchain-riscv32-esp")
+
+        Returns:
+            URL string or None if package not found
+        """
+        platform_json = self.get_platform_json()
+        packages = platform_json.get("packages", {})
+
+        if package_name not in packages:
+            return None
+
+        package_info = packages[package_name]
+        return package_info.get("version")  # "version" field contains URL
+
+    def get_required_packages(self, board_mcu: str) -> Dict[str, str]:
+        """Get required packages for a specific MCU.
+
+        Args:
+            board_mcu: MCU type (e.g., "esp32c6", "esp32s3", "esp32")
+
+        Returns:
+            Dictionary of package_name -> url for required packages
+        """
+        packages = {}
+
+        # All ESP32 boards need the Arduino framework
+        framework_url = self.get_package_url("framework-arduinoespressif32")
+        if framework_url:
+            packages["framework-arduinoespressif32"] = framework_url
+
+        libs_url = self.get_package_url("framework-arduinoespressif32-libs")
+        if libs_url:
+            packages["framework-arduinoespressif32-libs"] = libs_url
+
+        # Check for MCU-specific skeleton libraries
+        # These are used when the main libs package is empty or incomplete
+        # The naming pattern is: framework-arduino-{mcu_suffix}-skeleton-lib
+        # where mcu_suffix is extracted from the MCU name (e.g., "esp32c2" -> "c2")
+        mcu_suffix = board_mcu.replace("esp32", "")
+        skeleton_lib_name = f"framework-arduino-{mcu_suffix}-skeleton-lib"
+        skeleton_lib_url = self.get_package_url(skeleton_lib_name)
+        if skeleton_lib_url:
+            packages[skeleton_lib_name] = skeleton_lib_url
+
+        # Determine which toolchain is needed based on MCU architecture
+        if board_mcu in [
+            "esp32c3",
+            "esp32c6",
+            "esp32h2",
+            "esp32c2",
+            "esp32c5",
+            "esp32p4",
+        ]:
+            # RISC-V based ESP32s
+            toolchain_url = self.get_package_url("toolchain-riscv32-esp")
+            if toolchain_url:
+                packages["toolchain-riscv32-esp"] = toolchain_url
+        else:
+            # Xtensa based ESP32s (original ESP32, S2, S3)
+            toolchain_url = self.get_package_url("toolchain-xtensa-esp-elf")
+            if toolchain_url:
+                packages["toolchain-xtensa-esp-elf"] = toolchain_url
+
+        # Add esptool (needed for all ESP32 boards)
+        esptool_url = self.get_package_url("tool-esptoolpy")
+        if esptool_url:
+            packages["tool-esptoolpy"] = esptool_url
+
+        return packages
+
+    def get_boards_dir(self) -> Path:
+        """Get path to boards directory.
+
+        Returns:
+            Path to boards directory containing JSON board definitions
+        """
+        return self.platform_path / "boards"
+
+    def get_board_json(self, board_id: str) -> Dict[str, Any]:
+        """Load board configuration from JSON.
+
+        Args:
+            board_id: Board identifier (e.g., "esp32-c6-devkitm-1")
+
+        Returns:
+            Dictionary containing board configuration
+
+        Raises:
+            PlatformErrorESP32: If board JSON doesn't exist or is invalid
+        """
+        board_json_path = self.get_boards_dir() / f"{board_id}.json"
+
+        if not board_json_path.exists():
+            raise PlatformErrorESP32(f"Board definition not found: {board_id} " + f"at {board_json_path}")
+
+        try:
+            with open(board_json_path, "r") as f:
+                return json.load(f)
+        except json.JSONDecodeError as e:
+            raise PlatformErrorESP32(f"Failed to parse board JSON: {e}")
+        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:
+            raise PlatformErrorESP32(f"Failed to read board JSON: {e}")
+
+    def list_boards(self) -> list[str]:
+        """List all available board IDs.
+
+        Returns:
+            List of board identifiers
+        """
+        boards_dir = self.get_boards_dir()
+        if not boards_dir.exists():
+            return []
+
+        return [f.stem for f in boards_dir.glob("*.json") if f.is_file() and not f.name.endswith(".py")]
+
+    def get_package_info(self) -> Dict[str, Any]:
+        """Get information about the installed platform.
+
+        Returns:
+            Dictionary with platform information
+        """
+        return self.get_platform_info()
+
+    def get_platform_info(self) -> Dict[str, Any]:
+        """Get information about the installed platform.
+
+        Returns:
+            Dictionary with platform information
+        """
+        info = {
+            "version": self.version,
+            "path": str(self.platform_path),
+            "url": self.platform_url,
+            "installed": self.is_installed(),
+        }
+
+        if self.is_installed():
+            info["boards_dir"] = str(self.get_boards_dir())
+            info["available_boards"] = len(self.list_boards())
+
+            # Get package information
+            try:
+                platform_json = self.get_platform_json()
+                info["platform_version"] = platform_json.get("version")
+                info["available_packages"] = list(platform_json.get("packages", {}).keys())
+            except PlatformErrorESP32:
+                pass
+
+        return info

fbuild/packages/platform_teensy.py

@@ -0,0 +1,312 @@
+"""Teensy Platform Package Management.
+
+This module coordinates Teensy platform components including toolchain and framework.
+It provides a unified interface for managing Teensy 4.x platform builds.
+
+Platform Components:
+    - ARM GCC Toolchain (arm-none-eabi-gcc)
+    - Teensy Cores Framework (Arduino core for Teensy 4.x)
+
+Supported Boards:
+    - Teensy 4.1 (NXP i.MX RT1062, ARM Cortex-M7 @ 600MHz)
+    - Teensy 4.0 (NXP i.MX RT1062, ARM Cortex-M7 @ 600MHz)
+"""
+
+from pathlib import Path
+from typing import Any, Dict, List
+
+from .cache import Cache
+from .framework_teensy import FrameworkErrorTeensy, FrameworkTeensy
+from .package import IPackage, PackageError
+from .toolchain_teensy import ToolchainErrorTeensy, ToolchainTeensy
+
+
+class PlatformErrorTeensy(PackageError):
+    """Raised when Teensy platform operations fail."""
+
+    pass
+
+
+class PlatformTeensy(IPackage):
+    """Manages Teensy platform components and configuration.
+
+    This class coordinates the Teensy toolchain and framework to provide
+    a complete build environment for Teensy 4.x boards.
+    """
+
+    def __init__(self, cache: Cache, board_mcu: str, show_progress: bool = True):
+        """Initialize Teensy platform manager.
+
+        Args:
+            cache: Cache manager instance
+            board_mcu: MCU type (e.g., "imxrt1062")
+            show_progress: Whether to show download/extraction progress
+        """
+        self.cache = cache
+        self.board_mcu = board_mcu
+        self.show_progress = show_progress
+
+        # Initialize toolchain and framework
+        self.toolchain = ToolchainTeensy(cache, show_progress=show_progress)
+        self.framework = FrameworkTeensy(cache, show_progress=show_progress)
+
+    def ensure_package(self) -> Path:
+        """Ensure platform components are downloaded and extracted.
+
+        Returns:
+            Path to the framework directory (main platform directory)
+
+        Raises:
+            PlatformErrorTeensy: If download or extraction fails
+        """
+        try:
+            # Ensure toolchain is installed
+            self.toolchain.ensure_toolchain()
+
+            # Ensure framework is installed
+            framework_path = self.framework.ensure_framework()
+
+            return framework_path
+
+        except (ToolchainErrorTeensy, FrameworkErrorTeensy) as e:
+            raise PlatformErrorTeensy(f"Failed to install Teensy platform: {e}")
+        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:
+            raise PlatformErrorTeensy(f"Unexpected error installing platform: {e}")
+
+    def is_installed(self) -> bool:
+        """Check if platform is already installed.
+
+        Returns:
+            True if both toolchain and framework are installed
+        """
+        return self.toolchain.is_installed() and self.framework.is_installed()
+
+    def get_compiler_flags(self, board_config: Any) -> List[str]:
+        """Get compiler flags for Teensy builds.
+
+        Args:
+            board_config: Board configuration object
+
+        Returns:
+            List of compiler flags
+        """
+        flags = [
+            # CPU and architecture
+            "-mcpu=cortex-m7",
+            "-mthumb",
+            "-mfloat-abi=hard",
+            "-mfpu=fpv5-d16",
+            # Optimization
+            "-O2",
+            "-g",
+            # Warnings
+            "-Wall",
+            "-Wextra",
+            "-Wno-unused-parameter",
+            # Standards
+            "-std=gnu11",  # For C files
+            # Board-specific defines
+            f"-DF_CPU={board_config.f_cpu}",
+            "-DARDUINO_TEENSY41",
+            "-D__IMXRT1062__",
+            "-DARDUINO=10819",
+            "-DTEENSYDUINO=159",
+            "-DUSB_SERIAL",
+            # Memory layout
+            "-DARDUINO_ARCH_TEENSY",
+        ]
+
+        return flags
+
+    def get_compiler_flags_cpp(self, board_config: Any) -> List[str]:
+        """Get C++ compiler flags for Teensy builds.
+
+        Args:
+            board_config: Board configuration object
+
+        Returns:
+            List of C++ compiler flags
+        """
+        # Start with base C flags
+        flags = self.get_compiler_flags(board_config)
+
+        # Replace C standard with C++ standard
+        flags = [f for f in flags if not f.startswith("-std=gnu11")]
+        flags.extend(
+            [
+                "-std=gnu++14",
+                "-fno-exceptions",
+                "-fno-rtti",
+                "-felide-constructors",
+                "-fno-threadsafe-statics",
+            ]
+        )
+
+        return flags
+
+    def get_linker_flags(self, board_config: Any, board_id: str = "teensy41") -> List[str]:
+        """Get linker flags for Teensy builds.
+
+        Args:
+            board_config: Board configuration object
+            board_id: Board identifier for linker script selection
+
+        Returns:
+            List of linker flags
+        """
+        # Get linker script
+        linker_script = self.framework.get_linker_script(board_id)
+        if not linker_script:
+            raise PlatformErrorTeensy(f"Linker script not found for board: {board_id}")
+
+        flags = [
+            # CPU and architecture
+            "-mcpu=cortex-m7",
+            "-mthumb",
+            "-mfloat-abi=hard",
+            "-mfpu=fpv5-d16",
+            # Optimization
+            "-O2",
+            # Linker script
+            f"-T{linker_script}",
+            # Linker options
+            "-Wl,--gc-sections",
+            "-Wl,--print-memory-usage",
+            # Math library
+            "-lm",
+            "-lstdc++",
+        ]
+
+        return flags
+
+    def get_include_dirs(self, board_config: Any) -> List[Path]:
+        """Get include directories for Teensy builds.
+
+        Args:
+            board_config: Board configuration object
+
+        Returns:
+            List of include directory paths
+        """
+        includes = []
+
+        # Core includes
+        try:
+            core_includes = self.framework.get_core_includes("teensy4")
+            includes.extend(core_includes)
+        except FrameworkErrorTeensy:
+            pass
+
+        return includes
+
+    def get_core_sources(self) -> List[Path]:
+        """Get core source files for Teensy builds.
+
+        Returns:
+            List of core source file paths
+        """
+        try:
+            return self.framework.get_core_sources("teensy4")
+        except FrameworkErrorTeensy:
+            return []
+
+    def get_toolchain_binaries(self) -> Dict[str, Path]:
+        """Get paths to toolchain binaries.
+
+        Returns:
+            Dictionary mapping tool names to paths
+
+        Raises:
+            PlatformErrorTeensy: If toolchain binaries are not found
+        """
+        tools = self.toolchain.get_all_tool_paths()
+
+        # Verify all required tools exist
+        required_tools = ["gcc", "g++", "ar", "objcopy", "size"]
+        for tool_name in required_tools:
+            if tool_name not in tools or tools[tool_name] is None:
+                raise PlatformErrorTeensy(f"Required tool not found: {tool_name}")
+
+        # Filter out None values
+        return {name: path for name, path in tools.items() if path is not None}
+
+    def get_package_info(self) -> Dict[str, Any]:
+        """Get information about the installed platform.
+
+        Returns:
+            Dictionary with platform information
+        """
+        return self.get_platform_info()
+
+    def get_board_json(self, board_id: str) -> Dict[str, Any]:
+        """Get board configuration in JSON format.
+
+        This method returns board configuration compatible with the format
+        expected by ConfigurableCompiler and ConfigurableLinker.
+
+        Args:
+            board_id: Board identifier (e.g., "teensy41")
+
+        Returns:
+            Dictionary containing board configuration
+
+        Raises:
+            PlatformErrorTeensy: If board is not supported
+        """
+        # Map board IDs to their configurations
+        board_configs = {
+            "teensy41": {
+                "build": {
+                    "mcu": "imxrt1062",
+                    "f_cpu": "600000000L",
+                    "core": "teensy4",
+                    "variant": "teensy41",
+                    "board": "TEENSY41",
+                },
+                "name": "Teensy 4.1",
+                "upload": {
+                    "maximum_size": 8126464,
+                    "maximum_ram_size": 524288,
+                },
+            },
+            "teensy40": {
+                "build": {
+                    "mcu": "imxrt1062",
+                    "f_cpu": "600000000L",
+                    "core": "teensy4",
+                    "variant": "teensy40",
+                    "board": "TEENSY40",
+                },
+                "name": "Teensy 4.0",
+                "upload": {
+                    "maximum_size": 2031616,
+                    "maximum_ram_size": 524288,
+                },
+            },
+        }
+
+        if board_id not in board_configs:
+            raise PlatformErrorTeensy(f"Unsupported board: {board_id}. " + f"Supported boards: {', '.join(board_configs.keys())}")
+
+        return board_configs[board_id]
+
+    def get_platform_info(self) -> Dict[str, Any]:
+        """Get information about the installed platform.
+
+        Returns:
+            Dictionary with platform information
+        """
+        info = {
+            "platform": "teensy",
+            "mcu": self.board_mcu,
+            "installed": self.is_installed(),
+            "toolchain": self.toolchain.get_toolchain_info(),
+            "framework": self.framework.get_framework_info(),
+        }
+
+        return info