Posts Tagged ‘CMake’

CMake part 3: Finding libraries

March 7, 2010

Over time, I find myself more and more interested in CMake. That’s because I write many little programs, and those that use makefiles routinely break as I switch OS.

The last one was a program that depended on libpng. When I tried to compile it on Mac OS X, it failed to find the library. That’s because on Linux libpng.so is simply in /usr/lib and png.h is in /usr/include, both of which are in the compiler’s search path, so that all you need to do is add “-lpng” when linking.

But on a Mac libpng.dylib (yes, shared libraries on a Mac have .dylib extension) is in /usr/X11/lib and png.h is in /usr/X11/include that are not in the compiler’s search path, so that when compiling you need to add “-I/usr/X11/include” and when linking “-L/usr/X11/lib -lpng”.

The solution was not to keep two separate makefiles, but rather to throw away the makefile and replace it with a CMakeLists.txt

Which brings us to the question: how to link with libraries using CMake?

There are two ways, the first is the find_package command, the other is the find_library command.

Let’s start with find_package. CMake “knows” about many widely used libraries. For them, there is a script to find them in all supported platforms. So, to use a library all you need to do is find it with the find_package command. Here is a simple example of a program that uses threads and so depends on “-lpthread”, main.cpp:

#include <iostream>

using namespace std;

void *thread(void *argv)
{
    cout<<"Into a spawned thread"<<endl;
}

int main()
{
    pthread_t t;
    pthread_create(&t,NULL,thread,NULL);
    pthread_join(t,NULL);
    cout<<"Back in main thread"<<endl;
}

and here is the CMakeLists.txt file:

cmake_minimum_required(VERSION 2.6)
project(TEST)

## Target
set(TEST_SRCS main.cpp)
add_executable(test ${TEST_SRCS})

## Link libraries
find_package(Threads REQUIRED)
target_link_libraries(test ${CMAKE_THREAD_LIBS_INIT})

As can be seen, the first parameter passed to find_package is the name of the package, the second is “REQUIRED” and means that if the library could not be found, CMake should stop and print an error message.

Once the library is found, you have to say which executable needs it (because a single CMakeLists.txt can be used to produce many executable by just using more add_executable commands). This is achieved with the target_link_libraries command that appends a library to the list of libraries an executable needs. The first parameter is the executable name, the second is the library. Note that find_library generates a variable that contains the name of the library, in this case the name is CMAKE_THREAD_LIBS_INIT. This strange name is an exception, usually all find_package scripts create a variable with the name <libraryname>_LIBRARY.

Now a more complex example: the libpng issue I talked about earlier. It is more complex because you don’t just need to add a library when linking, you also need to tell the compiler where is the png.h file when compiling. Luckily, CMake has a package for libpng that does all that, and here is the CMakeLists.txt example:

cmake_minimum_required(VERSION 2.6)
project(TEST)

## Targets
set(TEST_SRCS test.cpp)
add_executable(test ${TEST_SRCS})

## Link libraries
find_package(PNG REQUIRED)
include_directories(${PNG_INCLUDE_DIR})
target_link_libraries(test ${PNG_LIBRARY})

The find_package command finds the PNG library, target_link_libraries adds the library to the list of libraries the executable needs, and include_directories adds the directory where the .h file is when compiling.

But this isn’t the end. Other than libraries there are collections of libraries. And CMake supports them too. One example are the boost libraries. There is no single libboost.so to link to; instead every sub-library has its .so file. So there should be a way to link only with the desired sub-libraries. This is an example CMakeLists.txt that does that:

cmake_minimum_required(VERSION 2.6)
project(TEST)

## Target
set(TEST_SRCS main.cpp)
add_executable(test ${TEST_SRCS})

## Link libraries
set(BOOST_LIBS thread date_time system)
find_package(Boost COMPONENTS ${BOOST_LIBS} REQUIRED)
target_link_libraries(test ${Boost_LIBRARIES})
find_package(Threads REQUIRED)
target_link_libraries(test ${CMAKE_THREAD_LIBS_INIT})

