From KitwarePublic
Jump to navigationJump to search


General information and availability

What is CMake

CMake is a cross-platform, open-source make system. CMake is used to control the software compilation process using simple platform and compiler independent configuration files. CMake generates native makefiles and workspaces that can be used in the compiler environment of your choice. CMake is quite sophisticated: it is possible to support complex environments requiring system configuration, preprocessor generation, code generation, and template instantiation. Please go to to learn more about CMake.

What is the current release?

The current release of CMake is 2.0. This release is available at:

Nightly development can be accessed through CVS.

See for more information.

CMake roadmap and release schedule

CMake 2.0 is out and CMake 2.2 will probably happen in late 2004 or early 2005. Depending on funding and time there may be support for FORTRAN, native Java, and cross-compiling. The bug tracker at also has a number of feature requests for CMake. These feature requests typically et rolled into future versions of CMake.

Edit this entry / Log info / Last changed on Wed Jun 9 08:41:44 2004 by Andy

I found a Bug! What should I do?

Please report the bug in our bug tracker: .

Please make sure to look at the old bugs not to include duplicates, include detailed instructions of the bug and how to reproduce it.

I want a new feature in CMake. What should I do?

Report a feature request in our Bug tracker .

Please make sure to look at the old feature requests not to include duplicates, include detailed instructions of the feature and proposed implementation.

Using CMake

Backward and Forward Compatibility

CMake by default maintains quite a bit of backwards compatibility to support older projects that used earlier versions of CMake. This backwards compatibility comes at the expense of allowing new CMakeLists.txt to use deprecated features and still work. To deal with this problem, CMake always creates a cache entry called CMAKE_BACKWARDS_COMPATIBILITY and sets it to the version (major.minor) of CMake currently running. During the "Configure" step, CMake will support enough backward compatibility features to simulate the version of CMake specified by this cache entry's value. When a new version of CMake is run on an old project and reports errors, one can set CMAKE_BACKWARDS_COMPATIBILITY to an older version of CMake to solve the problem.

A good practice for project developers that use CMake is to add code like this to the RELEASE version of the source tree:

     "Latest version of CMake when this project was released." FORCE)

That way whenever someone tries to build the release with a later version of CMake, the necessary backward compatibility level will already be set. DO NOT keep this code in the development version of the source tree. When a new version of CMake is released, it is good practice to fix the problems it reports in the source tree instead of abusing the backward compatibility features.

When a new version of CMake is released that adds some features, it is nice to be able to take advantage of them in your project. However, doing so will cause other developers that have not yet upgraded to the new CMake to get errors when attempting to build the source. In order to have CMake tell them that they need to upgrade, your project should contain a line like this:


at the top of your main CMakeLists.txt file. This will tell older versions of CMake that they are too old to build this project and produce a message telling the user they need to upgrade to a more recent version of CMake.

How do I get the current source or binary directory?

Is there any way to get the "current working directory" in a CMake variable?

You can use the following:

CMAKE_CURRENT_SOURCE_DIR: points to your current source directory CMAKE_CURRENT_BINARY_DIR: points to the equivalent binary directory

Why are my CMake variables not updated in the GUI after a SET command?

The cache variables listed in the GUI when you press "Configure" are used to initialize the values seen by the code in CMakeLists.txt files.

Changes made by the code are used during the configure step and seen by the generators but are not stored back into the cache. For example:


will turn on building of shared libraries for the directory containing the command and all subdirectories, but the change will not appear in the GUI.

The CACHE and FORCE options on the SET command can be used to change variables in a way that will be reflected in the GUI. Run

 cmake --help-command SET

to see full instructions for the command.

How can I generate a source file during the build?

The ADD_CUSTOM_COMMAND command can be used to generate a source file that is then included in another target. For example:

 ADD_EXECUTABLE(foo foo.c)

This will create an executable by copying bar.c to foo.c and then compiling it to produce the executable. Whenever bar.c changes foo.c will be regenerated and the executable rebuilt. This even works when the generator command is another executable built in the same project:

 ADD_EXECUTABLE(my_generator my_generator.c)
 ADD_EXECUTABLE(generated generated.c)

It is assumed in this example that the my_generator program accepts as its first argument the full path to the source file to generate. The second argument is used as input for the generator. When either the generator source or the sample input changes, the generated.c source will be regenerated.

In both of the above cases, the source file named as the OUTPUT argument of the ADD_CUSTOM_COMMAND command will automatically have the GENERATED source file property set to true. The source may then be referenced without the ${CMAKE_CURRENT_BINARY_DIR} part of the path. Note that use of the "LOCATION" target property requires CMake 2.0 or higher.

