DEV Community: Sam

Compile lua scripts to exe

Sam — Sat, 04 Feb 2023 11:33:14 +0000

Have you ever wanted to compile your Lua scripts into Windows executables? Having trouble deploying Lua programs on other computers? Here's a quick and easy way to turn your Lua scripts into executables.

rtc, an open source Lua to exe compiler

rtc is a simple command line tool to build standalone executables from your Lua scripts. A GUI front end is available for those who are resistant to the console.
rtc can be downloaded on the GitHub project homepage, and available for x86 and x64 Windows platforms.
Once downloaded, put the content of the ZIP archive on your hard disk and make sure it's available on your system PATH.

Let's build our first executable

Create a simple hello.lua file containing this script :

print("Hello World !")
io.stdin:read("*l")

Now, open a console or terminal prompt, go to the folder where you have saved the file hello.lua and enter the following command :

rtc hello.lua

And voila ! rtc should have produced an executable named hello.exe. You can run it like any other executable.

Static executables with rtc

By default, rtc creates dynamic executables, meaning the Lua VM is in the library lua54.dll and its needed to run any program built with rtc (this dependency can be found along your executable or in your system PATH).

If you want to get rid of this library dependency, you can tell rtc to build a static executable with the -s option :

rtc -s hello.lua

The hello.exe file will be fatter, as it includes now the Lua VM. But be careful with those static executables, as it is strongly discouraged to require for Lua binary modules (may lead to crash). Use this option only if your program don't need any Lua binary module.

What's next ?

This tutorial shows basic usage of rtc. But there is more functionnalities available, like generating Desktop executables, changing default executable icon, embedding content...

Please read the rtc documentation for more on this.

Working with ZIP files in LuaRT

Sam — Tue, 28 Sep 2021 17:09:06 +0000

LuaRT provides a builtin compression module to work with compressed files in ZIP format, without any additional dependencies.

ZIP archive files

ZIP is a file format that supports lossless compression. A lossless compression algorithm allows the original data to be perfectly reconstructed from the compressed data. A ZIP file contains one or more compressed files, making it an ideal way to reduce the size of large files and keep related files together.

The Zip Object

The LuaRT compression module provides an abstraction of zip files represented as a Zip Object. Only INFLATE/DEFLATE algorithms are supported.
This Object facilitates the creation of ZIP archive files and provides methods and properties for adding and extracting compressed files.

To use the Zip Object, you must first require for the compression module :

-- require the builtin 'compression' module
local compression = require "compression"

Extract files from a ZIP archive

To extract files from an existing ZIP archive, you can use the Zip:extractall() method :

local compression = require "compression"

-- Create a Zip instance to represent the ZIP file 'archive.zip'
local archive = compression.Zip("archive.zip")

-- open the ZIP archive for reading
archive:open("read")

-- extract and uncompress all the files in the current directory
archive:extractall()

You can extract a specific entry with the Zip:extract() method :

-- extract the ZIP entry "extractme.bin" in the current directory 
archive:extract("extractme.bin")

A destination path can optionaly be provided :

-- extract the ZIP entry "data.bin" in the specified directory 
archive:extract("data.bin", "C:\\Extract\\Me\\Here")

Creating a ZIP archive

Zip:open() can be used to create an empty ZIP archive. Files can be added to the archive with the Zip:write() method:

local compression = require "compression"

-- Create a Zip value to represent the ZIP file 'new.zip'
local archive = compression.Zip("new.zip")

-- open the ZIP archive for writing
archive:open("write")

-- add a file to this archive
archive:write("C:\\addme.txt"))

You can recursively add entire directories too :

archive:write("C:\\I_am_a_directory_addme\\"))

Iterating over files in a ZIP archive

Zip object is iterable with the each() function, returning at every iteration the next entry name in the ZIP archive previously opened in "read" mode:

local compmression = require "compression"

-- Create a Zip value to represent the ZIP file 'archive.zip'
local archive= compression.Zip("archive.zip")

-- open the ZIP archive for reading
archive:open("read")

-- Iterate over each ZIP archive entries and extract it
for entry in each(archive) do
   print("Extracting '"..entry.."'")
   archive:extract(entry)
end

Reading ZIP archive entries in memory

ZIP archive entries can also be extracted in-memory using the Zip:read() method :

local compression = require "compression"

-- Create a Zip value to represent the ZIP file 'archive.zip'
local archive = compression.Zip("archive.zip")

-- open the ZIP archive for reading
archive:open("read")

-- print the content of the ZIP archive entry 'README.TXT'
print(archive:read("README.TXT"))

As you can see, LuaRT's compression module provides an easy way to manage ZIP archives. Additionally, you can read the complete compression module module documentation.

Using files in LuaRT

Sam — Thu, 27 May 2021 06:52:57 +0000

LuaRT is a comprehensive Windows framework to develop in Lua with a specific runtime library. In the Lua standard library, input / output functionalities are gathered within the io module. In LuaRT, they are grouped together within the sys module, and more particularly the File object.

Using the File object in LuaRT

The manipulation of files in LuaRT is facilitated by the use of File objects: creation of files, opening, closing, moving, copying, deleting ...

Creating a File value

At this point, it's important to understand that a File object represents an abstraction of a file that may or may not physically exist. For example, when creating a new file, only the call to the File:open() method will physically create the file on the computer's storage:

local newfile = sys.File("hello.txt") -- newfile holds a File value
print(newfile.exists) -- outputs false
newfile:open("write") -- creates the file physically on the disk 
newfile:close()       -- closes the opened File
print(newfile.exists) -- now outputs true

File operations

A File object can be used to perform file operations:

