Writing Source Dists

Creating source dists is relatively straightforward process. For most Lua modules this does not require any knowledge of CMake. However every source dist needs to provide this file and dist.info so LuaDist can automatically deploy it.

CMakeLists.txt file

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. Please mind the following guidelines for creating CMake build files for LuaDist when not relying on our macros.

Install paths

LuaDist does not configure install paths in dist so it is up to the maintainer to provide correct defaults so binary dists are correctly created. The following variables are recommended by LuaDist maintainers:

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_DATA 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 dists use following paths.

SET(INSTALL_LMOD share/lua/lmod CACHE "Directory to store lua modules in.")
SET(INSTALL_CMOD share/lua/cmod CACHE "Directory to store lua binary modules in.")

Installing files using these paths is usually done as follows:

INSTALL(TARGETS lua luac DESTINATION ${INSTALL_BIN})
INSTALL(FILES etc/strict.lua DESTINATION ${INSTALL_LMOD})
INSTALL(DIRECTORY doc/ DESTINATION ${INSTALL_DOC})

For convenience we provide this defaults and few useful macros in a CMake include file called dist.cmake.

Other conventions.

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

Writing CMakeLists.txt

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. Pure Lua module - Easiest to build and install are pure Lua or C-based modules with no dependencies.

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

3. C-based Lua module with external dependencies - 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. Building external dependencies - 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.

Important

Writing CMake scripts for complex modules may be complicated by platform or compiler specifics that must be considered - especially when the module was developed for multiple platforms.

Note

If you are interested in learning to write your own scripts, we recomend you to analyze CMake scripts provided by LuaDist - they range from very simple to very complex. Feel free to ask for pointers in the mailing list.