CMake

From WxWiki
Jump to: navigation, search

What is CMake

CMake is a project/makefile generator that uses one (or multiple) input files, and can generate multiple types of project files depending on the OS it is executed from. I've first seen it in action on wxArt2D. I started to seriously use it when people started emailing me that the Makefiles I provided for WxTreeMultiCtrl didn't worked on HP-UX, and that the Visual Studio 6 project file was hopelessly out of date (sure enough as I only had VS7 installed back then ;-)

On what OS can I use it?

There are downloadable binaries for the following platforms:

  • Windows (supports Visual Studio 6-10, Borland Makefiles, MinGW, MSYS, NMake, JOM (parallel NMake), Watcom WMake, Code::Blocks and Eclipse)
  • Linux(x86 and ia64) (generates Linux makefile, KDevelop, Code::Blocks and Eclipse)
  • HP-UX (Unix Makefile)
  • IRIX64 (Unix Makefile)
  • SunOS 5.7 (Unix Makefile)
  • AIX 5.1 (Unix Makefile)
  • OSF1 (Unix Makefile)
  • OSX (Unix Makefile, Xcode project)
  • OSX(Darwin) (Unix Makefile)

For all those platforms, all most common projects IDE's can be generated, and at least Makefiles if no IDE is used. Now you can see the power of CMake, because with only one file, you can satisfy a lot of developers. No need to keep 5+ makefiles up to date anymore!

How to use it with wxWidgets ?

Ok, now how to use it. First download the latest version from Cmake Homepage. Depending on what OS, install it. I will refer to the Windows version here, but on Linux (use ccmake command for visual setup) it will look similar. On windows the executable you need is CMake-GUI.exe or CMakeSetup.exe in older versions.

The CMake 2.6.4 installation comes with the file FindwxWidgets.cmake which is used by Cmake for finding any installed wxWidgets on the system. To change the default search path of the wxWidgets installation, use SET(wxWidgets_ROOT_DIR <wxWidgets Directory>). Use SET(wxWidgets_CONFIGURATION mswud) to find appropriate configuration. Then use FIND_PACKAGE(wxWidgets COMPONENTS core base REQUIRED). You may configure the FIND_PACKAGE line as per your needs. Then use INCLUDE(${wxWidgets_USE_FILE}). At the end, don't forget to use TARGET_LINK_LIBRARIES(<YourTarget> ${wxWidgets_LIBRARIES}). See the example:

project(myGreatProject)
cmake_minimum_required(VERSION 2.8)
aux_source_directory(. SRC_LIST)
 
set(wxWidgets_CONFIGURATION mswu)
find_package(wxWidgets COMPONENTS core base REQUIRED)
include(${wxWidgets_USE_FILE})
 
add_executable(${PROJECT_NAME} ${SRC_LIST})
target_link_libraries(${PROJECT_NAME} ${wxWidgets_LIBRARIES})

This is (probably) all that is needed to work with wxWidgets using cmake. Much of the information below related to FindWxWin.cmake is OUTDATED and not required with the new CMake versions.

If all is installed, we need one thing, which I took from wxArt2D. It is a macro that can be used to determine the install dir for wxWidgets, what libs are used, what type of builds are compiled, etc. You can find this file here FindWxWin.Cmake. Save this file in {CMAKE_INSTALL}\Modules. As you can see in this directory, there are a lot of helper macros that can determine if certain tools are installed, compiler flags / functions are supported, etc. This is really extensive and very handy.

Now that we have the macro we need in place, we can make our first CMakeLists.txt file, which will allow us to generate a minimal sample that can be compiled. Go to the minimal sample directory (usually {WXWIN}\samples\minimal\), and start up your editor.

NOTE: This CMakeLists.txt file is compatible with the CMake 2.6.2 If you find any problems with it, please contact me jorgb [at] xs4all.nl

The following file can be copied and pasted. In this CMake file the comments will explain what all sections mean:

