This guide will go through the FULL process of installing Lua + MinGW + Luarocks on native Windows. This guide is for those who want to use Lua on Windows without WSL and want everything to work well. By the way, it would be greatly appreciated if anyone wants to make a script that does all of this.
I am only targeting Windows 10/11 in this tutorial, specifically ucrt. If you are using Windows 10/11, ignore this. If you use a different version, you will probably be using msvcrt, so you can skip the steps where I switch Luarocks to ucrt.
You could use MSVC, but most luarocks packages assume MinGW, so it's better to use it. If you already have a MinGW installation, you can skip this step, but we will be installing LLVM-MinGW because it also includes a bunch of other cool utilities like make, so there is more package compatibility. Another great choice is w64devkit, which has even more preinstalled programmes.
- Download the latest release of LLVM-MinGW (or any other MinGW); for this tutorial, I will be using LLVM-MinGW, which you can find releases here. Match the arch you are using, and unless you know what you are doing, use
ucrt. - Extract the downloaded archive to a location; for this tutorial, I will be using the path
C:\Program Files\LLVM - (Optional) Delete all files and folders in the extracted directory that are not your target architecture. I am deleting everything but the executables without any specific architecture and the files with the x86_64 architecture. For example, if I am using x86_64, I will remove aarch64-w64-mingw32, armv7-w64-mingw32, i686-w64-mingw32, and then go into
binand remove all coreponding executables as well. This step is to save space but is not necessary. - (VERY OPTIONAL) If you are using LLVM-MinGW, I like to make a hard link from
mingw32-make(included inLLVM-MinGW) withmakeso I can usemake`` on the command line. The command to do this for me oncmd.exe` would be
mklink "C:\Program Files\LLVM\bin\make.exe" "C:\Program Files\LLVM\bin\mingw32-make.exe"and for Powershell users it would be
New-Item -ItemType SymbolicLink -Path "C:\Program Files\LLVM\bin\make.exe" -Target "C:\Program Files\LLVM\bin\mingw32-make.exe"- Add the
bindirectory of the extracted directory to your PATH. You can do this by searching for "Environment Variables" in the start menu and then clicking "Environment Variables" in the window that pops up. Then, find the Path variable in the "System Variables" section and click "Edit". Then click "New" and paste the path to thebindirectory of the extracted directory. For me, this isC:\Program Files\LLVM\bin. Then click "OK" on all the windows to close them.
Restart your terminal, and do gcc --version to verify that it is working, after you are ready to install lua!
We are going to be compiling lua, and creating a wlua.exe which is a special version of lua that lets us use lua modules (like yue) that use windows GUI controls. If you don't need this, you can skip the wlua part of this tutorial.
- Download the whichever version of of Lua from the Lua website. I will use the latest, which for me is lua 5.4.6.
- Extract the downloaded archive to a temporary location, I will just do this into my
Downloadsdirectory. We will place it into the final installation place after we compile it. - Open a terminal, and navigate to the extracted directory. Before we can compile lua we need to make a small fix in the Makefile because it does not expect a path to have spaces in it. Open the
Makefilein a text editor (I will use notepad, so you can just donotepad Makefile), and anywhere you see$(MAKE)replace it with"$(MAKE)". Save the file and close the text editor. - Run
make mingwin the terminal. This will compile lua for us. After it is done, we will have alua.exein thesrcdirectory, alongsideluac.exe,lua54.dll, andliblua.a. - Wherever you want to install Lua, create 3 directories,
bin,libandinclude. For this tutorial, I will be usingC:\Program Files\Lua. Copylua.exeandluac.exeto thebindirectory,lua54.dllto thelibdirectory, andliblua.ato thelibdirectory. Then, copy the fileslua.h,lualib.h,lauxlib.h,luaconf.h, andlua.hppinto theincludedirectory. You should now have a directory structure that looks something like this:
your lua installation dir:
bin:
- lua.exe
- luac.exe
lib:
- lua54.dll
- liblua.a
include:
- lua.h
- lualib.h
- lauxlib.h
- luaconf.h
- lua.hpp- Add the
binandlibdirectories to your PATH. You need thelibdirectory so that yourlua.execan still work by finding thelua54.dll
Creating wlua is a bit more complicated.
First, open up src/lua.c in a text editor, and add this line after #include <signal.h>
#define WIN32_LEAN_AND_MEAN
#include <windows.h>Scroll down to where you see static void l_message (const char *pname, const char *msg), and replace the entire function with this:
static void l_message (const char *pname, const char *msg) {
char buffer[1024] = {0};
strncpy(buffer, msg, 1024);
pname = pname ? pname : "Error";
MessageBox(NULL, buffer, pname, MB_OK | MB_ICONERROR);
}This will make it so any errors will be displayed in a message box instead of the console (which isn't visible in wlua).
Finally at the end of the file, add this line:
int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine, int nCmdShow) {
return main(__argc, __argv);
}Libraries like yue rely on windows GUI components which are only available to be used in an executable if a "manifest" allows it. When a manifest is not defined you would get an error such as the specified module could not be found. We can use this manifest with our project, put it in a file named wlua.manifest or something:
<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
<assembly xmlns='urn:schemas-microsoft-com:asm.v1' manifestVersion='1.0'>
<compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
<application>
<!-- Windows 10 -->
<supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}"/>
<!-- Windows 8.1 -->
<supportedOS Id="{1f676c76-80e1-4239-95bb-83d0f6d0da78}"/>
<!-- Windows 8 -->
<supportedOS Id="{4a2f28e3-53b9-4441-ba9c-d69d4a4a6e38}"/>
<!-- Windows 7 -->
<supportedOS Id="{35138b9a-5d96-4fbd-8e2d-a2440225f93a}"/>
<!-- Windows Vista -->
<supportedOS Id="{e2011457-1546-43c5-a5fe-008deee3d3f0}"/>
</application>
</compatibility>
<dependency>
<dependentAssembly>
<!-- Visual styles -->
<assemblyIdentity type="win32"
name="Microsoft.Windows.Common-Controls"
version="6.0.0.0"
processorArchitecture="*"
publicKeyToken="6595b64144ccf1df"
language="*"/>
</dependentAssembly>
</dependency>
</assembly>Then, create a file called wlua.rc with the following contents:
// this is a UTF-8 file
#pragma code_page(65001)
1 24 "wlua.manifest"Now we need to compile this .rc file into a .o file. We can do this with windres which is included in MinGW. In your terminal run
windres wlua.rc -O coff -o resources.oNow we can compile wlua. In your terminal, you can run
make mingwin order to recompile lua.c and remake a lua54.dll, but now you must delete the built lua.exe as we will be creating a new one that uses our resources. You can run
gcc resources.o src/lua.o -o wlua.exe src/lua54.dll -mwindowsWhich will create a wlua.exe that you can move to your bin directory.
Restart your terminal, and test all this out by doing
lua -e "print(_VERSION)"to test regular lua, and use
wlua -e "error(_VERSION)"to test wlua (which should display an error message in a message box).
As of the latest commits to Luarocks, Windows support is pretty good! We only need minor changes to our configurations to make it work.
- Download the development version of luarocks from the luarocks github. You can do this by clicking the green "Code" button and then "Download ZIP". Extract the downloaded archive to a temporary location, I will just do this into my
Downloadsdirectory. - Open that directory in your terminal, and luarocks offers a nice
install.batto streamline the installation process. You can runinstall.bat /?to see all the options, but for our use case, we just need 2 flags,/MWwhich makes luarocks use MinGW, and/Pto specify our installation location (by default, it installs toC:\Program Files (x86)\Luarocks, which if you are alright with, you can omit this flag). For me, I will run
./install.bat /MW /P "C:\Program Files\Luarocks"This will automatically run thorugh the process, find your lua installation, and handle everything! After installation is done, it will show a "summary" with a bunch of paths you need to add to your environment variables.
| ❗ This is very important ❗ |
|---|
In your LUA_PATH and LUA_CPATH env vars, make sure you also do not forget to have your ?.lua;?/init.lua and ?.dll entries! If these are not present, you wont be able to load modules in the same directory as yourself! |
Now, navigate to where you installed luarocks, there should be a file called config-<lua.version>.lua (so for me it would be config-5.4.lua). Open this file in your text editor and verify that the paths are correct. If you are using ucrt (you didn't download the msvcrt version of MinGW), then you will need to change the MSVCRT variable in the variables table to be ucrt. This will fix any modules installed with luarocks. Also, if any of your paths have spaces in them, you will need to quote them. I created this nice function to do it for me
local function q(x) return '"'..x..'"' end
variables = {
CC = q[[C:\Program Files\LLVM\bin\gcc.exe]],
}etc, you can do it howveer you like!
Now, you can test luarocks by restarting your terminal and running
luarocks install luafilesystemIf it installs without any errors, then you are good to go! You can test it in lua by running the lua repl with lua and then running
> lfs = require "lfs"
> print(lfs._VERSION)If that all works, then you are good to go! You have a fully working lua environment on Windows!
...
DUDE YOU'RE A LIVESAVER!!!!
thank you so frickin much! I was digging through massive rabbit holes to figure out how to install luarocks. now it works like a charm! big W for ya!