Debian Lua policy
==============================

Index
-----

* [Conventions](#ch-conventions)
* [Rationale](#ch-rationale)
* [Packages Contents](#ch-pkgcontents)
  * [Run time package: `liblua{LUA_VERSION}-{PKG_NAME}{CABI}` ](#sec-runtime)
  * [Development package: `liblua{LUA_VERSION}-{PKG_NAME}-dev` ](#sec-devel)
  * [Packages Contents (an example)](#sec-pkgconsample)
* [Creating a package in a quick and clean way](#ch-quickandclean)
  * [The `lua5.1-policy-dev` package](#sec-pkgpolicydev)
  * [Writing a `debian/Makefile.Debian.conf` file](#sec-makefileconf)
  * [The `rules` file](#sec-rules)
  * [No `.install` files](#sec-install)
  * [Multiple packages from the same source](#sec-multipkg)
  * [Automatically testing your package](#sec-autotest)
* [Notes on undefined symbols and packages dependencies](#ch-notesundef)
* [Notes on source package names](#ch-notessource)

  
Conventions <a id="ch-conventions"></a>
-----------

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 <a id="ch-rationale"></a>
---------

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.

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 <a id="ch-pkgcontents"></a>
-----------------

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

### Run time package: `liblua{LUA_VERSION}-{PKG_NAME}{CABI}` <a id="sec-runtime"></a>

  - `/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` <a id="sec-devel"></a>

  - `/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) <a id="sec-pkgconsample"></a>

*`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/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-expat-dev/us/*html`
  - `/usr/lib/pkgconfig/lua5.1-expat.pc`

Creating a package in a quick and clean way <a id="ch-quickandclean"></a>
-------------------------------------------

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 <a id="sec-pkgpolicydev"></a>

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 the following
utility:

  - `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 <a id="sec-makefileconf"></a>

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_LDFLAGS_STATIC= $(shell pkg-config libcurl --libs --static)`
  - `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]), while
the `CLIB_LDFLAGS_STATIC` variant is used when building the statically linked
test application (if `LUA_TEST` is not empty).
`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_CPART=lxp`

`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_CPART` 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.
`LUA_MODNAME_CPART` is the suffix of the C function to load the module (if empty
`LUA_MODNAME` is used). 

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 clean target is customizable using the following hooks.

  - `pre-clean-hook`
  - `post-clean-hook`

### The `rules` file <a id="sec-rules"></a>

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/lua.mk
</pre>

### No `.install` files <a id="sec-install"></a>

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, substituting the `@@DEB_HOST_MULTIARCH@@` with the
corresponding `dpkg-architecture -qDEB_HOST_MULTIARCH` 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}/LUA_MODNAME_UNDERSCORE.so
</pre>

Where `LUA_MODNAME_UNDERSCORE` is `LUA_MODNAME` where `.` is replaced by `_`.
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
</pre>

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

### Multiple packages from the same source <a id="sec-multipkg"></a>

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.
 
### Automatically testing your package <a id="sec-autotest"></a>

If you specify the `LUA_TEST` variable in the `Makefile.Debian.conf` file, three
tests will be performed after compilation and before building the package.

* `lua-dynamic-test` calls the lua standard interpreter in the following way:
  `lua{LUA_VERSION} -l LUA_MODNAME LUA_TEST` (note that if you set `LUA_TEST` to 
  something like `tests/test.lua arg1 arg2` the arguments will be passed to 
  the test). The lua interpreter should found the `.lua` and eventual `.so` files
  in the current working directory. For that purpose `LUA_MODNAME` is used to
  make a symbolic link pointing to the real `.so` file during build phase. If
  you need a different setting, set an hook for `pre-lua-dynamic-test-hook`
* `app-dynamic-test` builds a minimal application that is linked (at compile time)
  with the C par of the library (if any). This means that the lua interpreter 
  should load the C part of the library calling a function that is already
  linked with the binary, and not use dlopen as in the previous test. This
  minimal application is `app.c` that includes a minimal configuration file
  that is tuned using the variables defined in `Makefile.Debian.conf` (see the
  [code snippet](#snippet-appconf) at the end of this section).
  The variables between `@@` will be replaced with their values (the
  `_UNDERSCORE` is simply the result of replacing `.` by `_`). This code means 
  that when a `require` is issued for `LUA_MODNAME_CPART` the corresponding
  C function `luaopen_LUA_MODNAME_CPART_UNDERSCORE` is called
* `app-static-test` behaves exactly as `app-dynamic-test`, but libtool is run
  to statically link the C code of the library into the `app` executable

<pre id="snippet-appconf">
  &#x0023;include "@@LUA_HEADER@@"
  static void app_open(lua_State* L){
    lua_getglobal(L,"package");
    lua_getfield(L,-1,"preload");
    lua_pushcfunction(L,luaopen_@@LUA_MODNAME_CPART_UNDERSCORE@@);
    lua_setfield(L,-2,"@@LUA_MODNAME_CPART@@");
  }
</pre>

Notes on undefined symbols and packages dependencies <a id="ch-notesundef"></a>
----------------------------------------------------

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 <a id="ch-notessource"></a>
-----------------------------

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 1608 2011-07-19 21:36:28Z 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"