##---------------------------------------------------------------------------
## Author:      Jorgen Bodde
## Copyright:   (c) Jorgen Bodde
## License:     wxWidgets License
## Update:      2008/12 by Werner Smekal
##---------------------------------------------------------------------------
 
# define minimum cmake version
cmake_minimum_required(VERSION 2.6.2)
 
# Our project is called 'minimal' this is how it will be called in
# visual studio, and in our makefiles. 
project(minimal)
 
# Location where cmake first looks for cmake modules.
set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}")
 
##---------------------------------------------------
## Please set your wxWidgets configuration here
##--------------------------------------------------- 
 
# Here you can define what libraries of wxWidgets you need for your
# application. You can figure out what libraries you need here;
# http://www.wxwidgets.org/manuals/2.8/wx_librarieslist.html
# We need the Find package for wxWidgets to work
# NOTE: if you're using aui, include aui in this required components list.
 
# It was noticed that when using MinGW gcc it is essential that 'core' is mentioned before 'base'.
find_package(wxWidgets COMPONENTS core base REQUIRED)
 
##---------------------------------------------------
## Actual config file starts here
##--------------------------------------------------- 
 
# wxWidgets include (this will do all the magic to configure everything)
include( "${wxWidgets_USE_FILE}" )
 
# For convenience we define the sources as a variable. You can add 
# header files and cpp/c files and CMake will sort them out
set(SRCS minimal.cpp)
 
# If we build for windows systems, we also include the resource file
# containing the manifest, icon and other resources
if(WIN32)
  set(SRCS ${SRCS} minimal.rc)
endif(WIN32)
 
# Here we define the executable minimal.exe or minimal on other systems
# the above paths and defines will be used in this build
add_executable(minimal WIN32 ${SRCS})
 
# We add to our target 'minimal' the wxWidgets libraries. These are
# set for us by the find script. If you need other libraries, you
# can add them here as well. 
target_link_libraries(minimal ${wxWidgets_LIBRARIES})

Save this file as CMakeLists.txt into the minimal sample directory.


This is the CMakeLists.txt file for older (2.4) version of CMake.

##---------------------------------------------------------------------------
## $RCSfile: CMakeLists.txt $
## $Source: CMakeLists.txt $
## $Revision: 1.48 $
## $Date: Feb 26, 2006 10:39:43 PM $
##---------------------------------------------------------------------------
## Author:      Jorgen Bodde
## Copyright:   (c) Jorgen Bodde
## License:     wxWidgets License
##---------------------------------------------------------------------------
 
##---------------------------------------------------
## Please set your wxWidgets configuration here
##--------------------------------------------------- 
 
SET(CMAKE_FIND_LIBRARY_PREFIXES "")
SET(CMAKE_FIND_LIBRARY_SUFFIXES ".lib")
 
# Here you can define what libraries of wxWidgets you need for your
# application. You can figure out what libraries you need here;
# http://www.wxwidgets.org/manuals/2.8/wx_librarieslist.html
SET(wxWidgets_USE_LIBS base core gl net)
 
# We need the Find package for wxWidgets to work
FIND_PACKAGE(wxWidgets)
 
##---------------------------------------------------
## Actual config file starts here
##--------------------------------------------------- 
 
# Did we find wxWidgets ? This condition will fail
# for as long as the internal vars do not point to
# the proper wxWidgets configuration
IF(wxWidgets_FOUND)
 
    # Include wxWidgets macros
    INCLUDE("${wxWidgets_USE_FILE}")
 
    # Our project is called 'minimal' this is how it will be called in
    # visual studio, and in our makefiles. 
    PROJECT( minimal )
 
    # We define the include paths here, our minimal source dir is one, 
    # and also the include dirs defined by wxWidgets
    INCLUDE_DIRECTORIES(${minimal_SOURCE_DIR}
                        ${wxWidgets_INCLUDE_DIRS} )
 
    # For convenience we define the sources as a variable. You can add 
    # header files and cpp / c files and CMake will sort them out
    SET(SRCS minimal.cpp )
 
    # If we build for windows systems, we also include the resource file
    # containing the manifest, icon and other resources
    IF(WIN32)
        SET(SRCS ${SRCS} minimal.rc)
    ENDIF(WIN32)
 
    # Here we define the executable minimal.exe or minimal on other systems
    # the above paths and defines will be used in this build
    ADD_EXECUTABLE(minimal WIN32 ${SRCS})
 
    # We add to our target 'minimal' the wxWidgets libraries. These are
    # set for us by the find script. If you need other libraries, you
    # can add them here as well. 
    TARGET_LINK_LIBRARIES(minimal ${wxWidgets_LIBRARIES} )
 
