Monday, December 20, 2010

CMake - Build an OS X Bundle

OS X applications are structured as bundles. A bundle is a folder with a predefined structure that contains the program and other files.
It is possible to create an application bundle with CMake using specific commands.

First we must specify the files containing the application icons. For example:

#--------------------------------------------------------------------------------
# For Apple set the icns file containing icons
if(APPLE)
  # icon files to copy in the bundle
  set( OSX_ICON_FILES ${CMAKE_CURRENT_SOURCE_DIR}/graphics/vvv.icns ${CMAKE_CURRENT_SOURCE_DIR}/graphics/vvv-document.icns )
  # set where in the bundle to put the icns files
  set_source_files_properties( ${OSX_ICON_FILES} PROPERTIES MACOSX_PACKAGE_LOCATION Resources)
  # include the icns files in the target
  set( SRCS ${SRCS} ${OSX_ICON_FILES} )
ENDIF(APPLE)


add_executable( vvv WIN32 MACOSX_BUNDLE ${SRCS} )

This example defines two icons, one for the application and one for the application documents. The SRCS variable already contains the list of source files and this code adds the icons to the files list.
The ADD_EXECUTABLE command in the last line tells CMake to create an OS X bundle.

The following code will tell CMake where to find the Info.plist that will be copied into the bundle:

if(APPLE)
  # configure CMake to use a custom Info.plist
  set_target_properties( vvv PROPERTIES MACOSX_BUNDLE_INFO_PLIST ${PROJECT_SOURCE_DIR}/vvv-Info.plist )
ENDIF(APPLE)

Using the code above CMake will be able to create an OS X application bundle.

Sunday, December 5, 2010

CMake - Build with Boost and Firebird

In the previous post I explained how to use wxWidgets with CMake.
Now we will look at the steps to successfully build a program that uses Firebird and the Boost library.

Boost is a well know and widely used library. Most of it does not require linking to a library file, just include some headers. That is what I do in my program, and here is the CMake code:

# try find BOOST (we need headers only)
find_package( Boost 1.37.0 )
if( Boost_FOUND)
  include_directories( ${Boost_INCLUDE_DIRS} )
endif( Boost_FOUND)

more information in C:\Program Files\CMake 2.8\share\cmake-2.8\Modules\FIndBoost.cmake. I am sure that you will figure out the correct path for your computer.

I use the IBPP library as a data access layer, and it requires a preprocessor definition to specify the operating system. Here is the CMake code:

# definitions for IBPP
if( WIN32 )
  add_definitions( -DIBPP_WINDOWS )
elseif( APPLE )
  add_definitions( -DIBPP_DARWIN )
else( WIN32 )
  add_definitions( -DIBPP_LINUX )
endif( WIN32 )

Under Windows the Firebird client library is loaded dynamically so there are no othe rrequirements.
Under Linux and OS X the program must link with the client library. Here is the CMake code:

if( UNIX )
  # link to the Firebird client library
  # the last path is used for OS X where I have a local copy (not installed)
  find_library( FB_LIB fbembed PATHS /usr/lib /usr/local/lib /opt/firebird/lib ${PROJECT_SOURCE_DIR}/firebird_runtime/firebird )
  if( NOT FB_LIB )
    message( FATAL_ERROR "Unable to find firebird interface" )
  else( NOT FB_LIB )
    message( STATUS "Firebird interface: " ${FB_LIB} )
  endif( NOT FB_LIB )

  target_link_libraries( MyTarget ${FB_LIB} )
endif( UNIX )

the find_libary command accepts some paths as parameters. They are used as suggestions to find the file. The example contains my paths, you will probably change them.

With this code in CMakeLists.txt it should be possible to successfully build the program. The next problem will be make it run using an embedded copy of Firebird.

Friday, December 3, 2010

CMake - wxWidgets

CMake is released with a large set of source code that can be used to accomplish common tasks. One of this tasks is looking for a package used by your project.

For example, let's see how to look for the wxWidgets library. We can use the FIND_PACKAGE command for this purpose: CMake already knows how to handle wxWidgets.

Just add the following lines to CMakeLists.txt:

FIND_PACKAGE(wxWidgets REQUIRED html adv core base net aui xrc qa richtext )
INCLUDE(${wxWidgets_USE_FILE})
TARGET_LINK_LIBRARIES(myTarget ${wxWidgets_LIBRARIES})


The first line tells CMake to look for wxWidgets. The REQUIRED clause says that you require the specified modules.
The FIND_PACKAGE command executes some code and sets a number of variables if it finds the library.
The second line uses one of those variables to tell CMake where to look for include files.
The third line tells CMake how to link a target with wxWidgets.

Now let's see what happens when we run CMake from its GUI. Press Configure and you will probably see a number of red rows that need to be fixed. The rows content changes with the operating system.

Linux

I create two build folders, one for the debug configuration and one for the release one.

