klubhaus-doorbell/libraries/FastLED/ci/AGENTS.md

FastLED CI/Build System Agent Guidelines

🔧 Python Build System

Core Architecture

FastLED uses a high-performance Python-based build system:

Key Components:

• ci/compiler/clang_compiler.py - Core compiler with PCH and fingerprint cache
• ci/ci/fingerprint_cache.py - 99% faster PCH rebuilds through intelligent caching
• ci/util/build_flags.py - TOML-based build configuration management
• ci/compiler/test_example_compilation.py - Example compilation system

Performance Features:

• PCH (Precompiled Headers) - Dramatically faster compilation
• Fingerprint Cache - 99% time reduction for unchanged dependencies
• Parallel Compilation - Automatic CPU-optimized parallel builds
• Smart Rebuilds - Only rebuild when source files actually change

🚨 Command Execution Rules

FOREGROUND AGENTS (Interactive Development)

Python Code Execution:

• ✅ Create/modify tmp.py in project root (NOT subdirectories)
• ✅ Always run: uv run python tmp.py (never just python)
• ✅ Correct import paths: from ci.ci.module for ci.ci modules, from ci.module for top-level ci modules
• ❌ NEVER cd to subdirectories - stay in project root

Example:

# tmp.py (created in project root)
from ci.ci.clang_compiler import Compiler  # CORRECT import path
import subprocess
result = subprocess.run(['git', 'status'], capture_output=True, text=True)
print(result.stdout)

Then run: uv run python tmp.py

BACKGROUND AGENTS (Automated/CI Environments)

Restrictions:

• ❌ NO tmp.py files (forbidden for background agents)
• ✅ Use existing scripts: uv run python ci/ci-compile.py uno --examples Blink
• ✅ Use MCP server tools for programmatic operations
• ✅ Always use uv run python with existing scripts

🤖 MCP Server Configuration

Start server: uv run mcp_server.py

Available Tools:

• Running tests with various options
• Compiling examples for different platforms
• Code fingerprinting and change detection
• Linting and formatting
• Build info analysis for platform-specific defines, compiler flags, toolchain information
• Symbol analysis for binary optimization (all platforms)
• Stack trace setup for enhanced debugging
• 🌐 FastLED Web Compiler with Playwright (FOREGROUND AGENTS ONLY)
• 🚨 validate_completion tool (MANDATORY for background agents)

FastLED Web Compiler (FOREGROUND AGENTS ONLY)

Prerequisites:

• pip install fastled - FastLED web compiler
• pip install playwright - Browser automation
• Docker (optional, for faster compilation)

Usage via MCP Server:

# Basic usage
use run_fastled_web_compiler tool with:
- example_path: "examples/Audio"
- capture_duration: 30
- headless: false
- save_screenshot: true

Key Features:

• Compiles Arduino sketches to WASM for browser execution
• Captures console.log output with playwright automation
• Takes screenshots of running visualizations
• Monitors FastLED_onFrame calls to verify proper initialization

🚫 BACKGROUND AGENT RESTRICTION: This tool is COMPLETELY DISABLED for background agents and CI environments.

🤖 Linting Guidelines

FOREGROUND AGENTS

🚨 ALWAYS USE bash lint - DO NOT RUN INDIVIDUAL LINTING SCRIPTS

• ✅ CORRECT: bash lint
• ❌ FORBIDDEN: ./lint-js, ./check-js, python3 scripts/enhance-js-typing.py
• ❌ FORBIDDEN: uv run ruff check, uv run black, individual tools

WHY: bash lint provides comprehensive coverage of Python, C++, JavaScript, and enhancement analysis.

BACKGROUND AGENTS

CAN USE FINE-GRAINED LINTING FOR SPECIFIC NEEDS

Background agents may use individual linting scripts when needed:

• ./lint-js - JavaScript-only linting
• ./check-js - JavaScript type checking
• python3 scripts/enhance-js-typing.py - JavaScript enhancement analysis
• uv run ruff check - Python linting only
• MCP server lint_code tool - Programmatic access

BUT STILL PREFER bash lint FOR COMPREHENSIVE CHECKING