ELSE(wxWidgets_FOUND)
    # For convenience. When we cannot continue, inform the user
    MESSAGE("wxWidgets not found!")
ENDIF(wxWidgets_FOUND)

Building the project files

When starting CMakeSetup.exe, you can choose from a number of projects to generate. This means the script above will be parsed, and generated in that specific project. Let's choose VS7. In the Build for field, select "Visual Studio 7 .NET 2003". Now, if you don't have this IDE, select one that you have. CMakeSetup.exe is smart and will check for existence of the IDE you wish to build. In the field Where is the sourcecode fill in the path to the minimal sample. In my case it is "D:\related\src\wxWidgets\wxMSW-2.4.2\samples\minimal\". I recommend out-of-source building. If you rather have all junk inside your source dir, leave the next field empty. Else fill in at Where to build the binaries the same dir, but append e.g. cbuild. You can put it anywhere you want, even on a temp drive if you like. I filled in "D:\related\src\wxWidgets\wxMSW-2.4.2\samples\minimal\cbuild".

Now press the Configure button. You will see a couple of red entries. These entries can be changed but should be left default for now. The purpose of those entries is to allow developers to configure the build process by setting define flags to a specific value, or specific paths. Press Configure again, and all should be grey now. This means, there is no new information to be presented and all the optional values are now used upon generation.

Press OK, and now in our build dir the project should be generated. In case of the Visual Studio 7 .NET 2003 project solution, simply click it and rebuild the project. You will notice a number of targets such as there are:


  • ALL_BUILD
  • INSTALL
  • Minimal

The minimal target is the one we created, ALL_BUILD is a dummy target that will reflect the same behaviour as "make all", and could be used to perform cleanup actions, generation actions of flex / yacc files or the likes, and then start building all sub projects. The INSTALL target is similar to the "make install" under linux. It can be used to copy DLL files or LIB files to a specific directory.

Building under Linux

As the steps described above are nearly similar, the following should be done under linux (I assume you are using makefiles). At first, create a dir where you want to build the binaries. For example in the samples/minimal dir, create another one called cbuild. Go to that directory and start up the following command "ccmake ../" this will bring you to a similar IDE as described in CMakeSetup.exe. As from there it is easy to follow the steps.

Updates

The above ZIP file contains enhanced FindwxW and UsewxW modules along with a CMakeLists.txt template that makes it very easy to use CMake for your wxWidgets application. See the readme for usage information.

  • Easy way to get going with CMake and wxWidgets:

Just tried cmake-2.4.6-win32-x86.exe from cmake.org website: There is a find package macro included there, based on the one described on this page here, and it works with 2.8 apparently. This is my basic CMakeLists.txt file for a program consisting of only one main.cpp:

 PROJECT(Test)
 SET(wxWidgets_USE_LIBS)
 FIND_PACKAGE(wxWidgets)
 IF(wxWidgets_FOUND)
   INCLUDE("${wxWidgets_USE_FILE}")
   ADD_EXECUTABLE(MyTest WIN32 main.cpp main.h)
   # and for each of your dependant executable/library targets:
   TARGET_LINK_LIBRARIES(MyTest ${wxWidgets_LIBRARIES})
 ELSE(wxWidgets_FOUND)
   # For convenience. When we cannot continue, inform the user
   MESSAGE("wxWidgets not found!")
 ENDIF(wxWidgets_FOUND)

More information