Example: Building Libraries

Building Libraries

Building external dependencies and libraries is not trivial and requires either:

• that the external dependency has a detailed documentation how to build it
• you have a good understanding of make tools (autoconf, automake, etc.)
• external dependencies use some other build tools e.g. SCons, Bakefiles etc. for building

At least moderate knowledge of CMake is recomended. If you fulfill above criteria then all you have to do is:

• define project name, usually the name of the module
• include dist.cmake
  • this will set up all variables that contain installation paths
• check platform/compiler specifics
• generate a configuration header if needed (requires to write down a template file of the configuration header)
• instruct CMAKE to search for external dependencies if needed
  • check if external dependencies were found
• create the library
• link library against other external dependencies
• write commands for installing library and other files

Here is an commented example for the Expat library:

Write a configuration template file: expat_config.h.cmake

This file contains defines like this

/* Define to 1 if you have the `bcopy' function. */
#cmakedefine HAVE_BCOPY ${HAVE_BCOPY}

and during configuration phase is evaluated to e.g.

#define HAVE_BCOPY 1

depending whether compiler finds bcopy function.

Write CMakeLists.txt

The following example shows how configuration of headers can be implemented. On some libraries this is obsolete but for the purpose of example we will show a more complex situation.

# Copyright (C) 2007-2011 LuaDist.
# Created by Peter Kapec
# Redistribution and use of this file is allowed according to the terms of the MIT license.
# For details see the COPYRIGHT file distributed with LuaDist.
# Please note that the package source code is licensed under its own license.
project ( libexpat C ) # projects name

# CMake configuration:
cmake_minimum_required ( VERSION 2.6 )	# set minimum CMake version

# Include dist.cmake, this defines install paths and some useful macros
include ( dist.cmake )

## Generating expat_config.h file:
message ( "Configure: Expat - generating expat_config.h:" )

# include functions for checking stuff
include (CheckIncludeFiles)     # check for headers
include (CheckFunctionExists)	# check for functions
include ( CheckSymbolExists )     # check for symbols
include ( TestBigEndian )         # check endiandnes
include ( CheckTypeSize )         # check size of types

test_big_endian ( ENDIAN_TEST )	 # check endiandness and set byte order
if ( ENDIAN_TEST )
	set ( BYTEORDER 4321 )	
else ()
	set ( BYTEORDER 1234 )
endif ()

check_function_exists ( bcopy HAVE_BCOPY )	# check if bcopy exist
check_include_files ( dlfcn.h HAVE_DLFCN_H )	# check if dlfcn.h header exist
check_include_files ( fcntl.h HAVE_FCNTL_H )
check_function_exists ( getpagesize HAVE_GETPAGESIZE )	# check if function getpagesize exist
check_include_files ( inttypes.h HAVE_INTTYPES_H )
check_function_exists ( memmove HAVE_MEMMOVE )
check_include_files ( memory.h HAVE_MEMORY_H )
check_function_exists ( mmap HAVE_MMAP )
check_include_files ( stdint.h HAVE_STDINT_H )
check_include_files ( stdlib.h HAVE_STDLIB_H )
check_include_files ( strings.h HAVE_STRINGS_H )
check_include_files ( string.h HAVE_STRING_H )
check_include_files ( "sys/stat.h" HAVE_SYS_STAT_H )
check_include_files ( "sys/types.h" HAVE_SYS_TYPES_H )
check_include_files ( unistd.h HAVE_UNISTD_H )
set ( PACKAGE_BUGREPORT "[email protected]" )
set ( PACKAGE_NAME "expat" )
set ( PACKAGE_STRING "expat 2.0.0" )
set ( PACKAGE_TARNAME "expat" )
set ( PACKAGE_VERSION "2.0.0" )
check_include_files ( "stdlib.h;stdarg.h;string.h;float.h" STDC_HEADERS )

#WARNING: Following tests might NOT be the original test as found in original ./configure script!
#TODO: Someone has to check it, pliz (I'm not an automake guru).

# how to check WORDS_BIGENDIAN ? maybe:
set ( WORDS_BIGENDIAN ${ENDIAN_TEST} )

# TODO:
#/* Define to __FUNCTION__ or "" if `__func__' does not conform to ANSI C. */
#cmakedefine __func__

# TODO:
#/* Define to empty if `const' does not conform to ANSI C. */
#cmakedefine const

#/* Define to `long' if <sys/types.h> does not define. */
check_type_size ( "off_t" SIZEOF_OFF_T )	# check size of off_t
if ( HAVE_SIZEOF_OFF_T )
	set (HAVE_OFF_T 1)
else ()
	set (HAVE_OFF_T 0)
	set (off_t "long")
endif ()

#/* Define to `unsigned' if <sys/types.h> does not define. */
check_type_size ( "size_t" SIZEOF_SIZE_T )
if ( HAVE_SIZEOF_SIZE_T )
	set ( HAVE_SIZE_T 1 )
else ()
	set ( HAVE_SIZE_T 0 )
	set ( size_t "unsigned" )
endif ()

# all checks have been tested (all variables from expat_config.h.cmake were set)
# so replace all #cmakedefine's in xpat_config.h.cmake with correct walues
configure_file ( ${CMAKE_CURRENT_SOURCE_DIR}/expat_config.h.cmake ${CMAKE_CURRENT_BINARY_DIR}/expat_config.h )	
# CONFIGURE_FILE operates on CONFIGURE_FILE(source_file destination_file) where
# source_file - uses ${CMAKE_CURRENT_SOURCE_DIR} path - it is our source dir
# destination_file - uses ${CMAKE_CURRENT_BINARY_DIR} path - we are doing out-of-source build, so this won't polute Expat sources 

message ( "Configure: Expat - done." )
# end of generating expat_config.h file:

## Expat library
# set include path to include lib directory and our build directory stored in ${CMAKE_CURRENT_BINARY_DIR}
include_directories ( lib ${CMAKE_CURRENT_BINARY_DIR}) 

# Expat library consist of these 3 files
set ( SRC_EXPATLIB lib/xmlparse.c lib/xmlrole.c lib/xmltok.c )

# add -DHAVE_EXPAT_CONFIG_H to compiler to tell we have our own expat_config.h file
add_definitions ( -DHAVE_EXPAT_CONFIG_H )

# create the expat library using source files stored in ${SRC_EXPATLIB} and add .def file stored in ${DEF_FILE} if necessary
add_library ( expat SHARED ${SRC_EXPATLIB} lib/libexpat.def )

install_library ( expat )
install_header ( lib/expat.h lib/expat_external.h )
install_data ( COPYING Changes README )
install_doc ( doc/ )

Note:

This tutorial only some aspects of translating libraries to CMake. It is a guide how to proceed and other libraries may require you to write more complex scripts, especially when you need to select files or compiler flags for platform/copiler specific tests. Please see other libraries providied by LuaDist for examples.

Alternatively you can submit an issue to the Repository Issues if you need help.