Binary Lua modules: best practices for Unix


Key points
----------
    * don't hard-code Lua header or library paths in your build script
    * use pkg-config tool
    * use libtool, especially for modules to be loaded dynamically
    * for general modules which are to be published for use by various apps:
        * provide both static and dynamic library files
        * publish a pkg-config .pc file for the module


Library naming
--------------
Given a Lua module "foo_bar", the base name for the library files should
be "liblua-foo_bar".  The "lib" prefix is a requirement of libtool, and
allows you to use the -l option of the linker as in "-llua-foo_bar".  The
"lua-" part, besides letting us know that the library is related to Lua,
by way of the dash charcter affects the module open function which require
will try to use when it dynamically loads the module.  Since everything
before the dash is ignored, the open function will simply be
"luaopen_foo_bar".  An added benefit of the "lua-" prefix is that it
discourages use of "Lua" in the module name itself.  Note that in order
for require to locate the library files, "liblua-?.so" patterns have been
added to the default CPATH.

While other platforms may require a different naming convention, note that
this shouldn't be an issue for Unix software builds which discover library
names by way of pkg-config.


Real example
------------
In this directory is a minimal binary Lua module called "foo" which has
a single function "get_greeting" which returns a string.  The purpose
is to show how to build and use both dynamic and static modules in a
portable way (as far as Unix goes).

If you don't have libtool installed, try:

    $ apt-get install libtool

Build and run the dynamic test with:

    $ make test-dynamic

or the static test with:

    $ make test-dynamic

TODO: show example .pc file