Obscure Problems and Gotchas

These instructions may not be accurate in the future, so just know this was written on 05/19/2024.

Rant you can skip

Windows is largely an after thought for many programming languages now-a-days. That’s not a complaint, it’s just a fact. The inventors are under no obligation to support Windows and I respect that. So it has been getting harder and harder to experiment with some things, such as Lua on Windows. I don’t care what camp you reside in, I’ve talked about this before, where some people make their operating system their religion. So some people may just say something stupid like “Windows sucks that’s why, use Linux you Win-tard!”, but for the rest of us who use Windows on a daily for personal and work, it doesn’t suck and it still dominates 72% of the market. Microsoft and Windows, like the C programming language, are never going away – so for the haters out there grow up and stop giving people crap for using an OS where you don’t have to stop every five minutes to debug why something isn’t working.

Installing Lua for development on Windows

Before I dive into the instructions I need to point out a few things that I found to be important while diving into this adventure:

• There are too many conflicting and outdated instructions out there, which is irritating, which is why I am providing my own instructions because I think I am going to capture exactly what is needed to be done and not all of the things you can do. Either I am helping or adding to the problem 😝.
• Lua really isn’t designed for Windows, it’s designed for Linux and it shows. Luckily, we can still install it on Windows.
  • If you don’t want to install it on Windows, your alternative method is to just use the Windows Subsystem for Linux (WSL) it works because I tried that too. However, that comes with problems of its own (I will explain below).
• Using a precompiled version of Lua from LuaBinaries is not going to allow you to use a package manager like LuaRocks because it is NOT the development version! I learned this the hard way.
• I don’t recommend using Lua for Windows because it was last released on 2018 – it is not being maintained and the GitHub page says so. No offense to the author, just a fact.
• I do not recommend using the precompiled all in one package for Windows from LuaRocks because the Lua version is behind. Again no offense, just a fact. It is behind by at least 3+ minor versions.

Choose your adventure!

Depending on your needs is what you will do. I do recommend adventure B though.

Adventure A: Use any precompiled version

There are so many to choose from and they all have different Lua versions that are not latest. If you don’t need LuaRocks, then just use the latest version from Lua Binaries.

If you try to use LuaRocks regardless…

You will run into this exact problem. Long story short, the precompiled version is not for development because it does not include the lua.h which is only a part of the source code. This is why you must do it from source or use WSL as the SO answer describes.

Adventure B: Compile Lua locally

I recommend this option honestly because then you have the choice to upgrade whenever you want. You are not beholden-to or limited-to what someone else is precompiling for you. The official instructions for this are actually located as a link on Lua’s website which take you to yet another website, but the instructions are needlessly long in my opinion. I am going to refer to this link at one point below.

1. Create a folder named gcc-lua-install on your C-drive like shown: C:\gcc-lua-install
2. Download the current source release from https://lua.org/download.html for the sake of argument let’s say it’s version lua-5.4.6.tar.gz.
3. Decompress the tarball (*.tar.gz) into the C:\gcc-lua-install path. You should now have:
   • C:\gcc-lua-install\lua-5.4.6
   • For the sake of argument, let the decompressed folder be named lua-5.4.6
4. If you don’t have it installed already, you need MinGW. This is quintessential to compiling the source code. You get that by going to the official website and downloading what is called w64devkit. Follow the GitHub link and download the latest version. For argument’s sake it’s w64devkit-1.23.0.zip
5. Decompress the zip file into the C:\gcc-lua-install path. You should now have:
   • C:\gcc-lua-install\w64devkit
6. Create a new empty batch file named build.cmd in the C:\gcc-lua-install\ path.
7. Navigate to the aforementioned build guide: http://lua-users.org/wiki/BuildingLuaInWindowsForNewbies and view Step 6: Create a Windows Shell Script to Drive the Build
8. Copy the contents of that batch script into the build.cmd file you created above. Don’t close it.
9. Change the line that says set lua_version=5.3.0 to read set lua_version=5.4.6
   • Notice even these instructions are not up to date
10. Change the line that says set compiler_bin_dir=%work_dir%\tdm-gcc\bin to read set compiler_bin_dir=%work_dir%\w64devkit\bin
    • We are not using tdm-gcc, we are using mingw, hence the change
