imported from "final" folder
This commit is contained in:
243
.pio/libdeps/esp01_1m/FastLED/CONTRIBUTING.md
Normal file
243
.pio/libdeps/esp01_1m/FastLED/CONTRIBUTING.md
Normal file
@@ -0,0 +1,243 @@
|
||||
## 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)
|
||||
Reference in New Issue
Block a user