# 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.