In some cases, the program doing the generation may generate more than one file that needs to be part of the build. In this case, some dummy custom commands must be created to "chain" the outputs so that the files are created in the correct order. For example, suppose you had a program that read input.txt and generated three files output1.cpp, output2.h, and output3.cpp, and that those three files needed to be compiled into an executable program. The cmake list file for that would look like this:

 # make sure cmake addes the binary directory for the project to the include path
 # add the executable that will do the generation
 ADD_EXECUTABLE(my_generator my_generator.cxx)
 # add the custom command that will generate all three files but only specify one of the outputs
 # add the second output and run the dummy command echo but make sure that output1.cpp 
 # is the DEPEND for this command.  Once output1.cpp exists output2.h will also be created.
   COMMAND echo
   DEPENDS ${FOO_BINARY_DIR}/output1.cpp
 # do the same thing for output3.cpp
   COMMAND echo
   DEPENDS ${FOO_BINARY_DIR}/output1.cpp
 # now create an executable using the input files 
 ADD_EXECUTABLE(generated ${FOO_BINARY_DIR}/output1.cpp 
                ${FOO_BINARY_DIR}/output3.cpp ${FOO_SOURCE_DIR}/input.txt)

How do I use CMake to generate SWIG wrapper libraries?

CMake version 2 supports the generation of SWIG wrapper libraries. The SWIG package defines the following macros: SWIG_ADD_MODULE and SWIG_LINK_LIBRARIES

# This example shows how to use python
# Currently these languages have been tested:
#  perl tcl ruby php4 pike





SWIG_ADD_MODULE(example python
  example.i example.cxx)

I use EXEC_PROGRAM but the result is not set in subdirectories. Why?

An unfortunate holdover from ancient CMake versions is that certain commands are "inherited" into subdirectories and others are not. EXEC_PROGRAM is not inherited. What this means is that when the listfile code from a parent directory executes in a subdirectory the EXEC_PROGRAM command is left out. Therefore the code executes differently. This problem will be fixed in CMake 2.2, but for now you will have to cache the result:


This will store the result in a global location so it will be available in the subdirectory. Be sure to choose a descriptive name for MY_OUTPUT to avoid conflict in the global setting.

Running CMake

Is there an option to produce more 'verbose' compiling?

Set CMAKE_VERBOSE_MAKEFILE to ON. This will make generator to produce all outputs, including compiler lines.

If you are on Windows using Borland or NMake Makefiles, then you will see lines like:

cl @c:\DOCUME~1\ANDY~1.KIT\LOCALS~1\Temp\nma03504

The reason for this is that Borland and Microsoft Visual Studio make programs have limitation on the length of command string. They overcome this limitation by writing arguments to the file and then pass file to the program.

If you actually want to see what the command looks like, set CMAKE_START_TEMP_FILE and CMAKE_END_TEMP_FILE to "".

On Makefile generators, there is a shortcut by setting Makefile variable VERBOSE to 1. For example on UNIX:

make VERBOSE=1

I set a cmake variable in my environment, but it didn't change anything. Why?

CMake build settings are stored in the CMake cache corresponding to a project's build tree. They are called CMake "cache entries" and have no relation to your command shell's environment variables. Use a CMake GUI (CMakeSetup on Windows or ccmake on UNIX) or the wizard mode (cmake -i) to edit cache entries. Initial values may also be specified for a build by using the -D command line argument to cmake when it is first run to produce a new build tree.

I run an out-of-source build but CMake generates in-source anyway. Why?

This means that there is a CMakeCache.txt file in the source tree, possibly as part of an existing in-source build. If CMake is given the path to a directory with a CMakeCache.txt file, it assumes the directory is a build tree. Therefore if one runs "cmake ../mysrc" to build out-of-source but there is a mysrc/CMakeCache.txt file then cmake will treat mysrc as the build tree.

This is a side-effect of the feature that allows "cmake ." to be used to regenerate a build tree. The behavior will not be changed because mixing in-source and out-of-source builds is not safe anyway (configured headers may be found in the wrong place).

Platform-specific questions

How can I apply resources on Mac OSX automatically?

Using ADD_CUSTOM_COMMAND. For example, let's say you are creating executable MyExecutable, which needs the resources file Carbon.r. All you do is add custom rule which is executed after the executable is linked:

ADD_EXECUTABLE(MyExecutable ${MyExecutable_SRCS})
IF(NOT MyExecutable_PATH)
ENDIF(NOT MyExecutable_PATH)
                       COMMAND ${VTK_APPLE_RESOURCE}
                       ARGS Carbon.r -o 
                       TARGET MyExecutable)