Build System Commands

Unit Test Compilation:

# Fast Python API (default)
bash test --unit --verbose  # Uses PCH optimization

# Disable PCH if needed  
bash test --unit --no-pch --verbose

# Legacy CMake system (8x slower)
bash test --unit --legacy --verbose  

Available Build Options:

• --no-pch - Disable precompiled headers
• --clang - Use Clang compiler (recommended for speed)
• --clean - Force full rebuild
• --verbose - Show detailed compilation output
• --legacy - Use old CMake system (discouraged)

Platform Compilation:

# Compile examples for specific platforms
uv run ci/ci-compile.py uno --examples Blink
uv run ci/ci-compile.py esp32dev --examples Blink
uv run ci/ci-compile.py teensy31 --examples Blink

WASM Compilation:

# Compile any sketch directory to WASM
uv run ci/wasm_compile.py path/to/your/sketch

# Quick compile test (compile only, no browser)
uv run ci/wasm_compile.py examples/Blink --just-compile

# Compile and open browser
uv run ci/wasm_compile.py examples/Blink -b --open

Build Troubleshooting

For Linker Issues:

1. Check tests/cmake/LinkerCompatibility.cmake first
2. Look for lld-link detection and compatibility functions
3. Check GNU→MSVC flag translation logic
4. Verify warning suppression settings

For Compiler Issues:

1. Check tests/cmake/CompilerDetection.cmake for detection logic
2. Review tests/cmake/CompilerFlags.cmake for flag conflicts
3. Verify optimization settings in OptimizationSettings.cmake

For Build Performance:

1. Check tests/cmake/ParallelBuild.cmake for parallel settings
2. Review LTO configuration in OptimizationSettings.cmake
3. Verify linker selection (mold, lld, default)

🚨 Critical User Feedback Corrections

Always Use uv run python - NEVER just python or uv run:

• ❌ WRONG: python -c "..."
• ❌ WRONG: uv run -c "..."
• ✅ CORRECT: uv run python -c "..."

Correct Import Paths:

• ✅ CORRECT: from ci.ci.clang_compiler import ... (for ci.ci modules)
• ✅ CORRECT: from ci.clang_compiler import ... (for top-level ci modules, if they exist)

Never Change Directory:

• ❌ WRONG: cd ci && python ...
• ❌ WRONG: cd ci/ci && python ...
• ✅ CORRECT: Stay in project root, use full paths: uv run python ci/script.py

Git-Bash Terminal Compatibility: Use leading space for git-bash compatibility:

• ✅ CORRECT: bash test (note the leading space)
• ❌ INCORRECT: bash test (may get truncated to ash test)

Platform Build Information Analysis

Generate Build Info:

# Compile a platform to generate build_info.json
uv run ci/ci-compile.py uno --examples Blink
uv run ci/ci-compile.py esp32dev --examples Blink

Analyze Platform Defines:

# Command line tool
python3 ci/ci/build_info_analyzer.py --board uno --show-defines

# Via MCP server
uv run mcp_server.py
# Use build_info_analysis tool with: board="uno", show_defines=true

Compare Platforms:

# Command line
python3 ci/ci/build_info_analyzer.py --compare uno esp32dev

# Via MCP 
# Use build_info_analysis tool with: board="uno", compare_with="esp32dev"

Symbol Analysis for Binary Optimization

Analyze specific platform:

uv run ci/ci/symbol_analysis.py --board uno
uv run ci/ci/symbol_analysis.py --board esp32dev
uv run ci/ci/symbol_analysis.py --board teensy31

Analyze all available platforms:

uv run ci/demo_symbol_analysis.py

Using MCP Server:

# Use MCP server tools
uv run mcp_server.py
# Then use symbol_analysis tool with board: "uno" or "auto"
# Or use symbol_analysis tool with run_all_platforms: true

JSON Output:

uv run symbol_analysis.py --board esp32dev --output-json
# Results saved to: .build/esp32dev_symbol_analysis.json

Memory Refresh Rule

🚨 ALL AGENTS: Read ci/AGENTS.md before concluding CI/build work to refresh memory about current Python build system rules and MCP server requirements.