CMake

Cmake is a build system for C++ projects. It is an alternative to GNU autotools.

Installing

Downloading

You can either visit http://www.cmake.org and download the binary, or you can use wget:

$ wget http://www.cmake.org/files/v2.8/cmake-X.Y.Z.tar.gz

and untar it using tar:

$ tar xvzf cmake-X.Y.Z.tar.gz

Configuring

Cmake is straightforward to install. It is intended to replace autotools, but it still uses autotools to build it - but a little differently.

You can configure it by running:

$ ./bootstrap --prefix=/path/to/cmake/build

Then you can type make and make install, and you're good to go. Don't forget to add /path/to/cmake/build/bin to your $PATH!

Basics

Directory Layout

CMake builds software projects outside of the source directory.

When building with Autotools, the source code is compiled inside the source directory (usually by executing "./configure" and then "make"), and the software is only installed in the correct place when "make install" is executed.

Directory structure should look like this:

/path/to/application
                  /src        # <-- Contains CMake files like CMakeList.txt
                  /build      # <-- Directory from which you run the "cmake" command and "make/make install"

Hello World Project

See Scientific Computing Summer Workshop 2: Creating, Building, and Using Scientific Software for more info on libraries, linking, and building software in general.

Hello World Executable

You can create a simple hello world project in CMake by putting :

PROJECT( helloworld )
SET( hello_SRCS hello.cpp ) 
ADD_EXECUTABLE( hello ${hello_SRCS} )

PROJECT creates a name for your CMake project.

SET defines the variable "hello_SRCS" to contain a list of source code files (in this case, just the hello world code hello.cpp).

ADD_EXECUTABLE creates an executable from the list of source code files "hello_SRCS".

Hello World Library

PROJECT( mylibrary ) 
SET( mylib_SRCS library.cpp ) 
ADD_LIBRARY( my SHARED ${mylib_SRCS} )

PROJECT does the same thing as above

SET does the same thing as above

ADD_LIBRARY creates a library from the list of source code files in "mylib_SRCS". The keyword SHARED creates a shared library; to create a static library, just remove the keyword "SHARED".

Recall that linking to shared libraries tells the code where to find the libraries; linking to static libraries adds the library code used into the executable.

Debugging/Verbose Output

Adding the following will cause the created Makefiles to be more verbose:

SET( CMAKE_VERBOSE_MAKEFILE on )

Advantages and Disadvantages

Advantages

Cross-Platform

Most software projects that are built from source code have to distribute binaries for non-Unix systems (basically, Windows). However, using CMake, you can specify that you want to create a configuration for a software project that will work for a Make system (Unix), or another IDE like XCode (Mac) or Visual C++ (Windows). It's always good to let people choose their own IDEs/platforms (even if their IDEs/platforms suck a golf ball through a garden hose).

Backward-Forward Compatibility

You can specify which version of CMake to emulate when running CMake - so if you have CMake 2.6, you can make a CMakeLists.txt that works like CMake 2.4. You can also require users to have a certain minimum version of CMake (although this can sometimes be a pain for users.)

Doxygen Compatibility

You can use a macro to generate Doxygen documentation if Doxygen is available on the system. This is a convenient feature - anything that makes generating documentation easier is good.

Testing Capabilities

CMake makes running software tests very easy - you basically create your test and then add something like

ENABLE_TESTING()
ADD_TEST( testname testexecutable args )

into your CMakeLists.txt. This test system allows for downloading from a version control system and outputting test results in a variety of formats. This makes regression testers quite simple. You can even use a tool like CDash to display your outputs in a pretty format.

See http://www.cdash.org for more info on CDash.

Disadvantages

Cleaning Up To Reconfigure

If you're using autotools, it's straightforward to re-make or re-configure: you either run "make clean", or you just run configure again. Worst case scenario, you nuke config.log.

With CMake, there are a lot of files that CMake creates, and it's not clear which one needs to be deleted to re-configure with CMake. There's CMakeCache.txt, CMakeFiles/, CPackConfig.cmake, CPackSourceConfig.cmake, CTestTestfile.cmake, and cmake_install.cmake. So, if I want to reconfigure, I have to blow away all of these files. Otherwise, changing the CMake command and running it again doesn't implement any of the changes.

Finding Packages

Using the CMake function find_package() can cause many difficulties, because Cmake has an unusual way of dealing with software dependencies. Unlike GNU autotools, you can't always point CMake to a path where you built something and expect it to "just work". (Boost is an excellent example of this.)

CMake contains pre-existing "rules" for finding things that can make life difficult for people who specify --prefix when they install things. CMake contains a list of rules in /path/to/cmake/X.X/Modules/cmake-X.X/. These rules will be in files named Find(Package).cmake (e.g. FindBoost.cmake).

While these can be customized, they are cryptic and can take a long time to try and figure out. Due to these esoteric "find rules", it can be difficult to get CMake to "pick up" on custom installs of third-party packages like Boost. This isn't the case with all third-party packages, just the ones for which "find rules" exist.

This can also cause unfortunate consequences, such as (if your user is on a Mac, like me) requiring users to install Boost through ridiculous third-party software packages like MacPorts, which build everything they need from source, taking forever and requiring still more ridiculous software packages like zlib, which requires the ridiculous IDE XCode 3.1, which is no longer available on Mac's Developers page, or the also ridiculous IDE XCode 3.2, which requires you to upgrade your entire operating system to 10.6 so that you can successfully install a piece of software (iPhone SDK) that you don't want, don't need, and will never ever use because you don't own an iPhone. Or, you can shell out a hundred dollars for XCode 4.0, with all kinds of useless features you'll also never use, so that you can be part of the elite "Mac Developers Club for Snobs."

You see what you did??? And you thought you were just requiring Boost.

Incidentally, many consider this an "advantage". Whatever.

PITARE

CMake uses PITARE - pain-in-the-ass regular expressions. In other words, not PCRE - Perl-compatible regular expressions.

Smart software uses Perl-compatible regular expressions. This makes sure that a regular expressions ninja can be a ninja in Vim, Emacs, Perl, PHP, sed, etc. But, sadly, not CMake.

See CMake FAQ for details.

Presentations

Professor James Sutherland's presentation on using CMake, part of the 2010 Scientific Computing Summer Workshop, is here: File:CMake Sutherland.pdf

This presentation contains an example of a "Hello World" program built with CMake.

References

• Learning CMake slides (good overview of CMake): http://www.elpauer.org/stuff/learning_cmake.pdf
• Explanation of how the find_package() function works: http://www.itk.org/Wiki/CMake:How_To_Find_Libraries