Dist file format.

Structure and naming convention.

Dists are simple zip archives containing either source or binary files of a package. The name of the archive usually contains the package name and version. Binary dists usually have additional designations for the architecture and binary type.

For example a dist named lua-5.1.4.dist indicates that the package contains Lua version 5.1.4 and the lack of further designation means that the package contains source files. However a package named luajit-2.0-Windows-x86.dist would indicate that its contents is binaries of LuaJIT version 2.0 for 32bit Windows.

Contents of a source dist.

LuaDist does not force source dists to follow any prescribed structure but requires the contents to be contained inside a subdirectory with no additional files at the root of the archive. Usually this directory follows the naming convention of the dist filename but it is not required.

Sources are usually created from their original archives and two additional files are provided. First is dist.info which contains basic information about the package and its dependencies. Second is CMakeLists.txt file for CMake build backend.

Package maintainers have to provide both these files in order to create a working package. LuaDist cannot use other build systems such as makefiles or build scripts as it requires CMakeLists.txt file which contains instructions in CMake format which is later used to generate the final build instruction on various platforms. However creating this file does not usually require knowledge of CMake as simple and easy to use macros are prepared. See our tutorial section for examples.

Contents of binary dist.

Binary dists can contain anything you want installed into deployment directories. However we recommend following the structure here presented. Similarly to the source dist a binary dist has to contain a single subdirectory often following the filename naming convention. Inside this subdirectory the following directories are recommend:

bin - Directory for binaries, executable scripts and tools.
lib - Directory for dynamic and static libraries. NOTE: Dynamic libraries are preferred.
etc - Directory for configuration files.
include - Directory containing headers. NOTE: even binary packages are expected to provide headers.
share - Directory with shared data. Usually each package has its own subdirectory but modules can install data into other modules. e.g /share/lua/lmod is used to store all pure lua modules.

Additional paths are mentioned in our (tutorials)[/Documentation/Tutorials] section.

Format of dist.info file.

dist.info is the core file of any dist. It uniquely identifies the package and allows LuaDist to automatically resolve needed dependencies and relations to other packages. Following entries are available:

name - Required, lowercase alphanumeric name of the package. Can use "_.:-" characters as separators.
version - Required, alphanumeric string identifying the version of the package. Additional characters such as "_.:-" can be used.
arch - By default is set to Universal. Identifies the architecture of the package, alphanumeric string only.
type - By default is set to source. Identifies the type of the package, used to mark differences between compilers and usually processor types. This string is restricted to alphanumeric characters.
desc - Short description of the package.
author - Author or list of authors separated by commas.
maintainer - Maintainer of the dist. In case of multiple maintainers use comma to separate names.
url - URL to the homepage of the package.
depends - List of dependencies. 2DO: Expand on its syntax.
provides - List of packages of which functionality is provided by the package.
conflicts - List of packages that are in conflict with the package.
replaces - List of packages that are replaced by the package. NOT IMPLEMENTED.

For example a typical dist.info file looks as follows

-- LuaDist info file
name = "luadist"
version = "1.0.0"

desc = "Simple Lua Module Development, Distribution and Deployment Tool."
maintainer = "Peter Drahoš"
author = "Peter Drahoš, Peter Kapec, David Manura"
license = "MIT/X11"
url = "http://www.luadist.org"

depends = {
    "lua ~= 5.1",
    "luasocket >= 2.0.2",
    "luafilesystem >= 1.4.1",
    "unzip >= 6.0"
}

Additional information and notes for maintainers can be stored using comments. The encoding format of the file can be either UTF8 without cookie or ASCII.