Complete Lua 5.4 + LuaRocks + Native Compilation Setup on Windows

INSTALL.md

Complete Lua 5.4 + LuaRocks + Native Compilation Setup

A comprehensive guide to setting up a complete Lua development environment on Windows with native compilation support for LuaRocks packages.

The Problem

Setting up Lua development on Windows with native compilation capabilities is notoriously complex. You need:

• Working Lua interpreter
• LuaRocks package manager
• Native compiler (MinGW-w64) for compiling Lua rocks with C extensions
• Proper environment configuration

This guide walks through the complete setup process and common pitfalls.

Prerequisites

• Windows 10/11
• Administrator privileges (for some installations)
• PowerShell

Step 1: Install Lua 5.4.2

1. Download Tools Executable

   • Go to LuaBinaries - Tools Executables
   • Download lua-5.4.2_Win64_bin.zip

2. Download Static Windows Libraries

   • Go to LuaBinaries - Windows Libraries - Static
   • Download lua-5.4.2_Win64_mingw6_lib.zip

3. Extract and Install

   # Create Lua directory
   mkdir C:\Lua54

   Extract both zips to C:\Lua54\, you should have: lua54.exe, lua54.dll, luac54.exe, liblua54.a and an include\ folder

   # Rename lua54.exe to lua.exe for convenience
   Rename-Item C:\Lua54\lua54.exe lua.exe
   
   # Rename luac54.exe to luac.exe for convenience
   Rename-Item C:\Lua54\luac54.exe luac.exe

4. Add to PATH

   Add C:\Lua54 to your system PATH environment variable.

5. Verify Installation

   lua -v
   # Should output: Lua 5.4.2  Copyright (C) 1994-2020 Lua.org, PUC-Rio

Step 2: Install MSYS2 and MinGW-w64

LuaRocks needs a native compiler for packages with C extensions.

1. Install MSYS2

   • Download from msys2.org
   • Run installer with default settings
   • Install to C:\msys64

2. Install MinGW-w64 Toolchain

   # In MSYS2 terminal
   pacman -S mingw-w64-ucrt-x86_64-gcc

3. Add MinGW to Windows PATH

   Add C:\msys64\ucrt64\bin to your system PATH environment variable.

4. Verify Compiler

   gcc --version
   # Should show gcc version information

Step 3: Install LuaRocks

1. Download LuaRocks for Windows

   • Go to LuaRocks releases
   • Download luarocks-3.x.x-windows-64.zip

2. Extract and Install

   Extract to C:\Lua54, luarocks.exe should be in C:\Lua54\

3. Verify LuaRocks

   luarocks --version
   # Should show LuaRocks version information

Step 4: Configure Environment Variables

Set up the complete environment for Lua development:

1. Apply LuaRocks Environment

   Add the following to your users environment variables:

   • Add %APPDATA%\luarocks\bin to PATH
   • Set LUA_PATH and LUA_CPATH environment variables from luarocks path output

Step 5: Test Complete Installation

1. Test Basic Lua

   lua -e "print('Hello, Lua!')"

2. Test LuaRocks

   luarocks list

3. Test Native Compilation

   # Try installing a package that requires compilation
   luarocks install luafilesystem

   If successful, you'll see compilation output like:

   x86_64-w64-mingw32-gcc -O2 -c -o src/lfs.o -IC:\Lua54/include src/lfs.c

4. Test Installed Package

   lua -e "require('lfs'); print('LFS loaded successfully')"

Directory Structure After Setup

C:\Lua54\
├── lua.exe           # Lua interpreter
├── luac54.exe        # Lua compiler
├── lua54.dll         # Lua library
├── liblua54.a        # Static library for compilation
├── luarocks.exe      # LuaRocks package manager
└── include\          # Lua header files (if included)

C:\msys64\
├── ucrt64\bin\      # MinGW-w64 compiler tools
│   ├── gcc.exe
│   ├── x86_64-w64-mingw32-gcc.exe
│   └── ...
└── ...

# User directories
%APPDATA%\luarocks\
├── bin\              # Installed Lua scripts
├── lib\              # Installed Lua libraries
└── ...

Tips

1. Install MSYS2 First: Set up the compiler environment before LuaRocks
2. Check PATH Order: Ensure your Lua installation comes before any other Lua in PATH
3. Verify Each Step: Test each component individually before proceeding
4. Use PowerShell: It handles path escaping better than Command Prompt

Environment Variables Summary

After complete setup, you should have:

# PATH should include:
C:\Lua54
C:\msys64\ucrt64\bin
%APPDATA%\luarocks\bin

# LUA_PATH and LUA_CPATH should be set according to:
luarocks path

---

This setup provides a complete Lua 5.4 development environment on Windows with native compilation support for LuaRocks packages. The key is getting all the components properly configured and in the right order in your PATH.