This will execute:

/Developer/Tools/Rez Carbon.r -o /binary/path/MyExecutable

after MyExecutable is linked.

Why does FIND_LIBRARY not find .DLL libraries under WIN32?

For those who come from a Unix background to MS Windows:

You never link directly to the .dll, you have to link against the import library .lib for the .dll.

Linking against dynamic libraries (.dll under Windows) is quite different from linking against shared objects (.so) under Linux.

In Windows, there are two types of library, a static library and an import library (both called .lib). In Windows, building A.dll will also build the import library A.lib (which is not the static library).

Conclusion: There is no need to find a .dll for linking.

Some more details can be found here:

Why am I getting a linker error to _mainCRTStartup under WIN32?

Your program is a GUI application using WinMain (/subsystem:windows) and not a console application using main.

You have to use the WIN32 option with the ADD_EXECUTABLE command.

ADD_EXECUTABLE(exename [WIN32] source1 source2 ... sourceN)

... The second argument to this command can be WIN32 which indicates that the executable (when compiled on windows) is a windows app (using WinMain) not a console app (using main)....

Why do I get this error: nafxcwd.lib(appcore.obj) : error LNK2001: unresolved external symbol ___argv

This is becuase the application is using both the static and dll versions of the MFC library. To fix the problem, you can do the following:

SET(CMAKE_MFC_FLAG 2)     # force the IDE to use static MFC
ADD_DEFINITIONS(-D_AFXDLL) # make sure if afx.h is included the dll MFC is used

How to use MFC with CMake

To use MFC, the CMAKE_MFC_FLAG variable must be set as follows:

0: Use Standard Windows Libraries
1: Use MFC in a Static Library
2: Use MFC in a Shared DLL 

This can be set in a CMakeLists.txt file and will enable MFC in the application. It should be set to 1 or 2. This is used in visual studio 6 and 7 project files. The CMakeSetup dialog uses MFC and the CMakeLists.txt looks like this:


How Put Files in Folders in Visual Studio Projects

The Visual Studio IDE supports putting files into folders. CMake can be used to put files in folders with the SOURCE_GROUP command.

 SOURCE_GROUP(name [REGULAR_EXPRESSION regex] [FILES src1 src2 ...])

Defines a group into which sources will be placed in project files. This is mainly used to setup file tabs in Visual Studio. Any file whose name is listed or matches the regular expression will be placed in this group. If a file matches multiple groups, the LAST group that explicitly lists the file will be favored, if any. If no group explicitly lists the file, the LAST group whose regular expression matches the file will be favored. For backwards compatibility,this command is also supports the format SOURCE_GROUP(name regex).

How to create Visual Studio 6 Projects that contain only a single build type

For Visual Studio.NET (version 7.0 and above) it is possible to set the CMAKE_CONFIGURATION_TYPES variable to the build type(s) (Debug/Release/...) that you want. This does not work for Visual Studio 6. There is however a way to achieve this. To create your own set of configurations:

1. Create a directory in which you copy the files *.dsptemplate and CMakeVisualStudio6Configurations.cmake from CMake's Templates directory.
2. Edit the .cmake file and change the SET(CMAKE_CONFIGURATION_TYPES ...) line to set the build types that you want in your set.
3. Edit the *Header.dsptemplate files to contain only the configuration types you want in your set.
4. In your CMakeLists.txt file, set the MSPROJECT_TEMPLATE_DIRECTORY to the directory that you created.

That's it. Run CMake and your new configuration files will be created.

Note: Editing the *Header.dsptemplates files should be done very carefully. Here are some guidelines:

- You MUST remove the targets that you do not want in your set at the bottom of the file (e.g. '# Name "OUTPUT_LIBNAME - Win32 MinSizeRel"') - You can remove the '!IF "$(CFG)" == ...' until '!ELSEIF "$(CFG)" == ...' or '!ELSEIF "$(CFG)" == ...' until '!ENDIF' lines for the configurations you do not want. Make sure that the resulting code still starts with '!IF ...' and ends with '!ENDIF' with any number of '!ELSEIF' sections in between. If you create templates for a single configuration (aka makefile), it is possible to remove everything starting from '!IF' until and including '!ENDIF' and leave only the contents of the relevant section intact. - Do not edit the lines starting with '!MESSAGE' as the changes may - and probably will - corrupt your resulting DSP files. The only thing I was able to change without corrupting the DSP is to remove the irrevant configurations from the "Possible choices for configuration are:" list.

