Amalg -- Amalgamation of Lua Modules/Scripts

Introduction

Deploying a Lua application that is split among multiple modules is a challenge. A tool that can package a Lua script and its modules into a single file is a valuable help. This is such a tool.

Features:

• Pure Lua (compatible with both 5.1 and 5.2), no other external dependencies. Works for Lua 5.1 and 5.2 modules (even those using the deprecated module function).
• You don't have to take care of the order in which the modules are require'd.
• Can collect require'd Lua modules automatically.

What it doesn't do:

• It does not compile to bytecode. Use luac for that yourself, or take a look at squish, or luac.lua.
• It doesn't do static analysis of Lua code to collect require'd modules. That won't work reliably anyway. You can write your own program for that (using the output of luac -p -l), or use squish, or soar instead.
• It will not compress, minify, obfuscate your Lua source code, or any of the other things squish can do.

There are alternatives to this program: See squish, LOOP, soar, luac.lua, and bundle.lua (and probably some more).

Getting Started

You can bundle a collection of modules in a single file by calling the amalg.lua script and passing the module names on the commandline.

./amalg.lua module1 module2

The modules are collected using package.path, so they have to be available there. The resulting merged Lua code will be written to the standard output stream. You have to run the code to make the embedded Lua modules available for require.

You can specify an output file to use instead of the standard output stream.

./amalg.lua -o out.lua module1 module2

You can also embed the main script of your application in the merged Lua code as well. Of course the embedded Lua modules can be require'd in the main script.

./amalg.lua -o out.lua -s main.lua module1 module2

If you want the original file names and line numbers to appear in error messages, you have to activate debug mode. This will require slightly more memory, however.

./amalg.lua -o out.lua -d -s main.lua module1 module2

To collect all Lua modules used by a program, you can load the amalg.lua script as a module, and it will intercept calls to require and save the necessary Lua module names in a file amalg.cache in the current directory.

lua -lamalg main.lua

Multiple calls will add to this module cache. But don't access it from multiple concurrent processes!

You can use the cache (in addition to all module names given on the commandline) using the -c flag.

./amalg.lua -o out.lua -s main.lua -c

To fix a compatibility issue with Lua 5.1's vararg handling, amalg.lua by default adds a local alias to the global arg table to every loaded module. If for some reason you don't want that, use the -a flag (but be aware that in Lua 5.1 with LUA_COMPAT_VARARG defined (the default) your modules can only access the global arg table as _G.arg).

./amalg.lua -o out.lua -a -s main.lua -c

That's it. For further info consult the source. Have fun!

Contact

Philipp Janda, siffiejoe(a)gmx.net

Comments and feedback are always welcome.

License

amalg is copyrighted free software distributed under the MIT license (the same license as Lua 5.1). The full license text follows:

amalg (c) 2013-2014 Philipp Janda

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHOR OR COPYRIGHT HOLDER BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.