11. Open up your shell of choice as Administrator just to avoid any issues. This can be your standard Windows CMD or my personal favorite cmder.
12. In your shell, navigate to C:\gcc-lua-install\
13. Execute the build.cmd
14. You will see a ton of output, but when it’s finished you know it worked when in the C:\gcc-lua-install\ path you find a new folder named lua which is your compiled version of 5.4.6.

This next part is a matter of preference

At this point you are nearly complete. I am going to give my recommendation on how to handle it, but it’s purely up to you. You need to register the Lua path in the windows PATH variable. Especially, if you want to use LuaRocks.

1. Copy the compiled Lua folder to C:\Lua\lua-5.4.6
2. Register the base path into the Windows system PATH variable: C:\Lua\lua-5.4.6
3. Register the bin path into the Windows system PATH variable: C:\Lua\lua-5.4.6\bin
4. If you plan on using LuaRocks, then go to the LuaRocks GitHub and download the latest version.
   • For argument’s sake it’s going to be luarocks-3.11.0-windows-64.zip (luarocks.exe stand-alone Windows 64-bit binary)
5. Decompress the luarocks files directly into C:\Lua\lua-5.4.6\bin
   • My reasoning for doing this is, when will they be used separately?
6. Before this can be called finished – it’s important to let Lua know where packages are going to be stored, so the instructions for that are here: https://github.com/luarocks/luarocks/wiki/Using-LuaRocks
   • The short version is, you run the luarocks path --bin command to see what it suggests you change for your OS
   • Caution, the output is on multiple lines, I don’t recommend taking that and just running it because it can mess up your current PATH variable. I recommend doing this by hand.
   • Update your Windows system PATH variable to include what is missing based on what is outputted by the command. Should just be one more directory.
   • Add two more variables named LUA_PATH and LUA_CPATH – use the values provided by the output of the command respectively. Make sure the values are all on a single line!
7. Now you are ready to download packages from LuaRocks and use them with your Lua development.

Adventure C: Using WSL to avoid all the hassle

Like so many articles have suggested, after getting errors from LuaRocks about not finding a lua.h header file, some people just give up and turn to WSL. That’s totally fine! I did too! I had to ask a friend who is far more proficient with Linux and C/C++ to help me even get Adventure B to work! It all depends on how you want to work.

1. I am not going to describe how to install the WSL, tons of instructions on how to do that. If you are running Docker, you already have it more than likely. Again, I recommend Ubuntu for your distro.
2. Literally all you need to do is run the following commands in Bash as indicated by this SO answer: https://stackoverflow.com/questions/60761358/how-to-install-luarocks-for-windows-10

sudo apt install lua5.3 liblua5.3-0 liblua5.3-dev
sudo apt install luarocks

Notice several things about those commands:

• You are installing lua
• You are installing a lua dev version
• You are install luarocks
• The lua version is limited by what is available to you from your Linux distro’s repository by OS version. This website demonstrates the point: https://repology.org/project/lua/versions
  • At the time of writing this, the latest version available for Ubuntu 22.04 was lua 5.4.4
  • Once again pointing out that it’s older. Meaning again, you are at the whim of whoever is making these packages

How do I reference my project files in my Windows installation from WSL?

Final tip, your files probably live in Windows and you are just using WSL to get Lua to work properly. Therefore, you need a way to point to those files. WSL has a handy mounting mechanism that automatically mounts to your drives. At the very least the C drive. You access your files like so: root@YourMachineName:/mnt/c/Dev/yourGitRepository#

References and credit

• Thank you to my friend Mark who read through all of the instructions on how to install Lua on Windows and worked with me to reproduce what he did seamlessly. The instructions really were linked right on the Lua site, but I got flustered the moment I needed to compile something with gcc on my Windows local because historically I could never get that to work. I am glad this isn’t a mystery anymore.
• https://lua.org/start.html
• https://luabinaries.sourceforge.net/#installation
• https://luarocks.github.io/luarocks/releases/
• http://lua-users.org/wiki/BuildingLuaInWindowsForNewbies
• https://www.mingw-w64.org/downloads/#w64devkit
• https://stackoverflow.com/questions/67063417/lua-5-3-is-installed-but-i-cant-locate-the-correct-lua-h
• https://stackoverflow.com/questions/60761358/how-to-install-luarocks-for-windows-10
• https://lua.org/pil/contents.html Programming in Lua first edition ebook