docs: 包括的なビルドガイドを追加

- docs/guides/build/README.md - すべてのビルドパターンを網羅 - docs/guides/build/cross-platform.md - クロスプラットフォーム開発ガイド - docs/guides/build/windows-distribution.md - Windows配布版作成の詳細手順 - docs/guides/build/aot-compilation.md - AOTネイティブコンパイルガイド - CLAUDE.mdにビルドガイドへのリンクを追加 - cargo-xwinでのWindows向けビルド方法を文書化 - プラグインの自動拡張子変換機能（ChatGPT5実装）を説明
2025-08-29 23:37:49 +09:00
parent 8e58942726
commit cdb75dfac1
5 changed files with 1172 additions and 1 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -74,6 +74,7 @@ Notes:
 - **実行バックエンド完全ガイド**: [docs/reference/architecture/execution-backends.md](docs/reference/architecture/execution-backends.md) 
  - インタープリター（開発・デバッグ）/ VM（高速実行）/ WASM（Web配布）
  - ⚡ **ベンチマーク機能**: `--benchmark` で3バックエンド性能比較（13.5倍実行高速化実証済み！）
+- **ビルド方法完全ガイド**: [docs/guides/build/](docs/guides/build/) - プラットフォーム別ビルド手順

 ### 🐧 Linux/WSL版
 ```bash
@ -97,10 +98,16 @@ cargo build --release -j32
 cargo install cargo-xwin
 cargo xwin build --target x86_64-pc-windows-msvc --release

-# 生成された実行ファイル (916KB)
+# 生成された実行ファイル (4.1MB)
 target/x86_64-pc-windows-msvc/release/nyash.exe
 ```

+### 📚 完全ビルドガイド
+- **🏗️ [ビルドパターン総合ガイド](docs/guides/build/)** - すべてのビルド方法を網羅
+  - 📦 [Windows配布版作成ガイド](docs/guides/build/windows-distribution.md) - 実践的な配布パッケージ作成
+  - 🌍 [クロスプラットフォーム開発](docs/guides/build/cross-platform.md) - Write Once, Run Everywhere
+  - 🔌 プラグインのマルチプラットフォームビルド
+
 ### 🌐 WebAssembly版（2種類あるので注意！）

 #### 1️⃣ **Rust→WASM（ブラウザでNyashインタープリター実行）**
