fbuild 1.1.0__py3-none-any.whl

fbuild/packages/arduino_core.py

@@ -0,0 +1,412 @@
+"""Arduino core platform management.
+
+This module handles downloading and managing Arduino core platforms
+(e.g., ArduinoCore-avr) required for building Arduino sketches.
+"""
+
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from .cache import Cache
+from .downloader import PackageDownloader
+from .package import IFramework, PackageError
+
+
+class ArduinoCoreError(PackageError):
+    """Raised when Arduino core operations fail."""
+
+    pass
+
+
+class ArduinoCore(IFramework):
+    """Manages Arduino core platform packages."""
+
+    # Arduino AVR core version
+    AVR_VERSION = "1.8.6"
+
+    # Package URL and checksum
+    # The Arduino AVR core is hosted on GitHub
+    AVR_URL = f"https://github.com/arduino/ArduinoCore-avr/archive/refs/tags/{AVR_VERSION}.tar.gz"
+    AVR_CHECKSUM = "49241fd5e504482b94954b5843c7d69ce38ebc1ab47ad3b677e8bb77e0cb8fe6"
+
+    def __init__(self, cache: Cache):
+        """Initialize Arduino core manager.
+
+        Args:
+            cache: Cache instance for storing cores
+        """
+        self.cache = cache
+        self.downloader = PackageDownloader()
+        self._core_path: Optional[Path] = None
+
+    def ensure_package(self) -> Path:
+        """Ensure Arduino AVR core is available.
+
+        Returns:
+            Path to Arduino AVR core directory
+
+        Raises:
+            ArduinoCoreError: If core cannot be obtained
+        """
+        return self.ensure_avr_core()
+
+    def ensure_avr_core(self, force_download: bool = False) -> Path:
+        """Ensure Arduino AVR core is available.
+
+        Args:
+            force_download: Force re-download even if cached
+
+        Returns:
+            Path to Arduino AVR core directory
+
+        Raises:
+            ArduinoCoreError: If core cannot be obtained
+        """
+        # Check if already loaded
+        if self._core_path and not force_download:
+            return self._core_path
+
+        # Use URL-based caching
+        core_path = self.cache.get_platform_path(self.AVR_URL, self.AVR_VERSION)
+        package_name = f"avr-{self.AVR_VERSION}.tar.gz"
+        package_path = self.cache.get_package_path(self.AVR_URL, self.AVR_VERSION, package_name)
+
+        # Check if already extracted and valid
+        if not force_download and self.cache.is_platform_cached(self.AVR_URL, self.AVR_VERSION):
+            if self._verify_core(core_path):
+                self._core_path = core_path
+                return core_path
+            else:
+                print("Cached Arduino core failed validation, re-downloading...")
+
+        # Need to download and extract
+        self.cache.ensure_directories()
+
+        print(f"Downloading Arduino AVR core ({self.AVR_VERSION})...")
+
+        try:
+            # Ensure package directory exists
+            package_path.parent.mkdir(parents=True, exist_ok=True)
+
+            # Download if not cached
+            if force_download or not package_path.exists():
+                self.downloader.download(self.AVR_URL, package_path, self.AVR_CHECKSUM)
+            else:
+                print(f"Using cached {package_name}")
+
+            # Extract
+            print("Extracting Arduino core...")
+            core_path.parent.mkdir(parents=True, exist_ok=True)
+
+            # Extract to temporary location first
+            import shutil
+            import tempfile
+
+            with tempfile.TemporaryDirectory() as temp_dir:
+                temp_path = Path(temp_dir)
+                self.downloader.extract_archive(package_path, temp_path, show_progress=False)
+
+                # The archive extracts to avr/ subdirectory
+                extracted_dir = temp_path / "avr"
+                if not extracted_dir.exists():
+                    # If not in avr/ subdirectory, use first directory found
+                    extracted_dirs = [d for d in temp_path.iterdir() if d.is_dir()]
+                    if extracted_dirs:
+                        extracted_dir = extracted_dirs[0]
+                    else:
+                        raise ArduinoCoreError("No directory found in extracted archive")
+
+                # Move to final location
+                if core_path.exists():
+                    shutil.rmtree(core_path)
+                shutil.move(str(extracted_dir), str(core_path))
+
+            # Verify installation
+            if not self._verify_core(core_path):
+                raise ArduinoCoreError("Core verification failed after extraction")
+
+            self._core_path = core_path
+            print(f"Arduino core ready at {core_path}")
+            return core_path
+
+        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 ArduinoCoreError(f"Failed to setup Arduino core: {e}")
+
+    def is_installed(self) -> bool:
+        """Check if Arduino core is already installed.
+
+        Returns:
+            True if core is installed and valid
+        """
+        if not self._core_path:
+            # Check cache
+            core_path = self.cache.get_platform_path(self.AVR_URL, self.AVR_VERSION)
+            if core_path.exists():
+                return self._verify_core(core_path)
+            return False
+        return self._verify_core(self._core_path)
+
+    def get_package_info(self) -> Dict[str, Any]:
+        """Get information about the installed core.
+
+        Returns:
+            Dictionary with core information
+        """
+        info = {
+            "version": self.AVR_VERSION,
+            "url": self.AVR_URL,
+            "installed": self.is_installed(),
+        }
+
+        if self._core_path:
+            info["path"] = str(self._core_path)
+            info["cores_dir"] = str(self.get_cores_dir())
+            info["variants_dir"] = str(self.get_variants_dir())
+
+        return info
+
+    def _verify_core(self, core_path: Path) -> bool:
+        """Comprehensively verify Arduino core is complete.
+
+        Checks for:
+        - Required directories (cores/arduino, variants)
+        - Configuration files (boards.txt, platform.txt)
+        - Key core source files
+        - Key header files
+
+        Args:
+            core_path: Path to core directory
+
+        Returns:
+            True if core appears valid
+        """
+        # Check for essential directories
+        required_dirs = [
+            "cores/arduino",
+            "variants",
+            "variants/standard",  # Uno variant
+        ]
+
+        for dir_path in required_dirs:
+            if not (core_path / dir_path).exists():
+                print(f"Missing directory: {dir_path}")
+                return False
+
+        # Check for essential configuration files
+        required_files = [
+            "boards.txt",
+            "platform.txt",
+        ]
+
+        for file_path in required_files:
+            if not (core_path / file_path).exists():
+                print(f"Missing file: {file_path}")
+                return False
+
+        # Check for key core header files
+        required_headers = [
+            "cores/arduino/Arduino.h",
+            "cores/arduino/HardwareSerial.h",
+            "variants/standard/pins_arduino.h",
+        ]
+
+        for header in required_headers:
+            if not (core_path / header).exists():
+                print(f"Missing header: {header}")
+                return False
+
+        # Check for key core source files
+        required_sources = [
+            "cores/arduino/main.cpp",
+            "cores/arduino/wiring.c",
+            "cores/arduino/wiring_digital.c",
+        ]
+
+        for source in required_sources:
+            if not (core_path / source).exists():
+                print(f"Missing source: {source}")
+                return False
+
+        # Verify boards.txt contains uno configuration
+        boards_txt = core_path / "boards.txt"
+        try:
+            content = boards_txt.read_text(encoding="utf-8", errors="ignore")
+            if "uno.name" not in content:
+                print("boards.txt missing uno configuration")
+                return False
+        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:
+            print(f"Failed to read boards.txt: {e}")
+            return False
+
+        return True
+
+    def get_boards_txt(self) -> Path:
+        """Get path to boards.txt file.
+
+        Returns:
+            Path to boards.txt
+
+        Raises:
+            ArduinoCoreError: If core not initialized
+        """
+        if not self._core_path:
+            raise ArduinoCoreError("Core not initialized. Call ensure_avr_core() first.")
+
+        boards_txt = self._core_path / "boards.txt"
+        if not boards_txt.exists():
+            raise ArduinoCoreError("boards.txt not found in core")
+
+        return boards_txt
+
+    def get_platform_txt(self) -> Path:
+        """Get path to platform.txt file.
+
+        Returns:
+            Path to platform.txt
+
+        Raises:
+            ArduinoCoreError: If core not initialized
+        """
+        if not self._core_path:
+            raise ArduinoCoreError("Core not initialized. Call ensure_avr_core() first.")
+
+        platform_txt = self._core_path / "platform.txt"
+        if not platform_txt.exists():
+            raise ArduinoCoreError("platform.txt not found in core")
+
+        return platform_txt
+
+    def get_cores_dir(self) -> Path:
+        """Get path to cores directory.
+
+        Returns:
+            Path to cores directory
+
+        Raises:
+            ArduinoCoreError: If core not initialized
+        """
+        if not self._core_path:
+            raise ArduinoCoreError("Core not initialized. Call ensure_avr_core() first.")
+
+        cores_dir = self._core_path / "cores"
+        if not cores_dir.exists():
+            raise ArduinoCoreError("cores directory not found")
+
+        return cores_dir
+
+    def get_variants_dir(self) -> Path:
+        """Get path to variants directory.
+
+        Returns:
+            Path to variants directory
+
+        Raises:
+            ArduinoCoreError: If core not initialized
+        """
+        if not self._core_path:
+            raise ArduinoCoreError("Core not initialized. Call ensure_avr_core() first.")
+
+        variants_dir = self._core_path / "variants"
+        if not variants_dir.exists():
+            raise ArduinoCoreError("variants directory not found")
+
+        return variants_dir
+
+    def get_libraries_dir(self) -> Path:
+        """Get path to built-in libraries directory.
+
+        Returns:
+            Path to libraries directory
+
+        Raises:
+            ArduinoCoreError: If core not initialized
+        """
+        if not self._core_path:
+            raise ArduinoCoreError("Core not initialized. Call ensure_avr_core() first.")
+
+        # Arduino AVR core doesn't have a libraries directory, return a non-existent path
+        libraries_dir = self._core_path / "libraries"
+        return libraries_dir
+
+    def get_core_dir(self) -> Path:
+        """Get path to cores/arduino directory.
+
+        Returns:
+            Path to core library sources
+
+        Raises:
+            ArduinoCoreError: If core not initialized
+        """
+        if not self._core_path:
+            raise ArduinoCoreError("Core not initialized. Call ensure_avr_core() first.")
+
+        core_dir = self._core_path / "cores" / "arduino"
+        if not core_dir.exists():
+            raise ArduinoCoreError("cores/arduino directory not found")
+
+        return core_dir
+
+    def get_variant_dir(self, variant_name: str = "standard") -> Path:
+        """Get path to a board variant directory.
+
+        Args:
+            variant_name: Name of the variant (e.g., 'standard' for Uno)
+
+        Returns:
+            Path to variant directory
+
+        Raises:
+            ArduinoCoreError: If core not initialized or variant not found
+        """
+        if not self._core_path:
+            raise ArduinoCoreError("Core not initialized. Call ensure_avr_core() first.")
+
+        variant_dir = self._core_path / "variants" / variant_name
+        if not variant_dir.exists():
+            raise ArduinoCoreError(f"Variant '{variant_name}' not found")
+
+        return variant_dir
+
+    def get_core_sources(self) -> list[Path]:
+        """Get list of all core source files (.c and .cpp).
+
+        Returns:
+            List of paths to core source files
+
+        Raises:
+            ArduinoCoreError: If core not initialized
+        """
+        core_dir = self.get_core_dir()
+
+        sources: list[Path] = []
+        for pattern in ("*.c", "*.cpp"):
+            sources.extend(core_dir.glob(pattern))
+
+        return sorted(sources)
+
+    def get_variant_sources(self, variant_name: str = "standard") -> list[Path]:
+        """Get list of variant source files.
+
+        Args:
+            variant_name: Name of the variant
+
+        Returns:
+            List of paths to variant source files
+        """
+        variant_dir = self.get_variant_dir(variant_name)
+
+        sources: list[Path] = []
+        for pattern in ("*.c", "*.cpp"):
+            sources.extend(variant_dir.glob(pattern))
+
+        return sorted(sources)

