Building Lua In Windows For Newbies

wiki

Introduction

This is a step-by-step tutorial to get up and running with Lua on Microsoft Windows systems by downloading and compiling the sources using only free tools or tools already present on any Windows installation. Very little programming experience is required from the user. This tutorial may also be of some interest to expert Linux users having little knowledge of Windows platforms.

If you are an experienced programmer and find this tutorial too easy or limited, please consult the page BuildingLua, which is far more technical and detailed.

Overview and Prerequisites

Assumptions about the reader:

• Has a general knowledge of the Windows file system and knows how to perform basic operations on it using the OS-provided tools (browse the file system, copy/move a file, rename a file, create a directory, etc.).
• Knows how to download a file from the Internet using a web browser.
• Knows how to install a program in Windows using an installer.
• Knows what a text file is and how to create one using a text editor (Windows Notepad is enough for this tutorial, but the freely available [SciTE] or [TextAdept] could be better choices for a novice programmer).
• Knows what a compressed archive is and how to decompress it.
• Knows what the Windows command shell is and how to bring it up.
• Knows what the Windows executable files search path is and how to add entries to it (this is sometimes referred to as the system path or simply the path and is related to Windows PATH environment variable [1]).

Many of the assumptions above are not strict requirements, because in the following some procedures will be explained in detail, but the reader should not expect too much hand-holding on such subjects.

The tutorial is organized in sequential steps that can be outlined as follows:

• Download a suitable C-compiler (TDM GCC).
• Download Lua source package.
• Download a decompressor for the Lua source package (7-zip).
• Install the compiler.
• Install the decompressor.
• Decompress the archive in a suitable location.
• Configure the compiler in such a way it can find the sources and start the building process (we will use a Windows command shell script to do this).

Important Note: we recommend that you read this page in its entirety before actually beginning with the procedure. Make sure to have understood everything in advance: this could save you some time and troubles later. This procedure is rather foolproof (we hope), but you never know! ;-)

Note: the procedure has been tested, using an account with administrative privileges, on an x86 32 bit machine running Windows XP professional with Service Pack 3 (SP3) installed (Intel Mobile Core 2 Duo T7500 - 2GB RAM). The compiler used is TDM GCC 4.7.1 (32 bit version).

Note: as time goes by some of the links here contained could well become outdated. That's why below we give not only the direct links to packages but also the link to the main pages for the applications involved. This should allow the motivated reader to adapt to the obvious changes (e.g. compensate for future version numbers in the links) browsing the websites by himself, should this page not be updated.

Step by Step Tutorial

Step 1: Download the Compiler (TDM-GCC)

We will use the Windows port of the open source GCC compiler by TDM. The download page is found at [2], while the following is the direct link for the package we need: [3]. Click on the previous link, follow the instructions and wait for the download to complete. The downloaded file should be tdm-gcc-4.7.1-2.exe. It is a ~25MB download, so be sure to have a fast enough Internet connection.

To avoid possible problems, make sure that the downloaded package lies in a directory (folder) whose complete path doesn't contain spaces. If this is not the case, copy or move it in a directory which meets this requirement. All the packages that we'll download should end up in this directory (we will use it as a temporary working directory for the whole tutorial).

For the purpose of this tutorial we will assume you created the following folder as a working directory:

        C:\gcc-lua-install

Copy (or move) the installation package you just downloaded in the working directory, if you didn't download it there in the first place. Now our working directory should have the following content:

        C:\gcc-lua-install\tdm-gcc-4.7.1-2.exe

Step 2: Download Lua Sources

