hakorune/docs/guides/build/windows-distribution.md

🪟 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)

# 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

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

# From WSL or Linux
mkdir -p dist/my-nyash-app/plugins

# Or from Windows
mkdir dist\my-nyash-app\plugins

2. Copy Main Executable

cp target/x86_64-pc-windows-msvc/release/nyash.exe dist/my-nyash-app/

3. Create Minimal nyash.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

# 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

cp your_app.hako dist/my-nyash-app/app.hako

6. Create Run Script (Optional)

Create run.bat:

@echo off
nyash.exe app.hako %*

🚀 Real-World Example

Here's the exact process used on 2025-08-29:

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

🎯 Testing Your Distribution

Basic Test Program

Create test.hako:

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

:: Basic run
nyash.exe test.hako

:: With verbose output
nyash.exe --verbose test.hako

:: Check plugin loading
set NYASH_CLI_VERBOSE=1
nyash.exe test.hako

📝 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:

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:

# 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

[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.hako"; DestDir: "{app}"
Source: "plugins\*.dll"; DestDir: "{app}\plugins"

[Icons]
Name: "{group}\My Nyash App"; Filename: "{app}\nyash.exe"; Parameters: "app.hako"

Using zip for Simple Distribution

# 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
• Plugin Development
• Build Overview