fbuild/packages/cache.py

@@ -0,0 +1,249 @@
+"""Cache management for fbuild packages.
+
+This module provides a unified cache structure for storing downloaded
+packages, toolchains, platforms, and build artifacts.
+
+Cache Structure:
+    .fbuild/
+    ├── cache/
+    │   ├── packages/
+    │   │   └── {url_hash}/         # SHA256 hash of base URL
+    │   │       └── {version}/      # Version string
+    │   │           └── archive     # Downloaded archive
+    │   ├── toolchains/
+    │   │   └── {url_hash}/         # SHA256 hash of base URL
+    │   │       └── {version}/      # Version string
+    │   │           └── bin/        # Extracted toolchain binaries
+    │   ├── platforms/
+    │   │   └── {url_hash}/         # SHA256 hash of base URL
+    │   │       └── {version}/      # Version string
+    │   │           ├── cores/
+    │   │           ├── variants/
+    │   │           ├── boards.txt
+    │   │           └── platform.txt
+    │   └── libraries/
+    │       └── {url_hash}/         # SHA256 hash of base URL
+    │           └── {version}/      # Version string
+    └── build/
+        └── {env_name}/             # Build output per environment
+            ├── core/               # Compiled core objects
+            ├── src/                # Compiled sketch objects
+            └── firmware.*          # Final firmware files
+
+This structure ensures that different versions from the same URL don't
+stomp on each other, and allows multiple sources to coexist.
+"""
+
+import hashlib
+import os
+from pathlib import Path
+from typing import Optional
+
+
+class Cache:
+    """Manages the fbuild cache directory structure.
+
+    The cache can be located in the project directory (.fbuild/) or in a
+    global location specified by the FBUILD_CACHE_DIR environment variable.
+
+    Uses URL hashing to organize cached items, preventing version conflicts.
+    """
+
+    def __init__(self, project_dir: Optional[Path] = None):
+        """Initialize cache manager.
+
+        Args:
+            project_dir: Project directory. If None, uses current directory.
+        """
+        if project_dir is None:
+            project_dir = Path.cwd()
+
+        self.project_dir = Path(project_dir).resolve()
+
+        # Check for environment variable override
+        cache_env = os.environ.get("FBUILD_CACHE_DIR")
+        if cache_env:
+            self.cache_root = Path(cache_env).resolve()
+        else:
+            self.cache_root = self.project_dir / ".fbuild" / "cache"
+
+        self.build_root = self.project_dir / ".fbuild" / "build"
+
+    @staticmethod
+    def hash_url(url: str) -> str:
+        """Generate a SHA256 hash of a URL for cache directory naming.
+
+        Args:
+            url: The base URL to hash
+
+        Returns:
+            First 16 characters of SHA256 hash (sufficient for uniqueness)
+        """
+        return hashlib.sha256(url.encode("utf-8")).hexdigest()[:16]
+
+    @property
+    def packages_dir(self) -> Path:
+        """Directory for downloaded package archives."""
+        return self.cache_root / "packages"
+
+    @property
+    def toolchains_dir(self) -> Path:
+        """Directory for extracted toolchain binaries."""
+        return self.cache_root / "toolchains"
+
+    @property
+    def platforms_dir(self) -> Path:
+        """Directory for extracted platform cores."""
+        return self.cache_root / "platforms"
+
+    @property
+    def libraries_dir(self) -> Path:
+        """Directory for downloaded libraries."""
+        return self.cache_root / "libraries"
+
+    def get_build_dir(self, env_name: str) -> Path:
+        """Get build directory for a specific environment.
+
+        Args:
+            env_name: Environment name (e.g., 'uno', 'mega')
+
+        Returns:
+            Path to the environment's build directory
+        """
+        return self.build_root / env_name
+
+    def get_core_build_dir(self, env_name: str) -> Path:
+        """Get directory for compiled core objects.
+
+        Args:
+            env_name: Environment name
+
+        Returns:
+            Path to core build directory
+        """
+        return self.get_build_dir(env_name) / "core"
+
+    def get_src_build_dir(self, env_name: str) -> Path:
+        """Get directory for compiled sketch objects.
+
+        Args:
+            env_name: Environment name
+
+        Returns:
+            Path to sketch build directory
+        """
+        return self.get_build_dir(env_name) / "src"
+
+    def ensure_directories(self) -> None:
+        """Create all cache directories if they don't exist."""
+        for directory in [
+            self.packages_dir,
+            self.toolchains_dir,
+            self.platforms_dir,
+            self.libraries_dir,
+        ]:
+            directory.mkdir(parents=True, exist_ok=True)
+
+    def ensure_build_directories(self, env_name: str) -> None:
+        """Create build directories for a specific environment.
+
+        Args:
+            env_name: Environment name
+        """
+        for directory in [
+            self.get_build_dir(env_name),
+            self.get_core_build_dir(env_name),
+            self.get_src_build_dir(env_name),
+        ]:
+            directory.mkdir(parents=True, exist_ok=True)
+
+    def clean_build(self, env_name: str) -> None:
+        """Remove all build artifacts for an environment.
+
+        Args:
+            env_name: Environment name
+        """
+        import shutil
+
+        build_dir = self.get_build_dir(env_name)
+        if build_dir.exists():
+            shutil.rmtree(build_dir)
+
+    def get_package_path(self, url: str, version: str, filename: str) -> Path:
+        """Get path where a package archive would be stored.
+
+        Args:
+            url: Base URL for the package source
+            version: Version string (e.g., '7.3.0-atmel3.6.1-arduino7')
+            filename: Archive filename (e.g., 'avr-gcc-7.3.0.tar.bz2')
+
+        Returns:
+            Path to the package archive
+        """
+        url_hash = self.hash_url(url)
+        return self.packages_dir / url_hash / version / filename
+
+    def get_toolchain_path(self, url: str, version: str) -> Path:
+        """Get path where a toolchain would be extracted.
+
+        Args:
+            url: Base URL for the toolchain source
+            version: Version string (e.g., '7.3.0-atmel3.6.1-arduino7')
+
+        Returns:
+            Path to the extracted toolchain directory
+        """
+        url_hash = self.hash_url(url)
+        return self.toolchains_dir / url_hash / version
+
+    def get_platform_path(self, url: str, version: str) -> Path:
+        """Get path where a platform would be extracted.
+
+        Args:
+            url: Base URL for the platform source
+            version: Version string (e.g., '1.8.6')
+
+        Returns:
+            Path to the extracted platform directory
+        """
+        url_hash = self.hash_url(url)
+        return self.platforms_dir / url_hash / version
+
+    def is_package_cached(self, url: str, version: str, filename: str) -> bool:
+        """Check if a package is already downloaded.
+
+        Args:
+            url: Base URL for the package source
+            version: Version string
+            filename: Archive filename
+
+        Returns:
+            True if package exists in cache
+        """
+        return self.get_package_path(url, version, filename).exists()
+
+    def is_toolchain_cached(self, url: str, version: str) -> bool:
+        """Check if a toolchain is already extracted.
+
+        Args:
+            url: Base URL for the toolchain source
+            version: Version string
+
+        Returns:
+            True if toolchain exists in cache
+        """
+        toolchain_path = self.get_toolchain_path(url, version)
+        return toolchain_path.exists() and toolchain_path.is_dir()
+
+    def is_platform_cached(self, url: str, version: str) -> bool:
+        """Check if a platform is already extracted.
+
+        Args:
+            url: Base URL for the platform source
+            version: Version string
+
+        Returns:
+            True if platform exists in cache
+        """
+        platform_path = self.get_platform_path(url, version)
+        return platform_path.exists() and platform_path.is_dir()