If you have only a single configuration in your set, you may want to get rid of the intermediate dir that MsDev creates. You can do that by setting:

  1. PROP BASE Output_Dir ""
  2. PROP BASE Intermediate_Dir ""
  3. PROP Intermediate_Dir ""



Additionally you should then also edit the '# ADD LINK32' line in the DLLHeader.dsptemplate file. Change for example '/out:"LIBRARY_OUTPUT_PATHDebug/OUTPUT_LIBNAMEDEBUG_POSTFIX.dll"' into '/out:"LIBRARY_OUTPUT_PATHOUTPUT_LIBNAMEDEBUG_POSTFIX.dll"' (Note that the configuration name and also the slash are removed).

It is even possible to rename the pre-defined configurations of CMake in this way. Let's say you prefer 'PreProduction' over 'RelWithDebInfo'. You can change the name in the *.dsptemplate files, but you should also change it in the CMakeVisualStudio6Configurations.cmake file. Be careful, however. Only entries relevant to the configuration name should be changed. Do not change the /debug options and the entries that contain the build type in capital characters. Internally in CMake the build type will still remain 'RelWithDebInfo', so also the CMAKE_BUILD_TYPE should be set to the old value. You can only change the way it is named in MSDev.

Note: Apparently MsDev as command-line build tool only performs a partial check on the build type. It will match all configuration types that CONTAIN the build type in their name. (e.g. if you have renamed RelWithDebInfo to DebugRelease, Debug will build Debug and DebugRelease, Release will build Release and DebugRelease. This may be exactly what you want, but be warned.)

Miscellaneous questions

How do I use CMake to build LaTeX documents?

Use the following approach. Note that you have to set LATEX_COMPILE to LaTeX executable, DVIPDF_COMPILE to dvi to pdf converter. Also, the LaTeX source is TDocument.tex and the result is called TDocument.pdf. Note that this uses commands in CMake version 1.8 or later.

    OUTPUT    ${Document_BINARY_DIR}/TDocument.dvi
    DEPENDS   ${Document_BINARY_DIR}/TDocument.tex
    ARGS      ${Document_SOURCE_DIR}/TDocument.tex 

    OUTPUT    ${Document_BINARY_DIR}/TDocument.pdf
    DEPENDS   ${Document_BINARY_DIR}/TDocument.dvi 
    ARGS      ${Document_SOURCE_DIR}/TDocument.dvi
  DEPENDS ${Document_BINARY_DIR}/TDocument.pdf

The following uses commands in CMake version 2.0 and later

