Skip to content

Latest commit

 

History

History
252 lines (182 loc) · 9.25 KB

CONTRIBUTING.md

File metadata and controls

252 lines (182 loc) · 9.25 KB

Contributing

The most important part about contributing to FastLED is knowing how to test your changes.

The FastLED library includes a powerful cli that can compile to any device. It will run if you have either python or uv installed on the system.

FastLED compiler cli

clone and compile

The FastLED compiler cli can be invoked at the project root.

git clone https://github.com/fastled/fastled
cd fastled
./compile uno  # Compiles Blink by default (linux/macos/git-bash)
# compile.bat  # Windows.

Linting and Unit Testing

./lint
./test  # runs unit tests
# Note that you do NOT need to install the C++ compiler toolchain
# for compiling + running unit tests via ./test. If `gcc` is not
# found in your system `PATH` then the `ziglang` clang compiler
# will be swapped in automatically.

Testing platforms and examples

By default, ./compile <board> compiles the Blink example. You can specify different examples or use the all keyword to compile all examples:

# Compile Blink (default)
./compile uno

# Compile specific examples
./compile teensy41,teensy40 --examples ColorPalette
./compile esp32dev,esp32s3,esp32c3,esp32c6,esp32s2 --examples Blink,Apa102HD

# Compile ALL examples (use 'all' keyword)
./compile uno all
./compile esp32dev all

Unit Tests

Shared code is unit-tested on the host machine. They can be found at tests/ at the root of the repo. Unit testing only requires either python or uv to be installed. The C++ compiler toolchain will be installed automatically.

The easiest way to run the tests is just use ./test

Alternatively, tests can be built and run for your development machine with CMake:

cmake -S tests -B tests/.build
ctest --test-dir tests/.build --output-on-failure
# Not that this will fail if you do not have gcc installed. When in doubt
# use ./test to compile the unit tests, as a compiler is guaranteed to be
# available via this tool.

QEMU Emulation Testing

FastLED supports testing ESP32-S3 examples in QEMU emulation, providing a powerful way to validate code without physical hardware.

Running ESP32-S3 Examples in QEMU

# Test default examples (BlinkParallel, RMT5WorkerPool)
./test --qemu esp32s3

# Test specific examples
./test --qemu esp32s3 BlinkParallel
./test --qemu esp32s3 RMT5WorkerPool BlinkParallel

# Quick validation test (setup verification only)
FASTLED_QEMU_QUICK_TEST=true ./test --qemu esp32s3

What QEMU Testing Does

  1. Automatic QEMU Installation: Downloads and sets up ESP32-S3 QEMU emulator
  2. Cross-Platform Compilation: Builds examples for ESP32-S3 target architecture
  3. Emulated Execution: Runs compiled firmware in QEMU virtual environment
  4. Automated Validation: Monitors execution for success/failure indicators

QEMU Test Output

The QEMU tests provide detailed feedback:

  • Build Status: Compilation success/failure for each example
  • Execution Results: Runtime behavior in emulated environment
  • Summary Statistics: Pass/fail counts and timing information
  • Error Details: Specific failure reasons when tests don't pass

Supported Platforms

Currently supported QEMU platforms:

  • esp32s3: ESP32-S3 SoC emulation

Future platforms may include additional ESP32 variants as QEMU support expands.

Advanced QEMU Usage

# Run with verbose output to see detailed build and execution logs
./test --qemu esp32s3 --verbose

# Test in non-interactive mode (useful for CI/CD)
./test --qemu esp32s3 --no-interactive

VSCode

We also support VSCode and IntelliSense auto-completion when the free platformio extension is installed. The development sketch to test library changes can be found at dev/dev.ino.

  • Make sure you have platformio installed.
  • Click the compile button.

image Changes in non platform specific code can be tested quickly in our webcompiler by invoking the script ./wasm at the project root

VSCode Debugging Guide

FastLED includes comprehensive VSCode debugging support with GDB and Clang-generated debug symbols, providing professional-grade step-through debugging capabilities for the test suite.