--- a/docs/guides/build/README.md
+++ b/docs/guides/build/README.md
@ -0,0 +1,289 @@
+# 🏗️ Nyash Build Guide - Complete Build Patterns
+
+Everything you need to know about building Nyash for different platforms and configurations.
+
+## 📚 Table of Contents
+
+1. [Quick Start](#quick-start)
+2. [Build Patterns Overview](#build-patterns-overview)
+3. [Platform-Specific Builds](#platform-specific-builds)
+4. [Plugin Development](#plugin-development)
+5. [Distribution Packages](#distribution-packages)
+6. [Troubleshooting](#troubleshooting)
+
+## 🚀 Quick Start
+
+### Basic Build (Linux/WSL)
+```bash
+# Standard build
+cargo build --release -j32
+
+# Run
+./target/release/nyash program.nyash
+```
+
+### Windows Cross-Compile from WSL
+```bash
+# Install cargo-xwin
+cargo install cargo-xwin
+
+# Build for Windows
+cargo xwin build --target x86_64-pc-windows-msvc --release
+```
+
+## 📊 Build Patterns Overview
+
+| Pattern | Command | Output | Use Case |
+|---------|---------|--------|----------|
+| **Standard** | `cargo build --release` | Linux/macOS binary | Local development |
+| **Windows Cross** | `cargo xwin build --target x86_64-pc-windows-msvc` | Windows .exe | Windows distribution |
+| **WebAssembly** | `wasm-pack build --target web` | .wasm + JS | Browser deployment |
+| **AOT Native** | `./tools/build_aot.sh program.nyash` | Standalone executable | High-performance deployment |
+| **Plugins** | `cargo build --release` (in plugin dir) | .so/.dll/.dylib | Extending Nyash |
+
+## 🖥️ Platform-Specific Builds
+
+### 🐧 Linux/WSL Build
+
+Standard Rust build process:
+
+```bash
+# Debug build
+cargo build
+
+# Release build (recommended)
+cargo build --release -j32
+
+# With specific features
+cargo build --release --features cranelift-jit
+```
+
+### 🪟 Windows Build
+
+#### Prerequisites (Native Windows)
+- Rust MSVC toolchain (host = x86_64-pc-windows-msvc)
+- Visual Studio Build Tools (C++ デスクトップ開発)
+- LLVM/clang (AOTリンクに推奨)
+- PowerShell 実行許可（`-ExecutionPolicy Bypass`で一時回避可）
+
+#### Option 1: Cross-compile from Linux/WSL (Recommended)
+
+```bash
+# One-time setup
+cargo install cargo-xwin
+
+# Build Windows binary
+cargo xwin build --target x86_64-pc-windows-msvc --release
+
+# Output: target/x86_64-pc-windows-msvc/release/nyash.exe
+```
+
+#### Option 2: Native Windows Build
+
+Requirements:
+- Rust with MSVC toolchain
+- Visual Studio Build Tools (C++ Desktop Development)
+- LLVM/clang (optional, for AOT)
+
+```bash
+# On Windows
+cargo build --release
+```
+
+#### AOT on Windows (Native EXE)
+```powershell
+# Requires Cranelift + (clang または MSYS2/WSL の bash+cc)
+cargo build --release --features cranelift-jit
+powershell -ExecutionPolicy Bypass -File tools\build_aot.ps1 -Input examples\aot_min_string_len.nyash -Out app.exe
+./app.exe
+```
+
+Notes:
+- EXEはまず実行ファイルと同じフォルダの `nyash.toml` を探します。なければカレントディレクトリを参照します。
+- 追加ログは `-v` もしくは `set NYASH_CLI_VERBOSE=1` で表示。
+- プラグインの依存DLLがある場合は、各プラグインDLLと同じフォルダに配置するか、`PATH` に追加してください。
+
+### 🌐 WebAssembly Build
+
+Two types of WASM builds:
+
+#### 1. Nyash Interpreter in Browser
+```bash
+# Build Nyash itself as WASM
+wasm-pack build --target web
+
+# Files generated in pkg/
+# - nyash_rust_bg.wasm
+# - nyash_rust.js
+# - nyash_rust.d.ts
+```
+
+#### 2. Compile Nyash Code to WASM
+```bash
+# Compile .nyash to .wat (WebAssembly Text)
+./target/release/nyash --compile-wasm program.nyash -o output.wat
+
+# Convert to binary WASM (requires wabt)
+wat2wasm output.wat -o output.wasm
+```
+
+### 🚀 AOT (Ahead-of-Time) Native Compilation
+
+Compile Nyash programs to standalone native executables:
+
+#### Linux/WSL
+```bash
+# Build with Cranelift support
+cargo build --release --features cranelift-jit
+
+# Compile to native
+./tools/build_aot.sh program.nyash -o app
+./app  # Standalone executable!
+```
+
+#### Windows
+```powershell
+# From PowerShell
+cargo build --release --features cranelift-jit
+powershell -ExecutionPolicy Bypass -File tools\build_aot.ps1 -Input program.nyash -Out app.exe
+.\app.exe
+```
+
+## 🔌 Plugin Development
+
+### Building Plugins
+
+Plugins must be built for each target platform:
+
+#### Linux Plugin (.so)
+```bash
+cd plugins/nyash-example-plugin
+cargo build --release
+# Output: target/release/libnyash_example_plugin.so
+```
+
+#### Windows Plugin (.dll)
+```bash
+# From WSL
+cd plugins/nyash-example-plugin
+cargo xwin build --target x86_64-pc-windows-msvc --release
+# Output: target/x86_64-pc-windows-msvc/release/nyash_example_plugin.dll
+```
+
+#### macOS Plugin (.dylib)
+```bash
+cd plugins/nyash-example-plugin
+cargo build --release
+# Output: target/release/libnyash_example_plugin.dylib
+```
+
+### Plugin Naming Convention
+
+**Important**: Windows removes the `lib` prefix automatically:
+- Linux/macOS: `libnyash_example_plugin.so/dylib`
+- Windows: `nyash_example_plugin.dll`
+
+The plugin loader handles this automatically with platform-agnostic configuration.
+
+## 📦 Distribution Packages
+
+### Creating a Windows Distribution
+
+Perfect for sharing Nyash applications:
+
+```bash
+# 1. Build main executable
+cargo xwin build --target x86_64-pc-windows-msvc --release
+
+# 2. Build plugins
+for plugin in filebox array map string integer; do
+  (cd plugins/nyash-$plugin-plugin && \
+   cargo xwin build --target x86_64-pc-windows-msvc --release)
+done
+
+# 3. Create distribution structure
+mkdir -p dist/plugins
+cp target/x86_64-pc-windows-msvc/release/nyash.exe dist/
+cp nyash.toml dist/
+
+# 4. Copy plugin DLLs
+cp plugins/*/target/x86_64-pc-windows-msvc/release/*.dll dist/plugins/
+
+# 5. Add your .nyash files
+cp your_app.nyash dist/
+```
+
+**Distribution structure:**
+```
+dist/
+├── nyash.exe
+├── nyash.toml
+├── your_app.nyash
+└── plugins/
+    ├── nyash_filebox_plugin.dll
+    ├── nyash_array_plugin.dll
+    └── ...
+```
+
+### Platform-Agnostic Configuration
+
+Use `.so` extensions in `nyash.toml` - they work on all platforms:
+
+```toml
+[plugin_paths]
+search_paths = ["./plugins"]
+
+[libraries]
+[libraries."libnyash_filebox_plugin.so"]
+boxes = ["FileBox"]
+path = "libnyash_filebox_plugin.so"  # Works on Windows/Linux/macOS!
+```
+
+The plugin loader automatically:
+- Converts `.so` → `.dll` (Windows) or `.dylib` (macOS)
+- Tries with/without `lib` prefix on Windows
+- Searches in configured paths
+
+## 🔧 Build Optimization
+
+### Performance Builds
+```bash
+# Maximum optimization
+RUSTFLAGS="-C target-cpu=native" cargo build --release
+
+# Link-time optimization
+CARGO_PROFILE_RELEASE_LTO=true cargo build --release
+```
+
+### Size Optimization
+```bash
+# Smaller binary
+cargo build --release --profile=min-size
+
+# Strip symbols (Linux/macOS)
+strip target/release/nyash
+```
+
+## ❓ Troubleshooting
+
+### Common Issues
+
+#### "LoadLibraryExW failed" on Windows
+- Ensure plugins are built for Windows (`cargo xwin build`)
+- Check that DLLs are in the `plugins/` directory
+- Verify `nyash.toml` has correct `plugin_paths`
+
+#### Cross-compilation fails
+- Install `cargo-xwin`: `cargo install cargo-xwin`
+- For mingw target: `sudo apt install mingw-w64`
+
+#### WASM build errors
+- Install wasm-pack: `curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh`
+- Check Rust target: `rustup target add wasm32-unknown-unknown`
+
+## 📚 Related Documentation
+
+- [Cross-Platform Development](cross-platform.md)
+- [Plugin Development Guide](../../reference/plugin-system/)
+- [AOT Compilation Details](aot-compilation.md)
+- [Performance Tuning](../../reference/performance/)
--- a/docs/guides/build/aot-compilation.md
+++ b/docs/guides/build/aot-compilation.md
@ -0,0 +1,280 @@
+# 🚀 AOT (Ahead-of-Time) Compilation Guide
+
+Transform your Nyash programs into standalone native executables!
+
+## 📌 What is AOT?
+
+AOT compilation converts Nyash programs directly to native machine code, producing standalone executables that:
+- Run without the Nyash runtime
+- Start instantly (no JIT compilation)
+- Achieve maximum performance
+- Can be distributed as single files
+
+## 🔧 Prerequisites
+
+- Nyash built with Cranelift support: `--features cranelift-jit`
+- C compiler (gcc/clang) for linking
+- nyrt runtime library (automatically built)
+
+## 🏗️ Building AOT Support
+
+```bash
+# Enable Cranelift JIT (required for AOT)
+cargo build --release --features cranelift-jit
+
+# Build the runtime library
+cd crates/nyrt
+cargo build --release
+```
+
+## 📦 Creating Native Executables
+
+### Linux/WSL
+
+Use the provided build script:
+
+```bash
+# Basic usage
+./tools/build_aot.sh program.nyash -o myapp
+
+# Run the native executable
+./myapp
+```
+
+**What happens behind the scenes:**
+1. Nyash compiles your program to object file (.o)
+2. Links with libnyrt.a (runtime support)
+3. Produces standalone executable
+
+### Windows
+
+From PowerShell:
+
+```powershell
+# Build native executable
+powershell -ExecutionPolicy Bypass -File tools\build_aot.ps1 -Input program.nyash -Out myapp.exe
+
+# Run it
+.\myapp.exe
+```
+
+From WSL (cross-compile):
+
+```bash
+# Use the bash script even for Windows targets
+NYASH_TARGET=windows ./tools/build_aot.sh program.nyash -o myapp.exe
+```
+
+## 🎯 AOT Compilation Pipeline
+
+```
+program.nyash
+    ↓
+[Nyash Parser]
+    ↓
+   AST
+    ↓
+[MIR Builder]
+    ↓
+   MIR
+    ↓
+[JIT Compiler - Strict Mode]
+    ↓
+  main.o (Object File)
+    ↓
+[C Linker + libnyrt.a]
+    ↓
+Native Executable
+```
+
+## ⚡ Supported Features
+
+### Currently Supported (Phase 10.10)
+- ✅ Basic arithmetic operations
+- ✅ Function calls (limited)
+- ✅ Integer operations
+- ✅ String operations (read-only)
+- ✅ Control flow (if/else, loops)
+
+### Not Yet Supported
+- ❌ Full plugin system
+- ❌ Dynamic code loading
+- ❌ Some built-in Box methods
+- ❌ Async/await
+- ❌ Exception handling
+
+## 📝 Writing AOT-Compatible Code
+
+### Example: Simple Calculation
+
+```nyash
+// aot_example.nyash
+static box Main {
+    main() {
+        local x = 10
+        local y = 20
+        local result = x + y
+        return result  // Exit code: 30
+    }
+}
+```
+
+### Example: String Length (Plugin-Based)
+
+```nyash
+// Requires NYASH_USE_PLUGIN_BUILTINS=1
+static box Main {
+    main() {
+        local s = "Hello"
+        return s.length()  // Exit code: 5
+    }
+}
+```
+
+## 🔍 Debugging AOT Compilation
+
+### Enable Verbose Output
+
+```bash
+# See what's happening
+NYASH_CLI_VERBOSE=1 ./tools/build_aot.sh program.nyash
+```
+
+### Check JIT Coverage
+
+```bash
+# See which operations are supported
+NYASH_JIT_DUMP=1 ./target/release/nyash --backend vm program.nyash
+```
+
+### Common Issues
+
+#### "Object not generated"
+```
+error: object not generated: target/aot_objects/main.o
+hint: Strict mode forbids fallback. Ensure main() is lowerable under current JIT coverage.
+```
+
+**Solution**: Simplify your program or wait for more JIT coverage.
+
+#### "Unsupported lowering ops"
+```
+[JIT][strict] unsupported lowering ops for main: 3 — failing compile
+```
+
+**Solution**: Check which operations are causing issues:
+- Complex Box method calls
+- Dynamic features
+- Plugin-dependent code
+
+## 🏃 Performance Considerations
+
+### Benchmark Results
+
+| Execution Mode | Time (ny_bench.nyash) | Relative |
+|----------------|----------------------|----------|
+| Interpreter | 110.10ms | 1.0x |
+| VM | 8.14ms | 13.5x |
+| VM + JIT | 5.8ms | 19.0x |
+| **AOT Native** | ~4ms | **~27x** |
+
+### Optimization Flags
+
+```bash
+# Maximum performance
+RUSTFLAGS="-C target-cpu=native" cargo build --release --features cranelift-jit
+
+# Then compile your program
+./tools/build_aot.sh program.nyash -o optimized_app
+```
+
+## 🔌 Plugin Support in AOT
+
+### Static Linking (Future)
+
+The goal is to statically link plugins:
+
+```bash
+# Future syntax (not yet implemented)
+./tools/build_aot.sh program.nyash \
+    --static-plugins filebox,stringbox \
+    -o standalone_app
+```
+
+### Dynamic Plugins (Current)
+
+AOT executables can load plugins if:
+- nyash.toml is present
+- Plugin .so/.dll files are available
+- Paths are correctly configured
+
+## 🛠️ Advanced Usage
+
+### Custom Linker Flags
+
+```bash
+# Modify build_aot.sh or use directly:
+cc main.o \
+   -L crates/nyrt/target/release \
+   -Wl,--whole-archive -lnyrt -Wl,--no-whole-archive \
+   -lpthread -ldl -lm \
+   -O3 -flto \  # Extra optimizations
+   -o myapp
+```
+
+### Embedding Resources
+
+Future feature to embed files in the executable:
+
+```nyash
+// Future syntax
+#[embed("data.json")]
+static DATA: &str
+
+static box Main {
+    main() {
+        local config = JSON.parse(DATA)
+        // ...
+    }
+}
+```
+
+## 📊 AOT vs Other Modes
+
+| Feature | Interpreter | VM | JIT | AOT |
+|---------|------------|----|----|-----|
+| Startup Time | Fast | Fast | Medium | **Instant** |
+| Peak Performance | Slow | Good | Better | **Best** |
+| Memory Usage | Low | Medium | High | **Lowest** |
+| Distribution | Needs Nyash | Needs Nyash | Needs Nyash | **Standalone** |
+| Plugin Support | Full | Full | Full | Limited |
+| Debug Info | Full | Good | Limited | Minimal |
+
+## 🎯 When to Use AOT
+
+**Use AOT when:**
+- Distributing standalone applications
+- Maximum performance is critical
+- Startup time matters
+- Deployment simplicity is important
+
+**Avoid AOT when:**
+- Using dynamic features heavily
+- Requiring full plugin ecosystem
+- Rapid development/debugging
+- Code uses unsupported operations
+
+## 🔮 Future Roadmap
+
+### Phase 10.11+ Plans
+- Full plugin static linking
+- Complete Box method coverage
+- Cross-compilation support
+- Size optimization options
+- Debug symbol control
+
+## 📚 See Also
+
+- [Build Overview](README.md)
+- [JIT Architecture](../../reference/jit/)
+- [Performance Guide](../../reference/performance/)
--- a/docs/guides/build/cross-platform.md
+++ b/docs/guides/build/cross-platform.md
@ -0,0 +1,307 @@
+# 🌍 Cross-Platform Development Guide
+
+How to build and distribute Nyash applications across Windows, Linux, and macOS.
+
+## 🎯 Philosophy: Write Once, Run Everywhere
+
+Nyash achieves true cross-platform compatibility through:
+- **Platform-agnostic configuration** (nyash.toml)
+- **Automatic library resolution** (plugin loader)
+- **Unified plugin system** (C ABI)
+
+## 🔄 Cross-Platform Plugin Loading
+
+### The Magic Behind It
+
+ChatGPT5's `resolve_library_path` implementation in `src/runtime/plugin_loader_v2.rs`:
+
+```rust
+// Automatic extension mapping
+let cur_ext: &str = if cfg!(target_os = "windows") { "dll" } 
+                   else if cfg!(target_os = "macos") { "dylib" } 
+                   else { "so" };
+
+// Windows: try without 'lib' prefix
+if cfg!(target_os = "windows") {
+    if let Some(stripped) = stem.strip_prefix("lib") {
+        // Try nyash_plugin.dll instead of libnyash_plugin.dll
+    }
+}
+```
+
+### Configuration That Works Everywhere
+
+```toml
+# nyash.toml - Same file works on all platforms!
+[libraries."libnyash_filebox_plugin.so"]
+boxes = ["FileBox"]
+path = "libnyash_filebox_plugin.so"  # .so works everywhere!
+```
+
+**Runtime Resolution:**
+- Linux: `libnyash_filebox_plugin.so` ✅
+- Windows: `nyash_filebox_plugin.dll` ✅ (lib prefix removed)
+- macOS: `libnyash_filebox_plugin.dylib` ✅
+
+## 🏗️ Building for Multiple Platforms
+
+### From Linux/WSL (Recommended Hub)
+
+```bash
+# For Linux (native)
+cargo build --release
+
+# For Windows
+cargo xwin build --target x86_64-pc-windows-msvc --release
+
+# For macOS (requires macOS SDK)
+# cargo build --target x86_64-apple-darwin --release
+```
+
+### Build Matrix
+
+| Host OS | Target | Tool | Command |
+|---------|--------|------|---------|
+| Linux/WSL | Linux | cargo | `cargo build --release` |
+| Linux/WSL | Windows | cargo-xwin | `cargo xwin build --target x86_64-pc-windows-msvc` |
+| Windows | Windows | cargo | `cargo build --release` |
+| Windows | Linux | cross | `cross build --target x86_64-unknown-linux-gnu` |
+| macOS | macOS | cargo | `cargo build --release` |
+| macOS | Linux | cross | `cross build --target x86_64-unknown-linux-gnu` |
+
+## 📦 Creating Universal Distributions
+
+### Directory Structure
+```
+nyash-universal/
+├── bin/
+│   ├── linux/
+│   │   └── nyash
+│   ├── windows/
+│   │   └── nyash.exe
+│   └── macos/
+│       └── nyash
+├── plugins/
+│   ├── linux/
+│   │   ├── libnyash_filebox_plugin.so
+│   │   └── ...
+│   ├── windows/
+│   │   ├── nyash_filebox_plugin.dll
+│   │   └── ...
+│   └── macos/
+│       ├── libnyash_filebox_plugin.dylib
+│       └── ...
+├── nyash.toml          # Universal config
+├── examples/
+└── README.md
+```
+
+### Universal Launcher Script
+
+Create `run.sh` (Linux/macOS) and `run.bat` (Windows):
+
+**run.sh:**
+```bash
+#!/bin/bash
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+OS="$(uname -s)"
+
+case "$OS" in
+    Linux*)  BIN="linux/nyash" ;;
+    Darwin*) BIN="macos/nyash" ;;
+    *)       echo "Unsupported OS: $OS"; exit 1 ;;
+esac
+
+export NYASH_PLUGIN_PATH="$SCRIPT_DIR/plugins/$(echo $OS | tr '[:upper:]' '[:lower:]')"
+"$SCRIPT_DIR/bin/$BIN" "$@"
+```
+
+**run.bat:**
+```batch
+@echo off
+set SCRIPT_DIR=%~dp0
+set NYASH_PLUGIN_PATH=%SCRIPT_DIR%plugins\windows
+"%SCRIPT_DIR%bin\windows\nyash.exe" %*
+```
+
+## 🔌 Plugin Compatibility
+
+### Building Plugins for All Platforms
+
+Automated build script (`build_all_plugins.sh`):
+
+```bash
+#!/bin/bash
+PLUGINS="filebox array map string integer net"
+
+for plugin in $PLUGINS; do
+    echo "Building $plugin plugin..."
+    cd "plugins/nyash-$plugin-plugin" || exit 1
+    
+    # Linux
+    cargo build --release
+    cp target/release/lib*.so ../../dist/plugins/linux/
+    
+    # Windows (from WSL)
+    cargo xwin build --target x86_64-pc-windows-msvc --release
+    cp target/x86_64-pc-windows-msvc/release/*.dll ../../dist/plugins/windows/
+    
+    cd ../..
+done
+```
+
+### Plugin ABI Stability
+
+The C ABI ensures plugins work across platforms:
+
+```c
+// Standard C ABI functions (same on all platforms)
+extern "C" {
+    fn nyash_plugin_abi_version() -> u32;
+    fn nyash_plugin_init(host_fns: *const HostFunctions) -> i32;
+    fn nyash_plugin_invoke(params: *const InvokeParams) -> i32;
+    fn nyash_plugin_shutdown();
+}
+```
+
+## 🎯 Testing Cross-Platform Builds
+
+### Test Matrix Script
+
+```bash
+#!/bin/bash
+# test_all_platforms.sh
+
+echo "=== Testing Linux Build ==="
+./target/release/nyash test/cross_platform.nyash
+
+echo "=== Testing Windows Build (Wine) ==="
+wine ./target/x86_64-pc-windows-msvc/release/nyash.exe test/cross_platform.nyash
+
+echo "=== Testing WASM Build ==="
+wasmtime ./target/wasm32-wasi/release/nyash.wasm test/cross_platform.nyash
+```
+
+### Cross-Platform Test Program
+
+```nyash
+// test/cross_platform.nyash
+print("Platform Test Starting...")
+
+// Test basic plugins
+local arr = new ArrayBox()
+arr.push("Cross")
+arr.push("Platform")
+arr.push("Success!")
+print("Array test: " + arr.get(0) + "-" + arr.get(1) + " " + arr.get(2))
+
+// Test file operations (platform-specific paths)
+local file = new FileBox()
+if file {
+    print("FileBox available on this platform")
+}
+
+print("✅ All tests passed!")
+```
+
+## 🚀 CI/CD for Cross-Platform
+
+### GitHub Actions Example
+
+```yaml
+name: Cross-Platform Build
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+          - os: windows-latest
+            target: x86_64-pc-windows-msvc
+          - os: macos-latest
+            target: x86_64-apple-darwin
+    
+    runs-on: ${{ matrix.os }}
+    
+    steps:
+    - uses: actions/checkout@v2
+    
+    - name: Install Rust
+      uses: actions-rs/toolchain@v1
+      with:
+        toolchain: stable
+        target: ${{ matrix.target }}
+    
+    - name: Build
+      run: cargo build --release --target ${{ matrix.target }}
+    
+    - name: Test
+      run: cargo test --release --target ${{ matrix.target }}
+    
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v2
+      with:
+        name: nyash-${{ matrix.target }}
+        path: target/${{ matrix.target }}/release/nyash*
+```
+
+## 💡 Best Practices
+
+### 1. Always Test on Target Platform
+```bash
+# Quick test after cross-compile
+wine ./nyash.exe --version  # Windows binary on Linux
+```
+
+### 2. Use Platform-Agnostic Paths
+```nyash
+// Bad
+local file = new FileBox()
+file.open("C:\\data\\file.txt", "r")  // Windows-specific
+
+// Good
+local file = new FileBox()
+file.open("./data/file.txt", "r")  // Works everywhere
+```
+
+### 3. Handle Platform Differences Gracefully
+```nyash
+box PlatformHelper {
+    static getPlatformName() {
+        // Future: return actual platform
+        return "universal"
+    }
+    
+    static getPathSeparator() {
+        // Future: return platform-specific separator
+        return "/"
+    }
+}
+```
+
+## 🔧 Troubleshooting
+
+### "Can't find plugin" after cross-compile
+- Check file naming (lib prefix on Windows)
+- Verify correct architecture (x86_64 vs ARM)
+- Use `--verbose` flag for detailed logs
+
+### Different behavior across platforms
+- File path separators (`/` vs `\`)
+- Case sensitivity (Linux/macOS vs Windows)
+- Line endings (LF vs CRLF)
+
+### Performance variations
+- Debug vs Release builds
+- Native CPU optimizations
+- Plugin loading overhead
+
+## 📚 References
+
+- [Plugin System Architecture](../../reference/plugin-system/)
+- [Build Configuration](README.md)
+- [Platform-Specific Notes](../../reference/platform-notes.md)
--- a/docs/guides/build/windows-distribution.md
+++ b/docs/guides/build/windows-distribution.md
@ -0,0 +1,288 @@
+# 🪟 Windows Distribution Guide
+
+Step-by-step guide to creating Windows distributions of Nyash applications.
+
+## 📋 Prerequisites
+
+### For Cross-Compilation from Linux/WSL
+- Rust toolchain
+- cargo-xwin: `cargo install cargo-xwin`
+
+### For Native Windows Build
+- Rust (MSVC toolchain)
+- Visual Studio Build Tools (C++ Desktop Development)
+- LLVM/clang (optional, for AOT)
+
+## 🏗️ Building for Windows
+
+### Option 1: Cross-Compile from WSL (Recommended)
+
+```bash
+# One-time setup
+cargo install cargo-xwin
+
+# Build main executable
+cargo xwin build --target x86_64-pc-windows-msvc --release
+
+# Build plugins
+cd plugins/nyash-filebox-plugin
+cargo xwin build --target x86_64-pc-windows-msvc --release
+```
+
+### Option 2: Native Windows Build
+
+```powershell
+# On Windows with MSVC
+cargo build --release
+
+# Plugins
+cd plugins\nyash-filebox-plugin
+cargo build --release
+```
+
+## 📦 Creating a Distribution Package
+
+### Recommended Directory Structure
+
+```
+my-nyash-app/
+├── nyash.exe           # Main executable (4.1MB)
+├── nyash.toml          # Configuration
+├── app.nyash           # Your application
+├── README.txt          # User instructions
+└── plugins/            # Plugin DLLs
+    ├── nyash_array_plugin.dll
+    ├── nyash_filebox_plugin.dll
+    ├── nyash_map_plugin.dll
+    └── ...
+```
+
+### Step-by-Step Creation
+
+#### 1. Create Distribution Directory
+
+```bash
+# From WSL or Linux
+mkdir -p dist/my-nyash-app/plugins
+
+# Or from Windows
+mkdir dist\my-nyash-app\plugins
+```
+
+#### 2. Copy Main Executable
+
+```bash
+cp target/x86_64-pc-windows-msvc/release/nyash.exe dist/my-nyash-app/
+```
+
+#### 3. Create Minimal nyash.toml
+
+```toml
+# dist/my-nyash-app/nyash.toml
+[plugin_paths]
+search_paths = ["./plugins"]
+
+[libraries]
+# Use .so extension - it works on Windows too!
+[libraries."libnyash_filebox_plugin.so"]
+boxes = ["FileBox"]
+path = "libnyash_filebox_plugin.so"
+
+[libraries."libnyash_string_plugin.so"]
+boxes = ["StringBox"]
+path = "libnyash_string_plugin.so"
+
+# Add other plugins as needed...
+```
+
+#### 4. Copy Plugin DLLs
+
+```bash
+# Note: Windows removes 'lib' prefix from plugin names
+cp plugins/nyash-filebox-plugin/target/x86_64-pc-windows-msvc/release/nyash_filebox_plugin.dll dist/my-nyash-app/plugins/
+cp plugins/nyash-array-plugin/target/x86_64-pc-windows-msvc/release/nyash_array_plugin.dll dist/my-nyash-app/plugins/
+# ... repeat for other plugins
+```
+
+#### 5. Add Your Application
+
+```bash
+cp your_app.nyash dist/my-nyash-app/app.nyash
+```
+
+#### 6. Create Run Script (Optional)
+
+Create `run.bat`:
+```batch
+@echo off
+nyash.exe app.nyash %*
+```
+
+## 🚀 Real-World Example
+
+Here's the exact process used on 2025-08-29:
+
+```bash
+# 1. Build everything for Windows
+cargo xwin build --target x86_64-pc-windows-msvc --release -j32
+
+# 2. Build plugins
+for plugin in filebox array map string integer; do
+  (cd plugins/nyash-$plugin-plugin && \
+   cargo xwin build --target x86_64-pc-windows-msvc --release --quiet)
+done
+
+# 3. Create distribution
+mkdir -p /mnt/c/tmp/nyash-windows-dist/plugins
+cp target/x86_64-pc-windows-msvc/release/nyash.exe /mnt/c/tmp/nyash-windows-dist/
+cp nyash.toml /mnt/c/tmp/nyash-windows-dist/  # Modified version
+
+# 4. Copy plugins
+for plugin in filebox array map string integer; do
+  cp plugins/nyash-$plugin-plugin/target/x86_64-pc-windows-msvc/release/nyash_${plugin}_plugin.dll \
+     /mnt/c/tmp/nyash-windows-dist/plugins/
+done
+
+# 5. Test on Windows
+cmd.exe /c "cd C:\tmp\nyash-windows-dist && nyash.exe test.nyash"
+```
+
+## 🎯 Testing Your Distribution
+
+### Basic Test Program
+
+Create `test.nyash`:
+```nyash
+print("=== Testing Nyash Distribution ===")
+
+// Test plugins
+local str = new StringBox()
+local arr = new ArrayBox()
+local map = new MapBox()
+
+arr.push("Distribution")
+arr.push("works!")
+
+map.set("status", "success")
+
+print("Plugins loaded: ✅")
+print("Array test: " + arr.get(0) + " " + arr.get(1))
+print("Map test: " + map.get("status"))
+```
+
+### Running Tests
+
+```batch
+:: Basic run
+nyash.exe test.nyash
+
+:: With verbose output
+nyash.exe --verbose test.nyash
+
+:: Check plugin loading
+set NYASH_CLI_VERBOSE=1
+nyash.exe test.nyash
+```
+
+## 📝 Important Notes
+
+### Plugin Name Differences
+
+| Platform | Library Name | Note |
+|----------|--------------|------|
+| Linux | `libnyash_example_plugin.so` | With 'lib' prefix |
+| Windows | `nyash_example_plugin.dll` | No 'lib' prefix! |
+| macOS | `libnyash_example_plugin.dylib` | With 'lib' prefix |
+
+The plugin loader handles this automatically!
+
+### Path Separators
+
+Use forward slashes in nyash.toml - they work on Windows:
+```toml
+search_paths = ["./plugins"]  # Works on Windows!
+```
+
+### Dependencies
+
+Most Nyash distributions are self-contained. However, some plugins might need:
+- Visual C++ Redistributables (usually already installed)
+- Python DLL (for Python plugin)
+
+## 🔐 Code Signing (Optional)
+
+For distribution without security warnings:
+
+```powershell
+# Sign the executable
+signtool sign /a /t http://timestamp.digicert.com nyash.exe
+
+# Sign all DLLs
+Get-ChildItem -Path plugins -Filter *.dll | ForEach-Object {
+    signtool sign /a /t http://timestamp.digicert.com $_.FullName
+}
+```
+
+## 📦 Creating an Installer
+
+### Using Inno Setup
+
+```ini
+[Setup]
+AppName=My Nyash Application
+AppVersion=1.0
+DefaultDirName={pf}\MyNyashApp
+DefaultGroupName=My Nyash App
+
+[Files]
+Source: "nyash.exe"; DestDir: "{app}"
+Source: "nyash.toml"; DestDir: "{app}"
+Source: "app.nyash"; DestDir: "{app}"
+Source: "plugins\*.dll"; DestDir: "{app}\plugins"
+
+[Icons]
+Name: "{group}\My Nyash App"; Filename: "{app}\nyash.exe"; Parameters: "app.nyash"
+```
+
+### Using zip for Simple Distribution
+
+```bash
+# From WSL/Linux
+cd dist
+zip -r my-nyash-app-windows.zip my-nyash-app/
+
+# Or use 7-Zip on Windows
+7z a my-nyash-app-windows.zip my-nyash-app\
+```
+
+## ✅ Distribution Checklist
+
+- [ ] Build nyash.exe for Windows
+- [ ] Build all required plugin DLLs
+- [ ] Create platform-agnostic nyash.toml
+- [ ] Copy all files to distribution folder
+- [ ] Test on a clean Windows system
+- [ ] Create README with instructions
+- [ ] Package as zip or installer
+- [ ] (Optional) Code sign binaries
+
+## 🆘 Troubleshooting
+
+### "Plugin not found" errors
+1. Check plugin DLL exists in `plugins/` folder
+2. Verify naming (no 'lib' prefix on Windows)
+3. Run with `--verbose` for detailed logs
+
+### Missing DLL errors
+- Install Visual C++ Redistributables
+- Check plugin dependencies with `dumpbin /dependents plugin.dll`
+
+### Performance issues
+- Ensure release build (`--release` flag)
+- Disable Windows Defender real-time scanning for Nyash folder
+
+## 📚 See Also
+
+- [Cross-Platform Guide](cross-platform.md)
+- [Plugin Development](../../reference/plugin-system/)
+- [Build Overview](README.md)