In this case we initialize a variable with the sub-libraries we want (boost.thread, boost.date_time and boost.system). Then we call find_package with the library name (Boost), the word COMPONENTS followed by the list of sub-libraries and as usual the REQUIRED word. Since boost.thread depends on the system’s thread library, we also use another find_package command to link with threads.

This ends the examples of find_package, but there is one last issue: what if we need a library for which there isn’t a package script? The solution is to use the find_library command. It will search in the system paths for the needed library. Here is an example that uses the command to find the Poco libraries:

cmake_minimum_required(VERSION 2.6)
project(TEST)

## Target
set(TEST_SRCS main.cpp)
add_executable(test ${TEST_SRCS})

## Link libraries
find_library(POCO_FOUNDATION PocoFoundation)
find_library(POCO_NET PocoNet)
target_link_libraries(test ${POCO_FOUNDATION} ${POCO_NET})
find_package(Threads REQUIRED)
target_link_libraries(test ${CMAKE_THREAD_LIBS_INIT})

The find_library command takes two parameters, the first is the variable where the found library will be stored, and the second is the library name (the name is camelcase in this example because Poco libraries are camelcase, the library name is really libPocoFoundation.so).
References: CMake wiki

CMake part 2: Compiler flags

December 21, 2009

It’s not the first time I talk about CMake in this blog, for the introduction read here. Now it’s time to explore the CMake syntax further. The first CMakeLists.txt looked like this:

cmake_minimum_required(VERSION 2.6)
project(HELLO)

set(HELLO_SRCS main.cpp foo.cpp)
add_executable(hello ${HELLO_SRCS})

As already explained, it successfully creates an executable called “hello” using the main.cpp and foo.cpp source files. But let’s see exactly what CMake does to compile these files. To do so, it is possible to use the commands:

mkdir build && cd build
cmake ../
make VERBOSE=1

The interesting thing here is the VERBOSE=1 option. By default CMake hides the options passed to the compiler, and displays a higher level status indicator with the build completion percentage together with the name of the file currently being built (a much more elegant solution than autoconf). But if the goal is to see the compiler flags used, it is always possible to override this behaviour with the VERBOSE=1 option.

Here is the relevant part of the printout:

[...]
[ 50%] Building CXX object CMakeFiles/hello.dir/main.cpp.o
/usr/bin/c++     -o CMakeFiles/hello.dir/main.cpp.o -c /tmp/cmaketest/main.cpp
[100%] Building CXX object CMakeFiles/hello.dir/foo.cpp.o
/usr/bin/c++     -o CMakeFiles/hello.dir/foo.cpp.o -c /tmp/cmaketest/foo.cpp
Linking CXX executable hello
/usr/bin/c++      CMakeFiles/hello.dir/main.cpp.o CMakeFiles/hello.dir/foo.cpp.o  -o hello
-rdynamic
[...]

Now, if you’ve read my previous blog post on GCC’s compiler flags, you might probably not like what you see, since no optimization flag has been passed to GCC and as a result, your program won’t run as fast as it should.

That’s because no build type has been specified to CMake. The build type is a feature most IDE have, it allows you to compile your program in “debug” mode, for easily single-stepping through it with a debugger, or in “release” mode, with speed optimization enabled.

To fix this you simply need to specify a build type in the CMakeLists.txt file, in this way:

set(CMAKE_BUILD_TYPE Release)

at the end of your CMakeLists.txt file. Of course, change “Release” with “Debug” for debug builds.

With the Release build type, the options passed to the compiler are these:

