fbuild 1.2.8__py3-none-any.whl → 1.2.15__py3-none-any.whl

fbuild/__init__.py

@@ -4,7 +4,9 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
-__version__ = "1.2.8"
+from fbuild.daemon.connection import DaemonConnection, connect_daemon
+
+__version__ = "1.2.15"
 
 
 def is_available() -> bool:
@@ -387,4 +389,6 @@ __all__ = [
     "is_available",
     "BuildContext",
     "Daemon",
+    "DaemonConnection",
+    "connect_daemon",
 ]

fbuild/build/configurable_compiler.py

@@ -14,6 +14,7 @@ from pathlib import Path
 from typing import Any, List, Dict, Optional, Union, TYPE_CHECKING
 
 from ..packages.package import IPackage, IToolchain, IFramework
+from ..output import ProgressCallback
 from .flag_builder import FlagBuilder
 from .compilation_executor import CompilationExecutor
 from .archive_creator import ArchiveCreator
@@ -335,6 +336,11 @@ class ConfigurableCompiler(ICompiler):
     def compile_sketch(self, sketch_path: Path) -> List[Path]:
         """Compile an Arduino sketch.
 
+        This method handles Arduino sketches that may contain multiple source files:
+        - The main .ino file is preprocessed and compiled
+        - Additional .cpp files in the sketch directory are also compiled
+        - The sketch directory is added to include paths for header file resolution
+
         Args:
             sketch_path: Path to .ino file
 
@@ -346,6 +352,12 @@ class ConfigurableCompiler(ICompiler):
         """
         object_files = []
 
+        # Add sketch directory to include paths so headers like ValidationConfig.h can be found
+        sketch_dir = sketch_path.parent
+        include_paths = self.get_include_paths()
+        if sketch_dir not in include_paths:
+            include_paths.insert(0, sketch_dir)  # Add at front for priority
+
         # Preprocess .ino to .cpp
         cpp_path = self.preprocess_ino(sketch_path)
 
@@ -357,19 +369,38 @@ class ConfigurableCompiler(ICompiler):
         # Skip compilation if object file is up-to-date
         if not self.needs_rebuild(cpp_path, obj_path):
             object_files.append(obj_path)
-            return object_files
+        else:
+            # Compile preprocessed .cpp
+            compiled_obj = self.compile_source(cpp_path, obj_path)
+            object_files.append(compiled_obj)
+
+        # Find and compile additional .cpp files in the sketch directory
+        # (Arduino IDE compiles all .cpp files in the sketch folder)
+        for cpp_file in sketch_dir.glob("*.cpp"):
+            cpp_obj_path = obj_dir / f"{cpp_file.stem}.o"
+
+            # Skip compilation if object file is up-to-date
+            if not self.needs_rebuild(cpp_file, cpp_obj_path):
+                object_files.append(cpp_obj_path)
+                continue
 
-        # Compile preprocessed .cpp
-        compiled_obj = self.compile_source(cpp_path, obj_path)
-        object_files.append(compiled_obj)
+            try:
+                compiled_obj = self.compile_source(cpp_file, cpp_obj_path)
+                object_files.append(compiled_obj)
+            except ConfigurableCompilerError as e:
+                # Re-raise with more context about which file failed
+                raise ConfigurableCompilerError(
+                    f"Failed to compile sketch source file {cpp_file.name}: {e}"
+                )
 
         return object_files
 
