[ANN] Lua 5.1 Debian package

[John Belmonte <john@...>]

With help from Enrico Tassi, I've packaged Lua 5.1 (currently up to the
"original" -rc release) for Debian GNU/Linux officially, and it has
entered the distribution's unstable archive.  For users of Sarge (the
last stable Debian release), a backport is also available.  Note that
this package is a work in progress and won't become part of a stable
Debian release until the end of 2006 or later.

    http://packages.qa.debian.org/l/lua5.1.html

    http://backports.org/package.php?search=lua5.1

The package includes some propaganda, and it may cause controversy in
the domain where the Lua tires meet the road.  As a matter of disclosure
to people who don't use Debian, I've attached the package README and
have posted the package's examples as plain files at
<http://memebeam.org/john/debian/lua5.1/examples/>.  These minimal
examples include the recommended way to build binary Lua modules, etc.

While doing this packaging work I've come to appreciate libtool, and I
have to say I think it's not given the attention it deserves in the
list's discussions on both building Lua itself and building Lua apps and
binary modules.  It takes care of static and dynamic builds in one shot,
 hides the differences between Unix platforms well, and is trivial to
use.  While it doesn't cover every user out there, it does likely cover
95% of those using Unix (including Cygwin on Windows and Darwin on Mac).
 Even in the case of higher level build solutions (i.e. those
encompassing Windows OS's), I'd expect that they would employ libtool
when it's available for the target.

I could probably make a similar argument for the pkg-config tool.

--John

lua5.1 for Debian
=================

This is packaging for Debian of the 5.1 series of the Lua programming
language.  For package development see <http://pkg-lua.alioth.debian.org/>.

Binary package index:

    * lua5.1 - command line tools (i.e. interpreter and bytecode compiler)
    * lua5.1-doc - documentation, including manual and examples
    * liblua5.1-0-dev - development libraries
    * liblua5.1-0 - runtime libraries


II. Propaganda
==============

Best practices
--------------
See "./examples/debian/" in the lua5.1-doc package for some tips and best
practices for using the Lua library in your app, building binary modules,
etc.


III. Rationale
==============

Packaging philosophy
--------------------
The packaging philosophy adopted is to avoid changes to upstream source as
much as possible.


Need to maintain old Lua releases
---------------------------------
While the Lua authors attempt to keep changes to the language and standard
libraries backwards compatible, the C API often changes significantly between
versions (e.g. from the 5.0 series to 5.1).  Applications in which Lua is
embedded often become bound to a certain version of Lua indefinitely.  For
these reasons, and in contrast to other interpreted languages which have more
of a stand-alone focus, it's important to maintain old Lua library releases
as long as they are in use by relevant applications.


Naming convention (lua5.1 vs. lua51)
------------------------------------
The naming convention prior to the lua5.1 package, specifically the lack of
delimiters in the version portion, lacked foresight.  The reason is that if
the version ever has more than one digit per component, the terser name will
be ambiguous.  Even if this will never be a problem in practice (will 61.1
clash with 6.11?), lua12.3 seems more friendly than lua123.


Library SONAME
--------------
As explained, each series of Lua (e.g. 5.0, 5.1) is treated as a completely
separate library.  Within a series, Libtool versioning is followed.  For
example, the first release of Lua 5.1 (5.1.0) will have a soname
"liblua5.1.so.0".  Let's say that 5.1.1 is later released, and it is binary
compatible with the previous version.  In that case, the soname will stay
the same, and existing applications do not need to relink.

Note that in this convention, along with the naming of interpreters, etc.,
as described previously, there has been a conscious compromise in the
granularity of the versions that may be specified.  That is, the
minor version number is considered significant in that it may break
compatibility, but not significant in calling out a version of Lua to
interpret a file, maintaining parallel versions for development, etc.


Package binaries: static vs. dynamic linking
--------------------------------------------
There are two executables in this source package: "lua" and "luac".  Due to
luac's use of internal symbols in the Lua core, at present it cannot be
dynamically linked.  Also, it's been reported that use of position-
independent code hinders the VM's performance.  For these reasons, and for
consistency, both executables are statically linked.


IV. For packagers
=================

Package testing
---------------
Final testing should be done in a clean environment (e.g. via pbuilder).
Important tests:
    * package build
    * install of each binary package without the others installed
    * with all packages installed:
        * run "make" in examples/debian/


Unfinished business
-------------------
TODO: document module paths
TODO: include soname number in source package name (on next increment).  May
    want to split library and command line tools into separate source packages.
ISSUE: want way to avoid hard-coding package and path names in
    lua5.1.postinst, etc.