fbuild 1.2.8__py3-none-any.whl

fbuild/packages/platformio_registry.py

@@ -0,0 +1,369 @@
+"""PlatformIO Registry client for downloading libraries.
+
+This module provides access to the PlatformIO registry API for resolving
+and downloading library dependencies.
+"""
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+import requests
+
+from fbuild.packages.downloader import PackageDownloader
+
+
+class RegistryError(Exception):
+    """Exception raised for registry-related errors."""
+
+    pass
+
+
+@dataclass
+class LibrarySpec:
+    """Parsed library specification from platformio.ini lib_deps."""
+
+    owner: str
+    name: str
+    version: Optional[str] = None
+    is_local: bool = False
+    local_path: Optional[Path] = None
+
+    @classmethod
+    def parse(cls, spec: str) -> "LibrarySpec":
+        """Parse a library specification string.
+
+        Supports formats:
+        - owner/name@version (e.g., fastled/FastLED@^3.7.8)
+        - owner/name (e.g., fastled/FastLED)
+        - name@version (e.g., FastLED@^3.7.8)
+        - name (e.g., FastLED)
+        - URL (e.g., https://github.com/FastLED/FastLED)
+        - symlink:// path (e.g., symlink://./)
+        - Name=symlink://path (e.g., FastLED=symlink://./)
+        - file:// path (e.g., file://../../fastled9)
+        - Relative path (e.g., ../../fastled9)
+
+        Args:
+            spec: Library specification string
+
+        Returns:
+            LibrarySpec instance
+
+        Raises:
+            RegistryError: If spec format is invalid
+        """
+        # Handle Name=symlink://path format (FastLED pattern)
+        if "=" in spec and "symlink://" in spec:
+            name, path_spec = spec.split("=", 1)
+            path_spec = path_spec.replace("symlink://", "", 1).strip()
+            local_path = Path(path_spec)
+            return cls(owner="", name=name.strip(), version=None, is_local=True, local_path=local_path)
+
+        # Handle bare symlink://path format
+        if spec.startswith("symlink://"):
+            path_str = spec.replace("symlink://", "", 1)
+            local_path = Path(path_str)
+            # Extract library name from path (last component)
+            name = local_path.name if local_path.name else "library"
+            return cls(owner="", name=name, version=None, is_local=True, local_path=local_path)
+
+        # Handle file:// URLs - local library paths
+        if spec.startswith("file://"):
+            path_str = spec.replace("file://", "", 1)
+            local_path = Path(path_str)
+            # Extract library name from path
+            name = local_path.name
+            return cls(owner="", name=name, version=None, is_local=True, local_path=local_path)
+
+        # Handle URLs - convert to owner/name format
+        if spec.startswith("http://") or spec.startswith("https://"):
+            # Extract owner/name from GitHub URL
+            match = re.search(r"github\.com/([^/]+)/([^/]+?)(?:\.git)?/?$", spec)
+            if match:
+                owner, name = match.groups()
+                return cls(owner=owner, name=name, version=None)
+            raise RegistryError(f"Cannot parse URL as library spec: {spec}")
+
+        # Handle relative/absolute paths (../foo, ./foo, /abs/path, C:/path)
+        # IMPORTANT: Check this AFTER URLs and BEFORE registry specs
+        # to avoid confusing "owner/name" registry specs with paths
+        is_path = (
+            spec.startswith(".")  # Relative paths like ./foo, ../bar
+            or spec.startswith("/")  # Absolute Unix paths
+            or spec.startswith("\\")  # Absolute Windows paths (UNC)
+            or (len(spec) > 2 and spec[1] == ":")  # Windows drive letter (C:/, D:/)
+        )
+        if is_path:
+            local_path = Path(spec)
+            name = local_path.name
+            return cls(owner="", name=name, version=None, is_local=True, local_path=local_path)
+
+        # Parse owner/name@version format (registry specs)
+        # This must come AFTER path checking to avoid treating "owner/name" as a path
+        if "@" in spec:
+            lib_part, version = spec.rsplit("@", 1)
+        else:
+            lib_part = spec
+            version = None
+
+        # Split owner/name
+        if "/" in lib_part:
+            owner, name = lib_part.split("/", 1)
+        else:
+            # If no owner specified, we'll need to search registry
+            owner = ""
+            name = lib_part
+
+        return cls(owner=owner, name=name, version=version)
+
+    def __str__(self) -> str:
+        """String representation."""
+        result = f"{self.owner}/{self.name}" if self.owner else self.name
+        if self.version:
+            result += f"@{self.version}"
+        return result
+
+
+@dataclass
+class LibraryVersion:
+    """Information about a specific library version."""
+
+    version: str
+    download_url: str
+    homepage: Optional[str] = None
+    repository: Optional[str] = None
+
+
+class PlatformIORegistry:
+    """Client for PlatformIO registry API."""
+
+    API_URL = "https://api.registry.platformio.org/v3"
+
+    def __init__(self, downloader: Optional[PackageDownloader] = None):
+        """Initialize registry client.
+
+        Args:
+            downloader: Optional package downloader instance
+        """
+        self.downloader = downloader or PackageDownloader()
+
+    def search_library(self, name: str) -> Optional[str]:
+        """Search for a library by name to find its owner.
+
+        Args:
+            name: Library name
+
+        Returns:
+            Owner name if found, None otherwise
+        """
+        try:
+            # Use search API
+            search_url = f"{self.API_URL}/search"
+            response = requests.get(search_url, params={"query": name}, timeout=10)
+            response.raise_for_status()
+
+            result = response.json()
+            items = result.get("items", [])
+
+            if items:
+                # Return first match owner
+                first = items[0]
+                owner_info = first.get("owner", {})
+                if isinstance(owner_info, dict):
+                    return owner_info.get("username")
+                return owner_info
+
+        except KeyboardInterrupt as ke:
+            from fbuild.interrupt_utils import handle_keyboard_interrupt_properly
+
+            handle_keyboard_interrupt_properly(ke)
+        except Exception as e:
+            print(f"Warning: Could not search for library {name}: {e}")
+
+        return None
+
+    def get_library_info(self, owner: str, name: str) -> dict:
+        """Get library information from registry using search API.
+
+        Args:
+            owner: Library owner (user/org name)
+            name: Library name
+
+        Returns:
+            Library information dictionary
+
+        Raises:
+            RegistryError: If library not found or API error
+        """
+        try:
+            # Build query
+            query = f"{owner}/{name}".lower() if owner else name.lower()
+
+            search_url = f"{self.API_URL}/search"
+            response = requests.get(search_url, params={"query": query}, timeout=10)
+            response.raise_for_status()
+
+            result = response.json()
+            items = result.get("items", [])
+
+            # Find exact match
+            for item in items:
+                item_owner = item.get("owner", {}).get("username", "").lower()
+                item_name = item.get("name", "").lower()
+
+                # Exact match
+                if item_name == name.lower():
+                    if not owner or item_owner == owner.lower():
+                        return item
+
+            # No match found
+            raise RegistryError(f"Library '{owner}/{name}' not found in registry")
+
+        except requests.RequestException as e:
+            raise RegistryError(f"Registry API error: {e}") from e
+
+    def resolve_version(self, owner: str, name: str, version_spec: Optional[str] = None) -> LibraryVersion:
+        """Resolve a version specification to a specific version.
+
+        Args:
+            owner: Library owner
+            name: Library name
+            version_spec: Version specification (e.g., "^3.7.8", "3.7.8", "latest")
+                         If None, uses latest version
+
+        Returns:
+            LibraryVersion with download URL
+
+        Raises:
+            RegistryError: If version cannot be resolved
+        """
+        info = self.get_library_info(owner, name)
+
+        # Get version info from search result (latest version)
+        version_info = info.get("version")
+        if not version_info:
+            raise RegistryError(f"No version information available for {owner}/{name}")
+
+        # For now, use the latest version from search results
+        # TODO: Implement proper version constraint matching by querying version history
+        version_str = version_info.get("name")
+        if not version_str:
+            raise RegistryError(f"No version name for {owner}/{name}")
+
+        files = version_info.get("files", [])
+        if not files:
+            raise RegistryError(f"No download files available for {owner}/{name}@{version_str}")
+
+        # Use first file (should be .tar.gz)
+        download_url = files[0].get("download_url")
+        if not download_url:
+            raise RegistryError(f"No download URL for {owner}/{name}@{version_str}")
+
+        return LibraryVersion(
+            version=version_str,
+            download_url=download_url,
+            homepage=None,
+            repository=None,
+        )
+
+    def download_library(self, spec: LibrarySpec, dest_dir: Path, show_progress: bool = True) -> Path:
+        """Download a library from the registry.
+
+        Args:
+            spec: Library specification
+            dest_dir: Destination directory for extraction
+            show_progress: Whether to show download progress
+
+        Returns:
+            Path to extracted library directory
+
+        Raises:
+            RegistryError: If download fails
+        """
+        # Resolve owner if not specified
+        owner = spec.owner
+        if not owner:
+            owner = self.search_library(spec.name)
+            if not owner:
+                raise RegistryError(f"Could not find owner for library '{spec.name}'")
+
+        # Resolve version
+        lib_version = self.resolve_version(owner, spec.name, spec.version)
+
+        if show_progress:
+            print(f"Downloading {owner}/{spec.name}@{lib_version.version}")
+
+        # Download archive
+        dest_dir.mkdir(parents=True, exist_ok=True)
+        archive_path = dest_dir / "library.tar.gz"
+
+        try:
+            self.downloader.download(lib_version.download_url, archive_path, show_progress=show_progress)
+        except KeyboardInterrupt as ke:
+            from fbuild.interrupt_utils import handle_keyboard_interrupt_properly
+
+            handle_keyboard_interrupt_properly(ke)
+        except Exception as e:
+            raise RegistryError(f"Failed to download library: {e}") from e
+
+        # Extract archive
+        if show_progress:
+            print(f"Extracting {spec.name}...")
+
+        extract_dir = dest_dir / "_extract"
+        extract_dir.mkdir(exist_ok=True)
+
+        try:
+            self.downloader.extract_archive(archive_path, extract_dir, show_progress=show_progress)
+        except KeyboardInterrupt as ke:
+            from fbuild.interrupt_utils import handle_keyboard_interrupt_properly
+
+            handle_keyboard_interrupt_properly(ke)
+        except Exception as e:
+            raise RegistryError(f"Failed to extract library: {e}") from e
+
+        # Find the actual library directory
+        # Archives often have a top-level directory
+        extracted_items = list(extract_dir.iterdir())
+
+        if len(extracted_items) == 1 and extracted_items[0].is_dir():
+            src_dir = extracted_items[0]
+        else:
+            src_dir = extract_dir
+
+        # Move to final location
+        final_dir = dest_dir / "src"
+        if final_dir.exists():
+            import shutil
+
+            shutil.rmtree(final_dir)
+
+        src_dir.rename(final_dir)
+
+        # Clean up
+        if extract_dir.exists():
+            import shutil
+
+            shutil.rmtree(extract_dir)
+        archive_path.unlink()
+
+        # Save library info
+        info_file = dest_dir / "library.json"
+        with open(info_file, "w", encoding="utf-8") as f:
+            json.dump(
+                {
+                    "name": spec.name,
+                    "owner": owner,
+                    "version": lib_version.version,
+                    "download_url": lib_version.download_url,
+                    "repository": lib_version.repository,
+                    "homepage": lib_version.homepage,
+                },
+                f,
+                indent=2,
+            )
+
+        return final_dir

