LuaTools 

LuaTools is a hybrid of Lua and C. It creates small independent 32-bit Windows programs instead of using Lua as an extension language in an existing program as originally intended. If used in published work, it is wise to examine Lua's license. There are no restrictions on use of my modifications and additions, but I am sometimes vain enough to like credit if I am lucky enough to get it.

LuaTools uses any one of three versions of Lua, v4.0.1, v5.0.2 and v5.4.2. If you chose to build it, you'll know which bits are original Lua and which are added, by comparing the original source files with the modified files provided here, and you'll need the original source archives to build LuaTools anyway, so there is no 'hidden code' anywhere. You'll need to compile it just to make it go, but that's very easy to do with the tools and details described in the ZIP file.

Lua is excellent for rapidly developing small tools, especially those that deal with large text files or data files whose size may change as a result of processing. The name 'LuaTools' is not the most imaginative, and may have been used by others more than once already, but it fits. There is no better way to define the purpose of this system.

Inflicting C and its need for rigorous use of computer memory on people who want to build tools isn't always wise! It is the best way, but some kind of bridge helps a lot. Lua is built in C, and that is why Lua is so useful. It lets people think more about their own purposes instead of the absolute needs of the computer. It is safer and faster to write new tools with Lua, and LuaTools extends it with C functions to make it easy to use coloured text in command-line windows, and to use a file dialog as the sole user interface to a file processing tool, and to do accurate time and date calculations, and to get convenient access to full paths and file names and extensions regardless of how the file or command arguments are passed. There is also a small, fast 32-bit integer logic function that makes five of C's bitwise operators available to Lua.

The three LuaTools library files have some things Lua can't do under some circumstances if not all, and they're mainly designed to augment Lua, not to replace it. Sometimes it's best to stay with Lua standard libraries, but smaller files are more efficient to store and distribute so it's worth reducing them if possible. Sets of tools using LUA.DLL as a common source of functions make the decision very easy: use all libraries.

The problem with using Lua is that you always need Lua unless you can build executable files that are independent from it, and there is no native support for coloured text, and it may rely on C 'runtime' library code that doesn't always work as hoped or expected (like crashing if trying to calculate with dates before 1970!). This system is designed to solve these problems in a way that is very easy to use. It adds as little as possible to Lua, and changes only what is needed to make it work when adding the same code to any of the three different versions of Lua used by LuaTools.

Luac.exe is the program used to convert scripts into programs separate from a Lua installation. It is modified for two purposes: to replace its -s switch with -d. It strips debug information by default. If debug information is to be kept, ask for it with the -d switch. The other purpose is to make a C file that contains the same data the 'luac' file contains, ready for compiling in place of Lua.c to make the executable file. This C file will have the same name as the script passed to Luac.exe, so a single act of dropping the script icon onto Luac.exe is enough to create that C file, or this can be automated as shown in the included batch file. There is also a -w switch added, to tell Luac to make the C file use a 'WinMain()' function instead of the usual 'main()'. This is useful for tools that need a file dialog to collect files for some task. Use it when a console window is an annoying inconvenience, or when you want to include an icon in your program.

Lua errors are suppressed by default in LUAC-based EXE files, but not when writing and testing the script with Lua, so pass the script to Lua as normal until it's ready to compile as an independent executable file.

If I was reading to this point, I'd have downloaded the file by now and had a look before reading any more. Just so you know...

This collection of files is small but must be completed with original Lua sources, as described in the file 'INSTALL.txt' in the ZIP file supplied here. There are no 'makefiles' or 'bakefiles'. Everything is coordinated by a single batch file, 'COMPILE.bat'. When the compiler and Lua directories are placed where you want them, modify copies of the batch file so it can find them when it compiles an executable tool from a Lua script. There are very few commands, but study them carefully because everything starts there.

