fbuild 1.2.8__py3-none-any.whl

fbuild/__init__.py

@@ -0,0 +1,390 @@
+"""fbuild - Modern embedded development tool."""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+__version__ = "1.2.8"
+
+
+def is_available() -> bool:
+    """Check if fbuild is properly installed and functional.
+
+    Returns:
+        True if fbuild daemon client is available, False otherwise.
+    """
+    try:
+        __import__("fbuild.daemon.client")
+        return True
+    except ImportError:
+        return False
+
+
+@dataclass
+class BuildContext:
+    """Configuration context for fbuild operations.
+
+    Groups common parameters used across build, deploy, and install operations.
+    Can be passed to Daemon methods instead of individual parameters.
+
+    Example usage:
+        import fbuild
+
+        # Create a context for repeated operations
+        ctx = fbuild.BuildContext(
+            project_dir=Path("my_project"),
+            environment="esp32dev",
+            port="COM3",
+            verbose=True
+        )
+
+        # Pre-install dependencies (toolchain, framework, libraries)
+        fbuild.Daemon.install_dependencies(ctx)
+
+        # Build using the context
+        fbuild.Daemon.build(ctx)
+
+        # Deploy using the context
+        fbuild.Daemon.deploy(ctx)
+
+    Attributes:
+        project_dir: Path to project directory containing platformio.ini
+        environment: Build environment name (e.g., 'esp32dev', 'esp32c6')
+        port: Serial port for upload/monitor (auto-detect if None)
+        clean_build: Whether to perform a clean build
+        verbose: Enable verbose output
+        timeout: Maximum wait time in seconds (default: 30 minutes)
+    """
+
+    project_dir: Path
+    environment: str
+    port: str | None = None
+    clean_build: bool = False
+    verbose: bool = False
+    timeout: float = 1800
+
+
+class Daemon:
+    """Daemon management API for fbuild.
+
+    Provides static methods to control the fbuild daemon which handles
+    build, deploy, and monitor operations.
+
+    Example usage:
+        import fbuild
+
+        # Option 1: Use BuildContext (recommended for repeated operations)
+        ctx = fbuild.BuildContext(
+            project_dir=Path("my_project"),
+            environment="esp32dev"
+        )
+        fbuild.Daemon.install_dependencies(ctx)
+        fbuild.Daemon.build(ctx)
+        fbuild.Daemon.deploy(ctx)
+
+        # Option 2: Use individual parameters
+        fbuild.Daemon.build(
+            project_dir=Path("my_project"),
+            environment="esp32dev"
+        )
+
+        # Daemon lifecycle
+        fbuild.Daemon.ensure_running()
+        fbuild.Daemon.status()
+        fbuild.Daemon.stop()
+    """
+
+    @staticmethod
+    def ensure_running() -> bool:
+        """Ensure the fbuild daemon is running.
+
+        Starts the daemon if not already running.
+
+        Returns:
+            True if daemon is running or was started successfully, False otherwise.
+        """
+        from fbuild.daemon import ensure_daemon_running
+
+        return ensure_daemon_running()
+
+    @staticmethod
+    def stop() -> bool:
+        """Stop the fbuild daemon.
+
+        Returns:
+            True if daemon was stopped, False otherwise.
+        """
+        from fbuild.daemon import stop_daemon
+
+        return stop_daemon()
+
+    @staticmethod
+    def status() -> dict[str, Any]:
+        """Get current fbuild daemon status.
+
+        Returns:
+            Dictionary with daemon status information including:
+            - state: Current daemon state
+            - message: Status message
+            - running: Whether daemon is running
+        """
+        from fbuild.daemon import get_daemon_status
+
+        return get_daemon_status()
+
+    @staticmethod
+    def install_dependencies(
+        ctx_or_project_dir: BuildContext | Path,
+        environment: str | None = None,
+        verbose: bool = False,
+        timeout: float = 1800,
+    ) -> bool:
+        """Pre-install toolchain, platform, framework, and libraries.
+
+        This downloads and caches all dependencies required for a build
+        without actually compiling. Useful for:
+        - Pre-warming the cache before builds
+        - Ensuring dependencies are available offline
+        - Separating dependency installation from compilation
+
+        Can be called with a BuildContext or individual parameters:
+
+            # Using BuildContext
+            ctx = fbuild.BuildContext(project_dir=Path("."), environment="esp32dev")
+            fbuild.Daemon.install_dependencies(ctx)
+
+            # Using individual parameters
+            fbuild.Daemon.install_dependencies(
+                project_dir=Path("."),
+                environment="esp32dev"
+            )
+
+        Args:
+            ctx_or_project_dir: BuildContext or Path to project directory
+            environment: Build environment name (ignored if BuildContext passed)
+            verbose: Enable verbose output (ignored if BuildContext passed)
+            timeout: Maximum wait time in seconds (ignored if BuildContext passed)
+
+        Returns:
+            True if dependencies installed successfully, False otherwise.
+        """
+        from fbuild.daemon import request_install_dependencies
+
+        # Handle BuildContext or individual parameters
+        if isinstance(ctx_or_project_dir, BuildContext):
+            ctx = ctx_or_project_dir
+            return request_install_dependencies(
+                project_dir=ctx.project_dir,
+                environment=ctx.environment,
+                verbose=ctx.verbose,
+                timeout=ctx.timeout,
+            )
+        else:
+            if environment is None:
+                raise ValueError("environment is required when not using BuildContext")
+            return request_install_dependencies(
+                project_dir=ctx_or_project_dir,
+                environment=environment,
+                verbose=verbose,
+                timeout=timeout,
+            )
+
+    @staticmethod
+    def build(
+        ctx_or_project_dir: BuildContext | Path,
+        environment: str | None = None,
+        clean_build: bool = False,
+        verbose: bool = False,
+        timeout: float = 1800,
+    ) -> bool:
+        """Request a build operation from the daemon.
+
+        Can be called with a BuildContext or individual parameters:
+
+            # Using BuildContext
+            ctx = fbuild.BuildContext(project_dir=Path("."), environment="esp32dev")
+            fbuild.Daemon.build(ctx)
+
+            # Using individual parameters
+            fbuild.Daemon.build(
+                project_dir=Path("."),
+                environment="esp32dev"
+            )
+
+        Args:
+            ctx_or_project_dir: BuildContext or Path to project directory
+            environment: Build environment name (ignored if BuildContext passed)
+            clean_build: Whether to perform a clean build (ignored if BuildContext passed)
+            verbose: Enable verbose build output (ignored if BuildContext passed)
+            timeout: Maximum wait time in seconds (ignored if BuildContext passed)
+
+        Returns:
+            True if build successful, False otherwise.
+        """
+        from fbuild.daemon import request_build
+
+        # Handle BuildContext or individual parameters
+        if isinstance(ctx_or_project_dir, BuildContext):
+            ctx = ctx_or_project_dir
+            return request_build(
+                project_dir=ctx.project_dir,
+                environment=ctx.environment,
+                clean_build=ctx.clean_build,
+                verbose=ctx.verbose,
+                timeout=ctx.timeout,
+            )
+        else:
+            if environment is None:
+                raise ValueError("environment is required when not using BuildContext")
+            return request_build(
+                project_dir=ctx_or_project_dir,
+                environment=environment,
+                clean_build=clean_build,
+                verbose=verbose,
+                timeout=timeout,
+            )
+
+    @staticmethod
+    def deploy(
+        ctx_or_project_dir: BuildContext | Path,
+        environment: str | None = None,
+        port: str | None = None,
+        clean_build: bool = False,
+        monitor_after: bool = False,
+        monitor_timeout: float | None = None,
+        monitor_halt_on_error: str | None = None,
+        monitor_halt_on_success: str | None = None,
+        monitor_expect: str | None = None,
+        timeout: float = 1800,
+    ) -> bool:
+        """Request a deploy (build + upload) operation from the daemon.
+
+        Can be called with a BuildContext or individual parameters:
+
+            # Using BuildContext
+            ctx = fbuild.BuildContext(
+                project_dir=Path("."),
+                environment="esp32dev",
+                port="COM3"
+            )
+            fbuild.Daemon.deploy(ctx)
+
+            # Using individual parameters
+            fbuild.Daemon.deploy(
+                project_dir=Path("."),
+                environment="esp32dev",
+                port="COM3"
+            )
+
+        Args:
+            ctx_or_project_dir: BuildContext or Path to project directory
+            environment: Build environment name (ignored if BuildContext passed)
+            port: Serial port for upload (ignored if BuildContext passed)
+            clean_build: Whether to perform a clean build (ignored if BuildContext passed)
+            monitor_after: Whether to start monitor after deploy
+            monitor_timeout: Timeout for monitor (if monitor_after=True)
+            monitor_halt_on_error: Pattern to halt on error (if monitor_after=True)
+            monitor_halt_on_success: Pattern to halt on success (if monitor_after=True)
+            monitor_expect: Expected pattern to check (if monitor_after=True)
+            timeout: Maximum wait time in seconds (ignored if BuildContext passed)
+
+        Returns:
+            True if deploy successful, False otherwise.
+        """
+        from fbuild.daemon import request_deploy
+
+        # Handle BuildContext or individual parameters
+        if isinstance(ctx_or_project_dir, BuildContext):
+            ctx = ctx_or_project_dir
+            return request_deploy(
+                project_dir=ctx.project_dir,
+                environment=ctx.environment,
+                port=ctx.port,
+                clean_build=ctx.clean_build,
+                monitor_after=monitor_after,
+                monitor_timeout=monitor_timeout,
+                monitor_halt_on_error=monitor_halt_on_error,
+                monitor_halt_on_success=monitor_halt_on_success,
+                monitor_expect=monitor_expect,
+                timeout=ctx.timeout,
+            )
+        else:
+            if environment is None:
+                raise ValueError("environment is required when not using BuildContext")
+            return request_deploy(
+                project_dir=ctx_or_project_dir,
+                environment=environment,
+                port=port,
+                clean_build=clean_build,
+                monitor_after=monitor_after,
+                monitor_timeout=monitor_timeout,
+                monitor_halt_on_error=monitor_halt_on_error,
+                monitor_halt_on_success=monitor_halt_on_success,
+                monitor_expect=monitor_expect,
+                timeout=timeout,
+            )
+
+    @staticmethod
+    def monitor(
+        ctx_or_project_dir: BuildContext | Path,
+        environment: str | None = None,
+        port: str | None = None,
+        baud_rate: int | None = None,
+        halt_on_error: str | None = None,
+        halt_on_success: str | None = None,
+        expect: str | None = None,
+        timeout: float | None = None,
+    ) -> bool:
+        """Request a monitor operation from the daemon.
+
+        Can be called with a BuildContext or individual parameters.
+
+        Args:
+            ctx_or_project_dir: BuildContext or Path to project directory
+            environment: Build environment name (ignored if BuildContext passed)
+            port: Serial port (ignored if BuildContext passed)
+            baud_rate: Serial baud rate (optional)
+            halt_on_error: Pattern to halt on (error detection)
+            halt_on_success: Pattern to halt on (success detection)
+            expect: Expected pattern to check at timeout/success
+            timeout: Maximum monitoring time in seconds
+
+        Returns:
+            True if monitoring successful, False otherwise.
+        """
+        from fbuild.daemon import request_monitor
+
+        # Handle BuildContext or individual parameters
+        if isinstance(ctx_or_project_dir, BuildContext):
+            ctx = ctx_or_project_dir
+            return request_monitor(
+                project_dir=ctx.project_dir,
+                environment=ctx.environment,
+                port=ctx.port,
+                baud_rate=baud_rate,
+                halt_on_error=halt_on_error,
+                halt_on_success=halt_on_success,
+                expect=expect,
+                timeout=timeout if timeout is not None else ctx.timeout,
+            )
+        else:
+            if environment is None:
+                raise ValueError("environment is required when not using BuildContext")
+            return request_monitor(
+                project_dir=ctx_or_project_dir,
+                environment=environment,
+                port=port,
+                baud_rate=baud_rate,
+                halt_on_error=halt_on_error,
+                halt_on_success=halt_on_success,
+                expect=expect,
+                timeout=timeout,
+            )
+
+
+__all__ = [
+    "__version__",
+    "is_available",
+    "BuildContext",
+    "Daemon",
+]