fbuild/packages/sdk_utils.py

@@ -0,0 +1,231 @@
+"""ESP32 SDK Path Utilities.
+
+This module provides utilities for discovering and managing ESP-IDF SDK paths,
+including include directories and precompiled libraries.
+"""
+
+from pathlib import Path
+from typing import List
+
+
+class SDKPathResolver:
+    """Resolves SDK paths for ESP-IDF frameworks.
+
+    Provides methods for discovering include directories and libraries
+    used by ESP-IDF based projects.
+    """
+
+    # MCU fallback mappings for platforms that don't have full SDK support
+    MCU_FALLBACKS = {
+        "esp32c2": "esp32c3",  # ESP32-C2 can use ESP32-C3 SDK (both rv32imc RISC-V)
+    }
+
+    def __init__(self, sdk_base_dir: Path, show_progress: bool = True):
+        """Initialize SDK path resolver.
+
+        Args:
+            sdk_base_dir: Base directory of the SDK (e.g., framework_path/tools/sdk)
+            show_progress: Whether to show progress messages
+        """
+        self.sdk_base_dir = sdk_base_dir
+        self.show_progress = show_progress
+
+    def _resolve_mcu(self, mcu: str) -> str:
+        """Resolve MCU to actual SDK directory, applying fallback if needed.
+
+        Args:
+            mcu: MCU type (e.g., "esp32c2", "esp32c6")
+
+        Returns:
+            Resolved MCU type for SDK lookup
+        """
+        # Check if MCU SDK directory exists
+        mcu_dir = self.sdk_base_dir / mcu
+        if mcu_dir.exists():
+            return mcu
+
+        # Try fallback if available
+        if mcu in self.MCU_FALLBACKS:
+            fallback_mcu = self.MCU_FALLBACKS[mcu]
+            fallback_dir = self.sdk_base_dir / fallback_mcu
+            if fallback_dir.exists():
+                if self.show_progress:
+                    print(f"      Note: Using {fallback_mcu} SDK for {mcu} (compatible)")
+                return fallback_mcu
+
+        # No fallback available, return original
+        return mcu
+
+    def get_sdk_includes(self, mcu: str) -> List[Path]:
+        """Get list of ESP-IDF include directories for a specific MCU.
+
+        This method reads the SDK's own includes file which lists the exact
+        include paths used by ESP-IDF, avoiding C++ stdlib conflicts that
+        occur when recursively discovering paths.
+
+        Args:
+            mcu: MCU type (e.g., "esp32c6", "esp32s3")
+
+        Returns:
+            List of include directory paths (305 paths for esp32c6)
+        """
+        # Resolve MCU with fallback if needed
+        resolved_mcu = self._resolve_mcu(mcu)
+
+        # Read the SDK's includes file
+        includes_file = self.get_sdk_flags_dir(resolved_mcu) / "includes"
+        if not includes_file.exists():
+            # Fallback to recursive discovery if includes file doesn't exist
+            return self._get_sdk_includes_recursive(resolved_mcu)
+
+        try:
+            # Read includes file (single line with space-separated entries)
+            includes_content = includes_file.read_text().strip()
+
+            # Parse the includes: "-iwithprefixbefore path1 -iwithprefixbefore path2 ..."
+            # The -iwithprefixbefore flag means to prepend the SDK include directory
+            sdk_include_base = self.sdk_base_dir / resolved_mcu / "include"
+
+            includes = []
+            parts = includes_content.split()
+            i = 0
+            while i < len(parts):
+                if parts[i] == "-iwithprefixbefore":
+                    # Next part is the relative path
+                    if i + 1 < len(parts):
+                        rel_path = parts[i + 1]
+                        abs_path = sdk_include_base / rel_path
+                        if abs_path.exists():
+                            includes.append(abs_path)
+                        i += 2
+                    else:
+                        i += 1
+                else:
+                    i += 1
+
+            return includes
+
+        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:
+            # Fallback to recursive discovery on error
+            if self.show_progress:
+                print(f"Warning: Failed to parse includes file: {e}")
+                print("Falling back to recursive include discovery")
+            return self._get_sdk_includes_recursive(mcu)
+
+    def _get_sdk_includes_recursive(self, mcu: str) -> List[Path]:
+        """Fallback method: recursively discover include directories.
+
+        This discovers 557 paths for esp32c6 but causes C++ stdlib conflicts.
+        Kept as a fallback when the includes file is not available.
+
+        Args:
+            mcu: MCU type (e.g., "esp32c6", "esp32s3")
+
+        Returns:
+            List of include directory paths
+        """
+        sdk_mcu_dir = self.sdk_base_dir / mcu / "include"
+        if not sdk_mcu_dir.exists():
+            return []
+
+        # Recursively find all subdirectories with header files
+        # ESP-IDF has a deep nested structure for includes
+        includes = []
+
+        def add_includes_recursive(directory: Path, max_depth: int = 6, current_depth: int = 0):
+            """Recursively add directories that contain header files."""
+            if current_depth > max_depth:
+                return
+
+            # Add this directory if it contains headers or is named 'include'
+            has_headers = any(directory.glob("*.h"))
+            if directory.name == "include" or has_headers:
+                includes.append(directory)
+
+            # Special handling for parent directories that have subdirs with headers
+            # but no headers themselves. Examples:
+            # - .../soc/esp32c6/register/ (has soc/ subdir with headers)
+            # - .../esp_rom/esp32c6/include/esp32c6/ (has rom/ subdir with headers)
+            # Only add if it matches specific patterns to avoid adding too many paths
+            is_parent_dir = False
+            if not has_headers:
+                # Check for specific directory names that are known parent directories
+                # Only add 'register' and MCU dirs that are under 'esp_rom' to be conservative
+                if directory.name == "register":
+                    is_parent_dir = True
+                elif directory.name.startswith("esp32"):
+                    # Only add MCU directories if they're under esp_rom component
+                    if "esp_rom" in str(directory):
+                        is_parent_dir = True
+
+                if is_parent_dir:
+                    try:
+                        # Check if it has immediate subdirs with headers
+                        for subdir in directory.iterdir():
+                            if subdir.is_dir() and any(subdir.glob("*.h")):
+                                includes.append(directory)
+                                break
+                    except (PermissionError, OSError):
+                        pass
+
+            # Recurse into subdirectories
+            try:
+                for subdir in directory.iterdir():
+                    if subdir.is_dir() and not subdir.name.startswith("."):
+                        add_includes_recursive(subdir, max_depth, current_depth + 1)
+            except (PermissionError, OSError):
+                pass
+
+        add_includes_recursive(sdk_mcu_dir)
+        return includes
+
+    def get_sdk_libs(self, mcu: str, flash_mode: str = "qio") -> List[Path]:
+        """Get list of ESP-IDF precompiled libraries for a specific MCU.
+
+        Args:
+            mcu: MCU type (e.g., "esp32c6", "esp32s3")
+            flash_mode: Flash mode (e.g., "qio", "dio") - determines flash library variant
+
+        Returns:
+            List of .a library file paths
+        """
+        # Resolve MCU with fallback if needed
+        resolved_mcu = self._resolve_mcu(mcu)
+
+        libs = []
+
+        # Get main SDK libraries
+        sdk_lib_dir = self.sdk_base_dir / resolved_mcu / "lib"
+        if sdk_lib_dir.exists():
+            libs.extend(sdk_lib_dir.glob("*.a"))
+
+        # Get flash mode-specific libraries (qio_qspi or dio_qspi)
+        # For ESP32-C6: Only libspi_flash.a
+        # For ESP32-S3: Multiple libraries including libfreertos.a, libesp_system.a, etc.
+        flash_lib_dir = self.sdk_base_dir / resolved_mcu / f"{flash_mode}_qspi"
+        if flash_lib_dir.exists():
+            # Collect ALL .a libraries from flash mode directory
+            # ESP32-S3 has: libfreertos.a, libspi_flash.a, libesp_system.a,
+            #               libesp_hw_support.a, libesp_psram.a, libbootloader_support.a
+            flash_libs = list(flash_lib_dir.glob("*.a"))
+            libs.extend(flash_libs)
+
+        return libs
+
+    def get_sdk_flags_dir(self, mcu: str) -> Path:
+        """Get path to SDK flags directory for a specific MCU.
+
+        Args:
+            mcu: MCU type (e.g., "esp32c6", "esp32s3")
+
+        Returns:
+            Path to flags directory
+        """
+        # Resolve MCU with fallback if needed
+        resolved_mcu = self._resolve_mcu(mcu)
+        return self.sdk_base_dir / resolved_mcu / "flags"