244 lines
9.0 KiB
Markdown
244 lines
9.0 KiB
Markdown
## 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](https://www.python.org/downloads/) or [uv](https://github.com/astral-sh/uv) installed on the system.
|
|
|
|
## FastLED compiler cli
|
|
|
|
[](https://github.com/FastLED/FastLED/actions/workflows/build_clone_and_compile.yml)
|
|
|
|
The FastLED compiler cli can be invoked at the project root.
|
|
|
|
```bash (MacOS/Linux, windows us git-bsh or compile.bat)
|
|
git clone https://github.com/fastled/fastled
|
|
cd fastled
|
|
./compile uno --examples Blink # linux/macos/git-bash
|
|
# compile.bat # Windows.
|
|
```
|
|
|
|
## Linting and Unit Testing
|
|
|
|
```bash
|
|
./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 a bunch of platforms at once.
|
|
|
|
```
|
|
./compile teensy41,teensy40 --examples Blink
|
|
./compile esp32dev,esp32s3,esp32c3,esp32c6,esp32s2 --examples Blink,Apa102HD
|
|
./compiles uno,digix,attiny85 --examples Blink,Apa102HD
|
|
```
|
|
|
|
## 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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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](https://marketplace.visualstudio.com/items?itemName=platformio.platformio-ide) extension is installed. The development sketch to test library changes can be found at [dev/dev.ino](dev/dev.ino).
|
|
|
|
* Make sure you have [platformio](https://marketplace.visualstudio.com/items?itemName=platformio.platformio-ide) installed.
|
|
* Click the compile button.
|
|
|
|
|
|
*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
|
|
```cpp
|
|
// 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
|
|
```cpp
|
|
// 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
|
|
```cpp
|
|
// 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](DEBUGGING.md).
|
|
|
|
|
|
## Once you are done
|
|
* run `./test`
|
|
* run `./lint`
|
|
* Then submit your code via a git pull request.
|
|
|
|
|
|
## Going deeper
|
|
|
|
[ADVANCED_DEVELOPMENT.md](https://github.com/FastLED/FastLED/blob/master/ADVANCED_DEVELOPMENT.md)
|