fbuild/assets/example.txt

@@ -0,0 +1 @@
+Example assets that will be deployed with python code.

fbuild/build/__init__.py

@@ -0,0 +1,117 @@
+"""
+Build system components for Fbuild.
+
+This module provides the build system implementation including:
+- Source file discovery and preprocessing
+- Compilation (avr-gcc/avr-g++)
+- Linking (avr-gcc linker, avr-objcopy)
+- Build orchestration
+"""
+
+from .source_scanner import SourceScanner, SourceCollection
+
+__all__ = [
+    'SourceScanner',
+    'SourceCollection',
+]
+
+# Import base classes
+try:
+    from .orchestrator import (  # noqa: F401
+        IBuildOrchestrator,
+        BuildResult,
+        BuildOrchestratorError
+    )
+    __all__.extend(['IBuildOrchestrator', 'BuildResult', 'BuildOrchestratorError'])
+except ImportError:
+    pass
+
+try:
+    from .compiler import ICompiler, CompilerError, ILinker, LinkerError  # noqa: F401
+    __all__.extend(['ICompiler', 'CompilerError', 'ILinker', 'LinkerError'])
+except ImportError:
+    pass
+
+# Import platform-specific implementations
+try:
+    from .compiler_avr import CompilerAVR  # noqa: F401
+    __all__.append('CompilerAVR')
+except ImportError:
+    pass
+
+try:
+    from .linker import LinkerAVR  # noqa: F401
+    __all__.append('LinkerAVR')
+except ImportError:
+    pass
+
+try:
+    from .orchestrator_avr import BuildOrchestratorAVR  # noqa: F401
+    __all__.append('BuildOrchestratorAVR')
+except ImportError:
+    pass
+
+try:
+    from .orchestrator_esp32 import OrchestratorESP32  # noqa: F401
+    __all__.append('OrchestratorESP32')
+except ImportError:
+    pass
+
+try:
+    from .binary_generator import BinaryGenerator  # noqa: F401
+    __all__.append('BinaryGenerator')
+except ImportError:
+    pass
+
+try:
+    from .build_utils import SizeInfoPrinter  # noqa: F401
+    __all__.append('SizeInfoPrinter')
+except ImportError:
+    pass
+
+try:
+    from .flag_builder import FlagBuilder  # noqa: F401
+    __all__.append('FlagBuilder')
+except ImportError:
+    pass
+
+try:
+    from .compilation_executor import CompilationExecutor  # noqa: F401
+    __all__.append('CompilationExecutor')
+except ImportError:
+    pass
+
+try:
+    from .archive_creator import ArchiveCreator  # noqa: F401
+    __all__.append('ArchiveCreator')
+except ImportError:
+    pass
+
+try:
+    from .library_dependency_processor import (  # noqa: F401
+        LibraryDependencyProcessor,
+        LibraryProcessingResult
+    )
+    __all__.extend(['LibraryDependencyProcessor', 'LibraryProcessingResult'])
+except ImportError:
+    pass
+
+try:
+    from .source_compilation_orchestrator import (  # noqa: F401
+        SourceCompilationOrchestrator,
+        SourceCompilationOrchestratorError,
+        MultiGroupCompilationResult
+    )
+    __all__.extend([
+        'SourceCompilationOrchestrator',
+        'SourceCompilationOrchestratorError',
+        'MultiGroupCompilationResult'
+    ])
+except ImportError:
+    pass
+
+try:
+    from .build_component_factory import BuildComponentFactory  # noqa: F401
+    __all__.append('BuildComponentFactory')
+except ImportError:
+    pass