[...]
[ 50%] Building CXX object CMakeFiles/hello.dir/main.cpp.o
/usr/bin/c++    -O3 -DNDEBUG   -o CMakeFiles/hello.dir/main.cpp.o -c /tmp/cmaketest/main.cpp
[100%] Building CXX object CMakeFiles/hello.dir/foo.cpp.o
/usr/bin/c++    -O3 -DNDEBUG   -o CMakeFiles/hello.dir/foo.cpp.o -c /tmp/cmaketest/foo.cpp
Linking CXX executable hello
/usr/bin/c++   -O3 -DNDEBUG   CMakeFiles/hello.dir/main.cpp.o CMakeFiles/hello.dir/foo.cpp.o
 -o hello -rdynamic
[...]

Much better than before. And if you find uncomfortable to have to edit the CMakeLists.txt file to switch between Release and Debug mode, you can also specify the option in the CMake command line, like this:

mkdir build && cd build
cmake -D CMAKE_BUILD_TYPE=Debug ../
make

Last, if you are a GCC wizard and you want full control of the options passed to the compiler, you can also set them manually. However, keep in mind that a CMakeLists.txt file should ideally work with many compilers. So before forcing compiler options, you need to check that the compiler is really GCC. This is an example that shows how to do it:

cmake_minimum_required(VERSION 2.6)
project(HELLO)

## Target
set(HELLO_SRCS main.cpp foo.cpp)
add_executable(hello ${HELLO_SRCS})

## Compiler flags
if(CMAKE_COMPILER_IS_GNUCXX)
    set(CMAKE_CXX_FLAGS "-O2")        ## Optimize
    set(CMAKE_EXE_LINKER_FLAGS "-s")  ## Strip binary
endif()

Note that you must not specify a build type (Debug or Release) since it apparently conflicts with the manually set compiler flags.

Last note, not necessarily CMake related, if you happen to have a multicore CPU and want to speed up builds, you can use the -jX option of make, where X is the number of cores in your CPU. It tells make to compile X files (lol :D) at the same time. So for a dual core, use:

mkdir build && cd build
cmake ../
make -j2

First steps with CMake

September 16, 2009

When building something I usually either let an IDE handle the build process, or write makefiles manually. Both solution work, but have drawbacks. IDEs allow you to forget about how code is built, but create some sort of IDE lock-in, since switching to another IDE becomes difficult. Makefiles solve this problem, but are a bit too low level, and writing makefiles for complex projects is tedious.

So it’s a while I’ve been searching a better way. The most known alternative is autoconf and automake. If you’ve compiled some software on Linux you’ll be familiar with the

./configure <options>
make
make install

way of doing things. However, these tools have the main problems of being built mostly with shell scripts. If you plan to support only Linux this is not an issue, but it becomes a bigger trouble if your program needs to be compiled on windows too, where bash is not available by default.

Recently I’ve found CMake, and it looks interesting. First it’s the tool used to build KDE4, and this means it’s well suited even for large projects, second it claims to work equally well on Linux, Mac and Windows. And lastly, its syntax seems simple and high level.

I’ve started with the documentaton on its website, and in 15 minutes I’ve been able to compile an example program. The example program is made of three files, main.cpp, foo.cpp and foo.h.

The first step to create a CMake project is to write a file named CMakeLists.txt. Its content is this:

cmake_minimum_required (VERSION 2.6)
project (HELLO)

add_executable (hello main.cpp foo.cpp)

The first line is a requirement for a new version of CMake. The second specifies the name of the project, and the third tells CMake to create an executable named hello by compiling the files main.cpp and foo.cpp. Really simple.

Like autoconf and automake, CMake doesn’t compile the code directly, instead it generates a makefile. The steps to compile the example program are to open a shell in the directory where the source files and CMakeLists.txt are, and type:

mkdir build
cd build
cmake ../
make

This is because with CMake it is recomended to keep the build directory separated from the source directory. To remove the generated files it is either possible to type “make clean” or simply to delete the build directory.

It is still early to say if I’ll use CMake for my projects, after all I’ve just started using it for 15 minutes, but it surely looks interesting.


Follow

Get every new post delivered to your Inbox.

Join 30 other followers