LuaDist: Package Structure

drahosp edited this page Mar 12, 2013 · 1 revision

Structure and naming convention.

Packages in LuaDist are git repositories cloned from their original source or recreated from the original release archive files. The package repository must contain a dist.info file and a master branch with the lates source. Binary packages are stored along in the same repositories using systematically named detached branches (eg. Windows-x86 or Ubuntu-x86_64)

Versioning of packages is strict and must conform to the format LuaDist recognizes. For example the release source of lua-5.1.5 will have the tag 5.1.5 associated with it. Binary releases will be tagged as 5.1.5-Windows-x86 etc.

Contents of a source dist.

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 custom build scripts, it relies completely on CMake and the rules contained in CMakeLists.txt. 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. NOTE: On Windows this will also contain dynamic libraries
  • 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 inside share but modules can install data into other modules. Lua modules are stored in /lib/lua/. Additional paths are mentioned in our (tutorials)[Tutorials] section.

The dist.info file.

dist.info is the core file of any package. 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.