Debian lua policy
==============================

Conventions
-----------

In the following we will write `{VARIABLE}` to mean a schema of file name.
Used variable names follow:

  - `{LUA_VERSION}` The lua version, now `5.1` (that is `5.1.1` without the minor
    version number). 
  - `{PKG_NAME}` The usual name for that library, e.g. `expat`.
  - `{ABI}` The ABI version info, e.g. `0.0.0`
  - `{CABI}` The ABI first number (called CURRENT in libtool terminology)
  - `{LUA_MODNAME}` The string used to `require` the module, e.g. `lxp`

Rationale
---------

For every library two packages will be available, one containing only the
minimum needed to run `require "{LUA_MODNAME}"` and one with all the other
stuff (documentation or headers and library files to link standalone
applications).  The former package will be named:

> `liblua{LUA_VERSION}-{PKG_NAME}{CABI}` or `liblua{LUA_VERSION}-{PKG_NAME}`

depending if it has a C part or not. If `{PKG_NAME}` ends with a digit, a dash 
should be used to separate it from `{CABI}`. The latter will be named:

> `liblua{LUA_VERSION}-{PKG_NAME}-dev`

even if it contains only documentation (like pure lua libraries), since it
may be modified in the future to include some C parts (and this would imply
a renaming).

The headers files `.h` are intended to declare the simple
`luaopen_{LUA_MODNAME}` function.