-    def compile_core(self, progress_bar: Optional[Any] = None) -> List[Path]:
+    def compile_core(self, progress_bar: Optional[Any] = None, progress_callback: ProgressCallback | None = None) -> List[Path]:
         """Compile Arduino core sources.
 
         Args:
             progress_bar: Optional tqdm progress bar to update during compilation
+            progress_callback: Optional callback for progress notifications
 
         Returns:
             List of generated object file paths
@@ -394,9 +425,15 @@ class ConfigurableCompiler(ICompiler):
         if progress_bar is not None:
             self.compilation_executor.show_progress = False
 
+        total_sources = len(core_sources)
+
         try:
             # Compile each core source
-            for source in core_sources:
+            for idx, source in enumerate(core_sources, 1):
+                # Notify progress callback of file start
+                if progress_callback is not None:
+                    progress_callback.on_file_start(source.name, idx, total_sources)
+
                 # Update progress bar BEFORE compilation for better UX
                 if progress_bar is not None:
                     progress_bar.set_description(f'Compiling {source.name[:30]}')
@@ -407,17 +444,23 @@ class ConfigurableCompiler(ICompiler):
                     # Skip compilation if object file is up-to-date
                     if not self.needs_rebuild(source, obj_path):
                         object_files.append(obj_path)
+                        if progress_callback is not None:
+                            progress_callback.on_file_complete(source.name, idx, total_sources, cached=True)
                         if progress_bar is not None:
                             progress_bar.update(1)
                         continue
 
                     compiled_obj = self.compile_source(source, obj_path)
                     object_files.append(compiled_obj)
+                    if progress_callback is not None:
+                        progress_callback.on_file_complete(source.name, idx, total_sources, cached=False)
                     if progress_bar is not None:
                         progress_bar.update(1)
                 except ConfigurableCompilerError as e:
                     if self.show_progress:
                         print(f"Warning: Failed to compile {source.name}: {e}")
+                    if progress_callback is not None:
+                        progress_callback.on_file_complete(source.name, idx, total_sources, cached=False)
                     if progress_bar is not None:
                         progress_bar.update(1)
         finally:

fbuild/build/configurable_linker.py

@@ -18,6 +18,7 @@ from pathlib import Path
 from typing import List, Dict, Any, Optional, Union
 
 from ..packages.package import IPackage, IToolchain, IFramework
+from ..output import log_detail, format_size
 from .binary_generator import BinaryGenerator
 from .compiler import ILinker, LinkerError
 
@@ -322,11 +323,15 @@ class ConfigurableLinker(ILinker):
 
         # Execute linker
         if self.show_progress:
-            print("Linking firmware.elf...")
-            print(f"  Object files: {len(object_files)}")
-            print(f"  Core archive: {core_archive.name}")
-            print(f"  SDK libraries: {len(sdk_libs)}")
-            print(f"  Linker scripts: {len(linker_scripts)}")
+            log_detail("Linking firmware.elf...")
+            log_detail(f"Object files: {len(object_files)}")
+            log_detail(f"Core archive: {core_archive.name}")
+            log_detail(f"SDK libraries: {len(sdk_libs)}")
+            log_detail(f"Linker scripts: {len(linker_scripts)}")
+            core_size = core_archive.stat().st_size if core_archive.exists() else 0
+            lib_size = sum(a.stat().st_size for a in library_archives if a.exists())
+            obj_size = sum(o.stat().st_size for o in object_files if o.exists())
+            log_detail(f"Inputs: core ({format_size(core_size)}) + {len(library_archives)} libs ({format_size(lib_size)}) + {len(object_files)} objects ({format_size(obj_size)})")
 
         # Add retry logic for Windows file locking issues
         is_windows = platform.system() == "Windows"
@@ -340,7 +345,7 @@ class ConfigurableLinker(ILinker):
                     gc.collect()
                     time.sleep(delay)
                     if self.show_progress:
-                        print(f"  Retrying linking (attempt {attempt + 1}/{max_retries})...")
+                        log_detail(f"Retrying linking (attempt {attempt + 1}/{max_retries})...")
 
                 result = subprocess.run(
                     cmd,
@@ -362,7 +367,7 @@ class ConfigurableLinker(ILinker):
                     if is_windows and is_file_locking_error:
                         if attempt < max_retries - 1:
                             if self.show_progress:
-                                print("  [Windows] Detected file locking error, retrying...")
+                                log_detail("[Windows] Detected file locking error, retrying...")
                             delay = min(delay * 2, 1.0)  # Exponential backoff, max 1s
                             continue
                         else:
@@ -386,7 +391,7 @@ class ConfigurableLinker(ILinker):
 
             if self.show_progress:
                 size = output_elf.stat().st_size
-                print(f"✓ Created firmware.elf: {size:,} bytes ({size / 1024 / 1024:.2f} MB)")
+                log_detail(f"Created firmware.elf: {format_size(size)}")
 
             return output_elf
 
@@ -477,7 +482,7 @@ class ConfigurableLinker(ILinker):
 
             if self.show_progress:
                 size = output_hex.stat().st_size
-                print(f"✓ Created firmware.hex: {size:,} bytes")
+                log_detail(f"Created firmware.hex: {format_size(size)}")
 
             return output_hex
 

fbuild/build/orchestrator_esp32.py

@@ -25,7 +25,7 @@ from .orchestrator import IBuildOrchestrator, BuildResult
 from .build_utils import safe_rmtree
 from .build_state import BuildStateTracker
 from .build_info_generator import BuildInfoGenerator
-from ..output import log_phase, log_detail, log_warning
+from ..output import log_phase, log_detail, log_warning, DefaultProgressCallback
 
 # Module-level logger
 logger = logging.getLogger(__name__)
@@ -299,9 +299,12 @@ class OrchestratorESP32(IBuildOrchestrator):
                 compilation_queue=compilation_queue
             )
 
+            # Create progress callback for detailed file-by-file tracking
+            progress_callback = DefaultProgressCallback(verbose_only=not verbose)
+
             # Compile Arduino core with progress bar
             if verbose:
-                core_obj_files = compiler.compile_core()
+                core_obj_files = compiler.compile_core(progress_callback=progress_callback)
             else:
                 # Use tqdm progress bar for non-verbose mode
                 from tqdm import tqdm
@@ -318,7 +321,7 @@ class OrchestratorESP32(IBuildOrchestrator):
                     ncols=80,
                     leave=False
                 ) as pbar:
-                    core_obj_files = compiler.compile_core(progress_bar=pbar)
+                    core_obj_files = compiler.compile_core(progress_bar=pbar, progress_callback=progress_callback)
 
                 # Print completion message
                 log_detail(f"Compiled {len(core_obj_files)} core files")

fbuild/build/orchestrator_rp2040.py

@@ -19,6 +19,7 @@ from ..packages.toolchain_rp2040 import ToolchainRP2040
 from ..packages.library_manager import LibraryManager, LibraryError
 from ..config.board_config import BoardConfig
 from ..cli_utils import BannerFormatter
+from ..output import DefaultProgressCallback
 from .configurable_compiler import ConfigurableCompiler
 from .configurable_linker import ConfigurableLinker
 from .linker import SizeInfo
@@ -276,9 +277,12 @@ class OrchestratorRP2040(IBuildOrchestrator):
                 user_build_flags=build_flags
             )
 
+            # Create progress callback for detailed file-by-file tracking
+            progress_callback = DefaultProgressCallback(verbose_only=not verbose)
+
             # Compile Arduino core with progress bar
             if verbose:
-                core_obj_files = compiler.compile_core()
+                core_obj_files = compiler.compile_core(progress_callback=progress_callback)
             else:
                 # Use tqdm progress bar for non-verbose mode
                 from tqdm import tqdm
@@ -295,7 +299,7 @@ class OrchestratorRP2040(IBuildOrchestrator):
                     ncols=80,
                     leave=False
                 ) as pbar:
-                    core_obj_files = compiler.compile_core(progress_bar=pbar)
+                    core_obj_files = compiler.compile_core(progress_bar=pbar, progress_callback=progress_callback)
 
                 # Print completion message
                 logger.info(f"Compiled {len(core_obj_files)} core files")

fbuild/cli.py

@@ -272,7 +272,194 @@ def monitor_command(args: MonitorArgs) -> None:
         ErrorFormatter.handle_unexpected_error(e, args.verbose)
 
 
-def daemon_command(action: str, pid: Optional[int] = None, force: bool = False) -> None:
+def device_command(
+    action: str,
+    device_id: Optional[str] = None,
+    lease_type: str = "exclusive",
+    description: str = "",
+    reason: str = "",
+    refresh: bool = False,
+) -> None:
+    """Manage devices connected to the daemon.
+
+    Examples:
+        fbuild device list                           # List all connected devices
+        fbuild device list --refresh                 # Refresh device discovery before listing
+        fbuild device status <device_id>             # Show detailed device status
+        fbuild device lease <device_id>              # Acquire exclusive lease on device
+        fbuild device lease <device_id> --monitor    # Acquire monitor (read-only) lease
+        fbuild device release <device_id>            # Release lease on device
+        fbuild device take <device_id> --reason "Urgent deployment"  # Preempt current holder
+    """
+    try:
+        if action == "list":
+            # List all devices
+            devices = daemon_client.list_devices(refresh=refresh)
+            if devices is None:
+                ErrorFormatter.print_error("Failed to list devices", "Daemon may not be running")
+                sys.exit(1)
+
+            if not devices:
+                print("No devices found")
+                sys.exit(0)
+
+            print(f"Found {len(devices)} device(s):\n")
+            for device in devices:
+                device_id = device.get("device_id", "unknown")
+                port = device.get("port", "unknown")
+                connected = "✅ connected" if device.get("is_connected", False) else "❌ disconnected"
+                exclusive = device.get("exclusive_holder")
+                monitor_count = device.get("monitor_count", 0)
+
+                print(f"  {device_id}")
+                print(f"    Port: {port}")
+                print(f"    Status: {connected}")
+                if exclusive:
+                    print(f"    Exclusive holder: {exclusive}")
+                if monitor_count > 0:
+                    print(f"    Monitor sessions: {monitor_count}")
+                print()
+
+            sys.exit(0)
+
+        elif action == "status":
+            if not device_id:
+                ErrorFormatter.print_error("Device ID required", "Usage: fbuild device status <device_id>")
+                sys.exit(1)
+
+            status = daemon_client.get_device_status(device_id)
+            if status is None:
+                ErrorFormatter.print_error(f"Device not found: {device_id}", "")
+                sys.exit(1)
+
+            print(f"Device: {device_id}")
+            print(f"  Connected: {'✅ Yes' if status.get('is_connected') else '❌ No'}")
+            print(f"  Port: {status.get('device_info', {}).get('port', 'unknown')}")
+            print(f"  Available for exclusive: {'✅ Yes' if status.get('is_available_for_exclusive') else '❌ No'}")
+
+            if status.get("exclusive_lease"):
+                lease = status["exclusive_lease"]
+                print(f"  Exclusive holder: {lease.get('client_id', 'unknown')}")
+                print(f"    Description: {lease.get('description', 'N/A')}")
+
+            if status.get("monitor_count", 0) > 0:
+                print(f"  Monitor sessions: {status['monitor_count']}")
+                for monitor in status.get("monitor_leases", []):
+                    print(f"    - {monitor.get('client_id', 'unknown')}")
+
+            sys.exit(0)
+
+        elif action == "lease":
+            if not device_id:
+                ErrorFormatter.print_error("Device ID required", "Usage: fbuild device lease <device_id>")
+                sys.exit(1)
+
+            result = daemon_client.acquire_device_lease(
+                device_id=device_id,
+                lease_type=lease_type,
+                description=description,
+            )
+
+            if result is None:
+                ErrorFormatter.print_error("Failed to acquire lease", "Daemon may not be running")
+                sys.exit(1)
+
+            if result.get("success"):
+                lease_id = result.get("lease_id", "unknown")
+                print(f"✅ Acquired {lease_type} lease on device {device_id}")
+                print(f"   Lease ID: {lease_id}")
+                sys.exit(0)
+            else:
+                ErrorFormatter.print_error(f"Failed to acquire lease: {result.get('message', 'unknown error')}", "")
+                sys.exit(1)
+
+        elif action == "release":
+            if not device_id:
+                ErrorFormatter.print_error("Device ID or lease ID required", "Usage: fbuild device release <device_id>")
+                sys.exit(1)
+
+            result = daemon_client.release_device_lease(device_id)
+
+            if result is None:
+                ErrorFormatter.print_error("Failed to release lease", "Daemon may not be running")
+                sys.exit(1)
+
+            if result.get("success"):
+                print(f"✅ Released lease on device {device_id}")
+                sys.exit(0)
+            else:
+                ErrorFormatter.print_error(f"Failed to release lease: {result.get('message', 'unknown error')}", "")
+                sys.exit(1)
+
+        elif action == "take":
+            if not device_id:
+                ErrorFormatter.print_error("Device ID required", 'Usage: fbuild device take <device_id> --reason "..."')
+                sys.exit(1)
+
+            if not reason:
+                ErrorFormatter.print_error("Reason required for preemption", 'Usage: fbuild device take <device_id> --reason "..."')
+                sys.exit(1)
+
+            result = daemon_client.preempt_device(device_id, reason)
+
+            if result is None:
+                ErrorFormatter.print_error("Failed to preempt device", "Daemon may not be running")
+                sys.exit(1)
+
+            if result.get("success"):
+                preempted = result.get("preempted_client_id")
+                print(f"✅ Preempted device {device_id}")
+                if preempted:
+                    print(f"   Previous holder: {preempted}")
+                print(f"   Lease ID: {result.get('lease_id', 'unknown')}")
+                sys.exit(0)
+            else:
+                ErrorFormatter.print_error(f"Failed to preempt device: {result.get('message', 'unknown error')}", "")
+                sys.exit(1)
+
+        else:
+            ErrorFormatter.print_error(f"Unknown device action: {action}", "")
+            print("Valid actions: list, status, lease, release, take")
+            sys.exit(1)
+
+    except KeyboardInterrupt as ke:
+        from fbuild.interrupt_utils import handle_keyboard_interrupt_properly
+
+        handle_keyboard_interrupt_properly(ke)
+    except Exception as e:
+        ErrorFormatter.handle_unexpected_error(e, verbose=False)
+
+
+def show_command(target: str, follow: bool = True, lines: int = 50) -> None:
+    """Show daemon logs or other information.
+
+    Examples:
+        fbuild show daemon             # Tail daemon logs (Ctrl-C to stop, daemon continues)
+        fbuild show daemon --no-follow # Show last 50 lines and exit
+        fbuild show daemon --lines 100 # Show last 100 lines then follow
+    """
+    try:
+        if target == "daemon":
+            daemon_client.tail_daemon_logs(follow=follow, lines=lines)
+            sys.exit(0)
+        else:
+            from fbuild.cli_utils import ErrorFormatter
+
+            ErrorFormatter.print_error(f"Unknown target: {target}", "")
+            print("Valid targets: daemon")
+            sys.exit(1)
+
+    except KeyboardInterrupt as ke:
+        from fbuild.interrupt_utils import handle_keyboard_interrupt_properly
+
+        handle_keyboard_interrupt_properly(ke)
+    except Exception as e:
+        from fbuild.cli_utils import ErrorFormatter
+
+        ErrorFormatter.handle_unexpected_error(e, verbose=False)
+
+
+def daemon_command(action: str, pid: Optional[int] = None, force: bool = False, follow: bool = True, lines: int = 50) -> None:
     """Manage the fbuild daemon.
 
     Examples:
