Example: C module linking to library

Building C modules with Dependencies

CMake scripts can search for required files and libraries when building to satisfy the modules dependencies. Dependencies can be provided by LuaDist itself or by other means, for example by using the host operating system package manager. The following steps are usually needed to build modules with dependencies:

• Define project name - usually the name of the module.
• Copy the cmake macro folder directory from our Tools
• Instruct CMake to search for dependencies.
• Check if all external dependenies were found.
• Create a module using the provided macro.
• Link module against external dependencies.
• Write commands for installing module and other files.

Here is an commented example fo the LuaExpat module:

# Define projects name
# The C tells CMake to check for C compiler
project ( luaexpat C )

# Define minimun version of CMAKE for compatibility
cmake_minimum_required ( VERSION 2.8 )

# Include dist.cmake - defines LuaDist related macros and install paths
# Also include lua macros
include ( dist.cmake )
include ( lua )

# LuaExpat needs Lua but that dependency is conveniently provided by the macros. 
# Additionally luaexpat depends on the Expat library so lets search for it
# If successful this will define EXPAT_* variables such as EXPAT_INCLUDE_DIR and EXPAT_LIBRARIES
find_package ( EXPAT REQUIRED ) # REQUIRED ensures that Expat must be found
include_direcotries ( ${EXPAT_INCLUDE_DIR} ) # We need Expats's headers, so include them

# Build LuaExpat module
install_lua_module ( lxp src/lxplib.c src/lxp.def LINK ${EXPAT_LIBRARIES} )
install_lua_module ( lxp.lom src/lxp/lom.lua )

# Install Data (points to root of the project specific data folder)
install_data ( README )

# Install Documentation ( the tailing "/" means we want to install the contents of doc not doc itself )
install_doc ( doc/ )

# Install test suite
install_test ( test/ )

Notes

FIND_PACKAGE functionality

Finding external dependencies (libraries) is done by calling CMake's FIND_PACKAGE(XYZ) function, where XYZ is the name of the external dependency.

CMake's installation contains a large set of prepared scripts that are capable to find many existing external dependencies - see CMake's documentation

In our example if FIND_PACKAGE(EXPAT) finds Expat, then the variable EXPAT_FOUND will be set, otherwise EXPAT_NOTFOUND will be set.

If the external dependency is optional (the module can be build without it), then we can use following form:

find_package ( EXPAT )
if ( EXPAT_FOUND )
  # Expat was found, so we can use it.
else ()
  # Expat was NOT found...
endif ()	

All CMake's calls to FIND_PACKAGE(XYZ) usually set at least the following 3 variables:

XYZ_FOUND	# XYZ found
XYZ_INCLUDE_DIR # stores path to XYZ's headers
XYZ_LIBRARIES   # stores XYZ's libraries

Please see into CMake's find scripts what they define, because there are often more variables that are set up.

Using the REQUIRED directive the external dependency must be found if it is not found, then the build process will fail with an error message.

If the find modules you need are not distributed with CMake you can add your own into the cmake folder. Including dist.cmake will allow you to transparently use find_package with your find modules.

Searching for depencencies

If you need to find an external dependency that is not already included in CMake FIND_PACKAGE functionality, you can write a find script similar to those installed by CMake - they are well documented.

You do this by searching for headers and libraries with two commands. E.g. for the lmapm module we need to find mapm library and mapm header:

# search for m_apm.h header and store the path to this header into MAPM_INCLUDE_DIR variable
find_path ( MAPM_INCLUDE_DIR NAMES m_apm.h ) 

# search for mapm library (may be named mapm or libmapm; sufix is identified by CMake) 
# and store the path to this library into MAPM_LIBRARY variable
find_library ( MAPM_LIBRARY NAMES mapm libmapm )

See CMake's documentation and existing find scripts in CMake for details.