fbuild/build/archive_creator.py

@@ -0,0 +1,186 @@
+"""Archive Creator.
+
+This module handles creating static library archives (.a files) from compiled
+object files using the archiver tool (ar).
+
+Design:
+    - Wraps ar command execution
+    - Creates .a archives from object files
+    - Provides clear error messages
+    - Shows archive size information
+"""
+
+import gc
+import platform
+import subprocess
+import time
+from pathlib import Path
+from typing import List
+
+
+class ArchiveError(Exception):
+    """Raised when archive creation operations fail."""
+    pass
+
+
+class ArchiveCreator:
+    """Creates static library archives from object files.
+
+    This class handles:
+    - Running archiver (ar) commands
+    - Creating .a archives from object files
+    - Validating archive creation
+    - Showing size information
+    """
+
+    def __init__(self, show_progress: bool = True):
+        """Initialize archive creator.
+
+        Args:
+            show_progress: Whether to show archive creation progress
+        """
+        self.show_progress = show_progress
+
+    def create_archive(
+        self,
+        ar_path: Path,
+        archive_path: Path,
+        object_files: List[Path]
+    ) -> Path:
+        """Create static library archive from object files.
+
+        Args:
+            ar_path: Path to archiver tool (ar)
+            archive_path: Path for output .a file
+            object_files: List of object file paths to archive
+
+        Returns:
+            Path to generated archive file
+
+        Raises:
+            ArchiveError: If archive creation fails
+        """
+        if not object_files:
+            raise ArchiveError("No object files provided for archive")
+
+        if not ar_path.exists():
+            raise ArchiveError(
+                f"Archiver not found: {ar_path}. Ensure toolchain is installed."
+            )
+
+        # Ensure archive directory exists
+        archive_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Build archiver command
+        # 'rcs' flags: r=insert/replace, c=create, s=index (ranlib)
+        cmd = [str(ar_path), "rcs", str(archive_path)]
+        cmd.extend([str(obj) for obj in object_files])
+
+        # Execute archiver
+        if self.show_progress:
+            print(f"Creating {archive_path.name} archive from {len(object_files)} object files...")
+
+        # On Windows, add retry logic to handle file locking issues
+        # Object files may still have open handles from compiler/antivirus
+        is_windows = platform.system() == "Windows"
+        max_retries = 5 if is_windows else 1
+        delay = 0.1
+        last_error = None
+
+        for attempt in range(max_retries):
+            try:
+                # On Windows, force garbage collection and add delay before retry
+                if is_windows and attempt > 0:
+                    gc.collect()
+                    time.sleep(delay)
+                    if self.show_progress:
+                        print(f"  Retrying archive creation (attempt {attempt + 1}/{max_retries})...")
+
+                result = subprocess.run(
+                    cmd,
+                    capture_output=True,
+                    text=True,
+                    timeout=60
+                )
+
+                if result.returncode != 0:
+                    # Check if error is due to file truncation/locking (Windows-specific)
+                    # Windows file locking manifests as: "file truncated", "error reading", or "No such file"
+                    stderr_lower = result.stderr.lower()
+                    is_file_locking_error = (
+                        "file truncated" in stderr_lower or
+                        "error reading" in stderr_lower or
+                        "no such file" in stderr_lower
+                    )
+                    if is_windows and is_file_locking_error:
+                        last_error = result.stderr
+                        if attempt < max_retries - 1:
+                            if self.show_progress:
+                                print("  [Windows] Detected file locking error, retrying...")
+                            delay = min(delay * 2, 1.0)  # Exponential backoff, max 1s
+                            continue
+                        else:
+                            # Last attempt failed
+                            error_msg = f"Archive creation failed after {max_retries} attempts (file locking)\n"
+                            error_msg += f"stderr: {result.stderr}\n"
+                            error_msg += f"stdout: {result.stdout}"
+                            raise ArchiveError(error_msg)
+
+                    error_msg = f"Archive creation failed for {archive_path.name}\n"
+                    error_msg += f"stderr: {result.stderr}\n"
+                    error_msg += f"stdout: {result.stdout}"
+                    raise ArchiveError(error_msg)
+
+                if not archive_path.exists():
+                    raise ArchiveError(f"Archive was not created: {archive_path}")
+
+                if self.show_progress:
+                    size = archive_path.stat().st_size
+                    print(f"✓ Created {archive_path.name}: {size:,} bytes ({size / 1024 / 1024:.2f} MB)")
+
+                return archive_path
+
+            except subprocess.TimeoutExpired as e:
+                raise ArchiveError(f"Archive creation timeout for {archive_path.name}") from 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:
+                if isinstance(e, ArchiveError):
+                    raise
+                # If Windows file locking error, retry
+                if is_windows and attempt < max_retries - 1:
+                    last_error = str(e)
+                    delay = min(delay * 2, 1.0)
+                    continue
+                raise ArchiveError(f"Failed to create archive {archive_path.name}: {e}") from e
+
+        # If we exhausted retries, raise the last error
+        if last_error:
+            raise ArchiveError(f"Archive creation failed after {max_retries} attempts: {last_error}")
+        raise ArchiveError(f"Archive creation failed after {max_retries} attempts")
+
+    def create_core_archive(
+        self,
+        ar_path: Path,
+        build_dir: Path,
+        object_files: List[Path]
+    ) -> Path:
+        """Create core.a archive from core object files.
+
+        Convenience method for creating the standard core.a archive.
+
+        Args:
+            ar_path: Path to archiver tool (ar)
+            build_dir: Build directory
+            object_files: List of core object file paths
+
+        Returns:
+            Path to generated core.a file
+
+        Raises:
+            ArchiveError: If archive creation fails
+        """
+        archive_path = build_dir / "core.a"
+        return self.create_archive(ar_path, archive_path, object_files)