# Find LaTeX
    OUTPUT    ${Document_BINARY_DIR}/TDocument.dvi
    ARGS      ${Document_SOURCE_DIR}/TDocument.tex
    DEPENDS   ${Document_SOURCE_DIR}/TDocument.tex
    COMMENT   "Tex2dvi"
      OUTPUT    ${Document_BINARY_DIR}/
      ARGS      ${Document_BINARY_DIR}/TDocument.dvi
                -o ${Document_BINARY_DIR}/
      DEPENDS   ${Document_BINARY_DIR}/TDocument.dvi
      COMMENT   "dvi2ps"

      OUTPUT    ${Document_BINARY_DIR}/TDocument.pdf
      ARGS      ${Document_BINARY_DIR}/
      DEPENDS   ${Document_BINARY_DIR}/
      COMMENT   "ps2pdf"
    ADD_CUSTOM_TARGET(LaTeXDocument ALL echo
      DEPENDS   ${Document_BINARY_DIR}/TDocument.pdf

How can I set TEXINPUTS for a LaTeX compilation?

In case you need to use the TEXINPUTS environment variable (the latex command probably misses a -I flag) you can find an example in the InsightDocuments cvs archive (refer to the section "cvs access" near the bottom of Kitware's ITK download page) or use google with keywords "ITK_TEXINPUTS CONFIGURE_FILE". Look at InsightDocuments/CourseWare/Training/Vis2003/Latex/CMakeLists.txt and search for e.g. "". Roughly the mecanism goes:

- CONFIGURE_FILE "InsightDocuments/CourseWare/Training/Vis2003/" which generates an sh shell script setting the shell variable TEXINPUTS
  prior to running the latex command
- use ADD_CUSTOM_COMMAND to invoke this shell script

This very example is Win32 portable (except that generates a .bat shell script)

How do I rename library after it is created?

Let say you do are creating library named Foo to the new name Bar. Foo is created with command: ADD_LIBRARY(Foo SHARED ${Foo_sources})

The following will rename the library after it is created (requires CMake 1.8 or later):

 # Set the existing library name:
 # Set new library name:
 # Copy:
   ARGS -E copy

In CCMake, typing full paths is tedious. Is there a better way?

Since CMake 1.6, you can use tab completion in the path entries in CCMake. All you do is type first couple of characters and press <TAB> key. CCMake will examine the current typed path and try to expand it to some existing path. If that is possible, it will do it. If not, it will not do anything.

For example:


will expand to


Which regular expressions are supported by cmake?

The MATCHES and MATCHALL uses a regular expression, not a wild card. Here are the meanings of the metacharacters in the cmake regular expression:

^ Matches at beginning of a line
$ Matches at end of a line
. Matches any single character
[ ] Matches any character(s) inside the brackets
[^ ] Matches any character(s) not inside the brackets
- Matches any character in range on either side of a dash
* Matches preceding pattern zero or more times
+ Matches preceding pattern one or more times
? Matches preceding pattern zero or once only
() Saves a matched expression and uses it in a later match

example: "[-][L]([^ ;])+"

matches all strings beginning with -L and ending with a space or a semicolon, the usual linkdirs under Linux.

Why does CMake use full paths, or can I copy my build tree?

CMake uses full paths because:

  1. configured header files may have full paths in them, and moving those files without re-configuring would cause upredicatble behavior.
  2. because cmake supports out of source builds, if custom commands used relative paths to the source tree, the would not work when they are run in the build tree because the current directory would be incorrect.
  3. on Unix systems rpaths are built into executables so they can find shared libraries at run time. If the build tree is moved old executables may use the old shared libraries, and not the new ones.

Can the build tree be copied:

The short answer is NO. The reason is because full paths are used in CMake, see above.

The main problem is that cmake would need to detect when the binary tree has been moved. However, cmake is not run every time a build is done. Currently (cmake 1.6.X, and cmake 1.7.x ) do not support fixing a moved binary tree. This feature may be added before 1.8. If that feature were added, it would still require cmake to be re-run by hand each time a build tree is moved.

CMake does not generate a "make distclean" target. Why?

CMake generates many files related to the build system, but since CMakeLists.txt files can run scripts and other arbitrary commands, there is no way it can keep track of exactly which files are generated as part of running CMake. Providing a distclean target would give users the false impression that it would work as expected. There is a "make clean" target that will remove files generated by the compiler and linker.

A "make distclean" target is only necessary if the user performs an in-source build. CMake supports in-source builds, but we strongly encourage users to adopt the notion of an out-of-source build. Using a build tree that is separate from the source tree will prevent CMake from generating any files in the source tree.

Since the source tree is never changed, no distclean target is needed. A fresh build can be achieved by removing the build tree or creating a separate build tree.

Does CMake's "make install" support DESTDIR?

Yes, when a makefile generator is used. After the build completes, one may run "make install" to install any files the project configured to be installed. Running

make install DESTDIR="/home/me/mydist"

will cause the installation to copy files to "/home/me/mydist/PREFIX/...". This is useful for package maintainers.

Running "make clean" does not remove custom command outputs. Why?

Since CMake 2.0 developer can specify a list of files to be deleted. This can be done using SET_DIRECTORY_PROPERTIES setting property ADDITIONAL_MAKE_CLEAN_FILES to the list of files.

We however strongly recommend using an "out-of-source" build which never writes any files to the source tree. Using a separate source and build tree greatly reduces the need for "make clean" and "make distclean" targets. Please see question 5.6 for more details.

Can I do make uninstall with CMake?

By default CMake does not provide uninstall target. This is done for security reasons, since uninstalling can potentially remove some useful files from the system. That said, nobody prevents you from providing uninstall target in your project. To do that, you need to create CMake script that will remove files.

Create file in the toplevel directory of the project:

IF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")
  MESSAGE(FATAL_ERROR "Cannot find install manifest: \"@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt\"")

FILE(READ "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt" files)
STRING(REGEX REPLACE "\n" ";" files "${files}")
FOREACH(file ${files})
  MESSAGE(STATUS "Uninstalling \"${file}\"")
  IF(NOT EXISTS "${file}")
    MESSAGE(FATAL_ERROR "File \"${file}\" does not exists.")
  ENDIF(NOT EXISTS "${file}")
  EXEC_PROGRAM("@CMAKE_COMMAND@" ARGS "-E remove \"${file}\""
    RETURN_VARIABLE rm_retval)
  IF("${rm_retval}" GREATER 0)
    MESSAGE(FATAL_ERROR "Problem when removing \"${file}\"")
  ENDIF("${rm_retval}" GREATER 0)

Then in the toplevel CMakeLists.txt add the following logic:


  "${CMAKE_COMMAND}" -P "${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake")

Now you will have uninstall target in the toplevel directory of your binary tree.