Cross-Platform Software Development Using CMake

As a software developer, you probably organize source code in subdirectories. Different subdirectories can represent libraries, executables, testing or even documentation. We now can enable or disable subdirectories to build parts of our project and skip other parts. To tell CMake to process a subdirectory, use the SUBDIRS command. This command tells CMake to go to the specified subdirectory and find the CMakeLists.txt file. Using this command, we can now make our project a bit more organized. We move all the library files to the library subdirectory Library, and the top-level CMakeLists.txt now looks like this:

PROJECT(MyProject C)
SUBDIRS(SomeLibrary)
INCLUDE_DIRECTORIES(SomeLibrary)
ADD_EXECUTABLE(MyProgram main.c)
TARGET_LINK_LIBRARIES(MyProgram MyLibrary)

The INCLUDE_DIRECTORIES command tells the compiler where to find header files for main.c. So, even if your project has five hundred subdirectories and you move all your sources in, you will not have any problems getting dependencies to work. CMake does all this for you.

So, now we want to "cmakify" zlib. Start with a simple CMakeLists.txt file:

PROJECT(ZLIB)
# source files for zlib
SET(ZLIB_SRCS
adler32.c   gzio.c      
inftrees.c  uncompr.c
compress.c  infblock.c
infutil.c   zutil.c
crc32.c     infcodes.c 
deflate.c   inffast.c  
inflate.c   trees.c
)
ADD_LIBRARY(zlib ${ZLIB_SRCS})
ADD_EXECUTABLE(example example.c)
TARGET_LINK_LIBRARIES(example zlib)

Now you can build it. However, there are couple of little things to remember.First, zlib needs unistd.h on some platforms. So, we add this test:

INCLUDE (
  ${CMAKE_ROOT}/Modules/CheckIncludeFile.cmake)
CHECK_INCLUDE_FILE(
  "unistd.h" HAVE_UNISTD_H)
IF(HAVE_UNISTD_H)
  ADD_DEFINITION(-DHAVE_UNISTD_H)
ENDIF(HAVE_UNISTD_H)

Also, we have to do something about shared libraries on Windows. Zlib needs to be compiled with -DZLIB_DLL, for proper export macros. So, we add the following option:

OPTION(ZLIB_BUILD_SHARED
  "Build ZLIB shared" ON)
IF(WIN32)
  IF(ZLIB_BUILD_SHARED)
    SET(ZLIB_DLL 1)
  ENDIF(ZLIB_BUILD_SHARED)
ENDIF(WIN32)
IF(ZLIB_DLL)
  ADD_DEFINITION(-DZLIB_DLL)
ENDIF(ZLIB_DLL)

This works, but there is a better way. Instead of passing ZLIB_DLL and HAVE_UNISTD_H as compiler flags, we can configure an include file. We do that by preparing an input file with tags for CMake. An example of the include file for zlib would be zlibConfig.h.in:

#ifndef _zlibConfig_h
#define _zlibConfig_h
#cmakedefine ZLIB_DLL
#cmakedefine HAVE_UNISTD_H
#endif

Here, the \#cmakedefine VAR is replaced with \#define VAR or with /* \#undef VAR */, depending on whether VAR is defined. We tell CMake to create the file zlibConfig.h using the following CMake command:

CONFIGURE_FILE(>
  ${ZLIB_SOURCE_DIR}/zlibDllConfig.h.in
  ${ZLIB_BINARY_DIR}/zlibDllConfig.h)

With the information in this article you will be able to start using CMake for most of your everyday tasks. Except, now you are able to connect to your friend's AIX system and build your project, if your code is portable enough. Also, the CMake files are much easier to read than Makefiles, so your friend can check what you missed.

This example, however, only scratches the surface; CMake is capable of doing several other tasks. With its face-lift in version 1.6, it can now do platform independent TRY_RUN and TRY_COMPILE builds, which come in handy when you want to test the capabilities of the system. It natively supports only C and C++, but there is limited support for building Java files. With a little effort, you can build anything from Python- or Emacs-compiled scripts to LaTeX documents. By using CMake with the testing framework Dart, you can do platform-independent regression testing. If you want to go even further, you can use CMake's C API to write a plug-in for CMake, which adds your own command to the list of existing commands.

CMake is being actively used in several projects such as VTK and ITK. Its benefits are enormous in traditional software development, however they become even more apparent, when portability is necessary. By using CMake for software development, your code will be significantly more "open", because it will build on a variety of platforms.

Autoconf

Automake

CMake

public.kitware.com/Dart

ITK

Python

VTK

ZLib

Andrej Cedilnik (andy.cedilnik@kitware.com) is a senior software engineer at Kitware Inc., a small business devoted to imaging, visualization and computer graphics. He is one of the developers behind CMake, and in his spare time he is a Linux evangelist.