You need to look at the following variables:
  • CMAKE_BUILD_TYPE: set it to Debug for a build folder and to Release for the other.
  • wxWidgets_CONFIG_EXECUTABLE: it is the path to the wx-config script for the chosen copy of wxWidgets. For example, /usr/local/bin/wx-config for a library that has been installed, or /home/fulvio/wxSVN/buildgtk/wx-config for a library that has not been installed. In the library has not been installed you must point to the wx-config file in the folder with the right configuration (for example debug or not).
  • wxWidgets_USE_DEBUG: check it if you want to use a debug version of the library.
  • wxWIDGETS_USE_STATIC: check it if you ant to use a static version of the library.
  • wxWidgets_USE_UNICODE: check it if you want to use the Unicode version of the library. If you are using version 2.9 or later this setting does not make sense any more (the llibrary is only Unicode): I leave it checked and everything works well.
  • wxWidgets_wxrc_EXECUTABLE: this is probably a wxrc setting. Since I do not use it I left its value set to NOTFOUND.
OS X

I create two build folders, one for the debug configuration and one for the release one.

You need to look at the following variables:
  • CMAKE_BUILD_TYPE: set it to Debug for a build folder and to Release for the other.
  • CMAKE_OSX_ARCHITECTURES:  I set it to i386.
  • CMAKE_OSX_DEPLOYMENT_TARGET: I leave this blank.
  • wxWidgets_CONFIG_EXECUTABLE: it is the path to the wx-config script for the chosen copy of wxWidgets. For example /Users/fulvio/wxMac-2.8.10/buildgtk/wx-config for a library that has not been installed. In the library has not been installed you must point to the wx-config file in the folder with the right configuration (for example debug or not).
  • wxWidgets_wxrc_EXECUTABLE: this is probably a wxrc setting. Since I do not use it I left its value set to NOTFOUND.
Windows

In Windows I create a single build folder. It will contain a Visual Studio project file with both a debug and a release configuration.

You need to look at the following variables:
  • wxWidgets_CONFIGURATION: set to mswud, mswu or mswd. This is not very clear to me, but I set it to mswu and everything works well.
  • wxWidgets_ROOT_DIR: it is the path to the root folder of the wxWidgets installation, for example E:/wxWidgets-2.8.10. If CMake does not find the path you need to set it manually and configure again.
  • wxWidgets_LIB_DIR: it is the path of the folder that contains the libraries that will be linked to your program. Usually CMake can find this path by itself if it knows the root dir.
  • wxWidgets_USE_REL_AND_DBG is a boolean value. Check it if you want to have a project with both a debug and a release configuration. You will probably check it.
  • wxWidgets_wxrc_EXECUTABLE: this is probably a wxrc setting. Since I do not use it I left its value set to NOTFOUND.
As you can see configuring CMake to use your copy of wxWidgets is an easy task.
It is also easy to use different versions of wxWidgets with your project. Just build the different versions in different folders (do not install them in *nix), then create different build folders for the different wxWidgets versions. For each folder configure CMake to look for wxWidgets in the right folder, manually setting the required variables to the right value.

Thursday, December 2, 2010

CMake

My purpose is creating a program that can be compiled for Linux, OS X and Windows. If you have read older posts you already know that I was successful and I am already able to do it.

After some time spent developing a program for all these operating system it becomes obvious that handling the build files is a great problem. I have the Visual Studio project file for Windows, the KDevelop files for Linux and the XCode project for OS X. Maintaining all these files takes time and it is prone to errors. Moreover there are other kind of problems: I am still using Visual Studio 2003: if another developer checks out the source code and opens the project with a newer version of Visual Studio the project cannot be read by my older version any more. I could manually maintains different project files for different VS versions, but this is clearly a crazy thing to do.
Last but not least, creating the files for a new project is difficult: you have to copy the files from another project and carefully edit them.

In short, there must be a better way.

Some time ago I started looking for that way and I found a good solution: CMake. Maybe there are others, but I am very satisfied with this one.

The idea behind CMake is simple: use a single text file (CMakeLists.txt) in each folder to describe how the project must be built. Then let CMake create the build files for your preferred build tool.

You usually create a folder inside your project and instruct CMake to create the build files in that folder: all the build and compiled files will be in that folder, so your source code tree will be clean. You can even create different build folders for different build configurations.

There are plenty on information about CMake basic usage, so I will not write about it. I found little information about advanced usage, and I will post what I discovered with some work and experiments.

Using CMake is simple: just run the GUI program and it will show up its main window.
In the upper part you select your project's root folder (the upper one that contains a CMakeLists.txt file) and the build folder, where the build files will be created.

Below these paths there is grid that contains a list of couples: a variable and its value. You must check the values and set the missing or wrong ones. Here lies the magic: setting those variables tells CMake where to look for libraries or how to configure the build in your computer.

You must run the CMake GUI when you create the build folder and you will run it again when you change something, most often because you have added new source files.

In the lower part of the window there is a Configure button. When you press it CMake processes all the CMakeLists.txt files: if there are problems one or more rows in the grid will be colored in red. You need to fix the problem, for example editing the value of a variable, and press Configure again.
If everything is OK the Generate button is enabled: press it to create your build files, then move to the build folder and open the build files with your development tool.

Handling the project becomes a much easier task. For example, if you create some new source files just add the file names to the CMakeLists.txt file.
Then just run CMake in each operating system and configure again.

To create the build files CMake processes the CMakeLists.txt files found in each folder. Those files are written in the CMake language: the language is very powerful so the difficult part is learning it. I discovered that I used a relatively low number of features, but it took me a lot of work to learn how to use them correctly.