local file = sys.File("test.txt") 
file:copy("test_copy.txt")   -- copies file
file:move("C:\")             -- moves file
file:remove()                -- deletes the file

Opening and closing a File

A file can be opened to read or write its content. This is done by calling the File:open() method. By default, the file is open in "read" mode. The file encoding can be specified as a second argument or detected using Byte Mark Order :

local file = File("test.bin")
file:open()   -- opens the file "test.bin" in read mode (encoding is autodetected)
file:close()                   -- closes the file
file:open("write", "binary")   -- open the file in write mode (erasing its previous content), using "binary" encoding(ie raw binary)

Do not forget to close a file after the transaction on this one ended. This is done automatically when the File object is garbage collected, but that cannot be predicted.

Reading and writing Files

Once the File object has been created, and the File:open() method called, you can write or read on the File (depending on the mode used in the call). These methods return Buffer objects in binary mode (containing in memory binary data) or strings in UTF8 or UNICODE mode.

Reading file content

There are two methods for reading the content of a file: File:read() and File:readln()

local file = File("README.TXT"):open()  -- opens the File for reading
print(file:read())  -- reads and prints all the file content

The File:read() method reads a number of characters (when using UTF8 or UNICODE mode) or bytes (in binary mode) specified as argument, or all the content of the file if no argument is provided.

The File:readln() method reads a line (until end of line characters "\r\n" or "\n" are encountered).

Writing to files

There are two methods for writing data to a file: File:write() and File:writeln()

Each method take one argument, converted to a string to be written to the file. In binary mode, Buffer objects can be used.

File:writeln() writes a line to the file, appending "\r\n" (corresponding to the End Of Line marker on Windows).

File position

The File.position property get or set the current file position, as a number. File position always starts at 1 (as for all indexed/positioned values in Lua).
File position interpretation depends on the file encoding.
In "binary" encoding : the position is expressed in bytes.
In "utf8" or "unicode" encoding : the position is expressed in characters.
The File.eof property checks if the end of the file have been reached.

File timestamps

The File.accessed, File.modified and File.created permits to set or get timestamps using a Datetime object (in LuaRT, Datetime objects represent a moment, a combination of a date and a time).

File attributes

The File.hidden, File.temporary and File.readonly permits to set or get the corresponding attributes.

File path and names

The File.fullpath, File.filename, File.extension, File.path permits to get access to the different parts of a filename.

As you can see, File objects provide easy access to all of the functionality related to creating, reading, writing and manipulating files in LuaRT. These features go beyond the capabilities offered by the standard Lua library.

Lua strings are not strings

Sam — Sun, 21 Feb 2021 16:36:37 +0000

Yes, you read that right. It could have been worthy of a shakespear play but when it comes to strings in Lua, it can turn into a nightmare if you don't pay attention with the true definition of what a string is...

"Wait, what do you mean by strings are not strings?"

In Lua, strings could have been called buffers, arrays, or even containers. Indeed strings are only containers. But it does not contain characters. In fact, Lua has no idea what a character is.

"So what a string contains ?"

You may then wonder what the strings contain: they simply contain bytes. Strings can therefore, in Lua, contain lots of things: an image, a digitized sound, a database ... and characters too.

This is where things get complicated: Lua considers that in strings, a single byte corresponds to a single character. This is fine as long as you are using single-byte encoded characters (as with ASCII encoding), with only 255 character possibilities.

But in the age of the Internet, when the whole world communicates in all languages, that seems rather restrictive ! Fortunately other encodings than ASCII exist, to extend the number of usable characters: UTF8, UCS 2 LE, UCS 2 BE,...
They allow to encode a character over several bytes.

Multibytes characters

Multibytes characters can be stored in Lua strings after all, as strings in Lua contains bytes.
Yes, that's right. But it does not mean you can use them !

One rule to rule them all

All Lua strings functionnalities (concatenation, length calculation, string.find, string.gmatch, string.sub...) consider that strings contain only single byte characters : the same rule again !

Here is an example that illustrates the problem (the script must have been saved with UTF8 encoding +/- BOM)

local summer_infrench = "été"

-- outputs 5 !?
print(string.len(summer_infrench))

-- pos = 3 !?
pos = string.find(summer_infrench, "t"))

What's going on ?

Remember the rule : strings are considered as bytes containers. The UTF8 string "été" (means 'summer' in French) is 3 characters long, but occupies 5 bytes in memory :

é	t	é	= 3 characters
0xC3 0xA9	0x75	0xC3 0xA9	= 5 bytes

That's why the function string.len returns 5 and not 3.
The same for string.find : The byte position of the "t" character is 3.

Is there any workaround ?

Hopefully, yes there is one. Since Lua 5.3 a new module "utf8" is available to help developers with UTF8 encoded strings. But this greatly complicates the use of UTF8 strings, as it uses specific functions. A kind of overlay over strings. Not very friendly : in other modern programming languages, strings are containers for characters and support natively multibytes encodings.

Here is the previous example using the "utf8" module :

local utf8 = require "utf8"

local summer_infrench = "été"

-- yes ! outputs 3 !
print(utf8.len(summer_infrench))

-- Still pos = 3, no solution for string.find with UTF8 strings
pos = string.find(summer_infrench, "t"))

What if I want to use UTF8 strings with Lua ?

It's in Lua philosophy : if Lua lacks something, implement it using binary modules or Lua modules. Search on the net and you will find some of them. But again, for such a simple functionality, this represents a certain degree of complication especially for beginners.

Conclusion

I hope this article has helped to better understand the use of strings in Lua. This is also the main reason why I decided to natively implement UTF8 strings in my LuaRT project.