Installing my Lua libraries

Installing one of my Lua libraries should be simple: just download the package, 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. Do 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. This page explains what you'll find in the package and how to build, test, install, and use the library. 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 for Linux and macOS, which are the platforms I have easy access to. They'll probably work on other Unix systems, perhaps with minor adjustments. If you're running Windows, I'm sorry I can't give any instructions at all, but please read this anyway, because there's other useful information.

Get the latest version

My Lua libraries are tiny tools that become stable pretty soon. Recent packages include a version number; older ones do not. All packages 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 on the Lua mailing list. To check whether you have the latest version of a package, check its release data (version, date, size, 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. All recent packages are marked 5.x and work for Lua 5.1 and later. Otherwise, make sure to get the package corresponding to your version of Lua, if it exists. If you need a package for a previous version of Lua, please contact me.

Now open the package. A package named lfoo will contain Makefile, README, lfoo.c, test.lua, and possibly other files. The packages are self-contained. If the package contains third-party code, this code will be in a directory named src.

Building the library

The package builds out of the box in Linux and macOS, if Lua is installed in /usr/local. Just do

make
Otherwise, tell make where Lua is installed using a variant of
make LUA_TOPDIR=/var/tmp/lhf/lua-5.3.5/install

If all goes well (and I trust it will), this will build foo.so, and then run a simple test.

If the build failed, most probably it could not find the Lua headers, library, or interpreter. Set LUA_TOPDIR to the correct location when you run make or edit Makefile, and try again.

If the test failed, perhaps the current directory is not in the path where Lua looks for dynamic libraries. In this case, try

env LUA_CPATH='./?.so' make test
Otherwise, perhaps your Lua interpreter does not support dynamic loading. See the next section.

Adding the library to Lua

To install a library where Lua can find it, use a variant of these, depending on where you want to install it or on what permissions you need:

make install
sudo make install
sudo make install LIBDIR=/usr/local/lib/lua/5.3
This will allow you to use the library via the standard Lua interpreter with lua -lfoo or with require"foo". (The environment variable LUA_CPATH and the Lua variable package.cpath control where Lua looks for libraries.) That's all.

If you're embedding Lua into your own main program, follow what the standard Lua distribution does when building its command-line interpreter: link the Lua library statically into your program. 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 Lua library embedded in your program is to link your program using -Wl,-E. In macOS no special magic is needed here. The Makefile in the standard Lua distribution knows the correct magic for several common platforms.

Using the library

My libraries are usually just bindings to third-party C libraries, so the real documentation is their own documentation. Even when I include the source code for a third-party library, I don't include their documentation. This is usually part of their full distribution, which can be found at the address mentioned in the README.

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 (as in mathematical libraries).

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. Reading it and experimenting with it should give you a good start on how to use the library. (Writing test.lua is how I learn to use the library.)

License

All my Lua packages are free software. They are released into the public domain and also under the liberal MIT license, which is the same as the Lua license. Choose between the two licenses to best suit 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 terms above applies only to the code I wrote. Sometimes, I do include code written by someone else, either because I've modified the original code (rarely) or because it's part of a much larger package and it's a hassle to extract. In this case, all third-party code will be in a directory named src, together with their original license file, which may be called COPYING or README. Check that their license is acceptable to your needs. It probably will, because I try to only include certified Open Source code. See my README and their 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. Even nicer is to know how they're being used.

If you have a question that may interest other people, consider asking it in the Lua mailing list.

All feedback is welcome. Thank you for your interest in Lua and in my libraries.