Installing one of my Lua libraries should be simple: just download it, have a look at the README, perhaps fix a couple of lines in the Makefile, and then type make. This will build the library and run a simple test so that you can see that the library works.
Here are detailed instructions anyway. Read on: it's all very simple, really. I hope this explanation helps you use my libraries and makes Lua even more useful to you. If you still have questions, please contact me. Enjoy.
The instructions given here are biased towards Linux and Mac OS X. They'll probably work on other Unix systems, perhaps with minor adjustments. If you're running Windows, I'm afraid I can't give any instructions at all, but please read this anyway, because there's other useful information.
The instructions are for Lua 5.1 and 5.2. (They apply to Lua 5.0 with minor changes. But is anyone still using Lua 5.0? If you are and need the features of a 5.1 package in 5.0, please let me know. It's usually simple to update the 5.0 package.)
I do minor periodic updates to the libraries without announcing them. To check whether you have the latest version of a package, check its release data, (size, date, and checksum).
Next, download the package you need. Make sure to get the package corresponding to your version of Lua. The package is usually called lxxx and is distributed as a tarball named lxxx.tar.gz. Open this tarball with tar zxvf lxxx.tar.gz. This will create a directory called xxx (no 'l'), which will contain Makefile, README, lxxx.c, test.lua, and possibly other files.
The reason for this name scheme is that
I want to avoid name clashes,
hence the `l' before the names,
but I still want to be able to use the library in Lua by its plain name:
xxx will be the name of the table created by the library.
Also, I don't add an 'l' to xxx.so because
I want to be able to load it with lua -lxxx
Now, have a look at the README. If the library is a binding to a third-party C library, either download it at the URL mentioned in the README and install it, or look for it in your system (try using locate). Either way, make a note of where it is installed for the next step.
If you have installed Lua in a standard place, you may even skip editing Makefile because you may give the location of Lua on the command like. In this case, something like make LUA=/usr/local/lua will probably suffice.
Either way, now run make. If all goes well (and I trust it will), this will build lxxx.o and xxx.so, and then run a simple test.
If the test failed, perhaps your Lua interpreter does not support dynamic loading. See the next section.
The Makefile includes the targets o and so, in case you want to build lxxx.o and xxx.so without running the test.
If you're running Mac OS X, then you'll need to edit the Makefile
-bundle -undefined dynamic_lookup.
Most Makefiles have a
MAKESO variable that handles that; just uncomment the line with
For other platforms, read
In 64-bit Linux platforms,
you may need to add
The easiest way to make this scheme work is to follow what the standard Lua distribution does and build the Lua interpreter to support dynamic loading, but still link the Lua library into it statically. This avoids the hassle of having to know where the Lua library is located at run time. In Linux, the special magic needed to export the Lua API from the static Lua interpreter is to use -Wl,-E for linking. (I've seen it mentioned that -rdynamic also works in recent gcc, but I haven't tested it. The Makefile in the standard Lua distribution knows the correct magic for several common platforms.)
If you choose to use the library in this way,
install xxx.so in some official place,
where it can be found when you load the library with
lua -lxxx or with
(The environment variable
LUA_CPATH and the Lua variable
package.cpath control that.)
This scheme suffices if you're using Lua via the standard interpreter.
If you're embedding Lua in your own main program,
then dynamic loading still works
(provided you use the special link magic mentioned above),
but in case you want to link the xxx library statically,
just add lxxx.o to your project or Makefile and
add an entry for xxx in
(I recommend that you copy and edit
linit.c to suit
your needs if you're linking Lua libraries statically.)
The source code of the binding contains the names and parameters of the exported functions and methods. Running make doc will give you this brief list nicely formatted. The README includes that list.
The packages include a test program, called test.lua, which shows the library in action. This should give you a good start on how to use the library. (Writing test.lua is how I learn to use the library.) If you want to try the library with a different test script, do make TEST=mytest.lua.
The license applies only to the code I wrote. Since my libraries are usually just bindings to existing C libraries written by other people, other licenses may apply to those C libraries. That's why I don't usually include them in my packages and you'll have to get them yourself, if they're not already installed in your system.
In a few cases, I do include code written by someone else, either because I've modified the original code or because it's part of a much larger package and it's difficult to extract. These modules have their own licenses and you should check that they are acceptable to your needs. They probably will, because I try to only include certified Open Source code. See the README for details.