This document aims to be a guide for the standardization of third-party libraries for the Lua programming language. The standardization guidelines described below have been discussed on the Lua-l mailing list, and have been modified since its first release to accommodate the feedback from the Lua community. We expect that new Lua libraries or new releases of the existing libraries follow these steps, in order to improve the user-friendliness for users of those packages.
Some of the guidelines described here are oriented to UNIX-like systems, even though there are notes about Windows where appropriate. Most topics are generic enough to be used on most operating systems.
Installation path
The suggested path for the installation of Lua binary libraries (.so and .a files on UNIX) is /usr/local/lib/lua/5.0. The .lua loader files and libraries written in pure lua should be installed at /usr/local/share/lua/5.0. The Makefile or configure script should provide a way to change the default prefix (to /usr for example).
Rationale: the version directory is necessary for safety regarding API changes across Lua versions. The path for the .lua files was an agreement reached after a discussion on the Lua list, based on what the Filesystem Hierarchy Standard says.
Lua users can set the LUA_PATH environment variable to "?;?.lua;/usr/share/lua/5.0/?.lua", and operating system distributors can patch lbaselib.c from the Lua distribution to provide this path by default:
-#define LUA_PATH_DEFAULT "?;?.lua"
+#define LUA_PATH_DEFAULT "?;?.lua;/usr/local/share/lua/5.0/?.lua"
On Windows, the situation is a bit different, as the user is asked for the installation path during install time. It will be assumed that the installation directory on Windows is C:\Program Files\Lua\5.0. The LUA_PATH variable and the patch to change the LUA_PATH_DEFAULT macro should be edited to reflect the Windows filesystem hierarchy.
Note: starting on Lua 5.1, the config file will include a variable for the setting of LUA_PATH_DEFAULT. This will allow the choice of a path without the need to patch the Lua distribution.
Initialization function name
The initialization function to be used as the second argument to loadlib should have a name that begins with luaopen_ followed by the library name. For example, luaopen_socket.
Rationale: this allows the use of a default loader script (see details below), and provides general better standardization of function names.
Library names
Shared and static libraries should be named simply as name.so and name.a, without a "lib" prefix and without version information. For example, foo.so and foo.a, as opposed to libfoo.so and libfoo.a
On Windows, dynamic libraries should be called name.dll. There is no specific file extension for static libraries.
Rationale: this naming scheme is used by other scripting languages. Also, like the initialization function name described above, it allows the use of a default loader script (see details below).
Loader scripts
Loader scripts should be called name.lua. If the guidelines described above are followed, operating system packagers can distribute the generic loader script below with the main Lua package. On UNIX, the third-party library packages installation can then just create a hard link to the generic loader, as in
# ln default.lua foo.lua
On Windows systems, the default.lua file should be copied to create the loader for the library, as there are no hard links on that operating system.
The code for default.lua, the generic loader, follows:
if not _REQUIREDNAME then
error('Don\'t load directly, use require "LibName"', 2)
end
-- Get libname.
local libname = os.getenv "LUA_SOPATH"
if libname then
if not string.find(libname, '/$') then
libname = libname .. "/"
end
else
libname = "/usr/local/lib/lua/5.0/"
end
libname = libname .. _REQUIREDNAME .. ".so"
local funcname = "luaopen_" .. _REQUIREDNAME
local f, err = loadlib(libname, funcname)
if not f then
error("loadlib('" .. libname .. "', '" .. funcname .. "') failed: " .. err, 2)
end
local function ret(s, ...)
if s then
return unpack(arg)
end
error(_REQUIREDNAME .. "'s " .. funcname .. " failed: " .. arg[1], 3)
end
return ret(pcall(f))
Note that libraries written in pure Lua should have their own loader script, as default.lua is meant to be used by libraries written fully in C.
Rationale: it is more natural to require "foo" than to require "luafoo", for example, as specifying a "lua" prefix is not necessary, considering we are writing a Lua script in the first place. Also this matches the common behaviour of the equivalent functions on other scripting languages.