The files `liblua{LUA_VERSION}-{PKG_NAME}.la` and
`liblua{LUA_VERSION}-{PKG_NAME}.a` are meant to ease compilation (using
[libtool][3]) and to build static applications (that do not need the
`liblua{LUA_VERSION}-{PKG_NAME}.so.{ABI}` file to run. 

[pkg-config][4]'s `lua{LUA_VERSION}-{PKG_NAME}.pc` file should include
(in addition to the standard fields)

> `libtool_lib=${libdir}/lib{LUA_VERSION}-${lib_name}.la` 

to ease compilation with libtool. To get this value use:

> `pkg-config --variable=libtool_lib lua{LUA_VERSION}-{PKG_NAME}.pc`

To avoid bloating the Debian archive with minuscule packages, refrain from
providing a `-doc` package unless the documentation is very large.  Including
a short documentation in the `-dev` package does not hurt. 

If the same source package is able to provide more than one couple of deb
packages (like luasql, that provides various backends) only one copy of the
source package should be added to the archive and let that package generate all
the needed debs.  All packages should be named with a common prefix, like
`liblua{LUA_VERSION}-{PKG_NAME}-` that in the case of luasql will produce the
following debs:

  - `liblua{LUA_VERSION}-sql-mysql2`
  - `liblua{LUA_VERSION}-sql-mysql-dev`
  - `liblua{LUA_VERSION}-sql-sqlite2`
  - `liblua{LUA_VERSION}-sql-sqlite-dev`

If the package is made of a common part the best would be to put them in a
package which name ends with the `-common` suffix. All debs should then depend 
on it. This avoids playing with diversions. The same also applies to documentation,
that (if common to all debs) should not be replicated on all `-dev` packages, 
but put in a `-doc` package.

Packages Contents
-----------------

Here a listing of the contents of the two packages will follow.

### Run time package: `liblua{LUA_VERSION}-{PKG_NAME}{CABI}`

  - `/usr/lib/liblua{LUA_VERSION}-{PKG_NAME}.so.{ABI}`
  - `/usr/lib/liblua{LUA_VERSION}-{PKG_NAME}.so.{CABI} -> 
       liblua{LUA_VERSION}-{PKG_NAME}.so.{ABI}`
  - `/usr/lib/lua/{LUA_VERSION}/{LUA_MODNAME}.so -> 
       ../../liblua{LUA_VERSION}-{PKG_NAME}.so.{ABI}`
  - `/usr/share/lua/{LUA_VERSION}/*.lua`

### Development package: `liblua{LUA_VERSION}-{PKG_NAME}-dev`

  - `/usr/lib/liblua{LUA_VERSION}-{PKG_NAME}.la`
  - `/usr/inlude/lua{LUA_VERSION}/*.h`
  - `/usr/lib/liblua{LUA_VERSION}-{PKG_NAME}.a`
  - `/usr/lib/liblua{LUA_VERSION}-{PKG_NAME}.so -> 
       liblua{LUA_VERSION}-{PKG_NAME}.so.{ABI}`
  - `/usr/share/doc/liblua{LUA_VERSION}-{PKG_NAME}-dev/*`
  - `/usr/lib/pkgconfig/lua{LUA_VERSION}-{PKG_NAME}.pc`

Should a `-doc` package exist, only the following files will be contained
in the package:

  - `/usr/share/doc/liblua{LUA_VERSION}-{PKG_NAME}-doc/*`

### Packages Contents (an example)

*`liblua5.1-expat0`*

  - `/usr/lib/liblua5.1-expat.so.0.0.0`
  - `/usr/lib/liblua5.1-expat.so.0 -> liblua5.1-expat.so.0.0.0`
  - `/usr/lib/lua/5.1/lxp.so -> ../../liblua5.1-expat.so.0.0.0`
  - `/usr/share/lua/5.1/lxp/lom.lua`

*`liblua5.1-expat-dev`*

  - `/usr/lib/liblua5.1-expat.la`
  - `/usr/inlude/lua5.1/lxplib.h`
  - `/usr/lib/liblua5.1-expat.a`
  - `/usr/lib/liblua5.1-expat.so -> liblua5.1-expat.so.0.0.0`
  - `/usr/share/doc/liblua5.1-lxp-dev/us/*html`
  - `/usr/lib/pkgconfig/lua5.1-expat.pc`

Creating a package in a quick and clean way
-------------------------------------------

Since all lua libraries look almost the same, we provide a common set of
templates to help building packages conforming the policy and allowing
single-place modification all over these packages.

### The `lua5.1-policy-dev` package

The following files are contained in the package:

  - `Makefile.Debian` is a generic Makefile for lua libraries. It is fully
    configurable following the CDBS spirit, using hooks and parameters.
    
  - `app.c` and `app.c.conf.in` are automatically handled by `Makefile.Debian`
    and they implement an interpreter that calls `luaopen_{LUA_MODNAME}` and
    runs the file taken as parameter. `Makefile.Debian` test target links twice
    this interpreter (one time dynamically and one statically, i.e. including
    the library) and runs it on the test file.

  - `pkg-config.pc.in` is automatically handled by `Makefile.Debian` that
    will create for you a policy-conforming `.pc` file.

Since these files are needed at compile time, you should put `lua5.1-policy-dev`
in your `Build-Depends` field. In addition to these files it provides two
utilities:

  - `lua5.1-policy-apply` should be called in the `pre-build::` CDBS hook. It
    patches the current directory adding all needed files.

  - `lua5.1-policy-create-svnbuildpackage-layout` should be used to create the 
    svn repository of the debian packages. It build an svn-buildpackage ready 
    layout, adding the standard `debian/rules` file, a `debian/watch` template
    and a `debian/Makefile.Debian.conf` template.

So, to package a new library, just enter an svn repository and call:

> `lua5.1-policy-create-svnbuildpackage-layout {PKG_NAME}`

Then it should suffice to edit `debian/Makefile.Debian.conf`.

### Writing a `debian/Makefile.Debian.conf` file

You will find a template file called `Makefile.Debian.conf.sample` in these
`lua5.1-policy-dev` package (see `/usr/share/lua5.1-policy-dev/templates`).

Note that if you used the `lua5.1-policy-create-svnbuildpackage-layout`
utility to create the package svn repository, you will find a template
in `debian/`.

The `PKG_NAME` field is *mandatory*, the usual name of the library should be
used (like `curl` or `logging` for luacurl and lualogging).

  - `PKG_NAME=curl`

The next part is for the C part of the library (if any).

  - `CLIB_CFLAGS= -I src/`
  - `CLIB_LDFLAGS= $(shell pkg-config libcurl --libs)`
  - `CLIB_OBJS= src/lxplib.lo`
  - `VERSION_INFO=0:0:0`

Remember that all `.c` files have to produce a `.lo` files (in libtool
tradition).  List them in the `CLIB_OBJS` field. `CLIB_CFLAGS` and
`CLIB_LDFLAGS` have the standard meaning (see the [make manual][5]).
`VERSION_INFO` is libtool specific (read libtool documentation if in doubt).

The next part is for the lua part of the library (if any).

  - `LUA_HEADER=src/lxplib.h`
  - `LUA_SOURCES=src/lxp`
  - `LUA_MODNAME=lxp`
  - `LUA_TEST=tests/test.lua`

`LUA_MODNAME` will be the module name used inside lua (with `require`), if
empty `PKG_NAME` will be used.
`LUA_HEADER` points to the file (if any) that declares the
`luaopen_{LUA_MODNAME}` C function (if the library has a C part), if omitted
(and if the library has a C part) a trivial `.h` file will be automatically
generated.
`LUA_SOURCES` point to the `.lua` files or their root directory.  `LUA_TEST`
points to the test file that will be run once the library is compiled.

The next part is for pkg-config (if the library has a C part).

  - `PKG_VERSION=`
  - `PKG_LIBS_PRIVATE=`
  - `PKG_URL=`
  - `PKG_REQUIRES=`
  - `PKG_CONFLICTS=`

All these fields are explained in the manpage of pkg-config. The value of the
first field can be extracted from the control file using the following line:

> `$(shell dpkg-parsechangelog|grep ^Ver|cut -d ' ' -f 2|cut -d '-' -f 1)`

The next part is relative to debian libraries naming policy, and it can be
empty or `-` depending if the name of the package ends or not with a digit.
If it is the case the  package should be named
`liblua{LUA_VERSION}-{PKG_NAME}-{CABI}`, otherwise
`liblua{LUA_VERSION}-{PKG_NAME}{CABI}`.

  - `DEB_EXTRA_DASH=`

The last part is for adding hooks in `Makefile.Debian`. These hooks are called
in the following order.

  - `pre-all-hook`
  - `post-all-hook`
  - `pre-test-hook`
  - `pre-lua-dynamic-test-hook`
  - `pre-dynamic-link-hook`
  - `pre-app-dynamic-test-hook`
  - `pre-static-link-hook`
  - `pre-app-static-test-hook`
  - `pre-install-hook`
  - `post-install-hook` 

### The `rules` file

If you used the `lua5.1-policy-create-svnbuildpackage-layout` a standard
file is placed in `debian/` for you. If not, you can use this one:

<pre>
#!/usr/bin/make -f

include /usr/share/cdbs/1/class/makefile.mk
include /usr/share/cdbs/1/rules/debhelper.mk
include /usr/share/cdbs/1/rules/dpatch.mk

DEB_MAKE_BUILD_TARGET := all -f Makefile.Debian
DEB_MAKE_TEST_TARGET := test -f Makefile.Debian
DEB_MAKE_INSTALL_TARGET := install -f Makefile.Debian DESTDIR=$(DEB_DESTDIR)
DEB_DH_INSTALL_SOURCEDIR := $(DEB_DESTDIR)
pre-build::
	lua5.1-policy-apply
</pre>

### No `.install` files

Since all `.install` files contain a common part, it will be added
automatically by `Makefile.Debian` (if needed, e.g. if some files will be
installed somewhere). If you really need to ship more files, you may add a
`.install.in` file to add your paths. This `install.in` file will be
transformed in a `.install` substituting the `@@LUA_VERSION@@` string with the
`{LUA_VERSION}` value and appended with the standard paths if needed.

These are the lines added to `liblua{LUA_VERSION}-{PKG_NAME}{CABI}.install`

<pre>
/usr/share/lua/{LUA_VERSION}/*
/usr/lib/*.so.*
/usr/lib/lua/{LUA_VERSION}/*.so
</pre>

These are the lines added to `liblua{LUA_VERSION}-{PKG_NAME}-dev.install`

<pre>
/usr/lib/pkgconfig/*
/usr/include/lua{LUA_VERSION}/*
/usr/lib/*.so
/usr/lib/*.a
/usr/lib/*.la
</pre>

To install documentation, please use a `.docs` file.

### Multiple packages from the same source

It is possible that the same source package provides more (and distinct)
modules. This is the case for `luasql` that provides various backends.
`Makefile.Debian` is able to cope with this situation if it finds a set of
files (and not a single file) that match the pattern
`debian/*Makefile.Debian.conf`.

The variables `{PKG_NAME}` and `{LUA_MODNAME}` can be set using the `.` symbol
to separate modules.  In `luasql` the file `debian/mysql.Makefile.Debian.conf`
defines:

  - `PKG_NAME=sql.mysql`
  - `LUA_MODNAME=luasql.mysql`

The latter is the one expected since it is the same string used with `require`,
while the former is used to infer the deb package name, substituting `.` with
`-` when needed.

Notes on undefined symbols and packages dependencies
----------------------------------------------------

All lua libraries are not linked against `liblua5.1.so`, so all `lua_` and
`luaL_` prefixed symbols will appear as undefined (i.e. using `objdump -T` to
inspect them and look for symbols marked with `*UND*`). This is a *feature*
since:

  - The interpreter is statically linked with that library and exports all the
    needed symbols.  This means that it is able to dlopen the library with any
    troubles.

  - Any application linked against `liblua5.1.so` has these symbols defined,
    thus can load the library safely.

  - If libraries are linked against `liblua5.1.so` you would see `liblua5.1.so`
    resident in memory loading them from the lua interpreter (try `cat
    /proc/PID/maps`).  But the interpreter already had that code loaded.

As a side effect, all lua libraries do not depend on the `liblua5.1` package
(and must not declare it in the `Depends` field). 

All dependencies among other lua libraries must be declared. A `-dev` package
must depend on the `-dev` packages corresponding to the other lua libraries
that it uses, while the runtime package (non `-dev` package) must depend only
on the runtime package relative to the other lua libraries that it uses.

Notes on source package names
-----------------------------

All source packages should be named `lua-{PKG_NAME}` for consistency.  

-------------------------------------------------------------------------------
This file follows the markdown syntax. See [Markdown][1] and [lua markdown][2].

$Id: policy.txt 226 2006-10-09 07:56:51Z gareuselesinge $

[1]: http://daringfireball.net/projects/markdown/ "Markdown Homepage"
[2]: http://luaforge.net/projects/markdown/ "Lua implementation of markdown"
[3]: http://www.gnu.org/software/libtool/ "GNU Libtool"
[4]: http://pkgconfig.freedesktop.org/wiki/ "pkg-config tool"
[5]: http://www.gnu.org/software/make/manual/make.html "GNU Make"