Quick Start

  1. Prerequisites: Ensure you have VSCode with the C/C++ extension installed
  2. Open a test file: e.g., tests/test_allocator.cpp
  3. Set breakpoints: Click the left margin next to line numbers
  4. Press F5: Automatically debugs the corresponding test executable
  5. Debug: Use F10 (step over), F11 (step into), F5 (continue)

Available Debug Configurations

🎯 "Debug FastLED Test (Current File)" ⭐ Most Common

  • When to use: When you have any test file open (e.g., test_allocator.cpp)
  • What it does: Automatically detects and debugs the corresponding test executable
  • How to use: Open any test_*.cpp file and press F5

🔧 Specific Test Configurations

  • "Debug test_allocator" - Memory allocation and deallocation debugging
  • "Debug test_math" - Mathematical functions and color calculations
  • "Debug test_fastled" - Core FastLED functionality and API
  • "Debug test_hsv16" - Color space conversions and accuracy
  • "Debug test_corkscrew" - LED layout and geometric calculations

🎛️ Advanced Configurations

  • "Debug with Specific Test Filter" - Run only specific test cases
    • Example: Filter "allocator_inlined" to debug only those tests
  • "Debug with Custom Args" - Pass custom command-line arguments
    • Example: --verbose, --list-test-cases, etc.

Debugging Features

Step Commands

  • F5: Continue execution
  • F10: Step over (execute current line)
  • F11: Step into (enter function calls)
  • Shift+F11: Step out (exit current function)
  • Ctrl+Shift+F5: Restart debugging
  • Shift+F5: Stop debugging

Variable Inspection

  • Variables panel: See all local variables and their values
  • Watch panel: Add expressions to monitor continuously
  • Hover inspection: Hover over variables to see values
  • Debug console: Type expressions to evaluate

Build Tasks for Debugging

Access via Ctrl+Shift+P → "Tasks: Run Task":

  • "Build FastLED Tests" - Quick incremental build (default: Ctrl+Shift+B)
  • "Build FastLED Tests (Full)" - Complete build including Python tests
  • "Build Single Test" - Build and run specific test only
  • "Clean Build" - Remove all build artifacts and rebuild

Debugging Tips for FastLED

Memory Issues

// Use test_allocator for memory debugging
// Set breakpoints on allocate/deallocate functions
// Watch pointer values in Variables panel
// Monitor memory patterns for corruption

Color Conversion Issues

// Use test_hsv16 for color space debugging
// Watch RGB/HSV values during conversion
// Step through algorithms with F11
// Compare expected vs actual in Watch panel

Template Debugging

// Clang generates excellent template debug info
// Step into template functions with F11
// Watch template parameters in Variables panel
// Use Call Stack to understand instantiation chain

Technical Setup

Clang + GDB Benefits

This setup provides the best of both worlds:

  • Clang's superior symbol generation: Better template debugging, modern C++ support
  • GDB's mature debugging features: Robust breakpoint handling, memory inspection
  • Cross-platform compatibility: Works on Linux, macOS, Windows
  • FastLED optimization: Unified compilation testing with FASTLED_ALL_SRC=1

Debug Build Configuration

The FastLED test system automatically uses optimal debug settings:

  • Compiler: Clang (when available) or GCC fallback
  • Debug info: -g3 (full debug information including macros)
  • Optimization: -O0 (no optimization for accurate debugging)
  • Frame pointers: -fno-omit-frame-pointer (for accurate stack traces)

Troubleshooting

"Program not found" Error

  1. Build first: Run "Build FastLED Tests" task
  2. Check executable exists: ls tests/.build/bin/test_*
  3. Verify path: Ensure executable path in launch.json is correct

Breakpoints Not Hit

  1. Check file paths: Ensure source file matches executable
  2. Verify compilation: Code might be optimized out
  3. Try function breakpoints: Sometimes more reliable than line breakpoints

Variables Show "Optimized Out"

  1. Use debug build: Already configured with -O0 (no optimization)
  2. Check variable scope: Variable might be out of scope
  3. Try different breakpoint: Move breakpoint to where variable is active

For complete debugging documentation, see DEBUGGING.md.

Once you are done

  • run ./test
  • run ./lint
  • Then submit your code via a git pull request.

Going deeper

ADVANCED_DEVELOPMENT.md