@@ -282,6 +469,7 @@ def daemon_command(action: str, pid: Optional[int] = None, force: bool = False)
         fbuild daemon list         # List all daemon instances
         fbuild daemon locks        # Show lock status
         fbuild daemon clear-locks  # Clear stale locks
+        fbuild daemon monitor      # Tail daemon logs (alias for 'fbuild show daemon')
         fbuild daemon kill --pid 12345        # Kill specific daemon
         fbuild daemon kill-all               # Kill all daemons
         fbuild daemon kill-all --force       # Force kill all daemons
@@ -374,9 +562,14 @@ def daemon_command(action: str, pid: Optional[int] = None, force: bool = False)
                 print("No daemon instances found to kill")
             sys.exit(0)
 
+        elif action == "monitor":
+            # Monitor daemon logs (tail the log file)
+            daemon_client.tail_daemon_logs(follow=follow, lines=lines)
+            sys.exit(0)
+
         else:
             ErrorFormatter.print_error(f"Unknown daemon action: {action}", "")
-            print("Valid actions: status, stop, restart, list, locks, clear-locks, kill, kill-all")
+            print("Valid actions: status, stop, restart, list, locks, clear-locks, monitor, kill, kill-all")
             sys.exit(1)
 
     except KeyboardInterrupt as ke:
