imported from "final" folder
This commit is contained in:
494
.pio/libdeps/esp01_1m/FastLED/FEATURE_PACKAGE_JSON.md
Normal file
494
.pio/libdeps/esp01_1m/FastLED/FEATURE_PACKAGE_JSON.md
Normal file
@@ -0,0 +1,494 @@
|
||||
# FastLED Native Platform Configuration
|
||||
|
||||
## Overview
|
||||
|
||||
This document describes the comprehensive `platform.json` configuration for FastLED's native build platform. The design leverages the Python `ziglang` package to provide a unified, cross-platform compilation environment that integrates seamlessly with the existing `build_unit.toml` structure.
|
||||
|
||||
## Key Design Principles
|
||||
|
||||
### 1. **Unified Toolchain Integration**
|
||||
- **Ziglang Foundation**: Uses `python -m ziglang` commands matching the current `build_unit.toml` configuration
|
||||
- **Cross-Platform Consistency**: Single toolchain across Linux, macOS, Windows with automatic target detection
|
||||
- **Direct TOML Mapping**: Toolchain commands directly map between `platform.json` and `build_unit.toml`
|
||||
|
||||
### 2. **Comprehensive Architecture Support**
|
||||
- **x86_64 Targets**: Linux, macOS, Windows with appropriate system-specific flags
|
||||
- **ARM64 Targets**: Linux (generic), macOS (Apple Silicon), Windows with optimized CPU settings
|
||||
- **RISC-V 64**: Linux support for emerging architecture
|
||||
- **Auto-Detection**: Intelligent target selection for simplified development workflow
|
||||
|
||||
### 3. **Arduino Package Format Compliance**
|
||||
- **PlatformIO Integration**: Full compatibility with PlatformIO package management
|
||||
- **Framework Support**: Both FastLED-stub and Arduino-stub frameworks
|
||||
- **Package Dependencies**: Proper toolchain, framework, and tool dependency management
|
||||
- **Versioning Strategy**: Semantic versioning with appropriate version constraints
|
||||
|
||||
### 4. **Build System Flexibility**
|
||||
- **Flag Inheritance**: Base, debug, release, and test flag configurations
|
||||
- **Platform-Specific Linking**: Automatic application of OS-specific link flags
|
||||
- **Compiler Caching**: Optional ccache/sccache integration for performance
|
||||
- **Build System Support**: CMake, Ninja, and direct compilation compatibility
|
||||
|
||||
## Complete Platform.json Structure
|
||||
|
||||
The full `platform.json` includes:
|
||||
|
||||
1. **Board Definitions** (8 comprehensive targets):
|
||||
- `native-x64-linux`, `native-x64-macos`, `native-x64-windows`
|
||||
- `native-arm64-linux`, `native-arm64-macos`, `native-arm64-windows`
|
||||
- `native-riscv64-linux`, `native-auto` (intelligent detection)
|
||||
|
||||
2. **Toolchain Configuration**:
|
||||
- Complete ziglang tool mapping (CC, CXX, AR, LD, etc.)
|
||||
- Build flag hierarchies (base, debug, release, test)
|
||||
- Platform-specific link flags for each OS
|
||||
|
||||
3. **Package Management**:
|
||||
- Toolchain dependencies with proper versioning
|
||||
- Optional tool packages (cmake, ninja, caching)
|
||||
- Framework packages for Arduino compatibility
|
||||
|
||||
4. **Development Features**:
|
||||
- Integrated debugger support (GDB for Linux/Windows, LLDB for macOS)
|
||||
- Environment variable customization support
|
||||
- Target compatibility specifications
|
||||
|
||||
## Platform.json Configuration
|
||||
|
||||
The complete platform.json follows Arduino package format with these key sections:
|
||||
|
||||
### Core Metadata
|
||||
```json
|
||||
{
|
||||
"name": "FastLED Native Platform",
|
||||
"title": "Native Host Platform with Zig Toolchain",
|
||||
"description": "Cross-platform native compilation using Zig's bundled Clang",
|
||||
"version": "1.0.0",
|
||||
"packageType": "platform",
|
||||
"spec": {
|
||||
"owner": "fastled",
|
||||
"id": "native-zig",
|
||||
"name": "native-zig"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Framework Definitions
|
||||
```json
|
||||
{
|
||||
"frameworks": {
|
||||
"fastled-stub": {
|
||||
"package": "framework-fastled-stub",
|
||||
"script": "builder/frameworks/fastled-stub.py"
|
||||
},
|
||||
"arduino-stub": {
|
||||
"package": "framework-arduino-stub",
|
||||
"script": "builder/frameworks/arduino-stub.py"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Board Configurations
|
||||
Each board includes complete configuration:
|
||||
- **Hardware specs**: MCU, RAM, Flash, CPU frequency
|
||||
- **Target triple**: Zig compilation target
|
||||
- **Build flags**: Platform-specific preprocessor defines
|
||||
- **Debug tools**: Appropriate debugger (GDB/LLDB) configuration
|
||||
- **Framework support**: Compatible frameworks list
|
||||
|
||||
Example board definition:
|
||||
```json
|
||||
{
|
||||
"native-x64-linux": {
|
||||
"name": "Native x86_64 Linux",
|
||||
"mcu": "x86_64",
|
||||
"fcpu": "3000000000L",
|
||||
"ram": 17179869184,
|
||||
"flash": 1099511627776,
|
||||
"vendor": "Generic",
|
||||
"product": "Native x86_64",
|
||||
"frameworks": ["fastled-stub", "arduino-stub"],
|
||||
"build": {
|
||||
"target": "x86_64-linux-gnu",
|
||||
"toolchain": "ziglang",
|
||||
"cpu": "x86_64",
|
||||
"mcu": "native",
|
||||
"f_cpu": "3000000000L",
|
||||
"extra_flags": [
|
||||
"-DNATIVE_PLATFORM=1",
|
||||
"-DSTUB_PLATFORM=1",
|
||||
"-DFASTLED_NATIVE_X64=1",
|
||||
"-DFASTLED_NATIVE_LINUX=1"
|
||||
]
|
||||
},
|
||||
"upload": { "protocol": "native" },
|
||||
"debug": {
|
||||
"tools": {
|
||||
"gdb": {
|
||||
"server": {
|
||||
"executable": "gdb",
|
||||
"arguments": ["$PROG_PATH"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Toolchain Mapping
|
||||
Direct integration with ziglang commands:
|
||||
```json
|
||||
{
|
||||
"toolchain-ziglang": {
|
||||
"CC": "python -m ziglang cc",
|
||||
"CXX": "python -m ziglang c++",
|
||||
"AR": "python -m ziglang ar",
|
||||
"LD": "python -m ziglang c++",
|
||||
"OBJCOPY": "python -m ziglang objcopy",
|
||||
"NM": "python -m ziglang nm",
|
||||
"STRIP": "python -m ziglang strip",
|
||||
"RANLIB": "python -m ziglang ranlib"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Build Flag Hierarchies
|
||||
```json
|
||||
{
|
||||
"build_flags": {
|
||||
"base": [
|
||||
"-std=gnu++17",
|
||||
"-fpermissive",
|
||||
"-Wall",
|
||||
"-Wextra",
|
||||
"-Wno-deprecated-register",
|
||||
"-Wno-backslash-newline-escape",
|
||||
"-fno-exceptions",
|
||||
"-fno-rtti",
|
||||
"-DSTUB_PLATFORM=1",
|
||||
"-DNATIVE_PLATFORM=1"
|
||||
],
|
||||
"debug": [
|
||||
"-g3",
|
||||
"-Og",
|
||||
"-DDEBUG=1",
|
||||
"-DFASTLED_DEBUG=1"
|
||||
],
|
||||
"release": [
|
||||
"-O3",
|
||||
"-DNDEBUG=1",
|
||||
"-flto"
|
||||
],
|
||||
"test": [
|
||||
"-DFASTLED_UNIT_TEST=1",
|
||||
"-DFASTLED_FORCE_NAMESPACE=1",
|
||||
"-DFASTLED_TESTING=1",
|
||||
"-DFASTLED_USE_PROGMEM=0",
|
||||
"-DARDUINO=10808",
|
||||
"-DFASTLED_USE_STUB_ARDUINO=1",
|
||||
"-DSKETCH_HAS_LOTS_OF_MEMORY=1",
|
||||
"-DFASTLED_STUB_IMPL=1",
|
||||
"-DFASTLED_USE_JSON_UI=1",
|
||||
"-DFASTLED_NO_AUTO_NAMESPACE=1",
|
||||
"-DFASTLED_NO_PINMAP=1",
|
||||
"-DHAS_HARDWARE_PIN_SUPPORT=1",
|
||||
"-DFASTLED_DEBUG_LEVEL=1",
|
||||
"-DFASTLED_NO_ATEXIT=1",
|
||||
"-DDOCTEST_CONFIG_NO_EXCEPTIONS_BUT_WITH_ALL_ASSERTS=1"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Platform-Specific Linking
|
||||
```json
|
||||
{
|
||||
"link_flags": {
|
||||
"base": [],
|
||||
"linux": [
|
||||
"-pthread",
|
||||
"-lm",
|
||||
"-ldl"
|
||||
],
|
||||
"macos": [
|
||||
"-pthread",
|
||||
"-lm"
|
||||
],
|
||||
"windows": [
|
||||
"-mconsole",
|
||||
"-nodefaultlibs",
|
||||
"-unwindlib=libunwind",
|
||||
"-nostdlib++",
|
||||
"-lc++",
|
||||
"-lkernel32",
|
||||
"-luser32",
|
||||
"-lgdi32",
|
||||
"-ladvapi32"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Integration with build_unit.toml
|
||||
|
||||
The `platform.json` is designed to seamlessly integrate with the existing `build_unit.toml` configuration:
|
||||
|
||||
### Toolchain Mapping
|
||||
|
||||
The `[tools]` section in `build_unit.toml` directly maps to the ziglang toolchain defined in `platform.json`:
|
||||
|
||||
- `cpp_compiler = ["python", "-m", "ziglang", "c++"]` → `CXX: "python -m ziglang c++"`
|
||||
- `linker = ["python", "-m", "ziglang", "c++"]` → `LD: "python -m ziglang c++"`
|
||||
- `archiver = ["python", "-m", "ziglang", "ar"]` → `AR: "python -m ziglang ar"`
|
||||
|
||||
### Build Flag Integration
|
||||
|
||||
The platform flags complement the TOML configuration:
|
||||
|
||||
- **Base flags**: Defined in both `platform.json` and `build_unit.toml` for consistency
|
||||
- **Platform-specific flags**: Windows-specific flags from TOML are automatically applied
|
||||
- **Test flags**: Unit test defines from TOML are included in the platform test configuration
|
||||
|
||||
### Target Selection
|
||||
|
||||
The platform supports automatic target detection or explicit target selection:
|
||||
|
||||
```bash
|
||||
# Auto-detect target
|
||||
platformio run -e native-auto
|
||||
|
||||
# Explicit target selection
|
||||
platformio run -e native-x64-linux
|
||||
platformio run -e native-arm64-macos
|
||||
platformio run -e native-x64-windows
|
||||
```
|
||||
|
||||
## Integration Benefits
|
||||
|
||||
### Seamless TOML Integration
|
||||
The design ensures perfect compatibility with existing `build_unit.toml`:
|
||||
- Toolchain commands match exactly: `["python", "-m", "ziglang", "c++"]`
|
||||
- Build flags complement rather than duplicate TOML configuration
|
||||
- Platform-specific flags automatically applied based on detection
|
||||
|
||||
### Enhanced Development Workflow
|
||||
- **Single Command Compilation**: `platformio run -e native-auto`
|
||||
- **Cross-Compilation Support**: Build for different targets from any host
|
||||
- **Testing Integration**: Full unit test support with proper namespace isolation
|
||||
- **Debug Builds**: Integrated debugging with platform-appropriate tools
|
||||
|
||||
### Future-Proof Architecture
|
||||
- **Extensible Design**: Easy addition of new architectures and targets
|
||||
- **WebAssembly Ready**: Structure supports future WASM integration
|
||||
- **Container Builds**: Foundation for Docker/Podman integration
|
||||
- **Static Analysis**: Framework for clang-tidy and analyzer integration
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Compilation
|
||||
|
||||
```bash
|
||||
# Compile for current platform (auto-detect)
|
||||
platformio run -e native-auto
|
||||
|
||||
# Compile for specific platform
|
||||
platformio run -e native-x64-linux
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
```bash
|
||||
# Run unit tests
|
||||
platformio test -e native-auto
|
||||
|
||||
# Run tests with specific build flags
|
||||
platformio test -e native-x64-linux --test-port=native
|
||||
```
|
||||
|
||||
### Cross-Compilation
|
||||
|
||||
```bash
|
||||
# Compile for ARM64 Linux from x86_64
|
||||
platformio run -e native-arm64-linux
|
||||
|
||||
# Compile for Windows from Linux
|
||||
platformio run -e native-x64-windows
|
||||
```
|
||||
|
||||
### Debug Builds
|
||||
|
||||
```bash
|
||||
# Debug build with symbols
|
||||
platformio run -e native-auto --build-type=debug
|
||||
|
||||
# Release build with optimization
|
||||
platformio run -e native-auto --build-type=release
|
||||
```
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
### Custom Board Definition
|
||||
|
||||
```json
|
||||
{
|
||||
"native-custom": {
|
||||
"name": "Custom Native Target",
|
||||
"mcu": "custom",
|
||||
"build": {
|
||||
"target": "x86_64-linux-musl",
|
||||
"extra_flags": [
|
||||
"-DCUSTOM_DEFINE=1",
|
||||
"-static"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
The platform respects environment variables for customization:
|
||||
|
||||
- `ZIG_TARGET`: Override target triple (e.g., `x86_64-linux-musl`)
|
||||
- `ZIG_CPU`: Override CPU type (e.g., `x86_64_v3`)
|
||||
- `FASTLED_NATIVE_FLAGS`: Additional compiler flags
|
||||
|
||||
### Build System Integration
|
||||
|
||||
The platform integrates with multiple build systems:
|
||||
|
||||
- **PlatformIO**: Primary integration with comprehensive board support
|
||||
- **CMake**: Compatible with existing CMake configurations
|
||||
- **Direct Compilation**: Can be used directly with ziglang commands
|
||||
|
||||
## Complete Board Definitions
|
||||
|
||||
The platform.json includes 8 comprehensive board definitions:
|
||||
|
||||
1. **native-x64-linux**: x86_64 Linux with GNU target
|
||||
2. **native-x64-macos**: x86_64 macOS with Apple-specific configuration
|
||||
3. **native-x64-windows**: x86_64 Windows with MinGW compatibility
|
||||
4. **native-arm64-linux**: ARM64 Linux with Cortex-A76 optimization
|
||||
5. **native-arm64-macos**: ARM64 macOS with Apple M1 optimization
|
||||
6. **native-arm64-windows**: ARM64 Windows with appropriate runtime
|
||||
7. **native-riscv64-linux**: RISC-V 64-bit Linux support
|
||||
8. **native-auto**: Automatic target detection and selection
|
||||
|
||||
## Tool Dependencies
|
||||
|
||||
The platform includes comprehensive tool support:
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"python-ziglang": {
|
||||
"type": "compiler",
|
||||
"version": "^0.13.0",
|
||||
"description": "Zig toolchain with bundled Clang/LLVM",
|
||||
"install": { "pip": "ziglang" }
|
||||
},
|
||||
"cmake": {
|
||||
"type": "build-system",
|
||||
"version": "^3.21.0",
|
||||
"optional": true
|
||||
},
|
||||
"ninja": {
|
||||
"type": "build-system",
|
||||
"version": "^1.11.0",
|
||||
"optional": true
|
||||
},
|
||||
"ccache": {
|
||||
"type": "compiler-cache",
|
||||
"version": "^4.0.0",
|
||||
"optional": true
|
||||
},
|
||||
"sccache": {
|
||||
"type": "compiler-cache",
|
||||
"version": "^0.7.0",
|
||||
"optional": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Target Compatibility
|
||||
|
||||
Platform compatibility specifications ensure proper deployment:
|
||||
|
||||
```json
|
||||
{
|
||||
"target_compatibility": {
|
||||
"x86_64-linux-gnu": {
|
||||
"glibc": ">=2.31",
|
||||
"kernel": ">=5.4.0"
|
||||
},
|
||||
"x86_64-macos-none": {
|
||||
"macos": ">=11.0"
|
||||
},
|
||||
"x86_64-windows-gnu": {
|
||||
"windows": ">=10"
|
||||
},
|
||||
"aarch64-linux-gnu": {
|
||||
"glibc": ">=2.31",
|
||||
"kernel": ">=5.4.0"
|
||||
},
|
||||
"aarch64-macos-none": {
|
||||
"macos": ">=11.0"
|
||||
},
|
||||
"aarch64-windows-gnu": {
|
||||
"windows": ">=10"
|
||||
},
|
||||
"riscv64-linux-gnu": {
|
||||
"glibc": ">=2.31",
|
||||
"kernel": ">=5.10.0"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Ziglang not found**: Ensure `ziglang` Python package is installed
|
||||
2. **Target not supported**: Check `zig targets` for available targets
|
||||
3. **Linking errors**: Verify platform-specific link flags in configuration
|
||||
|
||||
### Debug Information
|
||||
|
||||
```bash
|
||||
# Check available targets
|
||||
zig targets
|
||||
|
||||
# Verify toolchain installation
|
||||
python -m ziglang version
|
||||
|
||||
# Test compilation
|
||||
python -m ziglang c++ --version
|
||||
```
|
||||
|
||||
## Implementation Status
|
||||
|
||||
This design is **ready for implementation** and provides:
|
||||
- ✅ **Complete board definitions** for all major native platforms
|
||||
- ✅ **Full toolchain integration** with existing ziglang setup
|
||||
- ✅ **Comprehensive build configurations** for all use cases
|
||||
- ✅ **Arduino package format compliance** for PlatformIO compatibility
|
||||
- ✅ **Debug and development tool integration** for professional development
|
||||
- ✅ **Future-proof extensible architecture** for additional platforms
|
||||
|
||||
The configuration can be deployed alongside the existing build system for gradual validation and testing before full migration.
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
- **WebAssembly Support**: Integration with FastLED WASM compilation
|
||||
- **Static Analysis**: Integration with clang-tidy and static analyzers
|
||||
- **Performance Profiling**: Built-in profiling support for optimization
|
||||
- **Container Builds**: Docker/Podman integration for reproducible builds
|
||||
- **Package Registry**: Publication to Arduino package index for distribution
|
||||
|
||||
## Conclusion
|
||||
|
||||
This platform.json design provides a comprehensive, production-ready configuration for FastLED's native build platform. It seamlessly integrates with the existing `build_unit.toml` while providing the standardized Arduino package format required for broader ecosystem compatibility. The design is thoroughly tested conceptually and ready for implementation with proper validation and testing procedures.
|
||||
Reference in New Issue
Block a user