Debian Lua policy

Index

Conventions

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

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) and to build static applications (that do not need the liblua{LUA_VERSION}-{PKG_NAME}.so.{ABI} file to run.

pkg-config'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:

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}

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

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

Packages Contents (an example)

liblua5.1-expat0

liblua5.1-expat-dev

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:

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:

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).

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

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), 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_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).

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}.

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

The clean target is customizable using the following hooks.

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:

#!/usr/bin/make -f

include /usr/share/cdbs/1/class/lua.mk

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

/usr/share/lua/{LUA_VERSION}/*
/usr/lib/*.so.*
/usr/lib/lua/{LUA_VERSION}/LUA_MODNAME_UNDERSCORE.so

Where LUA_MODNAME_UNDERSCORE is LUA_MODNAME where . is replaced by _. These are the lines added to liblua{LUA_VERSION}-{PKG_NAME}-dev.install

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

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:

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

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.

  #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@@");
  }

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:

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 and lua markdown.

$Id: policy.txt 1398 2009-11-13 21:10:12Z gareuselesinge $