Lua sources download page is [4]. This is the direct dowload link to the latest version at the time of this writing: [5]. Click on the previous link, follow the instructions and wait for the download to complete. Make sure that the file you download lies in the C:\gcc-lua-install directory (or copy/move it there after the download - we won't restate this).

Now we have two files in our working directory:

        C:\gcc-lua-install\tdm-gcc-4.7.1-2.exe

        C:\gcc-lua-install\lua-5.2.2.tar.gz

Step 3: Download a Decompressor (7-Zip) for Lua Sources

Lua sources are packaged in an archive format very common on Linux platforms, but which is unusual on Windows: the TAR-GZ format, as hinted by the .tar.gz double extension of the file. Windows OSes cannot decompress this format natively, so we need a program that can do that. A very good and versatile free compression/decompression program for Windows that can handle TAR-GZ files (and many other compressed formats) is [7-zip].

Since we want to keep the process as simple as possible we won't use the original 7-zip installation package, because this latter modifies the system when it is installed. Instead we will use an alternative "distribution" packaged by [PortableApps.com] and available from the page: [6]. Click on the download link, follow the instructions and wait for the download to complete. Make sure that also this file lies in our working directory.

Now we have three files in our working directory:

        C:\gcc-lua-install\tdm-gcc-4.7.1-2.exe

        C:\gcc-lua-install\lua-5.2.2.tar.gz

        C:\gcc-lua-install\7-ZipPortable_9.20_Rev_2.paf.exe

Step 4: Install the Compiler

Now browse with Windows Explorer, Windows' graphical file manager (this is NOT Internet Explorer!), into our working directory and execute the compiler's installer by double-clicking on tdm-gcc-4.7.1-2.exe. A dialog should appear.

• Uncheck the option Check for updated files on the TDM-GCC server.
• Press the button Create.
• In the edit box that appear specify C:\gcc-lua-install\tdm-gcc as installation directory.
• Press the button Next.
• In the selection tree that appears scroll to the end and uncheck the options Start Menu Items and Add to PATH (this step is not strictly necessary, but it ensures that the compiler installation leaves the system completely clean, besides extracting the files into the directory specified above).
• Press the button Install and wait for the installation to complete.
• When the installer declares the installation successful, press the button Next.
• Press the button Finish (you may read the readme file or not - it is not necessary for our purposes).

The current content of our working directory now should be:

        C:\gcc-lua-install\tdm-gcc-4.7.1-2.exe

        C:\gcc-lua-install\lua-5.2.2.tar.gz

        C:\gcc-lua-install\7-ZipPortable_9.20_Rev_2.paf.exe

        C:\gcc-lua-install\tdm-gcc

with the last item being the subdirectory where the compiler is now installed (note that in Windows Explorer these items will probably be displayed in a different order).

Step 5: Install the Decompressor

Now run the 7-zip portable installer by double-clicking on the file 7-ZipPortable_9.20_Rev_2.paf.exe inside our working directory. A dialog should appear.

• Select English as language (this is not strictly necessary, but otherwise the following instructions may not match the messages in the dialog boxes you'll see).
• Press the button Ok.
• Press the button Next.
• In the edit box that appear specify C:\gcc-lua-install\7zip as destination folder.
• Press the button Install and wait for the installation to complete.
• Press the button Finish.

The current content of our working directory now should be:

        C:\gcc-lua-install\tdm-gcc-4.7.1-2.exe

        C:\gcc-lua-install\lua-5.2.2.tar.gz

        C:\gcc-lua-install\7-ZipPortable_9.20_Rev_2.paf.exe

        C:\gcc-lua-install\tdm-gcc

        C:\gcc-lua-install\7zip

with the last item being the subdirectory where 7-zip is now installed.

Step 6: Unpack Lua Sources using 7-Zip

• Browse into the 7-zip installation directory (i.e. C:\gcc-lua-install\7zip) and double-click on the file 7-ZipPortable.exe. This will execute 7-zip and bring up the program's main window, which vaguely resembles Windows Explorer.
• Using 7-zip window, navigate to our working directory (e.g. you can copy and paste C:\gcc-lua-install in its location bar and press Return).
• Inside 7-zip window, double-click on Lua package file (lua-5.2.2.tar.gz), you should see the "internals" of the package as a single folder called lua-5.2.2.tar.
• Double-click on lua-5.2.2.tar, you should "enter" that folder and see another folder named lua-5.2.2.
• Right-click on lua-5.2.2, a context menu should appear. Select the Copy To... option from that menu. A dialog with a Copy caption should appear.
• Specify our working directory (C:\gcc-lua-install) in that dialog as destination and press Ok.
• Close 7-zip window, we no longer need it.

Now browse into our working directory and check it: a new subdirectory named lua-5.2.2 should be present.

The current content of our working directory now should be:

        C:\gcc-lua-install\tdm-gcc-4.7.1-2.exe

        C:\gcc-lua-install\lua-5.2.2.tar.gz

        C:\gcc-lua-install\7-ZipPortable_9.20_Rev_2.paf.exe

        C:\gcc-lua-install\tdm-gcc

        C:\gcc-lua-install\7zip

        C:\gcc-lua-install\lua-5.2.2

with the last item being the subdirectory where Lua sources have been unpacked.

Step 6: Create a Windows Shell Script to Drive the Build

        @echo off

        :: ========================

        :: file build.cmd

        :: ========================

        setlocal

        :: you may change the following variable's value

        :: to suit the downloaded version

        set lua_version=5.2.2



        set work_dir=%~dp0

        :: Removes trailing backslash

        :: to enhance readability in the following steps

        set work_dir=%work_dir:~0,-1%

        set lua_install_dir=%work_dir%\lua

        set compiler_bin_dir=%work_dir%\tdm-gcc\bin

        set lua_build_dir=%work_dir%\lua-%lua_version%

        set path=%compiler_bin_dir%;%path%



        cd /D %lua_build_dir%

        mingw32-make PLAT=mingw



        echo.

        echo **** COMPILATION TERMINATED ****

        echo.

        echo **** BUILDING BINARY DISTRIBUTION ****

        echo.



        :: create a clean "binary" installation

        mkdir %lua_install_dir%

        mkdir %lua_install_dir%\doc

        mkdir %lua_install_dir%\bin

        mkdir %lua_install_dir%\include



        copy %lua_build_dir%\doc\*.* %lua_install_dir%\doc\*.*

        copy %lua_build_dir%\src\*.exe %lua_install_dir%\bin\*.*

        copy %lua_build_dir%\src\*.dll %lua_install_dir%\bin\*.*

        copy %lua_build_dir%\src\luaconf.h %lua_install_dir%\include\*.*

        copy %lua_build_dir%\src\lua.h %lua_install_dir%\include\*.*

        copy %lua_build_dir%\src\lualib.h %lua_install_dir%\include\*.*

        copy %lua_build_dir%\src\lauxlib.h %lua_install_dir%\include\*.*

        copy %lua_build_dir%\src\lua.hpp %lua_install_dir%\include\*.*



        echo.

        echo **** BINARY DISTRIBUTION BUILT ****

        echo.



        %lua_install_dir%\bin\lua.exe -e"print [[Hello!]];print[[Simple Lua test successful!!!]]"



        echo.



        pause

        

The current content of our working directory now should be:

        C:\gcc-lua-install\tdm-gcc-4.7.1-2.exe

        C:\gcc-lua-install\lua-5.2.2.tar.gz

        C:\gcc-lua-install\7-ZipPortable_9.20_Rev_2.paf.exe

        C:\gcc-lua-install\tdm-gcc

        C:\gcc-lua-install\7zip

        C:\gcc-lua-install\lua-5.2.2

        C:\gcc-lua-install\build.cmd

Now run the shell script by double-clicking on build.cmd, a window with a black background should appear. Inside it you should see the messages produced by the script as it works (most of them are from GCC during the compilation of Lua sources).

This can take a while, but it heavily depends on the performance of your PC. With our test system it took about a minute, but that was a rather old system. After the compilation has finished, the script will also create a "clean" binary distribution (i.e. without unnecessary source files) in our working directory and will perform a simple test that will print a welcome message before terminating. You should see that self-explanatory message at the end of the output in the black window. You can now close the black window.

The current content of our working directory now should be:

        C:\gcc-lua-install\tdm-gcc-4.7.1-2.exe

        C:\gcc-lua-install\lua-5.2.2.tar.gz

        C:\gcc-lua-install\7-ZipPortable_9.20_Rev_2.paf.exe

        C:\gcc-lua-install\tdm-gcc

        C:\gcc-lua-install\7zip

        C:\gcc-lua-install\lua-5.2.2

        C:\gcc-lua-install\build.cmd

        C:\gcc-lua-install\lua

Step 7: Copy the Lua Binary Installation in a Suitable Location

The directory C:\gcc-lua-install\lua now contains everything is needed to run a Lua script. You can copy this directory with its content wherever you may find convenient (even on a USB pen drive!). The internal structure of lua binary installation directory should be the following:

        lua-----+--bin

                |

                +--doc

                |

                +--include

In the bin subdirectory you will find lua.exe, the Lua interpreter (if you double-click on it it will run in interactive mode), whereas in the doc subdirectory you will find the Lua reference manual.

Step 8: Configure the System to Run Lua Files

If you want to be able to type:

        lua myscript.lua

to run myscript.lua from the command line you must put the Lua bin subdirectory on the Windows search path.

Concluding Remarks

After you have copied the lua subdirectory in its final location, you could completely delete the working directory with all its content.

However, you can salvage many useful things easily:

• The installation packages lua-5.2.2.tar.gz, tdm-gcc-4.7.1-2.exe and 7-ZipPortable_9.20_Rev_2.paf.exe can be stored away for future needs or backup purposes.
• The GCC installation dir tdm-gcc can be copied or moved wherever you want (be careful not to put it in a directory having spaces in it) and the tools inside tdm-gcc\bin can be invoked directly from the command line (you must add tdm-gcc on the Windows search path if you want to avoid specifying their full pathname, however).
• The 7-zip installation dir is also fully relocatable ("portable", as non-programmer Windows users would say, but portability in programming has another meaning [7]). Thus you can move/copy it wherever you want and start 7-zip by executing the 7-ZipPortable.exe executable inside. It is so lightweight it fits nicely also on a pendrive!
• If you are curious you can also explore the directory and give a look inside the Lua sources, but you need to be a C programmer to understand most of them!

Have Fun with Lua!!!