Each of three Lua versions is adapted by files supplied here. This system will not teach you how to use Lua (other than to emphasise methods likely to work more often than not), but manuals are included with the original Lua source code. Examples I provide may also help, but they're mainly there to prove the system works, and to demonstrate the use of specific functions in the new LuaTools library code.

This system is based on Lua v4.0.1, v5.0.2 and v5.4.2, as complete systems ready for compiling by TCC v0.9.25 (Tiny C Compiler, the latest version for Win32 systems), to create independent Windows executable files. All three versions have several edits, mostly convergent with methods and syntax of Lua v5.0.2, so adapting existing scripts is likely to need minimal if any editing to be compatible with all three of the modified versions of Lua. To see exactly what changed, compare the files with their originals in the 'Tarballs' of source code from Lua.org because you'll need those anyway, to complete the file sets. Anything that was done was guided by examining how Lua does it.

There is a later version, 'lua-5.4.4.tar.gz', but this has not been used for LuaTools. It was released some time after LuaTools development started. It may be easily adaptable, but it is better to stay with the most recent stable release and to update only if there is a need to do so. LuaTools bridges the most enduring code in the three Lua versions it uses. It is NOT an 'upgrade chase'. It's intended to spare people from that. It's for people who use a tool to build their own tools, and who need the support to remain consistent whenever possible.

The earlier the version, the smaller the output executable will be, and Lua v4 functions are made accessible by Lua v5 calls intended to do the same things. If Lua v4 is too minimal for some task, consider v5.0.2, which will do more but result in larger files. Lua v5.4.2 is added to be sure that all the latest methods Lua can offer are still available using a consistent method that works for Lua v4.0.1 wherever there is enough in common to allow it. Lua's latest methods will work, but full compatibility with the earlier versions will fail, so avoid using the latest methods if small executables are the main purpose. Lua v4.0.1 makes files about half the size of Lua v5.4.2, so it's worth keeping to compatible methods where possible. It's best to start small and work with a larger version if needed. Lua was chosen partly because it IS small enough to make tools without bloated overheads built into every tool made with it.

A few minor changes to standard Lua practise can help, such as using brackets () to contain the whole string when a single capture is all there is, to prevent string-checking errors. Some versions need this, others don't, but all will work if you do it. Another case is using global variables if 'outer scope' errors arise, rather than try to use 'upvalues' which are obsolete in later versions of Lua anyway... If you find similar oddities, test each version and stick with whatever works for all.

While aiming to make scripts compatible without modification, the same applies to function libraries and to C files created by Luac, but the script and the version of LUAC used must be consistent with the version of Lua chosen to make the EXE file. The batch file 'COMPILE.bat' is deliberately written to make sure that Lua's executable files are all built from one version, which also makes it very easy to choose which to use.

If this page has interested you enough to know more, start exploring, but keep this page too, you'll need all the information you can get, but more than anything else, you need to see LuaTools work, then you'll really see the point of this if you don't already.

You may find it worth using this system purely to get the reliable use of coloured text in a console. It is vastly helpful to have this for clarity in text-based interfaces, and not many people have done it because there are bugs in the BIOS calls that are at the root of doing it on any 'X86'-based computer, and the Win32 API adds bugs of its own! The small PutConsole() and GetConsole() functions at the core of the '#console.c' library are carefully written to avoid these bugs, as are the auxiliary functions they call on. I extended the compatibility of this method to 16-bit DOS programs using auxiliary functions written in very compact assembly code, and Watcom can compile this with the exact same C code, with exactly the same results. This is a solid method, well tested in many contexts now. I may make the 16-bit ASM variants available too because COM files can be built with it, and those can be run damn near anywhere, and such code can run even without an operating system!

I mention this so you can see the context for the work, and how deep the rabbit hole goes (I DO like those little red pills...) But what you can get here now, is what started it. Making it work in Lua was the first reason I had to do it, and unifying three versions of Lua with intent to make it easy to create small EXE files was a nice extra.