LuaDist: Creating Packages

drahosp edited this page Apr 2, 2013 · 3 revisions

Creating Packages

Creating source packages is relatively straightforward process, for most Lua modules this does not require any knowledge of CMake. However every source dist needs to provide a CMakeLists.txt file and dist.info so LuaDist can automatically deploy it. Since writing CMake is rather painful especially for beginners we provide and useful set of macros to aid most projects.

CMakeLists.txt files describe how to build source packages. These are not required inside binary packages but are the only supported way of building source packages in LuaDist. For basic informarion about CMake visit its online documentation.

For convenience we provide few useful macros in a CMake include file called dist.cmake. Additionally for Lua based project we provide additional macros such as install_lua_module using the lua.cmake, both will be used in the examples.

Some LuaDist conventions to keep in mind

  • No versioning of libraries or any other files if it can be helped.
  • No versioning in install paths.
  • By default only shared libraries.
  • Restrict use of external tools and commands. Avoid dependencies until absolutely necessary.
  • Always mind that the package may be installed manually.

Creating Modules

Writing CMake build scripts is usually easy, but it depends on what we want to build and install. Most modules can be categorized into the following categories with increasing complexity:

  1. Example: Lua module - Easiest to build and install are pure Lua or C-based modules with no dependencies.

  2. Example: C module - Buiding C-based Lua modules that do not need external dependencies is easy when using the provided macro.

  3. Example: C module liking to library - Buiding C-based Lua modules that depend on external libraries requires to instruct CMake to find and use thes libraries. This is a bit more complicated than building pure Lua or C-based modules with no dependencies, but doable for everyone with minimum programming skills and no CMake knowledge.

  4. Example: Building Libraries - Most difficult are situations when you must build the external dependencies yourself, which is often the case when these external libraries are not provided by system or package manager. Writing a CMake script to build external dependencies often needs a good understanding of make tools (autoconf, automake, etc.) or a good documentation with detailed description of build steps.

  5. non C-based modules - Not the most complicated, but a special category are bindings to other languages than C/C++, e.g. LuaJava, LuaInterface etc. CMake is primarily targeted to C/C++ and JAVA, other languages are not directly supported. However such modules are rare, most CMake script writers won't deal with them and LuaDist already provides some of them.

Without Macros (For advanced CMake users)

Install paths

LuaDist uses the following install paths and it is up to the maintainer to use the correct variables when installing. By default we recommend the following setup:

# Primary paths
set ( INSTALL_BIN bin CACHE "Directory to store executables in." )
set ( INSTALL_LIB lib CACHE "Directory to store libraries in." )
set ( INSTALL_INC inc CACHE "Directory to store headers in." )
set ( INSTALL_ETC etc CACHE "Directory to store configuration files in." )
set ( INSTALL_SHARE shade CACHE "Directory to store data in." )

# Recommended data paths
set ( INSTALL_DATA ${INSTALL_SHARE}/${PROJECT_NAME} CACHE "Directory to store package data in." )
set ( INSTALL_EXAMPLE ${INSTALL_DATA}/example CACHE "Directory to store examples in." )
set ( INSTALL_TEST ${INSTALL_DATA}/test CACHE "Directory to store tests in." )
set ( INSTALL_DOC ${INSTALL_DATA}/doc CACHE "Directory to store documentation in." )

For Lua module use following paths.

set ( INSTALL_LMOD ${INSTALL_LIB}/lua CACHE "Directory to store lua modules in." )
set ( INSTALL_CMOD ${INSTALL_LIB}/lua CACHE "Directory to store lua binary modules in." )

Installing files using these paths is usually done as follows:

install ( TARGETS lua luac
  RUNTIME DESTINATION ${INSTALL_BIN}
  LIBRARY DESTINATION ${INSTALL_LIB}
  ARCHIVE DESTINATION ${INSTALL_LIB} )
install ( FILES etc/strict.lua DESTINATION ${INSTALL_LMOD} )
install ( DIRECTORY doc/ DESTINATION ${INSTALL_DOC} )

NOTE: LuaDist can now make use of the COMPONENT information used in the install command. Following components are recognized: Runtime, Library, Header, Documentation, Example, Test, Other and Unspecified

Submitting

If you want a module to be added to the LuaDist Repository Issues, please create an issue with a link to the github repository to clone. Alternatively you can create pull requests to existing modules referenced in the Repository.