@@ -470,9 +663,16 @@ def main() -> None:
 
     Replace PlatformIO with URL-based platform/toolchain management.
     """
+    # Display daemon stats as the first action (unless --version or --help anywhere)
+    help_flags = {"--version", "-V", "--help", "-h"}
+    skip_stats = any(arg in help_flags for arg in sys.argv)
+    if len(sys.argv) >= 2 and not skip_stats:
+        daemon_client.display_daemon_stats_compact()
+        print()  # Blank line after stats
+
     # Handle default action: fbuild <project_dir> [flags] → deploy with monitor
     # This check must happen before argparse to avoid conflicts
-    if len(sys.argv) >= 2 and not sys.argv[1].startswith("-") and sys.argv[1] not in ["build", "deploy", "monitor", "daemon"]:
+    if len(sys.argv) >= 2 and not sys.argv[1].startswith("-") and sys.argv[1] not in ["build", "deploy", "monitor", "daemon", "device", "show"]:
         # User provided a path without a subcommand - use default action
         deploy_args = parse_default_action_args(sys.argv)
         deploy_command(deploy_args)
@@ -640,6 +840,29 @@ def main() -> None:
         help="Show verbose output",
     )
 
+    # Show command
+    show_parser = subparsers.add_parser(
+        "show",
+        help="Show daemon logs or other information",
+    )
+    show_parser.add_argument(
+        "target",
+        choices=["daemon"],
+        help="What to show (currently only 'daemon' for daemon logs)",
+    )
+    show_parser.add_argument(
+        "--no-follow",
+        action="store_true",
+        dest="no_follow",
+        help="Don't follow the log file (just print last lines and exit)",
+    )
+    show_parser.add_argument(
+        "--lines",
+        type=int,
+        default=50,
+        help="Number of lines to show initially (default: 50)",
+    )
+
     # Daemon command
     daemon_parser = subparsers.add_parser(
         "daemon",
@@ -647,7 +870,7 @@ def main() -> None:
     )
     daemon_parser.add_argument(
         "action",
-        choices=["status", "stop", "restart", "list", "locks", "clear-locks", "kill", "kill-all"],
+        choices=["status", "stop", "restart", "list", "locks", "clear-locks", "monitor", "kill", "kill-all"],
         help="Daemon action to perform",
     )
     daemon_parser.add_argument(
@@ -661,6 +884,56 @@ def main() -> None:
         action="store_true",
         help="Force kill without graceful shutdown (for 'kill' and 'kill-all' actions)",
     )
+    daemon_parser.add_argument(
+        "--no-follow",
+        action="store_true",
+        dest="no_follow",
+        help="Don't follow the log file, just print last lines and exit (for 'monitor' action)",
+    )
+    daemon_parser.add_argument(
+        "--lines",
+        type=int,
+        default=50,
+        help="Number of lines to show initially (for 'monitor' action, default: 50)",
+    )
+
+    # Device command
+    device_parser = subparsers.add_parser(
+        "device",
+        help="Manage devices connected to the daemon",
+    )
+    device_parser.add_argument(
+        "action",
+        choices=["list", "status", "lease", "release", "take"],
+        help="Device action to perform",
+    )
+    device_parser.add_argument(
+        "device_id",
+        nargs="?",
+        default=None,
+        help="Device ID (required for status, lease, release, take)",
+    )
+    device_parser.add_argument(
+        "--monitor",
+        action="store_true",
+        dest="lease_monitor",
+        help="Acquire monitor (read-only) lease instead of exclusive (for 'lease' action)",
+    )
+    device_parser.add_argument(
+        "--description",
+        default="",
+        help="Description for lease (for 'lease' action)",
+    )
+    device_parser.add_argument(
+        "--reason",
+        default="",
+        help="Reason for preemption (required for 'take' action)",
+    )
+    device_parser.add_argument(
+        "--refresh",
+        action="store_true",
+        help="Refresh device discovery before listing (for 'list' action)",
+    )
 
     # Parse arguments
     parsed_args = parser.parse_args()
@@ -710,7 +983,29 @@ def main() -> None:
         )
         monitor_command(monitor_args)
     elif parsed_args.command == "daemon":
-        daemon_command(parsed_args.action, pid=parsed_args.pid, force=parsed_args.force)
+        daemon_command(
+            parsed_args.action,
+            pid=parsed_args.pid,
+            force=parsed_args.force,
+            follow=not parsed_args.no_follow,
+            lines=parsed_args.lines,
+        )
+    elif parsed_args.command == "show":
+        show_command(
+            target=parsed_args.target,
+            follow=not parsed_args.no_follow,
+            lines=parsed_args.lines,
+        )
+    elif parsed_args.command == "device":
+        lease_type = "monitor" if parsed_args.lease_monitor else "exclusive"
+        device_command(
+            action=parsed_args.action,
+            device_id=parsed_args.device_id,
+            lease_type=lease_type,
+            description=parsed_args.description,
+            reason=parsed_args.reason,
+            refresh=parsed_args.refresh,
+        )
 
 
 if __name__ == "__main__":

fbuild/config/ini_parser.py

@@ -6,6 +6,7 @@ environment configurations for building embedded projects.
 """
 
 import configparser
+import os
 from pathlib import Path
 from typing import Dict, List, Optional
 
@@ -301,14 +302,25 @@ class PlatformIOConfig:
 
     def get_src_dir(self) -> Optional[str]:
         """
-        Get source directory override from [platformio] section.
+        Get source directory override.
+
+        Checks in order:
+        1. PLATFORMIO_SRC_DIR environment variable (matches PlatformIO behavior)
+        2. src_dir in [platformio] section of platformio.ini
 
         Returns:
             Source directory path relative to project root, or None if not specified
 
         Example:
+            If PLATFORMIO_SRC_DIR=examples/Validation, returns 'examples/Validation'
             If [platformio] section has src_dir = examples/Blink, returns 'examples/Blink'
         """
+        # First check environment variable (PlatformIO standard behavior)
+        env_src_dir = os.environ.get("PLATFORMIO_SRC_DIR", "").strip()
+        if env_src_dir:
+            return env_src_dir
+
+        # Fall back to platformio.ini setting
         if "platformio" in self.config:
             src_dir = self.config["platformio"].get("src_dir", "").strip()
             # Remove inline comments (everything after ';')