Installing my Lua libraries

introduction · get the latest version · getting ready · building · adding · using · license · contact · about me · Lua

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.

Introduction

All my Lua libraries follow essentially the same pattern and so here is an explanation of what you'll find in the packages and how to build, test, install, and use them. For specific information, see the README in each package. The goal of this page is to make it easier for me to update the instructions and to avoid having large, repetitive READMEs in each package.

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.)

Get the latest version

My Lua libraries are tiny tools that become stable pretty soon. So, the package names do not include a version number. This may be inconvenient but it's one less thing for me to worry about. On the other hand, the libraries themselves include an update date in the source code and frequently a version string that is printed when you run the test. Please mention the package version or date when you report bugs or give feedback.

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).

Getting ready

First, download and install Lua. If you already have Lua installed, find out which version you have and where it is installed.

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 or with require"xxx".

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.

Building the library

First edit Makefile and fix the location of Lua and the third-party C library, if any. See if there's anything else you want to change. (Not really likely, because there's not much anyway.)

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 and change -shared to -bundle -undefined dynamic_lookup. Most Makefiles have a MAKESO variable that handles that; just uncomment the line with -bundle etc.) For other platforms, read this.

In 64-bit Linux platforms, you may need to add -fPIC to CFLAGS.

Adding the library to Lua

By far, the easiest way to add libraries to Lua is to dynamically load them. That's why the Makefile file builds xxx.so.

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 require"xxx". (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 linit.c. (I recommend that you copy and edit linit.c to suit your needs if you're linking Lua libraries statically.)

Using the library

My libraries are usually just bindings to third-party C libraries, so the real documentation is their own documentation. The bindings try to be as simple as possible: sometimes they are a mere translation of the C API, but I still try to do it in the Lua way. (For instance, I provide convenient metamethods whenever they make sense.)

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.

License

All my Lua libraries are in the public domain. If you cannot use public domain code for some reason, consider my code to be hereby released under the MIT license, which is the same as the Lua license. Choose between the two licenses that best suits your needs. My intent is that my code should be as free as possible. There, you have my permission to use my code without asking me. If you have special license requirements, please contact me.

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.

Getting in touch

Please send questions, comments, suggestions, requests, and bug reports to me by email at the address mentioned in the README. Or just drop me a line saying you're using one of my Lua libraries: it's always nice to know they're being used. All feedback is welcome. Thank you for your interest in Lua and in my libraries.


Last update: Mon May 27 23:21:13 BRT 2013 by lhf.