https://public.kitware.com/Wiki/api.php?action=feedcontributions&user=Plowman&feedformat=atomKitwarePublic - User contributions [en]2024-03-29T02:26:44ZUser contributionsMediaWiki 1.38.6https://public.kitware.com/Wiki/index.php?title=CMake_Useful_Variables&diff=34050CMake Useful Variables2010-11-10T03:24:24Z<p>Plowman: Augment disclaimer at the top of the page a bit more</p>
<hr />
<div>CMake uses and defines many variables, which can be used in CMakeLists.txt files.<br />
<br />
'''NOTE:''' As of CMake 2.6.0 many of these variables have been officially documented in TXT and [http://www.cmake.org/cmake/help/documentation.html HTML] files released with CMake. You may still see some ''useful'' variables here that haven't yet been documented in the official documentation, although the number of these diminishes with every release. This page, in either case, is more of a distilled list of some of the more important variables. The [http://www.cmake.org/cmake/help/documentation.html official documentation] is home of the authoritative guide to all CMake variables, commands, and properties.<br />
<br />
== Locations ==<br />
; CMAKE_BINARY_DIR : if you are building in-source, this is the same as CMAKE_SOURCE_DIR, otherwise this is the top level directory of your build tree<br />
; CMAKE_COMMAND : this is the complete path of the cmake which runs currently (e.g. <tt>/usr/local/bin/cmake</tt>)<br />
; CMAKE_CURRENT_BINARY_DIR : if you are building in-source, this is the same as CMAKE_CURRENT_SOURCE_DIR, otherwise this is the directory where the compiled or generated files from the current CMakeLists.txt will go to<br />
; CMAKE_CURRENT_LIST_FILE : this is the full path to the listfile currently being processed.<br />
; CMAKE_CURRENT_LIST_DIR : (since '''2.8.3''') this is the directory of the listfile currently being processed.<br />
; CMAKE_CURRENT_LIST_LINE : this is linenumber where the variable is used.<br />
CMakeLists.txt contains the PROJECT() command<br />
; CMAKE_CURRENT_SOURCE_DIR : this is the directory where the currently processed CMakeLists.txt is located in<br />
; CMAKE_FILES_DIRECTORY : the directory within the current binary directory that contains all the CMake generated files. Typically evaluates to "/CMakeFiles". Note the leading slash for the directory. Typically used with the current binary directory, i.e. ${CMAKE_CURRENT_BINARY_DIR}${CMAKE_FILES_DIRECTORY}<br />
; CMAKE_MODULE_PATH : tell CMake to search first in directories listed in CMAKE_MODULE_PATH when you use FIND_PACKAGE() or INCLUDE()<br> <tt> SET(CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/MyCMakeScripts)</tt><br> <tt>FIND_PACKAGE(HelloWorld)</tt><br />
; CMAKE_ROOT : this is the CMake installation directory<br />
; CMAKE_SOURCE_DIR : this is the directory, from which cmake was started, i.e. the top level source directory<br />
; EXECUTABLE_OUTPUT_PATH : set this variable to specify a common place where CMake should put all executable files (instead of CMAKE_CURRENT_BINARY_DIR)<br> <tt>SET(EXECUTABLE_OUTPUT_PATH ${PROJECT_BINARY_DIR}/bin)</tt><br />
; LIBRARY_OUTPUT_PATH : set this variable to specify a common place where CMake should put all libraries (instead of CMAKE_CURRENT_BINARY_DIR)<br> <tt>SET(LIBRARY_OUTPUT_PATH ${PROJECT_BINARY_DIR}/lib)</tt><br />
; PROJECT_NAME : the name of the project set by PROJECT() command.<br />
; CMAKE_PROJECT_NAME : the name of the first project set by the PROJECT() command, i.e. the top level project.<br />
; PROJECT_BINARY_DIR : contains the full path to the top level directory of your build tree<br />
; PROJECT_SOURCE_DIR : contains the full path to the root of your project source directory, i.e. to the nearest directory where CMakeLists.txt contains the PROJECT() command<br />
<br />
== Environment Variables ==<br />
<br />
These are environment variables which effect cmake behaviour.<br />
<br />
; CMAKE_INCLUDE_PATH : This is used when searching for include files e.g. using the FIND_PATH() command. If you have headers in non-standard locations, it may be useful to set this variable to this directory (e.g. <tt>/sw/include</tt> on Mac OS X). If you need several directories, separate them by the platform specific separators (e.g. ":" on UNIX)<br />
<br />
; CMAKE_LIBRARY_PATH : This is used when searching for libraries e.g. using the FIND_LIBRARY() command. If you have libraries in non-standard locations, it may be useful to set this variable to this directory (e.g. <tt>/sw/lib</tt> on Mac OS X). If you need several directories, separate them by the platform specific separators (e.g. ":" on UNIX)<br />
<br />
; CMAKE_PREFIX_PATH : (since CMake '''2.6.0''') This is used when searching for include files, binaries, or libraries using either the FIND_PATH(), FIND_PROGRAM(), or FIND_LIBRARY() commands. For each path in the CMAKE_PREFIX_PATH list, CMake will check "PATH/include" and "PATH" when FIND_PATH() is called, "PATH/bin" and "PATH" when FIND_PROGRAM() is called, and "PATH/lib" and "PATH" when FIND_LIBRARY() is called. See the documentation for FIND_LIBRARY(), FIND_PATH(), and FIND_PROGRAM() for more details.<br />
<br />
; CMAKE_INSTALL_ALWAYS : If set during installation CMake will install all files whether they have changed or not. The default when this is not set is to install only files that have changed since the previous installation. In both cases all files are reported to indicate CMake knows they are up to date in the installed location.<br />
<br />
; $ENV{name} : This is not an environment variable , but this is how you can access environment variables from cmake files. It returns the content of the environment variable with the given name (e.g. <tt>$ENV{PROGRAMFILES}</tt>)<br />
<br />
== System & Compiler Information ==<br />
; CMAKE_MAJOR_VERSION : major version number for CMake, e.g. the "2" in CMake 2.4.3<br />
; CMAKE_MINOR_VERSION : minor version number for CMake, e.g. the "4" in CMake 2.4.3<br />
; CMAKE_PATCH_VERSION : patch version number for CMake, e.g. the "3" in CMake 2.4.3<br />
; CMAKE_SYSTEM : the complete system name, e.g. "Linux-2.4.22", "FreeBSD-5.4-RELEASE" or "Windows 5.1"<br />
; CMAKE_SYSTEM_NAME : the short system name, e.g. "Linux", "FreeBSD" or "Windows"<br />
; CMAKE_SYSTEM_VERSION : only the version part of CMAKE_SYSTEM<br />
; CMAKE_SYSTEM_PROCESSOR : the processor name (e.g. "Intel(R) Pentium(R) M processor 2.00GHz")<br />
; CMAKE_GENERATOR : the generator specified on the commandline.<br />
; UNIX : is TRUE on all UNIX-like OS's, including Apple OS X and ''CygWin''<br />
; WIN32 : is TRUE on Windows, including ''CygWin''<br />
; APPLE : is TRUE on Apple systems. Note this does ''not'' imply the system is Mac OS X, only that __APPLE__ is #defined in C/C++ header files. Obtain more specific system information via CMAKE_SYSTEM_VERSION, i.e. IF(${CMAKE_SYSTEM_NAME} MATCHES "Darwin"), then it's Mac OS X.<br />
; MINGW : is TRUE when using the MinGW compiler in Windows<br />
; MSYS : is TRUE when using the MSYS developer environment in Windows<br />
; CYGWIN : is TRUE on Windows when using the ''CygWin'' version of cmake<br />
; BORLAND : is TRUE on Windows when using a Borland compiler<br />
; WATCOM : is TRUE on Windows when using the Open Watcom compiler<br />
; MSVC, MSVC_IDE, MSVC60, MSVC70, MSVC71, MSVC80, CMAKE_COMPILER_2005, MSVC90, MSVC10 (Visual Studio 2010) : Microsoft compiler<br />
; CMAKE_COMPILER_IS_GNUCC : is TRUE if the compiler is a variant of gcc<br />
; CMAKE_COMPILER_IS_GNUCXX : is TRUE if the compiler is a variant of g++<br />
<br />
== Various Options ==<br />
; CMAKE_SKIP_RULE_DEPENDENCY : set this to true if you don't want to rebuild the object files if the rules have changed, but not the actual source files or headers (e.g. if you changed the some compiler switches)<br />
; CMAKE_SKIP_INSTALL_ALL_DEPENDENCY : since CMake 2.1 the install rule depends on all, i.e. everything will be built before installing. If you don't like this, set this one to true.<br />
; CMAKE_SKIP_RPATH : If set, runtime paths are not added when using shared libraries. Default it is set to OFF.<br />
; CMAKE_INCLUDE_CURRENT_DIR : automatically add CMAKE_CURRENT_SOURCE_DIR and CMAKE_CURRENT_BINARY_DIR to the include directories in every processed CMakeLists.txt. It behaves as if you had used INCLUDE_DIRECTORIES in every CMakeLists.txt file or your project. The added directory paths are relative to the being-processed CMakeLists.txt, which is different in each directory. (See [http://www.cmake.org/pipermail/cmake/2007-March/013193.html this thread] for more details).<br />
; CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE : order the include directories so that directories which are in the source or build tree always come before directories outside the project.<br />
; CMAKE_VERBOSE_MAKEFILE : set this to true if you are using makefiles and want to see the full compile and link commands instead of only the shortened ones<br />
; CMAKE_SUPPRESS_REGENERATION : this will cause CMake to not put in the rules that re-run CMake. This might be useful if you want to use the generated build files on another machine.<br />
; CMAKE_COLOR_MAKEFILE : create Makefiles with colored output (defaults to on)<br />
; CMAKE_SKIP_PREPROCESSED_SOURCE_RULES : (since 2.4.4) if set to TRUE, the generated Makefiles will not contain rules for creating preprocessed files (foo.i)<br />
; CMAKE_SKIP_ASSEMBLY_SOURCE_RULES : (since 2.4.4) if set to TRUE, the generated Makefiles will not contain rules for creating compiled, but not yet assembled files (foo.s)<br />
; CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS : (redundant since '''2.6.0''') set this to true if you don't want to have to bother having your IF() ELSE() and ENDIF() conditions match. In other words so you can do this:<br />
<br />
IF(FOO)<br />
SET(BAR bar.cc)<br />
ELSE()<br />
SET(BAR bar2.cc)<br />
ENDIF()<br />
<br />
== Compilers and Tools ==<br />
<br />
; BUILD_SHARED_LIBS : if this is set to ON, then all libraries are built as shared libraries by default.<br> <tt>SET(BUILD_SHARED_LIBS ON)</tt><br />
<br />
; CMAKE_AR : tool for creating libraries. See also CMAKE_RANLIB, as "ar" and "ranlib" are typically used together.<br />
; CMAKE_BUILD_TYPE : A variable which controls the type of build when using a ''single-configuration generator'' like the Makefile generator. CMake will create by default the following variables when using a single-configuration generator:<br />
<br />
*None (CMAKE_C_FLAGS or CMAKE_CXX_FLAGS used) <br />
*Debug (CMAKE_C_FLAGS_DEBUG or CMAKE_CXX_FLAGS_DEBUG) <br />
*Release (CMAKE_C_FLAGS_RELEASE or CMAKE_CXX_FLAGS_RELEASE)<br />
*RelWithDebInfo (CMAKE_C_FLAGS_RELWITHDEBINFO or CMAKE_CXX_FLAGS_RELWITHDEBINFO<br />
*MinSizeRel (CMAKE_C_FLAGS_MINSIZEREL or CMAKE_CXX_FLAGS_MINSIZEREL)<br />
<br />
You can use these default compilation flags (or modify them) by setting the CMAKE_BUILD_TYPE variable at configuration time from within the "ccmake" GUI. '''Note!''' The default values for these flags change with different compilers. If CMake does not know your compiler, the contents will be empty.<br />
<br />
If you are using the Makefile generator, you can create your own build type like this:<br><br />
<tt>SET(CMAKE_BUILD_TYPE distribution)<br><br />
SET(CMAKE_CXX_FLAGS_DISTRIBUTION "-O3")<br><br />
SET(CMAKE_C_FLAGS_DISTRIBUTION "-O3")</tt><br />
<br />
Note that CMAKE_BUILD_TYPE is not initialized with a readable value at configuration time. This is because the user is free to select a build type at build time. Use CMAKE_CFG_INTDIR if you need a variable that evaluates to the correct build time directory.<br />
<br />
; CMAKE_CONFIGURATION_TYPES : When using a ''multi-configuration generator'', such as the one for '''Visual Studio''', this variable contains a list of the available configurations.<br />
; CMAKE_C_COMPILER : the compiler used for C files. Normally it is detected and set during the CMake run, but you can override it at configuration time. '''Note!''' It can not be changed after the first cmake or ccmake run. Although the gui allows to enter an alternative, it will be ignored in the next 'configure' run. Use for example: <br><tt>CC=gcc-3.3 CXX=g++-3.3 cmake</tt><br> to set the compiler. (You can also set CMAKE_C_COMPILER_INIT, before any PROJECT() or ENABLE_LANGUAGE() command.) Any other way (like writing <tt>make CC=gcc-3.3 CXX=g++-3.3</tt>) will not work. When using distcc or similar tools, you need to write: <br><tt>CC="distcc gcc-3.3" CXX="distcc g++-3.3" cmake</tt><br> However, this will empty all your CMAKE_..._FLAGS_... above.<br><br />
<br />
; CMAKE_C_FLAGS : the compiler flags for compiling C sources. Note you can also specify switches with ADD_DEFINITIONS().<br />
; CMAKE_C_FLAGS_DEBUG : compiler flags for compiling a debug build from C sources.<br />
; CMAKE_C_FLAGS_RELEASE : compiler flags for compiling a release build from C sources.<br />
; CMAKE_C_FLAGS_RELWITHDEBINFO : compiler flags for compiling a release build with debug flags from C sources.<br />
; CMAKE_C_OUTPUT_EXTENSION : what C object files end in. Typically .o or .obj.<br />
; CMAKE_CFG_INTDIR : the configuration directory for the project. For MSVC generators it is typically one of "/Debug", "/Release", "/RelWithDebInfo", or "/MinSizeRel". For other compiler generators it is typically "/", as they don't use MSVC-style configuration directories.<br />
; CMAKE_CXX_COMPILER : the compiler used for C++ files. Normally it is detected and set during the CMake run, but you can override it at configuration time. '''Note!''' It can not be changed after the first cmake or ccmake run. See CMAKE_C_COMPILER above.<br />
<br />
; CMAKE_CXX_FLAGS : the compiler flags for compiling C++ sources. Note you can also specify switches with ADD_DEFINITIONS().<br />
; CMAKE_CXX_FLAGS_DEBUG : compiler flags for compiling a debug build from C++ sources.<br />
; CMAKE_CXX_FLAGS_RELEASE : compiler flags for compiling a release build from C++ sources.<br />
; CMAKE_CXX_FLAGS_RELWITHDEBINFO : compiler flags for compiling a release build with debug flags from C++ sources.<br />
; CMAKE_RANLIB : tool for creating libraries. See also CMAKE_AR, as "ar" and "ranlib" are typically used together.<br />
<br />
; CMAKE_SHARED_LINKER_FLAGS : additional compiler flags for building shared libraries, e.g.: <br><br />
<tt>set(CMAKE_SHARED_LINKER_FLAGS "-Wl,--no-undefined")</tt><br><br />
On Unix systems, this will make linker report any unresolved symbols from object files (which is quite typical when you compile many targets in CMake projects, but do not bother with linking target dependencies in proper order).<br />
<br />
== Prefixes, Suffixes (Postfixes), and Extensions ==<br />
; CMAKE_C_IGNORE_EXTENSIONS :<br />
; CMAKE_C_OUTPUT_EXTENSION : what C object files end in. Typically .o or .obj.<br />
; CMAKE_C_SOURCE_FILE_EXTENSIONS :<br />
; CMAKE_CXX_IGNORE_EXTENSIONS :<br />
; CMAKE_CXX_OUTPUT_EXTENSION : what C++ object files end in. Typically .o or .obj.<br />
; CMAKE_CXX_SOURCE_FILE_EXTENSIONS :<br />
; CMAKE_EXECUTABLE_SUFFIX :<br />
; CMAKE_FIND_LIBRARY_PREFIXES :<br />
; CMAKE_FIND_LIBRARY_SUFFIXES :<br />
; CMAKE_IMPORT_LIBRARY_PREFIX : Windows-specific. Appears to be read-only. Use SET_TARGET_PROPERTIES.<br />
; CMAKE_IMPORT_LIBRARY_SUFFIX : Windows-specific. Appears to be read-only. Use SET_TARGET_PROPERTIES.<br />
; CMAKE_LINK_LIBRARY_SUFFIX : Windows-specific.<br />
; CMAKE_RC_OUTPUT_EXTENSION : Windows-specific.<br />
; CMAKE_RC_SOURCE_FILE_EXTENSIONS : Windows-specific.<br />
; CMAKE_SHARED_LIBRARY_PREFIX : Appears to be read-only. Use SET_TARGET_PROPERTIES.<br />
; CMAKE_SHARED_LIBRARY_SUFFIX : Appears to be read-only. Use SET_TARGET_PROPERTIES.<br />
; CMAKE_SHARED_MODULE_PREFIX :<br />
; CMAKE_SHARED_MODULE_SUFFIX :<br />
; CMAKE_STATIC_LIBRARY_PREFIX : Appears to be read-only. Use SET_TARGET_PROPERTIES.<br />
; CMAKE_STATIC_LIBRARY_SUFFIX : Appears to be read-only. Use SET_TARGET_PROPERTIES.<br />
; CMAKE_DEBUG_POSTFIX : Add a custom "postfix" to static and shared libraries when in Debug build. Example: mylib_d.lib.<br />
; CMAKE_RELEASE_POSTFIX :<br />
; CMAKE_<config>_POSTFIX :<br />
<br />
== Build rules ==<br />
<br />
Build rules are defined in CMakeCInformation.cmake and CMakeCXXInformation.cmake.<br />
<br />
Rules for C++ sources:<br />
<br />
; CMAKE_CXX_CREATE_SHARED_LIBRARY<br />
; CMAKE_CXX_CREATE_SHARED_MODULE<br />
; CMAKE_CXX_CREATE_STATIC_LIBRARY<br />
; CMAKE_CXX_COMPILE_OBJECT<br />
; CMAKE_CXX_LINK_EXECUTABLE<br />
<br />
and the equivalents for C sources:<br />
<br />
; CMAKE_C_CREATE_SHARED_LIBRARY<br />
; CMAKE_C_CREATE_SHARED_MODULE<br />
; CMAKE_C_CREATE_STATIC_LIBRARY<br />
; CMAKE_C_COMPILE_OBJECT<br />
; CMAKE_C_LINK_EXECUTABLE<br />
<br />
You can override the variables manually, e.g. replacing some flags in the linker command, but you can't change the value of the variables in sharp braces. Usually you don't have to change these rules, only in rare cases. You should only do this if you know what you are doing and there is no other way.<br />
<br />
== Expansion Rules ==<br />
From examining the source code the following style names exist:<br />
<br />
; ASSEMBLY_SOURCE<br />
; FLAGS<br />
; LANGUAGE_COMPILE_FLAGS<br />
; LINK_FLAGS<br />
; LINK_LIBRARIES<br />
; OBJECT<br />
; OBJECTS<br />
; OBJECTS_QUOTED<br />
; OBJECT_DIR<br />
; PREPROCESSED_SOURCE<br />
; SOURCE<br />
; TARGET<br />
; TARGET_BASE<br />
; TARGET_IMPLIB<br />
; TARGET_INSTALLNAME_DIR<br />
; TARGET_PDB<br />
; TARGET_QUOTED<br />
; TARGET_SONAME<br />
; TARGET_VERSION_MAJOR<br />
; TARGET_VERSION_MINOR<br />
<br />
Please note you can set these properties globally using SET or LIST, or for a single target using SET_TARGET_PROPERTIES.<br />
<br />
== Variables not listed here ==<br />
CMake has many more variables than are listed above. Documenting all of them is an ongoing project. We need everyone's help with this. If you know of a CMake variable that is not listed here, please edit the wiki and add it. Don't worry about whether you have a precise description for it. This is a wiki, and other people can provide a better description as time goes on.<br />
<br />
How does one find out about additional variables? The CMake mailing list is probably the best resource. Some things can be learned from inspecting the CMake source code. Many - but not all of them - are also listed by this [[CMake_Useful_Variables/Get_Variables_From_CMake_Dashboards|Dashboard script for extracting variables]]. The output of this script is rather raw, but it is a good starting point for finding more variables.<br />
<br />
When a CMake dashboard is run, a "SystemInformation test" is usually run as well. Among other things, it lists the names and values of all of the CMake variables that are in use when the test is run. The script looks at the SystemInformation test output, and uses regular expressions to find the start and end of the "AllVariables.txt" section. It prints the results out in the form of XML.<br />
<br />
== Logging code ==<br />
This code may be placed in a CMakelists.txt file to create status messages<br />
that log a number of the variables documented above. It is not a complete list, however. The variables are not auto-generated from the wiki, it is just sample code. Add whatever variables you are interested in.<br />
#[[CMake_Useful_Variables/Logging_Useful_Variables | Sample code for logging useful variables.]]<br />
<br />
<br />
{{CMake/Template/Footer}}</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake_Useful_Variables&diff=34049CMake Useful Variables2010-11-10T03:20:21Z<p>Plowman: /* Locations */ Add CMAKE_CURRENT_LIST_DIR documentation</p>
<hr />
<div>CMake uses and defines many variables, which can be used in CMakeLists.txt files.<br />
<br />
'''NOTE:''' As of CMake 2.6.0 many of these variables have been officially documented in TXT and [http://www.cmake.org/cmake/help/documentation.html HTML] files released with CMake. You may still see some ''useful'' variables here that haven't been documented in the official documentation. The official documentation is home of the authoritative guide to all CMake variables, commands, and properties.<br />
<br />
== Locations ==<br />
; CMAKE_BINARY_DIR : if you are building in-source, this is the same as CMAKE_SOURCE_DIR, otherwise this is the top level directory of your build tree<br />
; CMAKE_COMMAND : this is the complete path of the cmake which runs currently (e.g. <tt>/usr/local/bin/cmake</tt>)<br />
; CMAKE_CURRENT_BINARY_DIR : if you are building in-source, this is the same as CMAKE_CURRENT_SOURCE_DIR, otherwise this is the directory where the compiled or generated files from the current CMakeLists.txt will go to<br />
; CMAKE_CURRENT_LIST_FILE : this is the full path to the listfile currently being processed.<br />
; CMAKE_CURRENT_LIST_DIR : (since '''2.8.3''') this is the directory of the listfile currently being processed.<br />
; CMAKE_CURRENT_LIST_LINE : this is linenumber where the variable is used.<br />
CMakeLists.txt contains the PROJECT() command<br />
; CMAKE_CURRENT_SOURCE_DIR : this is the directory where the currently processed CMakeLists.txt is located in<br />
; CMAKE_FILES_DIRECTORY : the directory within the current binary directory that contains all the CMake generated files. Typically evaluates to "/CMakeFiles". Note the leading slash for the directory. Typically used with the current binary directory, i.e. ${CMAKE_CURRENT_BINARY_DIR}${CMAKE_FILES_DIRECTORY}<br />
; CMAKE_MODULE_PATH : tell CMake to search first in directories listed in CMAKE_MODULE_PATH when you use FIND_PACKAGE() or INCLUDE()<br> <tt> SET(CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/MyCMakeScripts)</tt><br> <tt>FIND_PACKAGE(HelloWorld)</tt><br />
; CMAKE_ROOT : this is the CMake installation directory<br />
; CMAKE_SOURCE_DIR : this is the directory, from which cmake was started, i.e. the top level source directory<br />
; EXECUTABLE_OUTPUT_PATH : set this variable to specify a common place where CMake should put all executable files (instead of CMAKE_CURRENT_BINARY_DIR)<br> <tt>SET(EXECUTABLE_OUTPUT_PATH ${PROJECT_BINARY_DIR}/bin)</tt><br />
; LIBRARY_OUTPUT_PATH : set this variable to specify a common place where CMake should put all libraries (instead of CMAKE_CURRENT_BINARY_DIR)<br> <tt>SET(LIBRARY_OUTPUT_PATH ${PROJECT_BINARY_DIR}/lib)</tt><br />
; PROJECT_NAME : the name of the project set by PROJECT() command.<br />
; CMAKE_PROJECT_NAME : the name of the first project set by the PROJECT() command, i.e. the top level project.<br />
; PROJECT_BINARY_DIR : contains the full path to the top level directory of your build tree<br />
; PROJECT_SOURCE_DIR : contains the full path to the root of your project source directory, i.e. to the nearest directory where CMakeLists.txt contains the PROJECT() command<br />
<br />
== Environment Variables ==<br />
<br />
These are environment variables which effect cmake behaviour.<br />
<br />
; CMAKE_INCLUDE_PATH : This is used when searching for include files e.g. using the FIND_PATH() command. If you have headers in non-standard locations, it may be useful to set this variable to this directory (e.g. <tt>/sw/include</tt> on Mac OS X). If you need several directories, separate them by the platform specific separators (e.g. ":" on UNIX)<br />
<br />
; CMAKE_LIBRARY_PATH : This is used when searching for libraries e.g. using the FIND_LIBRARY() command. If you have libraries in non-standard locations, it may be useful to set this variable to this directory (e.g. <tt>/sw/lib</tt> on Mac OS X). If you need several directories, separate them by the platform specific separators (e.g. ":" on UNIX)<br />
<br />
; CMAKE_PREFIX_PATH : (since CMake '''2.6.0''') This is used when searching for include files, binaries, or libraries using either the FIND_PATH(), FIND_PROGRAM(), or FIND_LIBRARY() commands. For each path in the CMAKE_PREFIX_PATH list, CMake will check "PATH/include" and "PATH" when FIND_PATH() is called, "PATH/bin" and "PATH" when FIND_PROGRAM() is called, and "PATH/lib" and "PATH" when FIND_LIBRARY() is called. See the documentation for FIND_LIBRARY(), FIND_PATH(), and FIND_PROGRAM() for more details.<br />
<br />
; CMAKE_INSTALL_ALWAYS : If set during installation CMake will install all files whether they have changed or not. The default when this is not set is to install only files that have changed since the previous installation. In both cases all files are reported to indicate CMake knows they are up to date in the installed location.<br />
<br />
; $ENV{name} : This is not an environment variable , but this is how you can access environment variables from cmake files. It returns the content of the environment variable with the given name (e.g. <tt>$ENV{PROGRAMFILES}</tt>)<br />
<br />
== System & Compiler Information ==<br />
; CMAKE_MAJOR_VERSION : major version number for CMake, e.g. the "2" in CMake 2.4.3<br />
; CMAKE_MINOR_VERSION : minor version number for CMake, e.g. the "4" in CMake 2.4.3<br />
; CMAKE_PATCH_VERSION : patch version number for CMake, e.g. the "3" in CMake 2.4.3<br />
; CMAKE_SYSTEM : the complete system name, e.g. "Linux-2.4.22", "FreeBSD-5.4-RELEASE" or "Windows 5.1"<br />
; CMAKE_SYSTEM_NAME : the short system name, e.g. "Linux", "FreeBSD" or "Windows"<br />
; CMAKE_SYSTEM_VERSION : only the version part of CMAKE_SYSTEM<br />
; CMAKE_SYSTEM_PROCESSOR : the processor name (e.g. "Intel(R) Pentium(R) M processor 2.00GHz")<br />
; CMAKE_GENERATOR : the generator specified on the commandline.<br />
; UNIX : is TRUE on all UNIX-like OS's, including Apple OS X and ''CygWin''<br />
; WIN32 : is TRUE on Windows, including ''CygWin''<br />
; APPLE : is TRUE on Apple systems. Note this does ''not'' imply the system is Mac OS X, only that __APPLE__ is #defined in C/C++ header files. Obtain more specific system information via CMAKE_SYSTEM_VERSION, i.e. IF(${CMAKE_SYSTEM_NAME} MATCHES "Darwin"), then it's Mac OS X.<br />
; MINGW : is TRUE when using the MinGW compiler in Windows<br />
; MSYS : is TRUE when using the MSYS developer environment in Windows<br />
; CYGWIN : is TRUE on Windows when using the ''CygWin'' version of cmake<br />
; BORLAND : is TRUE on Windows when using a Borland compiler<br />
; WATCOM : is TRUE on Windows when using the Open Watcom compiler<br />
; MSVC, MSVC_IDE, MSVC60, MSVC70, MSVC71, MSVC80, CMAKE_COMPILER_2005, MSVC90, MSVC10 (Visual Studio 2010) : Microsoft compiler<br />
; CMAKE_COMPILER_IS_GNUCC : is TRUE if the compiler is a variant of gcc<br />
; CMAKE_COMPILER_IS_GNUCXX : is TRUE if the compiler is a variant of g++<br />
<br />
== Various Options ==<br />
; CMAKE_SKIP_RULE_DEPENDENCY : set this to true if you don't want to rebuild the object files if the rules have changed, but not the actual source files or headers (e.g. if you changed the some compiler switches)<br />
; CMAKE_SKIP_INSTALL_ALL_DEPENDENCY : since CMake 2.1 the install rule depends on all, i.e. everything will be built before installing. If you don't like this, set this one to true.<br />
; CMAKE_SKIP_RPATH : If set, runtime paths are not added when using shared libraries. Default it is set to OFF.<br />
; CMAKE_INCLUDE_CURRENT_DIR : automatically add CMAKE_CURRENT_SOURCE_DIR and CMAKE_CURRENT_BINARY_DIR to the include directories in every processed CMakeLists.txt. It behaves as if you had used INCLUDE_DIRECTORIES in every CMakeLists.txt file or your project. The added directory paths are relative to the being-processed CMakeLists.txt, which is different in each directory. (See [http://www.cmake.org/pipermail/cmake/2007-March/013193.html this thread] for more details).<br />
; CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE : order the include directories so that directories which are in the source or build tree always come before directories outside the project.<br />
; CMAKE_VERBOSE_MAKEFILE : set this to true if you are using makefiles and want to see the full compile and link commands instead of only the shortened ones<br />
; CMAKE_SUPPRESS_REGENERATION : this will cause CMake to not put in the rules that re-run CMake. This might be useful if you want to use the generated build files on another machine.<br />
; CMAKE_COLOR_MAKEFILE : create Makefiles with colored output (defaults to on)<br />
; CMAKE_SKIP_PREPROCESSED_SOURCE_RULES : (since 2.4.4) if set to TRUE, the generated Makefiles will not contain rules for creating preprocessed files (foo.i)<br />
; CMAKE_SKIP_ASSEMBLY_SOURCE_RULES : (since 2.4.4) if set to TRUE, the generated Makefiles will not contain rules for creating compiled, but not yet assembled files (foo.s)<br />
; CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS : (redundant since '''2.6.0''') set this to true if you don't want to have to bother having your IF() ELSE() and ENDIF() conditions match. In other words so you can do this:<br />
<br />
IF(FOO)<br />
SET(BAR bar.cc)<br />
ELSE()<br />
SET(BAR bar2.cc)<br />
ENDIF()<br />
<br />
== Compilers and Tools ==<br />
<br />
; BUILD_SHARED_LIBS : if this is set to ON, then all libraries are built as shared libraries by default.<br> <tt>SET(BUILD_SHARED_LIBS ON)</tt><br />
<br />
; CMAKE_AR : tool for creating libraries. See also CMAKE_RANLIB, as "ar" and "ranlib" are typically used together.<br />
; CMAKE_BUILD_TYPE : A variable which controls the type of build when using a ''single-configuration generator'' like the Makefile generator. CMake will create by default the following variables when using a single-configuration generator:<br />
<br />
*None (CMAKE_C_FLAGS or CMAKE_CXX_FLAGS used) <br />
*Debug (CMAKE_C_FLAGS_DEBUG or CMAKE_CXX_FLAGS_DEBUG) <br />
*Release (CMAKE_C_FLAGS_RELEASE or CMAKE_CXX_FLAGS_RELEASE)<br />
*RelWithDebInfo (CMAKE_C_FLAGS_RELWITHDEBINFO or CMAKE_CXX_FLAGS_RELWITHDEBINFO<br />
*MinSizeRel (CMAKE_C_FLAGS_MINSIZEREL or CMAKE_CXX_FLAGS_MINSIZEREL)<br />
<br />
You can use these default compilation flags (or modify them) by setting the CMAKE_BUILD_TYPE variable at configuration time from within the "ccmake" GUI. '''Note!''' The default values for these flags change with different compilers. If CMake does not know your compiler, the contents will be empty.<br />
<br />
If you are using the Makefile generator, you can create your own build type like this:<br><br />
<tt>SET(CMAKE_BUILD_TYPE distribution)<br><br />
SET(CMAKE_CXX_FLAGS_DISTRIBUTION "-O3")<br><br />
SET(CMAKE_C_FLAGS_DISTRIBUTION "-O3")</tt><br />
<br />
Note that CMAKE_BUILD_TYPE is not initialized with a readable value at configuration time. This is because the user is free to select a build type at build time. Use CMAKE_CFG_INTDIR if you need a variable that evaluates to the correct build time directory.<br />
<br />
; CMAKE_CONFIGURATION_TYPES : When using a ''multi-configuration generator'', such as the one for '''Visual Studio''', this variable contains a list of the available configurations.<br />
; CMAKE_C_COMPILER : the compiler used for C files. Normally it is detected and set during the CMake run, but you can override it at configuration time. '''Note!''' It can not be changed after the first cmake or ccmake run. Although the gui allows to enter an alternative, it will be ignored in the next 'configure' run. Use for example: <br><tt>CC=gcc-3.3 CXX=g++-3.3 cmake</tt><br> to set the compiler. (You can also set CMAKE_C_COMPILER_INIT, before any PROJECT() or ENABLE_LANGUAGE() command.) Any other way (like writing <tt>make CC=gcc-3.3 CXX=g++-3.3</tt>) will not work. When using distcc or similar tools, you need to write: <br><tt>CC="distcc gcc-3.3" CXX="distcc g++-3.3" cmake</tt><br> However, this will empty all your CMAKE_..._FLAGS_... above.<br><br />
<br />
; CMAKE_C_FLAGS : the compiler flags for compiling C sources. Note you can also specify switches with ADD_DEFINITIONS().<br />
; CMAKE_C_FLAGS_DEBUG : compiler flags for compiling a debug build from C sources.<br />
; CMAKE_C_FLAGS_RELEASE : compiler flags for compiling a release build from C sources.<br />
; CMAKE_C_FLAGS_RELWITHDEBINFO : compiler flags for compiling a release build with debug flags from C sources.<br />
; CMAKE_C_OUTPUT_EXTENSION : what C object files end in. Typically .o or .obj.<br />
; CMAKE_CFG_INTDIR : the configuration directory for the project. For MSVC generators it is typically one of "/Debug", "/Release", "/RelWithDebInfo", or "/MinSizeRel". For other compiler generators it is typically "/", as they don't use MSVC-style configuration directories.<br />
; CMAKE_CXX_COMPILER : the compiler used for C++ files. Normally it is detected and set during the CMake run, but you can override it at configuration time. '''Note!''' It can not be changed after the first cmake or ccmake run. See CMAKE_C_COMPILER above.<br />
<br />
; CMAKE_CXX_FLAGS : the compiler flags for compiling C++ sources. Note you can also specify switches with ADD_DEFINITIONS().<br />
; CMAKE_CXX_FLAGS_DEBUG : compiler flags for compiling a debug build from C++ sources.<br />
; CMAKE_CXX_FLAGS_RELEASE : compiler flags for compiling a release build from C++ sources.<br />
; CMAKE_CXX_FLAGS_RELWITHDEBINFO : compiler flags for compiling a release build with debug flags from C++ sources.<br />
; CMAKE_RANLIB : tool for creating libraries. See also CMAKE_AR, as "ar" and "ranlib" are typically used together.<br />
<br />
; CMAKE_SHARED_LINKER_FLAGS : additional compiler flags for building shared libraries, e.g.: <br><br />
<tt>set(CMAKE_SHARED_LINKER_FLAGS "-Wl,--no-undefined")</tt><br><br />
On Unix systems, this will make linker report any unresolved symbols from object files (which is quite typical when you compile many targets in CMake projects, but do not bother with linking target dependencies in proper order).<br />
<br />
== Prefixes, Suffixes (Postfixes), and Extensions ==<br />
; CMAKE_C_IGNORE_EXTENSIONS :<br />
; CMAKE_C_OUTPUT_EXTENSION : what C object files end in. Typically .o or .obj.<br />
; CMAKE_C_SOURCE_FILE_EXTENSIONS :<br />
; CMAKE_CXX_IGNORE_EXTENSIONS :<br />
; CMAKE_CXX_OUTPUT_EXTENSION : what C++ object files end in. Typically .o or .obj.<br />
; CMAKE_CXX_SOURCE_FILE_EXTENSIONS :<br />
; CMAKE_EXECUTABLE_SUFFIX :<br />
; CMAKE_FIND_LIBRARY_PREFIXES :<br />
; CMAKE_FIND_LIBRARY_SUFFIXES :<br />
; CMAKE_IMPORT_LIBRARY_PREFIX : Windows-specific. Appears to be read-only. Use SET_TARGET_PROPERTIES.<br />
; CMAKE_IMPORT_LIBRARY_SUFFIX : Windows-specific. Appears to be read-only. Use SET_TARGET_PROPERTIES.<br />
; CMAKE_LINK_LIBRARY_SUFFIX : Windows-specific.<br />
; CMAKE_RC_OUTPUT_EXTENSION : Windows-specific.<br />
; CMAKE_RC_SOURCE_FILE_EXTENSIONS : Windows-specific.<br />
; CMAKE_SHARED_LIBRARY_PREFIX : Appears to be read-only. Use SET_TARGET_PROPERTIES.<br />
; CMAKE_SHARED_LIBRARY_SUFFIX : Appears to be read-only. Use SET_TARGET_PROPERTIES.<br />
; CMAKE_SHARED_MODULE_PREFIX :<br />
; CMAKE_SHARED_MODULE_SUFFIX :<br />
; CMAKE_STATIC_LIBRARY_PREFIX : Appears to be read-only. Use SET_TARGET_PROPERTIES.<br />
; CMAKE_STATIC_LIBRARY_SUFFIX : Appears to be read-only. Use SET_TARGET_PROPERTIES.<br />
; CMAKE_DEBUG_POSTFIX : Add a custom "postfix" to static and shared libraries when in Debug build. Example: mylib_d.lib.<br />
; CMAKE_RELEASE_POSTFIX :<br />
; CMAKE_<config>_POSTFIX :<br />
<br />
== Build rules ==<br />
<br />
Build rules are defined in CMakeCInformation.cmake and CMakeCXXInformation.cmake.<br />
<br />
Rules for C++ sources:<br />
<br />
; CMAKE_CXX_CREATE_SHARED_LIBRARY<br />
; CMAKE_CXX_CREATE_SHARED_MODULE<br />
; CMAKE_CXX_CREATE_STATIC_LIBRARY<br />
; CMAKE_CXX_COMPILE_OBJECT<br />
; CMAKE_CXX_LINK_EXECUTABLE<br />
<br />
and the equivalents for C sources:<br />
<br />
; CMAKE_C_CREATE_SHARED_LIBRARY<br />
; CMAKE_C_CREATE_SHARED_MODULE<br />
; CMAKE_C_CREATE_STATIC_LIBRARY<br />
; CMAKE_C_COMPILE_OBJECT<br />
; CMAKE_C_LINK_EXECUTABLE<br />
<br />
You can override the variables manually, e.g. replacing some flags in the linker command, but you can't change the value of the variables in sharp braces. Usually you don't have to change these rules, only in rare cases. You should only do this if you know what you are doing and there is no other way.<br />
<br />
== Expansion Rules ==<br />
From examining the source code the following style names exist:<br />
<br />
; ASSEMBLY_SOURCE<br />
; FLAGS<br />
; LANGUAGE_COMPILE_FLAGS<br />
; LINK_FLAGS<br />
; LINK_LIBRARIES<br />
; OBJECT<br />
; OBJECTS<br />
; OBJECTS_QUOTED<br />
; OBJECT_DIR<br />
; PREPROCESSED_SOURCE<br />
; SOURCE<br />
; TARGET<br />
; TARGET_BASE<br />
; TARGET_IMPLIB<br />
; TARGET_INSTALLNAME_DIR<br />
; TARGET_PDB<br />
; TARGET_QUOTED<br />
; TARGET_SONAME<br />
; TARGET_VERSION_MAJOR<br />
; TARGET_VERSION_MINOR<br />
<br />
Please note you can set these properties globally using SET or LIST, or for a single target using SET_TARGET_PROPERTIES.<br />
<br />
== Variables not listed here ==<br />
CMake has many more variables than are listed above. Documenting all of them is an ongoing project. We need everyone's help with this. If you know of a CMake variable that is not listed here, please edit the wiki and add it. Don't worry about whether you have a precise description for it. This is a wiki, and other people can provide a better description as time goes on.<br />
<br />
How does one find out about additional variables? The CMake mailing list is probably the best resource. Some things can be learned from inspecting the CMake source code. Many - but not all of them - are also listed by this [[CMake_Useful_Variables/Get_Variables_From_CMake_Dashboards|Dashboard script for extracting variables]]. The output of this script is rather raw, but it is a good starting point for finding more variables.<br />
<br />
When a CMake dashboard is run, a "SystemInformation test" is usually run as well. Among other things, it lists the names and values of all of the CMake variables that are in use when the test is run. The script looks at the SystemInformation test output, and uses regular expressions to find the start and end of the "AllVariables.txt" section. It prints the results out in the form of XML.<br />
<br />
== Logging code ==<br />
This code may be placed in a CMakelists.txt file to create status messages<br />
that log a number of the variables documented above. It is not a complete list, however. The variables are not auto-generated from the wiki, it is just sample code. Add whatever variables you are interested in.<br />
#[[CMake_Useful_Variables/Logging_Useful_Variables | Sample code for logging useful variables.]]<br />
<br />
<br />
{{CMake/Template/Footer}}</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake_FAQ&diff=16695CMake FAQ2009-10-07T05:13:09Z<p>Plowman: /* How can I build my MSVC application with a static runtime? */</p>
<hr />
<div>== General information and availability ==<br />
=== What is CMake? ===<br />
CMake is a cross-platform, open-source make system. CMake is used to control the software compilation process using simple platform-independent 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 http://www.cmake.org/HTML/About.html to learn more about CMake.<br />
<br />
=== What is the current release? ===<br />
The latest release of CMake is always available at: http://www.cmake.org/HTML/Download.html<br />
<br />
From there, you can fetch CMake binaries for Windows or several Unix variants, or you can download the source code of CMake.<br />
<br />
You can also access nightly development through CVS; see http://www.cmake.org/HTML/Download.html for more information. You may also browse the [http://www.cmake.org/cgi-bin/viewcvs.cgi/?root=CMake cvs repository online].<br />
<br />
=== I found a Bug! What should I do? ===<br />
Please report the bug in our bug tracker: http://www.cmake.org/Bug<br />
<br />
Please make sure to look at the old bugs not to include duplicates, include detailed instructions of the bug and how to reproduce it.<br />
<br />
=== I want a new feature in CMake. What should I do? ===<br />
Report a feature request in our Bug tracker http://www.cmake.org/Bug<br />
<br />
Please make sure to look at the old feature requests not to include duplicates, include detailed instructions of the feature and proposed implementation.<br />
<br />
=== What is the most recent version covered by the Mastering CMake book? ===<br />
A new edition of the [http://www.kitware.com/products/cmakebook.html Mastering CMake] book has been released which documents CMake 2.6.<br />
<br />
The following features have been added since printing the book:<br />
<br />
* New INSTALL command (cmake --help-command INSTALL)<br />
* New LIST command (cmake --help-command LIST)<br />
* Updated FIND_PATH, FIND_PROGRAM, and FIND_FILE commands to be more powerful (cmake --help-command FIND_PATH)<br />
* RPATH and Mac OS X install_name support (cmake --help-command SET_TARGET_PROPERTIES)<br />
* CPack Beta (not finished or documented)<br />
* EXECUTE_PROCESS was added and replaces EXEC_PROGRAM<br />
* Other changes have been bug fixes and internal CMake restructuring<br />
<br />
=== Where can I find searchable CMake Mailing Archives? ===<br />
There exists at list those ones:<br />
* [http://dir.gmane.org/gmane.comp.programming.tools.cmake.user cmake on Gmane]<br />
* [http://www.mail-archive.com/cmake@cmake.org/ http://www.mail-archive.com/cmake@cmake.org/]<br />
* [http://marc.info/?l=cmake http://marc.info/?l=cmake]<br />
* Use google ''site'' keyword in order to search directly in the CMake browsable ML:<br />
site:http://www.cmake.org/pipermail/cmake/ <search terms><br />
<br />
== Running CMake ==<br />
<br />
=== Is there an option to produce more 'verbose' compiling? ===<br />
<br />
On Makefile generators, you can set the Makefile variable VERBOSE to 1. For example on UNIX:<br />
make VERBOSE=1<br />
<br />
You can also set CMAKE_VERBOSE_MAKEFILE to ON.<br />
<br />
On Windows (nmake) you can override CMAKE_VERBOSE_MAKEFILE by using<br />
nmake /S<br />
On Unix make you can mostly override verbose mode by using<br />
make VERBOSE=""<br />
<br />
If you are on Windows using Borland or NMake Makefiles, you will see lines like:<br />
<br />
cl @c:\DOCUME~1\ANDY~1.KIT\LOCALS~1\Temp\nma03504<br />
<br />
The reason for this is that Borland and Microsoft Visual Studio make programs have limitation on the length of command strings. They overcome this limitation by writing arguments to the file and then pass file to the program.<br />
<br />
If you actually want to see what the command looks like, set CMAKE_START_TEMP_FILE and CMAKE_END_TEMP_FILE to ""<br />
<br />
=== Is there a way to skip checking of dependent libraries when compiling? ===<br />
<br />
'''Using the Makefile Generator'''<br />
<br />
When using the Makefile generator under *nix you can append "/fast" to your target name. For example:<br />
<br />
make target_name/fast<br />
<br />
Under Windows use a backslash instead:<br />
<br />
make target_name\fast<br />
<br />
'''Using Visual Studio >= 7.1'''<br />
<br />
If you have Visual Studio .NET 7.1 or greater you can use the native option to right click on a project and choose to build just that project.<br />
<br />
'''Using Visual Studio <= 7.0'''<br />
<br />
CMake doesn't try to compile all dependent libraries when you compile a library but it will do so for binary targets. You can't avoid this however you can take advantage of CTRL+F7 to manually compile a source file for the affected target and then relink the target by right clicking on it and choosing Link. You'll have to ensure that all dependent libraries are made up-to-date however or suffer through Visual's slow check.<br />
<br />
=== I set a cmake variable in my environment, but it didn't change anything. Why? ===<br />
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.<br />
<br />
=== How do I use a different compiler? ===<br />
<br />
==== Method 1: use set() ====<br />
<br />
Set the appropriate <tt>CMAKE_FOO_COMPILER</tt> variable(s) to a valid<br />
compiler name or full path in a list file using <tt>set()</tt>. This<br />
must be done ''before'' any language is set (ie before any<br />
<tt>project()</tt> or <tt>enable_language()</tt> command).<br />
<br />
For example:<br />
<pre><br />
set(CMAKE_C_COMPILER "gcc-4.2")<br />
set(CMAKE_CXX_COMPILER "/usr/bin/g++-4.2")<br />
<br />
project("YourProjectName")<br />
</pre><br />
<br />
==== Method 2: use cmake -D ====<br />
<br />
Set the appropriate <tt>CMAKE_FOO_COMPILER</tt> variable(s) to a valid<br />
compiler name or full path on the command-line using <tt>cmake -D</tt>.<br />
<br />
For example:<br />
<pre><br />
cmake -G "Your Generator" -D CMAKE_C_COMPILER=gcc-4.2 -D CMAKE_CXX_COMPILER=g++-4.2 path/to/your/source<br />
</pre><br />
<br />
==== Method 3 (deprecated): use environment variables ====<br />
<br />
For C and C++, set the <tt>CC</tt> and <tt>CXX</tt> environment<br />
variables. This method is not guaranteed to work for all generators.<br />
(Specifically, if you are trying to set Xcode's <tt>GCC_VERSION</tt>,<br />
this method confuses Xcode.)<br />
<br />
For example:<br />
<pre><br />
CC=gcc-4.2 CXX=/usr/bin/g++-4.2 cmake -G "Your Generator" path/to/your/source<br />
</pre><br />
<br />
=== I change CMAKE_C_COMPILER in the GUI but it changes back on the next configure step. Why? ===<br />
<br />
Once a build tree is created with a given compiler it cannot be changed. There are a variety of implementation reasons for this policy.<br />
<br />
=== In CCMake, typing full paths is tedious. Is there a better way? ===<br />
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.<br />
<br />
For example:<br />
<br />
/usr/loc<TAB><br />
<br />
will expand to<br />
<br />
/usr/local/<br />
<br />
<br />
<br />
== Out-of-source build trees ==<br />
<br />
=== What is an "out-of-source" build? ===<br />
When your build generates files, they have to go somewhere. An in-source build puts them in your source tree. An out-of-source build puts them in a completely separate directory, so that your source tree is unchanged.<br />
<br />
In the first example, an in-place build is performed, i.e., the binaries are placed in the same directory as the source code.<br />
<br />
cd Hello<br />
ccmake .<br />
make<br />
<br />
In the second example, an out-of-place build is performed, i.e., the source code, libraries, and executables are produced in a directory separate from the source code directory(ies).<br />
<br />
mkdir HelloBuild<br />
cd HelloBuild<br />
ccmake ../Hello<br />
make<br />
<br />
Out-of-source builds are recommended, as you can build multiple variants in separate directories, e.g., HelloBuildDebug, HelloBuildRelease.<br />
<br />
Note: Before performing an out-of-source build ensure that any possible CMake generated in-source build information is removed from the source directory, e.g., CMakeFiles directory, and CMakeCache.txt.<br />
<br />
=== I run an out-of-source build but CMake generates in-source anyway. Why? ===<br />
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.<br />
<br />
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).<br />
<br />
=== Why does CMake use full paths, or can I copy my build tree? ===<br />
CMake uses full paths because:<br />
<br />
# configured header files may have full paths in them, and moving those files without re-configuring would cause upredictable behavior.<br />
# because cmake supports out of source builds, if custom commands used relative paths to the source tree, they would not work when they are run in the build tree because the current directory would be incorrect.<br />
# on Unix systems rpaths might be 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.<br />
<br />
Can the build tree be copied or moved?<br />
<br />
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 and rerun. Often when people want to move a binary tree it is so that they can distribute it to other users who may not have cmake in which case this would not work even if cmake would detect the move.<br />
<br />
The workaround is to create a new build tree without copying or moving the old one.<br />
<br />
<br />
=== CMake does not generate a "make distclean" target. Why? ===<br />
Some build trees created with GNU autotools have a "make distclean" target that cleans the build and also removes Makefiles and other parts of the generated build system. CMake does not generate a "make distclean" target because CMakeLists.txt files can run scripts and arbitrary commands; CMake has no way of tracking 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. (CMake does generate a "make clean" target to remove files generated by the compiler and linker.)<br />
<br />
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. Because CMake does not change the source tree, there is no need for a distclean target. One can start a fresh build by deleting the build tree or creating a separate build tree.<br />
<br />
(If a CMakeLists.txt uses ADD_CUSTOM_COMMAND to generate source files in the source tree, not the build tree, then in CMake 2.2 or higher "make clean" will remove them. See next question.)<br />
<br />
=== Running "make clean" does not remove custom command outputs. Why? ===<br />
In CMake 2.2 and higher custom command outputs should be removed by make clean. Make sure you are using at least this version. Prior to CMake 2.2 custom command outputs were not automatically added to the list of files to clean. In CMake 2.0 the 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.<br />
<br />
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 to clean away files that differ between builds.<br />
<br />
<br />
== Writing CMakeLists.txt ==<br />
<br />
=== How to have backward and forward compatibility? ===<br />
<br />
As of CMake 2.6 we employ a "Policy" mechanism to provide backwards compatibility.<br />
The basic requirement for projects is to include one line at the top of the highest CMakeLists.txt file:<br />
<br />
cmake_minimum_required(VERSION 2.6) # or other version<br />
<br />
This tells versions of CMake older than that specified that they are too old to build the project.<br />
They will report this information to the user.<br />
It also tells versions of CMake newer than that specified that the project may not be aware of policies introduced in later versions, which enables additional compatibility.<br />
For futher documentation, see<br />
<br />
* [[CMake_Policies|CMake Policy Mechanism]]<br />
* [http://www.cmake.org/cmake/help/cmake2.6docs.html#command:cmake_policy cmake_policy() command]<br />
* [http://www.cmake.org/cmake/help/cmake2.6docs.html#section_Policies CMake 2.6 Policies]<br />
<br />
=== How do I get the current source or binary directory? ===<br />
The variable CMAKE_CURRENT_SOURCE_DIR contains the absolute path to your current source directory, while CMAKE_CURRENT_BINARY_DIR points to the equivalent binary directory.<br />
<br />
=== Why are my CMake variables not updated in the GUI after a SET command? ===<br />
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.<br />
<br />
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:<br />
<br />
SET(BUILD_SHARED_LIBS ON)<br />
<br />
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.<br />
<br />
You can use the CACHE and FORCE options on the SET command to change variables in a way that will be reflected in the GUI. Run<br />
<br />
cmake --help-command SET<br />
<br />
to see full instructions for the command.<br />
<br />
<br />
=== How can I change the default build mode and see it reflected in the GUI? ===<br />
Adapt the following commands in your CMakeLists.txt (this example sets the Release<br />
With Debug Information mode):<br />
<pre><br />
IF(NOT CMAKE_BUILD_TYPE)<br />
SET(CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING<br />
"Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel."<br />
FORCE)<br />
ENDIF(NOT CMAKE_BUILD_TYPE)<br />
</pre><br />
<br />
=== How do I generate an executable, then use the executable to generate a file? ===<br />
<br />
Create the generator executable by just adding a target:<br />
<br />
ADD_EXECUTABLE(generate generate.c)<br />
<br />
The rest of the process is simpler in CMake 2.6 and above than in previous versions.<br />
<br />
Use <code>ADD_CUSTOM_COMMAND</code> to specify a custom build rule for the file.<br />
(In this example we assume <code>generate</code> accepts the input and output files as arguments.)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT someoutput.txt<br />
COMMAND generate ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
DEPENDS generate ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt<br />
)<br />
<br />
This tells CMake how to build the file but does not actually add a rule to the build system.<br />
Another target must require it.<br />
One may create a custom target explicitly for this rule:<br />
<br />
ADD_CUSTOM_TARGET(driver ALL DEPENDS someoutput.txt)<br />
<br />
or the file may be added as part of some other target:<br />
<br />
ADD_EXECUTABLE(product product.c someoutput.txt)<br />
<br />
<font color=#555555><br />
In CMake 2.4 and below the <code>generate</code> target may not be specified directly in the <code>COMMAND</code> option of <code>add_custom_command</code><br />
(but it can still be used in the <code>DEPENDS</code> option as of CMake 2.4).<br />
Instead use GET_TARGET_PROPERTY to obtain the location of the generated executable.<br />
Additionally, the output must always be specified by full path.<br />
<br />
GET_TARGET_PROPERTY(GENERATE_EXE generate LOCATION)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
COMMAND ${GENERATE_EXE} ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
DEPENDS generate<br />
)<br />
</font><br />
<br />
=== How can I generate a source file during the build? ===<br />
The ADD_CUSTOM_COMMAND command lets you generate a source file that you can then include in another target. For example:<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
COMMAND ${CMAKE_COMMAND} copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.c ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.c<br />
)<br />
ADD_EXECUTABLE(foo foo.c)<br />
<br />
This will create an executable by copying bar.c to foo.c and then compiling foo.c to produce foo. CMake allows you to put generate source files in the current source or binary directory, so we were careful to output foo.c to the current binary directory. When we add foo.c to foo, CMake will look in either directory for it. Even if foo.c does not yet exist, CMake is smart enough to notice that a custom command creates it. (For the file named as the OUTPUT, CMake has its GENERATED source file property set to true.)<br />
<br />
You can also use ADD_CUSTOM_COMMAND when the<br />
[[CMake_FAQ#How_do_I_generate_an_executable.2C_then_use_the_executable_to_generate_a_file.3F|generator command is another executable in the same project]].<br />
<br />
Sometimes, the program doing the generation may generate multiple output files that each need to be part of the build. CMake 2.4 or higher supports having multiple files listed in the OUTPUT section. 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:<br />
<br />
PROJECT(FOO)<br />
# make sure cmake addes the binary directory for the project to the include path<br />
INCLUDE_DIRECTORIES(${FOO_BINARY_DIR})<br />
# add the executable that will do the generation<br />
ADD_EXECUTABLE(my_generator my_generator.cxx)<br />
GET_TARGET_PROPERTY(MY_GENERATOR_EXE my_generator LOCATION)<br />
# add the custom command that will generate all three files<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${FOO_BINARY_DIR}/output1.cpp ${FOO_BINARY_DIR}/output2.h ${FOO_BINARY_DIR}/output3.cpp<br />
COMMAND ${MY_GENERATOR_EXE} ${FOO_BINARY_DIR} ${FOO_SOURCE_DIR}/input.txt<br />
DEPENDS my_generator<br />
MAIN_DEPENDENCY ${FOO_SOURCE_DIR}/input.txt<br />
)<br />
# now create an executable using the generated files<br />
ADD_EXECUTABLE(generated<br />
${FOO_BINARY_DIR}/output1.cpp<br />
${FOO_BINARY_DIR}/output2.h<br />
${FOO_BINARY_DIR}/output3.cpp)<br />
<br />
CMake 2.4 allows you to generate a header file. Because generated headers often cause unnecessary rebuilds, you should try to avoid them; consider using the CONFIGURE_FILE command to prepare the header at CMake time. If you must generate a header file, use code like this:<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.h<br />
COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.h ${CMAKE_CURRENT_BINARY_DIR}/foo.h<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.h<br />
)<br />
ADD_EXECUTABLE(foo foo.c ${CMAKE_CURRENT_BINARY_DIR}/foo.h)<br />
<br />
This is like the first example above, except that it generates a header instead of a C file. The header might not exist when the build system scans foo.c's dependencies, so there is no way for CMake to know that this target requires foo.h unless we can tell it that foo.h may exist in the future. We give CMake this knowledge by listing the generated header file in the set of source files for the target. (This requires CMake 2.4. Previous versions of CMake required use of the OBJECT_DEPENDS source file property.)<br />
<br />
=== How can I add a dependency to a source file which is generated in a subdirectory? ===<br />
<br />
Rules created with <code>ADD_CUSTOM_COMMAND</code> as [[CMake_FAQ#How_can_I_generate_a_source_file_during_the_build.3F|above]] have scope only in the directory in which they are specified.<br />
If the generated file is needed in another directory, a target-level dependency needs to be added.<br />
Create a target in the subdirectory with the custom rule in order to drive it:<br />
<br />
# subdir/CMakeLists.txt<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
COMMAND ${CMAKE_COMMAND} copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.c ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.c<br />
)<br />
ADD_CUSTOM_TARGET(generate_foo DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/foo.c)<br />
<br />
Now other targets can depend on the target from the subdirectory:<br />
<br />
# CMakeLists.txt<br />
ADD_SUBDIRECTORY(subdir)<br />
# Create the executable.<br />
ADD_EXECUTABLE(generated ${CMAKE_CURRENT_BINARY_DIR}/subdir/foo.c)<br />
# Tell CMake the source won't be available until build time.<br />
SET_SOURCE_FILES_PROPERTIES(${CMAKE_CURRENT_BINARY_DIR}/subdir/foo.c PROPERTIES GENERATED 1)<br />
# Make sure the source is generated before the executable builds.<br />
ADD_DEPENDENCIES(generated generate_foo)<br />
<br />
=== I use EXEC_PROGRAM but the result is not set in subdirectories. Why? ===<br />
<br />
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 was fixed in CMake 2.2, but for older versions you will have to cache the result:<br />
<br />
<pre><br />
EXEC_PROGRAM(my-program OUTPUT_VARIABLE MY_OUTPUT)<br />
SET(MY_OUTPUT "${MY_OUTPUT}" CACHE INTERNAL "")<br />
</pre><br />
<br />
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.<br />
<br />
=== How can I get or set environment variables? ===<br />
<br />
CMake names environment variables using an ENV prefix and surrounding the names in curly braces. Here is an example:<br />
<br />
<pre><br />
MESSAGE("$ENV{PATH}")<br />
</pre><br />
<br />
Reading variables will work in any version of CMake. Writing to them works in CMake 2.2 and higher using the following syntax:<br />
<br />
<pre><br />
SET(ENV{HELLO} "World")<br />
</pre><br />
<br />
Note that there is currently no way to tell apart an empty environment variable value from a variable that is not set at all.<br />
<br />
One should avoid using environment variables for controlling the flow of CMake code (such as in IF commands). The build system generated by CMake may re-run CMake automatically when CMakeLists.txt files change. The environment in which this is executed is controlled by the build system and may not match that in which CMake was originally run. If you want to control build settings on the CMake command line, you need to use cache variables set with the -D option. The settings will be saved in CMakeCache.txt so that they don't have to be repeated every time CMake is run on the same build tree.<br />
<br />
Also, environment variables SET in the CMakeLists.txt ''only'' take effect for cmake itself, so you cannot use this method to set an environment variable that a custom command might need.<br />
<br />
=== Why do I have unwanted semicolons ; in my compiler flags? ===<br />
CMake has a list data type. A list is stored as a string of semicolon-separated list elements. Whitespace separated arguments to a SET statement are interpreted as list elements. For instance, SET(var a b c d e) will give "var" a value of a;b;c;d;e and this list can be used by other CMake commands. However, if you pass ${var} to a non-CMake external tool, such as a compiler's command line, you are passing a;b;c;d;e which is not what you want. Instead you either need to pass "${var}", so that the list will be converted to a whitespace-separated string, or you need to SET(var "a b c d e") in the 1st place so that you're working with a string, not a list.<br />
<br />
=== How can I get quoting and escapes to work properly? ===<br />
If you want to escape a character in CMake, you use "\", like in C code. For example, if you wanted to have a quote embedded in a string you would do this: "\"". However, each level of CMake that processes your code will need one level of escaping to work. So, if you configure a file that is read by cmake or cpack and you want to do the same thing, you would do "\\\"". You would still need to escape the " for the first cmake that processes the string. However, this time, you would want to also escape a '\' as well. This would leave the next level of processing with "\"". Also, for custom commands that may get passed to a shell, it maybe required to do escaping for that shell.<br />
<br />
=== Isn't the "Expression" in the "ELSE (Expression)" confusing? ===<br />
Traditional CMakeLists.txt files prior to 2.6.0, require the following syntax. In the IF syntax, the ELSE section requires the same (Expression) as the IF section. This sometimes can make the script kind of hard to follow, take the short example below:<br />
<br />
IF(WIN32)<br />
...do something...<br />
ELSE(WIN32)<br />
...do something else...<br />
ENDIF(WIN32)<br />
<br />
You might think that the ELSE section, here containing "...do something else...", is for the WIN32 portion of the script. That is not so! It is actually handling the NOT WIN32 section.<br />
<br />
As of CMake 2.6.0 the ELSE() and ENDIF() constructs can be empty. The same is true for closing constructs on ENDMACRO(), ENDFUNCTION(), and ENDFOREACH(). If you require 2.4.x compatibility, CMake 2.4.3 or greater recognizes the CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS option (which is superfluous in 2.6.0)<br />
<br />
cmake_minimum_required(VERSION 2.4.3)<br />
set(CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS true)<br />
<br />
if(WIN32)<br />
...do something...<br />
elseif(APPLE)<br />
...do something else...<br />
else()<br />
...do something else...<br />
endif()<br />
<br />
=== Which regular expressions are supported by CMake? ===<br />
When using MATCHES or MATCHALL in an IF command, or using any of the STRING(REGEX ...) commands, CMake expects regular expressions, not globs (wild cards). CMake uses the same regular expression engine above all platforms. Here are the meanings of the metacharacters:<br />
<br />
^ Matches at beginning of a line<br />
$ Matches at end of a line<br />
. Matches any single character<br />
[ ] Matches any character(s) inside the brackets<br />
[^ ] Matches any character(s) not inside the brackets<br />
- Matches any character in range on either side of a dash<br />
| Matches a pattern on either side of the |<br />
* Matches preceding pattern zero or more times<br />
+ Matches preceding pattern one or more times<br />
? Matches preceding pattern zero or once only<br />
() Saves a matched expression and uses it in a later match<br />
<br />
Example: "[-][L]([^ ;])+" matches all strings beginning with -L and ending with a space or a semicolon, the usual linkdirs under Linux.<br />
<br />
Here is how to catch a part of a string. The variable test is filled with some content, and then we want to catch the "me":<br />
<br />
SET(test "hello world ! catch: me if you can")<br />
STRING(REGEX REPLACE ".*catch: ([^ ]+).*" "\\1" result "${test}" )<br />
MESSAGE(STATUS "result= ${result}")<br />
<br />
This is slightly tricky. The part inside the brackets is available in \\1 . CMake will copy the variable test to the variable result, but then it will replace everything that the regular expression matches with \\1. This means the first regular expression has to match the whole string and the part we want to catch has to be put in parens.<br />
<br />
-- result= me<br />
<br />
For those of you who know Perl, the equivalent Perl code could be:<br />
<br />
$test = "hello world ! catch: me if you can";<br />
$result = $test;<br />
$result =~ s/.*catch: ([^ ]+).*/$1/;<br />
print "-- result= $result\n";<br />
<br />
There are other ways to do this in Perl, but this is how we do it in CMake because \\1 does not become a variable like $1 does in perl, so there is no SET(result ${\\1}) in CMake.<br />
<br />
<br />
=== How to convert a semicolon separated list to a whitespace separated string? ===<br />
<br />
set(foo<br />
abc.c<br />
abc.b<br />
abc.a<br />
)<br />
<br />
foreach(arg ${foo})<br />
set(bar "${bar} ${arg}")<br />
endforeach(arg ${foo})<br />
<br />
message("foo: ${foo}")<br />
message("bar: ${bar}")<br />
<br />
=== How can I build multiple modes without switching ? ===<br />
To build multiple modes (e.g. Debug and Release) in one shot without constantly running cmake -DCMAKE_BUILD_TYPE=Debug and cmake -DCMAKE_BUILD_TYPE=Release in source tree create a directory for builds eg.:<br />
<br />
<pre><br />
Project-directory/<br />
/Build<br />
</pre><br />
<br />
Inside you can place as many target directories for out-of-source build modes as you want, e.g.:<br />
<br />
<pre><br />
Project-directory/<br />
/Build<br />
/Debug<br />
/Release<br />
</pre><br />
<br />
In each of these directories issue a command (assuming that you have CMakeLists.txt directly in Project-directory)<br />
<br />
<pre><br />
cmake -DCMAKE_BUILD_TYPE=type_of_build ../../<br />
</pre><br />
<br />
to create a cmake cache configured for requested build type.<br />
<br />
Now you can make each build just by entering appropriate directory and executing a make command.<br />
<br />
=== How can I extend the build modes with a custom made one ? ===<br />
The following code snipet (taken from a CMakeLists.txt) adds a Maintainer mode:<br />
<pre><br />
SET( CMAKE_CXX_FLAGS_MAINTAINER "-Wall -Wabi" CACHE STRING<br />
"Flags used by the C++ compiler during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_C_FLAGS_MAINTAINER "-Wall -pedantic" CACHE STRING<br />
"Flags used by the C compiler during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_EXE_LINKER_FLAGS_MAINTAINER<br />
"-Wl,--warn-unresolved-symbols,--warn-once" CACHE STRING<br />
"Flags used for linking binaries during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_SHARED_LINKER_FLAGS_MAINTAINER<br />
"-Wl,--warn-unresolved-symbols,--warn-once" CACHE STRING<br />
"Flags used by the shared libraries linker during maintainer builds."<br />
FORCE )<br />
MARK_AS_ADVANCED(<br />
CMAKE_CXX_FLAGS_MAINTAINER<br />
CMAKE_C_FLAGS_MAINTAINER<br />
CMAKE_EXE_LINKER_FLAGS_MAINTAINER<br />
CMAKE_SHARED_LINKER_FLAGS_MAINTAINER )<br />
# Update the documentation string of CMAKE_BUILD_TYPE for GUIs<br />
SET( CMAKE_BUILD_TYPE "" CACHE STRING<br />
"Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel Maintainer."<br />
FORCE )<br />
</pre><br />
Notes: The flags used in this example are specific to GCC. Change them as needed for your project. Additionally the SET(CMAKE_BUILD_TYPE) command will override<br />
a CMAKE_BUILD_TYPE previously set in the CMakeLists.txt.<br />
<br />
=== Why does <code>foreach</code> skip empty values? ===<br />
<br />
The code in question is of the form<br />
<br />
set(var "a;b;;c;d") # list 'a', 'b', '', 'c', 'd'<br />
foreach(v ${var})<br />
# v=a, v=b, v=c, v=d, one at a time<br />
endforeach()<br />
<br />
and the loop variable 'v' never attains the empty-string value ''.<br />
This is because the <code>${var}</code> syntax is an unquoted argument so the CMake language expands the list and removes the empty value.<br />
The foreach command does not even see the empty value.<br />
One can verify this because the code<br />
<br />
foreach(v a b "" c d)<br />
...<br />
endforeach()<br />
<br />
will see the empty value.<br />
<br />
=== Does CMake support precompiled headers? ===<br />
<br />
Yes and no. Every platform does precompiled headers a bit differently, and there is currently no first-class interface provided by CMake and implemented on every platform.<br />
However, CMake does provide enough primitives for projects to use precompiled headers on specific platforms.<br />
Our issue tracker has a [http://www.cmake.org/Bug/view.php?id=1260 feature request] with attachements providing user-contributed helper macros for some platforms.<br />
<br />
== Writing FindXXX.cmake files ==<br />
<br />
=== What are the rules to write a FindXXX.cmake file? ===<br />
<br />
Let's follow the instructions and the advices in the <br />
Modules/readme.txt [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/readme.txt?root=CMake&view=markup]<br />
file located in the CVS repository.<br />
<br />
=== Why does find_library look in system directories before its PATHS option? ===<br />
<br />
The code in question is often of the form<br />
<br />
find_library(FOO_LIBRARY NAMES foo PATHS /opt/foo/lib)<br />
<br />
CMake will find "<code>/usr/lib/libfoo.so</code>" instead of "<code>/opt/foo/lib/libfoo.so</code>" if both exist.<br />
The reason is that /opt/foo/lib is a <i>hard-coded guess</i> of the location.<br />
The documentation of <code>[http://www.cmake.org/cmake/help/cmake2.6docs.html#command:find_library find_library]</code> specifies the search order.<br />
User, project, and system configuration variables are always more local than hard-coded guesses and should override them, so<br />
the PATHS option is used last.<br />
<br />
Some find-modules compute probable locations based on other information <i>available from the system</i> such as a project-specific environment variable.<br />
The HINTS option (CMake 2.6 and higher) takes precedence over system directories specifically for this case:<br />
<br />
file(TO_CMAKE_PATH "$ENV{FOO_LIB_DIR}" FOO_LIB_DIR)<br />
find_library(FOO_LIBRARY NAMES foo HINTS ${FOO_LIB_DIR})<br />
<br />
CMake will find "<code>$ENV{FOO_LIB_DIR}/libfoo.so</code>" before "<code>/usr/lib/libfoo.so</code>".<br />
<br />
== Finding and using external packages ==<br />
<br />
=== How do I use CMake to generate SWIG wrapper libraries? ===<br />
<br />
CMake version 2 includes a module that supports the generation of SWIG wrapper libraries. The SWIG package defines the following macros: SWIG_ADD_MODULE and SWIG_LINK_LIBRARIES.<br />
<br />
<pre><br />
# This example shows how to use python<br />
# Currently these languages have been tested:<br />
# perl tcl ruby php4 pike<br />
<br />
FIND_PACKAGE(SWIG REQUIRED)<br />
INCLUDE(${SWIG_USE_FILE})<br />
<br />
FIND_PACKAGE(PythonLibs)<br />
INCLUDE_DIRECTORIES(${PYTHON_INCLUDE_PATH})<br />
<br />
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})<br />
<br />
SET(CMAKE_SWIG_FLAGS "")<br />
<br />
SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES CPLUSPLUS ON)<br />
SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES SWIG_FLAGS "-includeall")<br />
SWIG_ADD_MODULE(example python<br />
example.i example.cxx)<br />
SWIG_LINK_LIBRARIES(example ${PYTHON_LIBRARIES})<br />
<br />
</pre><br />
<br />
<pre><br />
# This example shows how to use tcl<br />
PROJECT(TCL_WRAP)<br />
SET ( MODULE_NAME project )<br />
SET ( INTERFACE_FILES project.i)<br />
SET ( SRC_FILES Vertex.h Vertex.cxx Shapes.h Shapes.cxx )<br />
<br />
FIND_PACKAGE(SWIG REQUIRED)<br />
INCLUDE(${SWIG_USE_FILE})<br />
<br />
# Look for TCL<br />
INCLUDE_DIRECTORIES(${TCL_INCLUDE_PATH})<br />
<br />
FIND_LIBRARY(TCL_LIBRARY NAMES tcl tcl84 tcl83 tcl82 tcl80<br />
PATHS /usr/lib /usr/local/lib)<br />
IF (TCL_LIBRARY)<br />
TARGET_ADD_LIBRARY (${MODULE_NAME} TCL_LIBRARY)<br />
ENDIF (TCL_LIBRARY)<br />
<br />
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})<br />
<br />
SET(CMAKE_SWIG_FLAGS "-c++")<br />
<br />
SET_SOURCE_FILES_PROPERTIES(${INTERFACE_FILES} PROPERTIES CPLUSPLUS ON)<br />
SET_SOURCE_FILES_PROPERTIES(${INTERFACE_FILES} PROPERTIES CMAKE_SWIG_FLAGS "-includeall")<br />
SWIG_ADD_MODULE(${MODULE_NAME} tcl ${INTERFACE_FILES} ${SRC_FILES})<br />
SWIG_LINK_LIBRARIES(${MODULE_NAME} ${TCL_LIBRARIES})<br />
</pre><br />
<br />
=== How do I use CMake to build LaTeX documents? ===<br />
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.<br />
<br />
PROJECT(Document)<br />
IF(LATEX_COMPILE)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${Document_BINARY_DIR}/TDocument.dvi<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.tex<br />
COMMAND ${LATEX_COMPILE} <br />
ARGS ${Document_SOURCE_DIR}/TDocument.tex <br />
)<br />
ENDIF(LATEX_COMPILE)<br />
<br />
IF(DVIPDF_COMPILE)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${Document_BINARY_DIR}/TDocument.pdf<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.dvi <br />
COMMAND ${DVIPDF_COMPILE}<br />
ARGS ${Document_SOURCE_DIR}/TDocument.dvi<br />
)<br />
ENDIF(DVIPDF_COMPILE)<br />
<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.pdf<br />
)<br />
<br />
The following uses commands in CMake version 2.0 and later<br />
<br />
PROJECT(Document)<br />
# <br />
# Find LaTeX<br />
#<br />
FIND_PACKAGE(LATEX)<br />
<br />
IF(LATEX_COMPILER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.dvi<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS ${Document_SOURCE_DIR}/TDocument.tex<br />
DEPENDS ${Document_SOURCE_DIR}/TDocument.tex<br />
COMMENT "Tex2dvi"<br />
)<br />
<br />
IF(DVIPS_CONVERTER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.ps<br />
COMMAND ${DVIPS_CONVERTER}<br />
ARGS ${Document_BINARY_DIR}/TDocument.dvi<br />
-o ${Document_BINARY_DIR}/TDocument.ps<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.dvi<br />
COMMENT "dvi2ps"<br />
)<br />
<br />
IF(PS2PDF_CONVERTER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.pdf<br />
COMMAND ${PS2PDF_CONVERTER}<br />
ARGS ${Document_BINARY_DIR}/TDocument.ps<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.ps<br />
COMMENT "ps2pdf"<br />
)<br />
<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.pdf<br />
)<br />
ENDIF(PS2PDF_CONVERTER)<br />
ENDIF(DVIPS_CONVERTER)<br />
ENDIF(LATEX_COMPILER)<br />
<br />
=== How do I get LaTeX references to be correct? ===<br />
When your latex document contains references (e.g. \ref{...} command) you get to run two passes of latex. In the<br />
most general case, i.e. when additionally your document uses a bibtex bibliography, you shall need three<br />
passes of latex (and one pass of bibtex):<br />
# latex (first pass: for bibtex to have an .aux file)<br />
# bibtex (for generating the .bbl file)<br />
# latex (second pass)<br />
# latex (third pass)<br />
<br />
The following code snippet illustrates how you can "pervert" the bibtex and latex generated<br />
auxilary files (.aux, .log, .dvi, .bbl...) to create an "artificial" set of CMake dependencies.<br />
The side-effect of those dependencies should hopefully be the above described sequence of calls<br />
to latex and bibtex<br />
<pre><br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.aux<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/UsersManual.tex<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (first pass)"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.aux<br />
COMMAND ${BIBTEX_COMPILER}<br />
ARGS -terse ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Bibtex"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.dvi<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (second pass)"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.log<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
${CMAKE_CURRENT_BINARY_DIR}/UsersManual.dvi<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (third pass)"<br />
)<br />
# Eventually trigger the whole process<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.log<br />
)<br />
</pre><br />
<br />
=== How can I set TEXINPUTS for a LaTeX compilation? ===<br />
First note that most often you can avoid using TEXINPUTS by copying all the necessary files (.tex source file and<br />
included graphic files e.g. .eps files) from your PROJECT_SOURCE_DIR hirarchy to your PROJECT_BINARY_DIR subdir<br />
[refer to CONFIGURE_FILE with the COPYONLY flag set for copying files]. Since by default latex uses the current working directory as value for TEXINPUTS you should be all set. As expected, this trick is quick AND dirty since your<br />
concerned PROJECT_BINARY_DIR subdir now contains files that are NOT generated by CMake (in the sense that those<br />
files are not the result of a system command but were merely duplicated)... <br />
<br />
If you consider it is cleaner or easier to define a TEXINPUTS environment variable [the latex command probably<br />
misses a -I flag] you can find an example in the InsightDocuments cvs archive (refer to the section "cvs access"<br />
near the bottom of Kitware's ITK download page) or use google with keywords "ITK_TEXINPUTS CONFIGURE_FILE".<br />
Look at InsightDocuments/CourseWare/Training/Vis2003/Latex/CMakeLists.txt and search for e.g. "LaTeXWrapper.sh.in".<br />
<br />
Roughly the mechanism goes:<br />
* SET ITK_TEXINPUTS with the desired TEXINPUTS<br />
* CONFIGURE_FILE "InsightDocuments/CourseWare/Training/Vis2003/LaTeXWrapper.sh.in" which generates an sh shell script setting the shell variable TEXINPUTS prior to running the latex command<br />
* use ADD_CUSTOM_COMMAND to invoke this shell script<br />
This very example is Win32 portable (except that LaTeXWrapper.bat.in generates a .bat shell script)<br />
<br />
== Library questions ==<br />
<br />
=== Can I build both shared and static libraries with one ADD_LIBRARY command? ===<br />
<br />
No. Each library you build must have a unique target name, i.e. the "libname" field of the ADD_LIBRARY command. That way, CMake can track dependencies separately for each library. Libraries can have the same OUTPUT_NAME, see the SET_TARGET_PROPERTIES command, but this is not the default.<br />
<br />
=== Does that mean I have to build all my library objects twice, once for shared and once for static?! I don't like that! ===<br />
<br />
In practice, most libraries have different defines and compiler flags for the shared vs. static cases. So you would have to build all your library objects twice anyways. However, if you happen to have '''''exactly''''' the same defines and compiler flags for the shared vs. static cases...<br />
<br />
...if you're using Linux and a GCC-style linker, you could do the following. Note that for this to work correctly on linux, the zzSTATIC source files should have been compiled with "-fPIC" to ensure they will work in a shared library.<br />
<br />
IF(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_COMPILER_IS_GNUCC)<br />
ADD_LIBRARY(zzSTATIC STATIC -fPIC)<br />
ADD_LIBRARY(zzDYNAMIC SHARED)<br />
TARGET_LINK_LIBRARIES(zzDYNAMIC -Wl,-whole-archive zzSTATIC -Wl,-no-whole-archive)<br />
ENDIF(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_COMPILER_IS_GNUCC)<br />
<br />
...if you want a cross-platform approach that works on all compilers, not just GCC or Linux, you could extract the locations of previously built object files and insert them directly into the libraries that need them. This is documented in [http://www.cmake.org/Bug/view.php?id=5155 CMake Feature Request #5155: standard way to locate object files]. Unfortunately this approach relies on CMake's internal implementation, and that implementation could change in the future, breaking your code.<br />
<br />
=== How do I make my shared and static libraries have the same root name, but different suffixes? ===<br />
Set the OUTPUT_NAME of your shared and static libraries to the same thing.<br />
<br />
ADD_LIBRARY(foo SHARED ${foo_sources})<br />
ADD_LIBRARY(foo-static STATIC ${foo_sources})<br />
// The library target "foo" already has a default OUTPUT_NAME of "foo", so we don't need to change it.<br />
// The library target "foo-static" has a default OUTPUT_NAME of "foo-static", so change it.<br />
SET_TARGET_PROPERTIES(foo-static PROPERTIES OUTPUT_NAME "foo")<br />
<br />
If you are building your shared and static libraries in the same directory, you will also need the following to keep your shared and static libraries from clobbering each other during the build.<br />
<br />
SET_TARGET_PROPERTIES(foo PROPERTIES CLEAN_DIRECT_OUTPUT 1)<br />
SET_TARGET_PROPERTIES(foo-static PROPERTIES CLEAN_DIRECT_OUTPUT 1)<br />
<br />
=== How do I rename a library after it has already been built? ===<br />
You don't rename it. It's been built! Its name is whatever CMakeLists.txt says it's supposed to be.<br />
<br />
Perhaps you want to copy the library to a different name. But, are you sure that's what you want to do? You could just change the name in your ADD_LIBRARY command or change its OUTPUT_NAME property using SET_TARGET_PROPERTY(). If you really really want to copy the library to a different name, try:<br />
<br />
GET_TARGET_PROPERTY(LIB_NAME Foo LOCATION)<br />
GET_TARGET_PROPERTY(Bar_prefix Foo PREFIX)<br />
GET_TARGET_PROPERTY(Bar_suffix Foo SUFFIX)<br />
SET(NEW_LIB_NAME ${Bar_prefix}Bar${Bar_suffix})<br />
<br />
ADD_CUSTOM_COMMAND(<br />
TARGET Foo<br />
POST_BUILD<br />
COMMAND ${CMAKE_COMMAND} -E copy ${LIB_NAME} ${NEW_LIB_NAME}<br />
)<br />
<br />
On Windows you may also want to copy the .dll import lib, using the same approach as above, but with IMPORT_PREFIX and IMPORT_SUFFIX. ''Problem: LOCATION only refers to 1 file, the .dll. What is a simple way to get the location of the import lib? Could provide a complicated way, but that's annoying.''<br />
<br />
=== Does CMake support "convenience" libraries? ===<br />
No. CMake does not currently support convenience libraries. A "convenience" library, as GNU libtool calls it, is an archive of objects to be mixed into other libraries. Other libraries "link" to the convenience library, but the convenience library does not export any symbols; GNU libtool never installs the convenience library; no programs ever link to the convenience library.<br />
<br />
This does '''not''' mean that a project using convenience libraries cannot be converted to CMake. Instead the source files may be listed in each target that needs them. They will be built for each target separately using all the preprocessor definitions and flags configured for that target.<br />
<br />
=== Why are libraries linked to my shared library included when something links to it? ===<br />
This question arises when one has a library B which links to some library A. When a third target, say C, links to B, CMake will automatically include C to A also. When the libraries are static, then this is always necessary. When the libraries are shared, this is the default behavior provided by CMake. CMake 2.6 and above provide the target property "LINK_INTERFACE_LIBRARIES" (http://www.cmake.org/HTML/cmake-2.6.html#prop_tgt:LINK_INTERFACE_LIBRARIES) to specify the libraries that should be transitively included in the link by CMake. CMake 2.4 and below do not support the property.<br />
<br />
Something like the following will work in CMake 2.6:<br />
<br />
<pre><br />
set_target_properties(mylibrary<br />
PROPERTIES<br />
LINK_INTERFACE_LIBRARIES ""<br />
)<br />
</pre><br />
<br />
=== CMake dependency scanner ===<br />
<br />
CMake does not preprocess source files while scanning dependencies. Code like<br />
<pre><br />
#if 0<br />
# include "bla.h"<br />
#endif<br />
</pre><br />
will result in a dependency on "bla.h". This sometimes leads to source files recompiling unnecessarily but will not break the build.<br />
<br />
== Installation questions ==<br />
<br />
=== Does CMake's "make install" support DESTDIR? ===<br />
'''Yes''', especially when the build-system generator uses CMake's builtin support for installing files: Simply define the DESTDIR environment variable during installation and CMake will treat that value as the root of the file system for all installation paths; naturally, the DESTDIR path must be absolute.<br />
<br />
For example, if the Makefile generator is used, then all of the following are example usages of DESTDIR (perhaps assuming the bash shell for the last 2):<br />
<br />
(1) make install DESTDIR="/some/absolute/path"<br />
(2) make DESTDIR="/some/absolute/path" install<br />
(3) DESTDIR="/some/absolute/path" make install<br />
(4) export DESTDIR="/some/absolute/path<br />
make install<br />
<br />
=== Can I do "make uninstall" with CMake?===<br />
By default, CMake does not provide the "make uninstall" target, so you cannot do this. We do not want "make uninstall" to remove useful files from the system.<br />
<br />
If you want an "uninstall" target in your project, then nobody prevents you from providing one. You need to delete the files listed in install_manifest.txt file. Here is how to do it. First create file cmake_uninstall.cmake.in in the top-level directory of the project:<br />
<br />
<pre><br />
IF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")<br />
MESSAGE(FATAL_ERROR "Cannot find install manifest: \"@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt\"")<br />
ENDIF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")<br />
<br />
FILE(READ "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt" files)<br />
STRING(REGEX REPLACE "\n" ";" files "${files}")<br />
FOREACH(file ${files})<br />
MESSAGE(STATUS "Uninstalling \"$ENV{DESTDIR}${file}\"")<br />
IF(EXISTS "$ENV{DESTDIR}${file}")<br />
EXEC_PROGRAM(<br />
"@CMAKE_COMMAND@" ARGS "-E remove \"$ENV{DESTDIR}${file}\""<br />
OUTPUT_VARIABLE rm_out<br />
RETURN_VALUE rm_retval<br />
)<br />
IF(NOT "${rm_retval}" STREQUAL 0)<br />
MESSAGE(FATAL_ERROR "Problem when removing \"$ENV{DESTDIR}${file}\"")<br />
ENDIF(NOT "${rm_retval}" STREQUAL 0)<br />
ELSE(EXISTS "$ENV{DESTDIR}${file}")<br />
MESSAGE(STATUS "File \"$ENV{DESTDIR}${file}\" does not exist.")<br />
ENDIF(EXISTS "$ENV{DESTDIR}${file}")<br />
ENDFOREACH(file)<br />
</pre><br />
<br />
Then in the top-level CMakeLists.txt add the following logic:<br />
<br />
<pre><br />
CONFIGURE_FILE(<br />
"${CMAKE_CURRENT_SOURCE_DIR}/cmake_uninstall.cmake.in"<br />
"${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake"<br />
IMMEDIATE @ONLY)<br />
<br />
ADD_CUSTOM_TARGET(uninstall<br />
"${CMAKE_COMMAND}" -P "${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake")<br />
</pre><br />
<br />
Now you will have an "uninstall" target at the top-level directory of your build tree.<br />
<br />
Instead of creating an "uninstall" target, Unix users could enter this command in the shell:<br />
<br />
xargs rm < install_manifest.txt<br />
<br />
== Distribution questions ==<br />
<br />
=== Where is "make dist"? ===<br />
<br />
CMake doesn't create a "make dist" target.<br />
<br />
=== What is the best way to distribute source code or binaries for a cmake-based project? ===<br />
<br />
For creating source or binary packages there is now [[CMake#CPack | CPack]] coming with CMake, see the <br />
[[ CMake#CPack | documentation]].<br />
<br />
Of course you can also use any other ways to create packages.<br />
<br />
== Platform-specific questions ==<br />
=== How do I build universal binaries on Mac OS X? ===<br />
Before running CMake with an empty build tree, set the CMAKE_OSX_ARCHITECTURES environment variable. It should be set to contain a ; separated list of architectures that you want in the binary. For example, for 32-bit PowerPC and Intel you would do this:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386<br />
<br />
If you wish to build both as 32 and 64 bit, do this:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386;ppc64;x86_64<br />
<br />
You can also set the same named CMake cache variable on an existing binary tree. This works with both makefiles and the Xcode generator. <br />
<br />
In addition, you can also set the CMAKE_OSX_SYSROOT variable to point to the sysroot (aka Mac OS SDK) to be used. CMake will attempt to pick one on your system, but it can be changed in the cache or via an environment variable before running CMake. The 10.4u SDK or later must be used to create a Universal Binary.<br />
<br />
Universal Binaries are essentially cross compilation and so you should avoid using TRY_RUN, especially for things like testing endianess or variable size because the result will only be correct for one architecture.<br />
<br />
Lastly, note that CTest is only able to test one architecture. See bug 6157.<br />
<br />
=== How can I apply resources on Mac OS X automatically? ===<br />
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 a custom rule which is executed after the executable is linked:<br />
<br />
<pre><br />
ADD_EXECUTABLE(MyExecutable ${MyExecutable_SRCS})<br />
GET_TARGET_PROPERTY(MyExecutable_PATH MyExecutable LOCATION)<br />
<br />
IF(APPLE)<br />
FIND_PROGRAM(APPLE_RESOURCE Rez /Developer/Tools)<br />
IF(APPLE_RESOURCE)<br />
ADD_CUSTOM_COMMAND(TARGET MyExecutable POST_BUILD<br />
COMMAND ${APPLE_RESOURCE} Carbon.r -o ${MyExecutable_PATH})<br />
ENDIF(APPLE_RESOURCE)<br />
ENDIF(APPLE)<br />
</pre><br />
<br />
This will execute:<br />
<br />
/Developer/Tools/Rez Carbon.r -o /binary/path/MyExecutable<br />
<br />
after MyExecutable is linked.<br />
<br />
'Rez' may be located elsewhere on disk, depending on the version of Mac OS X and Xcode. You can use 'which Rez' in Terminal to find it's full path.<br />
<br />
=== Why does FIND_LIBRARY not find .DLL libraries under WIN32? ===<br />
For those who come from a Unix background to MS Windows:<br />
<br />
You never link directly to the .dll, you have to link against the import library .lib for the .dll.<br />
<br />
Linking against dynamic libraries (.dll under Windows) is quite different from linking against ELF shared objects (.so) under platforms like Linux or NetBSD. In Windows, there are two types of library, a static library and an import library (both confusingly use the .lib extension, however). In Windows, when you build an import library (A.lib) you will get a corresponding (A.dll) that you only need at runtime. At compile time you will need the import library.<br />
<br />
Conclusion: There is no need to find a .dll for linking. You only need to find the .lib import library.<br />
<br />
Some more details can be found here: [http://xenophilia.org/winvunix.html].<br />
<br />
=== Why am I getting a linker error to _mainCRTStartup under WIN32? ===<br />
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.<br />
<br />
ADD_EXECUTABLE(exename WIN32 source1 source2 ... sourceN)<br />
<br />
The second argument to ADD_EXECUTABLE can be WIN32. This indicates that the executable, when compiled on Windows, is a Windows app (using WinMain) and not a console app (using main). Please note that on Unix platforms, CMake ignores the WIN32 and the compiler will use "main" in any case.<br />
<br />
=== Why do I get this error: nafxcwd.lib(appcore.obj) : error LNK2001: unresolved external symbol ___argv ===<br />
<br />
This is because the application is using both the static and dll versions of the MFC library.<br />
To fix the problem, you can do the following:<br />
<br />
SET(CMAKE_MFC_FLAG 2) # force the IDE to use static MFC<br />
ADD_DEFINITIONS(-D_AFXDLL) # make sure if afx.h is included the dll MFC is used<br />
<br />
=== How to use MFC with CMake ===<br />
To use MFC, the CMAKE_MFC_FLAG variable must be set as follows:<br />
<br />
0: Use Standard Windows Libraries<br />
1: Use MFC in a Static Library<br />
2: Use MFC in a Shared DLL <br />
<br />
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:<br />
<br />
ADD_DEFINITIONS(-D_AFXDLL)<br />
SET(CMAKE_MFC_FLAG 2) <br />
ADD_EXECUTABLE(CMakeSetup WIN32 ${SRCS})<br />
<br />
Note that visual studio 9 project files do not appear to work with CMAKE_MFC_FLAG 1; this may be related to [http://www.cmake.org/Bug/view.php?id=7056 bug 7056].<br />
<br />
In order to use MFC with UNICODE, you must also [http://msdn.microsoft.com/en-us/library/dybsewaf.aspx specify the entry point wWinMainCRTStartup]. For example:<br />
<br />
set(CMAKE_MFC_FLAG 2)<br />
set_target_properties(MyApp PROPERTIES<br />
COMPILE_DEFINITIONS _AFXDLL,_UNICODE,UNICODE,_BIND_TO_CURRENT_CRT_VERSION,_BIND_TO_CURRENT_MFC_VERSION<br />
LINK_FLAGS "/ENTRY:\"wWinMainCRTStartup\"")<br />
<br />
See [http://stackoverflow.com/questions/59635/app-does-not-run-with-vs-2008-sp1-dlls-previous-version-works-with-rtm-versions this article] as to why _BIND_TO_CURRENT_CRT_VERSION and _BIND_TO_CURRENT_MFC_VERSION are necessary for Visual Studio 2008 SP1.<br />
<br />
=== How To Put Files in Folders in Visual Studio Projects ===<br />
The Visual Studio IDE supports putting files into folders.<br />
CMake can be used to put files in folders with the SOURCE_GROUP <br />
command. <br />
<br />
SOURCE_GROUP(name [REGULAR_EXPRESSION regex] [FILES src1 src2 ...])<br />
<br />
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 provided the source file is being passed to ADD_EXECUTABLE or ADD_LIBRARY.<br />
<br />
For example:<br />
SOURCE_GROUP(FooFiles FILES foo.cxx)<br />
SOURCE_GROUP(BarFiles FILES bar.cxx)<br />
ADD_LIBRARY(foo foo.cxx bar.cxx)<br />
<br />
In the event 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).<br />
<br />
As a convenience to developers CMake automatically adds standard header files to a "Header Files" folder and standard source files to a "Source Files" folder for Visual Studio Projects. This can be overridden via the SOURCE_GROUP method documented above.<br />
<br />
=== How to create Visual Studio 6 Projects that contain only a single build type===<br />
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:<br />
<br />
# Create a directory in which you copy the files *.dsptemplate and CMakeVisualStudio6Configurations.cmake from CMake's Templates directory.<br />
# Edit the .cmake file and change the SET(CMAKE_CONFIGURATION_TYPES ...) line to set the build types that you want in your set.<br />
# Edit the *Header.dsptemplate files to contain only the configuration types you want in your set.<br />
# In your CMakeLists.txt file, set the MSPROJECT_TEMPLATE_DIRECTORY to the directory that you created.<br />
<br />
<br />
That's it. Run CMake and your new configuration files will be created.<br />
<br />
Note: Editing the *Header.dsptemplates files should be done very carefully. Here are some guidelines:<br />
<br />
- 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"')<br />
- 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.<br />
- 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.<br />
<br />
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:<br />
# PROP BASE Output_Dir ""<br />
# PROP BASE Intermediate_Dir ""<br />
# PROP Intermediate_Dir ""<br />
# PROP Output_Dir "LIBRARY_OUTPUT_PATH"<br />
or<br />
# PROP Output_Dir "EXECUTABLE_OUTPUT_PATH"<br />
<br />
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).<br />
<br />
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.<br />
<br />
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.)<br />
<br />
=== Can CMake set the Debugging/Working Directory property in Visual Studio projects? ===<br />
<br />
No. The value of this property is not stored in the project files. It is stored in extra files created by the IDE when a solution is loaded (VS .NET 2003 uses a hidden .suo file next to the .sln solution file). The format of these files is not known to CMake and cannot be generated. In some versions of VS the files are binary and not human readable.<br />
<br />
=== Why does CMakeSetup with the message "LINK : fatal error LNK1104: cannot open file 'user32.lib'" while configuring a project? ===<br />
<br />
The path to the SDK libs (user32.lib) must be added by the IDE when the<br />
project generator "Visual Studio 8 2005" is used, because cmake uses<br />
VCExpress.exe and on the fly generated project files to check<br />
for compiling (VCExpress.exe reads some config files for the<br />
compiler/linker options)<br />
<br />
So add the sdk lib path (...\Microsoft Platform SDK\Lib) at Tools->Options->Projects and Solutions->VC++ Directories->Library files<br />
<br />
See also:<br />
*http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/<br />
<br />
=== How can I avoid the error "Arg list too long" when running make? ===<br />
This error is sometimes encountered when building a static library with many object files using Unix make command. It typically looks something like this:<br />
<br />
<pre><br />
gmake[2]: execvp: /bin/sh: Arg list too long<br />
</pre><br />
<br />
When make tries to run the archiver program to build the static library the shell it uses complains that the argument list is too long. In some shells this can be fixed by setting an environment variable such as <tt>ARG_MAX</tt> to extend the length of the command line it will allow.<br />
<br />
=== How can I find out platforms definitions, search paths, etc. from gcc ?===<br />
<br />
The following is really the best if not only way to get information about predefined macros with a GNU compiler:<br />
<pre><br />
$ touch empty.c<br />
$ gcc -v -dD -E empty.c <br />
</pre><br />
This will give you all you might want to know about the preprocessor, the builtin include search dirs and all<br />
predefined definitions, so you can check whether it's __LINUX or _LINUX_ or _APPLE_ or __APPLE etc. <br />
The empty file and all these parameters are really required. You probably want to pipe the output (both stdout and stderr) to a file.<br />
If you want the information for C++, use a C++ file suffix for the empty file.<br />
<br />
This is how you can get the builtin library search paths:<br />
<pre><br />
$ gcc --print-search-dirs<br />
</pre><br />
<br />
=== How can I get a windows registry key ?===<br />
<br />
The only thing to know is that you can't use just the "SET" command in place of "GET" command.<br />
CMake read the value from the registry only when you "get" it from the cache. For instance :<br />
<br />
<pre><br />
GET_FILENAME_COMPONENT(SDK_ROOT_PATH "[HKEY_LOCAL_MACHINE\\SOFTWARE\\PACKAGE;Install_Dir]" ABSOLUTE CACHE)<br />
</pre><br />
<br />
If a key name (ex: Install_Dir in this case) was not specified , the Default key value will be get.<br />
Now you could use the SDK_ROOT_PATH to add include and lib path to your project :<br />
<br />
<pre><br />
INCLUDE_DIRECTORIES(<br />
${SDK_ROOT_PATH}/include<br />
)<br />
<br />
LINK_DIRECTORIES(<br />
${SDK_ROOT_PATH}/lib<br />
)<br />
</pre><br />
<br />
You can also read a registry key in the PATHS section of a FIND_LIBRARY, FIND_PATH, FIND_PROGRAM, or FIND_FILE command<br />
FIND_FILE(BOOT_DOT_INI boot.ini PATHS [HKEY_CURRENT_USER\\Environment;HOMEDRIVE])<br />
<br />
For other examples have a look in the CMake Modules folder :<br />
- FindJava.cmake<br />
- FindPythonLibs.cmake<br />
- ..<br />
<br />
=== How can I build my MSVC application with a static runtime? ===<br />
<br />
Here are three options you could employ to compile your MSVC application with /MT instead of /MD.<br />
<br />
==== Manual Replace ====<br />
<br />
You can rely on the user to manually modify CMAKE_C_FLAGS_DEBUG, CMAKE_C_FLAGS_RELEASE, CMAKE_CXX_FLAGS_DEBUG, CMAKE_CXX_FLAGS_RELEASE, etc. within the cache editor. After an initial configure of your software they would have to replace /MD entries with /MT.<br />
<br />
==== Make Override Files ====<br />
<br />
If you intend to build the entire source tree using /MT and you don't<br />
need this ever to be configurable via the CMake GUI, the best approach<br />
is to create an override file which initializes the starting cache<br />
values for the compile flags.<br />
<br />
First create a c_flag_overrides.cmake & cxx_flag_overrides.cmake file which<br />
contain something like this... (or whatever flags you wish to use per compiler).<br />
<br />
c_flag_overrides.cmake<br />
if(MSVC)<br />
set(CMAKE_C_FLAGS_DEBUG_INIT "/D_DEBUG /MTd /Zi /Ob0 /Od /RTC1")<br />
set(CMAKE_C_FLAGS_MINSIZEREL_INIT "/MT /O1 /Ob1 /D NDEBUG")<br />
set(CMAKE_C_FLAGS_RELEASE_INIT "/MT /O2 /Ob2 /D NDEBUG")<br />
set(CMAKE_C_FLAGS_RELWITHDEBINFO_INIT "/MT /Zi /O2 /Ob1 /D NDEBUG")<br />
endif()<br />
<br />
cxx_flag_overrides.cmake<br />
if(MSVC)<br />
set(CMAKE_CXX_FLAGS_DEBUG_INIT "/D_DEBUG /MTd /Zi /Ob0 /Od /RTC1")<br />
set(CMAKE_CXX_FLAGS_MINSIZEREL_INIT "/MT /O1 /Ob1 /D NDEBUG")<br />
set(CMAKE_CXX_FLAGS_RELEASE_INIT "/MT /O2 /Ob2 /D NDEBUG")<br />
set(CMAKE_CXX_FLAGS_RELWITHDEBINFO_INIT "/MT /Zi /O2 /Ob1 /D NDEBUG")<br />
endif()<br />
<br />
'''NOTE:''' These files are only evaluated on the first run of CMake so they can't be dependent on a CMake option() meant to be toggled from the GUI, for example. They could be dependent on a command line -D option or an environment variable if desired.<br />
<br />
Then enable them by setting the following variables prior to the project() command.<br />
<br />
set(CMAKE_USER_MAKE_RULES_OVERRIDE<br />
${CMAKE_CURRENT_SOURCE_DIR}/c_flag_overrides.cmake)<br />
set(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX<br />
${CMAKE_CURRENT_SOURCE_DIR}/cxx_flag_overrides.cmake)<br />
project(Bar)<br />
<br />
==== Dynamic Replace ====<br />
<br />
Alternatively, if you need dynamic control of /MT via some configure option you could use the following technique. Note: CMAKE_CXX_FLAGS_<FOO> is a directory level option, however. Also, this option has the downside of leaving /MD visible in the cache editor although it has no effect.<br />
<br />
foreach(flag_var<br />
CMAKE_CXX_FLAGS CMAKE_CXX_FLAGS_DEBUG CMAKE_CXX_FLAGS_RELEASE<br />
CMAKE_CXX_FLAGS_MINSIZEREL CMAKE_CXX_FLAGS_RELWITHDEBINFO)<br />
if(${flag_var} MATCHES "/MD")<br />
string(REGEX REPLACE "/MD" "/MT" ${flag_var} "${${flag_var}}")<br />
endif(${flag_var} MATCHES "/MD")<br />
endforeach(flag_var)<br />
<br />
<br />
{{CMake/Template/Footer}}</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake_FAQ&diff=16694CMake FAQ2009-10-07T05:05:51Z<p>Plowman: /* Isn't the "Expression" in the "ELSE (Expression)" confusing? */</p>
<hr />
<div>== General information and availability ==<br />
=== What is CMake? ===<br />
CMake is a cross-platform, open-source make system. CMake is used to control the software compilation process using simple platform-independent 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 http://www.cmake.org/HTML/About.html to learn more about CMake.<br />
<br />
=== What is the current release? ===<br />
The latest release of CMake is always available at: http://www.cmake.org/HTML/Download.html<br />
<br />
From there, you can fetch CMake binaries for Windows or several Unix variants, or you can download the source code of CMake.<br />
<br />
You can also access nightly development through CVS; see http://www.cmake.org/HTML/Download.html for more information. You may also browse the [http://www.cmake.org/cgi-bin/viewcvs.cgi/?root=CMake cvs repository online].<br />
<br />
=== I found a Bug! What should I do? ===<br />
Please report the bug in our bug tracker: http://www.cmake.org/Bug<br />
<br />
Please make sure to look at the old bugs not to include duplicates, include detailed instructions of the bug and how to reproduce it.<br />
<br />
=== I want a new feature in CMake. What should I do? ===<br />
Report a feature request in our Bug tracker http://www.cmake.org/Bug<br />
<br />
Please make sure to look at the old feature requests not to include duplicates, include detailed instructions of the feature and proposed implementation.<br />
<br />
=== What is the most recent version covered by the Mastering CMake book? ===<br />
A new edition of the [http://www.kitware.com/products/cmakebook.html Mastering CMake] book has been released which documents CMake 2.6.<br />
<br />
The following features have been added since printing the book:<br />
<br />
* New INSTALL command (cmake --help-command INSTALL)<br />
* New LIST command (cmake --help-command LIST)<br />
* Updated FIND_PATH, FIND_PROGRAM, and FIND_FILE commands to be more powerful (cmake --help-command FIND_PATH)<br />
* RPATH and Mac OS X install_name support (cmake --help-command SET_TARGET_PROPERTIES)<br />
* CPack Beta (not finished or documented)<br />
* EXECUTE_PROCESS was added and replaces EXEC_PROGRAM<br />
* Other changes have been bug fixes and internal CMake restructuring<br />
<br />
=== Where can I find searchable CMake Mailing Archives? ===<br />
There exists at list those ones:<br />
* [http://dir.gmane.org/gmane.comp.programming.tools.cmake.user cmake on Gmane]<br />
* [http://www.mail-archive.com/cmake@cmake.org/ http://www.mail-archive.com/cmake@cmake.org/]<br />
* [http://marc.info/?l=cmake http://marc.info/?l=cmake]<br />
* Use google ''site'' keyword in order to search directly in the CMake browsable ML:<br />
site:http://www.cmake.org/pipermail/cmake/ <search terms><br />
<br />
== Running CMake ==<br />
<br />
=== Is there an option to produce more 'verbose' compiling? ===<br />
<br />
On Makefile generators, you can set the Makefile variable VERBOSE to 1. For example on UNIX:<br />
make VERBOSE=1<br />
<br />
You can also set CMAKE_VERBOSE_MAKEFILE to ON.<br />
<br />
On Windows (nmake) you can override CMAKE_VERBOSE_MAKEFILE by using<br />
nmake /S<br />
On Unix make you can mostly override verbose mode by using<br />
make VERBOSE=""<br />
<br />
If you are on Windows using Borland or NMake Makefiles, you will see lines like:<br />
<br />
cl @c:\DOCUME~1\ANDY~1.KIT\LOCALS~1\Temp\nma03504<br />
<br />
The reason for this is that Borland and Microsoft Visual Studio make programs have limitation on the length of command strings. They overcome this limitation by writing arguments to the file and then pass file to the program.<br />
<br />
If you actually want to see what the command looks like, set CMAKE_START_TEMP_FILE and CMAKE_END_TEMP_FILE to ""<br />
<br />
=== Is there a way to skip checking of dependent libraries when compiling? ===<br />
<br />
'''Using the Makefile Generator'''<br />
<br />
When using the Makefile generator under *nix you can append "/fast" to your target name. For example:<br />
<br />
make target_name/fast<br />
<br />
Under Windows use a backslash instead:<br />
<br />
make target_name\fast<br />
<br />
'''Using Visual Studio >= 7.1'''<br />
<br />
If you have Visual Studio .NET 7.1 or greater you can use the native option to right click on a project and choose to build just that project.<br />
<br />
'''Using Visual Studio <= 7.0'''<br />
<br />
CMake doesn't try to compile all dependent libraries when you compile a library but it will do so for binary targets. You can't avoid this however you can take advantage of CTRL+F7 to manually compile a source file for the affected target and then relink the target by right clicking on it and choosing Link. You'll have to ensure that all dependent libraries are made up-to-date however or suffer through Visual's slow check.<br />
<br />
=== I set a cmake variable in my environment, but it didn't change anything. Why? ===<br />
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.<br />
<br />
=== How do I use a different compiler? ===<br />
<br />
==== Method 1: use set() ====<br />
<br />
Set the appropriate <tt>CMAKE_FOO_COMPILER</tt> variable(s) to a valid<br />
compiler name or full path in a list file using <tt>set()</tt>. This<br />
must be done ''before'' any language is set (ie before any<br />
<tt>project()</tt> or <tt>enable_language()</tt> command).<br />
<br />
For example:<br />
<pre><br />
set(CMAKE_C_COMPILER "gcc-4.2")<br />
set(CMAKE_CXX_COMPILER "/usr/bin/g++-4.2")<br />
<br />
project("YourProjectName")<br />
</pre><br />
<br />
==== Method 2: use cmake -D ====<br />
<br />
Set the appropriate <tt>CMAKE_FOO_COMPILER</tt> variable(s) to a valid<br />
compiler name or full path on the command-line using <tt>cmake -D</tt>.<br />
<br />
For example:<br />
<pre><br />
cmake -G "Your Generator" -D CMAKE_C_COMPILER=gcc-4.2 -D CMAKE_CXX_COMPILER=g++-4.2 path/to/your/source<br />
</pre><br />
<br />
==== Method 3 (deprecated): use environment variables ====<br />
<br />
For C and C++, set the <tt>CC</tt> and <tt>CXX</tt> environment<br />
variables. This method is not guaranteed to work for all generators.<br />
(Specifically, if you are trying to set Xcode's <tt>GCC_VERSION</tt>,<br />
this method confuses Xcode.)<br />
<br />
For example:<br />
<pre><br />
CC=gcc-4.2 CXX=/usr/bin/g++-4.2 cmake -G "Your Generator" path/to/your/source<br />
</pre><br />
<br />
=== I change CMAKE_C_COMPILER in the GUI but it changes back on the next configure step. Why? ===<br />
<br />
Once a build tree is created with a given compiler it cannot be changed. There are a variety of implementation reasons for this policy.<br />
<br />
=== In CCMake, typing full paths is tedious. Is there a better way? ===<br />
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.<br />
<br />
For example:<br />
<br />
/usr/loc<TAB><br />
<br />
will expand to<br />
<br />
/usr/local/<br />
<br />
<br />
<br />
== Out-of-source build trees ==<br />
<br />
=== What is an "out-of-source" build? ===<br />
When your build generates files, they have to go somewhere. An in-source build puts them in your source tree. An out-of-source build puts them in a completely separate directory, so that your source tree is unchanged.<br />
<br />
In the first example, an in-place build is performed, i.e., the binaries are placed in the same directory as the source code.<br />
<br />
cd Hello<br />
ccmake .<br />
make<br />
<br />
In the second example, an out-of-place build is performed, i.e., the source code, libraries, and executables are produced in a directory separate from the source code directory(ies).<br />
<br />
mkdir HelloBuild<br />
cd HelloBuild<br />
ccmake ../Hello<br />
make<br />
<br />
Out-of-source builds are recommended, as you can build multiple variants in separate directories, e.g., HelloBuildDebug, HelloBuildRelease.<br />
<br />
Note: Before performing an out-of-source build ensure that any possible CMake generated in-source build information is removed from the source directory, e.g., CMakeFiles directory, and CMakeCache.txt.<br />
<br />
=== I run an out-of-source build but CMake generates in-source anyway. Why? ===<br />
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.<br />
<br />
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).<br />
<br />
=== Why does CMake use full paths, or can I copy my build tree? ===<br />
CMake uses full paths because:<br />
<br />
# configured header files may have full paths in them, and moving those files without re-configuring would cause upredictable behavior.<br />
# because cmake supports out of source builds, if custom commands used relative paths to the source tree, they would not work when they are run in the build tree because the current directory would be incorrect.<br />
# on Unix systems rpaths might be 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.<br />
<br />
Can the build tree be copied or moved?<br />
<br />
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 and rerun. Often when people want to move a binary tree it is so that they can distribute it to other users who may not have cmake in which case this would not work even if cmake would detect the move.<br />
<br />
The workaround is to create a new build tree without copying or moving the old one.<br />
<br />
<br />
=== CMake does not generate a "make distclean" target. Why? ===<br />
Some build trees created with GNU autotools have a "make distclean" target that cleans the build and also removes Makefiles and other parts of the generated build system. CMake does not generate a "make distclean" target because CMakeLists.txt files can run scripts and arbitrary commands; CMake has no way of tracking 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. (CMake does generate a "make clean" target to remove files generated by the compiler and linker.)<br />
<br />
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. Because CMake does not change the source tree, there is no need for a distclean target. One can start a fresh build by deleting the build tree or creating a separate build tree.<br />
<br />
(If a CMakeLists.txt uses ADD_CUSTOM_COMMAND to generate source files in the source tree, not the build tree, then in CMake 2.2 or higher "make clean" will remove them. See next question.)<br />
<br />
=== Running "make clean" does not remove custom command outputs. Why? ===<br />
In CMake 2.2 and higher custom command outputs should be removed by make clean. Make sure you are using at least this version. Prior to CMake 2.2 custom command outputs were not automatically added to the list of files to clean. In CMake 2.0 the 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.<br />
<br />
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 to clean away files that differ between builds.<br />
<br />
<br />
== Writing CMakeLists.txt ==<br />
<br />
=== How to have backward and forward compatibility? ===<br />
<br />
As of CMake 2.6 we employ a "Policy" mechanism to provide backwards compatibility.<br />
The basic requirement for projects is to include one line at the top of the highest CMakeLists.txt file:<br />
<br />
cmake_minimum_required(VERSION 2.6) # or other version<br />
<br />
This tells versions of CMake older than that specified that they are too old to build the project.<br />
They will report this information to the user.<br />
It also tells versions of CMake newer than that specified that the project may not be aware of policies introduced in later versions, which enables additional compatibility.<br />
For futher documentation, see<br />
<br />
* [[CMake_Policies|CMake Policy Mechanism]]<br />
* [http://www.cmake.org/cmake/help/cmake2.6docs.html#command:cmake_policy cmake_policy() command]<br />
* [http://www.cmake.org/cmake/help/cmake2.6docs.html#section_Policies CMake 2.6 Policies]<br />
<br />
=== How do I get the current source or binary directory? ===<br />
The variable CMAKE_CURRENT_SOURCE_DIR contains the absolute path to your current source directory, while CMAKE_CURRENT_BINARY_DIR points to the equivalent binary directory.<br />
<br />
=== Why are my CMake variables not updated in the GUI after a SET command? ===<br />
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.<br />
<br />
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:<br />
<br />
SET(BUILD_SHARED_LIBS ON)<br />
<br />
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.<br />
<br />
You can use the CACHE and FORCE options on the SET command to change variables in a way that will be reflected in the GUI. Run<br />
<br />
cmake --help-command SET<br />
<br />
to see full instructions for the command.<br />
<br />
<br />
=== How can I change the default build mode and see it reflected in the GUI? ===<br />
Adapt the following commands in your CMakeLists.txt (this example sets the Release<br />
With Debug Information mode):<br />
<pre><br />
IF(NOT CMAKE_BUILD_TYPE)<br />
SET(CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING<br />
"Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel."<br />
FORCE)<br />
ENDIF(NOT CMAKE_BUILD_TYPE)<br />
</pre><br />
<br />
=== How do I generate an executable, then use the executable to generate a file? ===<br />
<br />
Create the generator executable by just adding a target:<br />
<br />
ADD_EXECUTABLE(generate generate.c)<br />
<br />
The rest of the process is simpler in CMake 2.6 and above than in previous versions.<br />
<br />
Use <code>ADD_CUSTOM_COMMAND</code> to specify a custom build rule for the file.<br />
(In this example we assume <code>generate</code> accepts the input and output files as arguments.)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT someoutput.txt<br />
COMMAND generate ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
DEPENDS generate ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt<br />
)<br />
<br />
This tells CMake how to build the file but does not actually add a rule to the build system.<br />
Another target must require it.<br />
One may create a custom target explicitly for this rule:<br />
<br />
ADD_CUSTOM_TARGET(driver ALL DEPENDS someoutput.txt)<br />
<br />
or the file may be added as part of some other target:<br />
<br />
ADD_EXECUTABLE(product product.c someoutput.txt)<br />
<br />
<font color=#555555><br />
In CMake 2.4 and below the <code>generate</code> target may not be specified directly in the <code>COMMAND</code> option of <code>add_custom_command</code><br />
(but it can still be used in the <code>DEPENDS</code> option as of CMake 2.4).<br />
Instead use GET_TARGET_PROPERTY to obtain the location of the generated executable.<br />
Additionally, the output must always be specified by full path.<br />
<br />
GET_TARGET_PROPERTY(GENERATE_EXE generate LOCATION)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
COMMAND ${GENERATE_EXE} ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
DEPENDS generate<br />
)<br />
</font><br />
<br />
=== How can I generate a source file during the build? ===<br />
The ADD_CUSTOM_COMMAND command lets you generate a source file that you can then include in another target. For example:<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
COMMAND ${CMAKE_COMMAND} copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.c ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.c<br />
)<br />
ADD_EXECUTABLE(foo foo.c)<br />
<br />
This will create an executable by copying bar.c to foo.c and then compiling foo.c to produce foo. CMake allows you to put generate source files in the current source or binary directory, so we were careful to output foo.c to the current binary directory. When we add foo.c to foo, CMake will look in either directory for it. Even if foo.c does not yet exist, CMake is smart enough to notice that a custom command creates it. (For the file named as the OUTPUT, CMake has its GENERATED source file property set to true.)<br />
<br />
You can also use ADD_CUSTOM_COMMAND when the<br />
[[CMake_FAQ#How_do_I_generate_an_executable.2C_then_use_the_executable_to_generate_a_file.3F|generator command is another executable in the same project]].<br />
<br />
Sometimes, the program doing the generation may generate multiple output files that each need to be part of the build. CMake 2.4 or higher supports having multiple files listed in the OUTPUT section. 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:<br />
<br />
PROJECT(FOO)<br />
# make sure cmake addes the binary directory for the project to the include path<br />
INCLUDE_DIRECTORIES(${FOO_BINARY_DIR})<br />
# add the executable that will do the generation<br />
ADD_EXECUTABLE(my_generator my_generator.cxx)<br />
GET_TARGET_PROPERTY(MY_GENERATOR_EXE my_generator LOCATION)<br />
# add the custom command that will generate all three files<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${FOO_BINARY_DIR}/output1.cpp ${FOO_BINARY_DIR}/output2.h ${FOO_BINARY_DIR}/output3.cpp<br />
COMMAND ${MY_GENERATOR_EXE} ${FOO_BINARY_DIR} ${FOO_SOURCE_DIR}/input.txt<br />
DEPENDS my_generator<br />
MAIN_DEPENDENCY ${FOO_SOURCE_DIR}/input.txt<br />
)<br />
# now create an executable using the generated files<br />
ADD_EXECUTABLE(generated<br />
${FOO_BINARY_DIR}/output1.cpp<br />
${FOO_BINARY_DIR}/output2.h<br />
${FOO_BINARY_DIR}/output3.cpp)<br />
<br />
CMake 2.4 allows you to generate a header file. Because generated headers often cause unnecessary rebuilds, you should try to avoid them; consider using the CONFIGURE_FILE command to prepare the header at CMake time. If you must generate a header file, use code like this:<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.h<br />
COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.h ${CMAKE_CURRENT_BINARY_DIR}/foo.h<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.h<br />
)<br />
ADD_EXECUTABLE(foo foo.c ${CMAKE_CURRENT_BINARY_DIR}/foo.h)<br />
<br />
This is like the first example above, except that it generates a header instead of a C file. The header might not exist when the build system scans foo.c's dependencies, so there is no way for CMake to know that this target requires foo.h unless we can tell it that foo.h may exist in the future. We give CMake this knowledge by listing the generated header file in the set of source files for the target. (This requires CMake 2.4. Previous versions of CMake required use of the OBJECT_DEPENDS source file property.)<br />
<br />
=== How can I add a dependency to a source file which is generated in a subdirectory? ===<br />
<br />
Rules created with <code>ADD_CUSTOM_COMMAND</code> as [[CMake_FAQ#How_can_I_generate_a_source_file_during_the_build.3F|above]] have scope only in the directory in which they are specified.<br />
If the generated file is needed in another directory, a target-level dependency needs to be added.<br />
Create a target in the subdirectory with the custom rule in order to drive it:<br />
<br />
# subdir/CMakeLists.txt<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
COMMAND ${CMAKE_COMMAND} copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.c ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.c<br />
)<br />
ADD_CUSTOM_TARGET(generate_foo DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/foo.c)<br />
<br />
Now other targets can depend on the target from the subdirectory:<br />
<br />
# CMakeLists.txt<br />
ADD_SUBDIRECTORY(subdir)<br />
# Create the executable.<br />
ADD_EXECUTABLE(generated ${CMAKE_CURRENT_BINARY_DIR}/subdir/foo.c)<br />
# Tell CMake the source won't be available until build time.<br />
SET_SOURCE_FILES_PROPERTIES(${CMAKE_CURRENT_BINARY_DIR}/subdir/foo.c PROPERTIES GENERATED 1)<br />
# Make sure the source is generated before the executable builds.<br />
ADD_DEPENDENCIES(generated generate_foo)<br />
<br />
=== I use EXEC_PROGRAM but the result is not set in subdirectories. Why? ===<br />
<br />
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 was fixed in CMake 2.2, but for older versions you will have to cache the result:<br />
<br />
<pre><br />
EXEC_PROGRAM(my-program OUTPUT_VARIABLE MY_OUTPUT)<br />
SET(MY_OUTPUT "${MY_OUTPUT}" CACHE INTERNAL "")<br />
</pre><br />
<br />
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.<br />
<br />
=== How can I get or set environment variables? ===<br />
<br />
CMake names environment variables using an ENV prefix and surrounding the names in curly braces. Here is an example:<br />
<br />
<pre><br />
MESSAGE("$ENV{PATH}")<br />
</pre><br />
<br />
Reading variables will work in any version of CMake. Writing to them works in CMake 2.2 and higher using the following syntax:<br />
<br />
<pre><br />
SET(ENV{HELLO} "World")<br />
</pre><br />
<br />
Note that there is currently no way to tell apart an empty environment variable value from a variable that is not set at all.<br />
<br />
One should avoid using environment variables for controlling the flow of CMake code (such as in IF commands). The build system generated by CMake may re-run CMake automatically when CMakeLists.txt files change. The environment in which this is executed is controlled by the build system and may not match that in which CMake was originally run. If you want to control build settings on the CMake command line, you need to use cache variables set with the -D option. The settings will be saved in CMakeCache.txt so that they don't have to be repeated every time CMake is run on the same build tree.<br />
<br />
Also, environment variables SET in the CMakeLists.txt ''only'' take effect for cmake itself, so you cannot use this method to set an environment variable that a custom command might need.<br />
<br />
=== Why do I have unwanted semicolons ; in my compiler flags? ===<br />
CMake has a list data type. A list is stored as a string of semicolon-separated list elements. Whitespace separated arguments to a SET statement are interpreted as list elements. For instance, SET(var a b c d e) will give "var" a value of a;b;c;d;e and this list can be used by other CMake commands. However, if you pass ${var} to a non-CMake external tool, such as a compiler's command line, you are passing a;b;c;d;e which is not what you want. Instead you either need to pass "${var}", so that the list will be converted to a whitespace-separated string, or you need to SET(var "a b c d e") in the 1st place so that you're working with a string, not a list.<br />
<br />
=== How can I get quoting and escapes to work properly? ===<br />
If you want to escape a character in CMake, you use "\", like in C code. For example, if you wanted to have a quote embedded in a string you would do this: "\"". However, each level of CMake that processes your code will need one level of escaping to work. So, if you configure a file that is read by cmake or cpack and you want to do the same thing, you would do "\\\"". You would still need to escape the " for the first cmake that processes the string. However, this time, you would want to also escape a '\' as well. This would leave the next level of processing with "\"". Also, for custom commands that may get passed to a shell, it maybe required to do escaping for that shell.<br />
<br />
=== Isn't the "Expression" in the "ELSE (Expression)" confusing? ===<br />
Traditional CMakeLists.txt files prior to 2.6.0, require the following syntax. In the IF syntax, the ELSE section requires the same (Expression) as the IF section. This sometimes can make the script kind of hard to follow, take the short example below:<br />
<br />
IF(WIN32)<br />
...do something...<br />
ELSE(WIN32)<br />
...do something else...<br />
ENDIF(WIN32)<br />
<br />
You might think that the ELSE section, here containing "...do something else...", is for the WIN32 portion of the script. That is not so! It is actually handling the NOT WIN32 section.<br />
<br />
As of CMake 2.6.0 the ELSE() and ENDIF() constructs can be empty. The same is true for closing constructs on ENDMACRO(), ENDFUNCTION(), and ENDFOREACH(). If you require 2.4.x compatibility, CMake 2.4.3 or greater recognizes the CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS option (which is superfluous in 2.6.0)<br />
<br />
cmake_minimum_required(VERSION 2.4.3)<br />
set(CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS true)<br />
<br />
if(WIN32)<br />
...do something...<br />
elseif(APPLE)<br />
...do something else...<br />
else()<br />
...do something else...<br />
endif()<br />
<br />
=== Which regular expressions are supported by CMake? ===<br />
When using MATCHES or MATCHALL in an IF command, or using any of the STRING(REGEX ...) commands, CMake expects regular expressions, not globs (wild cards). CMake uses the same regular expression engine above all platforms. Here are the meanings of the metacharacters:<br />
<br />
^ Matches at beginning of a line<br />
$ Matches at end of a line<br />
. Matches any single character<br />
[ ] Matches any character(s) inside the brackets<br />
[^ ] Matches any character(s) not inside the brackets<br />
- Matches any character in range on either side of a dash<br />
| Matches a pattern on either side of the |<br />
* Matches preceding pattern zero or more times<br />
+ Matches preceding pattern one or more times<br />
? Matches preceding pattern zero or once only<br />
() Saves a matched expression and uses it in a later match<br />
<br />
Example: "[-][L]([^ ;])+" matches all strings beginning with -L and ending with a space or a semicolon, the usual linkdirs under Linux.<br />
<br />
Here is how to catch a part of a string. The variable test is filled with some content, and then we want to catch the "me":<br />
<br />
SET(test "hello world ! catch: me if you can")<br />
STRING(REGEX REPLACE ".*catch: ([^ ]+).*" "\\1" result "${test}" )<br />
MESSAGE(STATUS "result= ${result}")<br />
<br />
This is slightly tricky. The part inside the brackets is available in \\1 . CMake will copy the variable test to the variable result, but then it will replace everything that the regular expression matches with \\1. This means the first regular expression has to match the whole string and the part we want to catch has to be put in parens.<br />
<br />
-- result= me<br />
<br />
For those of you who know Perl, the equivalent Perl code could be:<br />
<br />
$test = "hello world ! catch: me if you can";<br />
$result = $test;<br />
$result =~ s/.*catch: ([^ ]+).*/$1/;<br />
print "-- result= $result\n";<br />
<br />
There are other ways to do this in Perl, but this is how we do it in CMake because \\1 does not become a variable like $1 does in perl, so there is no SET(result ${\\1}) in CMake.<br />
<br />
<br />
=== How to convert a semicolon separated list to a whitespace separated string? ===<br />
<br />
set(foo<br />
abc.c<br />
abc.b<br />
abc.a<br />
)<br />
<br />
foreach(arg ${foo})<br />
set(bar "${bar} ${arg}")<br />
endforeach(arg ${foo})<br />
<br />
message("foo: ${foo}")<br />
message("bar: ${bar}")<br />
<br />
=== How can I build multiple modes without switching ? ===<br />
To build multiple modes (e.g. Debug and Release) in one shot without constantly running cmake -DCMAKE_BUILD_TYPE=Debug and cmake -DCMAKE_BUILD_TYPE=Release in source tree create a directory for builds eg.:<br />
<br />
<pre><br />
Project-directory/<br />
/Build<br />
</pre><br />
<br />
Inside you can place as many target directories for out-of-source build modes as you want, e.g.:<br />
<br />
<pre><br />
Project-directory/<br />
/Build<br />
/Debug<br />
/Release<br />
</pre><br />
<br />
In each of these directories issue a command (assuming that you have CMakeLists.txt directly in Project-directory)<br />
<br />
<pre><br />
cmake -DCMAKE_BUILD_TYPE=type_of_build ../../<br />
</pre><br />
<br />
to create a cmake cache configured for requested build type.<br />
<br />
Now you can make each build just by entering appropriate directory and executing a make command.<br />
<br />
=== How can I extend the build modes with a custom made one ? ===<br />
The following code snipet (taken from a CMakeLists.txt) adds a Maintainer mode:<br />
<pre><br />
SET( CMAKE_CXX_FLAGS_MAINTAINER "-Wall -Wabi" CACHE STRING<br />
"Flags used by the C++ compiler during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_C_FLAGS_MAINTAINER "-Wall -pedantic" CACHE STRING<br />
"Flags used by the C compiler during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_EXE_LINKER_FLAGS_MAINTAINER<br />
"-Wl,--warn-unresolved-symbols,--warn-once" CACHE STRING<br />
"Flags used for linking binaries during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_SHARED_LINKER_FLAGS_MAINTAINER<br />
"-Wl,--warn-unresolved-symbols,--warn-once" CACHE STRING<br />
"Flags used by the shared libraries linker during maintainer builds."<br />
FORCE )<br />
MARK_AS_ADVANCED(<br />
CMAKE_CXX_FLAGS_MAINTAINER<br />
CMAKE_C_FLAGS_MAINTAINER<br />
CMAKE_EXE_LINKER_FLAGS_MAINTAINER<br />
CMAKE_SHARED_LINKER_FLAGS_MAINTAINER )<br />
# Update the documentation string of CMAKE_BUILD_TYPE for GUIs<br />
SET( CMAKE_BUILD_TYPE "" CACHE STRING<br />
"Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel Maintainer."<br />
FORCE )<br />
</pre><br />
Notes: The flags used in this example are specific to GCC. Change them as needed for your project. Additionally the SET(CMAKE_BUILD_TYPE) command will override<br />
a CMAKE_BUILD_TYPE previously set in the CMakeLists.txt.<br />
<br />
=== Why does <code>foreach</code> skip empty values? ===<br />
<br />
The code in question is of the form<br />
<br />
set(var "a;b;;c;d") # list 'a', 'b', '', 'c', 'd'<br />
foreach(v ${var})<br />
# v=a, v=b, v=c, v=d, one at a time<br />
endforeach()<br />
<br />
and the loop variable 'v' never attains the empty-string value ''.<br />
This is because the <code>${var}</code> syntax is an unquoted argument so the CMake language expands the list and removes the empty value.<br />
The foreach command does not even see the empty value.<br />
One can verify this because the code<br />
<br />
foreach(v a b "" c d)<br />
...<br />
endforeach()<br />
<br />
will see the empty value.<br />
<br />
=== Does CMake support precompiled headers? ===<br />
<br />
Yes and no. Every platform does precompiled headers a bit differently, and there is currently no first-class interface provided by CMake and implemented on every platform.<br />
However, CMake does provide enough primitives for projects to use precompiled headers on specific platforms.<br />
Our issue tracker has a [http://www.cmake.org/Bug/view.php?id=1260 feature request] with attachements providing user-contributed helper macros for some platforms.<br />
<br />
== Writing FindXXX.cmake files ==<br />
<br />
=== What are the rules to write a FindXXX.cmake file? ===<br />
<br />
Let's follow the instructions and the advices in the <br />
Modules/readme.txt [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/readme.txt?root=CMake&view=markup]<br />
file located in the CVS repository.<br />
<br />
=== Why does find_library look in system directories before its PATHS option? ===<br />
<br />
The code in question is often of the form<br />
<br />
find_library(FOO_LIBRARY NAMES foo PATHS /opt/foo/lib)<br />
<br />
CMake will find "<code>/usr/lib/libfoo.so</code>" instead of "<code>/opt/foo/lib/libfoo.so</code>" if both exist.<br />
The reason is that /opt/foo/lib is a <i>hard-coded guess</i> of the location.<br />
The documentation of <code>[http://www.cmake.org/cmake/help/cmake2.6docs.html#command:find_library find_library]</code> specifies the search order.<br />
User, project, and system configuration variables are always more local than hard-coded guesses and should override them, so<br />
the PATHS option is used last.<br />
<br />
Some find-modules compute probable locations based on other information <i>available from the system</i> such as a project-specific environment variable.<br />
The HINTS option (CMake 2.6 and higher) takes precedence over system directories specifically for this case:<br />
<br />
file(TO_CMAKE_PATH "$ENV{FOO_LIB_DIR}" FOO_LIB_DIR)<br />
find_library(FOO_LIBRARY NAMES foo HINTS ${FOO_LIB_DIR})<br />
<br />
CMake will find "<code>$ENV{FOO_LIB_DIR}/libfoo.so</code>" before "<code>/usr/lib/libfoo.so</code>".<br />
<br />
== Finding and using external packages ==<br />
<br />
=== How do I use CMake to generate SWIG wrapper libraries? ===<br />
<br />
CMake version 2 includes a module that supports the generation of SWIG wrapper libraries. The SWIG package defines the following macros: SWIG_ADD_MODULE and SWIG_LINK_LIBRARIES.<br />
<br />
<pre><br />
# This example shows how to use python<br />
# Currently these languages have been tested:<br />
# perl tcl ruby php4 pike<br />
<br />
FIND_PACKAGE(SWIG REQUIRED)<br />
INCLUDE(${SWIG_USE_FILE})<br />
<br />
FIND_PACKAGE(PythonLibs)<br />
INCLUDE_DIRECTORIES(${PYTHON_INCLUDE_PATH})<br />
<br />
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})<br />
<br />
SET(CMAKE_SWIG_FLAGS "")<br />
<br />
SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES CPLUSPLUS ON)<br />
SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES SWIG_FLAGS "-includeall")<br />
SWIG_ADD_MODULE(example python<br />
example.i example.cxx)<br />
SWIG_LINK_LIBRARIES(example ${PYTHON_LIBRARIES})<br />
<br />
</pre><br />
<br />
<pre><br />
# This example shows how to use tcl<br />
PROJECT(TCL_WRAP)<br />
SET ( MODULE_NAME project )<br />
SET ( INTERFACE_FILES project.i)<br />
SET ( SRC_FILES Vertex.h Vertex.cxx Shapes.h Shapes.cxx )<br />
<br />
FIND_PACKAGE(SWIG REQUIRED)<br />
INCLUDE(${SWIG_USE_FILE})<br />
<br />
# Look for TCL<br />
INCLUDE_DIRECTORIES(${TCL_INCLUDE_PATH})<br />
<br />
FIND_LIBRARY(TCL_LIBRARY NAMES tcl tcl84 tcl83 tcl82 tcl80<br />
PATHS /usr/lib /usr/local/lib)<br />
IF (TCL_LIBRARY)<br />
TARGET_ADD_LIBRARY (${MODULE_NAME} TCL_LIBRARY)<br />
ENDIF (TCL_LIBRARY)<br />
<br />
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})<br />
<br />
SET(CMAKE_SWIG_FLAGS "-c++")<br />
<br />
SET_SOURCE_FILES_PROPERTIES(${INTERFACE_FILES} PROPERTIES CPLUSPLUS ON)<br />
SET_SOURCE_FILES_PROPERTIES(${INTERFACE_FILES} PROPERTIES CMAKE_SWIG_FLAGS "-includeall")<br />
SWIG_ADD_MODULE(${MODULE_NAME} tcl ${INTERFACE_FILES} ${SRC_FILES})<br />
SWIG_LINK_LIBRARIES(${MODULE_NAME} ${TCL_LIBRARIES})<br />
</pre><br />
<br />
=== How do I use CMake to build LaTeX documents? ===<br />
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.<br />
<br />
PROJECT(Document)<br />
IF(LATEX_COMPILE)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${Document_BINARY_DIR}/TDocument.dvi<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.tex<br />
COMMAND ${LATEX_COMPILE} <br />
ARGS ${Document_SOURCE_DIR}/TDocument.tex <br />
)<br />
ENDIF(LATEX_COMPILE)<br />
<br />
IF(DVIPDF_COMPILE)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${Document_BINARY_DIR}/TDocument.pdf<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.dvi <br />
COMMAND ${DVIPDF_COMPILE}<br />
ARGS ${Document_SOURCE_DIR}/TDocument.dvi<br />
)<br />
ENDIF(DVIPDF_COMPILE)<br />
<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.pdf<br />
)<br />
<br />
The following uses commands in CMake version 2.0 and later<br />
<br />
PROJECT(Document)<br />
# <br />
# Find LaTeX<br />
#<br />
FIND_PACKAGE(LATEX)<br />
<br />
IF(LATEX_COMPILER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.dvi<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS ${Document_SOURCE_DIR}/TDocument.tex<br />
DEPENDS ${Document_SOURCE_DIR}/TDocument.tex<br />
COMMENT "Tex2dvi"<br />
)<br />
<br />
IF(DVIPS_CONVERTER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.ps<br />
COMMAND ${DVIPS_CONVERTER}<br />
ARGS ${Document_BINARY_DIR}/TDocument.dvi<br />
-o ${Document_BINARY_DIR}/TDocument.ps<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.dvi<br />
COMMENT "dvi2ps"<br />
)<br />
<br />
IF(PS2PDF_CONVERTER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.pdf<br />
COMMAND ${PS2PDF_CONVERTER}<br />
ARGS ${Document_BINARY_DIR}/TDocument.ps<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.ps<br />
COMMENT "ps2pdf"<br />
)<br />
<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.pdf<br />
)<br />
ENDIF(PS2PDF_CONVERTER)<br />
ENDIF(DVIPS_CONVERTER)<br />
ENDIF(LATEX_COMPILER)<br />
<br />
=== How do I get LaTeX references to be correct? ===<br />
When your latex document contains references (e.g. \ref{...} command) you get to run two passes of latex. In the<br />
most general case, i.e. when additionally your document uses a bibtex bibliography, you shall need three<br />
passes of latex (and one pass of bibtex):<br />
# latex (first pass: for bibtex to have an .aux file)<br />
# bibtex (for generating the .bbl file)<br />
# latex (second pass)<br />
# latex (third pass)<br />
<br />
The following code snippet illustrates how you can "pervert" the bibtex and latex generated<br />
auxilary files (.aux, .log, .dvi, .bbl...) to create an "artificial" set of CMake dependencies.<br />
The side-effect of those dependencies should hopefully be the above described sequence of calls<br />
to latex and bibtex<br />
<pre><br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.aux<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/UsersManual.tex<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (first pass)"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.aux<br />
COMMAND ${BIBTEX_COMPILER}<br />
ARGS -terse ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Bibtex"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.dvi<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (second pass)"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.log<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
${CMAKE_CURRENT_BINARY_DIR}/UsersManual.dvi<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (third pass)"<br />
)<br />
# Eventually trigger the whole process<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.log<br />
)<br />
</pre><br />
<br />
=== How can I set TEXINPUTS for a LaTeX compilation? ===<br />
First note that most often you can avoid using TEXINPUTS by copying all the necessary files (.tex source file and<br />
included graphic files e.g. .eps files) from your PROJECT_SOURCE_DIR hirarchy to your PROJECT_BINARY_DIR subdir<br />
[refer to CONFIGURE_FILE with the COPYONLY flag set for copying files]. Since by default latex uses the current working directory as value for TEXINPUTS you should be all set. As expected, this trick is quick AND dirty since your<br />
concerned PROJECT_BINARY_DIR subdir now contains files that are NOT generated by CMake (in the sense that those<br />
files are not the result of a system command but were merely duplicated)... <br />
<br />
If you consider it is cleaner or easier to define a TEXINPUTS environment variable [the latex command probably<br />
misses a -I flag] you can find an example in the InsightDocuments cvs archive (refer to the section "cvs access"<br />
near the bottom of Kitware's ITK download page) or use google with keywords "ITK_TEXINPUTS CONFIGURE_FILE".<br />
Look at InsightDocuments/CourseWare/Training/Vis2003/Latex/CMakeLists.txt and search for e.g. "LaTeXWrapper.sh.in".<br />
<br />
Roughly the mechanism goes:<br />
* SET ITK_TEXINPUTS with the desired TEXINPUTS<br />
* CONFIGURE_FILE "InsightDocuments/CourseWare/Training/Vis2003/LaTeXWrapper.sh.in" which generates an sh shell script setting the shell variable TEXINPUTS prior to running the latex command<br />
* use ADD_CUSTOM_COMMAND to invoke this shell script<br />
This very example is Win32 portable (except that LaTeXWrapper.bat.in generates a .bat shell script)<br />
<br />
== Library questions ==<br />
<br />
=== Can I build both shared and static libraries with one ADD_LIBRARY command? ===<br />
<br />
No. Each library you build must have a unique target name, i.e. the "libname" field of the ADD_LIBRARY command. That way, CMake can track dependencies separately for each library. Libraries can have the same OUTPUT_NAME, see the SET_TARGET_PROPERTIES command, but this is not the default.<br />
<br />
=== Does that mean I have to build all my library objects twice, once for shared and once for static?! I don't like that! ===<br />
<br />
In practice, most libraries have different defines and compiler flags for the shared vs. static cases. So you would have to build all your library objects twice anyways. However, if you happen to have '''''exactly''''' the same defines and compiler flags for the shared vs. static cases...<br />
<br />
...if you're using Linux and a GCC-style linker, you could do the following. Note that for this to work correctly on linux, the zzSTATIC source files should have been compiled with "-fPIC" to ensure they will work in a shared library.<br />
<br />
IF(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_COMPILER_IS_GNUCC)<br />
ADD_LIBRARY(zzSTATIC STATIC -fPIC)<br />
ADD_LIBRARY(zzDYNAMIC SHARED)<br />
TARGET_LINK_LIBRARIES(zzDYNAMIC -Wl,-whole-archive zzSTATIC -Wl,-no-whole-archive)<br />
ENDIF(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_COMPILER_IS_GNUCC)<br />
<br />
...if you want a cross-platform approach that works on all compilers, not just GCC or Linux, you could extract the locations of previously built object files and insert them directly into the libraries that need them. This is documented in [http://www.cmake.org/Bug/view.php?id=5155 CMake Feature Request #5155: standard way to locate object files]. Unfortunately this approach relies on CMake's internal implementation, and that implementation could change in the future, breaking your code.<br />
<br />
=== How do I make my shared and static libraries have the same root name, but different suffixes? ===<br />
Set the OUTPUT_NAME of your shared and static libraries to the same thing.<br />
<br />
ADD_LIBRARY(foo SHARED ${foo_sources})<br />
ADD_LIBRARY(foo-static STATIC ${foo_sources})<br />
// The library target "foo" already has a default OUTPUT_NAME of "foo", so we don't need to change it.<br />
// The library target "foo-static" has a default OUTPUT_NAME of "foo-static", so change it.<br />
SET_TARGET_PROPERTIES(foo-static PROPERTIES OUTPUT_NAME "foo")<br />
<br />
If you are building your shared and static libraries in the same directory, you will also need the following to keep your shared and static libraries from clobbering each other during the build.<br />
<br />
SET_TARGET_PROPERTIES(foo PROPERTIES CLEAN_DIRECT_OUTPUT 1)<br />
SET_TARGET_PROPERTIES(foo-static PROPERTIES CLEAN_DIRECT_OUTPUT 1)<br />
<br />
=== How do I rename a library after it has already been built? ===<br />
You don't rename it. It's been built! Its name is whatever CMakeLists.txt says it's supposed to be.<br />
<br />
Perhaps you want to copy the library to a different name. But, are you sure that's what you want to do? You could just change the name in your ADD_LIBRARY command or change its OUTPUT_NAME property using SET_TARGET_PROPERTY(). If you really really want to copy the library to a different name, try:<br />
<br />
GET_TARGET_PROPERTY(LIB_NAME Foo LOCATION)<br />
GET_TARGET_PROPERTY(Bar_prefix Foo PREFIX)<br />
GET_TARGET_PROPERTY(Bar_suffix Foo SUFFIX)<br />
SET(NEW_LIB_NAME ${Bar_prefix}Bar${Bar_suffix})<br />
<br />
ADD_CUSTOM_COMMAND(<br />
TARGET Foo<br />
POST_BUILD<br />
COMMAND ${CMAKE_COMMAND} -E copy ${LIB_NAME} ${NEW_LIB_NAME}<br />
)<br />
<br />
On Windows you may also want to copy the .dll import lib, using the same approach as above, but with IMPORT_PREFIX and IMPORT_SUFFIX. ''Problem: LOCATION only refers to 1 file, the .dll. What is a simple way to get the location of the import lib? Could provide a complicated way, but that's annoying.''<br />
<br />
=== Does CMake support "convenience" libraries? ===<br />
No. CMake does not currently support convenience libraries. A "convenience" library, as GNU libtool calls it, is an archive of objects to be mixed into other libraries. Other libraries "link" to the convenience library, but the convenience library does not export any symbols; GNU libtool never installs the convenience library; no programs ever link to the convenience library.<br />
<br />
This does '''not''' mean that a project using convenience libraries cannot be converted to CMake. Instead the source files may be listed in each target that needs them. They will be built for each target separately using all the preprocessor definitions and flags configured for that target.<br />
<br />
=== Why are libraries linked to my shared library included when something links to it? ===<br />
This question arises when one has a library B which links to some library A. When a third target, say C, links to B, CMake will automatically include C to A also. When the libraries are static, then this is always necessary. When the libraries are shared, this is the default behavior provided by CMake. CMake 2.6 and above provide the target property "LINK_INTERFACE_LIBRARIES" (http://www.cmake.org/HTML/cmake-2.6.html#prop_tgt:LINK_INTERFACE_LIBRARIES) to specify the libraries that should be transitively included in the link by CMake. CMake 2.4 and below do not support the property.<br />
<br />
Something like the following will work in CMake 2.6:<br />
<br />
<pre><br />
set_target_properties(mylibrary<br />
PROPERTIES<br />
LINK_INTERFACE_LIBRARIES ""<br />
)<br />
</pre><br />
<br />
=== CMake dependency scanner ===<br />
<br />
CMake does not preprocess source files while scanning dependencies. Code like<br />
<pre><br />
#if 0<br />
# include "bla.h"<br />
#endif<br />
</pre><br />
will result in a dependency on "bla.h". This sometimes leads to source files recompiling unnecessarily but will not break the build.<br />
<br />
== Installation questions ==<br />
<br />
=== Does CMake's "make install" support DESTDIR? ===<br />
'''Yes''', especially when the build-system generator uses CMake's builtin support for installing files: Simply define the DESTDIR environment variable during installation and CMake will treat that value as the root of the file system for all installation paths; naturally, the DESTDIR path must be absolute.<br />
<br />
For example, if the Makefile generator is used, then all of the following are example usages of DESTDIR (perhaps assuming the bash shell for the last 2):<br />
<br />
(1) make install DESTDIR="/some/absolute/path"<br />
(2) make DESTDIR="/some/absolute/path" install<br />
(3) DESTDIR="/some/absolute/path" make install<br />
(4) export DESTDIR="/some/absolute/path<br />
make install<br />
<br />
=== Can I do "make uninstall" with CMake?===<br />
By default, CMake does not provide the "make uninstall" target, so you cannot do this. We do not want "make uninstall" to remove useful files from the system.<br />
<br />
If you want an "uninstall" target in your project, then nobody prevents you from providing one. You need to delete the files listed in install_manifest.txt file. Here is how to do it. First create file cmake_uninstall.cmake.in in the top-level directory of the project:<br />
<br />
<pre><br />
IF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")<br />
MESSAGE(FATAL_ERROR "Cannot find install manifest: \"@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt\"")<br />
ENDIF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")<br />
<br />
FILE(READ "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt" files)<br />
STRING(REGEX REPLACE "\n" ";" files "${files}")<br />
FOREACH(file ${files})<br />
MESSAGE(STATUS "Uninstalling \"$ENV{DESTDIR}${file}\"")<br />
IF(EXISTS "$ENV{DESTDIR}${file}")<br />
EXEC_PROGRAM(<br />
"@CMAKE_COMMAND@" ARGS "-E remove \"$ENV{DESTDIR}${file}\""<br />
OUTPUT_VARIABLE rm_out<br />
RETURN_VALUE rm_retval<br />
)<br />
IF(NOT "${rm_retval}" STREQUAL 0)<br />
MESSAGE(FATAL_ERROR "Problem when removing \"$ENV{DESTDIR}${file}\"")<br />
ENDIF(NOT "${rm_retval}" STREQUAL 0)<br />
ELSE(EXISTS "$ENV{DESTDIR}${file}")<br />
MESSAGE(STATUS "File \"$ENV{DESTDIR}${file}\" does not exist.")<br />
ENDIF(EXISTS "$ENV{DESTDIR}${file}")<br />
ENDFOREACH(file)<br />
</pre><br />
<br />
Then in the top-level CMakeLists.txt add the following logic:<br />
<br />
<pre><br />
CONFIGURE_FILE(<br />
"${CMAKE_CURRENT_SOURCE_DIR}/cmake_uninstall.cmake.in"<br />
"${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake"<br />
IMMEDIATE @ONLY)<br />
<br />
ADD_CUSTOM_TARGET(uninstall<br />
"${CMAKE_COMMAND}" -P "${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake")<br />
</pre><br />
<br />
Now you will have an "uninstall" target at the top-level directory of your build tree.<br />
<br />
Instead of creating an "uninstall" target, Unix users could enter this command in the shell:<br />
<br />
xargs rm < install_manifest.txt<br />
<br />
== Distribution questions ==<br />
<br />
=== Where is "make dist"? ===<br />
<br />
CMake doesn't create a "make dist" target.<br />
<br />
=== What is the best way to distribute source code or binaries for a cmake-based project? ===<br />
<br />
For creating source or binary packages there is now [[CMake#CPack | CPack]] coming with CMake, see the <br />
[[ CMake#CPack | documentation]].<br />
<br />
Of course you can also use any other ways to create packages.<br />
<br />
== Platform-specific questions ==<br />
=== How do I build universal binaries on Mac OS X? ===<br />
Before running CMake with an empty build tree, set the CMAKE_OSX_ARCHITECTURES environment variable. It should be set to contain a ; separated list of architectures that you want in the binary. For example, for 32-bit PowerPC and Intel you would do this:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386<br />
<br />
If you wish to build both as 32 and 64 bit, do this:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386;ppc64;x86_64<br />
<br />
You can also set the same named CMake cache variable on an existing binary tree. This works with both makefiles and the Xcode generator. <br />
<br />
In addition, you can also set the CMAKE_OSX_SYSROOT variable to point to the sysroot (aka Mac OS SDK) to be used. CMake will attempt to pick one on your system, but it can be changed in the cache or via an environment variable before running CMake. The 10.4u SDK or later must be used to create a Universal Binary.<br />
<br />
Universal Binaries are essentially cross compilation and so you should avoid using TRY_RUN, especially for things like testing endianess or variable size because the result will only be correct for one architecture.<br />
<br />
Lastly, note that CTest is only able to test one architecture. See bug 6157.<br />
<br />
=== How can I apply resources on Mac OS X automatically? ===<br />
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 a custom rule which is executed after the executable is linked:<br />
<br />
<pre><br />
ADD_EXECUTABLE(MyExecutable ${MyExecutable_SRCS})<br />
GET_TARGET_PROPERTY(MyExecutable_PATH MyExecutable LOCATION)<br />
<br />
IF(APPLE)<br />
FIND_PROGRAM(APPLE_RESOURCE Rez /Developer/Tools)<br />
IF(APPLE_RESOURCE)<br />
ADD_CUSTOM_COMMAND(TARGET MyExecutable POST_BUILD<br />
COMMAND ${APPLE_RESOURCE} Carbon.r -o ${MyExecutable_PATH})<br />
ENDIF(APPLE_RESOURCE)<br />
ENDIF(APPLE)<br />
</pre><br />
<br />
This will execute:<br />
<br />
/Developer/Tools/Rez Carbon.r -o /binary/path/MyExecutable<br />
<br />
after MyExecutable is linked.<br />
<br />
'Rez' may be located elsewhere on disk, depending on the version of Mac OS X and Xcode. You can use 'which Rez' in Terminal to find it's full path.<br />
<br />
=== Why does FIND_LIBRARY not find .DLL libraries under WIN32? ===<br />
For those who come from a Unix background to MS Windows:<br />
<br />
You never link directly to the .dll, you have to link against the import library .lib for the .dll.<br />
<br />
Linking against dynamic libraries (.dll under Windows) is quite different from linking against ELF shared objects (.so) under platforms like Linux or NetBSD. In Windows, there are two types of library, a static library and an import library (both confusingly use the .lib extension, however). In Windows, when you build an import library (A.lib) you will get a corresponding (A.dll) that you only need at runtime. At compile time you will need the import library.<br />
<br />
Conclusion: There is no need to find a .dll for linking. You only need to find the .lib import library.<br />
<br />
Some more details can be found here: [http://xenophilia.org/winvunix.html].<br />
<br />
=== Why am I getting a linker error to _mainCRTStartup under WIN32? ===<br />
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.<br />
<br />
ADD_EXECUTABLE(exename WIN32 source1 source2 ... sourceN)<br />
<br />
The second argument to ADD_EXECUTABLE can be WIN32. This indicates that the executable, when compiled on Windows, is a Windows app (using WinMain) and not a console app (using main). Please note that on Unix platforms, CMake ignores the WIN32 and the compiler will use "main" in any case.<br />
<br />
=== Why do I get this error: nafxcwd.lib(appcore.obj) : error LNK2001: unresolved external symbol ___argv ===<br />
<br />
This is because the application is using both the static and dll versions of the MFC library.<br />
To fix the problem, you can do the following:<br />
<br />
SET(CMAKE_MFC_FLAG 2) # force the IDE to use static MFC<br />
ADD_DEFINITIONS(-D_AFXDLL) # make sure if afx.h is included the dll MFC is used<br />
<br />
=== How to use MFC with CMake ===<br />
To use MFC, the CMAKE_MFC_FLAG variable must be set as follows:<br />
<br />
0: Use Standard Windows Libraries<br />
1: Use MFC in a Static Library<br />
2: Use MFC in a Shared DLL <br />
<br />
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:<br />
<br />
ADD_DEFINITIONS(-D_AFXDLL)<br />
SET(CMAKE_MFC_FLAG 2) <br />
ADD_EXECUTABLE(CMakeSetup WIN32 ${SRCS})<br />
<br />
Note that visual studio 9 project files do not appear to work with CMAKE_MFC_FLAG 1; this may be related to [http://www.cmake.org/Bug/view.php?id=7056 bug 7056].<br />
<br />
In order to use MFC with UNICODE, you must also [http://msdn.microsoft.com/en-us/library/dybsewaf.aspx specify the entry point wWinMainCRTStartup]. For example:<br />
<br />
set(CMAKE_MFC_FLAG 2)<br />
set_target_properties(MyApp PROPERTIES<br />
COMPILE_DEFINITIONS _AFXDLL,_UNICODE,UNICODE,_BIND_TO_CURRENT_CRT_VERSION,_BIND_TO_CURRENT_MFC_VERSION<br />
LINK_FLAGS "/ENTRY:\"wWinMainCRTStartup\"")<br />
<br />
See [http://stackoverflow.com/questions/59635/app-does-not-run-with-vs-2008-sp1-dlls-previous-version-works-with-rtm-versions this article] as to why _BIND_TO_CURRENT_CRT_VERSION and _BIND_TO_CURRENT_MFC_VERSION are necessary for Visual Studio 2008 SP1.<br />
<br />
=== How To Put Files in Folders in Visual Studio Projects ===<br />
The Visual Studio IDE supports putting files into folders.<br />
CMake can be used to put files in folders with the SOURCE_GROUP <br />
command. <br />
<br />
SOURCE_GROUP(name [REGULAR_EXPRESSION regex] [FILES src1 src2 ...])<br />
<br />
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 provided the source file is being passed to ADD_EXECUTABLE or ADD_LIBRARY.<br />
<br />
For example:<br />
SOURCE_GROUP(FooFiles FILES foo.cxx)<br />
SOURCE_GROUP(BarFiles FILES bar.cxx)<br />
ADD_LIBRARY(foo foo.cxx bar.cxx)<br />
<br />
In the event 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).<br />
<br />
As a convenience to developers CMake automatically adds standard header files to a "Header Files" folder and standard source files to a "Source Files" folder for Visual Studio Projects. This can be overridden via the SOURCE_GROUP method documented above.<br />
<br />
=== How to create Visual Studio 6 Projects that contain only a single build type===<br />
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:<br />
<br />
# Create a directory in which you copy the files *.dsptemplate and CMakeVisualStudio6Configurations.cmake from CMake's Templates directory.<br />
# Edit the .cmake file and change the SET(CMAKE_CONFIGURATION_TYPES ...) line to set the build types that you want in your set.<br />
# Edit the *Header.dsptemplate files to contain only the configuration types you want in your set.<br />
# In your CMakeLists.txt file, set the MSPROJECT_TEMPLATE_DIRECTORY to the directory that you created.<br />
<br />
<br />
That's it. Run CMake and your new configuration files will be created.<br />
<br />
Note: Editing the *Header.dsptemplates files should be done very carefully. Here are some guidelines:<br />
<br />
- 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"')<br />
- 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.<br />
- 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.<br />
<br />
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:<br />
# PROP BASE Output_Dir ""<br />
# PROP BASE Intermediate_Dir ""<br />
# PROP Intermediate_Dir ""<br />
# PROP Output_Dir "LIBRARY_OUTPUT_PATH"<br />
or<br />
# PROP Output_Dir "EXECUTABLE_OUTPUT_PATH"<br />
<br />
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).<br />
<br />
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.<br />
<br />
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.)<br />
<br />
=== Can CMake set the Debugging/Working Directory property in Visual Studio projects? ===<br />
<br />
No. The value of this property is not stored in the project files. It is stored in extra files created by the IDE when a solution is loaded (VS .NET 2003 uses a hidden .suo file next to the .sln solution file). The format of these files is not known to CMake and cannot be generated. In some versions of VS the files are binary and not human readable.<br />
<br />
=== Why does CMakeSetup with the message "LINK : fatal error LNK1104: cannot open file 'user32.lib'" while configuring a project? ===<br />
<br />
The path to the SDK libs (user32.lib) must be added by the IDE when the<br />
project generator "Visual Studio 8 2005" is used, because cmake uses<br />
VCExpress.exe and on the fly generated project files to check<br />
for compiling (VCExpress.exe reads some config files for the<br />
compiler/linker options)<br />
<br />
So add the sdk lib path (...\Microsoft Platform SDK\Lib) at Tools->Options->Projects and Solutions->VC++ Directories->Library files<br />
<br />
See also:<br />
*http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/<br />
<br />
=== How can I avoid the error "Arg list too long" when running make? ===<br />
This error is sometimes encountered when building a static library with many object files using Unix make command. It typically looks something like this:<br />
<br />
<pre><br />
gmake[2]: execvp: /bin/sh: Arg list too long<br />
</pre><br />
<br />
When make tries to run the archiver program to build the static library the shell it uses complains that the argument list is too long. In some shells this can be fixed by setting an environment variable such as <tt>ARG_MAX</tt> to extend the length of the command line it will allow.<br />
<br />
=== How can I find out platforms definitions, search paths, etc. from gcc ?===<br />
<br />
The following is really the best if not only way to get information about predefined macros with a GNU compiler:<br />
<pre><br />
$ touch empty.c<br />
$ gcc -v -dD -E empty.c <br />
</pre><br />
This will give you all you might want to know about the preprocessor, the builtin include search dirs and all<br />
predefined definitions, so you can check whether it's __LINUX or _LINUX_ or _APPLE_ or __APPLE etc. <br />
The empty file and all these parameters are really required. You probably want to pipe the output (both stdout and stderr) to a file.<br />
If you want the information for C++, use a C++ file suffix for the empty file.<br />
<br />
This is how you can get the builtin library search paths:<br />
<pre><br />
$ gcc --print-search-dirs<br />
</pre><br />
<br />
=== How can I get a windows registry key ?===<br />
<br />
The only thing to know is that you can't use just the "SET" command in place of "GET" command.<br />
CMake read the value from the registry only when you "get" it from the cache. For instance :<br />
<br />
<pre><br />
GET_FILENAME_COMPONENT(SDK_ROOT_PATH "[HKEY_LOCAL_MACHINE\\SOFTWARE\\PACKAGE;Install_Dir]" ABSOLUTE CACHE)<br />
</pre><br />
<br />
If a key name (ex: Install_Dir in this case) was not specified , the Default key value will be get.<br />
Now you could use the SDK_ROOT_PATH to add include and lib path to your project :<br />
<br />
<pre><br />
INCLUDE_DIRECTORIES(<br />
${SDK_ROOT_PATH}/include<br />
)<br />
<br />
LINK_DIRECTORIES(<br />
${SDK_ROOT_PATH}/lib<br />
)<br />
</pre><br />
<br />
You can also read a registry key in the PATHS section of a FIND_LIBRARY, FIND_PATH, FIND_PROGRAM, or FIND_FILE command<br />
FIND_FILE(BOOT_DOT_INI boot.ini PATHS [HKEY_CURRENT_USER\\Environment;HOMEDRIVE])<br />
<br />
For other examples have a look in the CMake Modules folder :<br />
- FindJava.cmake<br />
- FindPythonLibs.cmake<br />
- ..<br />
<br />
=== How can I build my MSVC application with a static runtime? ===<br />
<br />
Here are two options you could employ to compile your MSVC application with /MT instead of /MD.<br />
<br />
==== Manual Replace ====<br />
<br />
You can rely on the user to modify CMAKE_C_FLAGS_DEBUG, CMAKE_C_FLAGS_RELEASE, CMAKE_CXX_FLAGS_DEBUG, CMAKE_CXX_FLAGS_RELEASE, etc. within the cache editor, replacing /MD with /MT after an initial configure of your software.<br />
<br />
==== Make Override Files ====<br />
<br />
If you intend to build the entire source tree using /MT and you don't<br />
need this ever to be configurable via the CMake GUI, the best approach<br />
is to create an override file which initializes the starting cache<br />
values for the compile flags.<br />
<br />
First create a c_flag_overrides.cmake & cxx_flag_overrides.cmake file which<br />
contain something like this... (or whatever flags you wish to use per compiler).<br />
<br />
'''NOTE:''' These files are only evaluated on the first run of CMake so they can't be dependent on a CMake option() meant to be toggled from the GUI, for example. They could be dependent on a command line -D option or an environment variable if desired.<br />
<br />
c_flag_overrides.cmake<br />
if(MSVC)<br />
set(CMAKE_C_FLAGS_DEBUG_INIT "/D_DEBUG /MTd /Zi /Ob0 /Od /RTC1")<br />
set(CMAKE_C_FLAGS_MINSIZEREL_INIT "/MT /O1 /Ob1 /D NDEBUG")<br />
set(CMAKE_C_FLAGS_RELEASE_INIT "/MT /O2 /Ob2 /D NDEBUG")<br />
set(CMAKE_C_FLAGS_RELWITHDEBINFO_INIT "/MT /Zi /O2 /Ob1 /D NDEBUG")<br />
endif()<br />
<br />
cxx_flag_overrides.cmake<br />
if(MSVC)<br />
set(CMAKE_CXX_FLAGS_DEBUG_INIT "/D_DEBUG /MTd /Zi /Ob0 /Od /RTC1")<br />
set(CMAKE_CXX_FLAGS_MINSIZEREL_INIT "/MT /O1 /Ob1 /D NDEBUG")<br />
set(CMAKE_CXX_FLAGS_RELEASE_INIT "/MT /O2 /Ob2 /D NDEBUG")<br />
set(CMAKE_CXX_FLAGS_RELWITHDEBINFO_INIT "/MT /Zi /O2 /Ob1 /D NDEBUG")<br />
endif()<br />
<br />
Then enable them by setting the following variables prior to the project() command.<br />
<br />
set(CMAKE_USER_MAKE_RULES_OVERRIDE<br />
${CMAKE_CURRENT_SOURCE_DIR}/c_flag_overrides.cmake)<br />
set(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX<br />
${CMAKE_CURRENT_SOURCE_DIR}/cxx_flag_overrides.cmake)<br />
project(Bar)<br />
<br />
==== Dynamic Replace ====<br />
<br />
Alternatively, if you need dynamic control of /MT via some configure option you could use the following technique. Note: CMAKE_CXX_FLAGS_<FOO> is a directory level option, however. Also, this option has the downside of leaving /MD in the cache.<br />
<br />
foreach(flag_var<br />
CMAKE_CXX_FLAGS CMAKE_CXX_FLAGS_DEBUG CMAKE_CXX_FLAGS_RELEASE<br />
CMAKE_CXX_FLAGS_MINSIZEREL CMAKE_CXX_FLAGS_RELWITHDEBINFO)<br />
if(${flag_var} MATCHES "/MD")<br />
string(REGEX REPLACE "/MD" "/MT" ${flag_var} "${${flag_var}}")<br />
endif(${flag_var} MATCHES "/MD")<br />
endforeach(flag_var)<br />
<br />
<br />
{{CMake/Template/Footer}}</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake_FAQ&diff=16693CMake FAQ2009-10-07T05:02:53Z<p>Plowman: /* How can I change the default build mode and see it reflected in the GUI? */ typo</p>
<hr />
<div>== General information and availability ==<br />
=== What is CMake? ===<br />
CMake is a cross-platform, open-source make system. CMake is used to control the software compilation process using simple platform-independent 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 http://www.cmake.org/HTML/About.html to learn more about CMake.<br />
<br />
=== What is the current release? ===<br />
The latest release of CMake is always available at: http://www.cmake.org/HTML/Download.html<br />
<br />
From there, you can fetch CMake binaries for Windows or several Unix variants, or you can download the source code of CMake.<br />
<br />
You can also access nightly development through CVS; see http://www.cmake.org/HTML/Download.html for more information. You may also browse the [http://www.cmake.org/cgi-bin/viewcvs.cgi/?root=CMake cvs repository online].<br />
<br />
=== I found a Bug! What should I do? ===<br />
Please report the bug in our bug tracker: http://www.cmake.org/Bug<br />
<br />
Please make sure to look at the old bugs not to include duplicates, include detailed instructions of the bug and how to reproduce it.<br />
<br />
=== I want a new feature in CMake. What should I do? ===<br />
Report a feature request in our Bug tracker http://www.cmake.org/Bug<br />
<br />
Please make sure to look at the old feature requests not to include duplicates, include detailed instructions of the feature and proposed implementation.<br />
<br />
=== What is the most recent version covered by the Mastering CMake book? ===<br />
A new edition of the [http://www.kitware.com/products/cmakebook.html Mastering CMake] book has been released which documents CMake 2.6.<br />
<br />
The following features have been added since printing the book:<br />
<br />
* New INSTALL command (cmake --help-command INSTALL)<br />
* New LIST command (cmake --help-command LIST)<br />
* Updated FIND_PATH, FIND_PROGRAM, and FIND_FILE commands to be more powerful (cmake --help-command FIND_PATH)<br />
* RPATH and Mac OS X install_name support (cmake --help-command SET_TARGET_PROPERTIES)<br />
* CPack Beta (not finished or documented)<br />
* EXECUTE_PROCESS was added and replaces EXEC_PROGRAM<br />
* Other changes have been bug fixes and internal CMake restructuring<br />
<br />
=== Where can I find searchable CMake Mailing Archives? ===<br />
There exists at list those ones:<br />
* [http://dir.gmane.org/gmane.comp.programming.tools.cmake.user cmake on Gmane]<br />
* [http://www.mail-archive.com/cmake@cmake.org/ http://www.mail-archive.com/cmake@cmake.org/]<br />
* [http://marc.info/?l=cmake http://marc.info/?l=cmake]<br />
* Use google ''site'' keyword in order to search directly in the CMake browsable ML:<br />
site:http://www.cmake.org/pipermail/cmake/ <search terms><br />
<br />
== Running CMake ==<br />
<br />
=== Is there an option to produce more 'verbose' compiling? ===<br />
<br />
On Makefile generators, you can set the Makefile variable VERBOSE to 1. For example on UNIX:<br />
make VERBOSE=1<br />
<br />
You can also set CMAKE_VERBOSE_MAKEFILE to ON.<br />
<br />
On Windows (nmake) you can override CMAKE_VERBOSE_MAKEFILE by using<br />
nmake /S<br />
On Unix make you can mostly override verbose mode by using<br />
make VERBOSE=""<br />
<br />
If you are on Windows using Borland or NMake Makefiles, you will see lines like:<br />
<br />
cl @c:\DOCUME~1\ANDY~1.KIT\LOCALS~1\Temp\nma03504<br />
<br />
The reason for this is that Borland and Microsoft Visual Studio make programs have limitation on the length of command strings. They overcome this limitation by writing arguments to the file and then pass file to the program.<br />
<br />
If you actually want to see what the command looks like, set CMAKE_START_TEMP_FILE and CMAKE_END_TEMP_FILE to ""<br />
<br />
=== Is there a way to skip checking of dependent libraries when compiling? ===<br />
<br />
'''Using the Makefile Generator'''<br />
<br />
When using the Makefile generator under *nix you can append "/fast" to your target name. For example:<br />
<br />
make target_name/fast<br />
<br />
Under Windows use a backslash instead:<br />
<br />
make target_name\fast<br />
<br />
'''Using Visual Studio >= 7.1'''<br />
<br />
If you have Visual Studio .NET 7.1 or greater you can use the native option to right click on a project and choose to build just that project.<br />
<br />
'''Using Visual Studio <= 7.0'''<br />
<br />
CMake doesn't try to compile all dependent libraries when you compile a library but it will do so for binary targets. You can't avoid this however you can take advantage of CTRL+F7 to manually compile a source file for the affected target and then relink the target by right clicking on it and choosing Link. You'll have to ensure that all dependent libraries are made up-to-date however or suffer through Visual's slow check.<br />
<br />
=== I set a cmake variable in my environment, but it didn't change anything. Why? ===<br />
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.<br />
<br />
=== How do I use a different compiler? ===<br />
<br />
==== Method 1: use set() ====<br />
<br />
Set the appropriate <tt>CMAKE_FOO_COMPILER</tt> variable(s) to a valid<br />
compiler name or full path in a list file using <tt>set()</tt>. This<br />
must be done ''before'' any language is set (ie before any<br />
<tt>project()</tt> or <tt>enable_language()</tt> command).<br />
<br />
For example:<br />
<pre><br />
set(CMAKE_C_COMPILER "gcc-4.2")<br />
set(CMAKE_CXX_COMPILER "/usr/bin/g++-4.2")<br />
<br />
project("YourProjectName")<br />
</pre><br />
<br />
==== Method 2: use cmake -D ====<br />
<br />
Set the appropriate <tt>CMAKE_FOO_COMPILER</tt> variable(s) to a valid<br />
compiler name or full path on the command-line using <tt>cmake -D</tt>.<br />
<br />
For example:<br />
<pre><br />
cmake -G "Your Generator" -D CMAKE_C_COMPILER=gcc-4.2 -D CMAKE_CXX_COMPILER=g++-4.2 path/to/your/source<br />
</pre><br />
<br />
==== Method 3 (deprecated): use environment variables ====<br />
<br />
For C and C++, set the <tt>CC</tt> and <tt>CXX</tt> environment<br />
variables. This method is not guaranteed to work for all generators.<br />
(Specifically, if you are trying to set Xcode's <tt>GCC_VERSION</tt>,<br />
this method confuses Xcode.)<br />
<br />
For example:<br />
<pre><br />
CC=gcc-4.2 CXX=/usr/bin/g++-4.2 cmake -G "Your Generator" path/to/your/source<br />
</pre><br />
<br />
=== I change CMAKE_C_COMPILER in the GUI but it changes back on the next configure step. Why? ===<br />
<br />
Once a build tree is created with a given compiler it cannot be changed. There are a variety of implementation reasons for this policy.<br />
<br />
=== In CCMake, typing full paths is tedious. Is there a better way? ===<br />
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.<br />
<br />
For example:<br />
<br />
/usr/loc<TAB><br />
<br />
will expand to<br />
<br />
/usr/local/<br />
<br />
<br />
<br />
== Out-of-source build trees ==<br />
<br />
=== What is an "out-of-source" build? ===<br />
When your build generates files, they have to go somewhere. An in-source build puts them in your source tree. An out-of-source build puts them in a completely separate directory, so that your source tree is unchanged.<br />
<br />
In the first example, an in-place build is performed, i.e., the binaries are placed in the same directory as the source code.<br />
<br />
cd Hello<br />
ccmake .<br />
make<br />
<br />
In the second example, an out-of-place build is performed, i.e., the source code, libraries, and executables are produced in a directory separate from the source code directory(ies).<br />
<br />
mkdir HelloBuild<br />
cd HelloBuild<br />
ccmake ../Hello<br />
make<br />
<br />
Out-of-source builds are recommended, as you can build multiple variants in separate directories, e.g., HelloBuildDebug, HelloBuildRelease.<br />
<br />
Note: Before performing an out-of-source build ensure that any possible CMake generated in-source build information is removed from the source directory, e.g., CMakeFiles directory, and CMakeCache.txt.<br />
<br />
=== I run an out-of-source build but CMake generates in-source anyway. Why? ===<br />
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.<br />
<br />
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).<br />
<br />
=== Why does CMake use full paths, or can I copy my build tree? ===<br />
CMake uses full paths because:<br />
<br />
# configured header files may have full paths in them, and moving those files without re-configuring would cause upredictable behavior.<br />
# because cmake supports out of source builds, if custom commands used relative paths to the source tree, they would not work when they are run in the build tree because the current directory would be incorrect.<br />
# on Unix systems rpaths might be 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.<br />
<br />
Can the build tree be copied or moved?<br />
<br />
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 and rerun. Often when people want to move a binary tree it is so that they can distribute it to other users who may not have cmake in which case this would not work even if cmake would detect the move.<br />
<br />
The workaround is to create a new build tree without copying or moving the old one.<br />
<br />
<br />
=== CMake does not generate a "make distclean" target. Why? ===<br />
Some build trees created with GNU autotools have a "make distclean" target that cleans the build and also removes Makefiles and other parts of the generated build system. CMake does not generate a "make distclean" target because CMakeLists.txt files can run scripts and arbitrary commands; CMake has no way of tracking 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. (CMake does generate a "make clean" target to remove files generated by the compiler and linker.)<br />
<br />
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. Because CMake does not change the source tree, there is no need for a distclean target. One can start a fresh build by deleting the build tree or creating a separate build tree.<br />
<br />
(If a CMakeLists.txt uses ADD_CUSTOM_COMMAND to generate source files in the source tree, not the build tree, then in CMake 2.2 or higher "make clean" will remove them. See next question.)<br />
<br />
=== Running "make clean" does not remove custom command outputs. Why? ===<br />
In CMake 2.2 and higher custom command outputs should be removed by make clean. Make sure you are using at least this version. Prior to CMake 2.2 custom command outputs were not automatically added to the list of files to clean. In CMake 2.0 the 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.<br />
<br />
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 to clean away files that differ between builds.<br />
<br />
<br />
== Writing CMakeLists.txt ==<br />
<br />
=== How to have backward and forward compatibility? ===<br />
<br />
As of CMake 2.6 we employ a "Policy" mechanism to provide backwards compatibility.<br />
The basic requirement for projects is to include one line at the top of the highest CMakeLists.txt file:<br />
<br />
cmake_minimum_required(VERSION 2.6) # or other version<br />
<br />
This tells versions of CMake older than that specified that they are too old to build the project.<br />
They will report this information to the user.<br />
It also tells versions of CMake newer than that specified that the project may not be aware of policies introduced in later versions, which enables additional compatibility.<br />
For futher documentation, see<br />
<br />
* [[CMake_Policies|CMake Policy Mechanism]]<br />
* [http://www.cmake.org/cmake/help/cmake2.6docs.html#command:cmake_policy cmake_policy() command]<br />
* [http://www.cmake.org/cmake/help/cmake2.6docs.html#section_Policies CMake 2.6 Policies]<br />
<br />
=== How do I get the current source or binary directory? ===<br />
The variable CMAKE_CURRENT_SOURCE_DIR contains the absolute path to your current source directory, while CMAKE_CURRENT_BINARY_DIR points to the equivalent binary directory.<br />
<br />
=== Why are my CMake variables not updated in the GUI after a SET command? ===<br />
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.<br />
<br />
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:<br />
<br />
SET(BUILD_SHARED_LIBS ON)<br />
<br />
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.<br />
<br />
You can use the CACHE and FORCE options on the SET command to change variables in a way that will be reflected in the GUI. Run<br />
<br />
cmake --help-command SET<br />
<br />
to see full instructions for the command.<br />
<br />
<br />
=== How can I change the default build mode and see it reflected in the GUI? ===<br />
Adapt the following commands in your CMakeLists.txt (this example sets the Release<br />
With Debug Information mode):<br />
<pre><br />
IF(NOT CMAKE_BUILD_TYPE)<br />
SET(CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING<br />
"Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel."<br />
FORCE)<br />
ENDIF(NOT CMAKE_BUILD_TYPE)<br />
</pre><br />
<br />
=== How do I generate an executable, then use the executable to generate a file? ===<br />
<br />
Create the generator executable by just adding a target:<br />
<br />
ADD_EXECUTABLE(generate generate.c)<br />
<br />
The rest of the process is simpler in CMake 2.6 and above than in previous versions.<br />
<br />
Use <code>ADD_CUSTOM_COMMAND</code> to specify a custom build rule for the file.<br />
(In this example we assume <code>generate</code> accepts the input and output files as arguments.)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT someoutput.txt<br />
COMMAND generate ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
DEPENDS generate ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt<br />
)<br />
<br />
This tells CMake how to build the file but does not actually add a rule to the build system.<br />
Another target must require it.<br />
One may create a custom target explicitly for this rule:<br />
<br />
ADD_CUSTOM_TARGET(driver ALL DEPENDS someoutput.txt)<br />
<br />
or the file may be added as part of some other target:<br />
<br />
ADD_EXECUTABLE(product product.c someoutput.txt)<br />
<br />
<font color=#555555><br />
In CMake 2.4 and below the <code>generate</code> target may not be specified directly in the <code>COMMAND</code> option of <code>add_custom_command</code><br />
(but it can still be used in the <code>DEPENDS</code> option as of CMake 2.4).<br />
Instead use GET_TARGET_PROPERTY to obtain the location of the generated executable.<br />
Additionally, the output must always be specified by full path.<br />
<br />
GET_TARGET_PROPERTY(GENERATE_EXE generate LOCATION)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
COMMAND ${GENERATE_EXE} ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
DEPENDS generate<br />
)<br />
</font><br />
<br />
=== How can I generate a source file during the build? ===<br />
The ADD_CUSTOM_COMMAND command lets you generate a source file that you can then include in another target. For example:<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
COMMAND ${CMAKE_COMMAND} copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.c ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.c<br />
)<br />
ADD_EXECUTABLE(foo foo.c)<br />
<br />
This will create an executable by copying bar.c to foo.c and then compiling foo.c to produce foo. CMake allows you to put generate source files in the current source or binary directory, so we were careful to output foo.c to the current binary directory. When we add foo.c to foo, CMake will look in either directory for it. Even if foo.c does not yet exist, CMake is smart enough to notice that a custom command creates it. (For the file named as the OUTPUT, CMake has its GENERATED source file property set to true.)<br />
<br />
You can also use ADD_CUSTOM_COMMAND when the<br />
[[CMake_FAQ#How_do_I_generate_an_executable.2C_then_use_the_executable_to_generate_a_file.3F|generator command is another executable in the same project]].<br />
<br />
Sometimes, the program doing the generation may generate multiple output files that each need to be part of the build. CMake 2.4 or higher supports having multiple files listed in the OUTPUT section. 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:<br />
<br />
PROJECT(FOO)<br />
# make sure cmake addes the binary directory for the project to the include path<br />
INCLUDE_DIRECTORIES(${FOO_BINARY_DIR})<br />
# add the executable that will do the generation<br />
ADD_EXECUTABLE(my_generator my_generator.cxx)<br />
GET_TARGET_PROPERTY(MY_GENERATOR_EXE my_generator LOCATION)<br />
# add the custom command that will generate all three files<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${FOO_BINARY_DIR}/output1.cpp ${FOO_BINARY_DIR}/output2.h ${FOO_BINARY_DIR}/output3.cpp<br />
COMMAND ${MY_GENERATOR_EXE} ${FOO_BINARY_DIR} ${FOO_SOURCE_DIR}/input.txt<br />
DEPENDS my_generator<br />
MAIN_DEPENDENCY ${FOO_SOURCE_DIR}/input.txt<br />
)<br />
# now create an executable using the generated files<br />
ADD_EXECUTABLE(generated<br />
${FOO_BINARY_DIR}/output1.cpp<br />
${FOO_BINARY_DIR}/output2.h<br />
${FOO_BINARY_DIR}/output3.cpp)<br />
<br />
CMake 2.4 allows you to generate a header file. Because generated headers often cause unnecessary rebuilds, you should try to avoid them; consider using the CONFIGURE_FILE command to prepare the header at CMake time. If you must generate a header file, use code like this:<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.h<br />
COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.h ${CMAKE_CURRENT_BINARY_DIR}/foo.h<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.h<br />
)<br />
ADD_EXECUTABLE(foo foo.c ${CMAKE_CURRENT_BINARY_DIR}/foo.h)<br />
<br />
This is like the first example above, except that it generates a header instead of a C file. The header might not exist when the build system scans foo.c's dependencies, so there is no way for CMake to know that this target requires foo.h unless we can tell it that foo.h may exist in the future. We give CMake this knowledge by listing the generated header file in the set of source files for the target. (This requires CMake 2.4. Previous versions of CMake required use of the OBJECT_DEPENDS source file property.)<br />
<br />
=== How can I add a dependency to a source file which is generated in a subdirectory? ===<br />
<br />
Rules created with <code>ADD_CUSTOM_COMMAND</code> as [[CMake_FAQ#How_can_I_generate_a_source_file_during_the_build.3F|above]] have scope only in the directory in which they are specified.<br />
If the generated file is needed in another directory, a target-level dependency needs to be added.<br />
Create a target in the subdirectory with the custom rule in order to drive it:<br />
<br />
# subdir/CMakeLists.txt<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
COMMAND ${CMAKE_COMMAND} copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.c ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.c<br />
)<br />
ADD_CUSTOM_TARGET(generate_foo DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/foo.c)<br />
<br />
Now other targets can depend on the target from the subdirectory:<br />
<br />
# CMakeLists.txt<br />
ADD_SUBDIRECTORY(subdir)<br />
# Create the executable.<br />
ADD_EXECUTABLE(generated ${CMAKE_CURRENT_BINARY_DIR}/subdir/foo.c)<br />
# Tell CMake the source won't be available until build time.<br />
SET_SOURCE_FILES_PROPERTIES(${CMAKE_CURRENT_BINARY_DIR}/subdir/foo.c PROPERTIES GENERATED 1)<br />
# Make sure the source is generated before the executable builds.<br />
ADD_DEPENDENCIES(generated generate_foo)<br />
<br />
=== I use EXEC_PROGRAM but the result is not set in subdirectories. Why? ===<br />
<br />
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 was fixed in CMake 2.2, but for older versions you will have to cache the result:<br />
<br />
<pre><br />
EXEC_PROGRAM(my-program OUTPUT_VARIABLE MY_OUTPUT)<br />
SET(MY_OUTPUT "${MY_OUTPUT}" CACHE INTERNAL "")<br />
</pre><br />
<br />
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.<br />
<br />
=== How can I get or set environment variables? ===<br />
<br />
CMake names environment variables using an ENV prefix and surrounding the names in curly braces. Here is an example:<br />
<br />
<pre><br />
MESSAGE("$ENV{PATH}")<br />
</pre><br />
<br />
Reading variables will work in any version of CMake. Writing to them works in CMake 2.2 and higher using the following syntax:<br />
<br />
<pre><br />
SET(ENV{HELLO} "World")<br />
</pre><br />
<br />
Note that there is currently no way to tell apart an empty environment variable value from a variable that is not set at all.<br />
<br />
One should avoid using environment variables for controlling the flow of CMake code (such as in IF commands). The build system generated by CMake may re-run CMake automatically when CMakeLists.txt files change. The environment in which this is executed is controlled by the build system and may not match that in which CMake was originally run. If you want to control build settings on the CMake command line, you need to use cache variables set with the -D option. The settings will be saved in CMakeCache.txt so that they don't have to be repeated every time CMake is run on the same build tree.<br />
<br />
Also, environment variables SET in the CMakeLists.txt ''only'' take effect for cmake itself, so you cannot use this method to set an environment variable that a custom command might need.<br />
<br />
=== Why do I have unwanted semicolons ; in my compiler flags? ===<br />
CMake has a list data type. A list is stored as a string of semicolon-separated list elements. Whitespace separated arguments to a SET statement are interpreted as list elements. For instance, SET(var a b c d e) will give "var" a value of a;b;c;d;e and this list can be used by other CMake commands. However, if you pass ${var} to a non-CMake external tool, such as a compiler's command line, you are passing a;b;c;d;e which is not what you want. Instead you either need to pass "${var}", so that the list will be converted to a whitespace-separated string, or you need to SET(var "a b c d e") in the 1st place so that you're working with a string, not a list.<br />
<br />
=== How can I get quoting and escapes to work properly? ===<br />
If you want to escape a character in CMake, you use "\", like in C code. For example, if you wanted to have a quote embedded in a string you would do this: "\"". However, each level of CMake that processes your code will need one level of escaping to work. So, if you configure a file that is read by cmake or cpack and you want to do the same thing, you would do "\\\"". You would still need to escape the " for the first cmake that processes the string. However, this time, you would want to also escape a '\' as well. This would leave the next level of processing with "\"". Also, for custom commands that may get passed to a shell, it maybe required to do escaping for that shell.<br />
<br />
=== Isn't the "Expression" in the "ELSE (Expression)" confusing? ===<br />
Traditional CMakeLists.txt files prior to 2.6.0, require the following syntax. In the IF syntax, the ELSE section requires the same (Expression) as the IF section. This sometimes can make the script kind of hard to follow, take the short example below:<br />
<br />
IF(WIN32)<br />
...do something...<br />
ELSE(WIN32)<br />
...do something else...<br />
ENDIF(WIN32)<br />
<br />
You might think that the ELSE section, here containing "...do something else...", is for the WIN32 portion of the script. That is not so! It is actually handling the NOT WIN32 section.<br />
<br />
As of CMake 2.6.0 the ELSE() and ENDIF() constructs can be empty. The same is true for closing constructs on ENDMACRO(), ENDFUNCTION(), and ENDFOREACH(). If you require 2.4.x compatibility, you can enable the CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS option on CMake 2.4.3 or greater. This option is superfluous on CMake 2.6.0 or greater.<br />
<br />
SET(CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS true)<br />
<br />
IF(WIN32)<br />
...do something...<br />
ELSEIF(APPLE)<br />
...do something else...<br />
ELSE()<br />
...do something else...<br />
ENDIF()<br />
<br />
=== Which regular expressions are supported by CMake? ===<br />
When using MATCHES or MATCHALL in an IF command, or using any of the STRING(REGEX ...) commands, CMake expects regular expressions, not globs (wild cards). CMake uses the same regular expression engine above all platforms. Here are the meanings of the metacharacters:<br />
<br />
^ Matches at beginning of a line<br />
$ Matches at end of a line<br />
. Matches any single character<br />
[ ] Matches any character(s) inside the brackets<br />
[^ ] Matches any character(s) not inside the brackets<br />
- Matches any character in range on either side of a dash<br />
| Matches a pattern on either side of the |<br />
* Matches preceding pattern zero or more times<br />
+ Matches preceding pattern one or more times<br />
? Matches preceding pattern zero or once only<br />
() Saves a matched expression and uses it in a later match<br />
<br />
Example: "[-][L]([^ ;])+" matches all strings beginning with -L and ending with a space or a semicolon, the usual linkdirs under Linux.<br />
<br />
Here is how to catch a part of a string. The variable test is filled with some content, and then we want to catch the "me":<br />
<br />
SET(test "hello world ! catch: me if you can")<br />
STRING(REGEX REPLACE ".*catch: ([^ ]+).*" "\\1" result "${test}" )<br />
MESSAGE(STATUS "result= ${result}")<br />
<br />
This is slightly tricky. The part inside the brackets is available in \\1 . CMake will copy the variable test to the variable result, but then it will replace everything that the regular expression matches with \\1. This means the first regular expression has to match the whole string and the part we want to catch has to be put in parens.<br />
<br />
-- result= me<br />
<br />
For those of you who know Perl, the equivalent Perl code could be:<br />
<br />
$test = "hello world ! catch: me if you can";<br />
$result = $test;<br />
$result =~ s/.*catch: ([^ ]+).*/$1/;<br />
print "-- result= $result\n";<br />
<br />
There are other ways to do this in Perl, but this is how we do it in CMake because \\1 does not become a variable like $1 does in perl, so there is no SET(result ${\\1}) in CMake.<br />
<br />
<br />
=== How to convert a semicolon separated list to a whitespace separated string? ===<br />
<br />
set(foo<br />
abc.c<br />
abc.b<br />
abc.a<br />
)<br />
<br />
foreach(arg ${foo})<br />
set(bar "${bar} ${arg}")<br />
endforeach(arg ${foo})<br />
<br />
message("foo: ${foo}")<br />
message("bar: ${bar}")<br />
<br />
=== How can I build multiple modes without switching ? ===<br />
To build multiple modes (e.g. Debug and Release) in one shot without constantly running cmake -DCMAKE_BUILD_TYPE=Debug and cmake -DCMAKE_BUILD_TYPE=Release in source tree create a directory for builds eg.:<br />
<br />
<pre><br />
Project-directory/<br />
/Build<br />
</pre><br />
<br />
Inside you can place as many target directories for out-of-source build modes as you want, e.g.:<br />
<br />
<pre><br />
Project-directory/<br />
/Build<br />
/Debug<br />
/Release<br />
</pre><br />
<br />
In each of these directories issue a command (assuming that you have CMakeLists.txt directly in Project-directory)<br />
<br />
<pre><br />
cmake -DCMAKE_BUILD_TYPE=type_of_build ../../<br />
</pre><br />
<br />
to create a cmake cache configured for requested build type.<br />
<br />
Now you can make each build just by entering appropriate directory and executing a make command.<br />
<br />
=== How can I extend the build modes with a custom made one ? ===<br />
The following code snipet (taken from a CMakeLists.txt) adds a Maintainer mode:<br />
<pre><br />
SET( CMAKE_CXX_FLAGS_MAINTAINER "-Wall -Wabi" CACHE STRING<br />
"Flags used by the C++ compiler during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_C_FLAGS_MAINTAINER "-Wall -pedantic" CACHE STRING<br />
"Flags used by the C compiler during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_EXE_LINKER_FLAGS_MAINTAINER<br />
"-Wl,--warn-unresolved-symbols,--warn-once" CACHE STRING<br />
"Flags used for linking binaries during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_SHARED_LINKER_FLAGS_MAINTAINER<br />
"-Wl,--warn-unresolved-symbols,--warn-once" CACHE STRING<br />
"Flags used by the shared libraries linker during maintainer builds."<br />
FORCE )<br />
MARK_AS_ADVANCED(<br />
CMAKE_CXX_FLAGS_MAINTAINER<br />
CMAKE_C_FLAGS_MAINTAINER<br />
CMAKE_EXE_LINKER_FLAGS_MAINTAINER<br />
CMAKE_SHARED_LINKER_FLAGS_MAINTAINER )<br />
# Update the documentation string of CMAKE_BUILD_TYPE for GUIs<br />
SET( CMAKE_BUILD_TYPE "" CACHE STRING<br />
"Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel Maintainer."<br />
FORCE )<br />
</pre><br />
Notes: The flags used in this example are specific to GCC. Change them as needed for your project. Additionally the SET(CMAKE_BUILD_TYPE) command will override<br />
a CMAKE_BUILD_TYPE previously set in the CMakeLists.txt.<br />
<br />
=== Why does <code>foreach</code> skip empty values? ===<br />
<br />
The code in question is of the form<br />
<br />
set(var "a;b;;c;d") # list 'a', 'b', '', 'c', 'd'<br />
foreach(v ${var})<br />
# v=a, v=b, v=c, v=d, one at a time<br />
endforeach()<br />
<br />
and the loop variable 'v' never attains the empty-string value ''.<br />
This is because the <code>${var}</code> syntax is an unquoted argument so the CMake language expands the list and removes the empty value.<br />
The foreach command does not even see the empty value.<br />
One can verify this because the code<br />
<br />
foreach(v a b "" c d)<br />
...<br />
endforeach()<br />
<br />
will see the empty value.<br />
<br />
=== Does CMake support precompiled headers? ===<br />
<br />
Yes and no. Every platform does precompiled headers a bit differently, and there is currently no first-class interface provided by CMake and implemented on every platform.<br />
However, CMake does provide enough primitives for projects to use precompiled headers on specific platforms.<br />
Our issue tracker has a [http://www.cmake.org/Bug/view.php?id=1260 feature request] with attachements providing user-contributed helper macros for some platforms.<br />
<br />
== Writing FindXXX.cmake files ==<br />
<br />
=== What are the rules to write a FindXXX.cmake file? ===<br />
<br />
Let's follow the instructions and the advices in the <br />
Modules/readme.txt [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/readme.txt?root=CMake&view=markup]<br />
file located in the CVS repository.<br />
<br />
=== Why does find_library look in system directories before its PATHS option? ===<br />
<br />
The code in question is often of the form<br />
<br />
find_library(FOO_LIBRARY NAMES foo PATHS /opt/foo/lib)<br />
<br />
CMake will find "<code>/usr/lib/libfoo.so</code>" instead of "<code>/opt/foo/lib/libfoo.so</code>" if both exist.<br />
The reason is that /opt/foo/lib is a <i>hard-coded guess</i> of the location.<br />
The documentation of <code>[http://www.cmake.org/cmake/help/cmake2.6docs.html#command:find_library find_library]</code> specifies the search order.<br />
User, project, and system configuration variables are always more local than hard-coded guesses and should override them, so<br />
the PATHS option is used last.<br />
<br />
Some find-modules compute probable locations based on other information <i>available from the system</i> such as a project-specific environment variable.<br />
The HINTS option (CMake 2.6 and higher) takes precedence over system directories specifically for this case:<br />
<br />
file(TO_CMAKE_PATH "$ENV{FOO_LIB_DIR}" FOO_LIB_DIR)<br />
find_library(FOO_LIBRARY NAMES foo HINTS ${FOO_LIB_DIR})<br />
<br />
CMake will find "<code>$ENV{FOO_LIB_DIR}/libfoo.so</code>" before "<code>/usr/lib/libfoo.so</code>".<br />
<br />
== Finding and using external packages ==<br />
<br />
=== How do I use CMake to generate SWIG wrapper libraries? ===<br />
<br />
CMake version 2 includes a module that supports the generation of SWIG wrapper libraries. The SWIG package defines the following macros: SWIG_ADD_MODULE and SWIG_LINK_LIBRARIES.<br />
<br />
<pre><br />
# This example shows how to use python<br />
# Currently these languages have been tested:<br />
# perl tcl ruby php4 pike<br />
<br />
FIND_PACKAGE(SWIG REQUIRED)<br />
INCLUDE(${SWIG_USE_FILE})<br />
<br />
FIND_PACKAGE(PythonLibs)<br />
INCLUDE_DIRECTORIES(${PYTHON_INCLUDE_PATH})<br />
<br />
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})<br />
<br />
SET(CMAKE_SWIG_FLAGS "")<br />
<br />
SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES CPLUSPLUS ON)<br />
SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES SWIG_FLAGS "-includeall")<br />
SWIG_ADD_MODULE(example python<br />
example.i example.cxx)<br />
SWIG_LINK_LIBRARIES(example ${PYTHON_LIBRARIES})<br />
<br />
</pre><br />
<br />
<pre><br />
# This example shows how to use tcl<br />
PROJECT(TCL_WRAP)<br />
SET ( MODULE_NAME project )<br />
SET ( INTERFACE_FILES project.i)<br />
SET ( SRC_FILES Vertex.h Vertex.cxx Shapes.h Shapes.cxx )<br />
<br />
FIND_PACKAGE(SWIG REQUIRED)<br />
INCLUDE(${SWIG_USE_FILE})<br />
<br />
# Look for TCL<br />
INCLUDE_DIRECTORIES(${TCL_INCLUDE_PATH})<br />
<br />
FIND_LIBRARY(TCL_LIBRARY NAMES tcl tcl84 tcl83 tcl82 tcl80<br />
PATHS /usr/lib /usr/local/lib)<br />
IF (TCL_LIBRARY)<br />
TARGET_ADD_LIBRARY (${MODULE_NAME} TCL_LIBRARY)<br />
ENDIF (TCL_LIBRARY)<br />
<br />
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})<br />
<br />
SET(CMAKE_SWIG_FLAGS "-c++")<br />
<br />
SET_SOURCE_FILES_PROPERTIES(${INTERFACE_FILES} PROPERTIES CPLUSPLUS ON)<br />
SET_SOURCE_FILES_PROPERTIES(${INTERFACE_FILES} PROPERTIES CMAKE_SWIG_FLAGS "-includeall")<br />
SWIG_ADD_MODULE(${MODULE_NAME} tcl ${INTERFACE_FILES} ${SRC_FILES})<br />
SWIG_LINK_LIBRARIES(${MODULE_NAME} ${TCL_LIBRARIES})<br />
</pre><br />
<br />
=== How do I use CMake to build LaTeX documents? ===<br />
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.<br />
<br />
PROJECT(Document)<br />
IF(LATEX_COMPILE)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${Document_BINARY_DIR}/TDocument.dvi<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.tex<br />
COMMAND ${LATEX_COMPILE} <br />
ARGS ${Document_SOURCE_DIR}/TDocument.tex <br />
)<br />
ENDIF(LATEX_COMPILE)<br />
<br />
IF(DVIPDF_COMPILE)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${Document_BINARY_DIR}/TDocument.pdf<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.dvi <br />
COMMAND ${DVIPDF_COMPILE}<br />
ARGS ${Document_SOURCE_DIR}/TDocument.dvi<br />
)<br />
ENDIF(DVIPDF_COMPILE)<br />
<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.pdf<br />
)<br />
<br />
The following uses commands in CMake version 2.0 and later<br />
<br />
PROJECT(Document)<br />
# <br />
# Find LaTeX<br />
#<br />
FIND_PACKAGE(LATEX)<br />
<br />
IF(LATEX_COMPILER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.dvi<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS ${Document_SOURCE_DIR}/TDocument.tex<br />
DEPENDS ${Document_SOURCE_DIR}/TDocument.tex<br />
COMMENT "Tex2dvi"<br />
)<br />
<br />
IF(DVIPS_CONVERTER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.ps<br />
COMMAND ${DVIPS_CONVERTER}<br />
ARGS ${Document_BINARY_DIR}/TDocument.dvi<br />
-o ${Document_BINARY_DIR}/TDocument.ps<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.dvi<br />
COMMENT "dvi2ps"<br />
)<br />
<br />
IF(PS2PDF_CONVERTER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.pdf<br />
COMMAND ${PS2PDF_CONVERTER}<br />
ARGS ${Document_BINARY_DIR}/TDocument.ps<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.ps<br />
COMMENT "ps2pdf"<br />
)<br />
<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.pdf<br />
)<br />
ENDIF(PS2PDF_CONVERTER)<br />
ENDIF(DVIPS_CONVERTER)<br />
ENDIF(LATEX_COMPILER)<br />
<br />
=== How do I get LaTeX references to be correct? ===<br />
When your latex document contains references (e.g. \ref{...} command) you get to run two passes of latex. In the<br />
most general case, i.e. when additionally your document uses a bibtex bibliography, you shall need three<br />
passes of latex (and one pass of bibtex):<br />
# latex (first pass: for bibtex to have an .aux file)<br />
# bibtex (for generating the .bbl file)<br />
# latex (second pass)<br />
# latex (third pass)<br />
<br />
The following code snippet illustrates how you can "pervert" the bibtex and latex generated<br />
auxilary files (.aux, .log, .dvi, .bbl...) to create an "artificial" set of CMake dependencies.<br />
The side-effect of those dependencies should hopefully be the above described sequence of calls<br />
to latex and bibtex<br />
<pre><br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.aux<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/UsersManual.tex<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (first pass)"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.aux<br />
COMMAND ${BIBTEX_COMPILER}<br />
ARGS -terse ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Bibtex"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.dvi<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (second pass)"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.log<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
${CMAKE_CURRENT_BINARY_DIR}/UsersManual.dvi<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (third pass)"<br />
)<br />
# Eventually trigger the whole process<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.log<br />
)<br />
</pre><br />
<br />
=== How can I set TEXINPUTS for a LaTeX compilation? ===<br />
First note that most often you can avoid using TEXINPUTS by copying all the necessary files (.tex source file and<br />
included graphic files e.g. .eps files) from your PROJECT_SOURCE_DIR hirarchy to your PROJECT_BINARY_DIR subdir<br />
[refer to CONFIGURE_FILE with the COPYONLY flag set for copying files]. Since by default latex uses the current working directory as value for TEXINPUTS you should be all set. As expected, this trick is quick AND dirty since your<br />
concerned PROJECT_BINARY_DIR subdir now contains files that are NOT generated by CMake (in the sense that those<br />
files are not the result of a system command but were merely duplicated)... <br />
<br />
If you consider it is cleaner or easier to define a TEXINPUTS environment variable [the latex command probably<br />
misses a -I flag] you can find an example in the InsightDocuments cvs archive (refer to the section "cvs access"<br />
near the bottom of Kitware's ITK download page) or use google with keywords "ITK_TEXINPUTS CONFIGURE_FILE".<br />
Look at InsightDocuments/CourseWare/Training/Vis2003/Latex/CMakeLists.txt and search for e.g. "LaTeXWrapper.sh.in".<br />
<br />
Roughly the mechanism goes:<br />
* SET ITK_TEXINPUTS with the desired TEXINPUTS<br />
* CONFIGURE_FILE "InsightDocuments/CourseWare/Training/Vis2003/LaTeXWrapper.sh.in" which generates an sh shell script setting the shell variable TEXINPUTS prior to running the latex command<br />
* use ADD_CUSTOM_COMMAND to invoke this shell script<br />
This very example is Win32 portable (except that LaTeXWrapper.bat.in generates a .bat shell script)<br />
<br />
== Library questions ==<br />
<br />
=== Can I build both shared and static libraries with one ADD_LIBRARY command? ===<br />
<br />
No. Each library you build must have a unique target name, i.e. the "libname" field of the ADD_LIBRARY command. That way, CMake can track dependencies separately for each library. Libraries can have the same OUTPUT_NAME, see the SET_TARGET_PROPERTIES command, but this is not the default.<br />
<br />
=== Does that mean I have to build all my library objects twice, once for shared and once for static?! I don't like that! ===<br />
<br />
In practice, most libraries have different defines and compiler flags for the shared vs. static cases. So you would have to build all your library objects twice anyways. However, if you happen to have '''''exactly''''' the same defines and compiler flags for the shared vs. static cases...<br />
<br />
...if you're using Linux and a GCC-style linker, you could do the following. Note that for this to work correctly on linux, the zzSTATIC source files should have been compiled with "-fPIC" to ensure they will work in a shared library.<br />
<br />
IF(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_COMPILER_IS_GNUCC)<br />
ADD_LIBRARY(zzSTATIC STATIC -fPIC)<br />
ADD_LIBRARY(zzDYNAMIC SHARED)<br />
TARGET_LINK_LIBRARIES(zzDYNAMIC -Wl,-whole-archive zzSTATIC -Wl,-no-whole-archive)<br />
ENDIF(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_COMPILER_IS_GNUCC)<br />
<br />
...if you want a cross-platform approach that works on all compilers, not just GCC or Linux, you could extract the locations of previously built object files and insert them directly into the libraries that need them. This is documented in [http://www.cmake.org/Bug/view.php?id=5155 CMake Feature Request #5155: standard way to locate object files]. Unfortunately this approach relies on CMake's internal implementation, and that implementation could change in the future, breaking your code.<br />
<br />
=== How do I make my shared and static libraries have the same root name, but different suffixes? ===<br />
Set the OUTPUT_NAME of your shared and static libraries to the same thing.<br />
<br />
ADD_LIBRARY(foo SHARED ${foo_sources})<br />
ADD_LIBRARY(foo-static STATIC ${foo_sources})<br />
// The library target "foo" already has a default OUTPUT_NAME of "foo", so we don't need to change it.<br />
// The library target "foo-static" has a default OUTPUT_NAME of "foo-static", so change it.<br />
SET_TARGET_PROPERTIES(foo-static PROPERTIES OUTPUT_NAME "foo")<br />
<br />
If you are building your shared and static libraries in the same directory, you will also need the following to keep your shared and static libraries from clobbering each other during the build.<br />
<br />
SET_TARGET_PROPERTIES(foo PROPERTIES CLEAN_DIRECT_OUTPUT 1)<br />
SET_TARGET_PROPERTIES(foo-static PROPERTIES CLEAN_DIRECT_OUTPUT 1)<br />
<br />
=== How do I rename a library after it has already been built? ===<br />
You don't rename it. It's been built! Its name is whatever CMakeLists.txt says it's supposed to be.<br />
<br />
Perhaps you want to copy the library to a different name. But, are you sure that's what you want to do? You could just change the name in your ADD_LIBRARY command or change its OUTPUT_NAME property using SET_TARGET_PROPERTY(). If you really really want to copy the library to a different name, try:<br />
<br />
GET_TARGET_PROPERTY(LIB_NAME Foo LOCATION)<br />
GET_TARGET_PROPERTY(Bar_prefix Foo PREFIX)<br />
GET_TARGET_PROPERTY(Bar_suffix Foo SUFFIX)<br />
SET(NEW_LIB_NAME ${Bar_prefix}Bar${Bar_suffix})<br />
<br />
ADD_CUSTOM_COMMAND(<br />
TARGET Foo<br />
POST_BUILD<br />
COMMAND ${CMAKE_COMMAND} -E copy ${LIB_NAME} ${NEW_LIB_NAME}<br />
)<br />
<br />
On Windows you may also want to copy the .dll import lib, using the same approach as above, but with IMPORT_PREFIX and IMPORT_SUFFIX. ''Problem: LOCATION only refers to 1 file, the .dll. What is a simple way to get the location of the import lib? Could provide a complicated way, but that's annoying.''<br />
<br />
=== Does CMake support "convenience" libraries? ===<br />
No. CMake does not currently support convenience libraries. A "convenience" library, as GNU libtool calls it, is an archive of objects to be mixed into other libraries. Other libraries "link" to the convenience library, but the convenience library does not export any symbols; GNU libtool never installs the convenience library; no programs ever link to the convenience library.<br />
<br />
This does '''not''' mean that a project using convenience libraries cannot be converted to CMake. Instead the source files may be listed in each target that needs them. They will be built for each target separately using all the preprocessor definitions and flags configured for that target.<br />
<br />
=== Why are libraries linked to my shared library included when something links to it? ===<br />
This question arises when one has a library B which links to some library A. When a third target, say C, links to B, CMake will automatically include C to A also. When the libraries are static, then this is always necessary. When the libraries are shared, this is the default behavior provided by CMake. CMake 2.6 and above provide the target property "LINK_INTERFACE_LIBRARIES" (http://www.cmake.org/HTML/cmake-2.6.html#prop_tgt:LINK_INTERFACE_LIBRARIES) to specify the libraries that should be transitively included in the link by CMake. CMake 2.4 and below do not support the property.<br />
<br />
Something like the following will work in CMake 2.6:<br />
<br />
<pre><br />
set_target_properties(mylibrary<br />
PROPERTIES<br />
LINK_INTERFACE_LIBRARIES ""<br />
)<br />
</pre><br />
<br />
=== CMake dependency scanner ===<br />
<br />
CMake does not preprocess source files while scanning dependencies. Code like<br />
<pre><br />
#if 0<br />
# include "bla.h"<br />
#endif<br />
</pre><br />
will result in a dependency on "bla.h". This sometimes leads to source files recompiling unnecessarily but will not break the build.<br />
<br />
== Installation questions ==<br />
<br />
=== Does CMake's "make install" support DESTDIR? ===<br />
'''Yes''', especially when the build-system generator uses CMake's builtin support for installing files: Simply define the DESTDIR environment variable during installation and CMake will treat that value as the root of the file system for all installation paths; naturally, the DESTDIR path must be absolute.<br />
<br />
For example, if the Makefile generator is used, then all of the following are example usages of DESTDIR (perhaps assuming the bash shell for the last 2):<br />
<br />
(1) make install DESTDIR="/some/absolute/path"<br />
(2) make DESTDIR="/some/absolute/path" install<br />
(3) DESTDIR="/some/absolute/path" make install<br />
(4) export DESTDIR="/some/absolute/path<br />
make install<br />
<br />
=== Can I do "make uninstall" with CMake?===<br />
By default, CMake does not provide the "make uninstall" target, so you cannot do this. We do not want "make uninstall" to remove useful files from the system.<br />
<br />
If you want an "uninstall" target in your project, then nobody prevents you from providing one. You need to delete the files listed in install_manifest.txt file. Here is how to do it. First create file cmake_uninstall.cmake.in in the top-level directory of the project:<br />
<br />
<pre><br />
IF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")<br />
MESSAGE(FATAL_ERROR "Cannot find install manifest: \"@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt\"")<br />
ENDIF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")<br />
<br />
FILE(READ "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt" files)<br />
STRING(REGEX REPLACE "\n" ";" files "${files}")<br />
FOREACH(file ${files})<br />
MESSAGE(STATUS "Uninstalling \"$ENV{DESTDIR}${file}\"")<br />
IF(EXISTS "$ENV{DESTDIR}${file}")<br />
EXEC_PROGRAM(<br />
"@CMAKE_COMMAND@" ARGS "-E remove \"$ENV{DESTDIR}${file}\""<br />
OUTPUT_VARIABLE rm_out<br />
RETURN_VALUE rm_retval<br />
)<br />
IF(NOT "${rm_retval}" STREQUAL 0)<br />
MESSAGE(FATAL_ERROR "Problem when removing \"$ENV{DESTDIR}${file}\"")<br />
ENDIF(NOT "${rm_retval}" STREQUAL 0)<br />
ELSE(EXISTS "$ENV{DESTDIR}${file}")<br />
MESSAGE(STATUS "File \"$ENV{DESTDIR}${file}\" does not exist.")<br />
ENDIF(EXISTS "$ENV{DESTDIR}${file}")<br />
ENDFOREACH(file)<br />
</pre><br />
<br />
Then in the top-level CMakeLists.txt add the following logic:<br />
<br />
<pre><br />
CONFIGURE_FILE(<br />
"${CMAKE_CURRENT_SOURCE_DIR}/cmake_uninstall.cmake.in"<br />
"${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake"<br />
IMMEDIATE @ONLY)<br />
<br />
ADD_CUSTOM_TARGET(uninstall<br />
"${CMAKE_COMMAND}" -P "${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake")<br />
</pre><br />
<br />
Now you will have an "uninstall" target at the top-level directory of your build tree.<br />
<br />
Instead of creating an "uninstall" target, Unix users could enter this command in the shell:<br />
<br />
xargs rm < install_manifest.txt<br />
<br />
== Distribution questions ==<br />
<br />
=== Where is "make dist"? ===<br />
<br />
CMake doesn't create a "make dist" target.<br />
<br />
=== What is the best way to distribute source code or binaries for a cmake-based project? ===<br />
<br />
For creating source or binary packages there is now [[CMake#CPack | CPack]] coming with CMake, see the <br />
[[ CMake#CPack | documentation]].<br />
<br />
Of course you can also use any other ways to create packages.<br />
<br />
== Platform-specific questions ==<br />
=== How do I build universal binaries on Mac OS X? ===<br />
Before running CMake with an empty build tree, set the CMAKE_OSX_ARCHITECTURES environment variable. It should be set to contain a ; separated list of architectures that you want in the binary. For example, for 32-bit PowerPC and Intel you would do this:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386<br />
<br />
If you wish to build both as 32 and 64 bit, do this:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386;ppc64;x86_64<br />
<br />
You can also set the same named CMake cache variable on an existing binary tree. This works with both makefiles and the Xcode generator. <br />
<br />
In addition, you can also set the CMAKE_OSX_SYSROOT variable to point to the sysroot (aka Mac OS SDK) to be used. CMake will attempt to pick one on your system, but it can be changed in the cache or via an environment variable before running CMake. The 10.4u SDK or later must be used to create a Universal Binary.<br />
<br />
Universal Binaries are essentially cross compilation and so you should avoid using TRY_RUN, especially for things like testing endianess or variable size because the result will only be correct for one architecture.<br />
<br />
Lastly, note that CTest is only able to test one architecture. See bug 6157.<br />
<br />
=== How can I apply resources on Mac OS X automatically? ===<br />
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 a custom rule which is executed after the executable is linked:<br />
<br />
<pre><br />
ADD_EXECUTABLE(MyExecutable ${MyExecutable_SRCS})<br />
GET_TARGET_PROPERTY(MyExecutable_PATH MyExecutable LOCATION)<br />
<br />
IF(APPLE)<br />
FIND_PROGRAM(APPLE_RESOURCE Rez /Developer/Tools)<br />
IF(APPLE_RESOURCE)<br />
ADD_CUSTOM_COMMAND(TARGET MyExecutable POST_BUILD<br />
COMMAND ${APPLE_RESOURCE} Carbon.r -o ${MyExecutable_PATH})<br />
ENDIF(APPLE_RESOURCE)<br />
ENDIF(APPLE)<br />
</pre><br />
<br />
This will execute:<br />
<br />
/Developer/Tools/Rez Carbon.r -o /binary/path/MyExecutable<br />
<br />
after MyExecutable is linked.<br />
<br />
'Rez' may be located elsewhere on disk, depending on the version of Mac OS X and Xcode. You can use 'which Rez' in Terminal to find it's full path.<br />
<br />
=== Why does FIND_LIBRARY not find .DLL libraries under WIN32? ===<br />
For those who come from a Unix background to MS Windows:<br />
<br />
You never link directly to the .dll, you have to link against the import library .lib for the .dll.<br />
<br />
Linking against dynamic libraries (.dll under Windows) is quite different from linking against ELF shared objects (.so) under platforms like Linux or NetBSD. In Windows, there are two types of library, a static library and an import library (both confusingly use the .lib extension, however). In Windows, when you build an import library (A.lib) you will get a corresponding (A.dll) that you only need at runtime. At compile time you will need the import library.<br />
<br />
Conclusion: There is no need to find a .dll for linking. You only need to find the .lib import library.<br />
<br />
Some more details can be found here: [http://xenophilia.org/winvunix.html].<br />
<br />
=== Why am I getting a linker error to _mainCRTStartup under WIN32? ===<br />
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.<br />
<br />
ADD_EXECUTABLE(exename WIN32 source1 source2 ... sourceN)<br />
<br />
The second argument to ADD_EXECUTABLE can be WIN32. This indicates that the executable, when compiled on Windows, is a Windows app (using WinMain) and not a console app (using main). Please note that on Unix platforms, CMake ignores the WIN32 and the compiler will use "main" in any case.<br />
<br />
=== Why do I get this error: nafxcwd.lib(appcore.obj) : error LNK2001: unresolved external symbol ___argv ===<br />
<br />
This is because the application is using both the static and dll versions of the MFC library.<br />
To fix the problem, you can do the following:<br />
<br />
SET(CMAKE_MFC_FLAG 2) # force the IDE to use static MFC<br />
ADD_DEFINITIONS(-D_AFXDLL) # make sure if afx.h is included the dll MFC is used<br />
<br />
=== How to use MFC with CMake ===<br />
To use MFC, the CMAKE_MFC_FLAG variable must be set as follows:<br />
<br />
0: Use Standard Windows Libraries<br />
1: Use MFC in a Static Library<br />
2: Use MFC in a Shared DLL <br />
<br />
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:<br />
<br />
ADD_DEFINITIONS(-D_AFXDLL)<br />
SET(CMAKE_MFC_FLAG 2) <br />
ADD_EXECUTABLE(CMakeSetup WIN32 ${SRCS})<br />
<br />
Note that visual studio 9 project files do not appear to work with CMAKE_MFC_FLAG 1; this may be related to [http://www.cmake.org/Bug/view.php?id=7056 bug 7056].<br />
<br />
In order to use MFC with UNICODE, you must also [http://msdn.microsoft.com/en-us/library/dybsewaf.aspx specify the entry point wWinMainCRTStartup]. For example:<br />
<br />
set(CMAKE_MFC_FLAG 2)<br />
set_target_properties(MyApp PROPERTIES<br />
COMPILE_DEFINITIONS _AFXDLL,_UNICODE,UNICODE,_BIND_TO_CURRENT_CRT_VERSION,_BIND_TO_CURRENT_MFC_VERSION<br />
LINK_FLAGS "/ENTRY:\"wWinMainCRTStartup\"")<br />
<br />
See [http://stackoverflow.com/questions/59635/app-does-not-run-with-vs-2008-sp1-dlls-previous-version-works-with-rtm-versions this article] as to why _BIND_TO_CURRENT_CRT_VERSION and _BIND_TO_CURRENT_MFC_VERSION are necessary for Visual Studio 2008 SP1.<br />
<br />
=== How To Put Files in Folders in Visual Studio Projects ===<br />
The Visual Studio IDE supports putting files into folders.<br />
CMake can be used to put files in folders with the SOURCE_GROUP <br />
command. <br />
<br />
SOURCE_GROUP(name [REGULAR_EXPRESSION regex] [FILES src1 src2 ...])<br />
<br />
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 provided the source file is being passed to ADD_EXECUTABLE or ADD_LIBRARY.<br />
<br />
For example:<br />
SOURCE_GROUP(FooFiles FILES foo.cxx)<br />
SOURCE_GROUP(BarFiles FILES bar.cxx)<br />
ADD_LIBRARY(foo foo.cxx bar.cxx)<br />
<br />
In the event 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).<br />
<br />
As a convenience to developers CMake automatically adds standard header files to a "Header Files" folder and standard source files to a "Source Files" folder for Visual Studio Projects. This can be overridden via the SOURCE_GROUP method documented above.<br />
<br />
=== How to create Visual Studio 6 Projects that contain only a single build type===<br />
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:<br />
<br />
# Create a directory in which you copy the files *.dsptemplate and CMakeVisualStudio6Configurations.cmake from CMake's Templates directory.<br />
# Edit the .cmake file and change the SET(CMAKE_CONFIGURATION_TYPES ...) line to set the build types that you want in your set.<br />
# Edit the *Header.dsptemplate files to contain only the configuration types you want in your set.<br />
# In your CMakeLists.txt file, set the MSPROJECT_TEMPLATE_DIRECTORY to the directory that you created.<br />
<br />
<br />
That's it. Run CMake and your new configuration files will be created.<br />
<br />
Note: Editing the *Header.dsptemplates files should be done very carefully. Here are some guidelines:<br />
<br />
- 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"')<br />
- 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.<br />
- 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.<br />
<br />
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:<br />
# PROP BASE Output_Dir ""<br />
# PROP BASE Intermediate_Dir ""<br />
# PROP Intermediate_Dir ""<br />
# PROP Output_Dir "LIBRARY_OUTPUT_PATH"<br />
or<br />
# PROP Output_Dir "EXECUTABLE_OUTPUT_PATH"<br />
<br />
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).<br />
<br />
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.<br />
<br />
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.)<br />
<br />
=== Can CMake set the Debugging/Working Directory property in Visual Studio projects? ===<br />
<br />
No. The value of this property is not stored in the project files. It is stored in extra files created by the IDE when a solution is loaded (VS .NET 2003 uses a hidden .suo file next to the .sln solution file). The format of these files is not known to CMake and cannot be generated. In some versions of VS the files are binary and not human readable.<br />
<br />
=== Why does CMakeSetup with the message "LINK : fatal error LNK1104: cannot open file 'user32.lib'" while configuring a project? ===<br />
<br />
The path to the SDK libs (user32.lib) must be added by the IDE when the<br />
project generator "Visual Studio 8 2005" is used, because cmake uses<br />
VCExpress.exe and on the fly generated project files to check<br />
for compiling (VCExpress.exe reads some config files for the<br />
compiler/linker options)<br />
<br />
So add the sdk lib path (...\Microsoft Platform SDK\Lib) at Tools->Options->Projects and Solutions->VC++ Directories->Library files<br />
<br />
See also:<br />
*http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/<br />
<br />
=== How can I avoid the error "Arg list too long" when running make? ===<br />
This error is sometimes encountered when building a static library with many object files using Unix make command. It typically looks something like this:<br />
<br />
<pre><br />
gmake[2]: execvp: /bin/sh: Arg list too long<br />
</pre><br />
<br />
When make tries to run the archiver program to build the static library the shell it uses complains that the argument list is too long. In some shells this can be fixed by setting an environment variable such as <tt>ARG_MAX</tt> to extend the length of the command line it will allow.<br />
<br />
=== How can I find out platforms definitions, search paths, etc. from gcc ?===<br />
<br />
The following is really the best if not only way to get information about predefined macros with a GNU compiler:<br />
<pre><br />
$ touch empty.c<br />
$ gcc -v -dD -E empty.c <br />
</pre><br />
This will give you all you might want to know about the preprocessor, the builtin include search dirs and all<br />
predefined definitions, so you can check whether it's __LINUX or _LINUX_ or _APPLE_ or __APPLE etc. <br />
The empty file and all these parameters are really required. You probably want to pipe the output (both stdout and stderr) to a file.<br />
If you want the information for C++, use a C++ file suffix for the empty file.<br />
<br />
This is how you can get the builtin library search paths:<br />
<pre><br />
$ gcc --print-search-dirs<br />
</pre><br />
<br />
=== How can I get a windows registry key ?===<br />
<br />
The only thing to know is that you can't use just the "SET" command in place of "GET" command.<br />
CMake read the value from the registry only when you "get" it from the cache. For instance :<br />
<br />
<pre><br />
GET_FILENAME_COMPONENT(SDK_ROOT_PATH "[HKEY_LOCAL_MACHINE\\SOFTWARE\\PACKAGE;Install_Dir]" ABSOLUTE CACHE)<br />
</pre><br />
<br />
If a key name (ex: Install_Dir in this case) was not specified , the Default key value will be get.<br />
Now you could use the SDK_ROOT_PATH to add include and lib path to your project :<br />
<br />
<pre><br />
INCLUDE_DIRECTORIES(<br />
${SDK_ROOT_PATH}/include<br />
)<br />
<br />
LINK_DIRECTORIES(<br />
${SDK_ROOT_PATH}/lib<br />
)<br />
</pre><br />
<br />
You can also read a registry key in the PATHS section of a FIND_LIBRARY, FIND_PATH, FIND_PROGRAM, or FIND_FILE command<br />
FIND_FILE(BOOT_DOT_INI boot.ini PATHS [HKEY_CURRENT_USER\\Environment;HOMEDRIVE])<br />
<br />
For other examples have a look in the CMake Modules folder :<br />
- FindJava.cmake<br />
- FindPythonLibs.cmake<br />
- ..<br />
<br />
=== How can I build my MSVC application with a static runtime? ===<br />
<br />
Here are two options you could employ to compile your MSVC application with /MT instead of /MD.<br />
<br />
==== Manual Replace ====<br />
<br />
You can rely on the user to modify CMAKE_C_FLAGS_DEBUG, CMAKE_C_FLAGS_RELEASE, CMAKE_CXX_FLAGS_DEBUG, CMAKE_CXX_FLAGS_RELEASE, etc. within the cache editor, replacing /MD with /MT after an initial configure of your software.<br />
<br />
==== Make Override Files ====<br />
<br />
If you intend to build the entire source tree using /MT and you don't<br />
need this ever to be configurable via the CMake GUI, the best approach<br />
is to create an override file which initializes the starting cache<br />
values for the compile flags.<br />
<br />
First create a c_flag_overrides.cmake & cxx_flag_overrides.cmake file which<br />
contain something like this... (or whatever flags you wish to use per compiler).<br />
<br />
'''NOTE:''' These files are only evaluated on the first run of CMake so they can't be dependent on a CMake option() meant to be toggled from the GUI, for example. They could be dependent on a command line -D option or an environment variable if desired.<br />
<br />
c_flag_overrides.cmake<br />
if(MSVC)<br />
set(CMAKE_C_FLAGS_DEBUG_INIT "/D_DEBUG /MTd /Zi /Ob0 /Od /RTC1")<br />
set(CMAKE_C_FLAGS_MINSIZEREL_INIT "/MT /O1 /Ob1 /D NDEBUG")<br />
set(CMAKE_C_FLAGS_RELEASE_INIT "/MT /O2 /Ob2 /D NDEBUG")<br />
set(CMAKE_C_FLAGS_RELWITHDEBINFO_INIT "/MT /Zi /O2 /Ob1 /D NDEBUG")<br />
endif()<br />
<br />
cxx_flag_overrides.cmake<br />
if(MSVC)<br />
set(CMAKE_CXX_FLAGS_DEBUG_INIT "/D_DEBUG /MTd /Zi /Ob0 /Od /RTC1")<br />
set(CMAKE_CXX_FLAGS_MINSIZEREL_INIT "/MT /O1 /Ob1 /D NDEBUG")<br />
set(CMAKE_CXX_FLAGS_RELEASE_INIT "/MT /O2 /Ob2 /D NDEBUG")<br />
set(CMAKE_CXX_FLAGS_RELWITHDEBINFO_INIT "/MT /Zi /O2 /Ob1 /D NDEBUG")<br />
endif()<br />
<br />
Then enable them by setting the following variables prior to the project() command.<br />
<br />
set(CMAKE_USER_MAKE_RULES_OVERRIDE<br />
${CMAKE_CURRENT_SOURCE_DIR}/c_flag_overrides.cmake)<br />
set(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX<br />
${CMAKE_CURRENT_SOURCE_DIR}/cxx_flag_overrides.cmake)<br />
project(Bar)<br />
<br />
==== Dynamic Replace ====<br />
<br />
Alternatively, if you need dynamic control of /MT via some configure option you could use the following technique. Note: CMAKE_CXX_FLAGS_<FOO> is a directory level option, however. Also, this option has the downside of leaving /MD in the cache.<br />
<br />
foreach(flag_var<br />
CMAKE_CXX_FLAGS CMAKE_CXX_FLAGS_DEBUG CMAKE_CXX_FLAGS_RELEASE<br />
CMAKE_CXX_FLAGS_MINSIZEREL CMAKE_CXX_FLAGS_RELWITHDEBINFO)<br />
if(${flag_var} MATCHES "/MD")<br />
string(REGEX REPLACE "/MD" "/MT" ${flag_var} "${${flag_var}}")<br />
endif(${flag_var} MATCHES "/MD")<br />
endforeach(flag_var)<br />
<br />
<br />
{{CMake/Template/Footer}}</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake_FAQ&diff=16692CMake FAQ2009-10-07T04:59:30Z<p>Plowman: /* Is there an option to produce more 'verbose' compiling? */ reword so make VERBOSE=1 comes first</p>
<hr />
<div>== General information and availability ==<br />
=== What is CMake? ===<br />
CMake is a cross-platform, open-source make system. CMake is used to control the software compilation process using simple platform-independent 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 http://www.cmake.org/HTML/About.html to learn more about CMake.<br />
<br />
=== What is the current release? ===<br />
The latest release of CMake is always available at: http://www.cmake.org/HTML/Download.html<br />
<br />
From there, you can fetch CMake binaries for Windows or several Unix variants, or you can download the source code of CMake.<br />
<br />
You can also access nightly development through CVS; see http://www.cmake.org/HTML/Download.html for more information. You may also browse the [http://www.cmake.org/cgi-bin/viewcvs.cgi/?root=CMake cvs repository online].<br />
<br />
=== I found a Bug! What should I do? ===<br />
Please report the bug in our bug tracker: http://www.cmake.org/Bug<br />
<br />
Please make sure to look at the old bugs not to include duplicates, include detailed instructions of the bug and how to reproduce it.<br />
<br />
=== I want a new feature in CMake. What should I do? ===<br />
Report a feature request in our Bug tracker http://www.cmake.org/Bug<br />
<br />
Please make sure to look at the old feature requests not to include duplicates, include detailed instructions of the feature and proposed implementation.<br />
<br />
=== What is the most recent version covered by the Mastering CMake book? ===<br />
A new edition of the [http://www.kitware.com/products/cmakebook.html Mastering CMake] book has been released which documents CMake 2.6.<br />
<br />
The following features have been added since printing the book:<br />
<br />
* New INSTALL command (cmake --help-command INSTALL)<br />
* New LIST command (cmake --help-command LIST)<br />
* Updated FIND_PATH, FIND_PROGRAM, and FIND_FILE commands to be more powerful (cmake --help-command FIND_PATH)<br />
* RPATH and Mac OS X install_name support (cmake --help-command SET_TARGET_PROPERTIES)<br />
* CPack Beta (not finished or documented)<br />
* EXECUTE_PROCESS was added and replaces EXEC_PROGRAM<br />
* Other changes have been bug fixes and internal CMake restructuring<br />
<br />
=== Where can I find searchable CMake Mailing Archives? ===<br />
There exists at list those ones:<br />
* [http://dir.gmane.org/gmane.comp.programming.tools.cmake.user cmake on Gmane]<br />
* [http://www.mail-archive.com/cmake@cmake.org/ http://www.mail-archive.com/cmake@cmake.org/]<br />
* [http://marc.info/?l=cmake http://marc.info/?l=cmake]<br />
* Use google ''site'' keyword in order to search directly in the CMake browsable ML:<br />
site:http://www.cmake.org/pipermail/cmake/ <search terms><br />
<br />
== Running CMake ==<br />
<br />
=== Is there an option to produce more 'verbose' compiling? ===<br />
<br />
On Makefile generators, you can set the Makefile variable VERBOSE to 1. For example on UNIX:<br />
make VERBOSE=1<br />
<br />
You can also set CMAKE_VERBOSE_MAKEFILE to ON.<br />
<br />
On Windows (nmake) you can override CMAKE_VERBOSE_MAKEFILE by using<br />
nmake /S<br />
On Unix make you can mostly override verbose mode by using<br />
make VERBOSE=""<br />
<br />
If you are on Windows using Borland or NMake Makefiles, you will see lines like:<br />
<br />
cl @c:\DOCUME~1\ANDY~1.KIT\LOCALS~1\Temp\nma03504<br />
<br />
The reason for this is that Borland and Microsoft Visual Studio make programs have limitation on the length of command strings. They overcome this limitation by writing arguments to the file and then pass file to the program.<br />
<br />
If you actually want to see what the command looks like, set CMAKE_START_TEMP_FILE and CMAKE_END_TEMP_FILE to ""<br />
<br />
=== Is there a way to skip checking of dependent libraries when compiling? ===<br />
<br />
'''Using the Makefile Generator'''<br />
<br />
When using the Makefile generator under *nix you can append "/fast" to your target name. For example:<br />
<br />
make target_name/fast<br />
<br />
Under Windows use a backslash instead:<br />
<br />
make target_name\fast<br />
<br />
'''Using Visual Studio >= 7.1'''<br />
<br />
If you have Visual Studio .NET 7.1 or greater you can use the native option to right click on a project and choose to build just that project.<br />
<br />
'''Using Visual Studio <= 7.0'''<br />
<br />
CMake doesn't try to compile all dependent libraries when you compile a library but it will do so for binary targets. You can't avoid this however you can take advantage of CTRL+F7 to manually compile a source file for the affected target and then relink the target by right clicking on it and choosing Link. You'll have to ensure that all dependent libraries are made up-to-date however or suffer through Visual's slow check.<br />
<br />
=== I set a cmake variable in my environment, but it didn't change anything. Why? ===<br />
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.<br />
<br />
=== How do I use a different compiler? ===<br />
<br />
==== Method 1: use set() ====<br />
<br />
Set the appropriate <tt>CMAKE_FOO_COMPILER</tt> variable(s) to a valid<br />
compiler name or full path in a list file using <tt>set()</tt>. This<br />
must be done ''before'' any language is set (ie before any<br />
<tt>project()</tt> or <tt>enable_language()</tt> command).<br />
<br />
For example:<br />
<pre><br />
set(CMAKE_C_COMPILER "gcc-4.2")<br />
set(CMAKE_CXX_COMPILER "/usr/bin/g++-4.2")<br />
<br />
project("YourProjectName")<br />
</pre><br />
<br />
==== Method 2: use cmake -D ====<br />
<br />
Set the appropriate <tt>CMAKE_FOO_COMPILER</tt> variable(s) to a valid<br />
compiler name or full path on the command-line using <tt>cmake -D</tt>.<br />
<br />
For example:<br />
<pre><br />
cmake -G "Your Generator" -D CMAKE_C_COMPILER=gcc-4.2 -D CMAKE_CXX_COMPILER=g++-4.2 path/to/your/source<br />
</pre><br />
<br />
==== Method 3 (deprecated): use environment variables ====<br />
<br />
For C and C++, set the <tt>CC</tt> and <tt>CXX</tt> environment<br />
variables. This method is not guaranteed to work for all generators.<br />
(Specifically, if you are trying to set Xcode's <tt>GCC_VERSION</tt>,<br />
this method confuses Xcode.)<br />
<br />
For example:<br />
<pre><br />
CC=gcc-4.2 CXX=/usr/bin/g++-4.2 cmake -G "Your Generator" path/to/your/source<br />
</pre><br />
<br />
=== I change CMAKE_C_COMPILER in the GUI but it changes back on the next configure step. Why? ===<br />
<br />
Once a build tree is created with a given compiler it cannot be changed. There are a variety of implementation reasons for this policy.<br />
<br />
=== In CCMake, typing full paths is tedious. Is there a better way? ===<br />
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.<br />
<br />
For example:<br />
<br />
/usr/loc<TAB><br />
<br />
will expand to<br />
<br />
/usr/local/<br />
<br />
<br />
<br />
== Out-of-source build trees ==<br />
<br />
=== What is an "out-of-source" build? ===<br />
When your build generates files, they have to go somewhere. An in-source build puts them in your source tree. An out-of-source build puts them in a completely separate directory, so that your source tree is unchanged.<br />
<br />
In the first example, an in-place build is performed, i.e., the binaries are placed in the same directory as the source code.<br />
<br />
cd Hello<br />
ccmake .<br />
make<br />
<br />
In the second example, an out-of-place build is performed, i.e., the source code, libraries, and executables are produced in a directory separate from the source code directory(ies).<br />
<br />
mkdir HelloBuild<br />
cd HelloBuild<br />
ccmake ../Hello<br />
make<br />
<br />
Out-of-source builds are recommended, as you can build multiple variants in separate directories, e.g., HelloBuildDebug, HelloBuildRelease.<br />
<br />
Note: Before performing an out-of-source build ensure that any possible CMake generated in-source build information is removed from the source directory, e.g., CMakeFiles directory, and CMakeCache.txt.<br />
<br />
=== I run an out-of-source build but CMake generates in-source anyway. Why? ===<br />
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.<br />
<br />
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).<br />
<br />
=== Why does CMake use full paths, or can I copy my build tree? ===<br />
CMake uses full paths because:<br />
<br />
# configured header files may have full paths in them, and moving those files without re-configuring would cause upredictable behavior.<br />
# because cmake supports out of source builds, if custom commands used relative paths to the source tree, they would not work when they are run in the build tree because the current directory would be incorrect.<br />
# on Unix systems rpaths might be 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.<br />
<br />
Can the build tree be copied or moved?<br />
<br />
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 and rerun. Often when people want to move a binary tree it is so that they can distribute it to other users who may not have cmake in which case this would not work even if cmake would detect the move.<br />
<br />
The workaround is to create a new build tree without copying or moving the old one.<br />
<br />
<br />
=== CMake does not generate a "make distclean" target. Why? ===<br />
Some build trees created with GNU autotools have a "make distclean" target that cleans the build and also removes Makefiles and other parts of the generated build system. CMake does not generate a "make distclean" target because CMakeLists.txt files can run scripts and arbitrary commands; CMake has no way of tracking 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. (CMake does generate a "make clean" target to remove files generated by the compiler and linker.)<br />
<br />
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. Because CMake does not change the source tree, there is no need for a distclean target. One can start a fresh build by deleting the build tree or creating a separate build tree.<br />
<br />
(If a CMakeLists.txt uses ADD_CUSTOM_COMMAND to generate source files in the source tree, not the build tree, then in CMake 2.2 or higher "make clean" will remove them. See next question.)<br />
<br />
=== Running "make clean" does not remove custom command outputs. Why? ===<br />
In CMake 2.2 and higher custom command outputs should be removed by make clean. Make sure you are using at least this version. Prior to CMake 2.2 custom command outputs were not automatically added to the list of files to clean. In CMake 2.0 the 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.<br />
<br />
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 to clean away files that differ between builds.<br />
<br />
<br />
== Writing CMakeLists.txt ==<br />
<br />
=== How to have backward and forward compatibility? ===<br />
<br />
As of CMake 2.6 we employ a "Policy" mechanism to provide backwards compatibility.<br />
The basic requirement for projects is to include one line at the top of the highest CMakeLists.txt file:<br />
<br />
cmake_minimum_required(VERSION 2.6) # or other version<br />
<br />
This tells versions of CMake older than that specified that they are too old to build the project.<br />
They will report this information to the user.<br />
It also tells versions of CMake newer than that specified that the project may not be aware of policies introduced in later versions, which enables additional compatibility.<br />
For futher documentation, see<br />
<br />
* [[CMake_Policies|CMake Policy Mechanism]]<br />
* [http://www.cmake.org/cmake/help/cmake2.6docs.html#command:cmake_policy cmake_policy() command]<br />
* [http://www.cmake.org/cmake/help/cmake2.6docs.html#section_Policies CMake 2.6 Policies]<br />
<br />
=== How do I get the current source or binary directory? ===<br />
The variable CMAKE_CURRENT_SOURCE_DIR contains the absolute path to your current source directory, while CMAKE_CURRENT_BINARY_DIR points to the equivalent binary directory.<br />
<br />
=== Why are my CMake variables not updated in the GUI after a SET command? ===<br />
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.<br />
<br />
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:<br />
<br />
SET(BUILD_SHARED_LIBS ON)<br />
<br />
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.<br />
<br />
You can use the CACHE and FORCE options on the SET command to change variables in a way that will be reflected in the GUI. Run<br />
<br />
cmake --help-command SET<br />
<br />
to see full instructions for the command.<br />
<br />
<br />
=== How can I change the default build mode and see it reflected in the GUI? ===<br />
Adapt the following commands in your CMakeList.txt (this example sets the Release<br />
With Debug Information mode):<br />
<pre><br />
IF(NOT CMAKE_BUILD_TYPE)<br />
SET(CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING<br />
"Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel."<br />
FORCE)<br />
ENDIF(NOT CMAKE_BUILD_TYPE)<br />
</pre><br />
<br />
=== How do I generate an executable, then use the executable to generate a file? ===<br />
<br />
Create the generator executable by just adding a target:<br />
<br />
ADD_EXECUTABLE(generate generate.c)<br />
<br />
The rest of the process is simpler in CMake 2.6 and above than in previous versions.<br />
<br />
Use <code>ADD_CUSTOM_COMMAND</code> to specify a custom build rule for the file.<br />
(In this example we assume <code>generate</code> accepts the input and output files as arguments.)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT someoutput.txt<br />
COMMAND generate ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
DEPENDS generate ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt<br />
)<br />
<br />
This tells CMake how to build the file but does not actually add a rule to the build system.<br />
Another target must require it.<br />
One may create a custom target explicitly for this rule:<br />
<br />
ADD_CUSTOM_TARGET(driver ALL DEPENDS someoutput.txt)<br />
<br />
or the file may be added as part of some other target:<br />
<br />
ADD_EXECUTABLE(product product.c someoutput.txt)<br />
<br />
<font color=#555555><br />
In CMake 2.4 and below the <code>generate</code> target may not be specified directly in the <code>COMMAND</code> option of <code>add_custom_command</code><br />
(but it can still be used in the <code>DEPENDS</code> option as of CMake 2.4).<br />
Instead use GET_TARGET_PROPERTY to obtain the location of the generated executable.<br />
Additionally, the output must always be specified by full path.<br />
<br />
GET_TARGET_PROPERTY(GENERATE_EXE generate LOCATION)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
COMMAND ${GENERATE_EXE} ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
DEPENDS generate<br />
)<br />
</font><br />
<br />
=== How can I generate a source file during the build? ===<br />
The ADD_CUSTOM_COMMAND command lets you generate a source file that you can then include in another target. For example:<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
COMMAND ${CMAKE_COMMAND} copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.c ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.c<br />
)<br />
ADD_EXECUTABLE(foo foo.c)<br />
<br />
This will create an executable by copying bar.c to foo.c and then compiling foo.c to produce foo. CMake allows you to put generate source files in the current source or binary directory, so we were careful to output foo.c to the current binary directory. When we add foo.c to foo, CMake will look in either directory for it. Even if foo.c does not yet exist, CMake is smart enough to notice that a custom command creates it. (For the file named as the OUTPUT, CMake has its GENERATED source file property set to true.)<br />
<br />
You can also use ADD_CUSTOM_COMMAND when the<br />
[[CMake_FAQ#How_do_I_generate_an_executable.2C_then_use_the_executable_to_generate_a_file.3F|generator command is another executable in the same project]].<br />
<br />
Sometimes, the program doing the generation may generate multiple output files that each need to be part of the build. CMake 2.4 or higher supports having multiple files listed in the OUTPUT section. 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:<br />
<br />
PROJECT(FOO)<br />
# make sure cmake addes the binary directory for the project to the include path<br />
INCLUDE_DIRECTORIES(${FOO_BINARY_DIR})<br />
# add the executable that will do the generation<br />
ADD_EXECUTABLE(my_generator my_generator.cxx)<br />
GET_TARGET_PROPERTY(MY_GENERATOR_EXE my_generator LOCATION)<br />
# add the custom command that will generate all three files<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${FOO_BINARY_DIR}/output1.cpp ${FOO_BINARY_DIR}/output2.h ${FOO_BINARY_DIR}/output3.cpp<br />
COMMAND ${MY_GENERATOR_EXE} ${FOO_BINARY_DIR} ${FOO_SOURCE_DIR}/input.txt<br />
DEPENDS my_generator<br />
MAIN_DEPENDENCY ${FOO_SOURCE_DIR}/input.txt<br />
)<br />
# now create an executable using the generated files<br />
ADD_EXECUTABLE(generated<br />
${FOO_BINARY_DIR}/output1.cpp<br />
${FOO_BINARY_DIR}/output2.h<br />
${FOO_BINARY_DIR}/output3.cpp)<br />
<br />
CMake 2.4 allows you to generate a header file. Because generated headers often cause unnecessary rebuilds, you should try to avoid them; consider using the CONFIGURE_FILE command to prepare the header at CMake time. If you must generate a header file, use code like this:<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.h<br />
COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.h ${CMAKE_CURRENT_BINARY_DIR}/foo.h<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.h<br />
)<br />
ADD_EXECUTABLE(foo foo.c ${CMAKE_CURRENT_BINARY_DIR}/foo.h)<br />
<br />
This is like the first example above, except that it generates a header instead of a C file. The header might not exist when the build system scans foo.c's dependencies, so there is no way for CMake to know that this target requires foo.h unless we can tell it that foo.h may exist in the future. We give CMake this knowledge by listing the generated header file in the set of source files for the target. (This requires CMake 2.4. Previous versions of CMake required use of the OBJECT_DEPENDS source file property.)<br />
<br />
=== How can I add a dependency to a source file which is generated in a subdirectory? ===<br />
<br />
Rules created with <code>ADD_CUSTOM_COMMAND</code> as [[CMake_FAQ#How_can_I_generate_a_source_file_during_the_build.3F|above]] have scope only in the directory in which they are specified.<br />
If the generated file is needed in another directory, a target-level dependency needs to be added.<br />
Create a target in the subdirectory with the custom rule in order to drive it:<br />
<br />
# subdir/CMakeLists.txt<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
COMMAND ${CMAKE_COMMAND} copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.c ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.c<br />
)<br />
ADD_CUSTOM_TARGET(generate_foo DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/foo.c)<br />
<br />
Now other targets can depend on the target from the subdirectory:<br />
<br />
# CMakeLists.txt<br />
ADD_SUBDIRECTORY(subdir)<br />
# Create the executable.<br />
ADD_EXECUTABLE(generated ${CMAKE_CURRENT_BINARY_DIR}/subdir/foo.c)<br />
# Tell CMake the source won't be available until build time.<br />
SET_SOURCE_FILES_PROPERTIES(${CMAKE_CURRENT_BINARY_DIR}/subdir/foo.c PROPERTIES GENERATED 1)<br />
# Make sure the source is generated before the executable builds.<br />
ADD_DEPENDENCIES(generated generate_foo)<br />
<br />
=== I use EXEC_PROGRAM but the result is not set in subdirectories. Why? ===<br />
<br />
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 was fixed in CMake 2.2, but for older versions you will have to cache the result:<br />
<br />
<pre><br />
EXEC_PROGRAM(my-program OUTPUT_VARIABLE MY_OUTPUT)<br />
SET(MY_OUTPUT "${MY_OUTPUT}" CACHE INTERNAL "")<br />
</pre><br />
<br />
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.<br />
<br />
=== How can I get or set environment variables? ===<br />
<br />
CMake names environment variables using an ENV prefix and surrounding the names in curly braces. Here is an example:<br />
<br />
<pre><br />
MESSAGE("$ENV{PATH}")<br />
</pre><br />
<br />
Reading variables will work in any version of CMake. Writing to them works in CMake 2.2 and higher using the following syntax:<br />
<br />
<pre><br />
SET(ENV{HELLO} "World")<br />
</pre><br />
<br />
Note that there is currently no way to tell apart an empty environment variable value from a variable that is not set at all.<br />
<br />
One should avoid using environment variables for controlling the flow of CMake code (such as in IF commands). The build system generated by CMake may re-run CMake automatically when CMakeLists.txt files change. The environment in which this is executed is controlled by the build system and may not match that in which CMake was originally run. If you want to control build settings on the CMake command line, you need to use cache variables set with the -D option. The settings will be saved in CMakeCache.txt so that they don't have to be repeated every time CMake is run on the same build tree.<br />
<br />
Also, environment variables SET in the CMakeLists.txt ''only'' take effect for cmake itself, so you cannot use this method to set an environment variable that a custom command might need.<br />
<br />
=== Why do I have unwanted semicolons ; in my compiler flags? ===<br />
CMake has a list data type. A list is stored as a string of semicolon-separated list elements. Whitespace separated arguments to a SET statement are interpreted as list elements. For instance, SET(var a b c d e) will give "var" a value of a;b;c;d;e and this list can be used by other CMake commands. However, if you pass ${var} to a non-CMake external tool, such as a compiler's command line, you are passing a;b;c;d;e which is not what you want. Instead you either need to pass "${var}", so that the list will be converted to a whitespace-separated string, or you need to SET(var "a b c d e") in the 1st place so that you're working with a string, not a list.<br />
<br />
=== How can I get quoting and escapes to work properly? ===<br />
If you want to escape a character in CMake, you use "\", like in C code. For example, if you wanted to have a quote embedded in a string you would do this: "\"". However, each level of CMake that processes your code will need one level of escaping to work. So, if you configure a file that is read by cmake or cpack and you want to do the same thing, you would do "\\\"". You would still need to escape the " for the first cmake that processes the string. However, this time, you would want to also escape a '\' as well. This would leave the next level of processing with "\"". Also, for custom commands that may get passed to a shell, it maybe required to do escaping for that shell.<br />
<br />
=== Isn't the "Expression" in the "ELSE (Expression)" confusing? ===<br />
Traditional CMakeLists.txt files prior to 2.6.0, require the following syntax. In the IF syntax, the ELSE section requires the same (Expression) as the IF section. This sometimes can make the script kind of hard to follow, take the short example below:<br />
<br />
IF(WIN32)<br />
...do something...<br />
ELSE(WIN32)<br />
...do something else...<br />
ENDIF(WIN32)<br />
<br />
You might think that the ELSE section, here containing "...do something else...", is for the WIN32 portion of the script. That is not so! It is actually handling the NOT WIN32 section.<br />
<br />
As of CMake 2.6.0 the ELSE() and ENDIF() constructs can be empty. The same is true for closing constructs on ENDMACRO(), ENDFUNCTION(), and ENDFOREACH(). If you require 2.4.x compatibility, you can enable the CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS option on CMake 2.4.3 or greater. This option is superfluous on CMake 2.6.0 or greater.<br />
<br />
SET(CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS true)<br />
<br />
IF(WIN32)<br />
...do something...<br />
ELSEIF(APPLE)<br />
...do something else...<br />
ELSE()<br />
...do something else...<br />
ENDIF()<br />
<br />
=== Which regular expressions are supported by CMake? ===<br />
When using MATCHES or MATCHALL in an IF command, or using any of the STRING(REGEX ...) commands, CMake expects regular expressions, not globs (wild cards). CMake uses the same regular expression engine above all platforms. Here are the meanings of the metacharacters:<br />
<br />
^ Matches at beginning of a line<br />
$ Matches at end of a line<br />
. Matches any single character<br />
[ ] Matches any character(s) inside the brackets<br />
[^ ] Matches any character(s) not inside the brackets<br />
- Matches any character in range on either side of a dash<br />
| Matches a pattern on either side of the |<br />
* Matches preceding pattern zero or more times<br />
+ Matches preceding pattern one or more times<br />
? Matches preceding pattern zero or once only<br />
() Saves a matched expression and uses it in a later match<br />
<br />
Example: "[-][L]([^ ;])+" matches all strings beginning with -L and ending with a space or a semicolon, the usual linkdirs under Linux.<br />
<br />
Here is how to catch a part of a string. The variable test is filled with some content, and then we want to catch the "me":<br />
<br />
SET(test "hello world ! catch: me if you can")<br />
STRING(REGEX REPLACE ".*catch: ([^ ]+).*" "\\1" result "${test}" )<br />
MESSAGE(STATUS "result= ${result}")<br />
<br />
This is slightly tricky. The part inside the brackets is available in \\1 . CMake will copy the variable test to the variable result, but then it will replace everything that the regular expression matches with \\1. This means the first regular expression has to match the whole string and the part we want to catch has to be put in parens.<br />
<br />
-- result= me<br />
<br />
For those of you who know Perl, the equivalent Perl code could be:<br />
<br />
$test = "hello world ! catch: me if you can";<br />
$result = $test;<br />
$result =~ s/.*catch: ([^ ]+).*/$1/;<br />
print "-- result= $result\n";<br />
<br />
There are other ways to do this in Perl, but this is how we do it in CMake because \\1 does not become a variable like $1 does in perl, so there is no SET(result ${\\1}) in CMake.<br />
<br />
<br />
=== How to convert a semicolon separated list to a whitespace separated string? ===<br />
<br />
set(foo<br />
abc.c<br />
abc.b<br />
abc.a<br />
)<br />
<br />
foreach(arg ${foo})<br />
set(bar "${bar} ${arg}")<br />
endforeach(arg ${foo})<br />
<br />
message("foo: ${foo}")<br />
message("bar: ${bar}")<br />
<br />
=== How can I build multiple modes without switching ? ===<br />
To build multiple modes (e.g. Debug and Release) in one shot without constantly running cmake -DCMAKE_BUILD_TYPE=Debug and cmake -DCMAKE_BUILD_TYPE=Release in source tree create a directory for builds eg.:<br />
<br />
<pre><br />
Project-directory/<br />
/Build<br />
</pre><br />
<br />
Inside you can place as many target directories for out-of-source build modes as you want, e.g.:<br />
<br />
<pre><br />
Project-directory/<br />
/Build<br />
/Debug<br />
/Release<br />
</pre><br />
<br />
In each of these directories issue a command (assuming that you have CMakeLists.txt directly in Project-directory)<br />
<br />
<pre><br />
cmake -DCMAKE_BUILD_TYPE=type_of_build ../../<br />
</pre><br />
<br />
to create a cmake cache configured for requested build type.<br />
<br />
Now you can make each build just by entering appropriate directory and executing a make command.<br />
<br />
=== How can I extend the build modes with a custom made one ? ===<br />
The following code snipet (taken from a CMakeLists.txt) adds a Maintainer mode:<br />
<pre><br />
SET( CMAKE_CXX_FLAGS_MAINTAINER "-Wall -Wabi" CACHE STRING<br />
"Flags used by the C++ compiler during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_C_FLAGS_MAINTAINER "-Wall -pedantic" CACHE STRING<br />
"Flags used by the C compiler during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_EXE_LINKER_FLAGS_MAINTAINER<br />
"-Wl,--warn-unresolved-symbols,--warn-once" CACHE STRING<br />
"Flags used for linking binaries during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_SHARED_LINKER_FLAGS_MAINTAINER<br />
"-Wl,--warn-unresolved-symbols,--warn-once" CACHE STRING<br />
"Flags used by the shared libraries linker during maintainer builds."<br />
FORCE )<br />
MARK_AS_ADVANCED(<br />
CMAKE_CXX_FLAGS_MAINTAINER<br />
CMAKE_C_FLAGS_MAINTAINER<br />
CMAKE_EXE_LINKER_FLAGS_MAINTAINER<br />
CMAKE_SHARED_LINKER_FLAGS_MAINTAINER )<br />
# Update the documentation string of CMAKE_BUILD_TYPE for GUIs<br />
SET( CMAKE_BUILD_TYPE "" CACHE STRING<br />
"Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel Maintainer."<br />
FORCE )<br />
</pre><br />
Notes: The flags used in this example are specific to GCC. Change them as needed for your project. Additionally the SET(CMAKE_BUILD_TYPE) command will override<br />
a CMAKE_BUILD_TYPE previously set in the CMakeLists.txt.<br />
<br />
=== Why does <code>foreach</code> skip empty values? ===<br />
<br />
The code in question is of the form<br />
<br />
set(var "a;b;;c;d") # list 'a', 'b', '', 'c', 'd'<br />
foreach(v ${var})<br />
# v=a, v=b, v=c, v=d, one at a time<br />
endforeach()<br />
<br />
and the loop variable 'v' never attains the empty-string value ''.<br />
This is because the <code>${var}</code> syntax is an unquoted argument so the CMake language expands the list and removes the empty value.<br />
The foreach command does not even see the empty value.<br />
One can verify this because the code<br />
<br />
foreach(v a b "" c d)<br />
...<br />
endforeach()<br />
<br />
will see the empty value.<br />
<br />
=== Does CMake support precompiled headers? ===<br />
<br />
Yes and no. Every platform does precompiled headers a bit differently, and there is currently no first-class interface provided by CMake and implemented on every platform.<br />
However, CMake does provide enough primitives for projects to use precompiled headers on specific platforms.<br />
Our issue tracker has a [http://www.cmake.org/Bug/view.php?id=1260 feature request] with attachements providing user-contributed helper macros for some platforms.<br />
<br />
== Writing FindXXX.cmake files ==<br />
<br />
=== What are the rules to write a FindXXX.cmake file? ===<br />
<br />
Let's follow the instructions and the advices in the <br />
Modules/readme.txt [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/readme.txt?root=CMake&view=markup]<br />
file located in the CVS repository.<br />
<br />
=== Why does find_library look in system directories before its PATHS option? ===<br />
<br />
The code in question is often of the form<br />
<br />
find_library(FOO_LIBRARY NAMES foo PATHS /opt/foo/lib)<br />
<br />
CMake will find "<code>/usr/lib/libfoo.so</code>" instead of "<code>/opt/foo/lib/libfoo.so</code>" if both exist.<br />
The reason is that /opt/foo/lib is a <i>hard-coded guess</i> of the location.<br />
The documentation of <code>[http://www.cmake.org/cmake/help/cmake2.6docs.html#command:find_library find_library]</code> specifies the search order.<br />
User, project, and system configuration variables are always more local than hard-coded guesses and should override them, so<br />
the PATHS option is used last.<br />
<br />
Some find-modules compute probable locations based on other information <i>available from the system</i> such as a project-specific environment variable.<br />
The HINTS option (CMake 2.6 and higher) takes precedence over system directories specifically for this case:<br />
<br />
file(TO_CMAKE_PATH "$ENV{FOO_LIB_DIR}" FOO_LIB_DIR)<br />
find_library(FOO_LIBRARY NAMES foo HINTS ${FOO_LIB_DIR})<br />
<br />
CMake will find "<code>$ENV{FOO_LIB_DIR}/libfoo.so</code>" before "<code>/usr/lib/libfoo.so</code>".<br />
<br />
== Finding and using external packages ==<br />
<br />
=== How do I use CMake to generate SWIG wrapper libraries? ===<br />
<br />
CMake version 2 includes a module that supports the generation of SWIG wrapper libraries. The SWIG package defines the following macros: SWIG_ADD_MODULE and SWIG_LINK_LIBRARIES.<br />
<br />
<pre><br />
# This example shows how to use python<br />
# Currently these languages have been tested:<br />
# perl tcl ruby php4 pike<br />
<br />
FIND_PACKAGE(SWIG REQUIRED)<br />
INCLUDE(${SWIG_USE_FILE})<br />
<br />
FIND_PACKAGE(PythonLibs)<br />
INCLUDE_DIRECTORIES(${PYTHON_INCLUDE_PATH})<br />
<br />
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})<br />
<br />
SET(CMAKE_SWIG_FLAGS "")<br />
<br />
SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES CPLUSPLUS ON)<br />
SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES SWIG_FLAGS "-includeall")<br />
SWIG_ADD_MODULE(example python<br />
example.i example.cxx)<br />
SWIG_LINK_LIBRARIES(example ${PYTHON_LIBRARIES})<br />
<br />
</pre><br />
<br />
<pre><br />
# This example shows how to use tcl<br />
PROJECT(TCL_WRAP)<br />
SET ( MODULE_NAME project )<br />
SET ( INTERFACE_FILES project.i)<br />
SET ( SRC_FILES Vertex.h Vertex.cxx Shapes.h Shapes.cxx )<br />
<br />
FIND_PACKAGE(SWIG REQUIRED)<br />
INCLUDE(${SWIG_USE_FILE})<br />
<br />
# Look for TCL<br />
INCLUDE_DIRECTORIES(${TCL_INCLUDE_PATH})<br />
<br />
FIND_LIBRARY(TCL_LIBRARY NAMES tcl tcl84 tcl83 tcl82 tcl80<br />
PATHS /usr/lib /usr/local/lib)<br />
IF (TCL_LIBRARY)<br />
TARGET_ADD_LIBRARY (${MODULE_NAME} TCL_LIBRARY)<br />
ENDIF (TCL_LIBRARY)<br />
<br />
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})<br />
<br />
SET(CMAKE_SWIG_FLAGS "-c++")<br />
<br />
SET_SOURCE_FILES_PROPERTIES(${INTERFACE_FILES} PROPERTIES CPLUSPLUS ON)<br />
SET_SOURCE_FILES_PROPERTIES(${INTERFACE_FILES} PROPERTIES CMAKE_SWIG_FLAGS "-includeall")<br />
SWIG_ADD_MODULE(${MODULE_NAME} tcl ${INTERFACE_FILES} ${SRC_FILES})<br />
SWIG_LINK_LIBRARIES(${MODULE_NAME} ${TCL_LIBRARIES})<br />
</pre><br />
<br />
=== How do I use CMake to build LaTeX documents? ===<br />
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.<br />
<br />
PROJECT(Document)<br />
IF(LATEX_COMPILE)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${Document_BINARY_DIR}/TDocument.dvi<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.tex<br />
COMMAND ${LATEX_COMPILE} <br />
ARGS ${Document_SOURCE_DIR}/TDocument.tex <br />
)<br />
ENDIF(LATEX_COMPILE)<br />
<br />
IF(DVIPDF_COMPILE)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${Document_BINARY_DIR}/TDocument.pdf<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.dvi <br />
COMMAND ${DVIPDF_COMPILE}<br />
ARGS ${Document_SOURCE_DIR}/TDocument.dvi<br />
)<br />
ENDIF(DVIPDF_COMPILE)<br />
<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.pdf<br />
)<br />
<br />
The following uses commands in CMake version 2.0 and later<br />
<br />
PROJECT(Document)<br />
# <br />
# Find LaTeX<br />
#<br />
FIND_PACKAGE(LATEX)<br />
<br />
IF(LATEX_COMPILER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.dvi<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS ${Document_SOURCE_DIR}/TDocument.tex<br />
DEPENDS ${Document_SOURCE_DIR}/TDocument.tex<br />
COMMENT "Tex2dvi"<br />
)<br />
<br />
IF(DVIPS_CONVERTER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.ps<br />
COMMAND ${DVIPS_CONVERTER}<br />
ARGS ${Document_BINARY_DIR}/TDocument.dvi<br />
-o ${Document_BINARY_DIR}/TDocument.ps<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.dvi<br />
COMMENT "dvi2ps"<br />
)<br />
<br />
IF(PS2PDF_CONVERTER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.pdf<br />
COMMAND ${PS2PDF_CONVERTER}<br />
ARGS ${Document_BINARY_DIR}/TDocument.ps<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.ps<br />
COMMENT "ps2pdf"<br />
)<br />
<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.pdf<br />
)<br />
ENDIF(PS2PDF_CONVERTER)<br />
ENDIF(DVIPS_CONVERTER)<br />
ENDIF(LATEX_COMPILER)<br />
<br />
=== How do I get LaTeX references to be correct? ===<br />
When your latex document contains references (e.g. \ref{...} command) you get to run two passes of latex. In the<br />
most general case, i.e. when additionally your document uses a bibtex bibliography, you shall need three<br />
passes of latex (and one pass of bibtex):<br />
# latex (first pass: for bibtex to have an .aux file)<br />
# bibtex (for generating the .bbl file)<br />
# latex (second pass)<br />
# latex (third pass)<br />
<br />
The following code snippet illustrates how you can "pervert" the bibtex and latex generated<br />
auxilary files (.aux, .log, .dvi, .bbl...) to create an "artificial" set of CMake dependencies.<br />
The side-effect of those dependencies should hopefully be the above described sequence of calls<br />
to latex and bibtex<br />
<pre><br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.aux<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/UsersManual.tex<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (first pass)"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.aux<br />
COMMAND ${BIBTEX_COMPILER}<br />
ARGS -terse ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Bibtex"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.dvi<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (second pass)"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.log<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
${CMAKE_CURRENT_BINARY_DIR}/UsersManual.dvi<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (third pass)"<br />
)<br />
# Eventually trigger the whole process<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.log<br />
)<br />
</pre><br />
<br />
=== How can I set TEXINPUTS for a LaTeX compilation? ===<br />
First note that most often you can avoid using TEXINPUTS by copying all the necessary files (.tex source file and<br />
included graphic files e.g. .eps files) from your PROJECT_SOURCE_DIR hirarchy to your PROJECT_BINARY_DIR subdir<br />
[refer to CONFIGURE_FILE with the COPYONLY flag set for copying files]. Since by default latex uses the current working directory as value for TEXINPUTS you should be all set. As expected, this trick is quick AND dirty since your<br />
concerned PROJECT_BINARY_DIR subdir now contains files that are NOT generated by CMake (in the sense that those<br />
files are not the result of a system command but were merely duplicated)... <br />
<br />
If you consider it is cleaner or easier to define a TEXINPUTS environment variable [the latex command probably<br />
misses a -I flag] you can find an example in the InsightDocuments cvs archive (refer to the section "cvs access"<br />
near the bottom of Kitware's ITK download page) or use google with keywords "ITK_TEXINPUTS CONFIGURE_FILE".<br />
Look at InsightDocuments/CourseWare/Training/Vis2003/Latex/CMakeLists.txt and search for e.g. "LaTeXWrapper.sh.in".<br />
<br />
Roughly the mechanism goes:<br />
* SET ITK_TEXINPUTS with the desired TEXINPUTS<br />
* CONFIGURE_FILE "InsightDocuments/CourseWare/Training/Vis2003/LaTeXWrapper.sh.in" which generates an sh shell script setting the shell variable TEXINPUTS prior to running the latex command<br />
* use ADD_CUSTOM_COMMAND to invoke this shell script<br />
This very example is Win32 portable (except that LaTeXWrapper.bat.in generates a .bat shell script)<br />
<br />
== Library questions ==<br />
<br />
=== Can I build both shared and static libraries with one ADD_LIBRARY command? ===<br />
<br />
No. Each library you build must have a unique target name, i.e. the "libname" field of the ADD_LIBRARY command. That way, CMake can track dependencies separately for each library. Libraries can have the same OUTPUT_NAME, see the SET_TARGET_PROPERTIES command, but this is not the default.<br />
<br />
=== Does that mean I have to build all my library objects twice, once for shared and once for static?! I don't like that! ===<br />
<br />
In practice, most libraries have different defines and compiler flags for the shared vs. static cases. So you would have to build all your library objects twice anyways. However, if you happen to have '''''exactly''''' the same defines and compiler flags for the shared vs. static cases...<br />
<br />
...if you're using Linux and a GCC-style linker, you could do the following. Note that for this to work correctly on linux, the zzSTATIC source files should have been compiled with "-fPIC" to ensure they will work in a shared library.<br />
<br />
IF(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_COMPILER_IS_GNUCC)<br />
ADD_LIBRARY(zzSTATIC STATIC -fPIC)<br />
ADD_LIBRARY(zzDYNAMIC SHARED)<br />
TARGET_LINK_LIBRARIES(zzDYNAMIC -Wl,-whole-archive zzSTATIC -Wl,-no-whole-archive)<br />
ENDIF(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_COMPILER_IS_GNUCC)<br />
<br />
...if you want a cross-platform approach that works on all compilers, not just GCC or Linux, you could extract the locations of previously built object files and insert them directly into the libraries that need them. This is documented in [http://www.cmake.org/Bug/view.php?id=5155 CMake Feature Request #5155: standard way to locate object files]. Unfortunately this approach relies on CMake's internal implementation, and that implementation could change in the future, breaking your code.<br />
<br />
=== How do I make my shared and static libraries have the same root name, but different suffixes? ===<br />
Set the OUTPUT_NAME of your shared and static libraries to the same thing.<br />
<br />
ADD_LIBRARY(foo SHARED ${foo_sources})<br />
ADD_LIBRARY(foo-static STATIC ${foo_sources})<br />
// The library target "foo" already has a default OUTPUT_NAME of "foo", so we don't need to change it.<br />
// The library target "foo-static" has a default OUTPUT_NAME of "foo-static", so change it.<br />
SET_TARGET_PROPERTIES(foo-static PROPERTIES OUTPUT_NAME "foo")<br />
<br />
If you are building your shared and static libraries in the same directory, you will also need the following to keep your shared and static libraries from clobbering each other during the build.<br />
<br />
SET_TARGET_PROPERTIES(foo PROPERTIES CLEAN_DIRECT_OUTPUT 1)<br />
SET_TARGET_PROPERTIES(foo-static PROPERTIES CLEAN_DIRECT_OUTPUT 1)<br />
<br />
=== How do I rename a library after it has already been built? ===<br />
You don't rename it. It's been built! Its name is whatever CMakeLists.txt says it's supposed to be.<br />
<br />
Perhaps you want to copy the library to a different name. But, are you sure that's what you want to do? You could just change the name in your ADD_LIBRARY command or change its OUTPUT_NAME property using SET_TARGET_PROPERTY(). If you really really want to copy the library to a different name, try:<br />
<br />
GET_TARGET_PROPERTY(LIB_NAME Foo LOCATION)<br />
GET_TARGET_PROPERTY(Bar_prefix Foo PREFIX)<br />
GET_TARGET_PROPERTY(Bar_suffix Foo SUFFIX)<br />
SET(NEW_LIB_NAME ${Bar_prefix}Bar${Bar_suffix})<br />
<br />
ADD_CUSTOM_COMMAND(<br />
TARGET Foo<br />
POST_BUILD<br />
COMMAND ${CMAKE_COMMAND} -E copy ${LIB_NAME} ${NEW_LIB_NAME}<br />
)<br />
<br />
On Windows you may also want to copy the .dll import lib, using the same approach as above, but with IMPORT_PREFIX and IMPORT_SUFFIX. ''Problem: LOCATION only refers to 1 file, the .dll. What is a simple way to get the location of the import lib? Could provide a complicated way, but that's annoying.''<br />
<br />
=== Does CMake support "convenience" libraries? ===<br />
No. CMake does not currently support convenience libraries. A "convenience" library, as GNU libtool calls it, is an archive of objects to be mixed into other libraries. Other libraries "link" to the convenience library, but the convenience library does not export any symbols; GNU libtool never installs the convenience library; no programs ever link to the convenience library.<br />
<br />
This does '''not''' mean that a project using convenience libraries cannot be converted to CMake. Instead the source files may be listed in each target that needs them. They will be built for each target separately using all the preprocessor definitions and flags configured for that target.<br />
<br />
=== Why are libraries linked to my shared library included when something links to it? ===<br />
This question arises when one has a library B which links to some library A. When a third target, say C, links to B, CMake will automatically include C to A also. When the libraries are static, then this is always necessary. When the libraries are shared, this is the default behavior provided by CMake. CMake 2.6 and above provide the target property "LINK_INTERFACE_LIBRARIES" (http://www.cmake.org/HTML/cmake-2.6.html#prop_tgt:LINK_INTERFACE_LIBRARIES) to specify the libraries that should be transitively included in the link by CMake. CMake 2.4 and below do not support the property.<br />
<br />
Something like the following will work in CMake 2.6:<br />
<br />
<pre><br />
set_target_properties(mylibrary<br />
PROPERTIES<br />
LINK_INTERFACE_LIBRARIES ""<br />
)<br />
</pre><br />
<br />
=== CMake dependency scanner ===<br />
<br />
CMake does not preprocess source files while scanning dependencies. Code like<br />
<pre><br />
#if 0<br />
# include "bla.h"<br />
#endif<br />
</pre><br />
will result in a dependency on "bla.h". This sometimes leads to source files recompiling unnecessarily but will not break the build.<br />
<br />
== Installation questions ==<br />
<br />
=== Does CMake's "make install" support DESTDIR? ===<br />
'''Yes''', especially when the build-system generator uses CMake's builtin support for installing files: Simply define the DESTDIR environment variable during installation and CMake will treat that value as the root of the file system for all installation paths; naturally, the DESTDIR path must be absolute.<br />
<br />
For example, if the Makefile generator is used, then all of the following are example usages of DESTDIR (perhaps assuming the bash shell for the last 2):<br />
<br />
(1) make install DESTDIR="/some/absolute/path"<br />
(2) make DESTDIR="/some/absolute/path" install<br />
(3) DESTDIR="/some/absolute/path" make install<br />
(4) export DESTDIR="/some/absolute/path<br />
make install<br />
<br />
=== Can I do "make uninstall" with CMake?===<br />
By default, CMake does not provide the "make uninstall" target, so you cannot do this. We do not want "make uninstall" to remove useful files from the system.<br />
<br />
If you want an "uninstall" target in your project, then nobody prevents you from providing one. You need to delete the files listed in install_manifest.txt file. Here is how to do it. First create file cmake_uninstall.cmake.in in the top-level directory of the project:<br />
<br />
<pre><br />
IF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")<br />
MESSAGE(FATAL_ERROR "Cannot find install manifest: \"@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt\"")<br />
ENDIF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")<br />
<br />
FILE(READ "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt" files)<br />
STRING(REGEX REPLACE "\n" ";" files "${files}")<br />
FOREACH(file ${files})<br />
MESSAGE(STATUS "Uninstalling \"$ENV{DESTDIR}${file}\"")<br />
IF(EXISTS "$ENV{DESTDIR}${file}")<br />
EXEC_PROGRAM(<br />
"@CMAKE_COMMAND@" ARGS "-E remove \"$ENV{DESTDIR}${file}\""<br />
OUTPUT_VARIABLE rm_out<br />
RETURN_VALUE rm_retval<br />
)<br />
IF(NOT "${rm_retval}" STREQUAL 0)<br />
MESSAGE(FATAL_ERROR "Problem when removing \"$ENV{DESTDIR}${file}\"")<br />
ENDIF(NOT "${rm_retval}" STREQUAL 0)<br />
ELSE(EXISTS "$ENV{DESTDIR}${file}")<br />
MESSAGE(STATUS "File \"$ENV{DESTDIR}${file}\" does not exist.")<br />
ENDIF(EXISTS "$ENV{DESTDIR}${file}")<br />
ENDFOREACH(file)<br />
</pre><br />
<br />
Then in the top-level CMakeLists.txt add the following logic:<br />
<br />
<pre><br />
CONFIGURE_FILE(<br />
"${CMAKE_CURRENT_SOURCE_DIR}/cmake_uninstall.cmake.in"<br />
"${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake"<br />
IMMEDIATE @ONLY)<br />
<br />
ADD_CUSTOM_TARGET(uninstall<br />
"${CMAKE_COMMAND}" -P "${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake")<br />
</pre><br />
<br />
Now you will have an "uninstall" target at the top-level directory of your build tree.<br />
<br />
Instead of creating an "uninstall" target, Unix users could enter this command in the shell:<br />
<br />
xargs rm < install_manifest.txt<br />
<br />
== Distribution questions ==<br />
<br />
=== Where is "make dist"? ===<br />
<br />
CMake doesn't create a "make dist" target.<br />
<br />
=== What is the best way to distribute source code or binaries for a cmake-based project? ===<br />
<br />
For creating source or binary packages there is now [[CMake#CPack | CPack]] coming with CMake, see the <br />
[[ CMake#CPack | documentation]].<br />
<br />
Of course you can also use any other ways to create packages.<br />
<br />
== Platform-specific questions ==<br />
=== How do I build universal binaries on Mac OS X? ===<br />
Before running CMake with an empty build tree, set the CMAKE_OSX_ARCHITECTURES environment variable. It should be set to contain a ; separated list of architectures that you want in the binary. For example, for 32-bit PowerPC and Intel you would do this:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386<br />
<br />
If you wish to build both as 32 and 64 bit, do this:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386;ppc64;x86_64<br />
<br />
You can also set the same named CMake cache variable on an existing binary tree. This works with both makefiles and the Xcode generator. <br />
<br />
In addition, you can also set the CMAKE_OSX_SYSROOT variable to point to the sysroot (aka Mac OS SDK) to be used. CMake will attempt to pick one on your system, but it can be changed in the cache or via an environment variable before running CMake. The 10.4u SDK or later must be used to create a Universal Binary.<br />
<br />
Universal Binaries are essentially cross compilation and so you should avoid using TRY_RUN, especially for things like testing endianess or variable size because the result will only be correct for one architecture.<br />
<br />
Lastly, note that CTest is only able to test one architecture. See bug 6157.<br />
<br />
=== How can I apply resources on Mac OS X automatically? ===<br />
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 a custom rule which is executed after the executable is linked:<br />
<br />
<pre><br />
ADD_EXECUTABLE(MyExecutable ${MyExecutable_SRCS})<br />
GET_TARGET_PROPERTY(MyExecutable_PATH MyExecutable LOCATION)<br />
<br />
IF(APPLE)<br />
FIND_PROGRAM(APPLE_RESOURCE Rez /Developer/Tools)<br />
IF(APPLE_RESOURCE)<br />
ADD_CUSTOM_COMMAND(TARGET MyExecutable POST_BUILD<br />
COMMAND ${APPLE_RESOURCE} Carbon.r -o ${MyExecutable_PATH})<br />
ENDIF(APPLE_RESOURCE)<br />
ENDIF(APPLE)<br />
</pre><br />
<br />
This will execute:<br />
<br />
/Developer/Tools/Rez Carbon.r -o /binary/path/MyExecutable<br />
<br />
after MyExecutable is linked.<br />
<br />
'Rez' may be located elsewhere on disk, depending on the version of Mac OS X and Xcode. You can use 'which Rez' in Terminal to find it's full path.<br />
<br />
=== Why does FIND_LIBRARY not find .DLL libraries under WIN32? ===<br />
For those who come from a Unix background to MS Windows:<br />
<br />
You never link directly to the .dll, you have to link against the import library .lib for the .dll.<br />
<br />
Linking against dynamic libraries (.dll under Windows) is quite different from linking against ELF shared objects (.so) under platforms like Linux or NetBSD. In Windows, there are two types of library, a static library and an import library (both confusingly use the .lib extension, however). In Windows, when you build an import library (A.lib) you will get a corresponding (A.dll) that you only need at runtime. At compile time you will need the import library.<br />
<br />
Conclusion: There is no need to find a .dll for linking. You only need to find the .lib import library.<br />
<br />
Some more details can be found here: [http://xenophilia.org/winvunix.html].<br />
<br />
=== Why am I getting a linker error to _mainCRTStartup under WIN32? ===<br />
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.<br />
<br />
ADD_EXECUTABLE(exename WIN32 source1 source2 ... sourceN)<br />
<br />
The second argument to ADD_EXECUTABLE can be WIN32. This indicates that the executable, when compiled on Windows, is a Windows app (using WinMain) and not a console app (using main). Please note that on Unix platforms, CMake ignores the WIN32 and the compiler will use "main" in any case.<br />
<br />
=== Why do I get this error: nafxcwd.lib(appcore.obj) : error LNK2001: unresolved external symbol ___argv ===<br />
<br />
This is because the application is using both the static and dll versions of the MFC library.<br />
To fix the problem, you can do the following:<br />
<br />
SET(CMAKE_MFC_FLAG 2) # force the IDE to use static MFC<br />
ADD_DEFINITIONS(-D_AFXDLL) # make sure if afx.h is included the dll MFC is used<br />
<br />
=== How to use MFC with CMake ===<br />
To use MFC, the CMAKE_MFC_FLAG variable must be set as follows:<br />
<br />
0: Use Standard Windows Libraries<br />
1: Use MFC in a Static Library<br />
2: Use MFC in a Shared DLL <br />
<br />
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:<br />
<br />
ADD_DEFINITIONS(-D_AFXDLL)<br />
SET(CMAKE_MFC_FLAG 2) <br />
ADD_EXECUTABLE(CMakeSetup WIN32 ${SRCS})<br />
<br />
Note that visual studio 9 project files do not appear to work with CMAKE_MFC_FLAG 1; this may be related to [http://www.cmake.org/Bug/view.php?id=7056 bug 7056].<br />
<br />
In order to use MFC with UNICODE, you must also [http://msdn.microsoft.com/en-us/library/dybsewaf.aspx specify the entry point wWinMainCRTStartup]. For example:<br />
<br />
set(CMAKE_MFC_FLAG 2)<br />
set_target_properties(MyApp PROPERTIES<br />
COMPILE_DEFINITIONS _AFXDLL,_UNICODE,UNICODE,_BIND_TO_CURRENT_CRT_VERSION,_BIND_TO_CURRENT_MFC_VERSION<br />
LINK_FLAGS "/ENTRY:\"wWinMainCRTStartup\"")<br />
<br />
See [http://stackoverflow.com/questions/59635/app-does-not-run-with-vs-2008-sp1-dlls-previous-version-works-with-rtm-versions this article] as to why _BIND_TO_CURRENT_CRT_VERSION and _BIND_TO_CURRENT_MFC_VERSION are necessary for Visual Studio 2008 SP1.<br />
<br />
=== How To Put Files in Folders in Visual Studio Projects ===<br />
The Visual Studio IDE supports putting files into folders.<br />
CMake can be used to put files in folders with the SOURCE_GROUP <br />
command. <br />
<br />
SOURCE_GROUP(name [REGULAR_EXPRESSION regex] [FILES src1 src2 ...])<br />
<br />
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 provided the source file is being passed to ADD_EXECUTABLE or ADD_LIBRARY.<br />
<br />
For example:<br />
SOURCE_GROUP(FooFiles FILES foo.cxx)<br />
SOURCE_GROUP(BarFiles FILES bar.cxx)<br />
ADD_LIBRARY(foo foo.cxx bar.cxx)<br />
<br />
In the event 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).<br />
<br />
As a convenience to developers CMake automatically adds standard header files to a "Header Files" folder and standard source files to a "Source Files" folder for Visual Studio Projects. This can be overridden via the SOURCE_GROUP method documented above.<br />
<br />
=== How to create Visual Studio 6 Projects that contain only a single build type===<br />
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:<br />
<br />
# Create a directory in which you copy the files *.dsptemplate and CMakeVisualStudio6Configurations.cmake from CMake's Templates directory.<br />
# Edit the .cmake file and change the SET(CMAKE_CONFIGURATION_TYPES ...) line to set the build types that you want in your set.<br />
# Edit the *Header.dsptemplate files to contain only the configuration types you want in your set.<br />
# In your CMakeLists.txt file, set the MSPROJECT_TEMPLATE_DIRECTORY to the directory that you created.<br />
<br />
<br />
That's it. Run CMake and your new configuration files will be created.<br />
<br />
Note: Editing the *Header.dsptemplates files should be done very carefully. Here are some guidelines:<br />
<br />
- 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"')<br />
- 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.<br />
- 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.<br />
<br />
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:<br />
# PROP BASE Output_Dir ""<br />
# PROP BASE Intermediate_Dir ""<br />
# PROP Intermediate_Dir ""<br />
# PROP Output_Dir "LIBRARY_OUTPUT_PATH"<br />
or<br />
# PROP Output_Dir "EXECUTABLE_OUTPUT_PATH"<br />
<br />
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).<br />
<br />
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.<br />
<br />
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.)<br />
<br />
=== Can CMake set the Debugging/Working Directory property in Visual Studio projects? ===<br />
<br />
No. The value of this property is not stored in the project files. It is stored in extra files created by the IDE when a solution is loaded (VS .NET 2003 uses a hidden .suo file next to the .sln solution file). The format of these files is not known to CMake and cannot be generated. In some versions of VS the files are binary and not human readable.<br />
<br />
=== Why does CMakeSetup with the message "LINK : fatal error LNK1104: cannot open file 'user32.lib'" while configuring a project? ===<br />
<br />
The path to the SDK libs (user32.lib) must be added by the IDE when the<br />
project generator "Visual Studio 8 2005" is used, because cmake uses<br />
VCExpress.exe and on the fly generated project files to check<br />
for compiling (VCExpress.exe reads some config files for the<br />
compiler/linker options)<br />
<br />
So add the sdk lib path (...\Microsoft Platform SDK\Lib) at Tools->Options->Projects and Solutions->VC++ Directories->Library files<br />
<br />
See also:<br />
*http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/<br />
<br />
=== How can I avoid the error "Arg list too long" when running make? ===<br />
This error is sometimes encountered when building a static library with many object files using Unix make command. It typically looks something like this:<br />
<br />
<pre><br />
gmake[2]: execvp: /bin/sh: Arg list too long<br />
</pre><br />
<br />
When make tries to run the archiver program to build the static library the shell it uses complains that the argument list is too long. In some shells this can be fixed by setting an environment variable such as <tt>ARG_MAX</tt> to extend the length of the command line it will allow.<br />
<br />
=== How can I find out platforms definitions, search paths, etc. from gcc ?===<br />
<br />
The following is really the best if not only way to get information about predefined macros with a GNU compiler:<br />
<pre><br />
$ touch empty.c<br />
$ gcc -v -dD -E empty.c <br />
</pre><br />
This will give you all you might want to know about the preprocessor, the builtin include search dirs and all<br />
predefined definitions, so you can check whether it's __LINUX or _LINUX_ or _APPLE_ or __APPLE etc. <br />
The empty file and all these parameters are really required. You probably want to pipe the output (both stdout and stderr) to a file.<br />
If you want the information for C++, use a C++ file suffix for the empty file.<br />
<br />
This is how you can get the builtin library search paths:<br />
<pre><br />
$ gcc --print-search-dirs<br />
</pre><br />
<br />
=== How can I get a windows registry key ?===<br />
<br />
The only thing to know is that you can't use just the "SET" command in place of "GET" command.<br />
CMake read the value from the registry only when you "get" it from the cache. For instance :<br />
<br />
<pre><br />
GET_FILENAME_COMPONENT(SDK_ROOT_PATH "[HKEY_LOCAL_MACHINE\\SOFTWARE\\PACKAGE;Install_Dir]" ABSOLUTE CACHE)<br />
</pre><br />
<br />
If a key name (ex: Install_Dir in this case) was not specified , the Default key value will be get.<br />
Now you could use the SDK_ROOT_PATH to add include and lib path to your project :<br />
<br />
<pre><br />
INCLUDE_DIRECTORIES(<br />
${SDK_ROOT_PATH}/include<br />
)<br />
<br />
LINK_DIRECTORIES(<br />
${SDK_ROOT_PATH}/lib<br />
)<br />
</pre><br />
<br />
You can also read a registry key in the PATHS section of a FIND_LIBRARY, FIND_PATH, FIND_PROGRAM, or FIND_FILE command<br />
FIND_FILE(BOOT_DOT_INI boot.ini PATHS [HKEY_CURRENT_USER\\Environment;HOMEDRIVE])<br />
<br />
For other examples have a look in the CMake Modules folder :<br />
- FindJava.cmake<br />
- FindPythonLibs.cmake<br />
- ..<br />
<br />
=== How can I build my MSVC application with a static runtime? ===<br />
<br />
Here are two options you could employ to compile your MSVC application with /MT instead of /MD.<br />
<br />
==== Manual Replace ====<br />
<br />
You can rely on the user to modify CMAKE_C_FLAGS_DEBUG, CMAKE_C_FLAGS_RELEASE, CMAKE_CXX_FLAGS_DEBUG, CMAKE_CXX_FLAGS_RELEASE, etc. within the cache editor, replacing /MD with /MT after an initial configure of your software.<br />
<br />
==== Make Override Files ====<br />
<br />
If you intend to build the entire source tree using /MT and you don't<br />
need this ever to be configurable via the CMake GUI, the best approach<br />
is to create an override file which initializes the starting cache<br />
values for the compile flags.<br />
<br />
First create a c_flag_overrides.cmake & cxx_flag_overrides.cmake file which<br />
contain something like this... (or whatever flags you wish to use per compiler).<br />
<br />
'''NOTE:''' These files are only evaluated on the first run of CMake so they can't be dependent on a CMake option() meant to be toggled from the GUI, for example. They could be dependent on a command line -D option or an environment variable if desired.<br />
<br />
c_flag_overrides.cmake<br />
if(MSVC)<br />
set(CMAKE_C_FLAGS_DEBUG_INIT "/D_DEBUG /MTd /Zi /Ob0 /Od /RTC1")<br />
set(CMAKE_C_FLAGS_MINSIZEREL_INIT "/MT /O1 /Ob1 /D NDEBUG")<br />
set(CMAKE_C_FLAGS_RELEASE_INIT "/MT /O2 /Ob2 /D NDEBUG")<br />
set(CMAKE_C_FLAGS_RELWITHDEBINFO_INIT "/MT /Zi /O2 /Ob1 /D NDEBUG")<br />
endif()<br />
<br />
cxx_flag_overrides.cmake<br />
if(MSVC)<br />
set(CMAKE_CXX_FLAGS_DEBUG_INIT "/D_DEBUG /MTd /Zi /Ob0 /Od /RTC1")<br />
set(CMAKE_CXX_FLAGS_MINSIZEREL_INIT "/MT /O1 /Ob1 /D NDEBUG")<br />
set(CMAKE_CXX_FLAGS_RELEASE_INIT "/MT /O2 /Ob2 /D NDEBUG")<br />
set(CMAKE_CXX_FLAGS_RELWITHDEBINFO_INIT "/MT /Zi /O2 /Ob1 /D NDEBUG")<br />
endif()<br />
<br />
Then enable them by setting the following variables prior to the project() command.<br />
<br />
set(CMAKE_USER_MAKE_RULES_OVERRIDE<br />
${CMAKE_CURRENT_SOURCE_DIR}/c_flag_overrides.cmake)<br />
set(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX<br />
${CMAKE_CURRENT_SOURCE_DIR}/cxx_flag_overrides.cmake)<br />
project(Bar)<br />
<br />
==== Dynamic Replace ====<br />
<br />
Alternatively, if you need dynamic control of /MT via some configure option you could use the following technique. Note: CMAKE_CXX_FLAGS_<FOO> is a directory level option, however. Also, this option has the downside of leaving /MD in the cache.<br />
<br />
foreach(flag_var<br />
CMAKE_CXX_FLAGS CMAKE_CXX_FLAGS_DEBUG CMAKE_CXX_FLAGS_RELEASE<br />
CMAKE_CXX_FLAGS_MINSIZEREL CMAKE_CXX_FLAGS_RELWITHDEBINFO)<br />
if(${flag_var} MATCHES "/MD")<br />
string(REGEX REPLACE "/MD" "/MT" ${flag_var} "${${flag_var}}")<br />
endif(${flag_var} MATCHES "/MD")<br />
endforeach(flag_var)<br />
<br />
<br />
{{CMake/Template/Footer}}</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake_FAQ&diff=16690CMake FAQ2009-10-07T04:53:30Z<p>Plowman: /* How can I build my MSVC application with a static runtime? */ document make override</p>
<hr />
<div>== General information and availability ==<br />
=== What is CMake? ===<br />
CMake is a cross-platform, open-source make system. CMake is used to control the software compilation process using simple platform-independent 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 http://www.cmake.org/HTML/About.html to learn more about CMake.<br />
<br />
=== What is the current release? ===<br />
The latest release of CMake is always available at: http://www.cmake.org/HTML/Download.html<br />
<br />
From there, you can fetch CMake binaries for Windows or several Unix variants, or you can download the source code of CMake.<br />
<br />
You can also access nightly development through CVS; see http://www.cmake.org/HTML/Download.html for more information. You may also browse the [http://www.cmake.org/cgi-bin/viewcvs.cgi/?root=CMake cvs repository online].<br />
<br />
=== I found a Bug! What should I do? ===<br />
Please report the bug in our bug tracker: http://www.cmake.org/Bug<br />
<br />
Please make sure to look at the old bugs not to include duplicates, include detailed instructions of the bug and how to reproduce it.<br />
<br />
=== I want a new feature in CMake. What should I do? ===<br />
Report a feature request in our Bug tracker http://www.cmake.org/Bug<br />
<br />
Please make sure to look at the old feature requests not to include duplicates, include detailed instructions of the feature and proposed implementation.<br />
<br />
=== What is the most recent version covered by the Mastering CMake book? ===<br />
A new edition of the [http://www.kitware.com/products/cmakebook.html Mastering CMake] book has been released which documents CMake 2.6.<br />
<br />
The following features have been added since printing the book:<br />
<br />
* New INSTALL command (cmake --help-command INSTALL)<br />
* New LIST command (cmake --help-command LIST)<br />
* Updated FIND_PATH, FIND_PROGRAM, and FIND_FILE commands to be more powerful (cmake --help-command FIND_PATH)<br />
* RPATH and Mac OS X install_name support (cmake --help-command SET_TARGET_PROPERTIES)<br />
* CPack Beta (not finished or documented)<br />
* EXECUTE_PROCESS was added and replaces EXEC_PROGRAM<br />
* Other changes have been bug fixes and internal CMake restructuring<br />
<br />
=== Where can I find searchable CMake Mailing Archives? ===<br />
There exists at list those ones:<br />
* [http://dir.gmane.org/gmane.comp.programming.tools.cmake.user cmake on Gmane]<br />
* [http://www.mail-archive.com/cmake@cmake.org/ http://www.mail-archive.com/cmake@cmake.org/]<br />
* [http://marc.info/?l=cmake http://marc.info/?l=cmake]<br />
* Use google ''site'' keyword in order to search directly in the CMake browsable ML:<br />
site:http://www.cmake.org/pipermail/cmake/ <search terms><br />
<br />
== Running CMake ==<br />
<br />
=== Is there an option to produce more 'verbose' compiling? ===<br />
Set CMAKE_VERBOSE_MAKEFILE to ON. This will make generator to produce all outputs, including compiler lines.<br />
<br />
If you are on Windows using Borland or NMake Makefiles, then you will see lines like:<br />
<br />
cl @c:\DOCUME~1\ANDY~1.KIT\LOCALS~1\Temp\nma03504<br />
<br />
The reason for this is that Borland and Microsoft Visual Studio make programs have limitation on the length of command strings. They overcome this limitation by writing arguments to the file and then pass file to the program.<br />
<br />
If you actually want to see what the command looks like, set CMAKE_START_TEMP_FILE and CMAKE_END_TEMP_FILE to "".<br />
<br />
On Makefile generators, there is a shortcut by setting Makefile variable VERBOSE to 1. For example on UNIX:<br />
<br />
make VERBOSE=1<br />
<br />
and Windows:<br />
nmake /S force silent mode, overrides (CMAKE_VERBOSE_MAKFILE)<br />
<br />
=== Is there a way to skip checking of dependent libraries when compiling? ===<br />
<br />
'''Using the Makefile Generator'''<br />
<br />
When using the Makefile generator under *nix you can append "/fast" to your target name. For example:<br />
<br />
make target_name/fast<br />
<br />
Under Windows use a backslash instead:<br />
<br />
make target_name\fast<br />
<br />
'''Using Visual Studio >= 7.1'''<br />
<br />
If you have Visual Studio .NET 7.1 or greater you can use the native option to right click on a project and choose to build just that project.<br />
<br />
'''Using Visual Studio <= 7.0'''<br />
<br />
CMake doesn't try to compile all dependent libraries when you compile a library but it will do so for binary targets. You can't avoid this however you can take advantage of CTRL+F7 to manually compile a source file for the affected target and then relink the target by right clicking on it and choosing Link. You'll have to ensure that all dependent libraries are made up-to-date however or suffer through Visual's slow check.<br />
<br />
=== I set a cmake variable in my environment, but it didn't change anything. Why? ===<br />
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.<br />
<br />
=== I change CMAKE_C_COMPILER in the GUI but it changes back on the next configure step. Why? ===<br />
Once a build tree is created with a given compiler it cannot be changed. There are a variety of implementation reasons for this policy. In order to choose a different compiler create a new build tree and set the CC and CXX environment variables to the compiler you want before running CMake.<br />
<br />
NOTE: While I don't know what the preferred method of doing it is, I do know that the advice above (to set CC and CXX env vars) is in direct conflict with advice somewhere else that says not to use env vars to control CMAKE... Hopefully someone that knows a little more than I will fix this discrepancy.<br />
<br />
NOTE2: You could pass in e.g. <tt>-D CMAKE_C_COMPILER_INIT:STRING=mycc</tt> on the command line, or set the same variable inside a listfile (before any PROJECT() or ENABLE_LANGUAGE() command). Might that be what you're getting at?<br />
<br />
=== In CCMake, typing full paths is tedious. Is there a better way? ===<br />
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.<br />
<br />
For example:<br />
<br />
/usr/loc<TAB><br />
<br />
will expand to<br />
<br />
/usr/local/<br />
<br />
<br />
<br />
== Out-of-source build trees ==<br />
<br />
=== What is an "out-of-source" build? ===<br />
When your build generates files, they have to go somewhere. An in-source build puts them in your source tree. An out-of-source build puts them in a completely separate directory, so that your source tree is unchanged.<br />
<br />
In the first example, an in-place build is performed, i.e., the binaries are placed in the same directory as the source code.<br />
<br />
cd Hello<br />
ccmake .<br />
make<br />
<br />
In the second example, an out-of-place build is performed, i.e., the source code, libraries, and executables are produced in a directory separate from the source code directory(ies).<br />
<br />
mkdir HelloBuild<br />
cd HelloBuild<br />
ccmake ../Hello<br />
make<br />
<br />
Out-of-source builds are recommended, as you can build multiple variants in separate directories, e.g., HelloBuildDebug, HelloBuildRelease.<br />
<br />
Note: Before performing an out-of-source build ensure that any possible CMake generated in-source build information is removed from the source directory, e.g., CMakeFiles directory, and CMakeCache.txt.<br />
<br />
=== I run an out-of-source build but CMake generates in-source anyway. Why? ===<br />
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.<br />
<br />
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).<br />
<br />
=== Why does CMake use full paths, or can I copy my build tree? ===<br />
CMake uses full paths because:<br />
<br />
# configured header files may have full paths in them, and moving those files without re-configuring would cause upredictable behavior.<br />
# because cmake supports out of source builds, if custom commands used relative paths to the source tree, they would not work when they are run in the build tree because the current directory would be incorrect.<br />
# on Unix systems rpaths might be 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.<br />
<br />
Can the build tree be copied or moved?<br />
<br />
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 and rerun. Often when people want to move a binary tree it is so that they can distribute it to other users who may not have cmake in which case this would not work even if cmake would detect the move.<br />
<br />
The workaround is to create a new build tree without copying or moving the old one.<br />
<br />
<br />
=== CMake does not generate a "make distclean" target. Why? ===<br />
Some build trees created with GNU autotools have a "make distclean" target that cleans the build and also removes Makefiles and other parts of the generated build system. CMake does not generate a "make distclean" target because CMakeLists.txt files can run scripts and arbitrary commands; CMake has no way of tracking 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. (CMake does generate a "make clean" target to remove files generated by the compiler and linker.)<br />
<br />
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. Because CMake does not change the source tree, there is no need for a distclean target. One can start a fresh build by deleting the build tree or creating a separate build tree.<br />
<br />
(If a CMakeLists.txt uses ADD_CUSTOM_COMMAND to generate source files in the source tree, not the build tree, then in CMake 2.2 or higher "make clean" will remove them. See next question.)<br />
<br />
=== Running "make clean" does not remove custom command outputs. Why? ===<br />
In CMake 2.2 and higher custom command outputs should be removed by make clean. Make sure you are using at least this version. Prior to CMake 2.2 custom command outputs were not automatically added to the list of files to clean. In CMake 2.0 the 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.<br />
<br />
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 to clean away files that differ between builds.<br />
<br />
<br />
== Writing CMakeLists.txt ==<br />
<br />
=== How to have backward and forward compatibility? ===<br />
<br />
As of CMake 2.6 we employ a "Policy" mechanism to provide backwards compatibility.<br />
The basic requirement for projects is to include one line at the top of the highest CMakeLists.txt file:<br />
<br />
cmake_minimum_required(VERSION 2.6) # or other version<br />
<br />
This tells versions of CMake older than that specified that they are too old to build the project.<br />
They will report this information to the user.<br />
It also tells versions of CMake newer than that specified that the project may not be aware of policies introduced in later versions, which enables additional compatibility.<br />
For futher documentation, see<br />
<br />
* [[CMake_Policies|CMake Policy Mechanism]]<br />
* [http://www.cmake.org/cmake/help/cmake2.6docs.html#command:cmake_policy cmake_policy() command]<br />
* [http://www.cmake.org/cmake/help/cmake2.6docs.html#section_Policies CMake 2.6 Policies]<br />
<br />
=== How do I get the current source or binary directory? ===<br />
The variable CMAKE_CURRENT_SOURCE_DIR contains the absolute path to your current source directory, while CMAKE_CURRENT_BINARY_DIR points to the equivalent binary directory.<br />
<br />
=== Why are my CMake variables not updated in the GUI after a SET command? ===<br />
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.<br />
<br />
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:<br />
<br />
SET(BUILD_SHARED_LIBS ON)<br />
<br />
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.<br />
<br />
You can use the CACHE and FORCE options on the SET command to change variables in a way that will be reflected in the GUI. Run<br />
<br />
cmake --help-command SET<br />
<br />
to see full instructions for the command.<br />
<br />
<br />
=== How can I change the default build mode and see it reflected in the GUI? ===<br />
Adapt the following commands in your CMakeList.txt (this example sets the Release<br />
With Debug Information mode):<br />
<pre><br />
IF(NOT CMAKE_BUILD_TYPE)<br />
SET(CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING<br />
"Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel."<br />
FORCE)<br />
ENDIF(NOT CMAKE_BUILD_TYPE)<br />
</pre><br />
<br />
=== How do I generate an executable, then use the executable to generate a file? ===<br />
<br />
Create the generator executable by just adding a target:<br />
<br />
ADD_EXECUTABLE(generate generate.c)<br />
<br />
The rest of the process is simpler in CMake 2.6 and above than in previous versions.<br />
<br />
Use <code>ADD_CUSTOM_COMMAND</code> to specify a custom build rule for the file.<br />
(In this example we assume <code>generate</code> accepts the input and output files as arguments.)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT someoutput.txt<br />
COMMAND generate ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
DEPENDS generate ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt<br />
)<br />
<br />
This tells CMake how to build the file but does not actually add a rule to the build system.<br />
Another target must require it.<br />
One may create a custom target explicitly for this rule:<br />
<br />
ADD_CUSTOM_TARGET(driver ALL DEPENDS someoutput.txt)<br />
<br />
or the file may be added as part of some other target:<br />
<br />
ADD_EXECUTABLE(product product.c someoutput.txt)<br />
<br />
<font color=#555555><br />
In CMake 2.4 and below the <code>generate</code> target may not be specified directly in the <code>COMMAND</code> option of <code>add_custom_command</code><br />
(but it can still be used in the <code>DEPENDS</code> option as of CMake 2.4).<br />
Instead use GET_TARGET_PROPERTY to obtain the location of the generated executable.<br />
Additionally, the output must always be specified by full path.<br />
<br />
GET_TARGET_PROPERTY(GENERATE_EXE generate LOCATION)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
COMMAND ${GENERATE_EXE} ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
DEPENDS generate<br />
)<br />
</font><br />
<br />
=== How can I generate a source file during the build? ===<br />
The ADD_CUSTOM_COMMAND command lets you generate a source file that you can then include in another target. For example:<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
COMMAND ${CMAKE_COMMAND} copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.c ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.c<br />
)<br />
ADD_EXECUTABLE(foo foo.c)<br />
<br />
This will create an executable by copying bar.c to foo.c and then compiling foo.c to produce foo. CMake allows you to put generate source files in the current source or binary directory, so we were careful to output foo.c to the current binary directory. When we add foo.c to foo, CMake will look in either directory for it. Even if foo.c does not yet exist, CMake is smart enough to notice that a custom command creates it. (For the file named as the OUTPUT, CMake has its GENERATED source file property set to true.)<br />
<br />
You can also use ADD_CUSTOM_COMMAND when the<br />
[[CMake_FAQ#How_do_I_generate_an_executable.2C_then_use_the_executable_to_generate_a_file.3F|generator command is another executable in the same project]].<br />
<br />
Sometimes, the program doing the generation may generate multiple output files that each need to be part of the build. CMake 2.4 or higher supports having multiple files listed in the OUTPUT section. 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:<br />
<br />
PROJECT(FOO)<br />
# make sure cmake addes the binary directory for the project to the include path<br />
INCLUDE_DIRECTORIES(${FOO_BINARY_DIR})<br />
# add the executable that will do the generation<br />
ADD_EXECUTABLE(my_generator my_generator.cxx)<br />
GET_TARGET_PROPERTY(MY_GENERATOR_EXE my_generator LOCATION)<br />
# add the custom command that will generate all three files<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${FOO_BINARY_DIR}/output1.cpp ${FOO_BINARY_DIR}/output2.h ${FOO_BINARY_DIR}/output3.cpp<br />
COMMAND ${MY_GENERATOR_EXE} ${FOO_BINARY_DIR} ${FOO_SOURCE_DIR}/input.txt<br />
DEPENDS my_generator<br />
MAIN_DEPENDENCY ${FOO_SOURCE_DIR}/input.txt<br />
)<br />
# now create an executable using the generated files<br />
ADD_EXECUTABLE(generated<br />
${FOO_BINARY_DIR}/output1.cpp<br />
${FOO_BINARY_DIR}/output2.h<br />
${FOO_BINARY_DIR}/output3.cpp)<br />
<br />
CMake 2.4 allows you to generate a header file. Because generated headers often cause unnecessary rebuilds, you should try to avoid them; consider using the CONFIGURE_FILE command to prepare the header at CMake time. If you must generate a header file, use code like this:<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.h<br />
COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.h ${CMAKE_CURRENT_BINARY_DIR}/foo.h<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.h<br />
)<br />
ADD_EXECUTABLE(foo foo.c ${CMAKE_CURRENT_BINARY_DIR}/foo.h)<br />
<br />
This is like the first example above, except that it generates a header instead of a C file. The header might not exist when the build system scans foo.c's dependencies, so there is no way for CMake to know that this target requires foo.h unless we can tell it that foo.h may exist in the future. We give CMake this knowledge by listing the generated header file in the set of source files for the target. (This requires CMake 2.4. Previous versions of CMake required use of the OBJECT_DEPENDS source file property.)<br />
<br />
=== How can I add a dependency to a source file which is generated in a subdirectory? ===<br />
<br />
Rules created with <code>ADD_CUSTOM_COMMAND</code> as [[CMake_FAQ#How_can_I_generate_a_source_file_during_the_build.3F|above]] have scope only in the directory in which they are specified.<br />
If the generated file is needed in another directory, a target-level dependency needs to be added.<br />
Create a target in the subdirectory with the custom rule in order to drive it:<br />
<br />
# subdir/CMakeLists.txt<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
COMMAND ${CMAKE_COMMAND} copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.c ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.c<br />
)<br />
ADD_CUSTOM_TARGET(generate_foo DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/foo.c)<br />
<br />
Now other targets can depend on the target from the subdirectory:<br />
<br />
# CMakeLists.txt<br />
ADD_SUBDIRECTORY(subdir)<br />
# Create the executable.<br />
ADD_EXECUTABLE(generated ${CMAKE_CURRENT_BINARY_DIR}/subdir/foo.c)<br />
# Tell CMake the source won't be available until build time.<br />
SET_SOURCE_FILES_PROPERTIES(${CMAKE_CURRENT_BINARY_DIR}/subdir/foo.c PROPERTIES GENERATED 1)<br />
# Make sure the source is generated before the executable builds.<br />
ADD_DEPENDENCIES(generated generate_foo)<br />
<br />
=== I use EXEC_PROGRAM but the result is not set in subdirectories. Why? ===<br />
<br />
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 was fixed in CMake 2.2, but for older versions you will have to cache the result:<br />
<br />
<pre><br />
EXEC_PROGRAM(my-program OUTPUT_VARIABLE MY_OUTPUT)<br />
SET(MY_OUTPUT "${MY_OUTPUT}" CACHE INTERNAL "")<br />
</pre><br />
<br />
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.<br />
<br />
=== How can I get or set environment variables? ===<br />
<br />
CMake names environment variables using an ENV prefix and surrounding the names in curly braces. Here is an example:<br />
<br />
<pre><br />
MESSAGE("$ENV{PATH}")<br />
</pre><br />
<br />
Reading variables will work in any version of CMake. Writing to them works in CMake 2.2 and higher using the following syntax:<br />
<br />
<pre><br />
SET(ENV{HELLO} "World")<br />
</pre><br />
<br />
Note that there is currently no way to tell apart an empty environment variable value from a variable that is not set at all.<br />
<br />
One should avoid using environment variables for controlling the flow of CMake code (such as in IF commands). The build system generated by CMake may re-run CMake automatically when CMakeLists.txt files change. The environment in which this is executed is controlled by the build system and may not match that in which CMake was originally run. If you want to control build settings on the CMake command line, you need to use cache variables set with the -D option. The settings will be saved in CMakeCache.txt so that they don't have to be repeated every time CMake is run on the same build tree.<br />
<br />
Also, environment variables SET in the CMakeLists.txt ''only'' take effect for cmake itself, so you cannot use this method to set an environment variable that a custom command might need.<br />
<br />
=== Why do I have unwanted semicolons ; in my compiler flags? ===<br />
CMake has a list data type. A list is stored as a string of semicolon-separated list elements. Whitespace separated arguments to a SET statement are interpreted as list elements. For instance, SET(var a b c d e) will give "var" a value of a;b;c;d;e and this list can be used by other CMake commands. However, if you pass ${var} to a non-CMake external tool, such as a compiler's command line, you are passing a;b;c;d;e which is not what you want. Instead you either need to pass "${var}", so that the list will be converted to a whitespace-separated string, or you need to SET(var "a b c d e") in the 1st place so that you're working with a string, not a list.<br />
<br />
=== How can I get quoting and escapes to work properly? ===<br />
If you want to escape a character in CMake, you use "\", like in C code. For example, if you wanted to have a quote embedded in a string you would do this: "\"". However, each level of CMake that processes your code will need one level of escaping to work. So, if you configure a file that is read by cmake or cpack and you want to do the same thing, you would do "\\\"". You would still need to escape the " for the first cmake that processes the string. However, this time, you would want to also escape a '\' as well. This would leave the next level of processing with "\"". Also, for custom commands that may get passed to a shell, it maybe required to do escaping for that shell.<br />
<br />
=== Isn't the "Expression" in the "ELSE (Expression)" confusing? ===<br />
Traditional CMakeLists.txt files prior to 2.6.0, require the following syntax. In the IF syntax, the ELSE section requires the same (Expression) as the IF section. This sometimes can make the script kind of hard to follow, take the short example below:<br />
<br />
IF(WIN32)<br />
...do something...<br />
ELSE(WIN32)<br />
...do something else...<br />
ENDIF(WIN32)<br />
<br />
You might think that the ELSE section, here containing "...do something else...", is for the WIN32 portion of the script. That is not so! It is actually handling the NOT WIN32 section.<br />
<br />
As of CMake 2.6.0 the ELSE() and ENDIF() constructs can be empty. The same is true for closing constructs on ENDMACRO(), ENDFUNCTION(), and ENDFOREACH(). If you require 2.4.x compatibility, you can enable the CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS option on CMake 2.4.3 or greater. This option is superfluous on CMake 2.6.0 or greater.<br />
<br />
SET(CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS true)<br />
<br />
IF(WIN32)<br />
...do something...<br />
ELSEIF(APPLE)<br />
...do something else...<br />
ELSE()<br />
...do something else...<br />
ENDIF()<br />
<br />
=== Which regular expressions are supported by CMake? ===<br />
When using MATCHES or MATCHALL in an IF command, or using any of the STRING(REGEX ...) commands, CMake expects regular expressions, not globs (wild cards). CMake uses the same regular expression engine above all platforms. Here are the meanings of the metacharacters:<br />
<br />
^ Matches at beginning of a line<br />
$ Matches at end of a line<br />
. Matches any single character<br />
[ ] Matches any character(s) inside the brackets<br />
[^ ] Matches any character(s) not inside the brackets<br />
- Matches any character in range on either side of a dash<br />
| Matches a pattern on either side of the |<br />
* Matches preceding pattern zero or more times<br />
+ Matches preceding pattern one or more times<br />
? Matches preceding pattern zero or once only<br />
() Saves a matched expression and uses it in a later match<br />
<br />
Example: "[-][L]([^ ;])+" matches all strings beginning with -L and ending with a space or a semicolon, the usual linkdirs under Linux.<br />
<br />
Here is how to catch a part of a string. The variable test is filled with some content, and then we want to catch the "me":<br />
<br />
SET(test "hello world ! catch: me if you can")<br />
STRING(REGEX REPLACE ".*catch: ([^ ]+).*" "\\1" result "${test}" )<br />
MESSAGE(STATUS "result= ${result}")<br />
<br />
This is slightly tricky. The part inside the brackets is available in \\1 . CMake will copy the variable test to the variable result, but then it will replace everything that the regular expression matches with \\1. This means the first regular expression has to match the whole string and the part we want to catch has to be put in parens.<br />
<br />
-- result= me<br />
<br />
For those of you who know Perl, the equivalent Perl code could be:<br />
<br />
$test = "hello world ! catch: me if you can";<br />
$result = $test;<br />
$result =~ s/.*catch: ([^ ]+).*/$1/;<br />
print "-- result= $result\n";<br />
<br />
There are other ways to do this in Perl, but this is how we do it in CMake because \\1 does not become a variable like $1 does in perl, so there is no SET(result ${\\1}) in CMake.<br />
<br />
<br />
=== How to convert a semicolon separated list to a whitespace separated string? ===<br />
<br />
set(foo<br />
abc.c<br />
abc.b<br />
abc.a<br />
)<br />
<br />
foreach(arg ${foo})<br />
set(bar "${bar} ${arg}")<br />
endforeach(arg ${foo})<br />
<br />
message("foo: ${foo}")<br />
message("bar: ${bar}")<br />
<br />
=== How can I build multiple modes without switching ? ===<br />
To build multiple modes (e.g. Debug and Release) in one shot without constantly running cmake -DCMAKE_BUILD_TYPE=Debug and cmake -DCMAKE_BUILD_TYPE=Release in source tree create a directory for builds eg.:<br />
<br />
<pre><br />
Project-directory/<br />
/Build<br />
</pre><br />
<br />
Inside you can place as many target directories for out-of-source build modes as you want, e.g.:<br />
<br />
<pre><br />
Project-directory/<br />
/Build<br />
/Debug<br />
/Release<br />
</pre><br />
<br />
In each of these directories issue a command (assuming that you have CMakeLists.txt directly in Project-directory)<br />
<br />
<pre><br />
cmake -DCMAKE_BUILD_TYPE=type_of_build ../../<br />
</pre><br />
<br />
to create a cmake cache configured for requested build type.<br />
<br />
Now you can make each build just by entering appropriate directory and executing a make command.<br />
<br />
=== How can I extend the build modes with a custom made one ? ===<br />
The following code snipet (taken from a CMakeLists.txt) adds a Maintainer mode:<br />
<pre><br />
SET( CMAKE_CXX_FLAGS_MAINTAINER "-Wall -Wabi" CACHE STRING<br />
"Flags used by the C++ compiler during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_C_FLAGS_MAINTAINER "-Wall -pedantic" CACHE STRING<br />
"Flags used by the C compiler during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_EXE_LINKER_FLAGS_MAINTAINER<br />
"-Wl,--warn-unresolved-symbols,--warn-once" CACHE STRING<br />
"Flags used for linking binaries during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_SHARED_LINKER_FLAGS_MAINTAINER<br />
"-Wl,--warn-unresolved-symbols,--warn-once" CACHE STRING<br />
"Flags used by the shared libraries linker during maintainer builds."<br />
FORCE )<br />
MARK_AS_ADVANCED(<br />
CMAKE_CXX_FLAGS_MAINTAINER<br />
CMAKE_C_FLAGS_MAINTAINER<br />
CMAKE_EXE_LINKER_FLAGS_MAINTAINER<br />
CMAKE_SHARED_LINKER_FLAGS_MAINTAINER )<br />
# Update the documentation string of CMAKE_BUILD_TYPE for GUIs<br />
SET( CMAKE_BUILD_TYPE "" CACHE STRING<br />
"Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel Maintainer."<br />
FORCE )<br />
</pre><br />
Notes: The flags used in this example are specific to GCC. Change them as needed for your project. Additionally the SET(CMAKE_BUILD_TYPE) command will override<br />
a CMAKE_BUILD_TYPE previously set in the CMakeLists.txt.<br />
<br />
=== Why does <code>foreach</code> skip empty values? ===<br />
<br />
The code in question is of the form<br />
<br />
set(var "a;b;;c;d") # list 'a', 'b', '', 'c', 'd'<br />
foreach(v ${var})<br />
# v=a, v=b, v=c, v=d, one at a time<br />
endforeach()<br />
<br />
and the loop variable 'v' never attains the empty-string value ''.<br />
This is because the <code>${var}</code> syntax is an unquoted argument so the CMake language expands the list and removes the empty value.<br />
The foreach command does not even see the empty value.<br />
One can verify this because the code<br />
<br />
foreach(v a b "" c d)<br />
...<br />
endforeach()<br />
<br />
will see the empty value.<br />
<br />
=== Does CMake support precompiled headers? ===<br />
<br />
Yes and no. Every platform does precompiled headers a bit differently, and there is currently no first-class interface provided by CMake and implemented on every platform.<br />
However, CMake does provide enough primitives for projects to use precompiled headers on specific platforms.<br />
Our issue tracker has a [http://www.cmake.org/Bug/view.php?id=1260 feature request] with attachements providing user-contributed helper macros for some platforms.<br />
<br />
== Writing FindXXX.cmake files ==<br />
<br />
=== What are the rules to write a FindXXX.cmake file? ===<br />
<br />
Let's follow the instructions and the advices in the <br />
Modules/readme.txt [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/readme.txt?root=CMake&view=markup]<br />
file located in the CVS repository.<br />
<br />
=== Why does find_library look in system directories before its PATHS option? ===<br />
<br />
The code in question is often of the form<br />
<br />
find_library(FOO_LIBRARY NAMES foo PATHS /opt/foo/lib)<br />
<br />
CMake will find "<code>/usr/lib/libfoo.so</code>" instead of "<code>/opt/foo/lib/libfoo.so</code>" if both exist.<br />
The reason is that /opt/foo/lib is a <i>hard-coded guess</i> of the location.<br />
The documentation of <code>[http://www.cmake.org/cmake/help/cmake2.6docs.html#command:find_library find_library]</code> specifies the search order.<br />
User, project, and system configuration variables are always more local than hard-coded guesses and should override them, so<br />
the PATHS option is used last.<br />
<br />
Some find-modules compute probable locations based on other information <i>available from the system</i> such as a project-specific environment variable.<br />
The HINTS option (CMake 2.6 and higher) takes precedence over system directories specifically for this case:<br />
<br />
file(TO_CMAKE_PATH "$ENV{FOO_LIB_DIR}" FOO_LIB_DIR)<br />
find_library(FOO_LIBRARY NAMES foo HINTS ${FOO_LIB_DIR})<br />
<br />
CMake will find "<code>$ENV{FOO_LIB_DIR}/libfoo.so</code>" before "<code>/usr/lib/libfoo.so</code>".<br />
<br />
== Finding and using external packages ==<br />
<br />
=== How do I use CMake to generate SWIG wrapper libraries? ===<br />
<br />
CMake version 2 includes a module that supports the generation of SWIG wrapper libraries. The SWIG package defines the following macros: SWIG_ADD_MODULE and SWIG_LINK_LIBRARIES.<br />
<br />
<pre><br />
# This example shows how to use python<br />
# Currently these languages have been tested:<br />
# perl tcl ruby php4 pike<br />
<br />
FIND_PACKAGE(SWIG REQUIRED)<br />
INCLUDE(${SWIG_USE_FILE})<br />
<br />
FIND_PACKAGE(PythonLibs)<br />
INCLUDE_DIRECTORIES(${PYTHON_INCLUDE_PATH})<br />
<br />
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})<br />
<br />
SET(CMAKE_SWIG_FLAGS "")<br />
<br />
SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES CPLUSPLUS ON)<br />
SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES SWIG_FLAGS "-includeall")<br />
SWIG_ADD_MODULE(example python<br />
example.i example.cxx)<br />
SWIG_LINK_LIBRARIES(example ${PYTHON_LIBRARIES})<br />
<br />
</pre><br />
<br />
<pre><br />
# This example shows how to use tcl<br />
PROJECT(TCL_WRAP)<br />
SET ( MODULE_NAME project )<br />
SET ( INTERFACE_FILES project.i)<br />
SET ( SRC_FILES Vertex.h Vertex.cxx Shapes.h Shapes.cxx )<br />
<br />
FIND_PACKAGE(SWIG REQUIRED)<br />
INCLUDE(${SWIG_USE_FILE})<br />
<br />
# Look for TCL<br />
INCLUDE_DIRECTORIES(${TCL_INCLUDE_PATH})<br />
<br />
FIND_LIBRARY(TCL_LIBRARY NAMES tcl tcl84 tcl83 tcl82 tcl80<br />
PATHS /usr/lib /usr/local/lib)<br />
IF (TCL_LIBRARY)<br />
TARGET_ADD_LIBRARY (${MODULE_NAME} TCL_LIBRARY)<br />
ENDIF (TCL_LIBRARY)<br />
<br />
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})<br />
<br />
SET(CMAKE_SWIG_FLAGS "-c++")<br />
<br />
SET_SOURCE_FILES_PROPERTIES(${INTERFACE_FILES} PROPERTIES CPLUSPLUS ON)<br />
SET_SOURCE_FILES_PROPERTIES(${INTERFACE_FILES} PROPERTIES CMAKE_SWIG_FLAGS "-includeall")<br />
SWIG_ADD_MODULE(${MODULE_NAME} tcl ${INTERFACE_FILES} ${SRC_FILES})<br />
SWIG_LINK_LIBRARIES(${MODULE_NAME} ${TCL_LIBRARIES})<br />
</pre><br />
<br />
=== How do I use CMake to build LaTeX documents? ===<br />
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.<br />
<br />
PROJECT(Document)<br />
IF(LATEX_COMPILE)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${Document_BINARY_DIR}/TDocument.dvi<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.tex<br />
COMMAND ${LATEX_COMPILE} <br />
ARGS ${Document_SOURCE_DIR}/TDocument.tex <br />
)<br />
ENDIF(LATEX_COMPILE)<br />
<br />
IF(DVIPDF_COMPILE)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${Document_BINARY_DIR}/TDocument.pdf<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.dvi <br />
COMMAND ${DVIPDF_COMPILE}<br />
ARGS ${Document_SOURCE_DIR}/TDocument.dvi<br />
)<br />
ENDIF(DVIPDF_COMPILE)<br />
<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.pdf<br />
)<br />
<br />
The following uses commands in CMake version 2.0 and later<br />
<br />
PROJECT(Document)<br />
# <br />
# Find LaTeX<br />
#<br />
FIND_PACKAGE(LATEX)<br />
<br />
IF(LATEX_COMPILER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.dvi<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS ${Document_SOURCE_DIR}/TDocument.tex<br />
DEPENDS ${Document_SOURCE_DIR}/TDocument.tex<br />
COMMENT "Tex2dvi"<br />
)<br />
<br />
IF(DVIPS_CONVERTER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.ps<br />
COMMAND ${DVIPS_CONVERTER}<br />
ARGS ${Document_BINARY_DIR}/TDocument.dvi<br />
-o ${Document_BINARY_DIR}/TDocument.ps<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.dvi<br />
COMMENT "dvi2ps"<br />
)<br />
<br />
IF(PS2PDF_CONVERTER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.pdf<br />
COMMAND ${PS2PDF_CONVERTER}<br />
ARGS ${Document_BINARY_DIR}/TDocument.ps<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.ps<br />
COMMENT "ps2pdf"<br />
)<br />
<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.pdf<br />
)<br />
ENDIF(PS2PDF_CONVERTER)<br />
ENDIF(DVIPS_CONVERTER)<br />
ENDIF(LATEX_COMPILER)<br />
<br />
=== How do I get LaTeX references to be correct? ===<br />
When your latex document contains references (e.g. \ref{...} command) you get to run two passes of latex. In the<br />
most general case, i.e. when additionally your document uses a bibtex bibliography, you shall need three<br />
passes of latex (and one pass of bibtex):<br />
# latex (first pass: for bibtex to have an .aux file)<br />
# bibtex (for generating the .bbl file)<br />
# latex (second pass)<br />
# latex (third pass)<br />
<br />
The following code snippet illustrates how you can "pervert" the bibtex and latex generated<br />
auxilary files (.aux, .log, .dvi, .bbl...) to create an "artificial" set of CMake dependencies.<br />
The side-effect of those dependencies should hopefully be the above described sequence of calls<br />
to latex and bibtex<br />
<pre><br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.aux<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/UsersManual.tex<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (first pass)"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.aux<br />
COMMAND ${BIBTEX_COMPILER}<br />
ARGS -terse ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Bibtex"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.dvi<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (second pass)"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.log<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
${CMAKE_CURRENT_BINARY_DIR}/UsersManual.dvi<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (third pass)"<br />
)<br />
# Eventually trigger the whole process<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.log<br />
)<br />
</pre><br />
<br />
=== How can I set TEXINPUTS for a LaTeX compilation? ===<br />
First note that most often you can avoid using TEXINPUTS by copying all the necessary files (.tex source file and<br />
included graphic files e.g. .eps files) from your PROJECT_SOURCE_DIR hirarchy to your PROJECT_BINARY_DIR subdir<br />
[refer to CONFIGURE_FILE with the COPYONLY flag set for copying files]. Since by default latex uses the current working directory as value for TEXINPUTS you should be all set. As expected, this trick is quick AND dirty since your<br />
concerned PROJECT_BINARY_DIR subdir now contains files that are NOT generated by CMake (in the sense that those<br />
files are not the result of a system command but were merely duplicated)... <br />
<br />
If you consider it is cleaner or easier to define a TEXINPUTS environment variable [the latex command probably<br />
misses a -I flag] you can find an example in the InsightDocuments cvs archive (refer to the section "cvs access"<br />
near the bottom of Kitware's ITK download page) or use google with keywords "ITK_TEXINPUTS CONFIGURE_FILE".<br />
Look at InsightDocuments/CourseWare/Training/Vis2003/Latex/CMakeLists.txt and search for e.g. "LaTeXWrapper.sh.in".<br />
<br />
Roughly the mechanism goes:<br />
* SET ITK_TEXINPUTS with the desired TEXINPUTS<br />
* CONFIGURE_FILE "InsightDocuments/CourseWare/Training/Vis2003/LaTeXWrapper.sh.in" which generates an sh shell script setting the shell variable TEXINPUTS prior to running the latex command<br />
* use ADD_CUSTOM_COMMAND to invoke this shell script<br />
This very example is Win32 portable (except that LaTeXWrapper.bat.in generates a .bat shell script)<br />
<br />
== Library questions ==<br />
<br />
=== Can I build both shared and static libraries with one ADD_LIBRARY command? ===<br />
<br />
No. Each library you build must have a unique target name, i.e. the "libname" field of the ADD_LIBRARY command. That way, CMake can track dependencies separately for each library. Libraries can have the same OUTPUT_NAME, see the SET_TARGET_PROPERTIES command, but this is not the default.<br />
<br />
=== Does that mean I have to build all my library objects twice, once for shared and once for static?! I don't like that! ===<br />
<br />
In practice, most libraries have different defines and compiler flags for the shared vs. static cases. So you would have to build all your library objects twice anyways. However, if you happen to have '''''exactly''''' the same defines and compiler flags for the shared vs. static cases...<br />
<br />
...if you're using Linux and a GCC-style linker, you could do the following. Note that for this to work correctly on linux, the zzSTATIC source files should have been compiled with "-fPIC" to ensure they will work in a shared library.<br />
<br />
IF(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_COMPILER_IS_GNUCC)<br />
ADD_LIBRARY(zzSTATIC STATIC -fPIC)<br />
ADD_LIBRARY(zzDYNAMIC SHARED)<br />
TARGET_LINK_LIBRARIES(zzDYNAMIC -Wl,-whole-archive zzSTATIC -Wl,-no-whole-archive)<br />
ENDIF(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_COMPILER_IS_GNUCC)<br />
<br />
...if you want a cross-platform approach that works on all compilers, not just GCC or Linux, you could extract the locations of previously built object files and insert them directly into the libraries that need them. This is documented in [http://www.cmake.org/Bug/view.php?id=5155 CMake Feature Request #5155: standard way to locate object files]. Unfortunately this approach relies on CMake's internal implementation, and that implementation could change in the future, breaking your code.<br />
<br />
=== How do I make my shared and static libraries have the same root name, but different suffixes? ===<br />
Set the OUTPUT_NAME of your shared and static libraries to the same thing.<br />
<br />
ADD_LIBRARY(foo SHARED ${foo_sources})<br />
ADD_LIBRARY(foo-static STATIC ${foo_sources})<br />
// The library target "foo" already has a default OUTPUT_NAME of "foo", so we don't need to change it.<br />
// The library target "foo-static" has a default OUTPUT_NAME of "foo-static", so change it.<br />
SET_TARGET_PROPERTIES(foo-static PROPERTIES OUTPUT_NAME "foo")<br />
<br />
If you are building your shared and static libraries in the same directory, you will also need the following to keep your shared and static libraries from clobbering each other during the build.<br />
<br />
SET_TARGET_PROPERTIES(foo PROPERTIES CLEAN_DIRECT_OUTPUT 1)<br />
SET_TARGET_PROPERTIES(foo-static PROPERTIES CLEAN_DIRECT_OUTPUT 1)<br />
<br />
=== How do I rename a library after it has already been built? ===<br />
You don't rename it. It's been built! Its name is whatever CMakeLists.txt says it's supposed to be.<br />
<br />
Perhaps you want to copy the library to a different name. But, are you sure that's what you want to do? You could just change the name in your ADD_LIBRARY command or change its OUTPUT_NAME property using SET_TARGET_PROPERTY(). If you really really want to copy the library to a different name, try:<br />
<br />
GET_TARGET_PROPERTY(LIB_NAME Foo LOCATION)<br />
GET_TARGET_PROPERTY(Bar_prefix Foo PREFIX)<br />
GET_TARGET_PROPERTY(Bar_suffix Foo SUFFIX)<br />
SET(NEW_LIB_NAME ${Bar_prefix}Bar${Bar_suffix})<br />
<br />
ADD_CUSTOM_COMMAND(<br />
TARGET Foo<br />
POST_BUILD<br />
COMMAND ${CMAKE_COMMAND} -E copy ${LIB_NAME} ${NEW_LIB_NAME}<br />
)<br />
<br />
On Windows you may also want to copy the .dll import lib, using the same approach as above, but with IMPORT_PREFIX and IMPORT_SUFFIX. ''Problem: LOCATION only refers to 1 file, the .dll. What is a simple way to get the location of the import lib? Could provide a complicated way, but that's annoying.''<br />
<br />
=== Does CMake support "convenience" libraries? ===<br />
No. CMake does not currently support convenience libraries. A "convenience" library, as GNU libtool calls it, is an archive of objects to be mixed into other libraries. Other libraries "link" to the convenience library, but the convenience library does not export any symbols; GNU libtool never installs the convenience library; no programs ever link to the convenience library.<br />
<br />
This does '''not''' mean that a project using convenience libraries cannot be converted to CMake. Instead the source files may be listed in each target that needs them. They will be built for each target separately using all the preprocessor definitions and flags configured for that target.<br />
<br />
=== Why are libraries linked to my shared library included when something links to it? ===<br />
This question arises when one has a library B which links to some library A. When a third target, say C, links to B, CMake will automatically include C to A also. When the libraries are static, then this is always necessary. When the libraries are shared, this is the default behavior provided by CMake. CMake 2.6 and above provide the target property "LINK_INTERFACE_LIBRARIES" (http://www.cmake.org/HTML/cmake-2.6.html#prop_tgt:LINK_INTERFACE_LIBRARIES) to specify the libraries that should be transitively included in the link by CMake. CMake 2.4 and below do not support the property.<br />
<br />
Something like the following will work in CMake 2.6:<br />
<br />
<pre><br />
set_target_properties(mylibrary<br />
PROPERTIES<br />
LINK_INTERFACE_LIBRARIES ""<br />
)<br />
</pre><br />
<br />
=== CMake dependency scanner ===<br />
<br />
CMake does not preprocess source files while scanning dependencies. Code like<br />
<pre><br />
#if 0<br />
# include "bla.h"<br />
#endif<br />
</pre><br />
will result in a dependency on "bla.h". This sometimes leads to source files recompiling unnecessarily but will not break the build.<br />
<br />
== Installation questions ==<br />
<br />
=== Does CMake's "make install" support DESTDIR? ===<br />
'''Yes''', especially when the build-system generator uses CMake's builtin support for installing files: Simply define the DESTDIR environment variable during installation and CMake will treat that value as the root of the file system for all installation paths; naturally, the DESTDIR path must be absolute.<br />
<br />
For example, if the Makefile generator is used, then all of the following are example usages of DESTDIR (perhaps assuming the bash shell for the last 2):<br />
<br />
(1) make install DESTDIR="/some/absolute/path"<br />
(2) make DESTDIR="/some/absolute/path" install<br />
(3) DESTDIR="/some/absolute/path" make install<br />
(4) export DESTDIR="/some/absolute/path<br />
make install<br />
<br />
=== Can I do "make uninstall" with CMake?===<br />
By default, CMake does not provide the "make uninstall" target, so you cannot do this. We do not want "make uninstall" to remove useful files from the system.<br />
<br />
If you want an "uninstall" target in your project, then nobody prevents you from providing one. You need to delete the files listed in install_manifest.txt file. Here is how to do it. First create file cmake_uninstall.cmake.in in the top-level directory of the project:<br />
<br />
<pre><br />
IF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")<br />
MESSAGE(FATAL_ERROR "Cannot find install manifest: \"@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt\"")<br />
ENDIF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")<br />
<br />
FILE(READ "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt" files)<br />
STRING(REGEX REPLACE "\n" ";" files "${files}")<br />
FOREACH(file ${files})<br />
MESSAGE(STATUS "Uninstalling \"$ENV{DESTDIR}${file}\"")<br />
IF(EXISTS "$ENV{DESTDIR}${file}")<br />
EXEC_PROGRAM(<br />
"@CMAKE_COMMAND@" ARGS "-E remove \"$ENV{DESTDIR}${file}\""<br />
OUTPUT_VARIABLE rm_out<br />
RETURN_VALUE rm_retval<br />
)<br />
IF(NOT "${rm_retval}" STREQUAL 0)<br />
MESSAGE(FATAL_ERROR "Problem when removing \"$ENV{DESTDIR}${file}\"")<br />
ENDIF(NOT "${rm_retval}" STREQUAL 0)<br />
ELSE(EXISTS "$ENV{DESTDIR}${file}")<br />
MESSAGE(STATUS "File \"$ENV{DESTDIR}${file}\" does not exist.")<br />
ENDIF(EXISTS "$ENV{DESTDIR}${file}")<br />
ENDFOREACH(file)<br />
</pre><br />
<br />
Then in the top-level CMakeLists.txt add the following logic:<br />
<br />
<pre><br />
CONFIGURE_FILE(<br />
"${CMAKE_CURRENT_SOURCE_DIR}/cmake_uninstall.cmake.in"<br />
"${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake"<br />
IMMEDIATE @ONLY)<br />
<br />
ADD_CUSTOM_TARGET(uninstall<br />
"${CMAKE_COMMAND}" -P "${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake")<br />
</pre><br />
<br />
Now you will have an "uninstall" target at the top-level directory of your build tree.<br />
<br />
Instead of creating an "uninstall" target, Unix users could enter this command in the shell:<br />
<br />
xargs rm < install_manifest.txt<br />
<br />
== Distribution questions ==<br />
<br />
=== Where is "make dist"? ===<br />
<br />
CMake doesn't create a "make dist" target.<br />
<br />
=== What is the best way to distribute source code or binaries for a cmake-based project? ===<br />
<br />
For creating source or binary packages there is now [[CMake#CPack | CPack]] coming with CMake, see the <br />
[[ CMake#CPack | documentation]].<br />
<br />
Of course you can also use any other ways to create packages.<br />
<br />
== Platform-specific questions ==<br />
=== How do I build universal binaries on Mac OS X? ===<br />
Before running CMake with an empty build tree, set the CMAKE_OSX_ARCHITECTURES environment variable. It should be set to contain a ; separated list of architectures that you want in the binary. For example, for 32-bit PowerPC and Intel you would do this:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386<br />
<br />
If you wish to build both as 32 and 64 bit, do this:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386;ppc64;x86_64<br />
<br />
You can also set the same named CMake cache variable on an existing binary tree. This works with both makefiles and the Xcode generator. <br />
<br />
In addition, you can also set the CMAKE_OSX_SYSROOT variable to point to the sysroot (aka Mac OS SDK) to be used. CMake will attempt to pick one on your system, but it can be changed in the cache or via an environment variable before running CMake. The 10.4u SDK or later must be used to create a Universal Binary.<br />
<br />
Universal Binaries are essentially cross compilation and so you should avoid using TRY_RUN, especially for things like testing endianess or variable size because the result will only be correct for one architecture.<br />
<br />
Lastly, note that CTest is only able to test one architecture. See bug 6157.<br />
<br />
=== How can I apply resources on Mac OS X automatically? ===<br />
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 a custom rule which is executed after the executable is linked:<br />
<br />
<pre><br />
ADD_EXECUTABLE(MyExecutable ${MyExecutable_SRCS})<br />
GET_TARGET_PROPERTY(MyExecutable_PATH MyExecutable LOCATION)<br />
<br />
IF(APPLE)<br />
FIND_PROGRAM(APPLE_RESOURCE Rez /Developer/Tools)<br />
IF(APPLE_RESOURCE)<br />
ADD_CUSTOM_COMMAND(TARGET MyExecutable POST_BUILD<br />
COMMAND ${APPLE_RESOURCE} Carbon.r -o ${MyExecutable_PATH})<br />
ENDIF(APPLE_RESOURCE)<br />
ENDIF(APPLE)<br />
</pre><br />
<br />
This will execute:<br />
<br />
/Developer/Tools/Rez Carbon.r -o /binary/path/MyExecutable<br />
<br />
after MyExecutable is linked.<br />
<br />
'Rez' may be located elsewhere on disk, depending on the version of Mac OS X and Xcode. You can use 'which Rez' in Terminal to find it's full path.<br />
<br />
=== Why does FIND_LIBRARY not find .DLL libraries under WIN32? ===<br />
For those who come from a Unix background to MS Windows:<br />
<br />
You never link directly to the .dll, you have to link against the import library .lib for the .dll.<br />
<br />
Linking against dynamic libraries (.dll under Windows) is quite different from linking against ELF shared objects (.so) under platforms like Linux or NetBSD. In Windows, there are two types of library, a static library and an import library (both confusingly use the .lib extension, however). In Windows, when you build an import library (A.lib) you will get a corresponding (A.dll) that you only need at runtime. At compile time you will need the import library.<br />
<br />
Conclusion: There is no need to find a .dll for linking. You only need to find the .lib import library.<br />
<br />
Some more details can be found here: [http://xenophilia.org/winvunix.html].<br />
<br />
=== Why am I getting a linker error to _mainCRTStartup under WIN32? ===<br />
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.<br />
<br />
ADD_EXECUTABLE(exename WIN32 source1 source2 ... sourceN)<br />
<br />
The second argument to ADD_EXECUTABLE can be WIN32. This indicates that the executable, when compiled on Windows, is a Windows app (using WinMain) and not a console app (using main). Please note that on Unix platforms, CMake ignores the WIN32 and the compiler will use "main" in any case.<br />
<br />
=== Why do I get this error: nafxcwd.lib(appcore.obj) : error LNK2001: unresolved external symbol ___argv ===<br />
<br />
This is because the application is using both the static and dll versions of the MFC library.<br />
To fix the problem, you can do the following:<br />
<br />
SET(CMAKE_MFC_FLAG 2) # force the IDE to use static MFC<br />
ADD_DEFINITIONS(-D_AFXDLL) # make sure if afx.h is included the dll MFC is used<br />
<br />
=== How to use MFC with CMake ===<br />
To use MFC, the CMAKE_MFC_FLAG variable must be set as follows:<br />
<br />
0: Use Standard Windows Libraries<br />
1: Use MFC in a Static Library<br />
2: Use MFC in a Shared DLL <br />
<br />
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:<br />
<br />
ADD_DEFINITIONS(-D_AFXDLL)<br />
SET(CMAKE_MFC_FLAG 2) <br />
ADD_EXECUTABLE(CMakeSetup WIN32 ${SRCS})<br />
<br />
Note that visual studio 9 project files do not appear to work with CMAKE_MFC_FLAG 1; this may be related to [http://www.cmake.org/Bug/view.php?id=7056 bug 7056].<br />
<br />
In order to use MFC with UNICODE, you must also [http://msdn.microsoft.com/en-us/library/dybsewaf.aspx specify the entry point wWinMainCRTStartup]. For example:<br />
<br />
set(CMAKE_MFC_FLAG 2)<br />
set_target_properties(MyApp PROPERTIES<br />
COMPILE_DEFINITIONS _AFXDLL,_UNICODE,UNICODE,_BIND_TO_CURRENT_CRT_VERSION,_BIND_TO_CURRENT_MFC_VERSION<br />
LINK_FLAGS "/ENTRY:\"wWinMainCRTStartup\"")<br />
<br />
See [http://stackoverflow.com/questions/59635/app-does-not-run-with-vs-2008-sp1-dlls-previous-version-works-with-rtm-versions this article] as to why _BIND_TO_CURRENT_CRT_VERSION and _BIND_TO_CURRENT_MFC_VERSION are necessary for Visual Studio 2008 SP1.<br />
<br />
=== How To Put Files in Folders in Visual Studio Projects ===<br />
The Visual Studio IDE supports putting files into folders.<br />
CMake can be used to put files in folders with the SOURCE_GROUP <br />
command. <br />
<br />
SOURCE_GROUP(name [REGULAR_EXPRESSION regex] [FILES src1 src2 ...])<br />
<br />
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 provided the source file is being passed to ADD_EXECUTABLE or ADD_LIBRARY.<br />
<br />
For example:<br />
SOURCE_GROUP(FooFiles FILES foo.cxx)<br />
SOURCE_GROUP(BarFiles FILES bar.cxx)<br />
ADD_LIBRARY(foo foo.cxx bar.cxx)<br />
<br />
In the event 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).<br />
<br />
As a convenience to developers CMake automatically adds standard header files to a "Header Files" folder and standard source files to a "Source Files" folder for Visual Studio Projects. This can be overridden via the SOURCE_GROUP method documented above.<br />
<br />
=== How to create Visual Studio 6 Projects that contain only a single build type===<br />
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:<br />
<br />
# Create a directory in which you copy the files *.dsptemplate and CMakeVisualStudio6Configurations.cmake from CMake's Templates directory.<br />
# Edit the .cmake file and change the SET(CMAKE_CONFIGURATION_TYPES ...) line to set the build types that you want in your set.<br />
# Edit the *Header.dsptemplate files to contain only the configuration types you want in your set.<br />
# In your CMakeLists.txt file, set the MSPROJECT_TEMPLATE_DIRECTORY to the directory that you created.<br />
<br />
<br />
That's it. Run CMake and your new configuration files will be created.<br />
<br />
Note: Editing the *Header.dsptemplates files should be done very carefully. Here are some guidelines:<br />
<br />
- 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"')<br />
- 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.<br />
- 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.<br />
<br />
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:<br />
# PROP BASE Output_Dir ""<br />
# PROP BASE Intermediate_Dir ""<br />
# PROP Intermediate_Dir ""<br />
# PROP Output_Dir "LIBRARY_OUTPUT_PATH"<br />
or<br />
# PROP Output_Dir "EXECUTABLE_OUTPUT_PATH"<br />
<br />
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).<br />
<br />
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.<br />
<br />
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.)<br />
<br />
=== Can CMake set the Debugging/Working Directory property in Visual Studio projects? ===<br />
<br />
No. The value of this property is not stored in the project files. It is stored in extra files created by the IDE when a solution is loaded (VS .NET 2003 uses a hidden .suo file next to the .sln solution file). The format of these files is not known to CMake and cannot be generated. In some versions of VS the files are binary and not human readable.<br />
<br />
=== Why does CMakeSetup with the message "LINK : fatal error LNK1104: cannot open file 'user32.lib'" while configuring a project? ===<br />
<br />
The path to the SDK libs (user32.lib) must be added by the IDE when the<br />
project generator "Visual Studio 8 2005" is used, because cmake uses<br />
VCExpress.exe and on the fly generated project files to check<br />
for compiling (VCExpress.exe reads some config files for the<br />
compiler/linker options)<br />
<br />
So add the sdk lib path (...\Microsoft Platform SDK\Lib) at Tools->Options->Projects and Solutions->VC++ Directories->Library files<br />
<br />
See also:<br />
*http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/<br />
<br />
=== How can I avoid the error "Arg list too long" when running make? ===<br />
This error is sometimes encountered when building a static library with many object files using Unix make command. It typically looks something like this:<br />
<br />
<pre><br />
gmake[2]: execvp: /bin/sh: Arg list too long<br />
</pre><br />
<br />
When make tries to run the archiver program to build the static library the shell it uses complains that the argument list is too long. In some shells this can be fixed by setting an environment variable such as <tt>ARG_MAX</tt> to extend the length of the command line it will allow.<br />
<br />
=== How can I find out platforms definitions, search paths, etc. from gcc ?===<br />
<br />
The following is really the best if not only way to get information about predefined macros with a GNU compiler:<br />
<pre><br />
$ touch empty.c<br />
$ gcc -v -dD -E empty.c <br />
</pre><br />
This will give you all you might want to know about the preprocessor, the builtin include search dirs and all<br />
predefined definitions, so you can check whether it's __LINUX or _LINUX_ or _APPLE_ or __APPLE etc. <br />
The empty file and all these parameters are really required. You probably want to pipe the output (both stdout and stderr) to a file.<br />
If you want the information for C++, use a C++ file suffix for the empty file.<br />
<br />
This is how you can get the builtin library search paths:<br />
<pre><br />
$ gcc --print-search-dirs<br />
</pre><br />
<br />
=== How can I get a windows registry key ?===<br />
<br />
The only thing to know is that you can't use just the "SET" command in place of "GET" command.<br />
CMake read the value from the registry only when you "get" it from the cache. For instance :<br />
<br />
<pre><br />
GET_FILENAME_COMPONENT(SDK_ROOT_PATH "[HKEY_LOCAL_MACHINE\\SOFTWARE\\PACKAGE;Install_Dir]" ABSOLUTE CACHE)<br />
</pre><br />
<br />
If a key name (ex: Install_Dir in this case) was not specified , the Default key value will be get.<br />
Now you could use the SDK_ROOT_PATH to add include and lib path to your project :<br />
<br />
<pre><br />
INCLUDE_DIRECTORIES(<br />
${SDK_ROOT_PATH}/include<br />
)<br />
<br />
LINK_DIRECTORIES(<br />
${SDK_ROOT_PATH}/lib<br />
)<br />
</pre><br />
<br />
You can also read a registry key in the PATHS section of a FIND_LIBRARY, FIND_PATH, FIND_PROGRAM, or FIND_FILE command<br />
FIND_FILE(BOOT_DOT_INI boot.ini PATHS [HKEY_CURRENT_USER\\Environment;HOMEDRIVE])<br />
<br />
For other examples have a look in the CMake Modules folder :<br />
- FindJava.cmake<br />
- FindPythonLibs.cmake<br />
- ..<br />
<br />
=== How can I build my MSVC application with a static runtime? ===<br />
<br />
Here are two options you could employ to compile your MSVC application with /MT instead of /MD.<br />
<br />
==== Manual Replace ====<br />
<br />
You can rely on the user to modify CMAKE_C_FLAGS_DEBUG, CMAKE_C_FLAGS_RELEASE, CMAKE_CXX_FLAGS_DEBUG, CMAKE_CXX_FLAGS_RELEASE, etc. within the cache editor, replacing /MD with /MT after an initial configure of your software.<br />
<br />
==== Make Override Files ====<br />
<br />
If you intend to build the entire source tree using /MT and you don't<br />
need this ever to be configurable via the CMake GUI, the best approach<br />
is to create an override file which initializes the starting cache<br />
values for the compile flags.<br />
<br />
First create a c_flag_overrides.cmake & cxx_flag_overrides.cmake file which<br />
contain something like this... (or whatever flags you wish to use per compiler).<br />
<br />
'''NOTE:''' These files are only evaluated on the first run of CMake so they can't be dependent on a CMake option() meant to be toggled from the GUI, for example. They could be dependent on a command line -D option or an environment variable if desired.<br />
<br />
c_flag_overrides.cmake<br />
if(MSVC)<br />
set(CMAKE_C_FLAGS_DEBUG_INIT "/D_DEBUG /MTd /Zi /Ob0 /Od /RTC1")<br />
set(CMAKE_C_FLAGS_MINSIZEREL_INIT "/MT /O1 /Ob1 /D NDEBUG")<br />
set(CMAKE_C_FLAGS_RELEASE_INIT "/MT /O2 /Ob2 /D NDEBUG")<br />
set(CMAKE_C_FLAGS_RELWITHDEBINFO_INIT "/MT /Zi /O2 /Ob1 /D NDEBUG")<br />
endif()<br />
<br />
cxx_flag_overrides.cmake<br />
if(MSVC)<br />
set(CMAKE_CXX_FLAGS_DEBUG_INIT "/D_DEBUG /MTd /Zi /Ob0 /Od /RTC1")<br />
set(CMAKE_CXX_FLAGS_MINSIZEREL_INIT "/MT /O1 /Ob1 /D NDEBUG")<br />
set(CMAKE_CXX_FLAGS_RELEASE_INIT "/MT /O2 /Ob2 /D NDEBUG")<br />
set(CMAKE_CXX_FLAGS_RELWITHDEBINFO_INIT "/MT /Zi /O2 /Ob1 /D NDEBUG")<br />
endif()<br />
<br />
Then enable them by setting the following variables prior to the project() command.<br />
<br />
set(CMAKE_USER_MAKE_RULES_OVERRIDE<br />
${CMAKE_CURRENT_SOURCE_DIR}/c_flag_overrides.cmake)<br />
set(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX<br />
${CMAKE_CURRENT_SOURCE_DIR}/cxx_flag_overrides.cmake)<br />
project(Bar)<br />
<br />
==== Dynamic Replace ====<br />
<br />
Alternatively, if you need dynamic control of /MT via some configure option you could use the following technique. Note: CMAKE_CXX_FLAGS_<FOO> is a directory level option, however. Also, this option has the downside of leaving /MD in the cache.<br />
<br />
foreach(flag_var<br />
CMAKE_CXX_FLAGS CMAKE_CXX_FLAGS_DEBUG CMAKE_CXX_FLAGS_RELEASE<br />
CMAKE_CXX_FLAGS_MINSIZEREL CMAKE_CXX_FLAGS_RELWITHDEBINFO)<br />
if(${flag_var} MATCHES "/MD")<br />
string(REGEX REPLACE "/MD" "/MT" ${flag_var} "${${flag_var}}")<br />
endif(${flag_var} MATCHES "/MD")<br />
endforeach(flag_var)<br />
<br />
<br />
{{CMake/Template/Footer}}</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake_FAQ&diff=16689CMake FAQ2009-10-07T04:36:47Z<p>Plowman: /* How can I build my MSVC application with a static runtime? */ only two options listed at the moment</p>
<hr />
<div>== General information and availability ==<br />
=== What is CMake? ===<br />
CMake is a cross-platform, open-source make system. CMake is used to control the software compilation process using simple platform-independent 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 http://www.cmake.org/HTML/About.html to learn more about CMake.<br />
<br />
=== What is the current release? ===<br />
The latest release of CMake is always available at: http://www.cmake.org/HTML/Download.html<br />
<br />
From there, you can fetch CMake binaries for Windows or several Unix variants, or you can download the source code of CMake.<br />
<br />
You can also access nightly development through CVS; see http://www.cmake.org/HTML/Download.html for more information. You may also browse the [http://www.cmake.org/cgi-bin/viewcvs.cgi/?root=CMake cvs repository online].<br />
<br />
=== I found a Bug! What should I do? ===<br />
Please report the bug in our bug tracker: http://www.cmake.org/Bug<br />
<br />
Please make sure to look at the old bugs not to include duplicates, include detailed instructions of the bug and how to reproduce it.<br />
<br />
=== I want a new feature in CMake. What should I do? ===<br />
Report a feature request in our Bug tracker http://www.cmake.org/Bug<br />
<br />
Please make sure to look at the old feature requests not to include duplicates, include detailed instructions of the feature and proposed implementation.<br />
<br />
=== What is the most recent version covered by the Mastering CMake book? ===<br />
A new edition of the [http://www.kitware.com/products/cmakebook.html Mastering CMake] book has been released which documents CMake 2.6.<br />
<br />
The following features have been added since printing the book:<br />
<br />
* New INSTALL command (cmake --help-command INSTALL)<br />
* New LIST command (cmake --help-command LIST)<br />
* Updated FIND_PATH, FIND_PROGRAM, and FIND_FILE commands to be more powerful (cmake --help-command FIND_PATH)<br />
* RPATH and Mac OS X install_name support (cmake --help-command SET_TARGET_PROPERTIES)<br />
* CPack Beta (not finished or documented)<br />
* EXECUTE_PROCESS was added and replaces EXEC_PROGRAM<br />
* Other changes have been bug fixes and internal CMake restructuring<br />
<br />
=== Where can I find searchable CMake Mailing Archives? ===<br />
There exists at list those ones:<br />
* [http://dir.gmane.org/gmane.comp.programming.tools.cmake.user cmake on Gmane]<br />
* [http://www.mail-archive.com/cmake@cmake.org/ http://www.mail-archive.com/cmake@cmake.org/]<br />
* [http://marc.info/?l=cmake http://marc.info/?l=cmake]<br />
* Use google ''site'' keyword in order to search directly in the CMake browsable ML:<br />
site:http://www.cmake.org/pipermail/cmake/ <search terms><br />
<br />
== Running CMake ==<br />
<br />
=== Is there an option to produce more 'verbose' compiling? ===<br />
Set CMAKE_VERBOSE_MAKEFILE to ON. This will make generator to produce all outputs, including compiler lines.<br />
<br />
If you are on Windows using Borland or NMake Makefiles, then you will see lines like:<br />
<br />
cl @c:\DOCUME~1\ANDY~1.KIT\LOCALS~1\Temp\nma03504<br />
<br />
The reason for this is that Borland and Microsoft Visual Studio make programs have limitation on the length of command strings. They overcome this limitation by writing arguments to the file and then pass file to the program.<br />
<br />
If you actually want to see what the command looks like, set CMAKE_START_TEMP_FILE and CMAKE_END_TEMP_FILE to "".<br />
<br />
On Makefile generators, there is a shortcut by setting Makefile variable VERBOSE to 1. For example on UNIX:<br />
<br />
make VERBOSE=1<br />
<br />
and Windows:<br />
nmake /S force silent mode, overrides (CMAKE_VERBOSE_MAKFILE)<br />
<br />
=== Is there a way to skip checking of dependent libraries when compiling? ===<br />
<br />
'''Using the Makefile Generator'''<br />
<br />
When using the Makefile generator under *nix you can append "/fast" to your target name. For example:<br />
<br />
make target_name/fast<br />
<br />
Under Windows use a backslash instead:<br />
<br />
make target_name\fast<br />
<br />
'''Using Visual Studio >= 7.1'''<br />
<br />
If you have Visual Studio .NET 7.1 or greater you can use the native option to right click on a project and choose to build just that project.<br />
<br />
'''Using Visual Studio <= 7.0'''<br />
<br />
CMake doesn't try to compile all dependent libraries when you compile a library but it will do so for binary targets. You can't avoid this however you can take advantage of CTRL+F7 to manually compile a source file for the affected target and then relink the target by right clicking on it and choosing Link. You'll have to ensure that all dependent libraries are made up-to-date however or suffer through Visual's slow check.<br />
<br />
=== I set a cmake variable in my environment, but it didn't change anything. Why? ===<br />
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.<br />
<br />
=== I change CMAKE_C_COMPILER in the GUI but it changes back on the next configure step. Why? ===<br />
Once a build tree is created with a given compiler it cannot be changed. There are a variety of implementation reasons for this policy. In order to choose a different compiler create a new build tree and set the CC and CXX environment variables to the compiler you want before running CMake.<br />
<br />
NOTE: While I don't know what the preferred method of doing it is, I do know that the advice above (to set CC and CXX env vars) is in direct conflict with advice somewhere else that says not to use env vars to control CMAKE... Hopefully someone that knows a little more than I will fix this discrepancy.<br />
<br />
NOTE2: You could pass in e.g. <tt>-D CMAKE_C_COMPILER_INIT:STRING=mycc</tt> on the command line, or set the same variable inside a listfile (before any PROJECT() or ENABLE_LANGUAGE() command). Might that be what you're getting at?<br />
<br />
=== In CCMake, typing full paths is tedious. Is there a better way? ===<br />
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.<br />
<br />
For example:<br />
<br />
/usr/loc<TAB><br />
<br />
will expand to<br />
<br />
/usr/local/<br />
<br />
<br />
<br />
== Out-of-source build trees ==<br />
<br />
=== What is an "out-of-source" build? ===<br />
When your build generates files, they have to go somewhere. An in-source build puts them in your source tree. An out-of-source build puts them in a completely separate directory, so that your source tree is unchanged.<br />
<br />
In the first example, an in-place build is performed, i.e., the binaries are placed in the same directory as the source code.<br />
<br />
cd Hello<br />
ccmake .<br />
make<br />
<br />
In the second example, an out-of-place build is performed, i.e., the source code, libraries, and executables are produced in a directory separate from the source code directory(ies).<br />
<br />
mkdir HelloBuild<br />
cd HelloBuild<br />
ccmake ../Hello<br />
make<br />
<br />
Out-of-source builds are recommended, as you can build multiple variants in separate directories, e.g., HelloBuildDebug, HelloBuildRelease.<br />
<br />
Note: Before performing an out-of-source build ensure that any possible CMake generated in-source build information is removed from the source directory, e.g., CMakeFiles directory, and CMakeCache.txt.<br />
<br />
=== I run an out-of-source build but CMake generates in-source anyway. Why? ===<br />
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.<br />
<br />
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).<br />
<br />
=== Why does CMake use full paths, or can I copy my build tree? ===<br />
CMake uses full paths because:<br />
<br />
# configured header files may have full paths in them, and moving those files without re-configuring would cause upredictable behavior.<br />
# because cmake supports out of source builds, if custom commands used relative paths to the source tree, they would not work when they are run in the build tree because the current directory would be incorrect.<br />
# on Unix systems rpaths might be 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.<br />
<br />
Can the build tree be copied or moved?<br />
<br />
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 and rerun. Often when people want to move a binary tree it is so that they can distribute it to other users who may not have cmake in which case this would not work even if cmake would detect the move.<br />
<br />
The workaround is to create a new build tree without copying or moving the old one.<br />
<br />
<br />
=== CMake does not generate a "make distclean" target. Why? ===<br />
Some build trees created with GNU autotools have a "make distclean" target that cleans the build and also removes Makefiles and other parts of the generated build system. CMake does not generate a "make distclean" target because CMakeLists.txt files can run scripts and arbitrary commands; CMake has no way of tracking 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. (CMake does generate a "make clean" target to remove files generated by the compiler and linker.)<br />
<br />
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. Because CMake does not change the source tree, there is no need for a distclean target. One can start a fresh build by deleting the build tree or creating a separate build tree.<br />
<br />
(If a CMakeLists.txt uses ADD_CUSTOM_COMMAND to generate source files in the source tree, not the build tree, then in CMake 2.2 or higher "make clean" will remove them. See next question.)<br />
<br />
=== Running "make clean" does not remove custom command outputs. Why? ===<br />
In CMake 2.2 and higher custom command outputs should be removed by make clean. Make sure you are using at least this version. Prior to CMake 2.2 custom command outputs were not automatically added to the list of files to clean. In CMake 2.0 the 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.<br />
<br />
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 to clean away files that differ between builds.<br />
<br />
<br />
== Writing CMakeLists.txt ==<br />
<br />
=== How to have backward and forward compatibility? ===<br />
<br />
As of CMake 2.6 we employ a "Policy" mechanism to provide backwards compatibility.<br />
The basic requirement for projects is to include one line at the top of the highest CMakeLists.txt file:<br />
<br />
cmake_minimum_required(VERSION 2.6) # or other version<br />
<br />
This tells versions of CMake older than that specified that they are too old to build the project.<br />
They will report this information to the user.<br />
It also tells versions of CMake newer than that specified that the project may not be aware of policies introduced in later versions, which enables additional compatibility.<br />
For futher documentation, see<br />
<br />
* [[CMake_Policies|CMake Policy Mechanism]]<br />
* [http://www.cmake.org/cmake/help/cmake2.6docs.html#command:cmake_policy cmake_policy() command]<br />
* [http://www.cmake.org/cmake/help/cmake2.6docs.html#section_Policies CMake 2.6 Policies]<br />
<br />
=== How do I get the current source or binary directory? ===<br />
The variable CMAKE_CURRENT_SOURCE_DIR contains the absolute path to your current source directory, while CMAKE_CURRENT_BINARY_DIR points to the equivalent binary directory.<br />
<br />
=== Why are my CMake variables not updated in the GUI after a SET command? ===<br />
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.<br />
<br />
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:<br />
<br />
SET(BUILD_SHARED_LIBS ON)<br />
<br />
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.<br />
<br />
You can use the CACHE and FORCE options on the SET command to change variables in a way that will be reflected in the GUI. Run<br />
<br />
cmake --help-command SET<br />
<br />
to see full instructions for the command.<br />
<br />
<br />
=== How can I change the default build mode and see it reflected in the GUI? ===<br />
Adapt the following commands in your CMakeList.txt (this example sets the Release<br />
With Debug Information mode):<br />
<pre><br />
IF(NOT CMAKE_BUILD_TYPE)<br />
SET(CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING<br />
"Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel."<br />
FORCE)<br />
ENDIF(NOT CMAKE_BUILD_TYPE)<br />
</pre><br />
<br />
=== How do I generate an executable, then use the executable to generate a file? ===<br />
<br />
Create the generator executable by just adding a target:<br />
<br />
ADD_EXECUTABLE(generate generate.c)<br />
<br />
The rest of the process is simpler in CMake 2.6 and above than in previous versions.<br />
<br />
Use <code>ADD_CUSTOM_COMMAND</code> to specify a custom build rule for the file.<br />
(In this example we assume <code>generate</code> accepts the input and output files as arguments.)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT someoutput.txt<br />
COMMAND generate ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
DEPENDS generate ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt<br />
)<br />
<br />
This tells CMake how to build the file but does not actually add a rule to the build system.<br />
Another target must require it.<br />
One may create a custom target explicitly for this rule:<br />
<br />
ADD_CUSTOM_TARGET(driver ALL DEPENDS someoutput.txt)<br />
<br />
or the file may be added as part of some other target:<br />
<br />
ADD_EXECUTABLE(product product.c someoutput.txt)<br />
<br />
<font color=#555555><br />
In CMake 2.4 and below the <code>generate</code> target may not be specified directly in the <code>COMMAND</code> option of <code>add_custom_command</code><br />
(but it can still be used in the <code>DEPENDS</code> option as of CMake 2.4).<br />
Instead use GET_TARGET_PROPERTY to obtain the location of the generated executable.<br />
Additionally, the output must always be specified by full path.<br />
<br />
GET_TARGET_PROPERTY(GENERATE_EXE generate LOCATION)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
COMMAND ${GENERATE_EXE} ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
DEPENDS generate<br />
)<br />
</font><br />
<br />
=== How can I generate a source file during the build? ===<br />
The ADD_CUSTOM_COMMAND command lets you generate a source file that you can then include in another target. For example:<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
COMMAND ${CMAKE_COMMAND} copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.c ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.c<br />
)<br />
ADD_EXECUTABLE(foo foo.c)<br />
<br />
This will create an executable by copying bar.c to foo.c and then compiling foo.c to produce foo. CMake allows you to put generate source files in the current source or binary directory, so we were careful to output foo.c to the current binary directory. When we add foo.c to foo, CMake will look in either directory for it. Even if foo.c does not yet exist, CMake is smart enough to notice that a custom command creates it. (For the file named as the OUTPUT, CMake has its GENERATED source file property set to true.)<br />
<br />
You can also use ADD_CUSTOM_COMMAND when the<br />
[[CMake_FAQ#How_do_I_generate_an_executable.2C_then_use_the_executable_to_generate_a_file.3F|generator command is another executable in the same project]].<br />
<br />
Sometimes, the program doing the generation may generate multiple output files that each need to be part of the build. CMake 2.4 or higher supports having multiple files listed in the OUTPUT section. 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:<br />
<br />
PROJECT(FOO)<br />
# make sure cmake addes the binary directory for the project to the include path<br />
INCLUDE_DIRECTORIES(${FOO_BINARY_DIR})<br />
# add the executable that will do the generation<br />
ADD_EXECUTABLE(my_generator my_generator.cxx)<br />
GET_TARGET_PROPERTY(MY_GENERATOR_EXE my_generator LOCATION)<br />
# add the custom command that will generate all three files<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${FOO_BINARY_DIR}/output1.cpp ${FOO_BINARY_DIR}/output2.h ${FOO_BINARY_DIR}/output3.cpp<br />
COMMAND ${MY_GENERATOR_EXE} ${FOO_BINARY_DIR} ${FOO_SOURCE_DIR}/input.txt<br />
DEPENDS my_generator<br />
MAIN_DEPENDENCY ${FOO_SOURCE_DIR}/input.txt<br />
)<br />
# now create an executable using the generated files<br />
ADD_EXECUTABLE(generated<br />
${FOO_BINARY_DIR}/output1.cpp<br />
${FOO_BINARY_DIR}/output2.h<br />
${FOO_BINARY_DIR}/output3.cpp)<br />
<br />
CMake 2.4 allows you to generate a header file. Because generated headers often cause unnecessary rebuilds, you should try to avoid them; consider using the CONFIGURE_FILE command to prepare the header at CMake time. If you must generate a header file, use code like this:<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.h<br />
COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.h ${CMAKE_CURRENT_BINARY_DIR}/foo.h<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.h<br />
)<br />
ADD_EXECUTABLE(foo foo.c ${CMAKE_CURRENT_BINARY_DIR}/foo.h)<br />
<br />
This is like the first example above, except that it generates a header instead of a C file. The header might not exist when the build system scans foo.c's dependencies, so there is no way for CMake to know that this target requires foo.h unless we can tell it that foo.h may exist in the future. We give CMake this knowledge by listing the generated header file in the set of source files for the target. (This requires CMake 2.4. Previous versions of CMake required use of the OBJECT_DEPENDS source file property.)<br />
<br />
=== How can I add a dependency to a source file which is generated in a subdirectory? ===<br />
<br />
Rules created with <code>ADD_CUSTOM_COMMAND</code> as [[CMake_FAQ#How_can_I_generate_a_source_file_during_the_build.3F|above]] have scope only in the directory in which they are specified.<br />
If the generated file is needed in another directory, a target-level dependency needs to be added.<br />
Create a target in the subdirectory with the custom rule in order to drive it:<br />
<br />
# subdir/CMakeLists.txt<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
COMMAND ${CMAKE_COMMAND} copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.c ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.c<br />
)<br />
ADD_CUSTOM_TARGET(generate_foo DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/foo.c)<br />
<br />
Now other targets can depend on the target from the subdirectory:<br />
<br />
# CMakeLists.txt<br />
ADD_SUBDIRECTORY(subdir)<br />
# Create the executable.<br />
ADD_EXECUTABLE(generated ${CMAKE_CURRENT_BINARY_DIR}/subdir/foo.c)<br />
# Tell CMake the source won't be available until build time.<br />
SET_SOURCE_FILES_PROPERTIES(${CMAKE_CURRENT_BINARY_DIR}/subdir/foo.c PROPERTIES GENERATED 1)<br />
# Make sure the source is generated before the executable builds.<br />
ADD_DEPENDENCIES(generated generate_foo)<br />
<br />
=== I use EXEC_PROGRAM but the result is not set in subdirectories. Why? ===<br />
<br />
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 was fixed in CMake 2.2, but for older versions you will have to cache the result:<br />
<br />
<pre><br />
EXEC_PROGRAM(my-program OUTPUT_VARIABLE MY_OUTPUT)<br />
SET(MY_OUTPUT "${MY_OUTPUT}" CACHE INTERNAL "")<br />
</pre><br />
<br />
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.<br />
<br />
=== How can I get or set environment variables? ===<br />
<br />
CMake names environment variables using an ENV prefix and surrounding the names in curly braces. Here is an example:<br />
<br />
<pre><br />
MESSAGE("$ENV{PATH}")<br />
</pre><br />
<br />
Reading variables will work in any version of CMake. Writing to them works in CMake 2.2 and higher using the following syntax:<br />
<br />
<pre><br />
SET(ENV{HELLO} "World")<br />
</pre><br />
<br />
Note that there is currently no way to tell apart an empty environment variable value from a variable that is not set at all.<br />
<br />
One should avoid using environment variables for controlling the flow of CMake code (such as in IF commands). The build system generated by CMake may re-run CMake automatically when CMakeLists.txt files change. The environment in which this is executed is controlled by the build system and may not match that in which CMake was originally run. If you want to control build settings on the CMake command line, you need to use cache variables set with the -D option. The settings will be saved in CMakeCache.txt so that they don't have to be repeated every time CMake is run on the same build tree.<br />
<br />
Also, environment variables SET in the CMakeLists.txt ''only'' take effect for cmake itself, so you cannot use this method to set an environment variable that a custom command might need.<br />
<br />
=== Why do I have unwanted semicolons ; in my compiler flags? ===<br />
CMake has a list data type. A list is stored as a string of semicolon-separated list elements. Whitespace separated arguments to a SET statement are interpreted as list elements. For instance, SET(var a b c d e) will give "var" a value of a;b;c;d;e and this list can be used by other CMake commands. However, if you pass ${var} to a non-CMake external tool, such as a compiler's command line, you are passing a;b;c;d;e which is not what you want. Instead you either need to pass "${var}", so that the list will be converted to a whitespace-separated string, or you need to SET(var "a b c d e") in the 1st place so that you're working with a string, not a list.<br />
<br />
=== How can I get quoting and escapes to work properly? ===<br />
If you want to escape a character in CMake, you use "\", like in C code. For example, if you wanted to have a quote embedded in a string you would do this: "\"". However, each level of CMake that processes your code will need one level of escaping to work. So, if you configure a file that is read by cmake or cpack and you want to do the same thing, you would do "\\\"". You would still need to escape the " for the first cmake that processes the string. However, this time, you would want to also escape a '\' as well. This would leave the next level of processing with "\"". Also, for custom commands that may get passed to a shell, it maybe required to do escaping for that shell.<br />
<br />
=== Isn't the "Expression" in the "ELSE (Expression)" confusing? ===<br />
Traditional CMakeLists.txt files prior to 2.6.0, require the following syntax. In the IF syntax, the ELSE section requires the same (Expression) as the IF section. This sometimes can make the script kind of hard to follow, take the short example below:<br />
<br />
IF(WIN32)<br />
...do something...<br />
ELSE(WIN32)<br />
...do something else...<br />
ENDIF(WIN32)<br />
<br />
You might think that the ELSE section, here containing "...do something else...", is for the WIN32 portion of the script. That is not so! It is actually handling the NOT WIN32 section.<br />
<br />
As of CMake 2.6.0 the ELSE() and ENDIF() constructs can be empty. The same is true for closing constructs on ENDMACRO(), ENDFUNCTION(), and ENDFOREACH(). If you require 2.4.x compatibility, you can enable the CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS option on CMake 2.4.3 or greater. This option is superfluous on CMake 2.6.0 or greater.<br />
<br />
SET(CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS true)<br />
<br />
IF(WIN32)<br />
...do something...<br />
ELSEIF(APPLE)<br />
...do something else...<br />
ELSE()<br />
...do something else...<br />
ENDIF()<br />
<br />
=== Which regular expressions are supported by CMake? ===<br />
When using MATCHES or MATCHALL in an IF command, or using any of the STRING(REGEX ...) commands, CMake expects regular expressions, not globs (wild cards). CMake uses the same regular expression engine above all platforms. Here are the meanings of the metacharacters:<br />
<br />
^ Matches at beginning of a line<br />
$ Matches at end of a line<br />
. Matches any single character<br />
[ ] Matches any character(s) inside the brackets<br />
[^ ] Matches any character(s) not inside the brackets<br />
- Matches any character in range on either side of a dash<br />
| Matches a pattern on either side of the |<br />
* Matches preceding pattern zero or more times<br />
+ Matches preceding pattern one or more times<br />
? Matches preceding pattern zero or once only<br />
() Saves a matched expression and uses it in a later match<br />
<br />
Example: "[-][L]([^ ;])+" matches all strings beginning with -L and ending with a space or a semicolon, the usual linkdirs under Linux.<br />
<br />
Here is how to catch a part of a string. The variable test is filled with some content, and then we want to catch the "me":<br />
<br />
SET(test "hello world ! catch: me if you can")<br />
STRING(REGEX REPLACE ".*catch: ([^ ]+).*" "\\1" result "${test}" )<br />
MESSAGE(STATUS "result= ${result}")<br />
<br />
This is slightly tricky. The part inside the brackets is available in \\1 . CMake will copy the variable test to the variable result, but then it will replace everything that the regular expression matches with \\1. This means the first regular expression has to match the whole string and the part we want to catch has to be put in parens.<br />
<br />
-- result= me<br />
<br />
For those of you who know Perl, the equivalent Perl code could be:<br />
<br />
$test = "hello world ! catch: me if you can";<br />
$result = $test;<br />
$result =~ s/.*catch: ([^ ]+).*/$1/;<br />
print "-- result= $result\n";<br />
<br />
There are other ways to do this in Perl, but this is how we do it in CMake because \\1 does not become a variable like $1 does in perl, so there is no SET(result ${\\1}) in CMake.<br />
<br />
<br />
=== How to convert a semicolon separated list to a whitespace separated string? ===<br />
<br />
set(foo<br />
abc.c<br />
abc.b<br />
abc.a<br />
)<br />
<br />
foreach(arg ${foo})<br />
set(bar "${bar} ${arg}")<br />
endforeach(arg ${foo})<br />
<br />
message("foo: ${foo}")<br />
message("bar: ${bar}")<br />
<br />
=== How can I build multiple modes without switching ? ===<br />
To build multiple modes (e.g. Debug and Release) in one shot without constantly running cmake -DCMAKE_BUILD_TYPE=Debug and cmake -DCMAKE_BUILD_TYPE=Release in source tree create a directory for builds eg.:<br />
<br />
<pre><br />
Project-directory/<br />
/Build<br />
</pre><br />
<br />
Inside you can place as many target directories for out-of-source build modes as you want, e.g.:<br />
<br />
<pre><br />
Project-directory/<br />
/Build<br />
/Debug<br />
/Release<br />
</pre><br />
<br />
In each of these directories issue a command (assuming that you have CMakeLists.txt directly in Project-directory)<br />
<br />
<pre><br />
cmake -DCMAKE_BUILD_TYPE=type_of_build ../../<br />
</pre><br />
<br />
to create a cmake cache configured for requested build type.<br />
<br />
Now you can make each build just by entering appropriate directory and executing a make command.<br />
<br />
=== How can I extend the build modes with a custom made one ? ===<br />
The following code snipet (taken from a CMakeLists.txt) adds a Maintainer mode:<br />
<pre><br />
SET( CMAKE_CXX_FLAGS_MAINTAINER "-Wall -Wabi" CACHE STRING<br />
"Flags used by the C++ compiler during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_C_FLAGS_MAINTAINER "-Wall -pedantic" CACHE STRING<br />
"Flags used by the C compiler during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_EXE_LINKER_FLAGS_MAINTAINER<br />
"-Wl,--warn-unresolved-symbols,--warn-once" CACHE STRING<br />
"Flags used for linking binaries during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_SHARED_LINKER_FLAGS_MAINTAINER<br />
"-Wl,--warn-unresolved-symbols,--warn-once" CACHE STRING<br />
"Flags used by the shared libraries linker during maintainer builds."<br />
FORCE )<br />
MARK_AS_ADVANCED(<br />
CMAKE_CXX_FLAGS_MAINTAINER<br />
CMAKE_C_FLAGS_MAINTAINER<br />
CMAKE_EXE_LINKER_FLAGS_MAINTAINER<br />
CMAKE_SHARED_LINKER_FLAGS_MAINTAINER )<br />
# Update the documentation string of CMAKE_BUILD_TYPE for GUIs<br />
SET( CMAKE_BUILD_TYPE "" CACHE STRING<br />
"Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel Maintainer."<br />
FORCE )<br />
</pre><br />
Notes: The flags used in this example are specific to GCC. Change them as needed for your project. Additionally the SET(CMAKE_BUILD_TYPE) command will override<br />
a CMAKE_BUILD_TYPE previously set in the CMakeLists.txt.<br />
<br />
=== Why does <code>foreach</code> skip empty values? ===<br />
<br />
The code in question is of the form<br />
<br />
set(var "a;b;;c;d") # list 'a', 'b', '', 'c', 'd'<br />
foreach(v ${var})<br />
# v=a, v=b, v=c, v=d, one at a time<br />
endforeach()<br />
<br />
and the loop variable 'v' never attains the empty-string value ''.<br />
This is because the <code>${var}</code> syntax is an unquoted argument so the CMake language expands the list and removes the empty value.<br />
The foreach command does not even see the empty value.<br />
One can verify this because the code<br />
<br />
foreach(v a b "" c d)<br />
...<br />
endforeach()<br />
<br />
will see the empty value.<br />
<br />
=== Does CMake support precompiled headers? ===<br />
<br />
Yes and no. Every platform does precompiled headers a bit differently, and there is currently no first-class interface provided by CMake and implemented on every platform.<br />
However, CMake does provide enough primitives for projects to use precompiled headers on specific platforms.<br />
Our issue tracker has a [http://www.cmake.org/Bug/view.php?id=1260 feature request] with attachements providing user-contributed helper macros for some platforms.<br />
<br />
== Writing FindXXX.cmake files ==<br />
<br />
=== What are the rules to write a FindXXX.cmake file? ===<br />
<br />
Let's follow the instructions and the advices in the <br />
Modules/readme.txt [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/readme.txt?root=CMake&view=markup]<br />
file located in the CVS repository.<br />
<br />
=== Why does find_library look in system directories before its PATHS option? ===<br />
<br />
The code in question is often of the form<br />
<br />
find_library(FOO_LIBRARY NAMES foo PATHS /opt/foo/lib)<br />
<br />
CMake will find "<code>/usr/lib/libfoo.so</code>" instead of "<code>/opt/foo/lib/libfoo.so</code>" if both exist.<br />
The reason is that /opt/foo/lib is a <i>hard-coded guess</i> of the location.<br />
The documentation of <code>[http://www.cmake.org/cmake/help/cmake2.6docs.html#command:find_library find_library]</code> specifies the search order.<br />
User, project, and system configuration variables are always more local than hard-coded guesses and should override them, so<br />
the PATHS option is used last.<br />
<br />
Some find-modules compute probable locations based on other information <i>available from the system</i> such as a project-specific environment variable.<br />
The HINTS option (CMake 2.6 and higher) takes precedence over system directories specifically for this case:<br />
<br />
file(TO_CMAKE_PATH "$ENV{FOO_LIB_DIR}" FOO_LIB_DIR)<br />
find_library(FOO_LIBRARY NAMES foo HINTS ${FOO_LIB_DIR})<br />
<br />
CMake will find "<code>$ENV{FOO_LIB_DIR}/libfoo.so</code>" before "<code>/usr/lib/libfoo.so</code>".<br />
<br />
== Finding and using external packages ==<br />
<br />
=== How do I use CMake to generate SWIG wrapper libraries? ===<br />
<br />
CMake version 2 includes a module that supports the generation of SWIG wrapper libraries. The SWIG package defines the following macros: SWIG_ADD_MODULE and SWIG_LINK_LIBRARIES.<br />
<br />
<pre><br />
# This example shows how to use python<br />
# Currently these languages have been tested:<br />
# perl tcl ruby php4 pike<br />
<br />
FIND_PACKAGE(SWIG REQUIRED)<br />
INCLUDE(${SWIG_USE_FILE})<br />
<br />
FIND_PACKAGE(PythonLibs)<br />
INCLUDE_DIRECTORIES(${PYTHON_INCLUDE_PATH})<br />
<br />
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})<br />
<br />
SET(CMAKE_SWIG_FLAGS "")<br />
<br />
SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES CPLUSPLUS ON)<br />
SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES SWIG_FLAGS "-includeall")<br />
SWIG_ADD_MODULE(example python<br />
example.i example.cxx)<br />
SWIG_LINK_LIBRARIES(example ${PYTHON_LIBRARIES})<br />
<br />
</pre><br />
<br />
<pre><br />
# This example shows how to use tcl<br />
PROJECT(TCL_WRAP)<br />
SET ( MODULE_NAME project )<br />
SET ( INTERFACE_FILES project.i)<br />
SET ( SRC_FILES Vertex.h Vertex.cxx Shapes.h Shapes.cxx )<br />
<br />
FIND_PACKAGE(SWIG REQUIRED)<br />
INCLUDE(${SWIG_USE_FILE})<br />
<br />
# Look for TCL<br />
INCLUDE_DIRECTORIES(${TCL_INCLUDE_PATH})<br />
<br />
FIND_LIBRARY(TCL_LIBRARY NAMES tcl tcl84 tcl83 tcl82 tcl80<br />
PATHS /usr/lib /usr/local/lib)<br />
IF (TCL_LIBRARY)<br />
TARGET_ADD_LIBRARY (${MODULE_NAME} TCL_LIBRARY)<br />
ENDIF (TCL_LIBRARY)<br />
<br />
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})<br />
<br />
SET(CMAKE_SWIG_FLAGS "-c++")<br />
<br />
SET_SOURCE_FILES_PROPERTIES(${INTERFACE_FILES} PROPERTIES CPLUSPLUS ON)<br />
SET_SOURCE_FILES_PROPERTIES(${INTERFACE_FILES} PROPERTIES CMAKE_SWIG_FLAGS "-includeall")<br />
SWIG_ADD_MODULE(${MODULE_NAME} tcl ${INTERFACE_FILES} ${SRC_FILES})<br />
SWIG_LINK_LIBRARIES(${MODULE_NAME} ${TCL_LIBRARIES})<br />
</pre><br />
<br />
=== How do I use CMake to build LaTeX documents? ===<br />
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.<br />
<br />
PROJECT(Document)<br />
IF(LATEX_COMPILE)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${Document_BINARY_DIR}/TDocument.dvi<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.tex<br />
COMMAND ${LATEX_COMPILE} <br />
ARGS ${Document_SOURCE_DIR}/TDocument.tex <br />
)<br />
ENDIF(LATEX_COMPILE)<br />
<br />
IF(DVIPDF_COMPILE)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${Document_BINARY_DIR}/TDocument.pdf<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.dvi <br />
COMMAND ${DVIPDF_COMPILE}<br />
ARGS ${Document_SOURCE_DIR}/TDocument.dvi<br />
)<br />
ENDIF(DVIPDF_COMPILE)<br />
<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.pdf<br />
)<br />
<br />
The following uses commands in CMake version 2.0 and later<br />
<br />
PROJECT(Document)<br />
# <br />
# Find LaTeX<br />
#<br />
FIND_PACKAGE(LATEX)<br />
<br />
IF(LATEX_COMPILER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.dvi<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS ${Document_SOURCE_DIR}/TDocument.tex<br />
DEPENDS ${Document_SOURCE_DIR}/TDocument.tex<br />
COMMENT "Tex2dvi"<br />
)<br />
<br />
IF(DVIPS_CONVERTER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.ps<br />
COMMAND ${DVIPS_CONVERTER}<br />
ARGS ${Document_BINARY_DIR}/TDocument.dvi<br />
-o ${Document_BINARY_DIR}/TDocument.ps<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.dvi<br />
COMMENT "dvi2ps"<br />
)<br />
<br />
IF(PS2PDF_CONVERTER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.pdf<br />
COMMAND ${PS2PDF_CONVERTER}<br />
ARGS ${Document_BINARY_DIR}/TDocument.ps<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.ps<br />
COMMENT "ps2pdf"<br />
)<br />
<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.pdf<br />
)<br />
ENDIF(PS2PDF_CONVERTER)<br />
ENDIF(DVIPS_CONVERTER)<br />
ENDIF(LATEX_COMPILER)<br />
<br />
=== How do I get LaTeX references to be correct? ===<br />
When your latex document contains references (e.g. \ref{...} command) you get to run two passes of latex. In the<br />
most general case, i.e. when additionally your document uses a bibtex bibliography, you shall need three<br />
passes of latex (and one pass of bibtex):<br />
# latex (first pass: for bibtex to have an .aux file)<br />
# bibtex (for generating the .bbl file)<br />
# latex (second pass)<br />
# latex (third pass)<br />
<br />
The following code snippet illustrates how you can "pervert" the bibtex and latex generated<br />
auxilary files (.aux, .log, .dvi, .bbl...) to create an "artificial" set of CMake dependencies.<br />
The side-effect of those dependencies should hopefully be the above described sequence of calls<br />
to latex and bibtex<br />
<pre><br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.aux<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/UsersManual.tex<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (first pass)"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.aux<br />
COMMAND ${BIBTEX_COMPILER}<br />
ARGS -terse ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Bibtex"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.dvi<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (second pass)"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.log<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
${CMAKE_CURRENT_BINARY_DIR}/UsersManual.dvi<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (third pass)"<br />
)<br />
# Eventually trigger the whole process<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.log<br />
)<br />
</pre><br />
<br />
=== How can I set TEXINPUTS for a LaTeX compilation? ===<br />
First note that most often you can avoid using TEXINPUTS by copying all the necessary files (.tex source file and<br />
included graphic files e.g. .eps files) from your PROJECT_SOURCE_DIR hirarchy to your PROJECT_BINARY_DIR subdir<br />
[refer to CONFIGURE_FILE with the COPYONLY flag set for copying files]. Since by default latex uses the current working directory as value for TEXINPUTS you should be all set. As expected, this trick is quick AND dirty since your<br />
concerned PROJECT_BINARY_DIR subdir now contains files that are NOT generated by CMake (in the sense that those<br />
files are not the result of a system command but were merely duplicated)... <br />
<br />
If you consider it is cleaner or easier to define a TEXINPUTS environment variable [the latex command probably<br />
misses a -I flag] you can find an example in the InsightDocuments cvs archive (refer to the section "cvs access"<br />
near the bottom of Kitware's ITK download page) or use google with keywords "ITK_TEXINPUTS CONFIGURE_FILE".<br />
Look at InsightDocuments/CourseWare/Training/Vis2003/Latex/CMakeLists.txt and search for e.g. "LaTeXWrapper.sh.in".<br />
<br />
Roughly the mechanism goes:<br />
* SET ITK_TEXINPUTS with the desired TEXINPUTS<br />
* CONFIGURE_FILE "InsightDocuments/CourseWare/Training/Vis2003/LaTeXWrapper.sh.in" which generates an sh shell script setting the shell variable TEXINPUTS prior to running the latex command<br />
* use ADD_CUSTOM_COMMAND to invoke this shell script<br />
This very example is Win32 portable (except that LaTeXWrapper.bat.in generates a .bat shell script)<br />
<br />
== Library questions ==<br />
<br />
=== Can I build both shared and static libraries with one ADD_LIBRARY command? ===<br />
<br />
No. Each library you build must have a unique target name, i.e. the "libname" field of the ADD_LIBRARY command. That way, CMake can track dependencies separately for each library. Libraries can have the same OUTPUT_NAME, see the SET_TARGET_PROPERTIES command, but this is not the default.<br />
<br />
=== Does that mean I have to build all my library objects twice, once for shared and once for static?! I don't like that! ===<br />
<br />
In practice, most libraries have different defines and compiler flags for the shared vs. static cases. So you would have to build all your library objects twice anyways. However, if you happen to have '''''exactly''''' the same defines and compiler flags for the shared vs. static cases...<br />
<br />
...if you're using Linux and a GCC-style linker, you could do the following. Note that for this to work correctly on linux, the zzSTATIC source files should have been compiled with "-fPIC" to ensure they will work in a shared library.<br />
<br />
IF(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_COMPILER_IS_GNUCC)<br />
ADD_LIBRARY(zzSTATIC STATIC -fPIC)<br />
ADD_LIBRARY(zzDYNAMIC SHARED)<br />
TARGET_LINK_LIBRARIES(zzDYNAMIC -Wl,-whole-archive zzSTATIC -Wl,-no-whole-archive)<br />
ENDIF(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_COMPILER_IS_GNUCC)<br />
<br />
...if you want a cross-platform approach that works on all compilers, not just GCC or Linux, you could extract the locations of previously built object files and insert them directly into the libraries that need them. This is documented in [http://www.cmake.org/Bug/view.php?id=5155 CMake Feature Request #5155: standard way to locate object files]. Unfortunately this approach relies on CMake's internal implementation, and that implementation could change in the future, breaking your code.<br />
<br />
=== How do I make my shared and static libraries have the same root name, but different suffixes? ===<br />
Set the OUTPUT_NAME of your shared and static libraries to the same thing.<br />
<br />
ADD_LIBRARY(foo SHARED ${foo_sources})<br />
ADD_LIBRARY(foo-static STATIC ${foo_sources})<br />
// The library target "foo" already has a default OUTPUT_NAME of "foo", so we don't need to change it.<br />
// The library target "foo-static" has a default OUTPUT_NAME of "foo-static", so change it.<br />
SET_TARGET_PROPERTIES(foo-static PROPERTIES OUTPUT_NAME "foo")<br />
<br />
If you are building your shared and static libraries in the same directory, you will also need the following to keep your shared and static libraries from clobbering each other during the build.<br />
<br />
SET_TARGET_PROPERTIES(foo PROPERTIES CLEAN_DIRECT_OUTPUT 1)<br />
SET_TARGET_PROPERTIES(foo-static PROPERTIES CLEAN_DIRECT_OUTPUT 1)<br />
<br />
=== How do I rename a library after it has already been built? ===<br />
You don't rename it. It's been built! Its name is whatever CMakeLists.txt says it's supposed to be.<br />
<br />
Perhaps you want to copy the library to a different name. But, are you sure that's what you want to do? You could just change the name in your ADD_LIBRARY command or change its OUTPUT_NAME property using SET_TARGET_PROPERTY(). If you really really want to copy the library to a different name, try:<br />
<br />
GET_TARGET_PROPERTY(LIB_NAME Foo LOCATION)<br />
GET_TARGET_PROPERTY(Bar_prefix Foo PREFIX)<br />
GET_TARGET_PROPERTY(Bar_suffix Foo SUFFIX)<br />
SET(NEW_LIB_NAME ${Bar_prefix}Bar${Bar_suffix})<br />
<br />
ADD_CUSTOM_COMMAND(<br />
TARGET Foo<br />
POST_BUILD<br />
COMMAND ${CMAKE_COMMAND} -E copy ${LIB_NAME} ${NEW_LIB_NAME}<br />
)<br />
<br />
On Windows you may also want to copy the .dll import lib, using the same approach as above, but with IMPORT_PREFIX and IMPORT_SUFFIX. ''Problem: LOCATION only refers to 1 file, the .dll. What is a simple way to get the location of the import lib? Could provide a complicated way, but that's annoying.''<br />
<br />
=== Does CMake support "convenience" libraries? ===<br />
No. CMake does not currently support convenience libraries. A "convenience" library, as GNU libtool calls it, is an archive of objects to be mixed into other libraries. Other libraries "link" to the convenience library, but the convenience library does not export any symbols; GNU libtool never installs the convenience library; no programs ever link to the convenience library.<br />
<br />
This does '''not''' mean that a project using convenience libraries cannot be converted to CMake. Instead the source files may be listed in each target that needs them. They will be built for each target separately using all the preprocessor definitions and flags configured for that target.<br />
<br />
=== Why are libraries linked to my shared library included when something links to it? ===<br />
This question arises when one has a library B which links to some library A. When a third target, say C, links to B, CMake will automatically include C to A also. When the libraries are static, then this is always necessary. When the libraries are shared, this is the default behavior provided by CMake. CMake 2.6 and above provide the target property "LINK_INTERFACE_LIBRARIES" (http://www.cmake.org/HTML/cmake-2.6.html#prop_tgt:LINK_INTERFACE_LIBRARIES) to specify the libraries that should be transitively included in the link by CMake. CMake 2.4 and below do not support the property.<br />
<br />
Something like the following will work in CMake 2.6:<br />
<br />
<pre><br />
set_target_properties(mylibrary<br />
PROPERTIES<br />
LINK_INTERFACE_LIBRARIES ""<br />
)<br />
</pre><br />
<br />
=== CMake dependency scanner ===<br />
<br />
CMake does not preprocess source files while scanning dependencies. Code like<br />
<pre><br />
#if 0<br />
# include "bla.h"<br />
#endif<br />
</pre><br />
will result in a dependency on "bla.h". This sometimes leads to source files recompiling unnecessarily but will not break the build.<br />
<br />
== Installation questions ==<br />
<br />
=== Does CMake's "make install" support DESTDIR? ===<br />
'''Yes''', especially when the build-system generator uses CMake's builtin support for installing files: Simply define the DESTDIR environment variable during installation and CMake will treat that value as the root of the file system for all installation paths; naturally, the DESTDIR path must be absolute.<br />
<br />
For example, if the Makefile generator is used, then all of the following are example usages of DESTDIR (perhaps assuming the bash shell for the last 2):<br />
<br />
(1) make install DESTDIR="/some/absolute/path"<br />
(2) make DESTDIR="/some/absolute/path" install<br />
(3) DESTDIR="/some/absolute/path" make install<br />
(4) export DESTDIR="/some/absolute/path<br />
make install<br />
<br />
=== Can I do "make uninstall" with CMake?===<br />
By default, CMake does not provide the "make uninstall" target, so you cannot do this. We do not want "make uninstall" to remove useful files from the system.<br />
<br />
If you want an "uninstall" target in your project, then nobody prevents you from providing one. You need to delete the files listed in install_manifest.txt file. Here is how to do it. First create file cmake_uninstall.cmake.in in the top-level directory of the project:<br />
<br />
<pre><br />
IF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")<br />
MESSAGE(FATAL_ERROR "Cannot find install manifest: \"@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt\"")<br />
ENDIF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")<br />
<br />
FILE(READ "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt" files)<br />
STRING(REGEX REPLACE "\n" ";" files "${files}")<br />
FOREACH(file ${files})<br />
MESSAGE(STATUS "Uninstalling \"$ENV{DESTDIR}${file}\"")<br />
IF(EXISTS "$ENV{DESTDIR}${file}")<br />
EXEC_PROGRAM(<br />
"@CMAKE_COMMAND@" ARGS "-E remove \"$ENV{DESTDIR}${file}\""<br />
OUTPUT_VARIABLE rm_out<br />
RETURN_VALUE rm_retval<br />
)<br />
IF(NOT "${rm_retval}" STREQUAL 0)<br />
MESSAGE(FATAL_ERROR "Problem when removing \"$ENV{DESTDIR}${file}\"")<br />
ENDIF(NOT "${rm_retval}" STREQUAL 0)<br />
ELSE(EXISTS "$ENV{DESTDIR}${file}")<br />
MESSAGE(STATUS "File \"$ENV{DESTDIR}${file}\" does not exist.")<br />
ENDIF(EXISTS "$ENV{DESTDIR}${file}")<br />
ENDFOREACH(file)<br />
</pre><br />
<br />
Then in the top-level CMakeLists.txt add the following logic:<br />
<br />
<pre><br />
CONFIGURE_FILE(<br />
"${CMAKE_CURRENT_SOURCE_DIR}/cmake_uninstall.cmake.in"<br />
"${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake"<br />
IMMEDIATE @ONLY)<br />
<br />
ADD_CUSTOM_TARGET(uninstall<br />
"${CMAKE_COMMAND}" -P "${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake")<br />
</pre><br />
<br />
Now you will have an "uninstall" target at the top-level directory of your build tree.<br />
<br />
Instead of creating an "uninstall" target, Unix users could enter this command in the shell:<br />
<br />
xargs rm < install_manifest.txt<br />
<br />
== Distribution questions ==<br />
<br />
=== Where is "make dist"? ===<br />
<br />
CMake doesn't create a "make dist" target.<br />
<br />
=== What is the best way to distribute source code or binaries for a cmake-based project? ===<br />
<br />
For creating source or binary packages there is now [[CMake#CPack | CPack]] coming with CMake, see the <br />
[[ CMake#CPack | documentation]].<br />
<br />
Of course you can also use any other ways to create packages.<br />
<br />
== Platform-specific questions ==<br />
=== How do I build universal binaries on Mac OS X? ===<br />
Before running CMake with an empty build tree, set the CMAKE_OSX_ARCHITECTURES environment variable. It should be set to contain a ; separated list of architectures that you want in the binary. For example, for 32-bit PowerPC and Intel you would do this:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386<br />
<br />
If you wish to build both as 32 and 64 bit, do this:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386;ppc64;x86_64<br />
<br />
You can also set the same named CMake cache variable on an existing binary tree. This works with both makefiles and the Xcode generator. <br />
<br />
In addition, you can also set the CMAKE_OSX_SYSROOT variable to point to the sysroot (aka Mac OS SDK) to be used. CMake will attempt to pick one on your system, but it can be changed in the cache or via an environment variable before running CMake. The 10.4u SDK or later must be used to create a Universal Binary.<br />
<br />
Universal Binaries are essentially cross compilation and so you should avoid using TRY_RUN, especially for things like testing endianess or variable size because the result will only be correct for one architecture.<br />
<br />
Lastly, note that CTest is only able to test one architecture. See bug 6157.<br />
<br />
=== How can I apply resources on Mac OS X automatically? ===<br />
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 a custom rule which is executed after the executable is linked:<br />
<br />
<pre><br />
ADD_EXECUTABLE(MyExecutable ${MyExecutable_SRCS})<br />
GET_TARGET_PROPERTY(MyExecutable_PATH MyExecutable LOCATION)<br />
<br />
IF(APPLE)<br />
FIND_PROGRAM(APPLE_RESOURCE Rez /Developer/Tools)<br />
IF(APPLE_RESOURCE)<br />
ADD_CUSTOM_COMMAND(TARGET MyExecutable POST_BUILD<br />
COMMAND ${APPLE_RESOURCE} Carbon.r -o ${MyExecutable_PATH})<br />
ENDIF(APPLE_RESOURCE)<br />
ENDIF(APPLE)<br />
</pre><br />
<br />
This will execute:<br />
<br />
/Developer/Tools/Rez Carbon.r -o /binary/path/MyExecutable<br />
<br />
after MyExecutable is linked.<br />
<br />
'Rez' may be located elsewhere on disk, depending on the version of Mac OS X and Xcode. You can use 'which Rez' in Terminal to find it's full path.<br />
<br />
=== Why does FIND_LIBRARY not find .DLL libraries under WIN32? ===<br />
For those who come from a Unix background to MS Windows:<br />
<br />
You never link directly to the .dll, you have to link against the import library .lib for the .dll.<br />
<br />
Linking against dynamic libraries (.dll under Windows) is quite different from linking against ELF shared objects (.so) under platforms like Linux or NetBSD. In Windows, there are two types of library, a static library and an import library (both confusingly use the .lib extension, however). In Windows, when you build an import library (A.lib) you will get a corresponding (A.dll) that you only need at runtime. At compile time you will need the import library.<br />
<br />
Conclusion: There is no need to find a .dll for linking. You only need to find the .lib import library.<br />
<br />
Some more details can be found here: [http://xenophilia.org/winvunix.html].<br />
<br />
=== Why am I getting a linker error to _mainCRTStartup under WIN32? ===<br />
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.<br />
<br />
ADD_EXECUTABLE(exename WIN32 source1 source2 ... sourceN)<br />
<br />
The second argument to ADD_EXECUTABLE can be WIN32. This indicates that the executable, when compiled on Windows, is a Windows app (using WinMain) and not a console app (using main). Please note that on Unix platforms, CMake ignores the WIN32 and the compiler will use "main" in any case.<br />
<br />
=== Why do I get this error: nafxcwd.lib(appcore.obj) : error LNK2001: unresolved external symbol ___argv ===<br />
<br />
This is because the application is using both the static and dll versions of the MFC library.<br />
To fix the problem, you can do the following:<br />
<br />
SET(CMAKE_MFC_FLAG 2) # force the IDE to use static MFC<br />
ADD_DEFINITIONS(-D_AFXDLL) # make sure if afx.h is included the dll MFC is used<br />
<br />
=== How to use MFC with CMake ===<br />
To use MFC, the CMAKE_MFC_FLAG variable must be set as follows:<br />
<br />
0: Use Standard Windows Libraries<br />
1: Use MFC in a Static Library<br />
2: Use MFC in a Shared DLL <br />
<br />
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:<br />
<br />
ADD_DEFINITIONS(-D_AFXDLL)<br />
SET(CMAKE_MFC_FLAG 2) <br />
ADD_EXECUTABLE(CMakeSetup WIN32 ${SRCS})<br />
<br />
Note that visual studio 9 project files do not appear to work with CMAKE_MFC_FLAG 1; this may be related to [http://www.cmake.org/Bug/view.php?id=7056 bug 7056].<br />
<br />
In order to use MFC with UNICODE, you must also [http://msdn.microsoft.com/en-us/library/dybsewaf.aspx specify the entry point wWinMainCRTStartup]. For example:<br />
<br />
set(CMAKE_MFC_FLAG 2)<br />
set_target_properties(MyApp PROPERTIES<br />
COMPILE_DEFINITIONS _AFXDLL,_UNICODE,UNICODE,_BIND_TO_CURRENT_CRT_VERSION,_BIND_TO_CURRENT_MFC_VERSION<br />
LINK_FLAGS "/ENTRY:\"wWinMainCRTStartup\"")<br />
<br />
See [http://stackoverflow.com/questions/59635/app-does-not-run-with-vs-2008-sp1-dlls-previous-version-works-with-rtm-versions this article] as to why _BIND_TO_CURRENT_CRT_VERSION and _BIND_TO_CURRENT_MFC_VERSION are necessary for Visual Studio 2008 SP1.<br />
<br />
=== How To Put Files in Folders in Visual Studio Projects ===<br />
The Visual Studio IDE supports putting files into folders.<br />
CMake can be used to put files in folders with the SOURCE_GROUP <br />
command. <br />
<br />
SOURCE_GROUP(name [REGULAR_EXPRESSION regex] [FILES src1 src2 ...])<br />
<br />
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 provided the source file is being passed to ADD_EXECUTABLE or ADD_LIBRARY.<br />
<br />
For example:<br />
SOURCE_GROUP(FooFiles FILES foo.cxx)<br />
SOURCE_GROUP(BarFiles FILES bar.cxx)<br />
ADD_LIBRARY(foo foo.cxx bar.cxx)<br />
<br />
In the event 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).<br />
<br />
As a convenience to developers CMake automatically adds standard header files to a "Header Files" folder and standard source files to a "Source Files" folder for Visual Studio Projects. This can be overridden via the SOURCE_GROUP method documented above.<br />
<br />
=== How to create Visual Studio 6 Projects that contain only a single build type===<br />
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:<br />
<br />
# Create a directory in which you copy the files *.dsptemplate and CMakeVisualStudio6Configurations.cmake from CMake's Templates directory.<br />
# Edit the .cmake file and change the SET(CMAKE_CONFIGURATION_TYPES ...) line to set the build types that you want in your set.<br />
# Edit the *Header.dsptemplate files to contain only the configuration types you want in your set.<br />
# In your CMakeLists.txt file, set the MSPROJECT_TEMPLATE_DIRECTORY to the directory that you created.<br />
<br />
<br />
That's it. Run CMake and your new configuration files will be created.<br />
<br />
Note: Editing the *Header.dsptemplates files should be done very carefully. Here are some guidelines:<br />
<br />
- 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"')<br />
- 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.<br />
- 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.<br />
<br />
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:<br />
# PROP BASE Output_Dir ""<br />
# PROP BASE Intermediate_Dir ""<br />
# PROP Intermediate_Dir ""<br />
# PROP Output_Dir "LIBRARY_OUTPUT_PATH"<br />
or<br />
# PROP Output_Dir "EXECUTABLE_OUTPUT_PATH"<br />
<br />
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).<br />
<br />
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.<br />
<br />
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.)<br />
<br />
=== Can CMake set the Debugging/Working Directory property in Visual Studio projects? ===<br />
<br />
No. The value of this property is not stored in the project files. It is stored in extra files created by the IDE when a solution is loaded (VS .NET 2003 uses a hidden .suo file next to the .sln solution file). The format of these files is not known to CMake and cannot be generated. In some versions of VS the files are binary and not human readable.<br />
<br />
=== Why does CMakeSetup with the message "LINK : fatal error LNK1104: cannot open file 'user32.lib'" while configuring a project? ===<br />
<br />
The path to the SDK libs (user32.lib) must be added by the IDE when the<br />
project generator "Visual Studio 8 2005" is used, because cmake uses<br />
VCExpress.exe and on the fly generated project files to check<br />
for compiling (VCExpress.exe reads some config files for the<br />
compiler/linker options)<br />
<br />
So add the sdk lib path (...\Microsoft Platform SDK\Lib) at Tools->Options->Projects and Solutions->VC++ Directories->Library files<br />
<br />
See also:<br />
*http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/<br />
<br />
=== How can I avoid the error "Arg list too long" when running make? ===<br />
This error is sometimes encountered when building a static library with many object files using Unix make command. It typically looks something like this:<br />
<br />
<pre><br />
gmake[2]: execvp: /bin/sh: Arg list too long<br />
</pre><br />
<br />
When make tries to run the archiver program to build the static library the shell it uses complains that the argument list is too long. In some shells this can be fixed by setting an environment variable such as <tt>ARG_MAX</tt> to extend the length of the command line it will allow.<br />
<br />
=== How can I find out platforms definitions, search paths, etc. from gcc ?===<br />
<br />
The following is really the best if not only way to get information about predefined macros with a GNU compiler:<br />
<pre><br />
$ touch empty.c<br />
$ gcc -v -dD -E empty.c <br />
</pre><br />
This will give you all you might want to know about the preprocessor, the builtin include search dirs and all<br />
predefined definitions, so you can check whether it's __LINUX or _LINUX_ or _APPLE_ or __APPLE etc. <br />
The empty file and all these parameters are really required. You probably want to pipe the output (both stdout and stderr) to a file.<br />
If you want the information for C++, use a C++ file suffix for the empty file.<br />
<br />
This is how you can get the builtin library search paths:<br />
<pre><br />
$ gcc --print-search-dirs<br />
</pre><br />
<br />
=== How can I get a windows registry key ?===<br />
<br />
The only thing to know is that you can't use just the "SET" command in place of "GET" command.<br />
CMake read the value from the registry only when you "get" it from the cache. For instance :<br />
<br />
<pre><br />
GET_FILENAME_COMPONENT(SDK_ROOT_PATH "[HKEY_LOCAL_MACHINE\\SOFTWARE\\PACKAGE;Install_Dir]" ABSOLUTE CACHE)<br />
</pre><br />
<br />
If a key name (ex: Install_Dir in this case) was not specified , the Default key value will be get.<br />
Now you could use the SDK_ROOT_PATH to add include and lib path to your project :<br />
<br />
<pre><br />
INCLUDE_DIRECTORIES(<br />
${SDK_ROOT_PATH}/include<br />
)<br />
<br />
LINK_DIRECTORIES(<br />
${SDK_ROOT_PATH}/lib<br />
)<br />
</pre><br />
<br />
You can also read a registry key in the PATHS section of a FIND_LIBRARY, FIND_PATH, FIND_PROGRAM, or FIND_FILE command<br />
FIND_FILE(BOOT_DOT_INI boot.ini PATHS [HKEY_CURRENT_USER\\Environment;HOMEDRIVE])<br />
<br />
For other examples have a look in the CMake Modules folder :<br />
- FindJava.cmake<br />
- FindPythonLibs.cmake<br />
- ..<br />
<br />
=== How can I build my MSVC application with a static runtime? ===<br />
<br />
Here are two options you could employ to compile your MSVC application with /MT instead of /MD.<br />
<br />
==== Manual Replace ====<br />
<br />
You can rely on the user to modify CMAKE_C_FLAGS_DEBUG, CMAKE_C_FLAGS_RELEASE, CMAKE_CXX_FLAGS_DEBUG, CMAKE_CXX_FLAGS_RELEASE, etc. within the cache editor, replacing /MD with /MT after an initial configure of your software.<br />
<!--<br />
<br />
Not quite ready for primetime...<br />
==== Make Override Files ====<br />
<br />
If you intend to build the entire source tree using /MT and you don't<br />
need this ever to be configurable via the CMake GUI, the best approach<br />
is to create an override file which initializes the starting cache<br />
values for the compile flags.<br />
<br />
First create a c_flag_overrides.cmake & cxx_flag_overrides.cmake file which<br />
contain something like this... (or whatever flags you wish to use).<br />
<br />
c_flag_overrides.cmake<br />
set(CMAKE_C_FLAGS_DEBUG_INIT "/D_DEBUG /MTd /Zi /Ob0 /Od /RTC1")<br />
set(CMAKE_C_FLAGS_MINSIZEREL_INIT "/MT /O1 /Ob1 /D NDEBUG")<br />
set(CMAKE_C_FLAGS_RELEASE_INIT "/MT /O2 /Ob2 /D NDEBUG")<br />
set(CMAKE_C_FLAGS_RELWITHDEBINFO_INIT "/MT /Zi /O2 /Ob1 /D NDEBUG")<br />
<br />
cxx_flag_overrides.cmake<br />
set(CMAKE_CXX_FLAGS_DEBUG_INIT "/D_DEBUG /MTd /Zi /Ob0 /Od /RTC1")<br />
set(CMAKE_CXX_FLAGS_MINSIZEREL_INIT "/MT /O1 /Ob1 /D NDEBUG")<br />
set(CMAKE_CXX_FLAGS_RELEASE_INIT "/MT /O2 /Ob2 /D NDEBUG")<br />
set(CMAKE_CXX_FLAGS_RELWITHDEBINFO_INIT "/MT /Zi /O2 /Ob1 /D NDEBUG")<br />
<br />
Then enable them by placing the following prior to the project() command:<br />
<br />
set(CMAKE_USER_MAKE_RULES_OVERRIDE<br />
${CMAKE_CURRENT_SOURCE_DIR}/c_flag_overrides.cmake)<br />
set(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX<br />
${CMAKE_CURRENT_SOURCE_DIR}/cxx_flag_overrides.cmake)<br />
project(Bar)<br />
<br />
--><br />
==== Dynamic Replace ====<br />
<br />
Alternatively, if you need dynamic control of /MT via some configure option you could use the following technique. Note: CMAKE_CXX_FLAGS_<FOO> is a directory level option, however. Also, this option has the downside of leaving /MD in the cache.<br />
<br />
foreach(flag_var<br />
CMAKE_CXX_FLAGS CMAKE_CXX_FLAGS_DEBUG CMAKE_CXX_FLAGS_RELEASE<br />
CMAKE_CXX_FLAGS_MINSIZEREL CMAKE_CXX_FLAGS_RELWITHDEBINFO)<br />
if(${flag_var} MATCHES "/MD")<br />
string(REGEX REPLACE "/MD" "/MT" ${flag_var} "${${flag_var}}")<br />
endif(${flag_var} MATCHES "/MD")<br />
endforeach(flag_var)<br />
<br />
<br />
{{CMake/Template/Footer}}</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake_FAQ&diff=16688CMake FAQ2009-10-07T04:36:07Z<p>Plowman: /* How can I build my MSVC application with a static runtime? */ added commented out howto re. override pending better solution and manual option</p>
<hr />
<div>== General information and availability ==<br />
=== What is CMake? ===<br />
CMake is a cross-platform, open-source make system. CMake is used to control the software compilation process using simple platform-independent 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 http://www.cmake.org/HTML/About.html to learn more about CMake.<br />
<br />
=== What is the current release? ===<br />
The latest release of CMake is always available at: http://www.cmake.org/HTML/Download.html<br />
<br />
From there, you can fetch CMake binaries for Windows or several Unix variants, or you can download the source code of CMake.<br />
<br />
You can also access nightly development through CVS; see http://www.cmake.org/HTML/Download.html for more information. You may also browse the [http://www.cmake.org/cgi-bin/viewcvs.cgi/?root=CMake cvs repository online].<br />
<br />
=== I found a Bug! What should I do? ===<br />
Please report the bug in our bug tracker: http://www.cmake.org/Bug<br />
<br />
Please make sure to look at the old bugs not to include duplicates, include detailed instructions of the bug and how to reproduce it.<br />
<br />
=== I want a new feature in CMake. What should I do? ===<br />
Report a feature request in our Bug tracker http://www.cmake.org/Bug<br />
<br />
Please make sure to look at the old feature requests not to include duplicates, include detailed instructions of the feature and proposed implementation.<br />
<br />
=== What is the most recent version covered by the Mastering CMake book? ===<br />
A new edition of the [http://www.kitware.com/products/cmakebook.html Mastering CMake] book has been released which documents CMake 2.6.<br />
<br />
The following features have been added since printing the book:<br />
<br />
* New INSTALL command (cmake --help-command INSTALL)<br />
* New LIST command (cmake --help-command LIST)<br />
* Updated FIND_PATH, FIND_PROGRAM, and FIND_FILE commands to be more powerful (cmake --help-command FIND_PATH)<br />
* RPATH and Mac OS X install_name support (cmake --help-command SET_TARGET_PROPERTIES)<br />
* CPack Beta (not finished or documented)<br />
* EXECUTE_PROCESS was added and replaces EXEC_PROGRAM<br />
* Other changes have been bug fixes and internal CMake restructuring<br />
<br />
=== Where can I find searchable CMake Mailing Archives? ===<br />
There exists at list those ones:<br />
* [http://dir.gmane.org/gmane.comp.programming.tools.cmake.user cmake on Gmane]<br />
* [http://www.mail-archive.com/cmake@cmake.org/ http://www.mail-archive.com/cmake@cmake.org/]<br />
* [http://marc.info/?l=cmake http://marc.info/?l=cmake]<br />
* Use google ''site'' keyword in order to search directly in the CMake browsable ML:<br />
site:http://www.cmake.org/pipermail/cmake/ <search terms><br />
<br />
== Running CMake ==<br />
<br />
=== Is there an option to produce more 'verbose' compiling? ===<br />
Set CMAKE_VERBOSE_MAKEFILE to ON. This will make generator to produce all outputs, including compiler lines.<br />
<br />
If you are on Windows using Borland or NMake Makefiles, then you will see lines like:<br />
<br />
cl @c:\DOCUME~1\ANDY~1.KIT\LOCALS~1\Temp\nma03504<br />
<br />
The reason for this is that Borland and Microsoft Visual Studio make programs have limitation on the length of command strings. They overcome this limitation by writing arguments to the file and then pass file to the program.<br />
<br />
If you actually want to see what the command looks like, set CMAKE_START_TEMP_FILE and CMAKE_END_TEMP_FILE to "".<br />
<br />
On Makefile generators, there is a shortcut by setting Makefile variable VERBOSE to 1. For example on UNIX:<br />
<br />
make VERBOSE=1<br />
<br />
and Windows:<br />
nmake /S force silent mode, overrides (CMAKE_VERBOSE_MAKFILE)<br />
<br />
=== Is there a way to skip checking of dependent libraries when compiling? ===<br />
<br />
'''Using the Makefile Generator'''<br />
<br />
When using the Makefile generator under *nix you can append "/fast" to your target name. For example:<br />
<br />
make target_name/fast<br />
<br />
Under Windows use a backslash instead:<br />
<br />
make target_name\fast<br />
<br />
'''Using Visual Studio >= 7.1'''<br />
<br />
If you have Visual Studio .NET 7.1 or greater you can use the native option to right click on a project and choose to build just that project.<br />
<br />
'''Using Visual Studio <= 7.0'''<br />
<br />
CMake doesn't try to compile all dependent libraries when you compile a library but it will do so for binary targets. You can't avoid this however you can take advantage of CTRL+F7 to manually compile a source file for the affected target and then relink the target by right clicking on it and choosing Link. You'll have to ensure that all dependent libraries are made up-to-date however or suffer through Visual's slow check.<br />
<br />
=== I set a cmake variable in my environment, but it didn't change anything. Why? ===<br />
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.<br />
<br />
=== I change CMAKE_C_COMPILER in the GUI but it changes back on the next configure step. Why? ===<br />
Once a build tree is created with a given compiler it cannot be changed. There are a variety of implementation reasons for this policy. In order to choose a different compiler create a new build tree and set the CC and CXX environment variables to the compiler you want before running CMake.<br />
<br />
NOTE: While I don't know what the preferred method of doing it is, I do know that the advice above (to set CC and CXX env vars) is in direct conflict with advice somewhere else that says not to use env vars to control CMAKE... Hopefully someone that knows a little more than I will fix this discrepancy.<br />
<br />
NOTE2: You could pass in e.g. <tt>-D CMAKE_C_COMPILER_INIT:STRING=mycc</tt> on the command line, or set the same variable inside a listfile (before any PROJECT() or ENABLE_LANGUAGE() command). Might that be what you're getting at?<br />
<br />
=== In CCMake, typing full paths is tedious. Is there a better way? ===<br />
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.<br />
<br />
For example:<br />
<br />
/usr/loc<TAB><br />
<br />
will expand to<br />
<br />
/usr/local/<br />
<br />
<br />
<br />
== Out-of-source build trees ==<br />
<br />
=== What is an "out-of-source" build? ===<br />
When your build generates files, they have to go somewhere. An in-source build puts them in your source tree. An out-of-source build puts them in a completely separate directory, so that your source tree is unchanged.<br />
<br />
In the first example, an in-place build is performed, i.e., the binaries are placed in the same directory as the source code.<br />
<br />
cd Hello<br />
ccmake .<br />
make<br />
<br />
In the second example, an out-of-place build is performed, i.e., the source code, libraries, and executables are produced in a directory separate from the source code directory(ies).<br />
<br />
mkdir HelloBuild<br />
cd HelloBuild<br />
ccmake ../Hello<br />
make<br />
<br />
Out-of-source builds are recommended, as you can build multiple variants in separate directories, e.g., HelloBuildDebug, HelloBuildRelease.<br />
<br />
Note: Before performing an out-of-source build ensure that any possible CMake generated in-source build information is removed from the source directory, e.g., CMakeFiles directory, and CMakeCache.txt.<br />
<br />
=== I run an out-of-source build but CMake generates in-source anyway. Why? ===<br />
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.<br />
<br />
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).<br />
<br />
=== Why does CMake use full paths, or can I copy my build tree? ===<br />
CMake uses full paths because:<br />
<br />
# configured header files may have full paths in them, and moving those files without re-configuring would cause upredictable behavior.<br />
# because cmake supports out of source builds, if custom commands used relative paths to the source tree, they would not work when they are run in the build tree because the current directory would be incorrect.<br />
# on Unix systems rpaths might be 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.<br />
<br />
Can the build tree be copied or moved?<br />
<br />
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 and rerun. Often when people want to move a binary tree it is so that they can distribute it to other users who may not have cmake in which case this would not work even if cmake would detect the move.<br />
<br />
The workaround is to create a new build tree without copying or moving the old one.<br />
<br />
<br />
=== CMake does not generate a "make distclean" target. Why? ===<br />
Some build trees created with GNU autotools have a "make distclean" target that cleans the build and also removes Makefiles and other parts of the generated build system. CMake does not generate a "make distclean" target because CMakeLists.txt files can run scripts and arbitrary commands; CMake has no way of tracking 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. (CMake does generate a "make clean" target to remove files generated by the compiler and linker.)<br />
<br />
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. Because CMake does not change the source tree, there is no need for a distclean target. One can start a fresh build by deleting the build tree or creating a separate build tree.<br />
<br />
(If a CMakeLists.txt uses ADD_CUSTOM_COMMAND to generate source files in the source tree, not the build tree, then in CMake 2.2 or higher "make clean" will remove them. See next question.)<br />
<br />
=== Running "make clean" does not remove custom command outputs. Why? ===<br />
In CMake 2.2 and higher custom command outputs should be removed by make clean. Make sure you are using at least this version. Prior to CMake 2.2 custom command outputs were not automatically added to the list of files to clean. In CMake 2.0 the 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.<br />
<br />
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 to clean away files that differ between builds.<br />
<br />
<br />
== Writing CMakeLists.txt ==<br />
<br />
=== How to have backward and forward compatibility? ===<br />
<br />
As of CMake 2.6 we employ a "Policy" mechanism to provide backwards compatibility.<br />
The basic requirement for projects is to include one line at the top of the highest CMakeLists.txt file:<br />
<br />
cmake_minimum_required(VERSION 2.6) # or other version<br />
<br />
This tells versions of CMake older than that specified that they are too old to build the project.<br />
They will report this information to the user.<br />
It also tells versions of CMake newer than that specified that the project may not be aware of policies introduced in later versions, which enables additional compatibility.<br />
For futher documentation, see<br />
<br />
* [[CMake_Policies|CMake Policy Mechanism]]<br />
* [http://www.cmake.org/cmake/help/cmake2.6docs.html#command:cmake_policy cmake_policy() command]<br />
* [http://www.cmake.org/cmake/help/cmake2.6docs.html#section_Policies CMake 2.6 Policies]<br />
<br />
=== How do I get the current source or binary directory? ===<br />
The variable CMAKE_CURRENT_SOURCE_DIR contains the absolute path to your current source directory, while CMAKE_CURRENT_BINARY_DIR points to the equivalent binary directory.<br />
<br />
=== Why are my CMake variables not updated in the GUI after a SET command? ===<br />
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.<br />
<br />
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:<br />
<br />
SET(BUILD_SHARED_LIBS ON)<br />
<br />
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.<br />
<br />
You can use the CACHE and FORCE options on the SET command to change variables in a way that will be reflected in the GUI. Run<br />
<br />
cmake --help-command SET<br />
<br />
to see full instructions for the command.<br />
<br />
<br />
=== How can I change the default build mode and see it reflected in the GUI? ===<br />
Adapt the following commands in your CMakeList.txt (this example sets the Release<br />
With Debug Information mode):<br />
<pre><br />
IF(NOT CMAKE_BUILD_TYPE)<br />
SET(CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING<br />
"Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel."<br />
FORCE)<br />
ENDIF(NOT CMAKE_BUILD_TYPE)<br />
</pre><br />
<br />
=== How do I generate an executable, then use the executable to generate a file? ===<br />
<br />
Create the generator executable by just adding a target:<br />
<br />
ADD_EXECUTABLE(generate generate.c)<br />
<br />
The rest of the process is simpler in CMake 2.6 and above than in previous versions.<br />
<br />
Use <code>ADD_CUSTOM_COMMAND</code> to specify a custom build rule for the file.<br />
(In this example we assume <code>generate</code> accepts the input and output files as arguments.)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT someoutput.txt<br />
COMMAND generate ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
DEPENDS generate ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt<br />
)<br />
<br />
This tells CMake how to build the file but does not actually add a rule to the build system.<br />
Another target must require it.<br />
One may create a custom target explicitly for this rule:<br />
<br />
ADD_CUSTOM_TARGET(driver ALL DEPENDS someoutput.txt)<br />
<br />
or the file may be added as part of some other target:<br />
<br />
ADD_EXECUTABLE(product product.c someoutput.txt)<br />
<br />
<font color=#555555><br />
In CMake 2.4 and below the <code>generate</code> target may not be specified directly in the <code>COMMAND</code> option of <code>add_custom_command</code><br />
(but it can still be used in the <code>DEPENDS</code> option as of CMake 2.4).<br />
Instead use GET_TARGET_PROPERTY to obtain the location of the generated executable.<br />
Additionally, the output must always be specified by full path.<br />
<br />
GET_TARGET_PROPERTY(GENERATE_EXE generate LOCATION)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
COMMAND ${GENERATE_EXE} ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
DEPENDS generate<br />
)<br />
</font><br />
<br />
=== How can I generate a source file during the build? ===<br />
The ADD_CUSTOM_COMMAND command lets you generate a source file that you can then include in another target. For example:<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
COMMAND ${CMAKE_COMMAND} copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.c ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.c<br />
)<br />
ADD_EXECUTABLE(foo foo.c)<br />
<br />
This will create an executable by copying bar.c to foo.c and then compiling foo.c to produce foo. CMake allows you to put generate source files in the current source or binary directory, so we were careful to output foo.c to the current binary directory. When we add foo.c to foo, CMake will look in either directory for it. Even if foo.c does not yet exist, CMake is smart enough to notice that a custom command creates it. (For the file named as the OUTPUT, CMake has its GENERATED source file property set to true.)<br />
<br />
You can also use ADD_CUSTOM_COMMAND when the<br />
[[CMake_FAQ#How_do_I_generate_an_executable.2C_then_use_the_executable_to_generate_a_file.3F|generator command is another executable in the same project]].<br />
<br />
Sometimes, the program doing the generation may generate multiple output files that each need to be part of the build. CMake 2.4 or higher supports having multiple files listed in the OUTPUT section. 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:<br />
<br />
PROJECT(FOO)<br />
# make sure cmake addes the binary directory for the project to the include path<br />
INCLUDE_DIRECTORIES(${FOO_BINARY_DIR})<br />
# add the executable that will do the generation<br />
ADD_EXECUTABLE(my_generator my_generator.cxx)<br />
GET_TARGET_PROPERTY(MY_GENERATOR_EXE my_generator LOCATION)<br />
# add the custom command that will generate all three files<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${FOO_BINARY_DIR}/output1.cpp ${FOO_BINARY_DIR}/output2.h ${FOO_BINARY_DIR}/output3.cpp<br />
COMMAND ${MY_GENERATOR_EXE} ${FOO_BINARY_DIR} ${FOO_SOURCE_DIR}/input.txt<br />
DEPENDS my_generator<br />
MAIN_DEPENDENCY ${FOO_SOURCE_DIR}/input.txt<br />
)<br />
# now create an executable using the generated files<br />
ADD_EXECUTABLE(generated<br />
${FOO_BINARY_DIR}/output1.cpp<br />
${FOO_BINARY_DIR}/output2.h<br />
${FOO_BINARY_DIR}/output3.cpp)<br />
<br />
CMake 2.4 allows you to generate a header file. Because generated headers often cause unnecessary rebuilds, you should try to avoid them; consider using the CONFIGURE_FILE command to prepare the header at CMake time. If you must generate a header file, use code like this:<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.h<br />
COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.h ${CMAKE_CURRENT_BINARY_DIR}/foo.h<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.h<br />
)<br />
ADD_EXECUTABLE(foo foo.c ${CMAKE_CURRENT_BINARY_DIR}/foo.h)<br />
<br />
This is like the first example above, except that it generates a header instead of a C file. The header might not exist when the build system scans foo.c's dependencies, so there is no way for CMake to know that this target requires foo.h unless we can tell it that foo.h may exist in the future. We give CMake this knowledge by listing the generated header file in the set of source files for the target. (This requires CMake 2.4. Previous versions of CMake required use of the OBJECT_DEPENDS source file property.)<br />
<br />
=== How can I add a dependency to a source file which is generated in a subdirectory? ===<br />
<br />
Rules created with <code>ADD_CUSTOM_COMMAND</code> as [[CMake_FAQ#How_can_I_generate_a_source_file_during_the_build.3F|above]] have scope only in the directory in which they are specified.<br />
If the generated file is needed in another directory, a target-level dependency needs to be added.<br />
Create a target in the subdirectory with the custom rule in order to drive it:<br />
<br />
# subdir/CMakeLists.txt<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
COMMAND ${CMAKE_COMMAND} copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.c ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.c<br />
)<br />
ADD_CUSTOM_TARGET(generate_foo DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/foo.c)<br />
<br />
Now other targets can depend on the target from the subdirectory:<br />
<br />
# CMakeLists.txt<br />
ADD_SUBDIRECTORY(subdir)<br />
# Create the executable.<br />
ADD_EXECUTABLE(generated ${CMAKE_CURRENT_BINARY_DIR}/subdir/foo.c)<br />
# Tell CMake the source won't be available until build time.<br />
SET_SOURCE_FILES_PROPERTIES(${CMAKE_CURRENT_BINARY_DIR}/subdir/foo.c PROPERTIES GENERATED 1)<br />
# Make sure the source is generated before the executable builds.<br />
ADD_DEPENDENCIES(generated generate_foo)<br />
<br />
=== I use EXEC_PROGRAM but the result is not set in subdirectories. Why? ===<br />
<br />
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 was fixed in CMake 2.2, but for older versions you will have to cache the result:<br />
<br />
<pre><br />
EXEC_PROGRAM(my-program OUTPUT_VARIABLE MY_OUTPUT)<br />
SET(MY_OUTPUT "${MY_OUTPUT}" CACHE INTERNAL "")<br />
</pre><br />
<br />
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.<br />
<br />
=== How can I get or set environment variables? ===<br />
<br />
CMake names environment variables using an ENV prefix and surrounding the names in curly braces. Here is an example:<br />
<br />
<pre><br />
MESSAGE("$ENV{PATH}")<br />
</pre><br />
<br />
Reading variables will work in any version of CMake. Writing to them works in CMake 2.2 and higher using the following syntax:<br />
<br />
<pre><br />
SET(ENV{HELLO} "World")<br />
</pre><br />
<br />
Note that there is currently no way to tell apart an empty environment variable value from a variable that is not set at all.<br />
<br />
One should avoid using environment variables for controlling the flow of CMake code (such as in IF commands). The build system generated by CMake may re-run CMake automatically when CMakeLists.txt files change. The environment in which this is executed is controlled by the build system and may not match that in which CMake was originally run. If you want to control build settings on the CMake command line, you need to use cache variables set with the -D option. The settings will be saved in CMakeCache.txt so that they don't have to be repeated every time CMake is run on the same build tree.<br />
<br />
Also, environment variables SET in the CMakeLists.txt ''only'' take effect for cmake itself, so you cannot use this method to set an environment variable that a custom command might need.<br />
<br />
=== Why do I have unwanted semicolons ; in my compiler flags? ===<br />
CMake has a list data type. A list is stored as a string of semicolon-separated list elements. Whitespace separated arguments to a SET statement are interpreted as list elements. For instance, SET(var a b c d e) will give "var" a value of a;b;c;d;e and this list can be used by other CMake commands. However, if you pass ${var} to a non-CMake external tool, such as a compiler's command line, you are passing a;b;c;d;e which is not what you want. Instead you either need to pass "${var}", so that the list will be converted to a whitespace-separated string, or you need to SET(var "a b c d e") in the 1st place so that you're working with a string, not a list.<br />
<br />
=== How can I get quoting and escapes to work properly? ===<br />
If you want to escape a character in CMake, you use "\", like in C code. For example, if you wanted to have a quote embedded in a string you would do this: "\"". However, each level of CMake that processes your code will need one level of escaping to work. So, if you configure a file that is read by cmake or cpack and you want to do the same thing, you would do "\\\"". You would still need to escape the " for the first cmake that processes the string. However, this time, you would want to also escape a '\' as well. This would leave the next level of processing with "\"". Also, for custom commands that may get passed to a shell, it maybe required to do escaping for that shell.<br />
<br />
=== Isn't the "Expression" in the "ELSE (Expression)" confusing? ===<br />
Traditional CMakeLists.txt files prior to 2.6.0, require the following syntax. In the IF syntax, the ELSE section requires the same (Expression) as the IF section. This sometimes can make the script kind of hard to follow, take the short example below:<br />
<br />
IF(WIN32)<br />
...do something...<br />
ELSE(WIN32)<br />
...do something else...<br />
ENDIF(WIN32)<br />
<br />
You might think that the ELSE section, here containing "...do something else...", is for the WIN32 portion of the script. That is not so! It is actually handling the NOT WIN32 section.<br />
<br />
As of CMake 2.6.0 the ELSE() and ENDIF() constructs can be empty. The same is true for closing constructs on ENDMACRO(), ENDFUNCTION(), and ENDFOREACH(). If you require 2.4.x compatibility, you can enable the CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS option on CMake 2.4.3 or greater. This option is superfluous on CMake 2.6.0 or greater.<br />
<br />
SET(CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS true)<br />
<br />
IF(WIN32)<br />
...do something...<br />
ELSEIF(APPLE)<br />
...do something else...<br />
ELSE()<br />
...do something else...<br />
ENDIF()<br />
<br />
=== Which regular expressions are supported by CMake? ===<br />
When using MATCHES or MATCHALL in an IF command, or using any of the STRING(REGEX ...) commands, CMake expects regular expressions, not globs (wild cards). CMake uses the same regular expression engine above all platforms. Here are the meanings of the metacharacters:<br />
<br />
^ Matches at beginning of a line<br />
$ Matches at end of a line<br />
. Matches any single character<br />
[ ] Matches any character(s) inside the brackets<br />
[^ ] Matches any character(s) not inside the brackets<br />
- Matches any character in range on either side of a dash<br />
| Matches a pattern on either side of the |<br />
* Matches preceding pattern zero or more times<br />
+ Matches preceding pattern one or more times<br />
? Matches preceding pattern zero or once only<br />
() Saves a matched expression and uses it in a later match<br />
<br />
Example: "[-][L]([^ ;])+" matches all strings beginning with -L and ending with a space or a semicolon, the usual linkdirs under Linux.<br />
<br />
Here is how to catch a part of a string. The variable test is filled with some content, and then we want to catch the "me":<br />
<br />
SET(test "hello world ! catch: me if you can")<br />
STRING(REGEX REPLACE ".*catch: ([^ ]+).*" "\\1" result "${test}" )<br />
MESSAGE(STATUS "result= ${result}")<br />
<br />
This is slightly tricky. The part inside the brackets is available in \\1 . CMake will copy the variable test to the variable result, but then it will replace everything that the regular expression matches with \\1. This means the first regular expression has to match the whole string and the part we want to catch has to be put in parens.<br />
<br />
-- result= me<br />
<br />
For those of you who know Perl, the equivalent Perl code could be:<br />
<br />
$test = "hello world ! catch: me if you can";<br />
$result = $test;<br />
$result =~ s/.*catch: ([^ ]+).*/$1/;<br />
print "-- result= $result\n";<br />
<br />
There are other ways to do this in Perl, but this is how we do it in CMake because \\1 does not become a variable like $1 does in perl, so there is no SET(result ${\\1}) in CMake.<br />
<br />
<br />
=== How to convert a semicolon separated list to a whitespace separated string? ===<br />
<br />
set(foo<br />
abc.c<br />
abc.b<br />
abc.a<br />
)<br />
<br />
foreach(arg ${foo})<br />
set(bar "${bar} ${arg}")<br />
endforeach(arg ${foo})<br />
<br />
message("foo: ${foo}")<br />
message("bar: ${bar}")<br />
<br />
=== How can I build multiple modes without switching ? ===<br />
To build multiple modes (e.g. Debug and Release) in one shot without constantly running cmake -DCMAKE_BUILD_TYPE=Debug and cmake -DCMAKE_BUILD_TYPE=Release in source tree create a directory for builds eg.:<br />
<br />
<pre><br />
Project-directory/<br />
/Build<br />
</pre><br />
<br />
Inside you can place as many target directories for out-of-source build modes as you want, e.g.:<br />
<br />
<pre><br />
Project-directory/<br />
/Build<br />
/Debug<br />
/Release<br />
</pre><br />
<br />
In each of these directories issue a command (assuming that you have CMakeLists.txt directly in Project-directory)<br />
<br />
<pre><br />
cmake -DCMAKE_BUILD_TYPE=type_of_build ../../<br />
</pre><br />
<br />
to create a cmake cache configured for requested build type.<br />
<br />
Now you can make each build just by entering appropriate directory and executing a make command.<br />
<br />
=== How can I extend the build modes with a custom made one ? ===<br />
The following code snipet (taken from a CMakeLists.txt) adds a Maintainer mode:<br />
<pre><br />
SET( CMAKE_CXX_FLAGS_MAINTAINER "-Wall -Wabi" CACHE STRING<br />
"Flags used by the C++ compiler during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_C_FLAGS_MAINTAINER "-Wall -pedantic" CACHE STRING<br />
"Flags used by the C compiler during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_EXE_LINKER_FLAGS_MAINTAINER<br />
"-Wl,--warn-unresolved-symbols,--warn-once" CACHE STRING<br />
"Flags used for linking binaries during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_SHARED_LINKER_FLAGS_MAINTAINER<br />
"-Wl,--warn-unresolved-symbols,--warn-once" CACHE STRING<br />
"Flags used by the shared libraries linker during maintainer builds."<br />
FORCE )<br />
MARK_AS_ADVANCED(<br />
CMAKE_CXX_FLAGS_MAINTAINER<br />
CMAKE_C_FLAGS_MAINTAINER<br />
CMAKE_EXE_LINKER_FLAGS_MAINTAINER<br />
CMAKE_SHARED_LINKER_FLAGS_MAINTAINER )<br />
# Update the documentation string of CMAKE_BUILD_TYPE for GUIs<br />
SET( CMAKE_BUILD_TYPE "" CACHE STRING<br />
"Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel Maintainer."<br />
FORCE )<br />
</pre><br />
Notes: The flags used in this example are specific to GCC. Change them as needed for your project. Additionally the SET(CMAKE_BUILD_TYPE) command will override<br />
a CMAKE_BUILD_TYPE previously set in the CMakeLists.txt.<br />
<br />
=== Why does <code>foreach</code> skip empty values? ===<br />
<br />
The code in question is of the form<br />
<br />
set(var "a;b;;c;d") # list 'a', 'b', '', 'c', 'd'<br />
foreach(v ${var})<br />
# v=a, v=b, v=c, v=d, one at a time<br />
endforeach()<br />
<br />
and the loop variable 'v' never attains the empty-string value ''.<br />
This is because the <code>${var}</code> syntax is an unquoted argument so the CMake language expands the list and removes the empty value.<br />
The foreach command does not even see the empty value.<br />
One can verify this because the code<br />
<br />
foreach(v a b "" c d)<br />
...<br />
endforeach()<br />
<br />
will see the empty value.<br />
<br />
=== Does CMake support precompiled headers? ===<br />
<br />
Yes and no. Every platform does precompiled headers a bit differently, and there is currently no first-class interface provided by CMake and implemented on every platform.<br />
However, CMake does provide enough primitives for projects to use precompiled headers on specific platforms.<br />
Our issue tracker has a [http://www.cmake.org/Bug/view.php?id=1260 feature request] with attachements providing user-contributed helper macros for some platforms.<br />
<br />
== Writing FindXXX.cmake files ==<br />
<br />
=== What are the rules to write a FindXXX.cmake file? ===<br />
<br />
Let's follow the instructions and the advices in the <br />
Modules/readme.txt [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/readme.txt?root=CMake&view=markup]<br />
file located in the CVS repository.<br />
<br />
=== Why does find_library look in system directories before its PATHS option? ===<br />
<br />
The code in question is often of the form<br />
<br />
find_library(FOO_LIBRARY NAMES foo PATHS /opt/foo/lib)<br />
<br />
CMake will find "<code>/usr/lib/libfoo.so</code>" instead of "<code>/opt/foo/lib/libfoo.so</code>" if both exist.<br />
The reason is that /opt/foo/lib is a <i>hard-coded guess</i> of the location.<br />
The documentation of <code>[http://www.cmake.org/cmake/help/cmake2.6docs.html#command:find_library find_library]</code> specifies the search order.<br />
User, project, and system configuration variables are always more local than hard-coded guesses and should override them, so<br />
the PATHS option is used last.<br />
<br />
Some find-modules compute probable locations based on other information <i>available from the system</i> such as a project-specific environment variable.<br />
The HINTS option (CMake 2.6 and higher) takes precedence over system directories specifically for this case:<br />
<br />
file(TO_CMAKE_PATH "$ENV{FOO_LIB_DIR}" FOO_LIB_DIR)<br />
find_library(FOO_LIBRARY NAMES foo HINTS ${FOO_LIB_DIR})<br />
<br />
CMake will find "<code>$ENV{FOO_LIB_DIR}/libfoo.so</code>" before "<code>/usr/lib/libfoo.so</code>".<br />
<br />
== Finding and using external packages ==<br />
<br />
=== How do I use CMake to generate SWIG wrapper libraries? ===<br />
<br />
CMake version 2 includes a module that supports the generation of SWIG wrapper libraries. The SWIG package defines the following macros: SWIG_ADD_MODULE and SWIG_LINK_LIBRARIES.<br />
<br />
<pre><br />
# This example shows how to use python<br />
# Currently these languages have been tested:<br />
# perl tcl ruby php4 pike<br />
<br />
FIND_PACKAGE(SWIG REQUIRED)<br />
INCLUDE(${SWIG_USE_FILE})<br />
<br />
FIND_PACKAGE(PythonLibs)<br />
INCLUDE_DIRECTORIES(${PYTHON_INCLUDE_PATH})<br />
<br />
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})<br />
<br />
SET(CMAKE_SWIG_FLAGS "")<br />
<br />
SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES CPLUSPLUS ON)<br />
SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES SWIG_FLAGS "-includeall")<br />
SWIG_ADD_MODULE(example python<br />
example.i example.cxx)<br />
SWIG_LINK_LIBRARIES(example ${PYTHON_LIBRARIES})<br />
<br />
</pre><br />
<br />
<pre><br />
# This example shows how to use tcl<br />
PROJECT(TCL_WRAP)<br />
SET ( MODULE_NAME project )<br />
SET ( INTERFACE_FILES project.i)<br />
SET ( SRC_FILES Vertex.h Vertex.cxx Shapes.h Shapes.cxx )<br />
<br />
FIND_PACKAGE(SWIG REQUIRED)<br />
INCLUDE(${SWIG_USE_FILE})<br />
<br />
# Look for TCL<br />
INCLUDE_DIRECTORIES(${TCL_INCLUDE_PATH})<br />
<br />
FIND_LIBRARY(TCL_LIBRARY NAMES tcl tcl84 tcl83 tcl82 tcl80<br />
PATHS /usr/lib /usr/local/lib)<br />
IF (TCL_LIBRARY)<br />
TARGET_ADD_LIBRARY (${MODULE_NAME} TCL_LIBRARY)<br />
ENDIF (TCL_LIBRARY)<br />
<br />
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})<br />
<br />
SET(CMAKE_SWIG_FLAGS "-c++")<br />
<br />
SET_SOURCE_FILES_PROPERTIES(${INTERFACE_FILES} PROPERTIES CPLUSPLUS ON)<br />
SET_SOURCE_FILES_PROPERTIES(${INTERFACE_FILES} PROPERTIES CMAKE_SWIG_FLAGS "-includeall")<br />
SWIG_ADD_MODULE(${MODULE_NAME} tcl ${INTERFACE_FILES} ${SRC_FILES})<br />
SWIG_LINK_LIBRARIES(${MODULE_NAME} ${TCL_LIBRARIES})<br />
</pre><br />
<br />
=== How do I use CMake to build LaTeX documents? ===<br />
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.<br />
<br />
PROJECT(Document)<br />
IF(LATEX_COMPILE)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${Document_BINARY_DIR}/TDocument.dvi<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.tex<br />
COMMAND ${LATEX_COMPILE} <br />
ARGS ${Document_SOURCE_DIR}/TDocument.tex <br />
)<br />
ENDIF(LATEX_COMPILE)<br />
<br />
IF(DVIPDF_COMPILE)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${Document_BINARY_DIR}/TDocument.pdf<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.dvi <br />
COMMAND ${DVIPDF_COMPILE}<br />
ARGS ${Document_SOURCE_DIR}/TDocument.dvi<br />
)<br />
ENDIF(DVIPDF_COMPILE)<br />
<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.pdf<br />
)<br />
<br />
The following uses commands in CMake version 2.0 and later<br />
<br />
PROJECT(Document)<br />
# <br />
# Find LaTeX<br />
#<br />
FIND_PACKAGE(LATEX)<br />
<br />
IF(LATEX_COMPILER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.dvi<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS ${Document_SOURCE_DIR}/TDocument.tex<br />
DEPENDS ${Document_SOURCE_DIR}/TDocument.tex<br />
COMMENT "Tex2dvi"<br />
)<br />
<br />
IF(DVIPS_CONVERTER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.ps<br />
COMMAND ${DVIPS_CONVERTER}<br />
ARGS ${Document_BINARY_DIR}/TDocument.dvi<br />
-o ${Document_BINARY_DIR}/TDocument.ps<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.dvi<br />
COMMENT "dvi2ps"<br />
)<br />
<br />
IF(PS2PDF_CONVERTER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.pdf<br />
COMMAND ${PS2PDF_CONVERTER}<br />
ARGS ${Document_BINARY_DIR}/TDocument.ps<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.ps<br />
COMMENT "ps2pdf"<br />
)<br />
<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.pdf<br />
)<br />
ENDIF(PS2PDF_CONVERTER)<br />
ENDIF(DVIPS_CONVERTER)<br />
ENDIF(LATEX_COMPILER)<br />
<br />
=== How do I get LaTeX references to be correct? ===<br />
When your latex document contains references (e.g. \ref{...} command) you get to run two passes of latex. In the<br />
most general case, i.e. when additionally your document uses a bibtex bibliography, you shall need three<br />
passes of latex (and one pass of bibtex):<br />
# latex (first pass: for bibtex to have an .aux file)<br />
# bibtex (for generating the .bbl file)<br />
# latex (second pass)<br />
# latex (third pass)<br />
<br />
The following code snippet illustrates how you can "pervert" the bibtex and latex generated<br />
auxilary files (.aux, .log, .dvi, .bbl...) to create an "artificial" set of CMake dependencies.<br />
The side-effect of those dependencies should hopefully be the above described sequence of calls<br />
to latex and bibtex<br />
<pre><br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.aux<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/UsersManual.tex<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (first pass)"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.aux<br />
COMMAND ${BIBTEX_COMPILER}<br />
ARGS -terse ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Bibtex"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.dvi<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (second pass)"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.log<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
${CMAKE_CURRENT_BINARY_DIR}/UsersManual.dvi<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (third pass)"<br />
)<br />
# Eventually trigger the whole process<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.log<br />
)<br />
</pre><br />
<br />
=== How can I set TEXINPUTS for a LaTeX compilation? ===<br />
First note that most often you can avoid using TEXINPUTS by copying all the necessary files (.tex source file and<br />
included graphic files e.g. .eps files) from your PROJECT_SOURCE_DIR hirarchy to your PROJECT_BINARY_DIR subdir<br />
[refer to CONFIGURE_FILE with the COPYONLY flag set for copying files]. Since by default latex uses the current working directory as value for TEXINPUTS you should be all set. As expected, this trick is quick AND dirty since your<br />
concerned PROJECT_BINARY_DIR subdir now contains files that are NOT generated by CMake (in the sense that those<br />
files are not the result of a system command but were merely duplicated)... <br />
<br />
If you consider it is cleaner or easier to define a TEXINPUTS environment variable [the latex command probably<br />
misses a -I flag] you can find an example in the InsightDocuments cvs archive (refer to the section "cvs access"<br />
near the bottom of Kitware's ITK download page) or use google with keywords "ITK_TEXINPUTS CONFIGURE_FILE".<br />
Look at InsightDocuments/CourseWare/Training/Vis2003/Latex/CMakeLists.txt and search for e.g. "LaTeXWrapper.sh.in".<br />
<br />
Roughly the mechanism goes:<br />
* SET ITK_TEXINPUTS with the desired TEXINPUTS<br />
* CONFIGURE_FILE "InsightDocuments/CourseWare/Training/Vis2003/LaTeXWrapper.sh.in" which generates an sh shell script setting the shell variable TEXINPUTS prior to running the latex command<br />
* use ADD_CUSTOM_COMMAND to invoke this shell script<br />
This very example is Win32 portable (except that LaTeXWrapper.bat.in generates a .bat shell script)<br />
<br />
== Library questions ==<br />
<br />
=== Can I build both shared and static libraries with one ADD_LIBRARY command? ===<br />
<br />
No. Each library you build must have a unique target name, i.e. the "libname" field of the ADD_LIBRARY command. That way, CMake can track dependencies separately for each library. Libraries can have the same OUTPUT_NAME, see the SET_TARGET_PROPERTIES command, but this is not the default.<br />
<br />
=== Does that mean I have to build all my library objects twice, once for shared and once for static?! I don't like that! ===<br />
<br />
In practice, most libraries have different defines and compiler flags for the shared vs. static cases. So you would have to build all your library objects twice anyways. However, if you happen to have '''''exactly''''' the same defines and compiler flags for the shared vs. static cases...<br />
<br />
...if you're using Linux and a GCC-style linker, you could do the following. Note that for this to work correctly on linux, the zzSTATIC source files should have been compiled with "-fPIC" to ensure they will work in a shared library.<br />
<br />
IF(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_COMPILER_IS_GNUCC)<br />
ADD_LIBRARY(zzSTATIC STATIC -fPIC)<br />
ADD_LIBRARY(zzDYNAMIC SHARED)<br />
TARGET_LINK_LIBRARIES(zzDYNAMIC -Wl,-whole-archive zzSTATIC -Wl,-no-whole-archive)<br />
ENDIF(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_COMPILER_IS_GNUCC)<br />
<br />
...if you want a cross-platform approach that works on all compilers, not just GCC or Linux, you could extract the locations of previously built object files and insert them directly into the libraries that need them. This is documented in [http://www.cmake.org/Bug/view.php?id=5155 CMake Feature Request #5155: standard way to locate object files]. Unfortunately this approach relies on CMake's internal implementation, and that implementation could change in the future, breaking your code.<br />
<br />
=== How do I make my shared and static libraries have the same root name, but different suffixes? ===<br />
Set the OUTPUT_NAME of your shared and static libraries to the same thing.<br />
<br />
ADD_LIBRARY(foo SHARED ${foo_sources})<br />
ADD_LIBRARY(foo-static STATIC ${foo_sources})<br />
// The library target "foo" already has a default OUTPUT_NAME of "foo", so we don't need to change it.<br />
// The library target "foo-static" has a default OUTPUT_NAME of "foo-static", so change it.<br />
SET_TARGET_PROPERTIES(foo-static PROPERTIES OUTPUT_NAME "foo")<br />
<br />
If you are building your shared and static libraries in the same directory, you will also need the following to keep your shared and static libraries from clobbering each other during the build.<br />
<br />
SET_TARGET_PROPERTIES(foo PROPERTIES CLEAN_DIRECT_OUTPUT 1)<br />
SET_TARGET_PROPERTIES(foo-static PROPERTIES CLEAN_DIRECT_OUTPUT 1)<br />
<br />
=== How do I rename a library after it has already been built? ===<br />
You don't rename it. It's been built! Its name is whatever CMakeLists.txt says it's supposed to be.<br />
<br />
Perhaps you want to copy the library to a different name. But, are you sure that's what you want to do? You could just change the name in your ADD_LIBRARY command or change its OUTPUT_NAME property using SET_TARGET_PROPERTY(). If you really really want to copy the library to a different name, try:<br />
<br />
GET_TARGET_PROPERTY(LIB_NAME Foo LOCATION)<br />
GET_TARGET_PROPERTY(Bar_prefix Foo PREFIX)<br />
GET_TARGET_PROPERTY(Bar_suffix Foo SUFFIX)<br />
SET(NEW_LIB_NAME ${Bar_prefix}Bar${Bar_suffix})<br />
<br />
ADD_CUSTOM_COMMAND(<br />
TARGET Foo<br />
POST_BUILD<br />
COMMAND ${CMAKE_COMMAND} -E copy ${LIB_NAME} ${NEW_LIB_NAME}<br />
)<br />
<br />
On Windows you may also want to copy the .dll import lib, using the same approach as above, but with IMPORT_PREFIX and IMPORT_SUFFIX. ''Problem: LOCATION only refers to 1 file, the .dll. What is a simple way to get the location of the import lib? Could provide a complicated way, but that's annoying.''<br />
<br />
=== Does CMake support "convenience" libraries? ===<br />
No. CMake does not currently support convenience libraries. A "convenience" library, as GNU libtool calls it, is an archive of objects to be mixed into other libraries. Other libraries "link" to the convenience library, but the convenience library does not export any symbols; GNU libtool never installs the convenience library; no programs ever link to the convenience library.<br />
<br />
This does '''not''' mean that a project using convenience libraries cannot be converted to CMake. Instead the source files may be listed in each target that needs them. They will be built for each target separately using all the preprocessor definitions and flags configured for that target.<br />
<br />
=== Why are libraries linked to my shared library included when something links to it? ===<br />
This question arises when one has a library B which links to some library A. When a third target, say C, links to B, CMake will automatically include C to A also. When the libraries are static, then this is always necessary. When the libraries are shared, this is the default behavior provided by CMake. CMake 2.6 and above provide the target property "LINK_INTERFACE_LIBRARIES" (http://www.cmake.org/HTML/cmake-2.6.html#prop_tgt:LINK_INTERFACE_LIBRARIES) to specify the libraries that should be transitively included in the link by CMake. CMake 2.4 and below do not support the property.<br />
<br />
Something like the following will work in CMake 2.6:<br />
<br />
<pre><br />
set_target_properties(mylibrary<br />
PROPERTIES<br />
LINK_INTERFACE_LIBRARIES ""<br />
)<br />
</pre><br />
<br />
=== CMake dependency scanner ===<br />
<br />
CMake does not preprocess source files while scanning dependencies. Code like<br />
<pre><br />
#if 0<br />
# include "bla.h"<br />
#endif<br />
</pre><br />
will result in a dependency on "bla.h". This sometimes leads to source files recompiling unnecessarily but will not break the build.<br />
<br />
== Installation questions ==<br />
<br />
=== Does CMake's "make install" support DESTDIR? ===<br />
'''Yes''', especially when the build-system generator uses CMake's builtin support for installing files: Simply define the DESTDIR environment variable during installation and CMake will treat that value as the root of the file system for all installation paths; naturally, the DESTDIR path must be absolute.<br />
<br />
For example, if the Makefile generator is used, then all of the following are example usages of DESTDIR (perhaps assuming the bash shell for the last 2):<br />
<br />
(1) make install DESTDIR="/some/absolute/path"<br />
(2) make DESTDIR="/some/absolute/path" install<br />
(3) DESTDIR="/some/absolute/path" make install<br />
(4) export DESTDIR="/some/absolute/path<br />
make install<br />
<br />
=== Can I do "make uninstall" with CMake?===<br />
By default, CMake does not provide the "make uninstall" target, so you cannot do this. We do not want "make uninstall" to remove useful files from the system.<br />
<br />
If you want an "uninstall" target in your project, then nobody prevents you from providing one. You need to delete the files listed in install_manifest.txt file. Here is how to do it. First create file cmake_uninstall.cmake.in in the top-level directory of the project:<br />
<br />
<pre><br />
IF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")<br />
MESSAGE(FATAL_ERROR "Cannot find install manifest: \"@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt\"")<br />
ENDIF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")<br />
<br />
FILE(READ "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt" files)<br />
STRING(REGEX REPLACE "\n" ";" files "${files}")<br />
FOREACH(file ${files})<br />
MESSAGE(STATUS "Uninstalling \"$ENV{DESTDIR}${file}\"")<br />
IF(EXISTS "$ENV{DESTDIR}${file}")<br />
EXEC_PROGRAM(<br />
"@CMAKE_COMMAND@" ARGS "-E remove \"$ENV{DESTDIR}${file}\""<br />
OUTPUT_VARIABLE rm_out<br />
RETURN_VALUE rm_retval<br />
)<br />
IF(NOT "${rm_retval}" STREQUAL 0)<br />
MESSAGE(FATAL_ERROR "Problem when removing \"$ENV{DESTDIR}${file}\"")<br />
ENDIF(NOT "${rm_retval}" STREQUAL 0)<br />
ELSE(EXISTS "$ENV{DESTDIR}${file}")<br />
MESSAGE(STATUS "File \"$ENV{DESTDIR}${file}\" does not exist.")<br />
ENDIF(EXISTS "$ENV{DESTDIR}${file}")<br />
ENDFOREACH(file)<br />
</pre><br />
<br />
Then in the top-level CMakeLists.txt add the following logic:<br />
<br />
<pre><br />
CONFIGURE_FILE(<br />
"${CMAKE_CURRENT_SOURCE_DIR}/cmake_uninstall.cmake.in"<br />
"${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake"<br />
IMMEDIATE @ONLY)<br />
<br />
ADD_CUSTOM_TARGET(uninstall<br />
"${CMAKE_COMMAND}" -P "${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake")<br />
</pre><br />
<br />
Now you will have an "uninstall" target at the top-level directory of your build tree.<br />
<br />
Instead of creating an "uninstall" target, Unix users could enter this command in the shell:<br />
<br />
xargs rm < install_manifest.txt<br />
<br />
== Distribution questions ==<br />
<br />
=== Where is "make dist"? ===<br />
<br />
CMake doesn't create a "make dist" target.<br />
<br />
=== What is the best way to distribute source code or binaries for a cmake-based project? ===<br />
<br />
For creating source or binary packages there is now [[CMake#CPack | CPack]] coming with CMake, see the <br />
[[ CMake#CPack | documentation]].<br />
<br />
Of course you can also use any other ways to create packages.<br />
<br />
== Platform-specific questions ==<br />
=== How do I build universal binaries on Mac OS X? ===<br />
Before running CMake with an empty build tree, set the CMAKE_OSX_ARCHITECTURES environment variable. It should be set to contain a ; separated list of architectures that you want in the binary. For example, for 32-bit PowerPC and Intel you would do this:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386<br />
<br />
If you wish to build both as 32 and 64 bit, do this:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386;ppc64;x86_64<br />
<br />
You can also set the same named CMake cache variable on an existing binary tree. This works with both makefiles and the Xcode generator. <br />
<br />
In addition, you can also set the CMAKE_OSX_SYSROOT variable to point to the sysroot (aka Mac OS SDK) to be used. CMake will attempt to pick one on your system, but it can be changed in the cache or via an environment variable before running CMake. The 10.4u SDK or later must be used to create a Universal Binary.<br />
<br />
Universal Binaries are essentially cross compilation and so you should avoid using TRY_RUN, especially for things like testing endianess or variable size because the result will only be correct for one architecture.<br />
<br />
Lastly, note that CTest is only able to test one architecture. See bug 6157.<br />
<br />
=== How can I apply resources on Mac OS X automatically? ===<br />
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 a custom rule which is executed after the executable is linked:<br />
<br />
<pre><br />
ADD_EXECUTABLE(MyExecutable ${MyExecutable_SRCS})<br />
GET_TARGET_PROPERTY(MyExecutable_PATH MyExecutable LOCATION)<br />
<br />
IF(APPLE)<br />
FIND_PROGRAM(APPLE_RESOURCE Rez /Developer/Tools)<br />
IF(APPLE_RESOURCE)<br />
ADD_CUSTOM_COMMAND(TARGET MyExecutable POST_BUILD<br />
COMMAND ${APPLE_RESOURCE} Carbon.r -o ${MyExecutable_PATH})<br />
ENDIF(APPLE_RESOURCE)<br />
ENDIF(APPLE)<br />
</pre><br />
<br />
This will execute:<br />
<br />
/Developer/Tools/Rez Carbon.r -o /binary/path/MyExecutable<br />
<br />
after MyExecutable is linked.<br />
<br />
'Rez' may be located elsewhere on disk, depending on the version of Mac OS X and Xcode. You can use 'which Rez' in Terminal to find it's full path.<br />
<br />
=== Why does FIND_LIBRARY not find .DLL libraries under WIN32? ===<br />
For those who come from a Unix background to MS Windows:<br />
<br />
You never link directly to the .dll, you have to link against the import library .lib for the .dll.<br />
<br />
Linking against dynamic libraries (.dll under Windows) is quite different from linking against ELF shared objects (.so) under platforms like Linux or NetBSD. In Windows, there are two types of library, a static library and an import library (both confusingly use the .lib extension, however). In Windows, when you build an import library (A.lib) you will get a corresponding (A.dll) that you only need at runtime. At compile time you will need the import library.<br />
<br />
Conclusion: There is no need to find a .dll for linking. You only need to find the .lib import library.<br />
<br />
Some more details can be found here: [http://xenophilia.org/winvunix.html].<br />
<br />
=== Why am I getting a linker error to _mainCRTStartup under WIN32? ===<br />
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.<br />
<br />
ADD_EXECUTABLE(exename WIN32 source1 source2 ... sourceN)<br />
<br />
The second argument to ADD_EXECUTABLE can be WIN32. This indicates that the executable, when compiled on Windows, is a Windows app (using WinMain) and not a console app (using main). Please note that on Unix platforms, CMake ignores the WIN32 and the compiler will use "main" in any case.<br />
<br />
=== Why do I get this error: nafxcwd.lib(appcore.obj) : error LNK2001: unresolved external symbol ___argv ===<br />
<br />
This is because the application is using both the static and dll versions of the MFC library.<br />
To fix the problem, you can do the following:<br />
<br />
SET(CMAKE_MFC_FLAG 2) # force the IDE to use static MFC<br />
ADD_DEFINITIONS(-D_AFXDLL) # make sure if afx.h is included the dll MFC is used<br />
<br />
=== How to use MFC with CMake ===<br />
To use MFC, the CMAKE_MFC_FLAG variable must be set as follows:<br />
<br />
0: Use Standard Windows Libraries<br />
1: Use MFC in a Static Library<br />
2: Use MFC in a Shared DLL <br />
<br />
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:<br />
<br />
ADD_DEFINITIONS(-D_AFXDLL)<br />
SET(CMAKE_MFC_FLAG 2) <br />
ADD_EXECUTABLE(CMakeSetup WIN32 ${SRCS})<br />
<br />
Note that visual studio 9 project files do not appear to work with CMAKE_MFC_FLAG 1; this may be related to [http://www.cmake.org/Bug/view.php?id=7056 bug 7056].<br />
<br />
In order to use MFC with UNICODE, you must also [http://msdn.microsoft.com/en-us/library/dybsewaf.aspx specify the entry point wWinMainCRTStartup]. For example:<br />
<br />
set(CMAKE_MFC_FLAG 2)<br />
set_target_properties(MyApp PROPERTIES<br />
COMPILE_DEFINITIONS _AFXDLL,_UNICODE,UNICODE,_BIND_TO_CURRENT_CRT_VERSION,_BIND_TO_CURRENT_MFC_VERSION<br />
LINK_FLAGS "/ENTRY:\"wWinMainCRTStartup\"")<br />
<br />
See [http://stackoverflow.com/questions/59635/app-does-not-run-with-vs-2008-sp1-dlls-previous-version-works-with-rtm-versions this article] as to why _BIND_TO_CURRENT_CRT_VERSION and _BIND_TO_CURRENT_MFC_VERSION are necessary for Visual Studio 2008 SP1.<br />
<br />
=== How To Put Files in Folders in Visual Studio Projects ===<br />
The Visual Studio IDE supports putting files into folders.<br />
CMake can be used to put files in folders with the SOURCE_GROUP <br />
command. <br />
<br />
SOURCE_GROUP(name [REGULAR_EXPRESSION regex] [FILES src1 src2 ...])<br />
<br />
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 provided the source file is being passed to ADD_EXECUTABLE or ADD_LIBRARY.<br />
<br />
For example:<br />
SOURCE_GROUP(FooFiles FILES foo.cxx)<br />
SOURCE_GROUP(BarFiles FILES bar.cxx)<br />
ADD_LIBRARY(foo foo.cxx bar.cxx)<br />
<br />
In the event 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).<br />
<br />
As a convenience to developers CMake automatically adds standard header files to a "Header Files" folder and standard source files to a "Source Files" folder for Visual Studio Projects. This can be overridden via the SOURCE_GROUP method documented above.<br />
<br />
=== How to create Visual Studio 6 Projects that contain only a single build type===<br />
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:<br />
<br />
# Create a directory in which you copy the files *.dsptemplate and CMakeVisualStudio6Configurations.cmake from CMake's Templates directory.<br />
# Edit the .cmake file and change the SET(CMAKE_CONFIGURATION_TYPES ...) line to set the build types that you want in your set.<br />
# Edit the *Header.dsptemplate files to contain only the configuration types you want in your set.<br />
# In your CMakeLists.txt file, set the MSPROJECT_TEMPLATE_DIRECTORY to the directory that you created.<br />
<br />
<br />
That's it. Run CMake and your new configuration files will be created.<br />
<br />
Note: Editing the *Header.dsptemplates files should be done very carefully. Here are some guidelines:<br />
<br />
- 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"')<br />
- 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.<br />
- 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.<br />
<br />
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:<br />
# PROP BASE Output_Dir ""<br />
# PROP BASE Intermediate_Dir ""<br />
# PROP Intermediate_Dir ""<br />
# PROP Output_Dir "LIBRARY_OUTPUT_PATH"<br />
or<br />
# PROP Output_Dir "EXECUTABLE_OUTPUT_PATH"<br />
<br />
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).<br />
<br />
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.<br />
<br />
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.)<br />
<br />
=== Can CMake set the Debugging/Working Directory property in Visual Studio projects? ===<br />
<br />
No. The value of this property is not stored in the project files. It is stored in extra files created by the IDE when a solution is loaded (VS .NET 2003 uses a hidden .suo file next to the .sln solution file). The format of these files is not known to CMake and cannot be generated. In some versions of VS the files are binary and not human readable.<br />
<br />
=== Why does CMakeSetup with the message "LINK : fatal error LNK1104: cannot open file 'user32.lib'" while configuring a project? ===<br />
<br />
The path to the SDK libs (user32.lib) must be added by the IDE when the<br />
project generator "Visual Studio 8 2005" is used, because cmake uses<br />
VCExpress.exe and on the fly generated project files to check<br />
for compiling (VCExpress.exe reads some config files for the<br />
compiler/linker options)<br />
<br />
So add the sdk lib path (...\Microsoft Platform SDK\Lib) at Tools->Options->Projects and Solutions->VC++ Directories->Library files<br />
<br />
See also:<br />
*http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/<br />
<br />
=== How can I avoid the error "Arg list too long" when running make? ===<br />
This error is sometimes encountered when building a static library with many object files using Unix make command. It typically looks something like this:<br />
<br />
<pre><br />
gmake[2]: execvp: /bin/sh: Arg list too long<br />
</pre><br />
<br />
When make tries to run the archiver program to build the static library the shell it uses complains that the argument list is too long. In some shells this can be fixed by setting an environment variable such as <tt>ARG_MAX</tt> to extend the length of the command line it will allow.<br />
<br />
=== How can I find out platforms definitions, search paths, etc. from gcc ?===<br />
<br />
The following is really the best if not only way to get information about predefined macros with a GNU compiler:<br />
<pre><br />
$ touch empty.c<br />
$ gcc -v -dD -E empty.c <br />
</pre><br />
This will give you all you might want to know about the preprocessor, the builtin include search dirs and all<br />
predefined definitions, so you can check whether it's __LINUX or _LINUX_ or _APPLE_ or __APPLE etc. <br />
The empty file and all these parameters are really required. You probably want to pipe the output (both stdout and stderr) to a file.<br />
If you want the information for C++, use a C++ file suffix for the empty file.<br />
<br />
This is how you can get the builtin library search paths:<br />
<pre><br />
$ gcc --print-search-dirs<br />
</pre><br />
<br />
=== How can I get a windows registry key ?===<br />
<br />
The only thing to know is that you can't use just the "SET" command in place of "GET" command.<br />
CMake read the value from the registry only when you "get" it from the cache. For instance :<br />
<br />
<pre><br />
GET_FILENAME_COMPONENT(SDK_ROOT_PATH "[HKEY_LOCAL_MACHINE\\SOFTWARE\\PACKAGE;Install_Dir]" ABSOLUTE CACHE)<br />
</pre><br />
<br />
If a key name (ex: Install_Dir in this case) was not specified , the Default key value will be get.<br />
Now you could use the SDK_ROOT_PATH to add include and lib path to your project :<br />
<br />
<pre><br />
INCLUDE_DIRECTORIES(<br />
${SDK_ROOT_PATH}/include<br />
)<br />
<br />
LINK_DIRECTORIES(<br />
${SDK_ROOT_PATH}/lib<br />
)<br />
</pre><br />
<br />
You can also read a registry key in the PATHS section of a FIND_LIBRARY, FIND_PATH, FIND_PROGRAM, or FIND_FILE command<br />
FIND_FILE(BOOT_DOT_INI boot.ini PATHS [HKEY_CURRENT_USER\\Environment;HOMEDRIVE])<br />
<br />
For other examples have a look in the CMake Modules folder :<br />
- FindJava.cmake<br />
- FindPythonLibs.cmake<br />
- ..<br />
<br />
=== How can I build my MSVC application with a static runtime? ===<br />
<br />
Here are three options you could employ to compile your MSVC application with /MT instead of /MD.<br />
<br />
==== Manual Replace ====<br />
<br />
You can rely on the user to modify CMAKE_C_FLAGS_DEBUG, CMAKE_C_FLAGS_RELEASE, CMAKE_CXX_FLAGS_DEBUG, CMAKE_CXX_FLAGS_RELEASE, etc. within the cache editor, replacing /MD with /MT after an initial configure of your software.<br />
<!--<br />
<br />
Not quite ready for primetime...<br />
==== Make Override Files ====<br />
<br />
If you intend to build the entire source tree using /MT and you don't<br />
need this ever to be configurable via the CMake GUI, the best approach<br />
is to create an override file which initializes the starting cache<br />
values for the compile flags.<br />
<br />
First create a c_flag_overrides.cmake & cxx_flag_overrides.cmake file which<br />
contain something like this... (or whatever flags you wish to use).<br />
<br />
c_flag_overrides.cmake<br />
set(CMAKE_C_FLAGS_DEBUG_INIT "/D_DEBUG /MTd /Zi /Ob0 /Od /RTC1")<br />
set(CMAKE_C_FLAGS_MINSIZEREL_INIT "/MT /O1 /Ob1 /D NDEBUG")<br />
set(CMAKE_C_FLAGS_RELEASE_INIT "/MT /O2 /Ob2 /D NDEBUG")<br />
set(CMAKE_C_FLAGS_RELWITHDEBINFO_INIT "/MT /Zi /O2 /Ob1 /D NDEBUG")<br />
<br />
cxx_flag_overrides.cmake<br />
set(CMAKE_CXX_FLAGS_DEBUG_INIT "/D_DEBUG /MTd /Zi /Ob0 /Od /RTC1")<br />
set(CMAKE_CXX_FLAGS_MINSIZEREL_INIT "/MT /O1 /Ob1 /D NDEBUG")<br />
set(CMAKE_CXX_FLAGS_RELEASE_INIT "/MT /O2 /Ob2 /D NDEBUG")<br />
set(CMAKE_CXX_FLAGS_RELWITHDEBINFO_INIT "/MT /Zi /O2 /Ob1 /D NDEBUG")<br />
<br />
Then enable them by placing the following prior to the project() command:<br />
<br />
set(CMAKE_USER_MAKE_RULES_OVERRIDE<br />
${CMAKE_CURRENT_SOURCE_DIR}/c_flag_overrides.cmake)<br />
set(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX<br />
${CMAKE_CURRENT_SOURCE_DIR}/cxx_flag_overrides.cmake)<br />
project(Bar)<br />
<br />
--><br />
==== Dynamic Replace ====<br />
<br />
Alternatively, if you need dynamic control of /MT via some configure option you could use the following technique. Note: CMAKE_CXX_FLAGS_<FOO> is a directory level option, however. Also, this option has the downside of leaving /MD in the cache.<br />
<br />
foreach(flag_var<br />
CMAKE_CXX_FLAGS CMAKE_CXX_FLAGS_DEBUG CMAKE_CXX_FLAGS_RELEASE<br />
CMAKE_CXX_FLAGS_MINSIZEREL CMAKE_CXX_FLAGS_RELWITHDEBINFO)<br />
if(${flag_var} MATCHES "/MD")<br />
string(REGEX REPLACE "/MD" "/MT" ${flag_var} "${${flag_var}}")<br />
endif(${flag_var} MATCHES "/MD")<br />
endforeach(flag_var)<br />
<br />
<br />
{{CMake/Template/Footer}}</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake:Module_Maintainers&diff=16586CMake:Module Maintainers2009-09-21T04:06:42Z<p>Plowman: </p>
<hr />
<div>If you want to add a new module to CMake, then you must volunteer to maintain it, or find someone that will. This page contains a list of Module maintainer volunteers, and instructions on how to become a maintainer. <br />
<br />
* This mail describes the procedure how to become maintainer, and how to modify or add modules: [http://www.cmake.org/pipermail/cmake/2007-July/015258.html Call for maintainers] <br />
<br />
* Please '''DO NOT ADD a Bug Tracker''' entry for new Module request [http://www.cmake.org/pipermail/cmake/2008-November/025196.html Do not add bug report for New Module] <br />
<br />
* Maintainers should follow the guide lines for module files documented here: [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/readme.txt?root=CMake&view=markup readme]<br />
<br />
In addition backwards compatibility for all existing variables in the current set<br />
of modules must be maintained strictly. <br />
<br />
If you want to become a module maintainer, please send an email with your module to the cmake mailing list.<br />
<br />
* Here is a list of "repositories" of 3rd party CMake modules, so maintainers can check for already existing modules etc.<br />
** KDE4: http://websvn.kde.org/trunk/KDE/kdelibs/cmake/modules/<br />
** PlPlot: http://plplot.svn.sourceforge.net/viewvc/plplot/trunk/cmake/modules/<br />
** http://cmake-modules.googlecode.com/svn/trunk/Modules/<br />
** OpenSceneGraph http://www.openscenegraph.org/svn/osg/OpenSceneGraph/trunk/CMakeModules/<br />
** OpenSync http://svn.opensync.org/branches/3rd-party-cmake-modules/modules/<br />
** http://github.com/jedbrown/cmake-modules<br />
<br />
----<br />
<br />
* Andreas Schneider, mail at cynapses dot org<br />
** FindBoost.cmake<br />
<br />
* Miguel A. Figueroa Villanueva, miguelf at ieee dot org<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindwxWidgets.cmake?root=CMake&view=markup FindwxWidgets.cmake]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindLATEX.cmake?root=CMake&view=markup FindLATEX]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindImageMagick.cmake?root=CMake&view=markup FindImageMagick]<br />
<br />
* Alan W. Irwin, irwin at beluga dot phys dot uvic dot ca<br />
** Ada<br />
<br />
* Tristan Carel, tristan dot carel at gmail dot com<br />
** FindSWIG<br />
** UseSWIG<br />
** FindSubversion<br />
<br />
* Alin M Elena, alinm dot elena at gmail dot com (http://titus.phy.qub.ac.uk/group/Alin/)<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindBLAS.cmake?root=CMake&view=markup FindBLAS]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindLAPACK.cmake?root=CMake&view=markup FindLAPACK] - <br />
<br />
* Tim Burrell (tim dot burrell at gmail dot com) (http://www.dsource.org/projects/cmaked)<br />
** D support<br />
<br />
* Philip Lowman, philip at yhbt dot com<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindGTK2.cmake?root=CMake&view=markup FindGTK2]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindOpenSceneGraph.cmake?root=CMake&view=markup FindOpenSceneGraph]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindCxxTest.cmake?root=CMake&view=markup FindCxxTest]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindDoxygen.cmake?root=CMake&view=markup FindDoxygen]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/CMakeDetermineVSServicePack.cmake?root=CMake&view=markup CMakeDetermineVSServicePack]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindGnuTLS.cmake?root=CMake&view=markup FindGnuTLS]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindFLEX.cmake?root=CMake&view=markup FindFLEX]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindBISON.cmake?root=CMake&view=markup FindBISON]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindGTest.cmake?root=CMake&view=markup FindGTest (Google C++ Testing Framework)]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindBullet.cmake?root=CMake&view=markup FindBullet]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindALSA.cmake?root=CMake&view=markup FindALSA]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindProtobuf.cmake?root=CMake&view=markup FindProtobuf]<br />
<br />
* Eric Wing ; in the commercial domain at gmail, ewing . public<br />
** FindFreeType.cmake<br />
** FindGDAL.cmake<br />
** FindGIFLIB.cmake<br />
** FindLua50.cmake, FindLua51.cmake<br />
** FindOpenAL.cmake<br />
** FindOpenThreads.cmake<br />
** FindPhysFS.cmake<br />
** FindProducer.cmake<br />
** FindQuickTime.cmake<br />
** FindSDL.cmake, FindSDL_image.cmake, FindSDL_mixer.cmake. FindSDL_net.cmake, FindSDL_sound.cmake, FindSDL_ttf.cmake<br />
** Findosg.cmake, FindosgDB.cmake, FindosgFX.cmake, FindosgGA.cmake, FindosgIntrospection.cmake, FindosgManipulator.cmake, FindosgParticle.cmake, FindosgProducer.cmake, FindosgShadow.cmake, FindosgSim.cmake, FindosgTerrain.cmake, FindosgText.cmake, FindosgUtil.cmake, FindosgViewer.cmake <br />
<br />
* Douglas Gregor (doug.gregor at gmail dot com)<br />
** FindMPI<br />
<br />
* Matt Leotta, matt.leotta at gmail dot com<br />
** FindCoin3D<br />
<br />
* Clinton Stimpson clinton at elemtech dot com<br />
** FindQt4<br />
<br />
* Petr Gotthard, petr dot gotthard at honeywell dot com<br />
** FindRTI<br />
<br />
* Will Dicharry, wdicharry at stellarscience dot com<br />
** FindHDF5<br />
** SelectLibraryConfigurations</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake_FAQ&diff=16352CMake FAQ2009-08-22T20:34:16Z<p>Plowman: /* Platform-specific questions */ add q&a regarding static runtime on MSVC</p>
<hr />
<div>== General information and availability ==<br />
=== What is CMake? ===<br />
CMake is a cross-platform, open-source make system. CMake is used to control the software compilation process using simple platform-independent 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 http://www.cmake.org/HTML/About.html to learn more about CMake.<br />
<br />
=== What is the current release? ===<br />
The latest release of CMake is always available at: http://www.cmake.org/HTML/Download.html<br />
<br />
From there, you can fetch CMake binaries for Windows or several Unix variants, or you can download the source code of CMake.<br />
<br />
You can also access nightly development through CVS; see http://www.cmake.org/HTML/Download.html for more information. You may also browse the [http://www.cmake.org/cgi-bin/viewcvs.cgi/?root=CMake cvs repository online].<br />
<br />
=== I found a Bug! What should I do? ===<br />
Please report the bug in our bug tracker: http://www.cmake.org/Bug<br />
<br />
Please make sure to look at the old bugs not to include duplicates, include detailed instructions of the bug and how to reproduce it.<br />
<br />
=== I want a new feature in CMake. What should I do? ===<br />
Report a feature request in our Bug tracker http://www.cmake.org/Bug<br />
<br />
Please make sure to look at the old feature requests not to include duplicates, include detailed instructions of the feature and proposed implementation.<br />
<br />
=== What is the most recent version covered by the Mastering CMake book? ===<br />
A new edition of the [http://www.kitware.com/products/cmakebook.html Mastering CMake] book has been released which documents CMake 2.6.<br />
<br />
The following features have been added since printing the book:<br />
<br />
* New INSTALL command (cmake --help-command INSTALL)<br />
* New LIST command (cmake --help-command LIST)<br />
* Updated FIND_PATH, FIND_PROGRAM, and FIND_FILE commands to be more powerful (cmake --help-command FIND_PATH)<br />
* RPATH and Mac OS X install_name support (cmake --help-command SET_TARGET_PROPERTIES)<br />
* CPack Beta (not finished or documented)<br />
* EXECUTE_PROCESS was added and replaces EXEC_PROGRAM<br />
* Other changes have been bug fixes and internal CMake restructuring<br />
<br />
=== Where can I find searchable CMake Mailing Archives? ===<br />
There exists at list those ones:<br />
* [http://dir.gmane.org/gmane.comp.programming.tools.cmake.user cmake on Gmane]<br />
* [http://www.mail-archive.com/cmake@cmake.org/ http://www.mail-archive.com/cmake@cmake.org/]<br />
* [http://marc.info/?l=cmake http://marc.info/?l=cmake]<br />
* Use google ''site'' keyword in order to search directly in the CMake browsable ML:<br />
site:http://www.cmake.org/pipermail/cmake/ <search terms><br />
<br />
== Running CMake ==<br />
<br />
=== Is there an option to produce more 'verbose' compiling? ===<br />
Set CMAKE_VERBOSE_MAKEFILE to ON. This will make generator to produce all outputs, including compiler lines.<br />
<br />
If you are on Windows using Borland or NMake Makefiles, then you will see lines like:<br />
<br />
cl @c:\DOCUME~1\ANDY~1.KIT\LOCALS~1\Temp\nma03504<br />
<br />
The reason for this is that Borland and Microsoft Visual Studio make programs have limitation on the length of command strings. They overcome this limitation by writing arguments to the file and then pass file to the program.<br />
<br />
If you actually want to see what the command looks like, set CMAKE_START_TEMP_FILE and CMAKE_END_TEMP_FILE to "".<br />
<br />
On Makefile generators, there is a shortcut by setting Makefile variable VERBOSE to 1. For example on UNIX:<br />
<br />
make VERBOSE=1<br />
<br />
and Windows:<br />
nmake /S force silent mode, overrides (CMAKE_VERBOSE_MAKFILE)<br />
<br />
=== Is there a way to skip checking of dependent libraries when compiling? ===<br />
<br />
'''Using the Makefile Generator'''<br />
<br />
When using the Makefile generator under *nix you can append "/fast" to your target name. For example:<br />
<br />
make target_name/fast<br />
<br />
Under Windows use a backslash instead:<br />
<br />
make target_name\fast<br />
<br />
'''Using Visual Studio >= 7.1'''<br />
<br />
If you have Visual Studio .NET 7.1 or greater you can use the native option to right click on a project and choose to build just that project.<br />
<br />
'''Using Visual Studio <= 7.0'''<br />
<br />
CMake doesn't try to compile all dependent libraries when you compile a library but it will do so for binary targets. You can't avoid this however you can take advantage of CTRL+F7 to manually compile a source file for the affected target and then relink the target by right clicking on it and choosing Link. You'll have to ensure that all dependent libraries are made up-to-date however or suffer through Visual's slow check.<br />
<br />
=== I set a cmake variable in my environment, but it didn't change anything. Why? ===<br />
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.<br />
<br />
=== I change CMAKE_C_COMPILER in the GUI but it changes back on the next configure step. Why? ===<br />
Once a build tree is created with a given compiler it cannot be changed. There are a variety of implementation reasons for this policy. In order to choose a different compiler create a new build tree and set the CC and CXX environment variables to the compiler you want before running CMake.<br />
<br />
NOTE: While I don't know what the preferred method of doing it is, I do know that the advice above (to set CC and CXX env vars) is in direct conflict with advice somewhere else that says not to use env vars to control CMAKE... Hopefully someone that knows a little more than I will fix this discrepancy.<br />
<br />
NOTE2: You could pass in e.g. <tt>-D CMAKE_C_COMPILER_INIT:STRING=mycc</tt> on the command line, or set the same variable inside a listfile (before any PROJECT() or ENABLE_LANGUAGE() command). Might that be what you're getting at?<br />
<br />
=== In CCMake, typing full paths is tedious. Is there a better way? ===<br />
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.<br />
<br />
For example:<br />
<br />
/usr/loc<TAB><br />
<br />
will expand to<br />
<br />
/usr/local/<br />
<br />
<br />
<br />
== Out-of-source build trees ==<br />
<br />
=== What is an "out-of-source" build? ===<br />
When your build generates files, they have to go somewhere. An in-source build puts them in your source tree. An out-of-source build puts them in a completely separate directory, so that your source tree is unchanged.<br />
<br />
In the first example, an in-place build is performed, i.e., the binaries are placed in the same directory as the source code.<br />
<br />
cd Hello<br />
ccmake .<br />
make<br />
<br />
In the second example, an out-of-place build is performed, i.e., the source code, libraries, and executables are produced in a directory separate from the source code directory(ies).<br />
<br />
mkdir HelloBuild<br />
cd HelloBuild<br />
ccmake ../Hello<br />
make<br />
<br />
Out-of-source builds are recommended, as you can build multiple variants in separate directories, e.g., HelloBuildDebug, HelloBuildRelease.<br />
<br />
Note: Before performing an out-of-source build ensure that any possible CMake generated in-source build information is removed from the source directory, e.g., CMakeFiles directory, and CMakeCache.txt.<br />
<br />
=== I run an out-of-source build but CMake generates in-source anyway. Why? ===<br />
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.<br />
<br />
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).<br />
<br />
=== Why does CMake use full paths, or can I copy my build tree? ===<br />
CMake uses full paths because:<br />
<br />
# configured header files may have full paths in them, and moving those files without re-configuring would cause upredictable behavior.<br />
# because cmake supports out of source builds, if custom commands used relative paths to the source tree, they would not work when they are run in the build tree because the current directory would be incorrect.<br />
# on Unix systems rpaths might be 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.<br />
<br />
Can the build tree be copied or moved?<br />
<br />
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 and rerun. Often when people want to move a binary tree it is so that they can distribute it to other users who may not have cmake in which case this would not work even if cmake would detect the move.<br />
<br />
The workaround is to create a new build tree without copying or moving the old one.<br />
<br />
<br />
=== CMake does not generate a "make distclean" target. Why? ===<br />
Some build trees created with GNU autotools have a "make distclean" target that cleans the build and also removes Makefiles and other parts of the generated build system. CMake does not generate a "make distclean" target because CMakeLists.txt files can run scripts and arbitrary commands; CMake has no way of tracking 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. (CMake does generate a "make clean" target to remove files generated by the compiler and linker.)<br />
<br />
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. Because CMake does not change the source tree, there is no need for a distclean target. One can start a fresh build by deleting the build tree or creating a separate build tree.<br />
<br />
(If a CMakeLists.txt uses ADD_CUSTOM_COMMAND to generate source files in the source tree, not the build tree, then in CMake 2.2 or higher "make clean" will remove them. See next question.)<br />
<br />
=== Running "make clean" does not remove custom command outputs. Why? ===<br />
In CMake 2.2 and higher custom command outputs should be removed by make clean. Make sure you are using at least this version. Prior to CMake 2.2 custom command outputs were not automatically added to the list of files to clean. In CMake 2.0 the 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.<br />
<br />
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 to clean away files that differ between builds.<br />
<br />
<br />
== Writing CMakeLists.txt ==<br />
<br />
=== How to have backward and forward compatibility? ===<br />
<br />
As of CMake 2.6 we employ a "Policy" mechanism to provide backwards compatibility.<br />
The basic requirement for projects is to include one line at the top of the highest CMakeLists.txt file:<br />
<br />
cmake_minimum_required(VERSION 2.6) # or other version<br />
<br />
This tells versions of CMake older than that specified that they are too old to build the project.<br />
They will report this information to the user.<br />
It also tells versions of CMake newer than that specified that the project may not be aware of policies introduced in later versions, which enables additional compatibility.<br />
For futher documentation, see<br />
<br />
* [[CMake_Policies|CMake Policy Mechanism]]<br />
* [http://www.cmake.org/cmake/help/cmake2.6docs.html#command:cmake_policy cmake_policy() command]<br />
* [http://www.cmake.org/cmake/help/cmake2.6docs.html#section_Policies CMake 2.6 Policies]<br />
<br />
=== How do I get the current source or binary directory? ===<br />
The variable CMAKE_CURRENT_SOURCE_DIR contains the absolute path to your current source directory, while CMAKE_CURRENT_BINARY_DIR points to the equivalent binary directory.<br />
<br />
=== Why are my CMake variables not updated in the GUI after a SET command? ===<br />
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.<br />
<br />
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:<br />
<br />
SET(BUILD_SHARED_LIBS ON)<br />
<br />
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.<br />
<br />
You can use the CACHE and FORCE options on the SET command to change variables in a way that will be reflected in the GUI. Run<br />
<br />
cmake --help-command SET<br />
<br />
to see full instructions for the command.<br />
<br />
<br />
=== How can I change the default build mode and see it reflected in the GUI? ===<br />
Adapt the following commands in your CMakeList.txt (this example sets the Release<br />
With Debug Information mode):<br />
<pre><br />
IF(NOT CMAKE_BUILD_TYPE)<br />
SET(CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING<br />
"Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel."<br />
FORCE)<br />
ENDIF(NOT CMAKE_BUILD_TYPE)<br />
</pre><br />
<br />
=== How do I generate an executable, then use the executable to generate a file? ===<br />
<br />
Create the generator executable by just adding a target:<br />
<br />
ADD_EXECUTABLE(generate generate.c)<br />
<br />
The rest of the process is simpler in CMake 2.6 and above than in previous versions.<br />
<br />
Use <code>ADD_CUSTOM_COMMAND</code> to specify a custom build rule for the file.<br />
(In this example we assume <code>generate</code> accepts the input and output files as arguments.)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT someoutput.txt<br />
COMMAND generate ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
DEPENDS generate ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt<br />
)<br />
<br />
This tells CMake how to build the file but does not actually add a rule to the build system.<br />
Another target must require it.<br />
One may create a custom target explicitly for this rule:<br />
<br />
ADD_CUSTOM_TARGET(driver ALL DEPENDS someoutput.txt)<br />
<br />
or the file may be added as part of some other target:<br />
<br />
ADD_EXECUTABLE(product product.c someoutput.txt)<br />
<br />
<font color=#555555><br />
In CMake 2.4 and below the <code>generate</code> target may not be specified directly in the <code>COMMAND</code> option of <code>add_custom_command</code><br />
(but it can still be used in the <code>DEPENDS</code> option as of CMake 2.4).<br />
Instead use GET_TARGET_PROPERTY to obtain the location of the generated executable.<br />
Additionally, the output must always be specified by full path.<br />
<br />
GET_TARGET_PROPERTY(GENERATE_EXE generate LOCATION)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
COMMAND ${GENERATE_EXE} ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
DEPENDS generate<br />
)<br />
</font><br />
<br />
=== How can I generate a source file during the build? ===<br />
The ADD_CUSTOM_COMMAND command lets you generate a source file that you can then include in another target. For example:<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
COMMAND ${CMAKE_COMMAND} copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.c ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.c<br />
)<br />
ADD_EXECUTABLE(foo foo.c)<br />
<br />
This will create an executable by copying bar.c to foo.c and then compiling foo.c to produce foo. CMake allows you to put generate source files in the current source or binary directory, so we were careful to output foo.c to the current binary directory. When we add foo.c to foo, CMake will look in either directory for it. Even if foo.c does not yet exist, CMake is smart enough to notice that a custom command creates it. (For the file named as the OUTPUT, CMake has its GENERATED source file property set to true.)<br />
<br />
You can also use ADD_CUSTOM_COMMAND when the<br />
[[CMake_FAQ#How_do_I_generate_an_executable.2C_then_use_the_executable_to_generate_a_file.3F|generator command is another executable in the same project]].<br />
<br />
Sometimes, the program doing the generation may generate multiple output files that each need to be part of the build. CMake 2.4 or higher supports having multiple files listed in the OUTPUT section. 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:<br />
<br />
PROJECT(FOO)<br />
# make sure cmake addes the binary directory for the project to the include path<br />
INCLUDE_DIRECTORIES(${FOO_BINARY_DIR})<br />
# add the executable that will do the generation<br />
ADD_EXECUTABLE(my_generator my_generator.cxx)<br />
GET_TARGET_PROPERTY(MY_GENERATOR_EXE my_generator LOCATION)<br />
# add the custom command that will generate all three files<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${FOO_BINARY_DIR}/output1.cpp ${FOO_BINARY_DIR}/output2.h ${FOO_BINARY_DIR}/output3.cpp<br />
COMMAND ${MY_GENERATOR_EXE} ${FOO_BINARY_DIR} ${FOO_SOURCE_DIR}/input.txt<br />
DEPENDS my_generator<br />
MAIN_DEPENDENCY ${FOO_SOURCE_DIR}/input.txt<br />
)<br />
# now create an executable using the generated files<br />
ADD_EXECUTABLE(generated<br />
${FOO_BINARY_DIR}/output1.cpp<br />
${FOO_BINARY_DIR}/output2.h<br />
${FOO_BINARY_DIR}/output3.cpp)<br />
<br />
CMake 2.4 allows you to generate a header file. Because generated headers often cause unnecessary rebuilds, you should try to avoid them; consider using the CONFIGURE_FILE command to prepare the header at CMake time. If you must generate a header file, use code like this:<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.h<br />
COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.h ${CMAKE_CURRENT_BINARY_DIR}/foo.h<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.h<br />
)<br />
ADD_EXECUTABLE(foo foo.c ${CMAKE_CURRENT_BINARY_DIR}/foo.h)<br />
<br />
This is like the first example above, except that it generates a header instead of a C file. The header might not exist when the build system scans foo.c's dependencies, so there is no way for CMake to know that this target requires foo.h unless we can tell it that foo.h may exist in the future. We give CMake this knowledge by listing the generated header file in the set of source files for the target. (This requires CMake 2.4. Previous versions of CMake required use of the OBJECT_DEPENDS source file property.)<br />
<br />
=== How can I add a dependency to a source file which is generated in a subdirectory? ===<br />
<br />
Rules created with <code>ADD_CUSTOM_COMMAND</code> as [[CMake_FAQ#How_can_I_generate_a_source_file_during_the_build.3F|above]] have scope only in the directory in which they are specified.<br />
If the generated file is needed in another directory, a target-level dependency needs to be added.<br />
Create a target in the subdirectory with the custom rule in order to drive it:<br />
<br />
# subdir/CMakeLists.txt<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
COMMAND ${CMAKE_COMMAND} copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.c ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.c<br />
)<br />
ADD_CUSTOM_TARGET(generate_foo DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/foo.c)<br />
<br />
Now other targets can depend on the target from the subdirectory:<br />
<br />
# CMakeLists.txt<br />
ADD_SUBDIRECTORY(subdir)<br />
# Create the executable.<br />
ADD_EXECUTABLE(generated ${CMAKE_CURRENT_BINARY_DIR}/subdir/foo.c)<br />
# Tell CMake the source won't be available until build time.<br />
SET_SOURCE_FILES_PROPERTIES(${CMAKE_CURRENT_BINARY_DIR}/subdir/foo.c PROPERTIES GENERATED 1)<br />
# Make sure the source is generated before the executable builds.<br />
ADD_DEPENDENCIES(generated generate_foo)<br />
<br />
=== I use EXEC_PROGRAM but the result is not set in subdirectories. Why? ===<br />
<br />
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 was fixed in CMake 2.2, but for older versions you will have to cache the result:<br />
<br />
<pre><br />
EXEC_PROGRAM(my-program OUTPUT_VARIABLE MY_OUTPUT)<br />
SET(MY_OUTPUT "${MY_OUTPUT}" CACHE INTERNAL "")<br />
</pre><br />
<br />
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.<br />
<br />
=== How can I get or set environment variables? ===<br />
<br />
CMake names environment variables using an ENV prefix and surrounding the names in curly braces. Here is an example:<br />
<br />
<pre><br />
MESSAGE("$ENV{PATH}")<br />
</pre><br />
<br />
Reading variables will work in any version of CMake. Writing to them works in CMake 2.2 and higher using the following syntax:<br />
<br />
<pre><br />
SET(ENV{HELLO} "World")<br />
</pre><br />
<br />
Note that there is currently no way to tell apart an empty environment variable value from a variable that is not set at all.<br />
<br />
One should avoid using environment variables for controlling the flow of CMake code (such as in IF commands). The build system generated by CMake may re-run CMake automatically when CMakeLists.txt files change. The environment in which this is executed is controlled by the build system and may not match that in which CMake was originally run. If you want to control build settings on the CMake command line, you need to use cache variables set with the -D option. The settings will be saved in CMakeCache.txt so that they don't have to be repeated every time CMake is run on the same build tree.<br />
<br />
Also, environment variables SET in the CMakeLists.txt ''only'' take effect for cmake itself, so you cannot use this method to set an environment variable that a custom command might need.<br />
<br />
=== Why do I have unwanted semicolons ; in my compiler flags? ===<br />
CMake has a list data type. A list is stored as a string of semicolon-separated list elements. Whitespace separated arguments to a SET statement are interpreted as list elements. For instance, SET(var a b c d e) will give "var" a value of a;b;c;d;e and this list can be used by other CMake commands. However, if you pass ${var} to a non-CMake external tool, such as a compiler's command line, you are passing a;b;c;d;e which is not what you want. Instead you either need to pass "${var}", so that the list will be converted to a whitespace-separated string, or you need to SET(var "a b c d e") in the 1st place so that you're working with a string, not a list.<br />
<br />
=== How can I get quoting and escapes to work properly? ===<br />
If you want to escape a character in CMake, you use "\", like in C code. For example, if you wanted to have a quote embedded in a string you would do this: "\"". However, each level of CMake that processes your code will need one level of escaping to work. So, if you configure a file that is read by cmake or cpack and you want to do the same thing, you would do "\\\"". You would still need to escape the " for the first cmake that processes the string. However, this time, you would want to also escape a '\' as well. This would leave the next level of processing with "\"". Also, for custom commands that may get passed to a shell, it maybe required to do escaping for that shell.<br />
<br />
=== Isn't the "Expression" in the "ELSE (Expression)" confusing? ===<br />
Traditional CMakeLists.txt files prior to 2.6.0, require the following syntax. In the IF syntax, the ELSE section requires the same (Expression) as the IF section. This sometimes can make the script kind of hard to follow, take the short example below:<br />
<br />
IF(WIN32)<br />
...do something...<br />
ELSE(WIN32)<br />
...do something else...<br />
ENDIF(WIN32)<br />
<br />
You might think that the ELSE section, here containing "...do something else...", is for the WIN32 portion of the script. That is not so! It is actually handling the NOT WIN32 section.<br />
<br />
As of CMake 2.6.0 the ELSE() and ENDIF() constructs can be empty. The same is true for closing constructs on ENDMACRO(), ENDFUNCTION(), and ENDFOREACH(). If you require 2.4.x compatibility, you can enable the CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS option on CMake 2.4.3 or greater. This option is superfluous on CMake 2.6.0 or greater.<br />
<br />
SET(CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS true)<br />
<br />
IF(WIN32)<br />
...do something...<br />
ELSEIF(APPLE)<br />
...do something else...<br />
ELSE()<br />
...do something else...<br />
ENDIF()<br />
<br />
=== Which regular expressions are supported by CMake? ===<br />
When using MATCHES or MATCHALL in an IF command, or using any of the STRING(REGEX ...) commands, CMake expects regular expressions, not globs (wild cards). CMake uses the same regular expression engine above all platforms. Here are the meanings of the metacharacters:<br />
<br />
^ Matches at beginning of a line<br />
$ Matches at end of a line<br />
. Matches any single character<br />
[ ] Matches any character(s) inside the brackets<br />
[^ ] Matches any character(s) not inside the brackets<br />
- Matches any character in range on either side of a dash<br />
| Matches a pattern on either side of the |<br />
* Matches preceding pattern zero or more times<br />
+ Matches preceding pattern one or more times<br />
? Matches preceding pattern zero or once only<br />
() Saves a matched expression and uses it in a later match<br />
<br />
Example: "[-][L]([^ ;])+" matches all strings beginning with -L and ending with a space or a semicolon, the usual linkdirs under Linux.<br />
<br />
Here is how to catch a part of a string. The variable test is filled with some content, and then we want to catch the "me":<br />
<br />
SET(test "hello world ! catch: me if you can")<br />
STRING(REGEX REPLACE ".*catch: ([^ ]+).*" "\\1" result "${test}" )<br />
MESSAGE(STATUS "result= ${result}")<br />
<br />
This is slightly tricky. The part inside the brackets is available in \\1 . CMake will copy the variable test to the variable result, but then it will replace everything that the regular expression matches with \\1. This means the first regular expression has to match the whole string and the part we want to catch has to be put in parens.<br />
<br />
-- result= me<br />
<br />
For those of you who know Perl, the equivalent Perl code could be:<br />
<br />
$test = "hello world ! catch: me if you can";<br />
$result = $test;<br />
$result =~ s/.*catch: ([^ ]+).*/$1/;<br />
print "-- result= $result\n";<br />
<br />
There are other ways to do this in Perl, but this is how we do it in CMake because \\1 does not become a variable like $1 does in perl, so there is no SET(result ${\\1}) in CMake.<br />
<br />
<br />
=== How to convert a semicolon separated list to a whitespace separated string? ===<br />
<br />
set(foo<br />
abc.c<br />
abc.b<br />
abc.a<br />
)<br />
<br />
foreach(arg ${foo})<br />
set(bar "${bar} ${arg}")<br />
endforeach(arg ${foo})<br />
<br />
message("foo: ${foo}")<br />
message("bar: ${bar}")<br />
<br />
=== How can I build multiple modes without switching ? ===<br />
To build multiple modes (e.g. Debug and Release) in one shot without constantly running cmake -DCMAKE_BUILD_TYPE=Debug and cmake -DCMAKE_BUILD_TYPE=Release in source tree create a directory for builds eg.:<br />
<br />
<pre><br />
Project-directory/<br />
/Build<br />
</pre><br />
<br />
Inside you can place as many target directories for out-of-source build modes as you want, e.g.:<br />
<br />
<pre><br />
Project-directory/<br />
/Build<br />
/Debug<br />
/Release<br />
</pre><br />
<br />
In each of these directories issue a command (assuming that you have CMakeLists.txt directly in Project-directory)<br />
<br />
<pre><br />
cmake -DCMAKE_BUILD_TYPE=type_of_build ../../<br />
</pre><br />
<br />
to create a cmake cache configured for requested build type.<br />
<br />
Now you can make each build just by entering appropriate directory and executing a make command.<br />
<br />
=== How can I extend the build modes with a custom made one ? ===<br />
The following code snipet (taken from a CMakeLists.txt) adds a Maintainer mode:<br />
<pre><br />
SET( CMAKE_CXX_FLAGS_MAINTAINER "-Wall -Wabi" CACHE STRING<br />
"Flags used by the C++ compiler during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_C_FLAGS_MAINTAINER "-Wall -pedantic" CACHE STRING<br />
"Flags used by the C compiler during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_EXE_LINKER_FLAGS_MAINTAINER<br />
"-Wl,--warn-unresolved-symbols,--warn-once" CACHE STRING<br />
"Flags used for linking binaries during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_SHARED_LINKER_FLAGS_MAINTAINER<br />
"-Wl,--warn-unresolved-symbols,--warn-once" CACHE STRING<br />
"Flags used by the shared libraries linker during maintainer builds."<br />
FORCE )<br />
MARK_AS_ADVANCED(<br />
CMAKE_CXX_FLAGS_MAINTAINER<br />
CMAKE_C_FLAGS_MAINTAINER<br />
CMAKE_EXE_LINKER_FLAGS_MAINTAINER<br />
CMAKE_SHARED_LINKER_FLAGS_MAINTAINER )<br />
# Update the documentation string of CMAKE_BUILD_TYPE for GUIs<br />
SET( CMAKE_BUILD_TYPE "" CACHE STRING<br />
"Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel Maintainer."<br />
FORCE )<br />
</pre><br />
Notes: The flags used in this example are specific to GCC. Change them as needed for your project. Additionally the SET(CMAKE_BUILD_TYPE) command will override<br />
a CMAKE_BUILD_TYPE previously set in the CMakeLists.txt.<br />
<br />
=== Why does <code>foreach</code> skip empty values? ===<br />
<br />
The code in question is of the form<br />
<br />
set(var "a;b;;c;d") # list 'a', 'b', '', 'c', 'd'<br />
foreach(v ${var})<br />
# v=a, v=b, v=c, v=d, one at a time<br />
endforeach()<br />
<br />
and the loop variable 'v' never attains the empty-string value ''.<br />
This is because the <code>${var}</code> syntax is an unquoted argument so the CMake language expands the list and removes the empty value.<br />
The foreach command does not even see the empty value.<br />
One can verify this because the code<br />
<br />
foreach(v a b "" c d)<br />
...<br />
endforeach()<br />
<br />
will see the empty value.<br />
<br />
=== Does CMake support precompiled headers? ===<br />
<br />
Yes and no. Every platform does precompiled headers a bit differently, and there is currently no first-class interface provided by CMake and implemented on every platform.<br />
However, CMake does provide enough primitives for projects to use precompiled headers on specific platforms.<br />
Our issue tracker has a [http://www.cmake.org/Bug/view.php?id=1260 feature request] with attachements providing user-contributed helper macros for some platforms.<br />
<br />
== Writing FindXXX.cmake files ==<br />
<br />
=== What are the rules to write a FindXXX.cmake file? ===<br />
<br />
Let's follow the instructions and the advices in the <br />
Modules/readme.txt [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/readme.txt?root=CMake&view=markup]<br />
file located in the CVS repository.<br />
<br />
=== Why does find_library look in system directories before its PATHS option? ===<br />
<br />
The code in question is often of the form<br />
<br />
find_library(FOO_LIBRARY NAMES foo PATHS /opt/foo/lib)<br />
<br />
CMake will find "<code>/usr/lib/libfoo.so</code>" instead of "<code>/opt/foo/lib/libfoo.so</code>" if both exist.<br />
The reason is that /opt/foo/lib is a <i>hard-coded guess</i> of the location.<br />
The documentation of <code>[http://www.cmake.org/cmake/help/cmake2.6docs.html#command:find_library find_library]</code> specifies the search order.<br />
User, project, and system configuration variables are always more local than hard-coded guesses and should override them, so<br />
the PATHS option is used last.<br />
<br />
Some find-modules compute probable locations based on other information <i>available from the system</i> such as a project-specific environment variable.<br />
The HINTS option (CMake 2.6 and higher) takes precedence over system directories specifically for this case:<br />
<br />
file(TO_CMAKE_PATH "$ENV{FOO_LIB_DIR}" FOO_LIB_DIR)<br />
find_library(FOO_LIBRARY NAMES foo HINTS ${FOO_LIB_DIR})<br />
<br />
CMake will find "<code>$ENV{FOO_LIB_DIR}/libfoo.so</code>" before "<code>/usr/lib/libfoo.so</code>".<br />
<br />
== Finding and using external packages ==<br />
<br />
=== How do I use CMake to generate SWIG wrapper libraries? ===<br />
<br />
CMake version 2 includes a module that supports the generation of SWIG wrapper libraries. The SWIG package defines the following macros: SWIG_ADD_MODULE and SWIG_LINK_LIBRARIES.<br />
<br />
<pre><br />
# This example shows how to use python<br />
# Currently these languages have been tested:<br />
# perl tcl ruby php4 pike<br />
<br />
FIND_PACKAGE(SWIG REQUIRED)<br />
INCLUDE(${SWIG_USE_FILE})<br />
<br />
FIND_PACKAGE(PythonLibs)<br />
INCLUDE_DIRECTORIES(${PYTHON_INCLUDE_PATH})<br />
<br />
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})<br />
<br />
SET(CMAKE_SWIG_FLAGS "")<br />
<br />
SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES CPLUSPLUS ON)<br />
SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES SWIG_FLAGS "-includeall")<br />
SWIG_ADD_MODULE(example python<br />
example.i example.cxx)<br />
SWIG_LINK_LIBRARIES(example ${PYTHON_LIBRARIES})<br />
<br />
</pre><br />
<br />
<pre><br />
# This example shows how to use tcl<br />
PROJECT(TCL_WRAP)<br />
SET ( MODULE_NAME project )<br />
SET ( INTERFACE_FILES project.i)<br />
SET ( SRC_FILES Vertex.h Vertex.cxx Shapes.h Shapes.cxx )<br />
<br />
FIND_PACKAGE(SWIG REQUIRED)<br />
INCLUDE(${SWIG_USE_FILE})<br />
<br />
# Look for TCL<br />
INCLUDE_DIRECTORIES(${TCL_INCLUDE_PATH})<br />
<br />
FIND_LIBRARY(TCL_LIBRARY NAMES tcl tcl84 tcl83 tcl82 tcl80<br />
PATHS /usr/lib /usr/local/lib)<br />
IF (TCL_LIBRARY)<br />
TARGET_ADD_LIBRARY (${MODULE_NAME} TCL_LIBRARY)<br />
ENDIF (TCL_LIBRARY)<br />
<br />
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})<br />
<br />
SET(CMAKE_SWIG_FLAGS "-c++")<br />
<br />
SET_SOURCE_FILES_PROPERTIES(${INTERFACE_FILES} PROPERTIES CPLUSPLUS ON)<br />
SET_SOURCE_FILES_PROPERTIES(${INTERFACE_FILES} PROPERTIES CMAKE_SWIG_FLAGS "-includeall")<br />
SWIG_ADD_MODULE(${MODULE_NAME} tcl ${INTERFACE_FILES} ${SRC_FILES})<br />
SWIG_LINK_LIBRARIES(${MODULE_NAME} ${TCL_LIBRARIES})<br />
</pre><br />
<br />
=== How do I use CMake to build LaTeX documents? ===<br />
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.<br />
<br />
PROJECT(Document)<br />
IF(LATEX_COMPILE)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${Document_BINARY_DIR}/TDocument.dvi<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.tex<br />
COMMAND ${LATEX_COMPILE} <br />
ARGS ${Document_SOURCE_DIR}/TDocument.tex <br />
)<br />
ENDIF(LATEX_COMPILE)<br />
<br />
IF(DVIPDF_COMPILE)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${Document_BINARY_DIR}/TDocument.pdf<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.dvi <br />
COMMAND ${DVIPDF_COMPILE}<br />
ARGS ${Document_SOURCE_DIR}/TDocument.dvi<br />
)<br />
ENDIF(DVIPDF_COMPILE)<br />
<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.pdf<br />
)<br />
<br />
The following uses commands in CMake version 2.0 and later<br />
<br />
PROJECT(Document)<br />
# <br />
# Find LaTeX<br />
#<br />
FIND_PACKAGE(LATEX)<br />
<br />
IF(LATEX_COMPILER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.dvi<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS ${Document_SOURCE_DIR}/TDocument.tex<br />
DEPENDS ${Document_SOURCE_DIR}/TDocument.tex<br />
COMMENT "Tex2dvi"<br />
)<br />
<br />
IF(DVIPS_CONVERTER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.ps<br />
COMMAND ${DVIPS_CONVERTER}<br />
ARGS ${Document_BINARY_DIR}/TDocument.dvi<br />
-o ${Document_BINARY_DIR}/TDocument.ps<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.dvi<br />
COMMENT "dvi2ps"<br />
)<br />
<br />
IF(PS2PDF_CONVERTER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.pdf<br />
COMMAND ${PS2PDF_CONVERTER}<br />
ARGS ${Document_BINARY_DIR}/TDocument.ps<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.ps<br />
COMMENT "ps2pdf"<br />
)<br />
<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.pdf<br />
)<br />
ENDIF(PS2PDF_CONVERTER)<br />
ENDIF(DVIPS_CONVERTER)<br />
ENDIF(LATEX_COMPILER)<br />
<br />
=== How do I get LaTeX references to be correct? ===<br />
When your latex document contains references (e.g. \ref{...} command) you get to run two passes of latex. In the<br />
most general case, i.e. when additionally your document uses a bibtex bibliography, you shall need three<br />
passes of latex (and one pass of bibtex):<br />
# latex (first pass: for bibtex to have an .aux file)<br />
# bibtex (for generating the .bbl file)<br />
# latex (second pass)<br />
# latex (third pass)<br />
<br />
The following code snippet illustrates how you can "pervert" the bibtex and latex generated<br />
auxilary files (.aux, .log, .dvi, .bbl...) to create an "artificial" set of CMake dependencies.<br />
The side-effect of those dependencies should hopefully be the above described sequence of calls<br />
to latex and bibtex<br />
<pre><br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.aux<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/UsersManual.tex<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (first pass)"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.aux<br />
COMMAND ${BIBTEX_COMPILER}<br />
ARGS -terse ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Bibtex"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.dvi<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (second pass)"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.log<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
${CMAKE_CURRENT_BINARY_DIR}/UsersManual.dvi<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (third pass)"<br />
)<br />
# Eventually trigger the whole process<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.log<br />
)<br />
</pre><br />
<br />
=== How can I set TEXINPUTS for a LaTeX compilation? ===<br />
First note that most often you can avoid using TEXINPUTS by copying all the necessary files (.tex source file and<br />
included graphic files e.g. .eps files) from your PROJECT_SOURCE_DIR hirarchy to your PROJECT_BINARY_DIR subdir<br />
[refer to CONFIGURE_FILE with the COPYONLY flag set for copying files]. Since by default latex uses the current working directory as value for TEXINPUTS you should be all set. As expected, this trick is quick AND dirty since your<br />
concerned PROJECT_BINARY_DIR subdir now contains files that are NOT generated by CMake (in the sense that those<br />
files are not the result of a system command but were merely duplicated)... <br />
<br />
If you consider it is cleaner or easier to define a TEXINPUTS environment variable [the latex command probably<br />
misses a -I flag] you can find an example in the InsightDocuments cvs archive (refer to the section "cvs access"<br />
near the bottom of Kitware's ITK download page) or use google with keywords "ITK_TEXINPUTS CONFIGURE_FILE".<br />
Look at InsightDocuments/CourseWare/Training/Vis2003/Latex/CMakeLists.txt and search for e.g. "LaTeXWrapper.sh.in".<br />
<br />
Roughly the mechanism goes:<br />
* SET ITK_TEXINPUTS with the desired TEXINPUTS<br />
* CONFIGURE_FILE "InsightDocuments/CourseWare/Training/Vis2003/LaTeXWrapper.sh.in" which generates an sh shell script setting the shell variable TEXINPUTS prior to running the latex command<br />
* use ADD_CUSTOM_COMMAND to invoke this shell script<br />
This very example is Win32 portable (except that LaTeXWrapper.bat.in generates a .bat shell script)<br />
<br />
== Library questions ==<br />
<br />
=== Can I build both shared and static libraries with one ADD_LIBRARY command? ===<br />
<br />
No. Each library you build must have a unique target name, i.e. the "libname" field of the ADD_LIBRARY command. That way, CMake can track dependencies separately for each library. Libraries can have the same OUTPUT_NAME, see the SET_TARGET_PROPERTIES command, but this is not the default.<br />
<br />
=== Does that mean I have to build all my library objects twice, once for shared and once for static?! I don't like that! ===<br />
<br />
In practice, most libraries have different defines and compiler flags for the shared vs. static cases. So you would have to build all your library objects twice anyways. However, if you happen to have '''''exactly''''' the same defines and compiler flags for the shared vs. static cases...<br />
<br />
...if you're using Linux and a GCC-style linker, you could do the following. Note that for this to work correctly on linux, the zzSTATIC source files should have been compiled with "-fPIC" to ensure they will work in a shared library.<br />
<br />
IF(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_COMPILER_IS_GNUCC)<br />
ADD_LIBRARY(zzSTATIC STATIC -fPIC)<br />
ADD_LIBRARY(zzDYNAMIC SHARED)<br />
TARGET_LINK_LIBRARIES(zzDYNAMIC -Wl,-whole-archive zzSTATIC -Wl,-no-whole-archive)<br />
ENDIF(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_COMPILER_IS_GNUCC)<br />
<br />
...if you want a cross-platform approach that works on all compilers, not just GCC or Linux, you could extract the locations of previously built object files and insert them directly into the libraries that need them. This is documented in [http://www.cmake.org/Bug/view.php?id=5155 CMake Feature Request #5155: standard way to locate object files]. Unfortunately this approach relies on CMake's internal implementation, and that implementation could change in the future, breaking your code.<br />
<br />
=== How do I make my shared and static libraries have the same root name, but different suffixes? ===<br />
Set the OUTPUT_NAME of your shared and static libraries to the same thing.<br />
<br />
ADD_LIBRARY(foo SHARED ${foo_sources})<br />
ADD_LIBRARY(foo-static STATIC ${foo_sources})<br />
// The library target "foo" already has a default OUTPUT_NAME of "foo", so we don't need to change it.<br />
// The library target "foo-static" has a default OUTPUT_NAME of "foo-static", so change it.<br />
SET_TARGET_PROPERTIES(foo-static PROPERTIES OUTPUT_NAME "foo")<br />
<br />
If you are building your shared and static libraries in the same directory, you will also need the following to keep your shared and static libraries from clobbering each other during the build.<br />
<br />
SET_TARGET_PROPERTIES(foo PROPERTIES CLEAN_DIRECT_OUTPUT 1)<br />
SET_TARGET_PROPERTIES(foo-static PROPERTIES CLEAN_DIRECT_OUTPUT 1)<br />
<br />
=== How do I rename a library after it has already been built? ===<br />
You don't rename it. It's been built! Its name is whatever CMakeLists.txt says it's supposed to be.<br />
<br />
Perhaps you want to copy the library to a different name. But, are you sure that's what you want to do? You could just change the name in your ADD_LIBRARY command or change its OUTPUT_NAME property using SET_TARGET_PROPERTY(). If you really really want to copy the library to a different name, try:<br />
<br />
GET_TARGET_PROPERTY(LIB_NAME Foo LOCATION)<br />
GET_TARGET_PROPERTY(Bar_prefix Foo PREFIX)<br />
GET_TARGET_PROPERTY(Bar_suffix Foo SUFFIX)<br />
SET(NEW_LIB_NAME ${Bar_prefix}Bar${Bar_suffix})<br />
<br />
ADD_CUSTOM_COMMAND(<br />
TARGET Foo<br />
POST_BUILD<br />
COMMAND ${CMAKE_COMMAND} -E copy ${LIB_NAME} ${NEW_LIB_NAME}<br />
)<br />
<br />
On Windows you may also want to copy the .dll import lib, using the same approach as above, but with IMPORT_PREFIX and IMPORT_SUFFIX. ''Problem: LOCATION only refers to 1 file, the .dll. What is a simple way to get the location of the import lib? Could provide a complicated way, but that's annoying.''<br />
<br />
=== Does CMake support "convenience" libraries? ===<br />
No. CMake does not currently support convenience libraries. A "convenience" library, as GNU libtool calls it, is an archive of objects to be mixed into other libraries. Other libraries "link" to the convenience library, but the convenience library does not export any symbols; GNU libtool never installs the convenience library; no programs ever link to the convenience library.<br />
<br />
This does '''not''' mean that a project using convenience libraries cannot be converted to CMake. Instead the source files may be listed in each target that needs them. They will be built for each target separately using all the preprocessor definitions and flags configured for that target.<br />
<br />
=== Why are libraries linked to my shared library included when something links to it? ===<br />
This question arises when one has a library B which links to some library A. When a third target, say C, links to B, CMake will automatically include C to A also. When the libraries are static, then this is always necessary. When the libraries are shared, this is the default behavior provided by CMake. CMake 2.6 and above provide the target property "LINK_INTERFACE_LIBRARIES" (http://www.cmake.org/HTML/cmake-2.6.html#prop_tgt:LINK_INTERFACE_LIBRARIES) to specify the libraries that should be transitively included in the link by CMake. CMake 2.4 and below do not support the property.<br />
<br />
Something like the following will work in CMake 2.6:<br />
<br />
<pre><br />
set_target_properties(mylibrary<br />
PROPERTIES<br />
LINK_INTERFACE_LIBRARIES ""<br />
)<br />
</pre><br />
<br />
=== CMake dependency scanner ===<br />
<br />
CMake does not preprocess source files while scanning dependencies. Code like<br />
<pre><br />
#if 0<br />
# include "bla.h"<br />
#endif<br />
</pre><br />
will result in a dependency on "bla.h". This sometimes leads to source files recompiling unnecessarily but will not break the build.<br />
<br />
== Installation questions ==<br />
<br />
=== Does CMake's "make install" support DESTDIR? ===<br />
'''Yes''', especially when the build-system generator uses CMake's builtin support for installing files: Simply define the DESTDIR environment variable during installation and CMake will treat that value as the root of the file system for all installation paths; naturally, the DESTDIR path must be absolute.<br />
<br />
For example, if the Makefile generator is used, then all of the following are example usages of DESTDIR (perhaps assuming the bash shell for the last 2):<br />
<br />
(1) make install DESTDIR="/some/absolute/path"<br />
(2) make DESTDIR="/some/absolute/path" install<br />
(3) DESTDIR="/some/absolute/path" make install<br />
(4) export DESTDIR="/some/absolute/path<br />
make install<br />
<br />
=== Can I do "make uninstall" with CMake?===<br />
By default, CMake does not provide the "make uninstall" target, so you cannot do this. We do not want "make uninstall" to remove useful files from the system.<br />
<br />
If you want an "uninstall" target in your project, then nobody prevents you from providing one. You need to delete the files listed in install_manifest.txt file. Here is how to do it. First create file cmake_uninstall.cmake.in in the top-level directory of the project:<br />
<br />
<pre><br />
IF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")<br />
MESSAGE(FATAL_ERROR "Cannot find install manifest: \"@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt\"")<br />
ENDIF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")<br />
<br />
FILE(READ "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt" files)<br />
STRING(REGEX REPLACE "\n" ";" files "${files}")<br />
FOREACH(file ${files})<br />
MESSAGE(STATUS "Uninstalling \"$ENV{DESTDIR}${file}\"")<br />
IF(EXISTS "$ENV{DESTDIR}${file}")<br />
EXEC_PROGRAM(<br />
"@CMAKE_COMMAND@" ARGS "-E remove \"$ENV{DESTDIR}${file}\""<br />
OUTPUT_VARIABLE rm_out<br />
RETURN_VALUE rm_retval<br />
)<br />
IF(NOT "${rm_retval}" STREQUAL 0)<br />
MESSAGE(FATAL_ERROR "Problem when removing \"$ENV{DESTDIR}${file}\"")<br />
ENDIF(NOT "${rm_retval}" STREQUAL 0)<br />
ELSE(EXISTS "$ENV{DESTDIR}${file}")<br />
MESSAGE(STATUS "File \"$ENV{DESTDIR}${file}\" does not exist.")<br />
ENDIF(EXISTS "$ENV{DESTDIR}${file}")<br />
ENDFOREACH(file)<br />
</pre><br />
<br />
Then in the top-level CMakeLists.txt add the following logic:<br />
<br />
<pre><br />
CONFIGURE_FILE(<br />
"${CMAKE_CURRENT_SOURCE_DIR}/cmake_uninstall.cmake.in"<br />
"${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake"<br />
IMMEDIATE @ONLY)<br />
<br />
ADD_CUSTOM_TARGET(uninstall<br />
"${CMAKE_COMMAND}" -P "${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake")<br />
</pre><br />
<br />
Now you will have an "uninstall" target at the top-level directory of your build tree.<br />
<br />
Instead of creating an "uninstall" target, Unix users could enter this command in the shell:<br />
<br />
xargs rm < install_manifest.txt<br />
<br />
== Distribution questions ==<br />
<br />
=== Where is "make dist"? ===<br />
<br />
CMake doesn't create a "make dist" target.<br />
<br />
=== What is the best way to distribute source code or binaries for a cmake-based project? ===<br />
<br />
For creating source or binary packages there is now [[CMake#CPack | CPack]] coming with CMake, see the <br />
[[ CMake#CPack | documentation]].<br />
<br />
Of course you can also use any other ways to create packages.<br />
<br />
== Platform-specific questions ==<br />
=== How do I build universal binaries on Mac OS X? ===<br />
Before running CMake with an empty build tree, set the CMAKE_OSX_ARCHITECTURES environment variable. It should be set to contain a ; separated list of architectures that you want in the binary. For example, for 32-bit PowerPC and Intel you would do this:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386<br />
<br />
If you wish to build both as 32 and 64 bit, do this:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386;ppc64;x86_64<br />
<br />
You can also set the same named CMake cache variable on an existing binary tree. This works with both makefiles and the Xcode generator. <br />
<br />
In addition, you can also set the CMAKE_OSX_SYSROOT variable to point to the sysroot (aka Mac OS SDK) to be used. CMake will attempt to pick one on your system, but it can be changed in the cache or via an environment variable before running CMake. The 10.4u SDK or later must be used to create a Universal Binary.<br />
<br />
Universal Binaries are essentially cross compilation and so you should avoid using TRY_RUN, especially for things like testing endianess or variable size because the result will only be correct for one architecture.<br />
<br />
Lastly, note that CTest is only able to test one architecture. See bug 6157.<br />
<br />
=== How can I apply resources on Mac OS X automatically? ===<br />
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 a custom rule which is executed after the executable is linked:<br />
<br />
<pre><br />
ADD_EXECUTABLE(MyExecutable ${MyExecutable_SRCS})<br />
GET_TARGET_PROPERTY(MyExecutable_PATH MyExecutable LOCATION)<br />
<br />
IF(APPLE)<br />
FIND_PROGRAM(APPLE_RESOURCE Rez /Developer/Tools)<br />
IF(APPLE_RESOURCE)<br />
ADD_CUSTOM_COMMAND(TARGET MyExecutable POST_BUILD<br />
COMMAND ${APPLE_RESOURCE} Carbon.r -o ${MyExecutable_PATH})<br />
ENDIF(APPLE_RESOURCE)<br />
ENDIF(APPLE)<br />
</pre><br />
<br />
This will execute:<br />
<br />
/Developer/Tools/Rez Carbon.r -o /binary/path/MyExecutable<br />
<br />
after MyExecutable is linked.<br />
<br />
'Rez' may be located elsewhere on disk, depending on the version of Mac OS X and Xcode. You can use 'which Rez' in Terminal to find it's full path.<br />
<br />
=== Why does FIND_LIBRARY not find .DLL libraries under WIN32? ===<br />
For those who come from a Unix background to MS Windows:<br />
<br />
You never link directly to the .dll, you have to link against the import library .lib for the .dll.<br />
<br />
Linking against dynamic libraries (.dll under Windows) is quite different from linking against ELF shared objects (.so) under platforms like Linux or NetBSD. In Windows, there are two types of library, a static library and an import library (both confusingly use the .lib extension, however). In Windows, when you build an import library (A.lib) you will get a corresponding (A.dll) that you only need at runtime. At compile time you will need the import library.<br />
<br />
Conclusion: There is no need to find a .dll for linking. You only need to find the .lib import library.<br />
<br />
Some more details can be found here: [http://xenophilia.org/winvunix.html].<br />
<br />
=== Why am I getting a linker error to _mainCRTStartup under WIN32? ===<br />
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.<br />
<br />
ADD_EXECUTABLE(exename WIN32 source1 source2 ... sourceN)<br />
<br />
The second argument to ADD_EXECUTABLE can be WIN32. This indicates that the executable, when compiled on Windows, is a Windows app (using WinMain) and not a console app (using main). Please note that on Unix platforms, CMake ignores the WIN32 and the compiler will use "main" in any case.<br />
<br />
=== Why do I get this error: nafxcwd.lib(appcore.obj) : error LNK2001: unresolved external symbol ___argv ===<br />
<br />
This is because the application is using both the static and dll versions of the MFC library.<br />
To fix the problem, you can do the following:<br />
<br />
SET(CMAKE_MFC_FLAG 2) # force the IDE to use static MFC<br />
ADD_DEFINITIONS(-D_AFXDLL) # make sure if afx.h is included the dll MFC is used<br />
<br />
=== How to use MFC with CMake ===<br />
To use MFC, the CMAKE_MFC_FLAG variable must be set as follows:<br />
<br />
0: Use Standard Windows Libraries<br />
1: Use MFC in a Static Library<br />
2: Use MFC in a Shared DLL <br />
<br />
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:<br />
<br />
ADD_DEFINITIONS(-D_AFXDLL)<br />
SET(CMAKE_MFC_FLAG 2) <br />
ADD_EXECUTABLE(CMakeSetup WIN32 ${SRCS})<br />
<br />
Note that visual studio 9 project files do not appear to work with CMAKE_MFC_FLAG 1; this may be related to [http://www.cmake.org/Bug/view.php?id=7056 bug 7056].<br />
<br />
In order to use MFC with UNICODE, you must also [http://msdn.microsoft.com/en-us/library/dybsewaf.aspx specify the entry point wWinMainCRTStartup]. For example:<br />
<br />
set(CMAKE_MFC_FLAG 2)<br />
set_target_properties(MyApp PROPERTIES<br />
COMPILE_DEFINITIONS _AFXDLL,_UNICODE,UNICODE,_BIND_TO_CURRENT_CRT_VERSION,_BIND_TO_CURRENT_MFC_VERSION<br />
LINK_FLAGS "/ENTRY:\"wWinMainCRTStartup\"")<br />
<br />
See [http://stackoverflow.com/questions/59635/app-does-not-run-with-vs-2008-sp1-dlls-previous-version-works-with-rtm-versions this article] as to why _BIND_TO_CURRENT_CRT_VERSION and _BIND_TO_CURRENT_MFC_VERSION are necessary for Visual Studio 2008 SP1.<br />
<br />
=== How To Put Files in Folders in Visual Studio Projects ===<br />
The Visual Studio IDE supports putting files into folders.<br />
CMake can be used to put files in folders with the SOURCE_GROUP <br />
command. <br />
<br />
SOURCE_GROUP(name [REGULAR_EXPRESSION regex] [FILES src1 src2 ...])<br />
<br />
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 provided the source file is being passed to ADD_EXECUTABLE or ADD_LIBRARY.<br />
<br />
For example:<br />
SOURCE_GROUP(FooFiles FILES foo.cxx)<br />
SOURCE_GROUP(BarFiles FILES bar.cxx)<br />
ADD_LIBRARY(foo foo.cxx bar.cxx)<br />
<br />
In the event 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).<br />
<br />
As a convenience to developers CMake automatically adds standard header files to a "Header Files" folder and standard source files to a "Source Files" folder for Visual Studio Projects. This can be overridden via the SOURCE_GROUP method documented above.<br />
<br />
=== How to create Visual Studio 6 Projects that contain only a single build type===<br />
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:<br />
<br />
# Create a directory in which you copy the files *.dsptemplate and CMakeVisualStudio6Configurations.cmake from CMake's Templates directory.<br />
# Edit the .cmake file and change the SET(CMAKE_CONFIGURATION_TYPES ...) line to set the build types that you want in your set.<br />
# Edit the *Header.dsptemplate files to contain only the configuration types you want in your set.<br />
# In your CMakeLists.txt file, set the MSPROJECT_TEMPLATE_DIRECTORY to the directory that you created.<br />
<br />
<br />
That's it. Run CMake and your new configuration files will be created.<br />
<br />
Note: Editing the *Header.dsptemplates files should be done very carefully. Here are some guidelines:<br />
<br />
- 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"')<br />
- 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.<br />
- 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.<br />
<br />
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:<br />
# PROP BASE Output_Dir ""<br />
# PROP BASE Intermediate_Dir ""<br />
# PROP Intermediate_Dir ""<br />
# PROP Output_Dir "LIBRARY_OUTPUT_PATH"<br />
or<br />
# PROP Output_Dir "EXECUTABLE_OUTPUT_PATH"<br />
<br />
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).<br />
<br />
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.<br />
<br />
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.)<br />
<br />
=== Can CMake set the Debugging/Working Directory property in Visual Studio projects? ===<br />
<br />
No. The value of this property is not stored in the project files. It is stored in extra files created by the IDE when a solution is loaded (VS .NET 2003 uses a hidden .suo file next to the .sln solution file). The format of these files is not known to CMake and cannot be generated. In some versions of VS the files are binary and not human readable.<br />
<br />
=== Why does CMakeSetup with the message "LINK : fatal error LNK1104: cannot open file 'user32.lib'" while configuring a project? ===<br />
<br />
The path to the SDK libs (user32.lib) must be added by the IDE when the<br />
project generator "Visual Studio 8 2005" is used, because cmake uses<br />
VCExpress.exe and on the fly generated project files to check<br />
for compiling (VCExpress.exe reads some config files for the<br />
compiler/linker options)<br />
<br />
So add the sdk lib path (...\Microsoft Platform SDK\Lib) at Tools->Options->Projects and Solutions->VC++ Directories->Library files<br />
<br />
See also:<br />
*http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/<br />
<br />
=== How can I avoid the error "Arg list too long" when running make? ===<br />
This error is sometimes encountered when building a static library with many object files using Unix make command. It typically looks something like this:<br />
<br />
<pre><br />
gmake[2]: execvp: /bin/sh: Arg list too long<br />
</pre><br />
<br />
When make tries to run the archiver program to build the static library the shell it uses complains that the argument list is too long. In some shells this can be fixed by setting an environment variable such as <tt>ARG_MAX</tt> to extend the length of the command line it will allow.<br />
<br />
=== How can I find out platforms definitions, search paths, etc. from gcc ?===<br />
<br />
The following is really the best if not only way to get information about predefined macros with a GNU compiler:<br />
<pre><br />
$ touch empty.c<br />
$ gcc -v -dD -E empty.c <br />
</pre><br />
This will give you all you might want to know about the preprocessor, the builtin include search dirs and all<br />
predefined definitions, so you can check whether it's __LINUX or _LINUX_ or _APPLE_ or __APPLE etc. <br />
The empty file and all these parameters are really required. You probably want to pipe the output (both stdout and stderr) to a file.<br />
If you want the information for C++, use a C++ file suffix for the empty file.<br />
<br />
This is how you can get the builtin library search paths:<br />
<pre><br />
$ gcc --print-search-dirs<br />
</pre><br />
<br />
=== How can I get a windows registry key ?===<br />
<br />
The only thing to know is that you can't use just the "SET" command in place of "GET" command.<br />
CMake read the value from the registry only when you "get" it from the cache. For instance :<br />
<br />
<pre><br />
GET_FILENAME_COMPONENT(SDK_ROOT_PATH "[HKEY_LOCAL_MACHINE\\SOFTWARE\\PACKAGE;Install_Dir]" ABSOLUTE CACHE)<br />
</pre><br />
<br />
If a key name (ex: Install_Dir in this case) was not specified , the Default key value will be get.<br />
Now you could use the SDK_ROOT_PATH to add include and lib path to your project :<br />
<br />
<pre><br />
INCLUDE_DIRECTORIES(<br />
${SDK_ROOT_PATH}/include<br />
)<br />
<br />
LINK_DIRECTORIES(<br />
${SDK_ROOT_PATH}/lib<br />
)<br />
</pre><br />
<br />
You can also read a registry key in the PATHS section of a FIND_LIBRARY, FIND_PATH, FIND_PROGRAM, or FIND_FILE command<br />
FIND_FILE(BOOT_DOT_INI boot.ini PATHS [HKEY_CURRENT_USER\\Environment;HOMEDRIVE])<br />
<br />
For other examples have a look in the CMake Modules folder :<br />
- FindJava.cmake<br />
- FindPythonLibs.cmake<br />
- ..<br />
<br />
=== How can I build my MSVC application with a static runtime? ===<br />
<br />
Simply change your compilation flags from the default (/MD) to /MT:<br />
<br />
foreach(flag_var<br />
CMAKE_CXX_FLAGS CMAKE_CXX_FLAGS_DEBUG CMAKE_CXX_FLAGS_RELEASE<br />
CMAKE_CXX_FLAGS_MINSIZEREL CMAKE_CXX_FLAGS_RELWITHDEBINFO)<br />
if(${flag_var} MATCHES "/MD")<br />
string(REGEX REPLACE "/MD" "/MT" ${flag_var} "${${flag_var}}")<br />
endif(${flag_var} MATCHES "/MD")<br />
endforeach(flag_var)<br />
<br />
<br />
{{CMake/Template/Footer}}</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake:Module_Maintainers&diff=16276CMake:Module Maintainers2009-08-17T03:09:16Z<p>Plowman: Add bullet physics engine</p>
<hr />
<div>If you want to add a new module to CMake, then you must volunteer to maintain it, or find someone that will. This page contains a list of Module maintainer volunteers, and instructions on how to become a maintainer. <br />
<br />
* This mail describes the procedure how to become maintainer, and how to modify or add modules: [http://www.cmake.org/pipermail/cmake/2007-July/015258.html Call for maintainers] <br />
<br />
* Please '''DO NOT ADD a Bug Tracker''' entry for new Module request [http://www.cmake.org/pipermail/cmake/2008-November/025196.html Do not add bug report for New Module] <br />
<br />
* Maintainers should follow the guide lines for module files documented here: [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/readme.txt?root=CMake&view=markup readme]<br />
<br />
In addition backwards compatibility for all existing variables in the current set<br />
of modules must be maintained strictly. <br />
<br />
If you want to become a module maintainer, please send an email with your module to the cmake mailing list.<br />
<br />
* Here is a list of "repositories" of 3rd party CMake modules, so maintainers can check for already existing modules etc.<br />
** KDE4: http://websvn.kde.org/trunk/KDE/kdelibs/cmake/modules/<br />
** PlPlot: http://plplot.svn.sourceforge.net/viewvc/plplot/trunk/cmake/modules/<br />
** http://cmake-modules.googlecode.com/svn/trunk/Modules/<br />
** OpenSceneGraph http://www.openscenegraph.org/svn/osg/OpenSceneGraph/trunk/CMakeModules/<br />
** OpenSync http://svn.opensync.org/branches/3rd-party-cmake-modules/modules/<br />
** http://github.com/jedbrown/cmake-modules<br />
<br />
----<br />
<br />
* Andreas Schneider, mail at cynapses dot org<br />
** FindBoost.cmake<br />
<br />
* Miguel A. Figueroa Villanueva, miguelf at ieee dot org<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindwxWidgets.cmake?root=CMake&view=markup FindwxWidgets.cmake]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindLATEX.cmake?root=CMake&view=markup FindLATEX]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindImageMagick.cmake?root=CMake&view=markup FindImageMagick]<br />
<br />
* Alan W. Irwin, irwin at beluga dot phys dot uvic dot ca<br />
** Ada<br />
<br />
* Tristan Carel, tristan dot carel at gmail dot com<br />
** FindSWIG<br />
** UseSWIG<br />
** FindSubversion<br />
<br />
* Alin M Elena, alinm dot elena at gmail dot com (http://titus.phy.qub.ac.uk/group/Alin/)<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindBLAS.cmake?root=CMake&view=markup FindBLAS]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindLAPACK.cmake?root=CMake&view=markup FindLAPACK] - <br />
<br />
* Tim Burrell (tim dot burrell at gmail dot com) (http://www.dsource.org/projects/cmaked)<br />
** D support<br />
<br />
* Philip Lowman, philip at yhbt dot com<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindGTK2.cmake?root=CMake&view=markup FindGTK2]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindOpenSceneGraph.cmake?root=CMake&view=markup FindOpenSceneGraph]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindCxxTest.cmake?root=CMake&view=markup FindCxxTest]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindDoxygen.cmake?root=CMake&view=markup FindDoxygen]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/CMakeDetermineVSServicePack.cmake?root=CMake&view=markup CMakeDetermineVSServicePack]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindGnuTLS.cmake?root=CMake&view=markup FindGnuTLS]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindFLEX.cmake?root=CMake&view=markup FindFLEX]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindBISON.cmake?root=CMake&view=markup FindBISON]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindGTest.cmake?root=CMake&view=markup FindGTest (Google C++ Testing Framework)]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindBullet.cmake?root=CMake&view=markup FindBullet]<br />
<br />
<br />
* Eric Wing ; in the commercial domain at gmail, ewing . public<br />
** FindFreeType.cmake<br />
** FindGDAL.cmake<br />
** FindGIFLIB.cmake<br />
** FindLua50.cmake, FindLua51.cmake<br />
** FindOpenAL.cmake<br />
** FindOpenThreads.cmake<br />
** FindPhysFS.cmake<br />
** FindProducer.cmake<br />
** FindQuickTime.cmake<br />
** FindSDL.cmake, FindSDL_image.cmake, FindSDL_mixer.cmake. FindSDL_net.cmake, FindSDL_sound.cmake, FindSDL_ttf.cmake<br />
** Findosg.cmake, FindosgDB.cmake, FindosgFX.cmake, FindosgGA.cmake, FindosgIntrospection.cmake, FindosgManipulator.cmake, FindosgParticle.cmake, FindosgProducer.cmake, FindosgShadow.cmake, FindosgSim.cmake, FindosgTerrain.cmake, FindosgText.cmake, FindosgUtil.cmake, FindosgViewer.cmake <br />
<br />
* Douglas Gregor (doug.gregor at gmail dot com)<br />
** FindMPI<br />
<br />
* Matt Leotta, matt.leotta at gmail dot com<br />
** FindCoin3D<br />
<br />
* Clinton Stimpson clinton at elemtech dot com<br />
** FindQt4<br />
<br />
* Petr Gotthard, petr dot gotthard at honeywell dot com<br />
** FindRTI</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake:Module_Maintainers&diff=16275CMake:Module Maintainers2009-08-17T02:14:48Z<p>Plowman: add GTest</p>
<hr />
<div>If you want to add a new module to CMake, then you must volunteer to maintain it, or find someone that will. This page contains a list of Module maintainer volunteers, and instructions on how to become a maintainer. <br />
<br />
* This mail describes the procedure how to become maintainer, and how to modify or add modules: [http://www.cmake.org/pipermail/cmake/2007-July/015258.html Call for maintainers] <br />
<br />
* Please '''DO NOT ADD a Bug Tracker''' entry for new Module request [http://www.cmake.org/pipermail/cmake/2008-November/025196.html Do not add bug report for New Module] <br />
<br />
* Maintainers should follow the guide lines for module files documented here: [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/readme.txt?root=CMake&view=markup readme]<br />
<br />
In addition backwards compatibility for all existing variables in the current set<br />
of modules must be maintained strictly. <br />
<br />
If you want to become a module maintainer, please send an email with your module to the cmake mailing list.<br />
<br />
* Here is a list of "repositories" of 3rd party CMake modules, so maintainers can check for already existing modules etc.<br />
** KDE4: http://websvn.kde.org/trunk/KDE/kdelibs/cmake/modules/<br />
** PlPlot: http://plplot.svn.sourceforge.net/viewvc/plplot/trunk/cmake/modules/<br />
** http://cmake-modules.googlecode.com/svn/trunk/Modules/<br />
** OpenSceneGraph http://www.openscenegraph.org/svn/osg/OpenSceneGraph/trunk/CMakeModules/<br />
** OpenSync http://svn.opensync.org/branches/3rd-party-cmake-modules/modules/<br />
** http://github.com/jedbrown/cmake-modules<br />
<br />
----<br />
<br />
* Andreas Schneider, mail at cynapses dot org<br />
** FindBoost.cmake<br />
<br />
* Miguel A. Figueroa Villanueva, miguelf at ieee dot org<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindwxWidgets.cmake?root=CMake&view=markup FindwxWidgets.cmake]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindLATEX.cmake?root=CMake&view=markup FindLATEX]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindImageMagick.cmake?root=CMake&view=markup FindImageMagick]<br />
<br />
* Alan W. Irwin, irwin at beluga dot phys dot uvic dot ca<br />
** Ada<br />
<br />
* Tristan Carel, tristan dot carel at gmail dot com<br />
** FindSWIG<br />
** UseSWIG<br />
** FindSubversion<br />
<br />
* Alin M Elena, alinm dot elena at gmail dot com (http://titus.phy.qub.ac.uk/group/Alin/)<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindBLAS.cmake?root=CMake&view=markup FindBLAS]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindLAPACK.cmake?root=CMake&view=markup FindLAPACK] - <br />
<br />
* Tim Burrell (tim dot burrell at gmail dot com) (http://www.dsource.org/projects/cmaked)<br />
** D support<br />
<br />
* Philip Lowman, philip at yhbt dot com<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindGTK2.cmake?root=CMake&view=markup FindGTK2]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindOpenSceneGraph.cmake?root=CMake&view=markup FindOpenSceneGraph]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindCxxTest.cmake?root=CMake&view=markup FindCxxTest]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindDoxygen.cmake?root=CMake&view=markup FindDoxygen]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/CMakeDetermineVSServicePack.cmake?root=CMake&view=markup CMakeDetermineVSServicePack]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindGnuTLS.cmake?root=CMake&view=markup FindGnuTLS]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindFLEX.cmake?root=CMake&view=markup FindFLEX]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindBISON.cmake?root=CMake&view=markup FindBISON]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindGTest.cmake?root=CMake&view=markup FindGTest (Google C++ Testing Framework)]<br />
<br />
<br />
* Eric Wing ; in the commercial domain at gmail, ewing . public<br />
** FindFreeType.cmake<br />
** FindGDAL.cmake<br />
** FindGIFLIB.cmake<br />
** FindLua50.cmake, FindLua51.cmake<br />
** FindOpenAL.cmake<br />
** FindOpenThreads.cmake<br />
** FindPhysFS.cmake<br />
** FindProducer.cmake<br />
** FindQuickTime.cmake<br />
** FindSDL.cmake, FindSDL_image.cmake, FindSDL_mixer.cmake. FindSDL_net.cmake, FindSDL_sound.cmake, FindSDL_ttf.cmake<br />
** Findosg.cmake, FindosgDB.cmake, FindosgFX.cmake, FindosgGA.cmake, FindosgIntrospection.cmake, FindosgManipulator.cmake, FindosgParticle.cmake, FindosgProducer.cmake, FindosgShadow.cmake, FindosgSim.cmake, FindosgTerrain.cmake, FindosgText.cmake, FindosgUtil.cmake, FindosgViewer.cmake <br />
<br />
* Douglas Gregor (doug.gregor at gmail dot com)<br />
** FindMPI<br />
<br />
* Matt Leotta, matt.leotta at gmail dot com<br />
** FindCoin3D<br />
<br />
* Clinton Stimpson clinton at elemtech dot com<br />
** FindQt4<br />
<br />
* Petr Gotthard, petr dot gotthard at honeywell dot com<br />
** FindRTI</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake:Module_Maintainers&diff=16245CMake:Module Maintainers2009-08-13T04:14:10Z<p>Plowman: adding FindFLEX / FindBISON</p>
<hr />
<div>If you want to add a new module to CMake, then you must volunteer to maintain it, or find someone that will. This page contains a list of Module maintainer volunteers, and instructions on how to become a maintainer. <br />
<br />
* This mail describes the procedure how to become maintainer, and how to modify or add modules: [http://www.cmake.org/pipermail/cmake/2007-July/015258.html Call for maintainers] <br />
<br />
* Please '''DO NOT ADD a Bug Tracker''' entry for new Module request [http://www.cmake.org/pipermail/cmake/2008-November/025196.html Do not add bug report for New Module] <br />
<br />
* Maintainers should follow the guide lines for module files documented here: [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/readme.txt?root=CMake&view=markup readme]<br />
<br />
In addition backwards compatibility for all existing variables in the current set<br />
of modules must be maintained strictly. <br />
<br />
If you want to become a module maintainer, please send an email with your module to the cmake mailing list.<br />
<br />
* Here is a list of "repositories" of 3rd party CMake modules, so maintainers can check for already existing modules etc.<br />
** KDE4: http://websvn.kde.org/trunk/KDE/kdelibs/cmake/modules/<br />
** PlPlot: http://plplot.svn.sourceforge.net/viewvc/plplot/trunk/cmake/modules/<br />
** http://cmake-modules.googlecode.com/svn/trunk/Modules/<br />
** OpenSceneGraph http://www.openscenegraph.org/svn/osg/OpenSceneGraph/trunk/CMakeModules/<br />
** OpenSync http://svn.opensync.org/branches/3rd-party-cmake-modules/modules/<br />
** http://github.com/jedbrown/cmake-modules<br />
<br />
----<br />
<br />
* Andreas Schneider, mail at cynapses dot org<br />
** FindBoost.cmake<br />
<br />
* Miguel A. Figueroa Villanueva, miguelf at ieee dot org<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindwxWidgets.cmake?root=CMake&view=markup FindwxWidgets.cmake]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindLATEX.cmake?root=CMake&view=markup FindLATEX]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindImageMagick.cmake?root=CMake&view=markup FindImageMagick]<br />
<br />
* Alan W. Irwin, irwin at beluga dot phys dot uvic dot ca<br />
** Ada<br />
<br />
* Tristan Carel, tristan dot carel at gmail dot com<br />
** FindSWIG<br />
** UseSWIG<br />
** FindSubversion<br />
<br />
* Alin M Elena, alinm dot elena at gmail dot com (http://titus.phy.qub.ac.uk/group/Alin/)<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindBLAS.cmake?root=CMake&view=markup FindBLAS]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindLAPACK.cmake?root=CMake&view=markup FindLAPACK] - <br />
<br />
* Tim Burrell (tim dot burrell at gmail dot com) (http://www.dsource.org/projects/cmaked)<br />
** D support<br />
<br />
* Philip Lowman, philip at yhbt dot com<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindGTK2.cmake?root=CMake&view=markup FindGTK2]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindOpenSceneGraph.cmake?root=CMake&view=markup FindOpenSceneGraph]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindCxxTest.cmake?root=CMake&view=markup FindCxxTest]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindDoxygen.cmake?root=CMake&view=markup FindDoxygen]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/CMakeDetermineVSServicePack.cmake?root=CMake&view=markup CMakeDetermineVSServicePack]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindGnuTLS.cmake?root=CMake&view=markup FindGnuTLS]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindFLEX.cmake?root=CMake&view=markup FindFLEX]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindBISON.cmake?root=CMake&view=markup FindBISON]<br />
<br />
<br />
* Eric Wing ; in the commercial domain at gmail, ewing . public<br />
** FindFreeType.cmake<br />
** FindGDAL.cmake<br />
** FindGIFLIB.cmake<br />
** FindLua50.cmake, FindLua51.cmake<br />
** FindOpenAL.cmake<br />
** FindOpenThreads.cmake<br />
** FindPhysFS.cmake<br />
** FindProducer.cmake<br />
** FindQuickTime.cmake<br />
** FindSDL.cmake, FindSDL_image.cmake, FindSDL_mixer.cmake. FindSDL_net.cmake, FindSDL_sound.cmake, FindSDL_ttf.cmake<br />
** Findosg.cmake, FindosgDB.cmake, FindosgFX.cmake, FindosgGA.cmake, FindosgIntrospection.cmake, FindosgManipulator.cmake, FindosgParticle.cmake, FindosgProducer.cmake, FindosgShadow.cmake, FindosgSim.cmake, FindosgTerrain.cmake, FindosgText.cmake, FindosgUtil.cmake, FindosgViewer.cmake <br />
<br />
* Douglas Gregor (doug.gregor at gmail dot com)<br />
** FindMPI<br />
<br />
* Matt Leotta, matt.leotta at gmail dot com<br />
** FindCoin3D<br />
<br />
* Clinton Stimpson clinton at elemtech dot com<br />
** FindQt4<br />
<br />
* Petr Gotthard, petr dot gotthard at honeywell dot com<br />
** FindRTI</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake:Module_Maintainers&diff=16244CMake:Module Maintainers2009-08-13T02:48:34Z<p>Plowman: add FindGnuTLS module</p>
<hr />
<div>If you want to add a new module to CMake, then you must volunteer to maintain it, or find someone that will. This page contains a list of Module maintainer volunteers, and instructions on how to become a maintainer. <br />
<br />
* This mail describes the procedure how to become maintainer, and how to modify or add modules: [http://www.cmake.org/pipermail/cmake/2007-July/015258.html Call for maintainers] <br />
<br />
* Please '''DO NOT ADD a Bug Tracker''' entry for new Module request [http://www.cmake.org/pipermail/cmake/2008-November/025196.html Do not add bug report for New Module] <br />
<br />
* Maintainers should follow the guide lines for module files documented here: [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/readme.txt?root=CMake&view=markup readme]<br />
<br />
In addition backwards compatibility for all existing variables in the current set<br />
of modules must be maintained strictly. <br />
<br />
If you want to become a module maintainer, please send an email with your module to the cmake mailing list.<br />
<br />
* Here is a list of "repositories" of 3rd party CMake modules, so maintainers can check for already existing modules etc.<br />
** KDE4: http://websvn.kde.org/trunk/KDE/kdelibs/cmake/modules/<br />
** PlPlot: http://plplot.svn.sourceforge.net/viewvc/plplot/trunk/cmake/modules/<br />
** http://cmake-modules.googlecode.com/svn/trunk/Modules/<br />
** OpenSceneGraph http://www.openscenegraph.org/svn/osg/OpenSceneGraph/trunk/CMakeModules/<br />
** OpenSync http://svn.opensync.org/branches/3rd-party-cmake-modules/modules/<br />
** http://github.com/jedbrown/cmake-modules<br />
<br />
----<br />
<br />
* Andreas Schneider, mail at cynapses dot org<br />
** FindBoost.cmake<br />
<br />
* Miguel A. Figueroa Villanueva, miguelf at ieee dot org<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindwxWidgets.cmake?root=CMake&view=markup FindwxWidgets.cmake]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindLATEX.cmake?root=CMake&view=markup FindLATEX]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindImageMagick.cmake?root=CMake&view=markup FindImageMagick]<br />
<br />
* Alan W. Irwin, irwin at beluga dot phys dot uvic dot ca<br />
** Ada<br />
<br />
* Tristan Carel, tristan dot carel at gmail dot com<br />
** FindSWIG<br />
** UseSWIG<br />
** FindSubversion<br />
<br />
* Alin M Elena, alinm dot elena at gmail dot com (http://titus.phy.qub.ac.uk/group/Alin/)<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindBLAS.cmake?root=CMake&view=markup FindBLAS]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindLAPACK.cmake?root=CMake&view=markup FindLAPACK] - <br />
<br />
* Tim Burrell (tim dot burrell at gmail dot com) (http://www.dsource.org/projects/cmaked)<br />
** D support<br />
<br />
* Philip Lowman, philip at yhbt dot com<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindGTK2.cmake?root=CMake&view=markup FindGTK2]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindOpenSceneGraph.cmake?root=CMake&view=markup FindOpenSceneGraph]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindCxxTest.cmake?root=CMake&view=markup FindCxxTest]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindDoxygen.cmake?root=CMake&view=markup FindDoxygen]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/CMakeDetermineVSServicePack.cmake?root=CMake&view=markup CMakeDetermineVSServicePack]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindGnuTLS.cmake?root=CMake&view=markup FindGnuTLS]<br />
<br />
* Eric Wing ; in the commercial domain at gmail, ewing . public<br />
** FindFreeType.cmake<br />
** FindGDAL.cmake<br />
** FindGIFLIB.cmake<br />
** FindLua50.cmake, FindLua51.cmake<br />
** FindOpenAL.cmake<br />
** FindOpenThreads.cmake<br />
** FindPhysFS.cmake<br />
** FindProducer.cmake<br />
** FindQuickTime.cmake<br />
** FindSDL.cmake, FindSDL_image.cmake, FindSDL_mixer.cmake. FindSDL_net.cmake, FindSDL_sound.cmake, FindSDL_ttf.cmake<br />
** Findosg.cmake, FindosgDB.cmake, FindosgFX.cmake, FindosgGA.cmake, FindosgIntrospection.cmake, FindosgManipulator.cmake, FindosgParticle.cmake, FindosgProducer.cmake, FindosgShadow.cmake, FindosgSim.cmake, FindosgTerrain.cmake, FindosgText.cmake, FindosgUtil.cmake, FindosgViewer.cmake <br />
<br />
* Douglas Gregor (doug.gregor at gmail dot com)<br />
** FindMPI<br />
<br />
* Matt Leotta, matt.leotta at gmail dot com<br />
** FindCoin3D<br />
<br />
* Clinton Stimpson clinton at elemtech dot com<br />
** FindQt4<br />
<br />
* Petr Gotthard, petr dot gotthard at honeywell dot com<br />
** FindRTI</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake:Module_Maintainers&diff=15019CMake:Module Maintainers2009-04-14T04:52:30Z<p>Plowman: </p>
<hr />
<div>If you want to add a new module to CMake, then you must volunteer to maintain it, or find someone that will. This page contains a list of Module maintainer volunteers, and instructions on how to become a maintainer. <br />
<br />
* This mail describes the procedure how to become maintainer, and how to modify or add modules: [http://www.cmake.org/pipermail/cmake/2007-July/015258.html Call for maintainers] <br />
<br />
* Please '''DO NOT ADD a Bug Tracker''' entry for new Module request [http://www.cmake.org/pipermail/cmake/2008-November/025196.html Do not add bug report for New Module] <br />
<br />
* Maintainers should follow the guide lines for module files documented here: [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/readme.txt?root=CMake&view=markup readme]<br />
<br />
In addition backwards compatibility for all existing variables in the current set<br />
of modules must be maintained strictly. <br />
<br />
If you want to become a module maintainer, please send an email with your module to the cmake mailing list.<br />
<br />
* Here is a list of "repositories" of 3rd party CMake modules, so maintainers can check for already existing modules etc.<br />
** KDE4: http://websvn.kde.org/trunk/KDE/kdelibs/cmake/modules/<br />
** PlPlot: http://plplot.svn.sourceforge.net/viewvc/plplot/trunk/cmake/modules/<br />
** http://cmake-modules.googlecode.com/svn/trunk/Modules/<br />
** OpenSceneGraph http://www.openscenegraph.org/svn/osg/OpenSceneGraph/trunk/CMakeModules/<br />
** OpenSync http://svn.opensync.org/branches/3rd-party-cmake-modules/modules/<br />
** http://github.com/jedbrown/cmake-modules<br />
<br />
----<br />
<br />
* Andreas Schneider, mail at cynapses dot org<br />
** FindBoost.cmake<br />
<br />
* Miguel A. Figueroa Villanueva, miguelf at ieee dot org<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindwxWidgets.cmake?root=CMake&view=markup FindwxWidgets.cmake]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindLATEX.cmake?root=CMake&view=markup FindLATEX]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindImageMagick.cmake?root=CMake&view=markup FindImageMagick]<br />
<br />
* Alan W. Irwin, irwin at beluga dot phys dot uvic dot ca<br />
** Ada<br />
<br />
* Tristan Carel, tristan dot carel at gmail dot com<br />
** FindSWIG<br />
** UseSWIG<br />
** FindSubversion<br />
<br />
* Alin M Elena, alinm dot elena at gmail dot com (http://titus.phy.qub.ac.uk/group/Alin/)<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindBLAS.cmake?root=CMake&view=markup FindBLAS]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindLAPACK.cmake?root=CMake&view=markup FindLAPACK] - <br />
<br />
* Tim Burrell (tim dot burrell at gmail dot com) (http://www.dsource.org/projects/cmaked)<br />
** D support<br />
<br />
* Philip Lowman, philip at yhbt dot com<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindGTK2.cmake?root=CMake&view=markup FindGTK2]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindOpenSceneGraph.cmake?root=CMake&view=markup FindOpenSceneGraph]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindCxxTest.cmake?root=CMake&view=markup FindCxxTest]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindDoxygen.cmake?root=CMake&view=markup FindDoxygen]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/CMakeDetermineVSServicePack.cmake?root=CMake&view=markup CMakeDetermineVSServicePack]<br />
<br />
* Eric Wing ; in the commercial domain at gmail, ewing . public<br />
** FindFreeType.cmake<br />
** FindGDAL.cmake<br />
** FindGIFLIB.cmake<br />
** FindLua50.cmake, FindLua51.cmake<br />
** FindOpenAL.cmake<br />
** FindOpenThreads.cmake<br />
** FindPhysFS.cmake<br />
** FindProducer.cmake<br />
** FindQuickTime.cmake<br />
** FindSDL.cmake, FindSDL_image.cmake, FindSDL_mixer.cmake. FindSDL_net.cmake, FindSDL_sound.cmake, FindSDL_ttf.cmake<br />
** Findosg.cmake, FindosgDB.cmake, FindosgFX.cmake, FindosgGA.cmake, FindosgIntrospection.cmake, FindosgManipulator.cmake, FindosgParticle.cmake, FindosgProducer.cmake, FindosgShadow.cmake, FindosgSim.cmake, FindosgTerrain.cmake, FindosgText.cmake, FindosgUtil.cmake, FindosgViewer.cmake <br />
<br />
* Douglas Gregor (doug.gregor at gmail dot com)<br />
** FindMPI<br />
<br />
* Matt Leotta, matt.leotta at gmail dot com<br />
** FindCoin3D<br />
<br />
* Clinton Stimpson clinton at elemtech dot com<br />
** FindQt4<br />
<br />
* Petr Gotthard, petr dot gotthard at honeywell dot com<br />
** FindRTI</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CTest:Nightly,_Experimental,_Continuous&diff=14928CTest:Nightly, Experimental, Continuous2009-04-04T04:29:37Z<p>Plowman: /* Continuous */</p>
<hr />
<div>CTest currently supports three different running submission modes: Experimental, Nightly, and Continuous.<br />
<br />
=Experimental=<br />
<br />
* By default no update happens. If update is explicitly issued using ''-D ExperimentalUpdate'' then it updates to the latest version in the repository<br />
* Experimental is typically used for:<br />
** Testing if the changes were succesfull<br />
** New dashboards that are not yet tested if everything works fine<br />
** Trying new features without poluting the Nightly section<br />
<br />
=Nightly=<br />
<br />
* CTest will update to the latest nightly start time specified in DartConfiguration.tcl as NightlyStartTime. Assuming the nightly start time is 9pm EST and currently it is before 9pm EST, anything between 9pm EST yesterday and 9pm EST today will be updated to 9pm yesterday. This way all nightly submissions are updated to the same version of repository.<br />
<br />
=Continuous=<br />
<br />
* Repository is updated to the latest version and if there are no updates, the processing will stop. If there are any changes, that the processing is similar to Nightly or Experimental.<br />
<br />
Here are some variables you may find useful:<br />
<br />
# should ctest wipe the binary tree before running<br />
SET (CTEST_START_WITH_EMPTY_BINARY_DIRECTORY_ONCE TRUE)<br />
<br />
# specify how long to run the continuous in minutes<br />
SET (CTEST_CONTINUOUS_DURATION 650)<br />
SET (CTEST_CONTINUOUS_MINIMUM_INTERVAL 15)<br />
<br />
{{CMake/Template/Footer}}</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CTest:Nightly,_Experimental,_Continuous&diff=14927CTest:Nightly, Experimental, Continuous2009-04-04T04:29:26Z<p>Plowman: </p>
<hr />
<div>CTest currently supports three different running submission modes: Experimental, Nightly, and Continuous.<br />
<br />
=Experimental=<br />
<br />
* By default no update happens. If update is explicitly issued using ''-D ExperimentalUpdate'' then it updates to the latest version in the repository<br />
* Experimental is typically used for:<br />
** Testing if the changes were succesfull<br />
** New dashboards that are not yet tested if everything works fine<br />
** Trying new features without poluting the Nightly section<br />
<br />
=Nightly=<br />
<br />
* CTest will update to the latest nightly start time specified in DartConfiguration.tcl as NightlyStartTime. Assuming the nightly start time is 9pm EST and currently it is before 9pm EST, anything between 9pm EST yesterday and 9pm EST today will be updated to 9pm yesterday. This way all nightly submissions are updated to the same version of repository.<br />
<br />
=Continuous=<br />
<br />
* Repository is updated to the latest version and if there are no updates, the processing will stop. If there are any changes, that the processing is similar to Nightly or Experimental.<br />
<br />
Here are some variables you may find useful:<br />
# should ctest wipe the binary tree before running<br />
SET (CTEST_START_WITH_EMPTY_BINARY_DIRECTORY_ONCE TRUE)<br />
<br />
# specify how long to run the continuous in minutes<br />
SET (CTEST_CONTINUOUS_DURATION 650)<br />
SET (CTEST_CONTINUOUS_MINIMUM_INTERVAL 15)<br />
<br />
{{CMake/Template/Footer}}</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake:Module_Maintainers&diff=14858CMake:Module Maintainers2009-03-22T20:53:31Z<p>Plowman: Added FindOpenSceneGraph, FindGTK2</p>
<hr />
<div>If you want to add a new module to CMake, then you must volunteer to maintain it, or find someone that will. This page contains a list of Module maintainer volunteers, and instructions on how to become a maintainer. <br />
<br />
* This mail describes the procedure how to become maintainer, and how to modify or add modules: [http://www.cmake.org/pipermail/cmake/2007-July/015258.html Call for maintainers] <br />
<br />
* Please '''DO NOT ADD a Bug Tracker''' entry for new Module request [http://www.cmake.org/pipermail/cmake/2008-November/025196.html Do not add bug report for New Module] <br />
<br />
* Maintainers should follow the guide lines for module files documented here: [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/readme.txt?root=CMake&view=markup readme]<br />
<br />
In addition backwards compatibility for all existing variables in the current set<br />
of modules must be maintained strictly. <br />
<br />
If you want to become a module maintainer, please send an email with your module to the cmake mailing list.<br />
<br />
* Here is a list of "repositories" of 3rd party CMake modules, so maintainers can check for already existing modules etc.<br />
** KDE4: http://websvn.kde.org/trunk/KDE/kdelibs/cmake/modules/<br />
** PlPlot: http://plplot.svn.sourceforge.net/viewvc/plplot/trunk/cmake/modules/<br />
** http://cmake-modules.googlecode.com/svn/trunk/Modules/<br />
** OpenSceneGraph http://www.openscenegraph.org/svn/osg/OpenSceneGraph/trunk/CMakeModules/<br />
** OpenSync http://svn.opensync.org/branches/3rd-party-cmake-modules/modules/<br />
** http://github.com/jedbrown/cmake-modules<br />
<br />
----<br />
<br />
* Andreas Schneider, mail at cynapses dot org<br />
** FindBoost.cmake<br />
<br />
* Miguel A. Figueroa Villanueva, miguelf at ieee dot org<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindwxWidgets.cmake?root=CMake&view=markup FindwxWidgets.cmake]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindLATEX.cmake?root=CMake&view=markup FindLATEX]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindImageMagick.cmake?root=CMake&view=markup FindImageMagick]<br />
<br />
* Alan W. Irwin, irwin at beluga dot phys dot uvic dot ca<br />
** Ada<br />
<br />
* Tristan Carel, tristan dot carel at gmail dot com<br />
** FindSWIG<br />
** UseSWIG<br />
** FindSubversion<br />
<br />
* Alin M Elena, alinm dot elena at gmail dot com (http://titus.phy.qub.ac.uk/group/Alin/)<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindBLAS.cmake?root=CMake&view=markup FindBLAS]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindLAPACK.cmake?root=CMake&view=markup FindLAPACK] - <br />
<br />
* Tim Burrell (tim dot burrell at gmail dot com) (http://www.dsource.org/projects/cmaked)<br />
** D support<br />
<br />
* Philip Lowman, philip at yhbt dot com<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindGTK2.cmake?root=CMake&view=markup FindGTK2]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindOpenSceneGraph.cmake?root=CMake&view=markup FindOpenSceneGraph]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindCxxTest.cmake?root=CMake&view=markup FindCxxTest]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindDoxygen.cmake?root=CMake&view=markup FindDoxygen]<br />
<br />
* Eric Wing ; in the commercial domain at gmail, ewing . public<br />
** FindFreeType.cmake<br />
** FindGDAL.cmake<br />
** FindGIFLIB.cmake<br />
** FindLua50.cmake, FindLua51.cmake<br />
** FindOpenAL.cmake<br />
** FindOpenThreads.cmake<br />
** FindPhysFS.cmake<br />
** FindProducer.cmake<br />
** FindQuickTime.cmake<br />
** FindSDL.cmake, FindSDL_image.cmake, FindSDL_mixer.cmake. FindSDL_net.cmake, FindSDL_sound.cmake, FindSDL_ttf.cmake<br />
** Findosg.cmake, FindosgDB.cmake, FindosgFX.cmake, FindosgGA.cmake, FindosgIntrospection.cmake, FindosgManipulator.cmake, FindosgParticle.cmake, FindosgProducer.cmake, FindosgShadow.cmake, FindosgSim.cmake, FindosgTerrain.cmake, FindosgText.cmake, FindosgUtil.cmake, FindosgViewer.cmake <br />
<br />
* Douglas Gregor (doug.gregor at gmail dot com)<br />
** FindMPI<br />
<br />
* Matt Leotta, matt.leotta at gmail dot com<br />
** FindCoin3D<br />
<br />
* Clinton Stimpson clinton at elemtech dot com<br />
** FindQt4<br />
<br />
* Petr Gotthard, petr dot gotthard at honeywell dot com<br />
** FindRTI</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake_FAQ&diff=14575CMake FAQ2009-02-09T12:42:11Z<p>Plowman: /* Isn't the "Expression" in the "ELSE (Expression)" confusing? */ continue code block</p>
<hr />
<div>== General information and availability ==<br />
=== What is CMake? ===<br />
CMake is a cross-platform, open-source make system. CMake is used to control the software compilation process using simple platform-independent 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 http://www.cmake.org/HTML/About.html to learn more about CMake.<br />
<br />
=== What is the current release? ===<br />
The latest release of CMake is always available at: http://www.cmake.org/HTML/Download.html<br />
<br />
From there, you can fetch CMake binaries for Windows or several Unix variants, or you can download the source code of CMake.<br />
<br />
You can also access nightly development through CVS; see http://www.cmake.org/HTML/Download.html for more information. You may also browse the [http://www.cmake.org/cgi-bin/viewcvs.cgi/?root=CMake cvs repository online].<br />
<br />
=== I found a Bug! What should I do? ===<br />
Please report the bug in our bug tracker: http://www.cmake.org/Bug<br />
<br />
Please make sure to look at the old bugs not to include duplicates, include detailed instructions of the bug and how to reproduce it.<br />
<br />
=== I want a new feature in CMake. What should I do? ===<br />
Report a feature request in our Bug tracker http://www.cmake.org/Bug<br />
<br />
Please make sure to look at the old feature requests not to include duplicates, include detailed instructions of the feature and proposed implementation.<br />
<br />
=== What is the most recent version covered by the Mastering CMake book? ===<br />
A new edition of the [http://www.kitware.com/products/cmakebook.html Mastering CMake] book has been released which documents CMake 2.6.<br />
<br />
The following features have been added since printing the book:<br />
<br />
* New INSTALL command (cmake --help-command INSTALL)<br />
* New LIST command (cmake --help-command LIST)<br />
* Updated FIND_PATH, FIND_PROGRAM, and FIND_FILE commands to be more powerful (cmake --help-command FIND_PATH)<br />
* RPATH and Mac OS X install_name support (cmake --help-command SET_TARGET_PROPERTIES)<br />
* CPack Beta (not finished or documented)<br />
* EXECUTE_PROCESS was added and replaces EXEC_PROGRAM<br />
* Other changes have been bug fixes and internal CMake restructuring<br />
<br />
== Running CMake ==<br />
<br />
=== Is there an option to produce more 'verbose' compiling? ===<br />
Set CMAKE_VERBOSE_MAKEFILE to ON. This will make generator to produce all outputs, including compiler lines.<br />
<br />
If you are on Windows using Borland or NMake Makefiles, then you will see lines like:<br />
<br />
cl @c:\DOCUME~1\ANDY~1.KIT\LOCALS~1\Temp\nma03504<br />
<br />
The reason for this is that Borland and Microsoft Visual Studio make programs have limitation on the length of command strings. They overcome this limitation by writing arguments to the file and then pass file to the program.<br />
<br />
If you actually want to see what the command looks like, set CMAKE_START_TEMP_FILE and CMAKE_END_TEMP_FILE to "".<br />
<br />
On Makefile generators, there is a shortcut by setting Makefile variable VERBOSE to 1. For example on UNIX:<br />
<br />
make VERBOSE=1<br />
<br />
and Windows:<br />
nmake /S force silent mode, overrides (CMAKE_VERBOSE_MAKFILE)<br />
<br />
=== Is there a way to skip checking of dependent libraries when compiling? ===<br />
<br />
'''Using the Makefile Generator'''<br />
<br />
When using the Makefile generator under *nix you can append "/fast" to your target name. For example:<br />
<br />
make target_name/fast<br />
<br />
Under Windows use a backslash instead:<br />
<br />
make target_name\fast<br />
<br />
'''Using Visual Studio >= 7.1'''<br />
<br />
If you have Visual Studio .NET 7.1 or greater you can use the native option to right click on a project and choose to build just that project.<br />
<br />
'''Using Visual Studio <= 7.0'''<br />
<br />
CMake doesn't try to compile all dependent libraries when you compile a library but it will do so for binary targets. You can't avoid this however you can take advantage of CTRL+F7 to manually compile a source file for the affected target and then relink the target by right clicking on it and choosing Link. You'll have to ensure that all dependent libraries are made up-to-date however or suffer through Visual's slow check.<br />
<br />
=== I set a cmake variable in my environment, but it didn't change anything. Why? ===<br />
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.<br />
<br />
=== I change CMAKE_C_COMPILER in the GUI but it changes back on the next configure step. Why? ===<br />
Once a build tree is created with a given compiler it cannot be changed. There are a variety of implementation reasons for this policy. In order to choose a different compiler create a new build tree and set the CC and CXX environment variables to the compiler you want before running CMake.<br />
<br />
NOTE: While I don't know what the preferred method of doing it is, I do know that the advice above (to set CC and CXX env vars) is in direct conflict with advice somewhere else that says not to use env vars to control CMAKE... Hopefully someone that knows a little more than I will fix this discrepancy.<br />
<br />
NOTE2: You could pass in e.g. <tt>-D CMAKE_C_COMPILER_INIT:STRING=mycc</tt> on the command line, or set the same variable inside a listfile (before any PROJECT() or ENABLE_LANGUAGE() command). Might that be what you're getting at?<br />
<br />
=== In CCMake, typing full paths is tedious. Is there a better way? ===<br />
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.<br />
<br />
For example:<br />
<br />
/usr/loc<TAB><br />
<br />
will expand to<br />
<br />
/usr/local/<br />
<br />
<br />
<br />
== Out-of-source build trees ==<br />
<br />
=== What is an "out-of-source" build? ===<br />
When your build generates files, they have to go somewhere. An in-source build puts them in your source tree. An out-of-source build puts them in a completely separate directory, so that your source tree is unchanged.<br />
<br />
In the first example, an in-place build is performed, i.e., the binaries are placed in the same directory as the source code.<br />
<br />
cd Hello<br />
ccmake .<br />
make<br />
<br />
In the second example, an out-of-place build is performed, i.e., the source code, libraries, and executables are produced in a directory separate from the source code directory(ies).<br />
<br />
mkdir HelloBuild<br />
cd HelloBuild<br />
ccmake ../Hello<br />
make<br />
<br />
Out-of-source builds are recommended, as you can build multiple variants in separate directories, e.g., HelloBuildDebug, HelloBuildRelease.<br />
<br />
Note: Before performing an out-of-source build ensure that any possible CMake generated in-source build information is removed from the source directory, e.g., CMakeFiles directory, and CMakeCache.txt.<br />
<br />
=== I run an out-of-source build but CMake generates in-source anyway. Why? ===<br />
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.<br />
<br />
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).<br />
<br />
=== Why does CMake use full paths, or can I copy my build tree? ===<br />
CMake uses full paths because:<br />
<br />
# configured header files may have full paths in them, and moving those files without re-configuring would cause upredictable behavior.<br />
# because cmake supports out of source builds, if custom commands used relative paths to the source tree, they would not work when they are run in the build tree because the current directory would be incorrect.<br />
# on Unix systems rpaths might be 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.<br />
<br />
Can the build tree be copied or moved?<br />
<br />
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 and rerun. Often when people want to move a binary tree it is so that they can distribute it to other users who may not have cmake in which case this would not work even if cmake would detect the move.<br />
<br />
The workaround is to create a new build tree without copying or moving the old one.<br />
<br />
<br />
=== CMake does not generate a "make distclean" target. Why? ===<br />
Some build trees created with GNU autotools have a "make distclean" target that cleans the build and also removes Makefiles and other parts of the generated build system. CMake does not generate a "make distclean" target because CMakeLists.txt files can run scripts and arbitrary commands; CMake has no way of tracking 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. (CMake does generate a "make clean" target to remove files generated by the compiler and linker.)<br />
<br />
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. Because CMake does not change the source tree, there is no need for a distclean target. One can start a fresh build by deleting the build tree or creating a separate build tree.<br />
<br />
(If a CMakeLists.txt uses ADD_CUSTOM_COMMAND to generate source files in the source tree, not the build tree, then in CMake 2.2 or higher "make clean" will remove them. See next question.)<br />
<br />
=== Running "make clean" does not remove custom command outputs. Why? ===<br />
In CMake 2.2 and higher custom command outputs should be removed by make clean. Make sure you are using at least this version. Prior to CMake 2.2 custom command outputs were not automatically added to the list of files to clean. In CMake 2.0 the 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.<br />
<br />
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 to clean away files that differ between builds.<br />
<br />
<br />
== Writing CMakeLists.txt ==<br />
<br />
=== How to have backward and forward compatibility? ===<br />
<br />
As of CMake 2.6 we employ a "Policy" mechanism to provide backwards compatibility.<br />
The basic requirement for projects is to include one line at the top of the highest CMakeLists.txt file:<br />
<br />
cmake_minimum_required(VERSION 2.6) # or other version<br />
<br />
This tells versions of CMake older than that specified that they are too old to build the project.<br />
They will report this information to the user.<br />
It also tells versions of CMake newer than that specified that the project may not be aware of policies introduced in later versions, which enables additional compatibility.<br />
For futher documentation, see<br />
<br />
* [[CMake_Policies|CMake Policy Mechanism]]<br />
* [http://www.cmake.org/cmake/help/cmake2.6docs.html#command:cmake_policy cmake_policy() command]<br />
* [http://www.cmake.org/cmake/help/cmake2.6docs.html#section_Policies CMake 2.6 Policies]<br />
<br />
=== How do I get the current source or binary directory? ===<br />
The variable CMAKE_CURRENT_SOURCE_DIR contains the absolute path to your current source directory, while CMAKE_CURRENT_BINARY_DIR points to the equivalent binary directory.<br />
<br />
=== Why are my CMake variables not updated in the GUI after a SET command? ===<br />
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.<br />
<br />
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:<br />
<br />
SET(BUILD_SHARED_LIBS ON)<br />
<br />
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.<br />
<br />
You can use the CACHE and FORCE options on the SET command to change variables in a way that will be reflected in the GUI. Run<br />
<br />
cmake --help-command SET<br />
<br />
to see full instructions for the command.<br />
<br />
<br />
=== How can I change the default build mode and see it reflected in the GUI? ===<br />
Adapt the following commands in your CMakeList.txt (this example sets the Release<br />
With Debug Information mode):<br />
<pre><br />
IF(NOT CMAKE_BUILD_TYPE)<br />
SET(CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING<br />
"Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel."<br />
FORCE)<br />
ENDIF(NOT CMAKE_BUILD_TYPE)<br />
</pre><br />
<br />
=== How do I generate an executable, then use the executable to generate a file? ===<br />
<br />
Create the generator executable by just adding a target:<br />
<br />
ADD_EXECUTABLE(generate generate.c)<br />
<br />
The rest of the process is simpler in CMake 2.6 and above than in previous versions.<br />
<br />
Use <code>ADD_CUSTOM_COMMAND</code> to specify a custom build rule for the file.<br />
(In this example we assume <code>generate</code> accpets the input and output files as arguments.)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT someoutput.txt<br />
COMMAND generate ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
DEPENDS generate ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt<br />
)<br />
<br />
This tells CMake how to build the file but does not actually add a rule to the build system.<br />
Another target must require it.<br />
One may create a custom target explicitly for this rule:<br />
<br />
ADD_CUSTOM_TARGET(driver ALL DEPENDS someoutput.txt)<br />
<br />
or the file may be added as part of some other target:<br />
<br />
ADD_EXECUTABLE(product product.c someoutput.txt)<br />
<br />
<font color=#555555><br />
In CMake 2.4 and below the <code>generate</code> target may not be specified directly in the <code>COMMAND</code> option of <code>add_custom_command</code><br />
(but it can still be used in the <code>DEPENDS</code> option as of CMake 2.4).<br />
Instead use GET_TARGET_PROPERTY to obtain the location of the generated executable.<br />
Additionally, the output must always be specified by full path.<br />
<br />
GET_TARGET_PROPERTY(GENERATE_EXE generate LOCATION)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
COMMAND ${GENERATE_EXE} ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
DEPENDS generate<br />
)<br />
</font><br />
<br />
=== How can I generate a source file during the build? ===<br />
The ADD_CUSTOM_COMMAND command lets you generate a source file that you can then include in another target. For example:<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
COMMAND ${CMAKE_COMMAND} copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.c ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.c<br />
)<br />
ADD_EXECUTABLE(foo foo.c)<br />
<br />
This will create an executable by copying bar.c to foo.c and then compiling foo.c to produce foo. CMake allows you to put generate source files in the current source or binary directory, so we were careful to output foo.c to the current binary directory. When we add foo.c to foo, CMake will look in either directory for it. Even if foo.c does not yet exist, CMake is smart enough to notice that a custom command creates it. (For the file named as the OUTPUT, CMake has its GENERATED source file property set to true.)<br />
<br />
You can also use ADD_CUSTOM_COMMAND when the<br />
[[CMake_FAQ#How_do_I_generate_an_executable.2C_then_use_the_executable_to_generate_a_file.3F|generator command is another executable in the same project]].<br />
<br />
Sometimes, the program doing the generation may generate multiple output files that each need to be part of the build. CMake 2.4 or higher supports having multiple files listed in the OUTPUT section. 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:<br />
<br />
PROJECT(FOO)<br />
# make sure cmake addes the binary directory for the project to the include path<br />
INCLUDE_DIRECTORIES(${FOO_BINARY_DIR})<br />
# add the executable that will do the generation<br />
ADD_EXECUTABLE(my_generator my_generator.cxx)<br />
GET_TARGET_PROPERTY(MY_GENERATOR_EXE my_generator LOCATION)<br />
# add the custom command that will generate all three files<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${FOO_BINARY_DIR}/output1.cpp ${FOO_BINARY_DIR}/output2.h ${FOO_BINARY_DIR}/output3.cpp<br />
COMMAND ${MY_GENERATOR_EXE} ${FOO_BINARY_DIR} ${FOO_SOURCE_DIR}/input.txt<br />
DEPENDS my_generator<br />
MAIN_DEPENDENCY ${FOO_SOURCE_DIR}/input.txt<br />
)<br />
# now create an executable using the generated files<br />
ADD_EXECUTABLE(generated<br />
${FOO_BINARY_DIR}/output1.cpp<br />
${FOO_BINARY_DIR}/output2.h<br />
${FOO_BINARY_DIR}/output3.cpp)<br />
<br />
CMake 2.4 allows you to generate a header file. Because generated headers often cause unnecessary rebuilds, you should try to avoid them; consider using the CONFIGURE_FILE command to prepare the header at CMake time. If you must generate a header file, use code like this:<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.h<br />
COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.h ${CMAKE_CURRENT_BINARY_DIR}/foo.h<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.h<br />
)<br />
ADD_EXECUTABLE(foo foo.c ${CMAKE_CURRENT_BINARY_DIR}/foo.h)<br />
<br />
This is like the first example above, except that it generates a header instead of a C file. The header might not exist when the build system scans foo.c's dependencies, so there is no way for CMake to know that this target requires foo.h unless we can tell it that foo.h may exist in the future. We give CMake this knowledge by listing the generated header file in the set of source files for the target. (This requires CMake 2.4. Previous versions of CMake required use of the OBJECT_DEPENDS source file property.)<br />
<br />
=== How can I add a dependency to a source file which is generated in a subdirectory? ===<br />
<br />
Rules created with <code>ADD_CUSTOM_COMMAND</code> as [[CMake_FAQ#How_can_I_generate_a_source_file_during_the_build.3F|above]] have scope only in the directory in which they are specified.<br />
If the generated file is needed in another directory, a target-level dependency needs to be added.<br />
Create a target in the subdirectory with the custom rule in order to drive it:<br />
<br />
# subdir/CMakeLists.txt<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
COMMAND ${CMAKE_COMMAND} copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.c ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.c<br />
)<br />
ADD_CUSTOM_TARGET(generate_foo DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/foo.c)<br />
<br />
Now other targets can depend on the target from the subdirectory:<br />
<br />
# CMakeLists.txt<br />
ADD_SUBDIRECTORY(subdir)<br />
# Create the executable.<br />
ADD_EXECUTABLE(generated ${CMAKE_CURRENT_BINARY_DIR}/subdir/foo.c)<br />
# Tell CMake the source won't be available until build time.<br />
SET_SOURCE_FILES_PROPERTIES(${CMAKE_CURRENT_BINARY_DIR}/subdir/foo.c PROPERTIES GENERATED 1)<br />
# Make sure the source is generated before the executable builds.<br />
ADD_DEPENDENCIES(generated generate_foo)<br />
<br />
=== I use EXEC_PROGRAM but the result is not set in subdirectories. Why? ===<br />
<br />
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 was fixed in CMake 2.2, but for older versions you will have to cache the result:<br />
<br />
<pre><br />
EXEC_PROGRAM(my-program OUTPUT_VARIABLE MY_OUTPUT)<br />
SET(MY_OUTPUT "${MY_OUTPUT}" CACHE INTERNAL "")<br />
</pre><br />
<br />
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.<br />
<br />
=== How can I get or set environment variables? ===<br />
<br />
CMake names environment variables using an ENV prefix and surrounding the names in curly braces. Here is an example:<br />
<br />
<pre><br />
MESSAGE("$ENV{PATH}")<br />
</pre><br />
<br />
Reading variables will work in any version of CMake. Writing to them works in CMake 2.2 and higher using the following syntax:<br />
<br />
<pre><br />
SET(ENV{HELLO} "World")<br />
</pre><br />
<br />
Note that there is currently no way to tell apart an empty environment variable value from a variable that is not set at all.<br />
<br />
One should avoid using environment variables for controlling the flow of CMake code (such as in IF commands). The build system generated by CMake may re-run CMake automatically when CMakeLists.txt files change. The environment in which this is executed is controlled by the build system and may not match that in which CMake was originally run. If you want to control build settings on the CMake command line, you need to use cache variables set with the -D option. The settings will be saved in CMakeCache.txt so that they don't have to be repeated every time CMake is run on the same build tree.<br />
<br />
Also, environment variables SET in the CMakeLists.txt ''only'' take effect for cmake itself, so you cannot use this method to set an environment variable that a custom command might need.<br />
<br />
=== Why do I have unwanted semicolons ; in my compiler flags? ===<br />
CMake has a list data type. A list is stored as a string of semicolon-separated list elements. Whitespace separated arguments to a SET statement are interpreted as list elements. For instance, SET(var a b c d e) will give "var" a value of a;b;c;d;e and this list can be used by other CMake commands. However, if you pass ${var} to a non-CMake external tool, such as a compiler's command line, you are passing a;b;c;d;e which is not what you want. Instead you either need to pass "${var}", so that the list will be converted to a whitespace-separated string, or you need to SET(var "a b c d e") in the 1st place so that you're working with a string, not a list.<br />
<br />
=== How can I get quoting and escapes to work properly? ===<br />
If you want to escape a character in CMake, you use "\", like in C code. For example, if you wanted to have a quote embedded in a string you would do this: "\"". However, each level of CMake that processes your code will need one level of escaping to work. So, if you configure a file that is read by cmake or cpack and you want to do the same thing, you would do "\\\"". You would still need to escape the " for the first cmake that processes the string. However, this time, you would want to also escape a '\' as well. This would leave the next level of processing with "\"". Also, for custom commands that may get passed to a shell, it maybe required to do escaping for that shell.<br />
<br />
=== Isn't the "Expression" in the "ELSE (Expression)" confusing? ===<br />
Traditional CMakeLists.txt files prior to 2.6.0, require the following syntax. In the IF syntax, the ELSE section requires the same (Expression) as the IF section. This sometimes can make the script kind of hard to follow, take the short example below:<br />
<br />
IF(WIN32)<br />
...do something...<br />
ELSE(WIN32)<br />
...do something else...<br />
ENDIF(WIN32)<br />
<br />
You might think that the ELSE section, here containing "...do something else...", is for the WIN32 portion of the script. That is not so! It is actually handling the NOT WIN32 section.<br />
<br />
As of CMake 2.6.0 the ELSE() and ENDIF() constructs can be empty. The same is true for closing constructs on ENDMACRO(), ENDFUNCTION(), and ENDFOREACH(). If you require 2.4.x compatibility, you can enable the CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS option on CMake 2.4.3 or greater. This option is superfluous on CMake 2.6.0 or greater.<br />
<br />
SET(CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS true)<br />
<br />
IF(WIN32)<br />
...do something...<br />
ELSEIF(APPLE)<br />
...do something else...<br />
ELSE()<br />
...do something else...<br />
ENDIF()<br />
<br />
=== Which regular expressions are supported by CMake? ===<br />
When using MATCHES or MATCHALL in an IF command, or using any of the STRING(REGEX ...) commands, CMake expects regular expressions, not globs (wild cards). CMake uses the same regular expression engine above all platforms. Here are the meanings of the metacharacters:<br />
<br />
^ Matches at beginning of a line<br />
$ Matches at end of a line<br />
. Matches any single character<br />
[ ] Matches any character(s) inside the brackets<br />
[^ ] Matches any character(s) not inside the brackets<br />
- Matches any character in range on either side of a dash<br />
| Matches a pattern on either side of the |<br />
* Matches preceding pattern zero or more times<br />
+ Matches preceding pattern one or more times<br />
? Matches preceding pattern zero or once only<br />
() Saves a matched expression and uses it in a later match<br />
<br />
Example: "[-][L]([^ ;])+" matches all strings beginning with -L and ending with a space or a semicolon, the usual linkdirs under Linux.<br />
<br />
Here is how to catch a part of a string. The variable test is filled with some content, and then we want to catch the "me":<br />
<br />
SET(test "hello world ! catch: me if you can")<br />
STRING(REGEX REPLACE ".*catch: ([^ ]+).*" "\\1" result "${test}" )<br />
MESSAGE(STATUS "result= ${result}")<br />
<br />
This is slightly tricky. The part inside the brackets is available in \\1 . CMake will copy the variable test to the variable result, but then it will replace everything that the regular expression matches with \\1. This means the first regular expression has to match the whole string and the part we want to catch has to be put in parens.<br />
<br />
-- result= me<br />
<br />
For those of you who know Perl, the equivalent Perl code could be:<br />
<br />
$test = "hello world ! catch: me if you can";<br />
$result = $test;<br />
$result =~ s/.*catch: ([^ ]+).*/$1/;<br />
print "-- result= $result\n";<br />
<br />
There are other ways to do this in Perl, but this is how we do it in CMake because \\1 does not become a variable like $1 does in perl, so there is no SET(result ${\\1}) in CMake.<br />
<br />
<br />
=== How to convert a semicolon separated list to a whitespace separated string? ===<br />
<br />
set(foo<br />
abc.c<br />
abc.b<br />
abc.a<br />
)<br />
<br />
foreach(arg ${foo})<br />
set(bar "${bar} ${arg}")<br />
endforeach(arg ${foo})<br />
<br />
message("foo: ${foo}")<br />
message("bar: ${bar}")<br />
<br />
=== How can I build multiple modes without switching ? ===<br />
To build multiple modes (e.g. Debug and Release) in one shot without constantly running cmake -DCMAKE_BUILD_TYPE=Debug and cmake -DCMAKE_BUILD_TYPE=Release in source tree create a directory for builds eg.:<br />
<br />
<pre><br />
Project-directory/<br />
/Build<br />
</pre><br />
<br />
Inside you can place as many target directories for out-of-source build modes as you want, e.g.:<br />
<br />
<pre><br />
Project-directory/<br />
/Build<br />
/Debug<br />
/Release<br />
</pre><br />
<br />
In each of these directories issue a command (assuming that you have CMakeLists.txt directly in Project-directory)<br />
<br />
<pre><br />
cmake -DCMAKE_BUILD_TYPE=type_of_build ../../<br />
</pre><br />
<br />
to create a cmake cache configured for requested build type.<br />
<br />
Now you can make each build just by entering appropriate directory and executing a make command.<br />
<br />
=== How can I extend the build modes with a custom made one ? ===<br />
The following code snipet (taken from a CMakeLists.txt) adds a Maintainer mode:<br />
<pre><br />
SET( CMAKE_CXX_FLAGS_MAINTAINER "-Wall -Wabi" CACHE STRING<br />
"Flags used by the C++ compiler during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_C_FLAGS_MAINTAINER "-Wall -pedantic" CACHE STRING<br />
"Flags used by the C compiler during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_EXE_LINKER_FLAGS_MAINTAINER<br />
"-Wl,--warn-unresolved-symbols,--warn-once" CACHE STRING<br />
"Flags used for linking binaries during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_SHARED_LINKER_FLAGS_MAINTAINER<br />
"-Wl,--warn-unresolved-symbols,--warn-once" CACHE STRING<br />
"Flags used by the shared libraries linker during maintainer builds."<br />
FORCE )<br />
MARK_AS_ADVANCED(<br />
CMAKE_CXX_FLAGS_MAINTAINER<br />
CMAKE_C_FLAGS_MAINTAINER<br />
CMAKE_EXE_LINKER_FLAGS_MAINTAINER<br />
CMAKE_SHARED_LINKER_FLAGS_MAINTAINER )<br />
# Update the documentation string of CMAKE_BUILD_TYPE for GUIs<br />
SET( CMAKE_BUILD_TYPE "" CACHE STRING<br />
"Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel Maintainer."<br />
FORCE )<br />
</pre><br />
Notes: this will only work with gcc (since the flags would need to be<br />
declined with the possible compilers). Additionaly this will override<br />
a CMAKE_BUILD_TYPE previously set in the CMakeLists.txt...<br />
<br />
== Writing FindXXX.cmake files ==<br />
<br />
=== What are the rules to write a FindXXX.cmake file? ===<br />
<br />
Let's follow the instructions and the advices in the <br />
Modules/readme.txt [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/readme.txt?root=CMake&view=markup]<br />
file located in the CVS repository.<br />
<br />
=== Why does find_library look in system directories before its PATHS option? ===<br />
<br />
The code in question is often of the form<br />
<br />
find_library(FOO_LIBRARY NAMES foo PATHS /opt/foo/lib)<br />
<br />
CMake will find "<code>/usr/lib/libfoo.so</code>" instead of "<code>/opt/foo/lib/libfoo.so</code>" if both exist.<br />
The reason is that /opt/foo/lib is a <i>hard-coded guess</i> of the location.<br />
The documentation of <code>[http://www.cmake.org/cmake/help/cmake2.6docs.html#command:find_library find_library]</code> specifies the search order.<br />
User, project, and system configuration variables are always more local than hard-coded guesses and should override them, so<br />
the PATHS option is used last.<br />
<br />
Some find-modules compute probable locations based on other information <i>available from the system</i> such as a project-specific environment variable.<br />
The HINTS option (CMake 2.6 and higher) takes precedence over system directories specifically for this case:<br />
<br />
file(TO_CMAKE_PATH "$ENV{FOO_LIB_DIR}" FOO_LIB_DIR)<br />
find_library(FOO_LIBRARY NAMES foo HINTS ${FOO_LIB_DIR})<br />
<br />
CMake will find "<code>$ENV{FOO_LIB_DIR}/libfoo.so</code>" before "<code>/usr/lib/libfoo.so</code>".<br />
<br />
== Finding and using external packages ==<br />
<br />
=== How do I use CMake to generate SWIG wrapper libraries? ===<br />
<br />
CMake version 2 includes a module that supports the generation of SWIG wrapper libraries. The SWIG package defines the following macros: SWIG_ADD_MODULE and SWIG_LINK_LIBRARIES.<br />
<br />
<pre><br />
# This example shows how to use python<br />
# Currently these languages have been tested:<br />
# perl tcl ruby php4 pike<br />
<br />
FIND_PACKAGE(SWIG REQUIRED)<br />
INCLUDE(${SWIG_USE_FILE})<br />
<br />
FIND_PACKAGE(PythonLibs)<br />
INCLUDE_DIRECTORIES(${PYTHON_INCLUDE_PATH})<br />
<br />
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})<br />
<br />
SET(CMAKE_SWIG_FLAGS "")<br />
<br />
SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES CPLUSPLUS ON)<br />
SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES SWIG_FLAGS "-includeall")<br />
SWIG_ADD_MODULE(example python<br />
example.i example.cxx)<br />
SWIG_LINK_LIBRARIES(example ${PYTHON_LIBRARIES})<br />
<br />
</pre><br />
<br />
<pre><br />
# This example shows how to use tcl<br />
PROJECT(TCL_WRAP)<br />
SET ( MODULE_NAME project )<br />
SET ( INTERFACE_FILES project.i)<br />
SET ( SRC_FILES Vertex.h Vertex.cxx Shapes.h Shapes.cxx )<br />
<br />
FIND_PACKAGE(SWIG REQUIRED)<br />
INCLUDE(${SWIG_USE_FILE})<br />
<br />
# Look for TCL<br />
INCLUDE_DIRECTORIES(${TCL_INCLUDE_PATH})<br />
<br />
FIND_LIBRARY(TCL_LIBRARY NAMES tcl tcl84 tcl83 tcl82 tcl80<br />
PATHS /usr/lib /usr/local/lib)<br />
IF (TCL_LIBRARY)<br />
TARGET_ADD_LIBRARY (${MODULE_NAME} TCL_LIBRARY)<br />
ENDIF (TCL_LIBRARY)<br />
<br />
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})<br />
<br />
SET(CMAKE_SWIG_FLAGS "-c++")<br />
<br />
SET_SOURCE_FILES_PROPERTIES(${INTERFACE_FILES} PROPERTIES CPLUSPLUS ON)<br />
SET_SOURCE_FILES_PROPERTIES(${INTERFACE_FILES} PROPERTIES CMAKE_SWIG_FLAGS "-includeall")<br />
SWIG_ADD_MODULE(${MODULE_NAME} tcl ${INTERFACE_FILES} ${SRC_FILES})<br />
SWIG_LINK_LIBRARIES(${MODULE_NAME} ${TCL_LIBRARIES})<br />
</pre><br />
<br />
=== How do I use CMake to build LaTeX documents? ===<br />
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.<br />
<br />
PROJECT(Document)<br />
IF(LATEX_COMPILE)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${Document_BINARY_DIR}/TDocument.dvi<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.tex<br />
COMMAND ${LATEX_COMPILE} <br />
ARGS ${Document_SOURCE_DIR}/TDocument.tex <br />
)<br />
ENDIF(LATEX_COMPILE)<br />
<br />
IF(DVIPDF_COMPILE)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${Document_BINARY_DIR}/TDocument.pdf<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.dvi <br />
COMMAND ${DVIPDF_COMPILE}<br />
ARGS ${Document_SOURCE_DIR}/TDocument.dvi<br />
)<br />
ENDIF(DVIPDF_COMPILE)<br />
<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.pdf<br />
)<br />
<br />
The following uses commands in CMake version 2.0 and later<br />
<br />
PROJECT(Document)<br />
# <br />
# Find LaTeX<br />
#<br />
FIND_PACKAGE(LATEX)<br />
<br />
IF(LATEX_COMPILER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.dvi<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS ${Document_SOURCE_DIR}/TDocument.tex<br />
DEPENDS ${Document_SOURCE_DIR}/TDocument.tex<br />
COMMENT "Tex2dvi"<br />
)<br />
<br />
IF(DVIPS_CONVERTER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.ps<br />
COMMAND ${DVIPS_CONVERTER}<br />
ARGS ${Document_BINARY_DIR}/TDocument.dvi<br />
-o ${Document_BINARY_DIR}/TDocument.ps<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.dvi<br />
COMMENT "dvi2ps"<br />
)<br />
<br />
IF(PS2PDF_CONVERTER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.pdf<br />
COMMAND ${PS2PDF_CONVERTER}<br />
ARGS ${Document_BINARY_DIR}/TDocument.ps<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.ps<br />
COMMENT "ps2pdf"<br />
)<br />
<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.pdf<br />
)<br />
ENDIF(PS2PDF_CONVERTER)<br />
ENDIF(DVIPS_CONVERTER)<br />
ENDIF(LATEX_COMPILER)<br />
<br />
=== How do I get LaTeX references to be correct? ===<br />
When your latex document contains references (e.g. \ref{...} command) you get to run two passes of latex. In the<br />
most general case, i.e. when additionally your document uses a bibtex bibliography, you shall need three<br />
passes of latex (and one pass of bibtex):<br />
# latex (first pass: for bibtex to have an .aux file)<br />
# bibtex (for generating the .bbl file)<br />
# latex (second pass)<br />
# latex (third pass)<br />
<br />
The following code snippet illustrates how you can "pervert" the bibtex and latex generated<br />
auxilary files (.aux, .log, .dvi, .bbl...) to create an "artificial" set of CMake dependencies.<br />
The side-effect of those dependencies should hopefully be the above described sequence of calls<br />
to latex and bibtex<br />
<pre><br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.aux<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/UsersManual.tex<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (first pass)"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.aux<br />
COMMAND ${BIBTEX_COMPILER}<br />
ARGS -terse ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Bibtex"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.dvi<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (second pass)"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.log<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
${CMAKE_CURRENT_BINARY_DIR}/UsersManual.dvi<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (third pass)"<br />
)<br />
# Eventually trigger the whole process<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.log<br />
)<br />
</pre><br />
<br />
=== How can I set TEXINPUTS for a LaTeX compilation? ===<br />
First note that most often you can avoid using TEXINPUTS by copying all the necessary files (.tex source file and<br />
included graphic files e.g. .eps files) from your PROJECT_SOURCE_DIR hirarchy to your PROJECT_BINARY_DIR subdir<br />
[refer to CONFIGURE_FILE with the COPYONLY flag set for copying files]. Since by default latex uses the current working directory as value for TEXINPUTS you should be all set. As expected, this trick is quick AND dirty since your<br />
concerned PROJECT_BINARY_DIR subdir now contains files that are NOT generated by CMake (in the sense that those<br />
files are not the result of a system command but were merely duplicated)... <br />
<br />
If you consider it is cleaner or easier to define a TEXINPUTS environment variable [the latex command probably<br />
misses a -I flag] you can find an example in the InsightDocuments cvs archive (refer to the section "cvs access"<br />
near the bottom of Kitware's ITK download page) or use google with keywords "ITK_TEXINPUTS CONFIGURE_FILE".<br />
Look at InsightDocuments/CourseWare/Training/Vis2003/Latex/CMakeLists.txt and search for e.g. "LaTeXWrapper.sh.in".<br />
<br />
Roughly the mechanism goes:<br />
* SET ITK_TEXINPUTS with the desired TEXINPUTS<br />
* CONFIGURE_FILE "InsightDocuments/CourseWare/Training/Vis2003/LaTeXWrapper.sh.in" which generates an sh shell script setting the shell variable TEXINPUTS prior to running the latex command<br />
* use ADD_CUSTOM_COMMAND to invoke this shell script<br />
This very example is Win32 portable (except that LaTeXWrapper.bat.in generates a .bat shell script)<br />
<br />
== Library questions ==<br />
<br />
=== Can I build both shared and static libraries with one ADD_LIBRARY command? ===<br />
<br />
No. Each library you build must have a unique target name, i.e. the "libname" field of the ADD_LIBRARY command. That way, CMake can track dependencies separately for each library. Libraries can have the same OUTPUT_NAME, see the SET_TARGET_PROPERTIES command, but this is not the default.<br />
<br />
=== Does that mean I have to build all my library objects twice, once for shared and once for static?! I don't like that! ===<br />
<br />
In practice, most libraries have different defines and compiler flags for the shared vs. static cases. So you would have to build all your library objects twice anyways. However, if you happen to have '''''exactly''''' the same defines and compiler flags for the shared vs. static cases...<br />
<br />
...if you're using Linux and a GCC-style linker, you could do the following. Note that for this to work correctly on linux, the zzSTATIC source files should have been compiled with "-fPIC" to ensure they will work in a shared library.<br />
<br />
IF(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_COMPILER_IS_GNUCC)<br />
ADD_LIBRARY(zzSTATIC STATIC -fPIC)<br />
ADD_LIBRARY(zzDYNAMIC SHARED)<br />
TARGET_LINK_LIBRARIES(zzDYNAMIC -Wl,-whole-archive zzSTATIC -Wl,-no-whole-archive)<br />
ENDIF(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_COMPILER_IS_GNUCC)<br />
<br />
...if you want a cross-platform approach that works on all compilers, not just GCC or Linux, you could extract the locations of previously built object files and insert them directly into the libraries that need them. This is documented in [http://www.cmake.org/Bug/view.php?id=5155 CMake Feature Request #5155: standard way to locate object files]. Unfortunately this approach relies on CMake's internal implementation, and that implementation could change in the future, breaking your code.<br />
<br />
=== How do I make my shared and static libraries have the same root name, but different suffixes? ===<br />
Set the OUTPUT_NAME of your shared and static libraries to the same thing.<br />
<br />
ADD_LIBRARY(foo SHARED ${foo_sources})<br />
ADD_LIBRARY(foo-static STATIC ${foo_sources})<br />
// The library target "foo" already has a default OUTPUT_NAME of "foo", so we don't need to change it.<br />
// The library target "foo-static" has a default OUTPUT_NAME of "foo-static", so change it.<br />
SET_TARGET_PROPERTIES(foo-static PROPERTIES OUTPUT_NAME "foo")<br />
<br />
If you are building your shared and static libraries in the same directory, you will also need the following to keep your shared and static libraries from clobbering each other during the build.<br />
<br />
SET_TARGET_PROPERTIES(foo PROPERTIES CLEAN_DIRECT_OUTPUT 1)<br />
SET_TARGET_PROPERTIES(foo-static PROPERTIES CLEAN_DIRECT_OUTPUT 1)<br />
<br />
=== How do I rename a library after it has already been built? ===<br />
You don't rename it. It's been built! Its name is whatever CMakeLists.txt says it's supposed to be.<br />
<br />
Perhaps you want to copy the library to a different name. But, are you sure that's what you want to do? You could just change the name in your ADD_LIBRARY command or change its OUTPUT_NAME property using SET_TARGET_PROPERTY(). If you really really want to copy the library to a different name, try:<br />
<br />
GET_TARGET_PROPERTY(LIB_NAME Foo LOCATION)<br />
GET_TARGET_PROPERTY(Bar_prefix Foo PREFIX)<br />
GET_TARGET_PROPERTY(Bar_suffix Foo SUFFIX)<br />
SET(NEW_LIB_NAME ${Bar_prefix}Bar${Bar_suffix})<br />
<br />
ADD_CUSTOM_COMMAND(<br />
TARGET Foo<br />
POST_BUILD<br />
COMMAND ${CMAKE_COMMAND} -E copy ${LIB_NAME} ${NEW_LIB_NAME}<br />
)<br />
<br />
On Windows you may also want to copy the .dll import lib, using the same approach as above, but with IMPORT_PREFIX and IMPORT_SUFFIX. ''Problem: LOCATION only refers to 1 file, the .dll. What is a simple way to get the location of the import lib? Could provide a complicated way, but that's annoying.''<br />
<br />
=== Does CMake support "convenience" libraries? ===<br />
No. CMake does not currently support convenience libraries. A "convenience" library, as GNU libtool calls it, is an archive of objects to be mixed into other libraries. Other libraries "link" to the convenience library, but the convenience library does not export any symbols; GNU libtool never installs the convenience library; no programs ever link to the convenience library.<br />
<br />
This does '''not''' mean that a project using convenience libraries cannot be converted to CMake. Instead the source files may be listed in each target that needs them. They will be built for each target separately using all the preprocessor definitions and flags configured for that target.<br />
<br />
=== Why are libraries linked to my shared library included when something links to it? ===<br />
This question arises when one has a library B which links to some library A. When a third target, say C, links to B, CMake will automatically include C to A also. When the libraries are static, then this is always necessary. When the libraries are shared, this is the default behavior provided by CMake. CMake 2.6 and above provide the target property "LINK_INTERFACE_LIBRARIES" (http://www.cmake.org/HTML/cmake-2.6.html#prop_tgt:LINK_INTERFACE_LIBRARIES) to specify the libraries that should be transitively included in the link by CMake. CMake 2.4 and below do not support the property.<br />
<br />
=== CMake dependency scanner ===<br />
<br />
CMake does not preprocess source files while scanning dependencies. Code like<br />
<pre><br />
#if 0<br />
# include "bla.h"<br />
#endif<br />
</pre><br />
will result in a dependency on "bla.h". This sometimes leads to source files recompiling unnecessarily but will not break the build.<br />
<br />
== Installation questions ==<br />
<br />
=== Does CMake's "make install" support DESTDIR? ===<br />
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<br />
<br />
make install DESTDIR="/home/me/mydist"<br />
<br />
will cause the installation to copy files to "/home/me/mydist/${CMAKE_INSTALL_PREFIX}/...". This is useful for package maintainers.<br />
<br />
=== Can I do "make uninstall" with CMake?===<br />
By default, CMake does not provide the "make uninstall" target, so you cannot do this. We do not want "make uninstall" to remove useful files from the system.<br />
<br />
If you want an "uninstall" target in your project, then nobody prevents you from providing one. You need to delete the files listed in install_manifest.txt file. Here is how to do it. First create file cmake_uninstall.cmake.in in the top-level directory of the project:<br />
<br />
<pre><br />
IF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")<br />
MESSAGE(FATAL_ERROR "Cannot find install manifest: \"@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt\"")<br />
ENDIF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")<br />
<br />
FILE(READ "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt" files)<br />
STRING(REGEX REPLACE "\n" ";" files "${files}")<br />
FOREACH(file ${files})<br />
MESSAGE(STATUS "Uninstalling \"$ENV{DESTDIR}${file}\"")<br />
IF(EXISTS "$ENV{DESTDIR}${file}")<br />
EXEC_PROGRAM(<br />
"@CMAKE_COMMAND@" ARGS "-E remove \"$ENV{DESTDIR}${file}\""<br />
OUTPUT_VARIABLE rm_out<br />
RETURN_VALUE rm_retval<br />
)<br />
IF(NOT "${rm_retval}" STREQUAL 0)<br />
MESSAGE(FATAL_ERROR "Problem when removing \"$ENV{DESTDIR}${file}\"")<br />
ENDIF(NOT "${rm_retval}" STREQUAL 0)<br />
ELSE(EXISTS "$ENV{DESTDIR}${file}")<br />
MESSAGE(STATUS "File \"$ENV{DESTDIR}${file}\" does not exist.")<br />
ENDIF(EXISTS "$ENV{DESTDIR}${file}")<br />
ENDFOREACH(file)<br />
</pre><br />
<br />
Then in the top-level CMakeLists.txt add the following logic:<br />
<br />
<pre><br />
CONFIGURE_FILE(<br />
"${CMAKE_CURRENT_SOURCE_DIR}/cmake_uninstall.cmake.in"<br />
"${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake"<br />
IMMEDIATE @ONLY)<br />
<br />
ADD_CUSTOM_TARGET(uninstall<br />
"${CMAKE_COMMAND}" -P "${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake")<br />
</pre><br />
<br />
Now you will have an "uninstall" target at the top-level directory of your build tree.<br />
<br />
Instead of creating an "uninstall" target, Unix users could enter this command in the shell:<br />
<br />
xargs rm < install_manifest.txt<br />
<br />
== Distribution questions ==<br />
<br />
=== Where is "make dist"? ===<br />
<br />
CMake doesn't create a "make dist" target.<br />
<br />
=== What is the best way to distribute source code or binaries for a cmake-based project? ===<br />
<br />
For creating source or binary packages there is now [[CMake#CPack | CPack]] coming with CMake, see the <br />
[[ CMake#CPack | documentation]].<br />
<br />
Of course you can also use any other ways to create packages.<br />
<br />
== Platform-specific questions ==<br />
=== How do I build universal binaries on Mac OS X? ===<br />
Before running CMake with an empty build tree, set the CMAKE_OSX_ARCHITECTURES environment variable. It should be set to contain a ; separated list of architectures that you want in the binary. For example, for 32-bit PowerPC and Intel you would do this:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386<br />
<br />
If you wish to build both as 32 and 64 bit, do this:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386;ppc64;x86_64<br />
<br />
You can also set the same named CMake cache variable on an existing binary tree. This works with both makefiles and the Xcode generator. <br />
<br />
In addition, you can also set the CMAKE_OSX_SYSROOT variable to point to the sysroot (aka Mac OS SDK) to be used. CMake will attempt to pick one on your system, but it can be changed in the cache or via an environment variable before running CMake. The 10.4u SDK or later must be used to create a Universal Binary.<br />
<br />
Universal Binaries are essentially cross compilation and so you should avoid using TRY_RUN, especially for things like testing endianess or variable size because the result will only be correct for one architecture.<br />
<br />
Lastly, note that CTest is only able to test one architecture. See bug 6157.<br />
<br />
=== How can I apply resources on Mac OS X automatically? ===<br />
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 a custom rule which is executed after the executable is linked:<br />
<br />
<pre><br />
ADD_EXECUTABLE(MyExecutable ${MyExecutable_SRCS})<br />
GET_TARGET_PROPERTY(MyExecutable_PATH MyExecutable LOCATION)<br />
<br />
IF(APPLE)<br />
FIND_PROGRAM(APPLE_RESOURCE Rez /Developer/Tools)<br />
IF(APPLE_RESOURCE)<br />
ADD_CUSTOM_COMMAND(TARGET MyExecutable POST_BUILD<br />
COMMAND ${APPLE_RESOURCE} Carbon.r -o ${MyExecutable_PATH})<br />
ENDIF(APPLE_RESOURCE)<br />
ENDIF(APPLE)<br />
</pre><br />
<br />
This will execute:<br />
<br />
/Developer/Tools/Rez Carbon.r -o /binary/path/MyExecutable<br />
<br />
after MyExecutable is linked.<br />
<br />
'Rez' may be located elsewhere on disk, depending on the version of Mac OS X and Xcode. You can use 'which Rez' in Terminal to find it's full path.<br />
<br />
=== Why does FIND_LIBRARY not find .DLL libraries under WIN32? ===<br />
For those who come from a Unix background to MS Windows:<br />
<br />
You never link directly to the .dll, you have to link against the import library .lib for the .dll.<br />
<br />
Linking against dynamic libraries (.dll under Windows) is quite different from linking against ELF shared objects (.so) under platforms like Linux or NetBSD. In Windows, there are two types of library, a static library and an import library (both confusingly use the .lib extension, however). In Windows, when you build an import library (A.lib) you will get a corresponding (A.dll) that you only need at runtime. At compile time you will need the import library.<br />
<br />
Conclusion: There is no need to find a .dll for linking. You only need to find the .lib import library.<br />
<br />
Some more details can be found here: [http://xenophilia.org/winvunix.html].<br />
<br />
=== Why am I getting a linker error to _mainCRTStartup under WIN32? ===<br />
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.<br />
<br />
ADD_EXECUTABLE(exename WIN32 source1 source2 ... sourceN)<br />
<br />
The second argument to ADD_EXECUTABLE can be WIN32. This indicates that the executable, when compiled on Windows, is a Windows app (using WinMain) and not a console app (using main). Please note that on Unix platforms, CMake ignores the WIN32 and the compiler will use "main" in any case.<br />
<br />
=== Why do I get this error: nafxcwd.lib(appcore.obj) : error LNK2001: unresolved external symbol ___argv ===<br />
<br />
This is because the application is using both the static and dll versions of the MFC library.<br />
To fix the problem, you can do the following:<br />
<br />
SET(CMAKE_MFC_FLAG 2) # force the IDE to use static MFC<br />
ADD_DEFINITIONS(-D_AFXDLL) # make sure if afx.h is included the dll MFC is used<br />
<br />
=== How to use MFC with CMake ===<br />
To use MFC, the CMAKE_MFC_FLAG variable must be set as follows:<br />
<br />
0: Use Standard Windows Libraries<br />
1: Use MFC in a Static Library<br />
2: Use MFC in a Shared DLL <br />
<br />
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:<br />
<br />
ADD_DEFINITIONS(-D_AFXDLL)<br />
SET(CMAKE_MFC_FLAG 2) <br />
ADD_EXECUTABLE(CMakeSetup WIN32 ${SRCS})<br />
<br />
=== How To Put Files in Folders in Visual Studio Projects ===<br />
The Visual Studio IDE supports putting files into folders.<br />
CMake can be used to put files in folders with the SOURCE_GROUP <br />
command. <br />
<br />
SOURCE_GROUP(name [REGULAR_EXPRESSION regex] [FILES src1 src2 ...])<br />
<br />
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 provided the source file is being passed to ADD_EXECUTABLE or ADD_LIBRARY.<br />
<br />
For example:<br />
SOURCE_GROUP(FooFiles FILES foo.cxx)<br />
SOURCE_GROUP(BarFiles FILES bar.cxx)<br />
ADD_LIBRARY(foo foo.cxx bar.cxx)<br />
<br />
In the event 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).<br />
<br />
As a convenience to developers CMake automatically adds standard header files to a "Header Files" folder and standard source files to a "Source Files" folder for Visual Studio Projects. This can be overridden via the SOURCE_GROUP method documented above.<br />
<br />
=== How to create Visual Studio 6 Projects that contain only a single build type===<br />
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:<br />
<br />
# Create a directory in which you copy the files *.dsptemplate and CMakeVisualStudio6Configurations.cmake from CMake's Templates directory.<br />
# Edit the .cmake file and change the SET(CMAKE_CONFIGURATION_TYPES ...) line to set the build types that you want in your set.<br />
# Edit the *Header.dsptemplate files to contain only the configuration types you want in your set.<br />
# In your CMakeLists.txt file, set the MSPROJECT_TEMPLATE_DIRECTORY to the directory that you created.<br />
<br />
<br />
That's it. Run CMake and your new configuration files will be created.<br />
<br />
Note: Editing the *Header.dsptemplates files should be done very carefully. Here are some guidelines:<br />
<br />
- 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"')<br />
- 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.<br />
- 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.<br />
<br />
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:<br />
# PROP BASE Output_Dir ""<br />
# PROP BASE Intermediate_Dir ""<br />
# PROP Intermediate_Dir ""<br />
# PROP Output_Dir "LIBRARY_OUTPUT_PATH"<br />
or<br />
# PROP Output_Dir "EXECUTABLE_OUTPUT_PATH"<br />
<br />
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).<br />
<br />
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.<br />
<br />
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.)<br />
<br />
=== Can CMake set the Debugging/Working Directory property in Visual Studio projects? ===<br />
<br />
No. The value of this property is not stored in the project files. It is stored in extra files created by the IDE when a solution is loaded (VS .NET 2003 uses a hidden .suo file next to the .sln solution file). The format of these files is not known to CMake and cannot be generated. In some versions of VS the files are binary and not human readable.<br />
<br />
=== Why does CMakeSetup with the message "LINK : fatal error LNK1104: cannot open file 'user32.lib'" while configuring a project? ===<br />
<br />
The path to the SDK libs (user32.lib) must be added by the IDE when the<br />
project generator "Visual Studio 8 2005" is used, because cmake uses<br />
VCExpress.exe and on the fly generated project files to check<br />
for compiling (VCExpress.exe reads some config files for the<br />
compiler/linker options)<br />
<br />
So add the sdk lib path (...\Microsoft Platform SDK\Lib) at Tools->Options->Projects and Solutions->VC++ Directories->Library files<br />
<br />
See also:<br />
*http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/<br />
<br />
=== How can I avoid the error "Arg list too long" when running make? ===<br />
This error is sometimes encountered when building a static library with many object files using Unix make command. It typically looks something like this:<br />
<br />
<pre><br />
gmake[2]: execvp: /bin/sh: Arg list too long<br />
</pre><br />
<br />
When make tries to run the archiver program to build the static library the shell it uses complains that the argument list is too long. In some shells this can be fixed by setting an environment variable such as <tt>ARG_MAX</tt> to extend the length of the command line it will allow.<br />
<br />
=== How can I find out platforms definitions, search paths, etc. from gcc ?===<br />
<br />
The following is really the best if not only way to get information about predefined macros with a GNU compiler:<br />
<pre><br />
$ touch empty.c<br />
$ gcc -v -dD -E empty.c <br />
</pre><br />
This will give you all you might want to know about the preprocessor, the builtin include search dirs and all<br />
predefined definitions, so you can check whether it's __LINUX or _LINUX_ or _APPLE_ or __APPLE etc. <br />
The empty file and all these parameters are really required. You probably want to pipe the output (both stdout and stderr) to a file.<br />
<br />
This is how you can get the builtin library search paths:<br />
<pre><br />
$ gcc --print-search-dirs<br />
</pre><br />
<br />
=== How can I get a windows registry key ?===<br />
<br />
The only thing to know is that you can't use just the "SET" command in place of "GET" command.<br />
CMake read the value from the registry only when you "get" it from the cache. For instance :<br />
<br />
<pre><br />
GET_FILENAME_COMPONENT(SDK_ROOT_PATH "[HKEY_LOCAL_MACHINE\\SOFTWARE\\PACKAGE;Install_Dir]" ABSOLUTE CACHE)<br />
</pre><br />
<br />
If a key name (ex: Install_Dir in this case) was not specified , the Default key value will be get.<br />
Now you could use the SDK_ROOT_PATH to add include and lib path to your project :<br />
<br />
<pre><br />
INCLUDE_DIRECTORIES(<br />
${SDK_ROOT_PATH}/include<br />
)<br />
<br />
LINK_DIRECTORIES(<br />
${SDK_ROOT_PATH}/lib<br />
)<br />
</pre><br />
<br />
You can also read a registry key in the PATHS section of a FIND_LIBRARY, FIND_PATH, FIND_PROGRAM, or FIND_FILE command<br />
FIND_FILE(BOOT_DOT_INI boot.ini PATHS [HKEY_CURRENT_USER\\Environment;HOMEDRIVE])<br />
<br />
For other examples have a look in the CMake Modules folder :<br />
- FindJava.cmake<br />
- FindPythonLibs.cmake<br />
- ..<br />
<br />
{{CMake/Template/Footer}}</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake_FAQ&diff=14574CMake FAQ2009-02-09T12:41:39Z<p>Plowman: /* Isn't the "Expression" in the "ELSE (Expression)" confusing? */ made wording more neutral, mentioned change of behavior in 2.6.0</p>
<hr />
<div>== General information and availability ==<br />
=== What is CMake? ===<br />
CMake is a cross-platform, open-source make system. CMake is used to control the software compilation process using simple platform-independent 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 http://www.cmake.org/HTML/About.html to learn more about CMake.<br />
<br />
=== What is the current release? ===<br />
The latest release of CMake is always available at: http://www.cmake.org/HTML/Download.html<br />
<br />
From there, you can fetch CMake binaries for Windows or several Unix variants, or you can download the source code of CMake.<br />
<br />
You can also access nightly development through CVS; see http://www.cmake.org/HTML/Download.html for more information. You may also browse the [http://www.cmake.org/cgi-bin/viewcvs.cgi/?root=CMake cvs repository online].<br />
<br />
=== I found a Bug! What should I do? ===<br />
Please report the bug in our bug tracker: http://www.cmake.org/Bug<br />
<br />
Please make sure to look at the old bugs not to include duplicates, include detailed instructions of the bug and how to reproduce it.<br />
<br />
=== I want a new feature in CMake. What should I do? ===<br />
Report a feature request in our Bug tracker http://www.cmake.org/Bug<br />
<br />
Please make sure to look at the old feature requests not to include duplicates, include detailed instructions of the feature and proposed implementation.<br />
<br />
=== What is the most recent version covered by the Mastering CMake book? ===<br />
A new edition of the [http://www.kitware.com/products/cmakebook.html Mastering CMake] book has been released which documents CMake 2.6.<br />
<br />
The following features have been added since printing the book:<br />
<br />
* New INSTALL command (cmake --help-command INSTALL)<br />
* New LIST command (cmake --help-command LIST)<br />
* Updated FIND_PATH, FIND_PROGRAM, and FIND_FILE commands to be more powerful (cmake --help-command FIND_PATH)<br />
* RPATH and Mac OS X install_name support (cmake --help-command SET_TARGET_PROPERTIES)<br />
* CPack Beta (not finished or documented)<br />
* EXECUTE_PROCESS was added and replaces EXEC_PROGRAM<br />
* Other changes have been bug fixes and internal CMake restructuring<br />
<br />
== Running CMake ==<br />
<br />
=== Is there an option to produce more 'verbose' compiling? ===<br />
Set CMAKE_VERBOSE_MAKEFILE to ON. This will make generator to produce all outputs, including compiler lines.<br />
<br />
If you are on Windows using Borland or NMake Makefiles, then you will see lines like:<br />
<br />
cl @c:\DOCUME~1\ANDY~1.KIT\LOCALS~1\Temp\nma03504<br />
<br />
The reason for this is that Borland and Microsoft Visual Studio make programs have limitation on the length of command strings. They overcome this limitation by writing arguments to the file and then pass file to the program.<br />
<br />
If you actually want to see what the command looks like, set CMAKE_START_TEMP_FILE and CMAKE_END_TEMP_FILE to "".<br />
<br />
On Makefile generators, there is a shortcut by setting Makefile variable VERBOSE to 1. For example on UNIX:<br />
<br />
make VERBOSE=1<br />
<br />
and Windows:<br />
nmake /S force silent mode, overrides (CMAKE_VERBOSE_MAKFILE)<br />
<br />
=== Is there a way to skip checking of dependent libraries when compiling? ===<br />
<br />
'''Using the Makefile Generator'''<br />
<br />
When using the Makefile generator under *nix you can append "/fast" to your target name. For example:<br />
<br />
make target_name/fast<br />
<br />
Under Windows use a backslash instead:<br />
<br />
make target_name\fast<br />
<br />
'''Using Visual Studio >= 7.1'''<br />
<br />
If you have Visual Studio .NET 7.1 or greater you can use the native option to right click on a project and choose to build just that project.<br />
<br />
'''Using Visual Studio <= 7.0'''<br />
<br />
CMake doesn't try to compile all dependent libraries when you compile a library but it will do so for binary targets. You can't avoid this however you can take advantage of CTRL+F7 to manually compile a source file for the affected target and then relink the target by right clicking on it and choosing Link. You'll have to ensure that all dependent libraries are made up-to-date however or suffer through Visual's slow check.<br />
<br />
=== I set a cmake variable in my environment, but it didn't change anything. Why? ===<br />
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.<br />
<br />
=== I change CMAKE_C_COMPILER in the GUI but it changes back on the next configure step. Why? ===<br />
Once a build tree is created with a given compiler it cannot be changed. There are a variety of implementation reasons for this policy. In order to choose a different compiler create a new build tree and set the CC and CXX environment variables to the compiler you want before running CMake.<br />
<br />
NOTE: While I don't know what the preferred method of doing it is, I do know that the advice above (to set CC and CXX env vars) is in direct conflict with advice somewhere else that says not to use env vars to control CMAKE... Hopefully someone that knows a little more than I will fix this discrepancy.<br />
<br />
NOTE2: You could pass in e.g. <tt>-D CMAKE_C_COMPILER_INIT:STRING=mycc</tt> on the command line, or set the same variable inside a listfile (before any PROJECT() or ENABLE_LANGUAGE() command). Might that be what you're getting at?<br />
<br />
=== In CCMake, typing full paths is tedious. Is there a better way? ===<br />
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.<br />
<br />
For example:<br />
<br />
/usr/loc<TAB><br />
<br />
will expand to<br />
<br />
/usr/local/<br />
<br />
<br />
<br />
== Out-of-source build trees ==<br />
<br />
=== What is an "out-of-source" build? ===<br />
When your build generates files, they have to go somewhere. An in-source build puts them in your source tree. An out-of-source build puts them in a completely separate directory, so that your source tree is unchanged.<br />
<br />
In the first example, an in-place build is performed, i.e., the binaries are placed in the same directory as the source code.<br />
<br />
cd Hello<br />
ccmake .<br />
make<br />
<br />
In the second example, an out-of-place build is performed, i.e., the source code, libraries, and executables are produced in a directory separate from the source code directory(ies).<br />
<br />
mkdir HelloBuild<br />
cd HelloBuild<br />
ccmake ../Hello<br />
make<br />
<br />
Out-of-source builds are recommended, as you can build multiple variants in separate directories, e.g., HelloBuildDebug, HelloBuildRelease.<br />
<br />
Note: Before performing an out-of-source build ensure that any possible CMake generated in-source build information is removed from the source directory, e.g., CMakeFiles directory, and CMakeCache.txt.<br />
<br />
=== I run an out-of-source build but CMake generates in-source anyway. Why? ===<br />
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.<br />
<br />
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).<br />
<br />
=== Why does CMake use full paths, or can I copy my build tree? ===<br />
CMake uses full paths because:<br />
<br />
# configured header files may have full paths in them, and moving those files without re-configuring would cause upredictable behavior.<br />
# because cmake supports out of source builds, if custom commands used relative paths to the source tree, they would not work when they are run in the build tree because the current directory would be incorrect.<br />
# on Unix systems rpaths might be 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.<br />
<br />
Can the build tree be copied or moved?<br />
<br />
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 and rerun. Often when people want to move a binary tree it is so that they can distribute it to other users who may not have cmake in which case this would not work even if cmake would detect the move.<br />
<br />
The workaround is to create a new build tree without copying or moving the old one.<br />
<br />
<br />
=== CMake does not generate a "make distclean" target. Why? ===<br />
Some build trees created with GNU autotools have a "make distclean" target that cleans the build and also removes Makefiles and other parts of the generated build system. CMake does not generate a "make distclean" target because CMakeLists.txt files can run scripts and arbitrary commands; CMake has no way of tracking 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. (CMake does generate a "make clean" target to remove files generated by the compiler and linker.)<br />
<br />
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. Because CMake does not change the source tree, there is no need for a distclean target. One can start a fresh build by deleting the build tree or creating a separate build tree.<br />
<br />
(If a CMakeLists.txt uses ADD_CUSTOM_COMMAND to generate source files in the source tree, not the build tree, then in CMake 2.2 or higher "make clean" will remove them. See next question.)<br />
<br />
=== Running "make clean" does not remove custom command outputs. Why? ===<br />
In CMake 2.2 and higher custom command outputs should be removed by make clean. Make sure you are using at least this version. Prior to CMake 2.2 custom command outputs were not automatically added to the list of files to clean. In CMake 2.0 the 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.<br />
<br />
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 to clean away files that differ between builds.<br />
<br />
<br />
== Writing CMakeLists.txt ==<br />
<br />
=== How to have backward and forward compatibility? ===<br />
<br />
As of CMake 2.6 we employ a "Policy" mechanism to provide backwards compatibility.<br />
The basic requirement for projects is to include one line at the top of the highest CMakeLists.txt file:<br />
<br />
cmake_minimum_required(VERSION 2.6) # or other version<br />
<br />
This tells versions of CMake older than that specified that they are too old to build the project.<br />
They will report this information to the user.<br />
It also tells versions of CMake newer than that specified that the project may not be aware of policies introduced in later versions, which enables additional compatibility.<br />
For futher documentation, see<br />
<br />
* [[CMake_Policies|CMake Policy Mechanism]]<br />
* [http://www.cmake.org/cmake/help/cmake2.6docs.html#command:cmake_policy cmake_policy() command]<br />
* [http://www.cmake.org/cmake/help/cmake2.6docs.html#section_Policies CMake 2.6 Policies]<br />
<br />
=== How do I get the current source or binary directory? ===<br />
The variable CMAKE_CURRENT_SOURCE_DIR contains the absolute path to your current source directory, while CMAKE_CURRENT_BINARY_DIR points to the equivalent binary directory.<br />
<br />
=== Why are my CMake variables not updated in the GUI after a SET command? ===<br />
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.<br />
<br />
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:<br />
<br />
SET(BUILD_SHARED_LIBS ON)<br />
<br />
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.<br />
<br />
You can use the CACHE and FORCE options on the SET command to change variables in a way that will be reflected in the GUI. Run<br />
<br />
cmake --help-command SET<br />
<br />
to see full instructions for the command.<br />
<br />
<br />
=== How can I change the default build mode and see it reflected in the GUI? ===<br />
Adapt the following commands in your CMakeList.txt (this example sets the Release<br />
With Debug Information mode):<br />
<pre><br />
IF(NOT CMAKE_BUILD_TYPE)<br />
SET(CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING<br />
"Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel."<br />
FORCE)<br />
ENDIF(NOT CMAKE_BUILD_TYPE)<br />
</pre><br />
<br />
=== How do I generate an executable, then use the executable to generate a file? ===<br />
<br />
Create the generator executable by just adding a target:<br />
<br />
ADD_EXECUTABLE(generate generate.c)<br />
<br />
The rest of the process is simpler in CMake 2.6 and above than in previous versions.<br />
<br />
Use <code>ADD_CUSTOM_COMMAND</code> to specify a custom build rule for the file.<br />
(In this example we assume <code>generate</code> accpets the input and output files as arguments.)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT someoutput.txt<br />
COMMAND generate ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
DEPENDS generate ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt<br />
)<br />
<br />
This tells CMake how to build the file but does not actually add a rule to the build system.<br />
Another target must require it.<br />
One may create a custom target explicitly for this rule:<br />
<br />
ADD_CUSTOM_TARGET(driver ALL DEPENDS someoutput.txt)<br />
<br />
or the file may be added as part of some other target:<br />
<br />
ADD_EXECUTABLE(product product.c someoutput.txt)<br />
<br />
<font color=#555555><br />
In CMake 2.4 and below the <code>generate</code> target may not be specified directly in the <code>COMMAND</code> option of <code>add_custom_command</code><br />
(but it can still be used in the <code>DEPENDS</code> option as of CMake 2.4).<br />
Instead use GET_TARGET_PROPERTY to obtain the location of the generated executable.<br />
Additionally, the output must always be specified by full path.<br />
<br />
GET_TARGET_PROPERTY(GENERATE_EXE generate LOCATION)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
COMMAND ${GENERATE_EXE} ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
DEPENDS generate<br />
)<br />
</font><br />
<br />
=== How can I generate a source file during the build? ===<br />
The ADD_CUSTOM_COMMAND command lets you generate a source file that you can then include in another target. For example:<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
COMMAND ${CMAKE_COMMAND} copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.c ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.c<br />
)<br />
ADD_EXECUTABLE(foo foo.c)<br />
<br />
This will create an executable by copying bar.c to foo.c and then compiling foo.c to produce foo. CMake allows you to put generate source files in the current source or binary directory, so we were careful to output foo.c to the current binary directory. When we add foo.c to foo, CMake will look in either directory for it. Even if foo.c does not yet exist, CMake is smart enough to notice that a custom command creates it. (For the file named as the OUTPUT, CMake has its GENERATED source file property set to true.)<br />
<br />
You can also use ADD_CUSTOM_COMMAND when the<br />
[[CMake_FAQ#How_do_I_generate_an_executable.2C_then_use_the_executable_to_generate_a_file.3F|generator command is another executable in the same project]].<br />
<br />
Sometimes, the program doing the generation may generate multiple output files that each need to be part of the build. CMake 2.4 or higher supports having multiple files listed in the OUTPUT section. 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:<br />
<br />
PROJECT(FOO)<br />
# make sure cmake addes the binary directory for the project to the include path<br />
INCLUDE_DIRECTORIES(${FOO_BINARY_DIR})<br />
# add the executable that will do the generation<br />
ADD_EXECUTABLE(my_generator my_generator.cxx)<br />
GET_TARGET_PROPERTY(MY_GENERATOR_EXE my_generator LOCATION)<br />
# add the custom command that will generate all three files<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${FOO_BINARY_DIR}/output1.cpp ${FOO_BINARY_DIR}/output2.h ${FOO_BINARY_DIR}/output3.cpp<br />
COMMAND ${MY_GENERATOR_EXE} ${FOO_BINARY_DIR} ${FOO_SOURCE_DIR}/input.txt<br />
DEPENDS my_generator<br />
MAIN_DEPENDENCY ${FOO_SOURCE_DIR}/input.txt<br />
)<br />
# now create an executable using the generated files<br />
ADD_EXECUTABLE(generated<br />
${FOO_BINARY_DIR}/output1.cpp<br />
${FOO_BINARY_DIR}/output2.h<br />
${FOO_BINARY_DIR}/output3.cpp)<br />
<br />
CMake 2.4 allows you to generate a header file. Because generated headers often cause unnecessary rebuilds, you should try to avoid them; consider using the CONFIGURE_FILE command to prepare the header at CMake time. If you must generate a header file, use code like this:<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.h<br />
COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.h ${CMAKE_CURRENT_BINARY_DIR}/foo.h<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.h<br />
)<br />
ADD_EXECUTABLE(foo foo.c ${CMAKE_CURRENT_BINARY_DIR}/foo.h)<br />
<br />
This is like the first example above, except that it generates a header instead of a C file. The header might not exist when the build system scans foo.c's dependencies, so there is no way for CMake to know that this target requires foo.h unless we can tell it that foo.h may exist in the future. We give CMake this knowledge by listing the generated header file in the set of source files for the target. (This requires CMake 2.4. Previous versions of CMake required use of the OBJECT_DEPENDS source file property.)<br />
<br />
=== How can I add a dependency to a source file which is generated in a subdirectory? ===<br />
<br />
Rules created with <code>ADD_CUSTOM_COMMAND</code> as [[CMake_FAQ#How_can_I_generate_a_source_file_during_the_build.3F|above]] have scope only in the directory in which they are specified.<br />
If the generated file is needed in another directory, a target-level dependency needs to be added.<br />
Create a target in the subdirectory with the custom rule in order to drive it:<br />
<br />
# subdir/CMakeLists.txt<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
COMMAND ${CMAKE_COMMAND} copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.c ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.c<br />
)<br />
ADD_CUSTOM_TARGET(generate_foo DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/foo.c)<br />
<br />
Now other targets can depend on the target from the subdirectory:<br />
<br />
# CMakeLists.txt<br />
ADD_SUBDIRECTORY(subdir)<br />
# Create the executable.<br />
ADD_EXECUTABLE(generated ${CMAKE_CURRENT_BINARY_DIR}/subdir/foo.c)<br />
# Tell CMake the source won't be available until build time.<br />
SET_SOURCE_FILES_PROPERTIES(${CMAKE_CURRENT_BINARY_DIR}/subdir/foo.c PROPERTIES GENERATED 1)<br />
# Make sure the source is generated before the executable builds.<br />
ADD_DEPENDENCIES(generated generate_foo)<br />
<br />
=== I use EXEC_PROGRAM but the result is not set in subdirectories. Why? ===<br />
<br />
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 was fixed in CMake 2.2, but for older versions you will have to cache the result:<br />
<br />
<pre><br />
EXEC_PROGRAM(my-program OUTPUT_VARIABLE MY_OUTPUT)<br />
SET(MY_OUTPUT "${MY_OUTPUT}" CACHE INTERNAL "")<br />
</pre><br />
<br />
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.<br />
<br />
=== How can I get or set environment variables? ===<br />
<br />
CMake names environment variables using an ENV prefix and surrounding the names in curly braces. Here is an example:<br />
<br />
<pre><br />
MESSAGE("$ENV{PATH}")<br />
</pre><br />
<br />
Reading variables will work in any version of CMake. Writing to them works in CMake 2.2 and higher using the following syntax:<br />
<br />
<pre><br />
SET(ENV{HELLO} "World")<br />
</pre><br />
<br />
Note that there is currently no way to tell apart an empty environment variable value from a variable that is not set at all.<br />
<br />
One should avoid using environment variables for controlling the flow of CMake code (such as in IF commands). The build system generated by CMake may re-run CMake automatically when CMakeLists.txt files change. The environment in which this is executed is controlled by the build system and may not match that in which CMake was originally run. If you want to control build settings on the CMake command line, you need to use cache variables set with the -D option. The settings will be saved in CMakeCache.txt so that they don't have to be repeated every time CMake is run on the same build tree.<br />
<br />
Also, environment variables SET in the CMakeLists.txt ''only'' take effect for cmake itself, so you cannot use this method to set an environment variable that a custom command might need.<br />
<br />
=== Why do I have unwanted semicolons ; in my compiler flags? ===<br />
CMake has a list data type. A list is stored as a string of semicolon-separated list elements. Whitespace separated arguments to a SET statement are interpreted as list elements. For instance, SET(var a b c d e) will give "var" a value of a;b;c;d;e and this list can be used by other CMake commands. However, if you pass ${var} to a non-CMake external tool, such as a compiler's command line, you are passing a;b;c;d;e which is not what you want. Instead you either need to pass "${var}", so that the list will be converted to a whitespace-separated string, or you need to SET(var "a b c d e") in the 1st place so that you're working with a string, not a list.<br />
<br />
=== How can I get quoting and escapes to work properly? ===<br />
If you want to escape a character in CMake, you use "\", like in C code. For example, if you wanted to have a quote embedded in a string you would do this: "\"". However, each level of CMake that processes your code will need one level of escaping to work. So, if you configure a file that is read by cmake or cpack and you want to do the same thing, you would do "\\\"". You would still need to escape the " for the first cmake that processes the string. However, this time, you would want to also escape a '\' as well. This would leave the next level of processing with "\"". Also, for custom commands that may get passed to a shell, it maybe required to do escaping for that shell.<br />
<br />
=== Isn't the "Expression" in the "ELSE (Expression)" confusing? ===<br />
Traditional CMakeLists.txt files prior to 2.6.0, require the following syntax. In the IF syntax, the ELSE section requires the same (Expression) as the IF section. This sometimes can make the script kind of hard to follow, take the short example below:<br />
<br />
IF(WIN32)<br />
...do something...<br />
ELSE(WIN32)<br />
...do something else...<br />
ENDIF(WIN32)<br />
<br />
You might think that the ELSE section, here containing "...do something else...", is for the WIN32 portion of the script. That is not so! It is actually handling the NOT WIN32 section.<br />
<br />
As of CMake 2.6.0 the ELSE() and ENDIF() constructs can be empty. The same is true for closing constructs on ENDMACRO(), ENDFUNCTION(), and ENDFOREACH(). If you require 2.4.x compatibility, you can enable the CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS option on CMake 2.4.3 or greater. This option is superfluous on CMake 2.6.0 or greater.<br />
<br />
SET(CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS true)<br />
<br />
IF(WIN32)<br />
...do something...<br />
ELSEIF(APPLE)<br />
...do something else...<br />
ELSE()<br />
...do something else...<br />
ENDIF()<br />
<br />
=== Which regular expressions are supported by CMake? ===<br />
When using MATCHES or MATCHALL in an IF command, or using any of the STRING(REGEX ...) commands, CMake expects regular expressions, not globs (wild cards). CMake uses the same regular expression engine above all platforms. Here are the meanings of the metacharacters:<br />
<br />
^ Matches at beginning of a line<br />
$ Matches at end of a line<br />
. Matches any single character<br />
[ ] Matches any character(s) inside the brackets<br />
[^ ] Matches any character(s) not inside the brackets<br />
- Matches any character in range on either side of a dash<br />
| Matches a pattern on either side of the |<br />
* Matches preceding pattern zero or more times<br />
+ Matches preceding pattern one or more times<br />
? Matches preceding pattern zero or once only<br />
() Saves a matched expression and uses it in a later match<br />
<br />
Example: "[-][L]([^ ;])+" matches all strings beginning with -L and ending with a space or a semicolon, the usual linkdirs under Linux.<br />
<br />
Here is how to catch a part of a string. The variable test is filled with some content, and then we want to catch the "me":<br />
<br />
SET(test "hello world ! catch: me if you can")<br />
STRING(REGEX REPLACE ".*catch: ([^ ]+).*" "\\1" result "${test}" )<br />
MESSAGE(STATUS "result= ${result}")<br />
<br />
This is slightly tricky. The part inside the brackets is available in \\1 . CMake will copy the variable test to the variable result, but then it will replace everything that the regular expression matches with \\1. This means the first regular expression has to match the whole string and the part we want to catch has to be put in parens.<br />
<br />
-- result= me<br />
<br />
For those of you who know Perl, the equivalent Perl code could be:<br />
<br />
$test = "hello world ! catch: me if you can";<br />
$result = $test;<br />
$result =~ s/.*catch: ([^ ]+).*/$1/;<br />
print "-- result= $result\n";<br />
<br />
There are other ways to do this in Perl, but this is how we do it in CMake because \\1 does not become a variable like $1 does in perl, so there is no SET(result ${\\1}) in CMake.<br />
<br />
<br />
=== How to convert a semicolon separated list to a whitespace separated string? ===<br />
<br />
set(foo<br />
abc.c<br />
abc.b<br />
abc.a<br />
)<br />
<br />
foreach(arg ${foo})<br />
set(bar "${bar} ${arg}")<br />
endforeach(arg ${foo})<br />
<br />
message("foo: ${foo}")<br />
message("bar: ${bar}")<br />
<br />
=== How can I build multiple modes without switching ? ===<br />
To build multiple modes (e.g. Debug and Release) in one shot without constantly running cmake -DCMAKE_BUILD_TYPE=Debug and cmake -DCMAKE_BUILD_TYPE=Release in source tree create a directory for builds eg.:<br />
<br />
<pre><br />
Project-directory/<br />
/Build<br />
</pre><br />
<br />
Inside you can place as many target directories for out-of-source build modes as you want, e.g.:<br />
<br />
<pre><br />
Project-directory/<br />
/Build<br />
/Debug<br />
/Release<br />
</pre><br />
<br />
In each of these directories issue a command (assuming that you have CMakeLists.txt directly in Project-directory)<br />
<br />
<pre><br />
cmake -DCMAKE_BUILD_TYPE=type_of_build ../../<br />
</pre><br />
<br />
to create a cmake cache configured for requested build type.<br />
<br />
Now you can make each build just by entering appropriate directory and executing a make command.<br />
<br />
=== How can I extend the build modes with a custom made one ? ===<br />
The following code snipet (taken from a CMakeLists.txt) adds a Maintainer mode:<br />
<pre><br />
SET( CMAKE_CXX_FLAGS_MAINTAINER "-Wall -Wabi" CACHE STRING<br />
"Flags used by the C++ compiler during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_C_FLAGS_MAINTAINER "-Wall -pedantic" CACHE STRING<br />
"Flags used by the C compiler during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_EXE_LINKER_FLAGS_MAINTAINER<br />
"-Wl,--warn-unresolved-symbols,--warn-once" CACHE STRING<br />
"Flags used for linking binaries during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_SHARED_LINKER_FLAGS_MAINTAINER<br />
"-Wl,--warn-unresolved-symbols,--warn-once" CACHE STRING<br />
"Flags used by the shared libraries linker during maintainer builds."<br />
FORCE )<br />
MARK_AS_ADVANCED(<br />
CMAKE_CXX_FLAGS_MAINTAINER<br />
CMAKE_C_FLAGS_MAINTAINER<br />
CMAKE_EXE_LINKER_FLAGS_MAINTAINER<br />
CMAKE_SHARED_LINKER_FLAGS_MAINTAINER )<br />
# Update the documentation string of CMAKE_BUILD_TYPE for GUIs<br />
SET( CMAKE_BUILD_TYPE "" CACHE STRING<br />
"Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel Maintainer."<br />
FORCE )<br />
</pre><br />
Notes: this will only work with gcc (since the flags would need to be<br />
declined with the possible compilers). Additionaly this will override<br />
a CMAKE_BUILD_TYPE previously set in the CMakeLists.txt...<br />
<br />
== Writing FindXXX.cmake files ==<br />
<br />
=== What are the rules to write a FindXXX.cmake file? ===<br />
<br />
Let's follow the instructions and the advices in the <br />
Modules/readme.txt [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/readme.txt?root=CMake&view=markup]<br />
file located in the CVS repository.<br />
<br />
=== Why does find_library look in system directories before its PATHS option? ===<br />
<br />
The code in question is often of the form<br />
<br />
find_library(FOO_LIBRARY NAMES foo PATHS /opt/foo/lib)<br />
<br />
CMake will find "<code>/usr/lib/libfoo.so</code>" instead of "<code>/opt/foo/lib/libfoo.so</code>" if both exist.<br />
The reason is that /opt/foo/lib is a <i>hard-coded guess</i> of the location.<br />
The documentation of <code>[http://www.cmake.org/cmake/help/cmake2.6docs.html#command:find_library find_library]</code> specifies the search order.<br />
User, project, and system configuration variables are always more local than hard-coded guesses and should override them, so<br />
the PATHS option is used last.<br />
<br />
Some find-modules compute probable locations based on other information <i>available from the system</i> such as a project-specific environment variable.<br />
The HINTS option (CMake 2.6 and higher) takes precedence over system directories specifically for this case:<br />
<br />
file(TO_CMAKE_PATH "$ENV{FOO_LIB_DIR}" FOO_LIB_DIR)<br />
find_library(FOO_LIBRARY NAMES foo HINTS ${FOO_LIB_DIR})<br />
<br />
CMake will find "<code>$ENV{FOO_LIB_DIR}/libfoo.so</code>" before "<code>/usr/lib/libfoo.so</code>".<br />
<br />
== Finding and using external packages ==<br />
<br />
=== How do I use CMake to generate SWIG wrapper libraries? ===<br />
<br />
CMake version 2 includes a module that supports the generation of SWIG wrapper libraries. The SWIG package defines the following macros: SWIG_ADD_MODULE and SWIG_LINK_LIBRARIES.<br />
<br />
<pre><br />
# This example shows how to use python<br />
# Currently these languages have been tested:<br />
# perl tcl ruby php4 pike<br />
<br />
FIND_PACKAGE(SWIG REQUIRED)<br />
INCLUDE(${SWIG_USE_FILE})<br />
<br />
FIND_PACKAGE(PythonLibs)<br />
INCLUDE_DIRECTORIES(${PYTHON_INCLUDE_PATH})<br />
<br />
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})<br />
<br />
SET(CMAKE_SWIG_FLAGS "")<br />
<br />
SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES CPLUSPLUS ON)<br />
SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES SWIG_FLAGS "-includeall")<br />
SWIG_ADD_MODULE(example python<br />
example.i example.cxx)<br />
SWIG_LINK_LIBRARIES(example ${PYTHON_LIBRARIES})<br />
<br />
</pre><br />
<br />
<pre><br />
# This example shows how to use tcl<br />
PROJECT(TCL_WRAP)<br />
SET ( MODULE_NAME project )<br />
SET ( INTERFACE_FILES project.i)<br />
SET ( SRC_FILES Vertex.h Vertex.cxx Shapes.h Shapes.cxx )<br />
<br />
FIND_PACKAGE(SWIG REQUIRED)<br />
INCLUDE(${SWIG_USE_FILE})<br />
<br />
# Look for TCL<br />
INCLUDE_DIRECTORIES(${TCL_INCLUDE_PATH})<br />
<br />
FIND_LIBRARY(TCL_LIBRARY NAMES tcl tcl84 tcl83 tcl82 tcl80<br />
PATHS /usr/lib /usr/local/lib)<br />
IF (TCL_LIBRARY)<br />
TARGET_ADD_LIBRARY (${MODULE_NAME} TCL_LIBRARY)<br />
ENDIF (TCL_LIBRARY)<br />
<br />
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})<br />
<br />
SET(CMAKE_SWIG_FLAGS "-c++")<br />
<br />
SET_SOURCE_FILES_PROPERTIES(${INTERFACE_FILES} PROPERTIES CPLUSPLUS ON)<br />
SET_SOURCE_FILES_PROPERTIES(${INTERFACE_FILES} PROPERTIES CMAKE_SWIG_FLAGS "-includeall")<br />
SWIG_ADD_MODULE(${MODULE_NAME} tcl ${INTERFACE_FILES} ${SRC_FILES})<br />
SWIG_LINK_LIBRARIES(${MODULE_NAME} ${TCL_LIBRARIES})<br />
</pre><br />
<br />
=== How do I use CMake to build LaTeX documents? ===<br />
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.<br />
<br />
PROJECT(Document)<br />
IF(LATEX_COMPILE)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${Document_BINARY_DIR}/TDocument.dvi<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.tex<br />
COMMAND ${LATEX_COMPILE} <br />
ARGS ${Document_SOURCE_DIR}/TDocument.tex <br />
)<br />
ENDIF(LATEX_COMPILE)<br />
<br />
IF(DVIPDF_COMPILE)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${Document_BINARY_DIR}/TDocument.pdf<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.dvi <br />
COMMAND ${DVIPDF_COMPILE}<br />
ARGS ${Document_SOURCE_DIR}/TDocument.dvi<br />
)<br />
ENDIF(DVIPDF_COMPILE)<br />
<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.pdf<br />
)<br />
<br />
The following uses commands in CMake version 2.0 and later<br />
<br />
PROJECT(Document)<br />
# <br />
# Find LaTeX<br />
#<br />
FIND_PACKAGE(LATEX)<br />
<br />
IF(LATEX_COMPILER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.dvi<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS ${Document_SOURCE_DIR}/TDocument.tex<br />
DEPENDS ${Document_SOURCE_DIR}/TDocument.tex<br />
COMMENT "Tex2dvi"<br />
)<br />
<br />
IF(DVIPS_CONVERTER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.ps<br />
COMMAND ${DVIPS_CONVERTER}<br />
ARGS ${Document_BINARY_DIR}/TDocument.dvi<br />
-o ${Document_BINARY_DIR}/TDocument.ps<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.dvi<br />
COMMENT "dvi2ps"<br />
)<br />
<br />
IF(PS2PDF_CONVERTER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.pdf<br />
COMMAND ${PS2PDF_CONVERTER}<br />
ARGS ${Document_BINARY_DIR}/TDocument.ps<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.ps<br />
COMMENT "ps2pdf"<br />
)<br />
<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.pdf<br />
)<br />
ENDIF(PS2PDF_CONVERTER)<br />
ENDIF(DVIPS_CONVERTER)<br />
ENDIF(LATEX_COMPILER)<br />
<br />
=== How do I get LaTeX references to be correct? ===<br />
When your latex document contains references (e.g. \ref{...} command) you get to run two passes of latex. In the<br />
most general case, i.e. when additionally your document uses a bibtex bibliography, you shall need three<br />
passes of latex (and one pass of bibtex):<br />
# latex (first pass: for bibtex to have an .aux file)<br />
# bibtex (for generating the .bbl file)<br />
# latex (second pass)<br />
# latex (third pass)<br />
<br />
The following code snippet illustrates how you can "pervert" the bibtex and latex generated<br />
auxilary files (.aux, .log, .dvi, .bbl...) to create an "artificial" set of CMake dependencies.<br />
The side-effect of those dependencies should hopefully be the above described sequence of calls<br />
to latex and bibtex<br />
<pre><br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.aux<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/UsersManual.tex<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (first pass)"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.aux<br />
COMMAND ${BIBTEX_COMPILER}<br />
ARGS -terse ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Bibtex"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.dvi<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (second pass)"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.log<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
${CMAKE_CURRENT_BINARY_DIR}/UsersManual.dvi<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (third pass)"<br />
)<br />
# Eventually trigger the whole process<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.log<br />
)<br />
</pre><br />
<br />
=== How can I set TEXINPUTS for a LaTeX compilation? ===<br />
First note that most often you can avoid using TEXINPUTS by copying all the necessary files (.tex source file and<br />
included graphic files e.g. .eps files) from your PROJECT_SOURCE_DIR hirarchy to your PROJECT_BINARY_DIR subdir<br />
[refer to CONFIGURE_FILE with the COPYONLY flag set for copying files]. Since by default latex uses the current working directory as value for TEXINPUTS you should be all set. As expected, this trick is quick AND dirty since your<br />
concerned PROJECT_BINARY_DIR subdir now contains files that are NOT generated by CMake (in the sense that those<br />
files are not the result of a system command but were merely duplicated)... <br />
<br />
If you consider it is cleaner or easier to define a TEXINPUTS environment variable [the latex command probably<br />
misses a -I flag] you can find an example in the InsightDocuments cvs archive (refer to the section "cvs access"<br />
near the bottom of Kitware's ITK download page) or use google with keywords "ITK_TEXINPUTS CONFIGURE_FILE".<br />
Look at InsightDocuments/CourseWare/Training/Vis2003/Latex/CMakeLists.txt and search for e.g. "LaTeXWrapper.sh.in".<br />
<br />
Roughly the mechanism goes:<br />
* SET ITK_TEXINPUTS with the desired TEXINPUTS<br />
* CONFIGURE_FILE "InsightDocuments/CourseWare/Training/Vis2003/LaTeXWrapper.sh.in" which generates an sh shell script setting the shell variable TEXINPUTS prior to running the latex command<br />
* use ADD_CUSTOM_COMMAND to invoke this shell script<br />
This very example is Win32 portable (except that LaTeXWrapper.bat.in generates a .bat shell script)<br />
<br />
== Library questions ==<br />
<br />
=== Can I build both shared and static libraries with one ADD_LIBRARY command? ===<br />
<br />
No. Each library you build must have a unique target name, i.e. the "libname" field of the ADD_LIBRARY command. That way, CMake can track dependencies separately for each library. Libraries can have the same OUTPUT_NAME, see the SET_TARGET_PROPERTIES command, but this is not the default.<br />
<br />
=== Does that mean I have to build all my library objects twice, once for shared and once for static?! I don't like that! ===<br />
<br />
In practice, most libraries have different defines and compiler flags for the shared vs. static cases. So you would have to build all your library objects twice anyways. However, if you happen to have '''''exactly''''' the same defines and compiler flags for the shared vs. static cases...<br />
<br />
...if you're using Linux and a GCC-style linker, you could do the following. Note that for this to work correctly on linux, the zzSTATIC source files should have been compiled with "-fPIC" to ensure they will work in a shared library.<br />
<br />
IF(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_COMPILER_IS_GNUCC)<br />
ADD_LIBRARY(zzSTATIC STATIC -fPIC)<br />
ADD_LIBRARY(zzDYNAMIC SHARED)<br />
TARGET_LINK_LIBRARIES(zzDYNAMIC -Wl,-whole-archive zzSTATIC -Wl,-no-whole-archive)<br />
ENDIF(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_COMPILER_IS_GNUCC)<br />
<br />
...if you want a cross-platform approach that works on all compilers, not just GCC or Linux, you could extract the locations of previously built object files and insert them directly into the libraries that need them. This is documented in [http://www.cmake.org/Bug/view.php?id=5155 CMake Feature Request #5155: standard way to locate object files]. Unfortunately this approach relies on CMake's internal implementation, and that implementation could change in the future, breaking your code.<br />
<br />
=== How do I make my shared and static libraries have the same root name, but different suffixes? ===<br />
Set the OUTPUT_NAME of your shared and static libraries to the same thing.<br />
<br />
ADD_LIBRARY(foo SHARED ${foo_sources})<br />
ADD_LIBRARY(foo-static STATIC ${foo_sources})<br />
// The library target "foo" already has a default OUTPUT_NAME of "foo", so we don't need to change it.<br />
// The library target "foo-static" has a default OUTPUT_NAME of "foo-static", so change it.<br />
SET_TARGET_PROPERTIES(foo-static PROPERTIES OUTPUT_NAME "foo")<br />
<br />
If you are building your shared and static libraries in the same directory, you will also need the following to keep your shared and static libraries from clobbering each other during the build.<br />
<br />
SET_TARGET_PROPERTIES(foo PROPERTIES CLEAN_DIRECT_OUTPUT 1)<br />
SET_TARGET_PROPERTIES(foo-static PROPERTIES CLEAN_DIRECT_OUTPUT 1)<br />
<br />
=== How do I rename a library after it has already been built? ===<br />
You don't rename it. It's been built! Its name is whatever CMakeLists.txt says it's supposed to be.<br />
<br />
Perhaps you want to copy the library to a different name. But, are you sure that's what you want to do? You could just change the name in your ADD_LIBRARY command or change its OUTPUT_NAME property using SET_TARGET_PROPERTY(). If you really really want to copy the library to a different name, try:<br />
<br />
GET_TARGET_PROPERTY(LIB_NAME Foo LOCATION)<br />
GET_TARGET_PROPERTY(Bar_prefix Foo PREFIX)<br />
GET_TARGET_PROPERTY(Bar_suffix Foo SUFFIX)<br />
SET(NEW_LIB_NAME ${Bar_prefix}Bar${Bar_suffix})<br />
<br />
ADD_CUSTOM_COMMAND(<br />
TARGET Foo<br />
POST_BUILD<br />
COMMAND ${CMAKE_COMMAND} -E copy ${LIB_NAME} ${NEW_LIB_NAME}<br />
)<br />
<br />
On Windows you may also want to copy the .dll import lib, using the same approach as above, but with IMPORT_PREFIX and IMPORT_SUFFIX. ''Problem: LOCATION only refers to 1 file, the .dll. What is a simple way to get the location of the import lib? Could provide a complicated way, but that's annoying.''<br />
<br />
=== Does CMake support "convenience" libraries? ===<br />
No. CMake does not currently support convenience libraries. A "convenience" library, as GNU libtool calls it, is an archive of objects to be mixed into other libraries. Other libraries "link" to the convenience library, but the convenience library does not export any symbols; GNU libtool never installs the convenience library; no programs ever link to the convenience library.<br />
<br />
This does '''not''' mean that a project using convenience libraries cannot be converted to CMake. Instead the source files may be listed in each target that needs them. They will be built for each target separately using all the preprocessor definitions and flags configured for that target.<br />
<br />
=== Why are libraries linked to my shared library included when something links to it? ===<br />
This question arises when one has a library B which links to some library A. When a third target, say C, links to B, CMake will automatically include C to A also. When the libraries are static, then this is always necessary. When the libraries are shared, this is the default behavior provided by CMake. CMake 2.6 and above provide the target property "LINK_INTERFACE_LIBRARIES" (http://www.cmake.org/HTML/cmake-2.6.html#prop_tgt:LINK_INTERFACE_LIBRARIES) to specify the libraries that should be transitively included in the link by CMake. CMake 2.4 and below do not support the property.<br />
<br />
=== CMake dependency scanner ===<br />
<br />
CMake does not preprocess source files while scanning dependencies. Code like<br />
<pre><br />
#if 0<br />
# include "bla.h"<br />
#endif<br />
</pre><br />
will result in a dependency on "bla.h". This sometimes leads to source files recompiling unnecessarily but will not break the build.<br />
<br />
== Installation questions ==<br />
<br />
=== Does CMake's "make install" support DESTDIR? ===<br />
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<br />
<br />
make install DESTDIR="/home/me/mydist"<br />
<br />
will cause the installation to copy files to "/home/me/mydist/${CMAKE_INSTALL_PREFIX}/...". This is useful for package maintainers.<br />
<br />
=== Can I do "make uninstall" with CMake?===<br />
By default, CMake does not provide the "make uninstall" target, so you cannot do this. We do not want "make uninstall" to remove useful files from the system.<br />
<br />
If you want an "uninstall" target in your project, then nobody prevents you from providing one. You need to delete the files listed in install_manifest.txt file. Here is how to do it. First create file cmake_uninstall.cmake.in in the top-level directory of the project:<br />
<br />
<pre><br />
IF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")<br />
MESSAGE(FATAL_ERROR "Cannot find install manifest: \"@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt\"")<br />
ENDIF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")<br />
<br />
FILE(READ "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt" files)<br />
STRING(REGEX REPLACE "\n" ";" files "${files}")<br />
FOREACH(file ${files})<br />
MESSAGE(STATUS "Uninstalling \"$ENV{DESTDIR}${file}\"")<br />
IF(EXISTS "$ENV{DESTDIR}${file}")<br />
EXEC_PROGRAM(<br />
"@CMAKE_COMMAND@" ARGS "-E remove \"$ENV{DESTDIR}${file}\""<br />
OUTPUT_VARIABLE rm_out<br />
RETURN_VALUE rm_retval<br />
)<br />
IF(NOT "${rm_retval}" STREQUAL 0)<br />
MESSAGE(FATAL_ERROR "Problem when removing \"$ENV{DESTDIR}${file}\"")<br />
ENDIF(NOT "${rm_retval}" STREQUAL 0)<br />
ELSE(EXISTS "$ENV{DESTDIR}${file}")<br />
MESSAGE(STATUS "File \"$ENV{DESTDIR}${file}\" does not exist.")<br />
ENDIF(EXISTS "$ENV{DESTDIR}${file}")<br />
ENDFOREACH(file)<br />
</pre><br />
<br />
Then in the top-level CMakeLists.txt add the following logic:<br />
<br />
<pre><br />
CONFIGURE_FILE(<br />
"${CMAKE_CURRENT_SOURCE_DIR}/cmake_uninstall.cmake.in"<br />
"${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake"<br />
IMMEDIATE @ONLY)<br />
<br />
ADD_CUSTOM_TARGET(uninstall<br />
"${CMAKE_COMMAND}" -P "${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake")<br />
</pre><br />
<br />
Now you will have an "uninstall" target at the top-level directory of your build tree.<br />
<br />
Instead of creating an "uninstall" target, Unix users could enter this command in the shell:<br />
<br />
xargs rm < install_manifest.txt<br />
<br />
== Distribution questions ==<br />
<br />
=== Where is "make dist"? ===<br />
<br />
CMake doesn't create a "make dist" target.<br />
<br />
=== What is the best way to distribute source code or binaries for a cmake-based project? ===<br />
<br />
For creating source or binary packages there is now [[CMake#CPack | CPack]] coming with CMake, see the <br />
[[ CMake#CPack | documentation]].<br />
<br />
Of course you can also use any other ways to create packages.<br />
<br />
== Platform-specific questions ==<br />
=== How do I build universal binaries on Mac OS X? ===<br />
Before running CMake with an empty build tree, set the CMAKE_OSX_ARCHITECTURES environment variable. It should be set to contain a ; separated list of architectures that you want in the binary. For example, for 32-bit PowerPC and Intel you would do this:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386<br />
<br />
If you wish to build both as 32 and 64 bit, do this:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386;ppc64;x86_64<br />
<br />
You can also set the same named CMake cache variable on an existing binary tree. This works with both makefiles and the Xcode generator. <br />
<br />
In addition, you can also set the CMAKE_OSX_SYSROOT variable to point to the sysroot (aka Mac OS SDK) to be used. CMake will attempt to pick one on your system, but it can be changed in the cache or via an environment variable before running CMake. The 10.4u SDK or later must be used to create a Universal Binary.<br />
<br />
Universal Binaries are essentially cross compilation and so you should avoid using TRY_RUN, especially for things like testing endianess or variable size because the result will only be correct for one architecture.<br />
<br />
Lastly, note that CTest is only able to test one architecture. See bug 6157.<br />
<br />
=== How can I apply resources on Mac OS X automatically? ===<br />
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 a custom rule which is executed after the executable is linked:<br />
<br />
<pre><br />
ADD_EXECUTABLE(MyExecutable ${MyExecutable_SRCS})<br />
GET_TARGET_PROPERTY(MyExecutable_PATH MyExecutable LOCATION)<br />
<br />
IF(APPLE)<br />
FIND_PROGRAM(APPLE_RESOURCE Rez /Developer/Tools)<br />
IF(APPLE_RESOURCE)<br />
ADD_CUSTOM_COMMAND(TARGET MyExecutable POST_BUILD<br />
COMMAND ${APPLE_RESOURCE} Carbon.r -o ${MyExecutable_PATH})<br />
ENDIF(APPLE_RESOURCE)<br />
ENDIF(APPLE)<br />
</pre><br />
<br />
This will execute:<br />
<br />
/Developer/Tools/Rez Carbon.r -o /binary/path/MyExecutable<br />
<br />
after MyExecutable is linked.<br />
<br />
'Rez' may be located elsewhere on disk, depending on the version of Mac OS X and Xcode. You can use 'which Rez' in Terminal to find it's full path.<br />
<br />
=== Why does FIND_LIBRARY not find .DLL libraries under WIN32? ===<br />
For those who come from a Unix background to MS Windows:<br />
<br />
You never link directly to the .dll, you have to link against the import library .lib for the .dll.<br />
<br />
Linking against dynamic libraries (.dll under Windows) is quite different from linking against ELF shared objects (.so) under platforms like Linux or NetBSD. In Windows, there are two types of library, a static library and an import library (both confusingly use the .lib extension, however). In Windows, when you build an import library (A.lib) you will get a corresponding (A.dll) that you only need at runtime. At compile time you will need the import library.<br />
<br />
Conclusion: There is no need to find a .dll for linking. You only need to find the .lib import library.<br />
<br />
Some more details can be found here: [http://xenophilia.org/winvunix.html].<br />
<br />
=== Why am I getting a linker error to _mainCRTStartup under WIN32? ===<br />
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.<br />
<br />
ADD_EXECUTABLE(exename WIN32 source1 source2 ... sourceN)<br />
<br />
The second argument to ADD_EXECUTABLE can be WIN32. This indicates that the executable, when compiled on Windows, is a Windows app (using WinMain) and not a console app (using main). Please note that on Unix platforms, CMake ignores the WIN32 and the compiler will use "main" in any case.<br />
<br />
=== Why do I get this error: nafxcwd.lib(appcore.obj) : error LNK2001: unresolved external symbol ___argv ===<br />
<br />
This is because the application is using both the static and dll versions of the MFC library.<br />
To fix the problem, you can do the following:<br />
<br />
SET(CMAKE_MFC_FLAG 2) # force the IDE to use static MFC<br />
ADD_DEFINITIONS(-D_AFXDLL) # make sure if afx.h is included the dll MFC is used<br />
<br />
=== How to use MFC with CMake ===<br />
To use MFC, the CMAKE_MFC_FLAG variable must be set as follows:<br />
<br />
0: Use Standard Windows Libraries<br />
1: Use MFC in a Static Library<br />
2: Use MFC in a Shared DLL <br />
<br />
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:<br />
<br />
ADD_DEFINITIONS(-D_AFXDLL)<br />
SET(CMAKE_MFC_FLAG 2) <br />
ADD_EXECUTABLE(CMakeSetup WIN32 ${SRCS})<br />
<br />
=== How To Put Files in Folders in Visual Studio Projects ===<br />
The Visual Studio IDE supports putting files into folders.<br />
CMake can be used to put files in folders with the SOURCE_GROUP <br />
command. <br />
<br />
SOURCE_GROUP(name [REGULAR_EXPRESSION regex] [FILES src1 src2 ...])<br />
<br />
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 provided the source file is being passed to ADD_EXECUTABLE or ADD_LIBRARY.<br />
<br />
For example:<br />
SOURCE_GROUP(FooFiles FILES foo.cxx)<br />
SOURCE_GROUP(BarFiles FILES bar.cxx)<br />
ADD_LIBRARY(foo foo.cxx bar.cxx)<br />
<br />
In the event 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).<br />
<br />
As a convenience to developers CMake automatically adds standard header files to a "Header Files" folder and standard source files to a "Source Files" folder for Visual Studio Projects. This can be overridden via the SOURCE_GROUP method documented above.<br />
<br />
=== How to create Visual Studio 6 Projects that contain only a single build type===<br />
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:<br />
<br />
# Create a directory in which you copy the files *.dsptemplate and CMakeVisualStudio6Configurations.cmake from CMake's Templates directory.<br />
# Edit the .cmake file and change the SET(CMAKE_CONFIGURATION_TYPES ...) line to set the build types that you want in your set.<br />
# Edit the *Header.dsptemplate files to contain only the configuration types you want in your set.<br />
# In your CMakeLists.txt file, set the MSPROJECT_TEMPLATE_DIRECTORY to the directory that you created.<br />
<br />
<br />
That's it. Run CMake and your new configuration files will be created.<br />
<br />
Note: Editing the *Header.dsptemplates files should be done very carefully. Here are some guidelines:<br />
<br />
- 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"')<br />
- 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.<br />
- 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.<br />
<br />
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:<br />
# PROP BASE Output_Dir ""<br />
# PROP BASE Intermediate_Dir ""<br />
# PROP Intermediate_Dir ""<br />
# PROP Output_Dir "LIBRARY_OUTPUT_PATH"<br />
or<br />
# PROP Output_Dir "EXECUTABLE_OUTPUT_PATH"<br />
<br />
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).<br />
<br />
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.<br />
<br />
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.)<br />
<br />
=== Can CMake set the Debugging/Working Directory property in Visual Studio projects? ===<br />
<br />
No. The value of this property is not stored in the project files. It is stored in extra files created by the IDE when a solution is loaded (VS .NET 2003 uses a hidden .suo file next to the .sln solution file). The format of these files is not known to CMake and cannot be generated. In some versions of VS the files are binary and not human readable.<br />
<br />
=== Why does CMakeSetup with the message "LINK : fatal error LNK1104: cannot open file 'user32.lib'" while configuring a project? ===<br />
<br />
The path to the SDK libs (user32.lib) must be added by the IDE when the<br />
project generator "Visual Studio 8 2005" is used, because cmake uses<br />
VCExpress.exe and on the fly generated project files to check<br />
for compiling (VCExpress.exe reads some config files for the<br />
compiler/linker options)<br />
<br />
So add the sdk lib path (...\Microsoft Platform SDK\Lib) at Tools->Options->Projects and Solutions->VC++ Directories->Library files<br />
<br />
See also:<br />
*http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/<br />
<br />
=== How can I avoid the error "Arg list too long" when running make? ===<br />
This error is sometimes encountered when building a static library with many object files using Unix make command. It typically looks something like this:<br />
<br />
<pre><br />
gmake[2]: execvp: /bin/sh: Arg list too long<br />
</pre><br />
<br />
When make tries to run the archiver program to build the static library the shell it uses complains that the argument list is too long. In some shells this can be fixed by setting an environment variable such as <tt>ARG_MAX</tt> to extend the length of the command line it will allow.<br />
<br />
=== How can I find out platforms definitions, search paths, etc. from gcc ?===<br />
<br />
The following is really the best if not only way to get information about predefined macros with a GNU compiler:<br />
<pre><br />
$ touch empty.c<br />
$ gcc -v -dD -E empty.c <br />
</pre><br />
This will give you all you might want to know about the preprocessor, the builtin include search dirs and all<br />
predefined definitions, so you can check whether it's __LINUX or _LINUX_ or _APPLE_ or __APPLE etc. <br />
The empty file and all these parameters are really required. You probably want to pipe the output (both stdout and stderr) to a file.<br />
<br />
This is how you can get the builtin library search paths:<br />
<pre><br />
$ gcc --print-search-dirs<br />
</pre><br />
<br />
=== How can I get a windows registry key ?===<br />
<br />
The only thing to know is that you can't use just the "SET" command in place of "GET" command.<br />
CMake read the value from the registry only when you "get" it from the cache. For instance :<br />
<br />
<pre><br />
GET_FILENAME_COMPONENT(SDK_ROOT_PATH "[HKEY_LOCAL_MACHINE\\SOFTWARE\\PACKAGE;Install_Dir]" ABSOLUTE CACHE)<br />
</pre><br />
<br />
If a key name (ex: Install_Dir in this case) was not specified , the Default key value will be get.<br />
Now you could use the SDK_ROOT_PATH to add include and lib path to your project :<br />
<br />
<pre><br />
INCLUDE_DIRECTORIES(<br />
${SDK_ROOT_PATH}/include<br />
)<br />
<br />
LINK_DIRECTORIES(<br />
${SDK_ROOT_PATH}/lib<br />
)<br />
</pre><br />
<br />
You can also read a registry key in the PATHS section of a FIND_LIBRARY, FIND_PATH, FIND_PROGRAM, or FIND_FILE command<br />
FIND_FILE(BOOT_DOT_INI boot.ini PATHS [HKEY_CURRENT_USER\\Environment;HOMEDRIVE])<br />
<br />
For other examples have a look in the CMake Modules folder :<br />
- FindJava.cmake<br />
- FindPythonLibs.cmake<br />
- ..<br />
<br />
{{CMake/Template/Footer}}</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake:Module_Maintainers&diff=14504CMake:Module Maintainers2009-01-23T06:11:22Z<p>Plowman: reads a lot easier now</p>
<hr />
<div>If you want to add a new module to CMake, then you must volunteer to maintain it, or find someone that will. This page contains a list of Module maintainer volunteers, and instructions on how to become a maintainer. <br />
<br />
* This mail describes the procedure how to become maintainer, and how to modify or add modules: [http://www.cmake.org/pipermail/cmake/2007-July/015258.html Call for maintainers] <br />
<br />
* Please '''DO NOT ADD a Bug Tracker''' entry for new Module request [http://www.cmake.org/pipermail/cmake/2008-November/025196.html Do not add bug report for New Module] <br />
<br />
* Maintainers should follow the guide lines for module files documented here: [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/readme.txt?root=CMake&view=markup readme]<br />
<br />
In addition backwards compatibility for all existing variables in the current set<br />
of modules must be maintained strictly. <br />
<br />
If you want to become a module maintainer, please send an email with your module to the cmake mailing list.<br />
<br />
* Here is a list of "repositories" of 3rd party CMake modules, so maintainers can check for already existing modules etc.<br />
** KDE4: http://websvn.kde.org/trunk/KDE/kdelibs/cmake/modules/<br />
** PlPlot: http://plplot.svn.sourceforge.net/viewvc/plplot/trunk/cmake/modules/<br />
** http://cmake-modules.googlecode.com/svn/trunk/Modules/<br />
** OpenSceneGraph http://www.openscenegraph.org/svn/osg/OpenSceneGraph/trunk/CMakeModules/<br />
** OpenSync http://svn.opensync.org/branches/3rd-party-cmake-modules/modules/<br />
** http://github.com/jedbrown/cmake-modules<br />
<br />
----<br />
<br />
* Andreas Schneider, mail at cynapses dot org<br />
** FindBoost.cmake<br />
<br />
* Miguel A. Figueroa Villanueva, miguelf at ieee dot org<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindwxWidgets.cmake?root=CMake&view=markup FindwxWidgets.cmake]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindLATEX.cmake?root=CMake&view=markup FindLATEX]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindImageMagick.cmake?root=CMake&view=markup FindImageMagick]<br />
<br />
* Alan W. Irwin, irwin at beluga dot phys dot uvic dot ca<br />
** Ada<br />
<br />
* Tristan Carel, tristan dot carel at gmail dot com<br />
** FindSWIG<br />
** UseSWIG<br />
** FindSubversion<br />
<br />
* Alin M Elena, alinm dot elena at gmail dot com (http://titus.phy.qub.ac.uk/group/Alin/)<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindBLAS.cmake?root=CMake&view=markup FindBLAS]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindLAPACK.cmake?root=CMake&view=markup FindLAPACK] - <br />
<br />
* Tim Burrell (tim dot burrell at gmail dot com) (http://www.dsource.org/projects/cmaked)<br />
** D support<br />
<br />
* Philip Lowman, philip at yhbt dot com<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindCxxTest.cmake?root=CMake&view=markup FindCxxTest]<br />
** [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindDoxygen.cmake?root=CMake&view=markup FindDoxygen]<br />
<br />
* Eric Wing ; in the commercial domain at gmail, ewing . public<br />
** FindFreeType.cmake<br />
** FindGDAL.cmake<br />
** FindGIFLIB.cmake<br />
** FindLua50.cmake, FindLua51.cmake<br />
** FindOpenAL.cmake<br />
** FindOpenThreads.cmake<br />
** FindPhysFS.cmake<br />
** FindProducer.cmake<br />
** FindQuickTime.cmake<br />
** FindSDL.cmake, FindSDL_image.cmake, FindSDL_mixer.cmake. FindSDL_net.cmake, FindSDL_sound.cmake, FindSDL_ttf.cmake<br />
** Findosg.cmake, FindosgDB.cmake, FindosgFX.cmake, FindosgGA.cmake, FindosgIntrospection.cmake, FindosgManipulator.cmake, FindosgParticle.cmake, FindosgProducer.cmake, FindosgShadow.cmake, FindosgSim.cmake, FindosgTerrain.cmake, FindosgText.cmake, FindosgUtil.cmake, FindosgViewer.cmake <br />
<br />
* Douglas Gregor (doug.gregor at gmail dot com)<br />
** FindMPI<br />
<br />
* Matt Leotta, matt.leotta at gmail dot com<br />
** FindCoin3D<br />
<br />
* Clinton Stimpson clinton at elemtech dot com<br />
** FindQt4<br />
<br />
* Petr Gotthard, petr dot gotthard at honeywell dot com<br />
** FindRTI</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake:Module_Maintainers&diff=14503CMake:Module Maintainers2009-01-23T06:02:00Z<p>Plowman: </p>
<hr />
<div>If you want to add a new module to CMake, then you must volunteer to maintain it, or find someone that will. This page contains a list of Module maintainer volunteers, and instructions on how to become a maintainer. <br />
<br />
* This mail describes the procedure how to become maintainer, and how to modify or add modules: [http://www.cmake.org/pipermail/cmake/2007-July/015258.html Call for maintainers] <br />
<br />
* Please '''DO NOT ADD a Bug Tracker''' entry for new Module request [http://www.cmake.org/pipermail/cmake/2008-November/025196.html Do not add bug report for New Module] <br />
<br />
* Maintainers should follow the guide lines for module files documented here: [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/readme.txt?root=CMake&view=markup readme]<br />
<br />
In addition backwards compatibility for all existing variables in the current set<br />
of modules must be maintained strictly. <br />
<br />
If you want to become a module maintainer, please send an email with your module to the cmake mailing list.<br />
<br />
* Here is a list of "repositories" of 3rd party CMake modules, so maintainers can check for already existing modules etc.<br />
** KDE4: http://websvn.kde.org/trunk/KDE/kdelibs/cmake/modules/<br />
** PlPlot: http://plplot.svn.sourceforge.net/viewvc/plplot/trunk/cmake/modules/<br />
** http://cmake-modules.googlecode.com/svn/trunk/Modules/<br />
** OpenSceneGraph http://www.openscenegraph.org/svn/osg/OpenSceneGraph/trunk/CMakeModules/<br />
** OpenSync http://svn.opensync.org/branches/3rd-party-cmake-modules/modules/<br />
** http://github.com/jedbrown/cmake-modules<br />
<br />
----<br />
<br />
<br />
<br />
* FindBoost.cmake - Andreas Schneider, mail at cynapses dot org<br />
* [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindwxWidgets.cmake?root=CMake&view=markup FindwxWidgets.cmake], [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindLATEX.cmake?root=CMake&view=markup FindLATEX], [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindImageMagick.cmake?root=CMake&view=markup FindImageMagick] - Miguel A. Figueroa Villanueva, miguelf at ieee dot org<br />
* Ada - Alan W. Irwin, irwin at beluga dot phys dot uvic dot ca<br />
* FindSWIG, UseSWIG, FindSubversion - Tristan Carel, tristan dot carel at gmail dot com<br />
* [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindBLAS.cmake?root=CMake&view=markup FindBLAS], [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindLAPACK.cmake?root=CMake&view=markup FindLAPACK] - Alin M Elena, alinm dot elena at gmail dot com (http://titus.phy.qub.ac.uk/group/Alin/)<br />
* D support - Tim Burrell (tim dot burrell at gmail dot com) (http://www.dsource.org/projects/cmaked)<br />
* FindFreeType.cmake, FindGDAL.cmake, FindGIFLIB.cmake, FindLua50.cmake, FindLua51.cmake, FindOpenAL.cmake, FindOpenThreads.cmake, FindPhysFS.cmake. FindProducer.cmake, FindQuickTime.cmake. FindSDL.cmake, FindSDL_image.cmake, FindSDL_mixer.cmake. FindSDL_net.cmake, FindSDL_sound.cmake, FindSDL_ttf.cmake, Findosg.cmake, FindosgDB.cmake, FindosgFX.cmake, FindosgGA.cmake, FindosgIntrospection.cmake, FindosgManipulator.cmake, FindosgParticle.cmake, FindosgProducer.cmake, FindosgShadow.cmake, FindosgSim.cmake, FindosgTerrain.cmake, FindosgText.cmake, FindosgUtil.cmake, FindosgViewer.cmake (Eric Wing ; in the commercial domain at gmail, ewing . public)<br />
* FindMPI - Douglas Gregor (doug.gregor at gmail dot com)<br />
* FindCxxTest, FindLua*, FindDoxygen - Philip Lowman, philip at yhbt dot com<br />
* FindCoin3D - Matt Leotta, matt.leotta at gmail dot com<br />
* FindQt4 - Clinton Stimpson clinton at elemtech dot com<br />
* FindRTI - Petr Gotthard, petr dot gotthard at honeywell dot com</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake:Module_Maintainers&diff=14502CMake:Module Maintainers2009-01-23T05:59:49Z<p>Plowman: </p>
<hr />
<div>If you want to add a new module to CMake, then you must volunteer to maintain it, or find someone that will. This page contains a list of Module maintainer volunteers, and instructions on how to become a maintainer. <br />
<br />
* This mail describes the procedure how to become maintainer, and how to modify or add modules: [http://www.cmake.org/pipermail/cmake/2007-July/015258.html Call for maintainers] <br />
<br />
* Please '''DO NOT ADD a Bug Tracker''' entry for new Module request [http://www.cmake.org/pipermail/cmake/2008-November/025196.html Do not add bug report for New Module] <br />
<br />
* Maintainers should follow the guide lines for module files documented here: [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/readme.txt?root=CMake&view=markup readme]<br />
<br />
In addition backwards compatibility for all existing variables in the current set<br />
of modules must be maintained strictly. <br />
<br />
If you want to become a module maintainer, please send an email with your module to the cmake mailing list.<br />
<br />
* Here is a list of "repositories" of 3rd party CMake modules, so maintainers can check for already existing modules etc.<br />
** KDE4: http://websvn.kde.org/trunk/KDE/kdelibs/cmake/modules/<br />
** PlPlot: http://plplot.svn.sourceforge.net/viewvc/plplot/trunk/cmake/modules/<br />
** http://cmake-modules.googlecode.com/svn/trunk/Modules/<br />
** OpenSceneGraph http://www.openscenegraph.org/svn/osg/OpenSceneGraph/trunk/CMakeModules/<br />
** OpenSync http://svn.opensync.org/branches/3rd-party-cmake-modules/modules/<br />
** http://github.com/jedbrown/cmake-modules<br />
<br />
----<br />
<br />
<br />
* FindBoost.cmake - Andreas Schneider, mail at cynapses dot org<br />
* [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindwxWidgets.cmake?root=CMake&view=markup FindwxWidgets.cmake], [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindLATEX.cmake?root=CMake&view=markup FindLATEX], [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindImageMagick.cmake?root=CMake&view=markup FindImageMagick] - Miguel A. Figueroa Villanueva, miguelf at ieee dot org<br />
* Ada - Alan W. Irwin, irwin at beluga dot phys dot uvic dot ca<br />
* FindSWIG, UseSWIG, FindSubversion - Tristan Carel, tristan dot carel at gmail dot com<br />
* [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindBLAS.cmake?root=CMake&view=markup FindBLAS], [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/FindLAPACK.cmake?root=CMake&view=markup FindLAPACK] - Alin M Elena, alinm dot elena at gmail dot com (http://titus.phy.qub.ac.uk/group/Alin/)<br />
* D support - Tim Burrell (tim dot burrell at gmail dot com) (http://www.dsource.org/projects/cmaked)<br />
* FindFreeType.cmake, FindGDAL.cmake, FindGIFLIB.cmake, FindLua50.cmake, FindLua51.cmake, FindOpenAL.cmake, FindOpenThreads.cmake, FindPhysFS.cmake. FindProducer.cmake, FindQuickTime.cmake. FindSDL.cmake, FindSDL_image.cmake, FindSDL_mixer.cmake. FindSDL_net.cmake, FindSDL_sound.cmake, FindSDL_ttf.cmake, Findosg.cmake, FindosgDB.cmake, FindosgFX.cmake, FindosgGA.cmake, FindosgIntrospection.cmake, FindosgManipulator.cmake, FindosgParticle.cmake, FindosgProducer.cmake, FindosgShadow.cmake, FindosgSim.cmake, FindosgTerrain.cmake, FindosgText.cmake, FindosgUtil.cmake, FindosgViewer.cmake (Eric Wing ; in the commercial domain at gmail, ewing . public)<br />
* FindMPI - Douglas Gregor (doug.gregor at gmail dot com)<br />
* FindCxxTest, FindLua* - Philip Lowman, philip at yhbt dot com<br />
* FindCoin3D - Matt Leotta, matt.leotta at gmail dot com<br />
* FindQt4 - Clinton Stimpson clinton at elemtech dot com<br />
* FindRTI - Petr Gotthard, petr dot gotthard at honeywell dot com</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMakeCompareVersionStrings&diff=14479CMakeCompareVersionStrings2009-01-16T07:06:28Z<p>Plowman: </p>
<hr />
<div>{{CMake/Template/Obsolete}}<br />
<br />
Please see the '''VERSION_LESS''', '''VERSION_EQUAL''', and '''VERSION_GREATER''' options to the IF() command.<br />
<br />
----<br />
<br />
I needed a way to compare two version strings to make sure that I had a version of a package that was sufficient for my needs. The first go around I used regular expressions to pull out all the dot versions, create a number, and finally compare the number.<br />
<br />
<pre><br />
SET(THREE_PART_VERSION_REGEX "[0-9]+\\.[0-9]+\\.[0-9]+")<br />
<br />
# Breaks up a string in the form n1.n2.n3 into three parts and stores<br />
# them in major, minor, and patch. version should be a value, not a<br />
# variable, while major, minor and patch should be variables.<br />
MACRO(THREE_PART_VERSION_TO_VARS version major minor patch)<br />
IF(${version} MATCHES ${THREE_PART_VERSION_REGEX})<br />
STRING(REGEX REPLACE "^([0-9]+)\\.[0-9]+\\.[0-9]+" "\\1" ${major} "${version}")<br />
STRING(REGEX REPLACE "^[0-9]+\\.([0-9])+\\.[0-9]+" "\\1" ${minor} "${version}")<br />
STRING(REGEX REPLACE "^[0-9]+\\.[0-9]+\\.([0-9]+)" "\\1" ${patch} "${version}")<br />
ELSE(${version} MATCHES ${THREE_PART_VERSION_REGEX})<br />
MESSAGE("MACRO(THREE_PART_VERSION_TO_VARS ${version} ${major} ${minor} ${patch}")<br />
MESSAGE(FATAL_ERROR "Problem parsing version string, I can't parse it properly.")<br />
ENDIF(${version} MATCHES ${THREE_PART_VERSION_REGEX})<br />
ENDMACRO(THREE_PART_VERSION_TO_VARS)<br />
<br />
THREE_PART_VERSION_TO_VARS(${version-string} major_vers minor_vers patch_vers)<br />
MESSAGE("version = ${major_vers}.${minor_vers}.${patch_vers}")<br />
<br />
# Compute a version number<br />
MATH(EXPR version_number "${major_vers} * 1000000 + ${minor_vers} * 1000 + ${patch_vers}" )<br />
MESSAGE("version_number = ${version_number}")<br />
</pre><br />
<br />
This was somewhat cumbersome, and was hard coded for three dot versions (x.y.z). I wanted to be able to use a single macro for version strings with 1 to any number of dot versions. In addition I wanted to be able to compare version strings with different number of dot versions (i.e. 0.99.1 and 0.99.1.2).<br />
<br />
<pre><br />
# Computes the realtionship between two version strings. A version<br />
# string is a number delineated by '.'s such as 1.3.2 and 0.99.9.1.<br />
# You can feed version strings with different number of dot versions,<br />
# and the shorter version number will be padded with zeros: 9.2 <<br />
# 9.2.1 will actually compare 9.2.0 < 9.2.1.<br />
#<br />
# Input: a_in - value, not variable<br />
# b_in - value, not variable<br />
# result_out - variable with value:<br />
# -1 : a_in < b_in<br />
# 0 : a_in == b_in<br />
# 1 : a_in > b_in<br />
#<br />
# Written by James Bigler.<br />
MACRO(COMPARE_VERSION_STRINGS a_in b_in result_out)<br />
# Since SEPARATE_ARGUMENTS using ' ' as the separation token,<br />
# replace '.' with ' ' to allow easy tokenization of the string.<br />
STRING(REPLACE "." " " a ${a_in})<br />
STRING(REPLACE "." " " b ${b_in})<br />
SEPARATE_ARGUMENTS(a)<br />
SEPARATE_ARGUMENTS(b)<br />
<br />
# Check the size of each list to see if they are equal.<br />
LIST(LENGTH a a_length)<br />
LIST(LENGTH b b_length)<br />
<br />
# Pad the shorter list with zeros.<br />
<br />
# Note that range needs to be one less than the length as the for<br />
# loop is inclusive (silly CMake).<br />
IF(a_length LESS b_length)<br />
# a is shorter<br />
SET(shorter a)<br />
MATH(EXPR range "${b_length} - 1")<br />
MATH(EXPR pad_range "${b_length} - ${a_length} - 1")<br />
ELSE(a_length LESS b_length)<br />
# b is shorter<br />
SET(shorter b)<br />
MATH(EXPR range "${a_length} - 1")<br />
MATH(EXPR pad_range "${a_length} - ${b_length} - 1")<br />
ENDIF(a_length LESS b_length)<br />
<br />
# PAD out if we need to<br />
IF(NOT pad_range LESS 0)<br />
FOREACH(pad RANGE ${pad_range})<br />
# Since shorter is an alias for b, we need to get to it by by dereferencing shorter.<br />
LIST(APPEND ${shorter} 0)<br />
ENDFOREACH(pad RANGE ${pad_range})<br />
ENDIF(NOT pad_range LESS 0)<br />
<br />
SET(result 0)<br />
FOREACH(index RANGE ${range})<br />
IF(result EQUAL 0)<br />
# Only continue to compare things as long as they are equal<br />
LIST(GET a ${index} a_version)<br />
LIST(GET b ${index} b_version)<br />
# LESS<br />
IF(a_version LESS b_version)<br />
SET(result -1)<br />
ENDIF(a_version LESS b_version)<br />
# GREATER<br />
IF(a_version GREATER b_version)<br />
SET(result 1)<br />
ENDIF(a_version GREATER b_version)<br />
ENDIF(result EQUAL 0)<br />
ENDFOREACH(index)<br />
<br />
# Copy out the return result<br />
SET(${result_out} ${result})<br />
ENDMACRO(COMPARE_VERSION_STRINGS)<br />
</pre><br />
<br />
I tested it with the following input:<br />
<br />
<pre><br />
# a and b need to be passed in by value<br />
MACRO(COMPARE_VERSION a b)<br />
COMPARE_VERSION_STRINGS(${a} ${b} result)<br />
IF(result LESS 0)<br />
MESSAGE("${a} < ${b}")<br />
ELSE(result LESS 0)<br />
IF(result GREATER 0)<br />
MESSAGE("${a} > ${b}")<br />
ELSE(result GREATER 0)<br />
MESSAGE("${a} == ${b}")<br />
ENDIF(result GREATER 0)<br />
ENDIF(result LESS 0)<br />
ENDMACRO(COMPARE_VERSION)<br />
<br />
SET(version-string "1.3.31")<br />
<br />
COMPARE_VERSION(${version-string} "1.3.30")<br />
COMPARE_VERSION(${version-string} "1.3.31")<br />
COMPARE_VERSION(${version-string} "1.3.32")<br />
COMPARE_VERSION(${version-string} "1.2.32")<br />
COMPARE_VERSION(${version-string} "1.10.1")<br />
<br />
COMPARE_VERSION("9.2" "9.1")<br />
COMPARE_VERSION("9.2" "9.2")<br />
COMPARE_VERSION("9.2" "9.3")<br />
<br />
COMPARE_VERSION("9.1" "9.2")<br />
COMPARE_VERSION("9.2" "9.2")<br />
COMPARE_VERSION("9.3" "9.2")<br />
<br />
COMPARE_VERSION("9.10" "9.2")<br />
COMPARE_VERSION("9.2" "9.10")<br />
<br />
COMPARE_VERSION("0.92.1.0" "0.92.1.1")<br />
COMPARE_VERSION("0.92.1.1" "0.92.1.1")<br />
COMPARE_VERSION("0.92.1.2" "0.92.1.1")<br />
<br />
COMPARE_VERSION("0.92.1.2" "0.99.1.1")<br />
COMPARE_VERSION("0.99.1.2" "0.92.1.1")<br />
<br />
COMPARE_VERSION("0.92.1.2" "0.99.1")<br />
COMPARE_VERSION("0.99.1" "0.92.1.1")<br />
<br />
COMPARE_VERSION("0.99.1.2" "0.99.1")<br />
COMPARE_VERSION("0.99.1" "0.99.1.1")<br />
<br />
COMPARE_VERSION( "1" "10")<br />
COMPARE_VERSION("10" "1")<br />
</pre><br />
<br />
Here's the output:<br />
<br />
<pre><br />
1.3.31 > 1.3.30<br />
1.3.31 == 1.3.31<br />
1.3.31 < 1.3.32<br />
1.3.31 > 1.2.32 (note this is 1.2 not 1.3)<br />
1.3.31 < 1.10.1<br />
9.2 > 9.1<br />
9.2 == 9.2<br />
9.2 < 9.3<br />
9.1 < 9.2<br />
9.2 == 9.2<br />
9.3 > 9.2<br />
9.10 > 9.2<br />
9.2 < 9.10<br />
0.92.1.0 < 0.92.1.1<br />
0.92.1.1 == 0.92.1.1<br />
0.92.1.2 > 0.92.1.1<br />
0.92.1.2 < 0.99.1.1<br />
0.99.1.2 > 0.92.1.1<br />
0.92.1.2 < 0.99.1<br />
0.99.1 > 0.92.1.1<br />
0.99.1.2 > 0.99.1<br />
0.99.1 < 0.99.1.1<br />
1 < 10<br />
10 > 1<br />
</pre><br />
<br />
[[Category:CMakeMacro]]</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=BuildingPythonWithCMake&diff=14478BuildingPythonWithCMake2009-01-16T07:04:07Z<p>Plowman: </p>
<hr />
<div>=Building Python 2.5.1=<br />
<br />
Get the Python sources for release 2.5.1, e.g. from http://www.python.org/download/ . <br />
If you are using Python 2.5.1 you'll need to apply the following patch, otherwise Python doesn't build with dynamic loading disabled and Unicode disabled: <br />
[http://www.cmake.org/Wiki/images/d/dd/Python-2.5.1-build-without-shared-libs-and-unicode.diff Python-2.5.1-build-without-shared-libs-and-unicode.diff]<br />
<br />
There are two ways to get the CMake files for building Python:<br />
<br />
* you can download a snapshot here: [http://www.cmake.org/Wiki/images/b/b9/Python-2.5.1-cmakefiles-2.tar.gz Python-2.5.1-cmakefiles-2.tar.gz].<br />
<br />
Unpack that file and copy them over to the Python source directory, so that the toplevel CMakeLists.txt ends up in<br />
the toplevel Python directory.<br />
<br />
* you can download the CMake files using cvs<br />
<br />
The CMake files for building Python 2.5.1 are in the ParaView3 cvs, in the branch Python-2_5_1-BRANCH.<br />
You can get them like this:<br />
<pre><br />
$ cvs -d :pserver:anoncvs@www.paraview.org:/cvsroot/ParaView3 login<br />
<empty password><br />
$ cvs -d :pserver:anoncvs@www.paraview.org:/cvsroot/ParaView3 co -d CMakeBuildForPython -r Python-2_5_1-BRANCH ParaView3/Utilities/CMakeBuildForPython<br />
</pre><br />
<br />
Then copy these files over to the Python source directory, so that the toplevel CMakeLists.txt ends up in<br />
the toplevel Python directory.<br />
<br />
=Building svn Python or Python >= 2.6.0=<br />
<br />
With Python from svn (not Python 3000) or Python 2.6.0 (not released yet, September 2007), the patch mentioned above for handling <br />
unicode and disabled dynamic loading isn't necessary anymore.<br />
Here's how you can get Python from Python svn and the CMake files for Python, which are in ParaView3 cvs, HEAD;<br />
<pre><br />
$ svn co http://svn.python.org/projects/python/trunk python-with-cmake<br />
$ cvs -d :pserver:anoncvs@www.paraview.org:/cvsroot/ParaView3 login<br />
<empty password><br />
$ cvs -d :pserver:anoncvs@www.paraview.org:/cvsroot/ParaView3 co -d python-with-cmake ParaView3/Utilities/CMakeBuildForPython <br />
</pre><br />
<br />
The commands shown above will check out Python and the CMake files in the same directory, which will be both a CVS and a svn working directory at the same time. While this is a bit unusual it works, since svn and CVS use different meta data directories (.svn/ vs. CVS/).<br />
<br />
=Platform specific build notes=<br />
<br />
==Building Python for Linux or Windows==<br />
<br />
Just run CMake on it as usual, then make, make install. Under Windows this is tested with VisualStudio 2003.<br />
Under Windows the tests in ConfigureChecks.cmake are not actually executed, but the pyconfig.h for Windows which is part of the Python<br />
sources is used as is. This is actually not necessary, the tests could be executed the same way as they are executed under Windows, <br />
but to get this working probably some flags, include files etc. have to be adjusted, and I didn't have the time to do this yet.<br />
As a difference to the original Python build for Windows not all modules are built into a huge python.dll, but instead they are built as separate plugins (as under Linux).<br />
<br />
==Building Python for other operating systems==<br />
<br />
Building Python using CMake for other operating systems like OS X, *BSD etc. shouldn't require a lot of work, maybe it already works<br />
out of the box. Probably some configure checks have to be tweaked.<br />
<br />
<br />
==Cross compiling Python for BlueGene/L==<br />
<br />
Cross compiling Python for BlueGene is easy, since in python-with-cmake/CMake/ there is a file TryRunResults-Python-bgl-gcc.cmake,<br />
which contains the results for the TRY_RUN() tests which are executed by CMake when configuring Python. Since <br />
we are cross compiling CMake can't actually run these tests, but the results have to be supplied manually.<br />
This is done in this case by preloading the CMake cache using the mentioned file:<br />
<br />
<pre><br />
~/src/python-with-cmake/ $ <br />
~/src/python-with-cmake/ $ mkdir build-bgl<br />
~/src/python-with-cmake/~$ cd build-bgl<br />
~/src/python-with-cmake/build-bgl/ $ cmake -DCMAKE_TOOLCHAIN_FILE=~/Toolchain-BlueGeneL-gcc.cmake -DCMAKE_INSTALL_PREFIX=~/bgl-install -C ../CMake/TryRunResults-Python-bgl-gcc.cmake ..<br />
...<br />
~/src/python-with-cmake/build-bgl/ $ make<br />
...<br />
~/src/python-with-cmake/build-bgl/ $ make install<br />
...<br />
</pre><br />
<br />
==Cross compiling Python for Cray Xt3/ Catamount==<br />
<br />
Cross compiling Python for Cray Xt3/Catamount is easy, since in python-with-cmake/CMake/ there is a file TryRunResults-Python-catamount-gcc.cmake,<br />
which contains the results for the TRY_RUN() tests which are executed by CMake when configuring Python. Since <br />
we are cross compiling CMake can't actually run these tests, but the results have to be supplied manually.<br />
This is done in this case by preloading the CMake cache using the mentioned file:<br />
<br />
<pre><br />
~/src/python-with-cmake/ $ <br />
~/src/python-with-cmake/ $ mkdir build-catamount-gcc<br />
~/src/python-with-cmake/~$ cd build-catamount-gcc<br />
~/src/python-with-cmake/build-catamount-gcc/ $ cmake -DCMAKE_TOOLCHAIN_FILE=~/Toolchain-Catamount-gcc.cmake -DCMAKE_INSTALL_PREFIX=~/catamount-install -C ../CMake/TryRunResults-Python-catamount-gcc.cmake ..<br />
...<br />
</pre><br />
The python module <tt>pwd</tt> has to be disabled by setting MODULE_pwd_ENABLE to OFF, since the getpw*() functions are not available under Catamount.<br />
<pre><br />
~/src/python-with-cmake/build-catamount/ $ make<br />
...<br />
~/src/python-with-cmake/build-catamount/ $ make install<br />
...<br />
</pre><br />
<br />
When linking it all together there are a lot of warnings about posix_* functions, where the linker warns that they will fail at runtime. They come from the posix module. But this has to be built, it's presence itself is used by python to detect that it's running on a POSIX-like platform.<br />
<br />
==Cross compiling Python for another platform==<br />
<br />
<pre><br />
~/src/python-with-cmake/ $ <br />
~/src/python-with-cmake/ $ mkdir build-ecos<br />
~/src/python-with-cmake/~$ cd build-ecos<br />
~/src/python-with-cmake/build-ecos/ $ cmake -DCMAKE_TOOLCHAIN_FILE=~/Toolchain-eCos-synth.cmake -DCMAKE_INSTALL_PREFIX=~/ecos-install ..<br />
...<br />
</pre><br />
<br />
This will finish with two errors, one for each TRY_RUN(), since this is cross compiling and CMake doesn't try to execute<br />
the executables. CMake will have created a file TryRunResults.cmake, <br />
This will finish with two errors:<br />
<pre><br />
-- Performing Test HAVE_BROKEN_NICE<br />
CMake Error: TRY_RUN() invoked in cross-compiling mode, please set the following cache variables appropriatly:<br />
HAVE_BROKEN_NICE_EXITCODE (advanced)<br />
For details see ~/src/python-with-cmake/build-ecos/TryRunResults.cmake<br />
-- Performing Test HAVE_BROKEN_NICE - Failed<br />
-- Performing Test HAVE_BROKEN_POLL<br />
CMake Error: TRY_RUN() invoked in cross-compiling mode, please set the following cache variables appropriatly:<br />
HAVE_BROKEN_POLL_EXITCODE (advanced)<br />
For details see ~/src/python-with-cmake/build-ecos/TryRunResults.cmake<br />
-- Performing Test HAVE_BROKEN_POLL - Failed<br />
</pre><br />
<br />
These are two system tests, where cmake used TRY_RUN() to test an executable, but since they are cross compiled, it didn't try to run them but instead produced these error messages.<br />
As the messages say have a look at ~/src/python-with-cmake/build-ecos/TryRunResults.cmake .<br />
You will find the executables which were not run in the build directory, named cmTryCompileExec-HAVE_BROKEN_NICE_EXITCODE and cmTryCompileExec-HAVE_BROKEN_POLL_EXITCODE. You can try to run them on the target to see what there exit code is and put these<br />
results into the TryRunResults.cmake file. After that you should copy this file to a safe place, otherwise it gets <br />
overwritten on the next CMake run and your changes are lost.<br />
Then use this file to preload the CMake cache with the results from the TRY_RUN():<br />
<pre><br />
~/src/python-with-cmake/build-ecos/ $ cmake -C ../CMake/TryRunResults-Python-ecos-synth.cmake ..<br />
...<br />
~/src/python-with-cmake/build-ecos/ $ make<br />
...<br />
~/src/python-with-cmake/build-ecos/ $ make install<br />
...<br />
</pre><br />
<br />
=Current status=<br />
<br />
==What works==<br />
* Builds on Linux, Windows and cross compiles to eCos, IBM BlueGene/L and Cray Xt3/Catamount<br />
* the python library can be built as shared or static library, RPATH is supported<br />
* each module can be enabled and disabled separatly<br />
* on systems without shared libs everything is build static, modules are linked into the python library<br />
* packages can be created using cpack (or "make package"): rpm, deb, tgz, stgz, zip, nsis and more<br />
<br />
==TODO==<br />
* Enable the configure checks on Windows, so the premade pyconfig.h file can go away.<br />
* Trying to build it on other platforms like *BSD, Apple. This shouldn't be much work.<br />
* Adding the remaining modules to the build. Should be just work, no major problems expected.<br />
* Add rules to bytecompile (or how it is called) the python modules to .pyc files<br />
* The python executable is currently installed with the version number in their name.<br />
<br />
=Potential problems=<br />
<br />
==Module not found==<br />
<br />
If the Python executable and the python library have been built and installed successfully and you can execute<br />
simple things, it still can happen that some modules are not found.<br />
Currently not all Python modules are built and not everything is installed. In this case have a look at python-with-svn/CMakeLists.txt and search in the list of ADD_PYTHON_MODULE() commands if your module is included. Some modules are disabled by default, you can enable building them by setting the option BUILD_UNTESTED_MODULES to TRUE. Other modules are still completely missing. <br />
If this is the case, figure out what the source files for this module are and add it to this list.<br />
If it is built and installed, but Python still doesn't find it, it's time for debugging. A good start might be python-with-svn/Python/import.c .<br />
<br />
[[Category:CMake]]</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMakeMacroListOperations&diff=14477CMakeMacroListOperations2009-01-16T07:03:34Z<p>Plowman: </p>
<hr />
<div>[[CMake_User_Contributed_Macros|Back]]<br />
<br />
{{CMake/Template/Obsolete}}<br />
<br />
Lists are an important component of most CMakeLists.txt files. Lists are built automatically from arguments to commands and macros. Thus, we often build lists in variables by calling SET with more than one variable argument. Surprisingly, there are very few CMake commands to handle lists. Here is a compilation of a few basic list manipulation commands.<br />
<br />
'''Update:''' Since CMake 2.4 most of the issues discussed here can be handled using the native CMake LIST command. However, these were very useful macros for handling lists in previous versions and they still are if you would like to add LIST support to your CMakeLists.txt files and for some reason you can't update your CMake installation. As such, I have maintained the original content as is, and provided a section at the bottom that makes use of the new CMake LIST command to perform the same functionality as the CAR, CDR, LIST_LENGTH, LIST_INDEX, and LIST_CONTAINS macros below. Note that there is a LIST_FILTER macro below that I have not attempted to write using the enhanced LIST command.<br />
<br />
== CAR and CDR ==<br />
<br />
Our first operations we take from lisp, a programming language built entirely around lists. Two fundamental functions of lisp are car, which returns the first element of a list, and cdr, which returns a list minus the first element. Here we give implementations of car and cdr CMake macros. Although they are not as efficient as their counterparts in lisp, they can still be surprisingly useful.<br />
<br />
<pre><br />
MACRO(CAR var)<br />
SET(${var} ${ARGV1})<br />
ENDMACRO(CAR)<br />
<br />
MACRO(CDR var junk)<br />
SET(${var} ${ARGN})<br />
ENDMACRO(CDR)<br />
</pre><br />
<br />
Here is a simple example of their use.<br />
<pre><br />
SET(MYLIST hello world foo bar)<br />
<br />
CAR(car ${MYLIST})<br />
CDR(cdr ${MYLIST})<br />
MESSAGE("car: ${car}")<br />
MESSAGE("cdr: ${cdr}")<br />
</pre><br />
The output of the command above is<br />
<pre><br />
car: hello<br />
cdr: world;foo;bar<br />
</pre><br />
<br />
Note that the CAR and CDR macros (as well as the rest of the macros in this document) take advantage of CMake's calling convention of expanding lists into arguments. If you quote the list argument, you get a very different result. If you change the previous example to<br />
<pre><br />
CAR(car "${MYLIST}")<br />
CDR(cdr "${MYLIST}")<br />
MESSAGE("car: ${car}")<br />
MESSAGE("cdr: ${cdr}")<br />
</pre><br />
you get<br />
<pre><br />
car: hello;world;foo;bar<br />
cdr: <br />
</pre><br />
<br />
== LIST_LENGTH ==<br />
<br />
Here is a macro to get the length of a list.<br />
<br />
<pre><br />
MACRO(LIST_LENGTH var)<br />
SET(entries)<br />
FOREACH(e ${ARGN})<br />
SET(entries "${entries}.")<br />
ENDFOREACH(e)<br />
STRING(LENGTH ${entries} ${var})<br />
ENDMACRO(LIST_LENGTH)<br />
</pre><br />
<br />
If you use the LIST_LENGTH macro as follows<br />
<pre><br />
SET(MYLIST hello world foo bar)<br />
<br />
LIST_LENGTH(length ${MYLIST})<br />
MESSAGE("length: ${length}")<br />
</pre><br />
you get this output:<br />
<pre><br />
length: 4<br />
</pre><br />
<br />
== LIST_INDEX ==<br />
<br />
Sometimes you want to get a particular entry of a list. This macro lets you grab the <math>n^\mathrm{th}</math> entry in a list (indexed from 1).<br />
<pre><br />
MACRO(LIST_INDEX var index)<br />
SET(list . ${ARGN})<br />
FOREACH(i RANGE 1 ${index})<br />
CDR(list ${list})<br />
ENDFOREACH(i)<br />
CAR(${var} ${list})<br />
ENDMACRO(LIST_INDEX)<br />
</pre><br />
<br />
If you use LIST_INDEX with the following commands<br />
<pre><br />
SET(MYLIST hello world foo bar)<br />
<br />
LIST_INDEX(first 1 ${MYLIST})<br />
LIST_INDEX(second 2 ${MYLIST})<br />
LIST_INDEX(third 3 ${MYLIST})<br />
LIST_INDEX(fourth 4 ${MYLIST})<br />
MESSAGE("first: ${first}")<br />
MESSAGE("second: ${second}")<br />
MESSAGE("third: ${third}")<br />
MESSAGE("fourth: ${fourth}")<br />
</pre><br />
you get this output:<br />
<pre><br />
first: hello<br />
second: world<br />
third: foo<br />
fourth: bar<br />
</pre><br />
<br />
== LIST_CONTAINS ==<br />
<br />
Sometimes you just want to know if a list contains a particular entry.<br />
<br />
<pre><br />
MACRO(LIST_CONTAINS var value)<br />
SET(${var})<br />
FOREACH (value2 ${ARGN})<br />
IF (${value} STREQUAL ${value2})<br />
SET(${var} TRUE)<br />
ENDIF (${value} STREQUAL ${value2})<br />
ENDFOREACH (value2)<br />
ENDMACRO(LIST_CONTAINS)<br />
</pre><br />
<br />
Here are some simple examples of using LIST_CONTAINS.<br />
<pre><br />
SET(MYLIST hello world foo bar)<br />
<br />
LIST_CONTAINS(contains foo ${MYLIST})<br />
IF (contains)<br />
MESSAGE("MYLIST contains foo")<br />
ENDIF (contains)<br />
<br />
LIST_CONTAINS(contains baz ${MYLIST})<br />
IF (NOT contains)<br />
MESSAGE("MYLIST does not contain baz")<br />
ENDIF (NOT contains)<br />
</pre><br />
The result of the previous examples is:<br />
<pre><br />
MYLIST contains foo<br />
MYLIST does not contain baz<br />
</pre><br />
<br />
== LIST_FILTER ==<br />
<br />
<pre><br />
# LIST_FILTER(<list> <regexp_var> [<regexp_var> ...]<br />
# [OUTPUT_VARIABLE <variable>])<br />
# Removes items from <list> which do not match any of the specified<br />
# regular expressions. An optional argument OUTPUT_VARIABLE<br />
# specifies a variable in which to store the matched items instead of<br />
# updating <list><br />
# As regular expressions can not be given to macros (see bug #5389), we pass<br />
# variable names whose content is the regular expressions.<br />
# Note that this macro requires PARSE_ARGUMENTS macro, available here:<br />
# http://www.cmake.org/Wiki/CMakeMacroParseArguments<br />
MACRO(LIST_FILTER)<br />
PARSE_ARGUMENTS(LIST_FILTER "OUTPUT_VARIABLE" "" ${ARGV})<br />
# Check arguments.<br />
LIST(LENGTH LIST_FILTER_DEFAULT_ARGS LIST_FILTER_default_length)<br />
IF(${LIST_FILTER_default_length} EQUAL 0)<br />
MESSAGE(FATAL_ERROR "LIST_FILTER: missing list variable.")<br />
ENDIF(${LIST_FILTER_default_length} EQUAL 0)<br />
IF(${LIST_FILTER_default_length} EQUAL 1)<br />
MESSAGE(FATAL_ERROR "LIST_FILTER: missing regular expression variable.")<br />
ENDIF(${LIST_FILTER_default_length} EQUAL 1)<br />
# Reset output variable<br />
IF(NOT LIST_FILTER_OUTPUT_VARIABLE)<br />
SET(LIST_FILTER_OUTPUT_VARIABLE "LIST_FILTER_internal_output")<br />
ENDIF(NOT LIST_FILTER_OUTPUT_VARIABLE)<br />
SET(${LIST_FILTER_OUTPUT_VARIABLE})<br />
# Extract input list from arguments<br />
LIST(GET LIST_FILTER_DEFAULT_ARGS 0 LIST_FILTER_input_list)<br />
LIST(REMOVE_AT LIST_FILTER_DEFAULT_ARGS 0)<br />
FOREACH(LIST_FILTER_item ${${LIST_FILTER_input_list}})<br />
FOREACH(LIST_FILTER_regexp_var ${LIST_FILTER_DEFAULT_ARGS})<br />
FOREACH(LIST_FILTER_regexp ${${LIST_FILTER_regexp_var}})<br />
IF(${LIST_FILTER_item} MATCHES ${LIST_FILTER_regexp})<br />
LIST(APPEND ${LIST_FILTER_OUTPUT_VARIABLE} ${LIST_FILTER_item})<br />
ENDIF(${LIST_FILTER_item} MATCHES ${LIST_FILTER_regexp})<br />
ENDFOREACH(LIST_FILTER_regexp ${${LIST_FILTER_regexp_var}})<br />
ENDFOREACH(LIST_FILTER_regexp_var)<br />
ENDFOREACH(LIST_FILTER_item)<br />
# If OUTPUT_VARIABLE is not specified, overwrite the input list.<br />
IF(${LIST_FILTER_OUTPUT_VARIABLE} STREQUAL "LIST_FILTER_internal_output")<br />
SET(${LIST_FILTER_input_list} ${${LIST_FILTER_OUTPUT_VARIABLE}})<br />
ENDIF(${LIST_FILTER_OUTPUT_VARIABLE} STREQUAL "LIST_FILTER_internal_output")<br />
ENDMACRO(LIST_FILTER)<br />
</pre><br />
<br />
Here is a use-case of the two signatures:<br />
<pre><br />
SET(sources foo.c foo.cc foo.cpp foo.cxx foo.h foo.hh foo.hxx foo.hpp foo.hcc)<br />
SET(re_header ".+\\.h$" ".+\\.hh$")<br />
SET(re_inline ".+\\.hxx$" ".+\\.hpp$")<br />
SET(re_impl ".+\\.c+" ".+\\.hcc$")<br />
LIST_FILTER(sources re_header re_inline OUTPUT_VARIABLE headers)<br />
LIST_FILTER(sources re_impl)<br />
FOREACH(var sources headers)<br />
MESSAGE(STATUS "content of variable \"${var}\":")<br />
FOREACH(elt ${${var}})<br />
MESSAGE(STATUS " ${elt}")<br />
ENDFOREACH(elt)<br />
ENDFOREACH(var)<br />
</pre><br />
<br />
Then you get the following output:<br />
<pre><br />
-- content of variable "sources":<br />
-- foo.c<br />
-- foo.cc<br />
-- foo.cpp<br />
-- foo.cxx<br />
-- foo.hcc<br />
-- content of variable "headers":<br />
-- foo.h<br />
-- foo.hh<br />
-- foo.hxx<br />
-- foo.hpp<br />
</pre><br />
<br />
Note that <tt>LIST_FILTER</tt> requires the macro [[CMakeMacroParseArguments|PARSE_ARGUMENTS]].<br />
<br />
== Using CMake LIST Command ==<br />
<br />
The following code is based on the macros presented above:<br />
<pre><br />
SET(MYLIST hello world foo bar)<br />
<br />
CAR(car ${MYLIST})<br />
<br />
CDR(cdr ${MYLIST})<br />
<br />
LIST_LENGTH(length ${MYLIST})<br />
<br />
LIST_INDEX(first 1 ${MYLIST})<br />
LIST_INDEX(second 2 ${MYLIST})<br />
LIST_INDEX(third 3 ${MYLIST})<br />
LIST_INDEX(fourth 4 ${MYLIST})<br />
<br />
LIST_CONTAINS(contains_foo foo ${MYLIST})<br />
LIST_CONTAINS(contains_baz baz ${MYLIST})<br />
</pre><br />
<br />
The previous code could have been implemented using the CMake LIST command (CMake 2.4+) as shown below. Note, however, that the LIST(FIND ...) is available in CMake 2.4.7+.<br />
<br />
<pre><br />
SET(MYLIST hello world foo bar)<br />
<br />
LIST(GET MYLIST 0 car)<br />
<br />
SET(cdr ${MYLIST})<br />
LIST(REMOVE_AT cdr 0)<br />
<br />
LIST(LENGTH MYLIST length)<br />
<br />
LIST(GET MYLIST 0 first)<br />
LIST(GET MYLIST 1 second)<br />
LIST(GET MYLIST 2 third)<br />
LIST(GET MYLIST 3 fourth)<br />
<br />
LIST(FIND MYLIST foo contains_foo)<br />
LIST(FIND MYLIST baz contains_baz)<br />
</pre><br />
<br />
The output of the variables in both cases is:<br />
<pre><br />
MESSAGE("car: ${car}")<br />
MESSAGE("cdr: ${cdr}")<br />
MESSAGE("length: ${length}")<br />
MESSAGE("first: ${first}")<br />
MESSAGE("second: ${second}")<br />
MESSAGE("third: ${third}")<br />
MESSAGE("fourth: ${fourth}")<br />
MESSAGE("contains_foo: ${contains_foo}")<br />
MESSAGE("contains_baz: ${contains_baz}")<br />
--<br />
car: hello<br />
cdr: world;foo;bar<br />
length: 4<br />
first: hello<br />
second: world<br />
third: foo<br />
fourth: bar<br />
contains_foo: 2 # for LIST_CONTAINS this is TRUE<br />
contains_baz: -1 # for LIST_CONTAINS this is empty; which evaluates to false<br />
</pre><br />
<br />
Note that the CMake LIST command also provides additional flexibility, such as APPEND, INSERT, SORT, REVERSE, etc. Type<br />
<pre><br />
cmake --help-command LIST<br />
</pre><br />
for the current usage information.<br />
<br />
-----<br />
[[CMake_User_Contributed_Macros|Back]]<br />
<br />
{{CMake/Template/Footer}}<br />
[[Category:CMakeMacro]]</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMakeTestInline&diff=14476CMakeTestInline2009-01-16T07:01:44Z<p>Plowman: </p>
<hr />
<div>[[CMake_User_Contributed_Macros|Back]]<br />
<br />
This handy test is from Jack Kelly on the cmake email list.<br />
<br />
Here is a minimal working example. It tests the inline keyword, then __inline__ and then __inline. When it finds one that works, it will ADD_DEFINITIONS(-Dinline=${KEYWORD}) and if none work, it will ADD_DEFINITIONS(-Dinline=). <br />
<br />
<pre><br />
# Inspired from /usr/share/autoconf/autoconf/c.m4<br />
FOREACH(KEYWORD "inline" "__inline__" "__inline")<br />
IF(NOT DEFINED C_INLINE)<br />
TRY_COMPILE(C_HAS_${KEYWORD} "${GPUIT_BINARY_DIR}"<br />
"${GPUIT_SOURCE_DIR}/test_inline.c"<br />
COMPILE_DEFINITIONS "-Dinline=${KEYWORD}")<br />
IF(C_HAS_${KEYWORD})<br />
SET(C_INLINE TRUE)<br />
ADD_DEFINITIONS("-Dinline=${KEYWORD}")<br />
ENDIF(C_HAS_${KEYWORD})<br />
ENDIF(NOT DEFINED C_INLINE)<br />
ENDFOREACH(KEYWORD)<br />
IF(NOT DEFINED C_INLINE)<br />
ADD_DEFINITIONS("-Dinline=")<br />
ENDIF(NOT DEFINED C_INLINE)<br />
</pre><br />
<br />
You also need this file in your source directory.<br />
<br />
<pre><br />
/* Test source lifted from /usr/share/autoconf/autoconf/c.m4 */<br />
typedef int foo_t;<br />
static inline foo_t static_foo(){return 0;}<br />
foo_t foo(){return 0;}<br />
int main(int argc, char *argv[]){return 0;}<br />
</pre><br />
<br />
[[Category:CMake]]</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake:MacOSXLinkerAndXCodeStuff&diff=14475CMake:MacOSXLinkerAndXCodeStuff2009-01-16T07:01:04Z<p>Plowman: </p>
<hr />
<div>=Building multiple configurations with XCode=<br />
<br />
If you do release and debug builds with XCode for frameworks, XCode will create completely separate frameworks for each<br />
configuration (e.g. Release and Debug). This is how CMake supports different configurations in XCode.<br />
<br />
There is an additional mechanism how this can be done. In the configuration dialog "Build variants" can be created, the default variant is "normal". When adding an additional name to this list, the library will be built in an additional variant and the name will be appended to the library name.<br />
E.g. if you add "profile" to the list, additionally to the library "foolib" now also "foolib_profile" will be created within the same framework. To get different settings/compiler flags/etc. for this version, XCode variables have to be defined for this build variant. They have the same name as the normal XCode variables, but have again the name appended:<br />
<br />
<pre><br />
BUILD_VARIANTS ="normal debug"<br />
OTHER_CFLAGS_debug=" -DMY_DEBUG=1 -DDEBUG=1 -gfull -O0 -fno-inline"<br />
OTHER_CFLAGS_normal=" -DMY_DEBUG=0 -DNODEBUG=1 -gfull -O3"<br />
</pre><br />
<br />
When building something which links to that framework, the normal name is used when building. When that application starts, by default it will load the normal variant. If the developer wants to use the "profile" variant, he has to set the DYLD_IMAGE_SUFFIX environment variable accordingly. So if DYLD_IMAGE_SUFFIX is set to "_profile", the application will get "foolib_profile". The same mechanism is used in the original OSX frameworks, there are "debug" variants of the frameworks available. This means if DYLD_IMAGE_SUFFIX is set to "_debug", an application will get the debug versions of the OSX libs and the debug version of "foolib" (if it exists). If the developer wants only debug versions of his own libs then he has to use a different variant name.<br />
<br />
=Versions in frameworks=<br />
<br />
Frameworks have version directories, usually version "A" with the symbolic link "Current" pointing to it.<br />
When an application is linked to a framework using "-framework Foo", then the link "Current" is used but the link destination is recorded in the application, so that when the application starts it doesn't matter to which version "Current" points.<br />
<br />
If there are two versions, "A" and "B" in a framework, and "Current" points to B, but a developer wants to build his application against version "A", the dylib_file option has to be used for gcc:<br />
<pre><br />
gcc -o Prog3 -dylib_file Foo.framework/Versions/B/Foo:Foo.framework/Versions/A/Foo -framework Foo<br />
</pre><br />
<br />
Alternatively the library inside the framework could be used directly:<br />
<pre><br />
gcc -o Prog3 Foo.framework/Versions/A/Foo<br />
</pre><br />
<br />
=dylib_compatibility_version and dylib_current_version=<br />
<br />
dylib_current_version is the current version of a dyld library (equivalent to the full versioned name of a so library). dylib_compatibility_version is the version to which the current version is compatible. I.e. the current version 1.2.3 could be compatible down to version 1.0.0 (or any other version before it, e.g. 0.5.3). This is somewhat similar to the SOVERSION of an so library, where a different SO version means a really different version of the library, but with the two dyld versions this can be used much more fine grained.<br />
So if an executable is linked against a dyld library with compatibility version 1.0.0, but when executing the linker finds only a current version 0.9.0 the app will not start.<br />
<br />
[[Category::CMake]]</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake_Emacs_mode_patch_for_comment_formatting&diff=14474CMake Emacs mode patch for comment formatting2009-01-16T07:00:31Z<p>Plowman: Replacing page with 'The latest cmake-mode.el file can be found [http://public.kitware.com/cgi-bin/viewcvs.cgi/Docs/cmake-mode.el?root=CMake&view=markup here].
Category:CMake'</p>
<hr />
<div>The latest cmake-mode.el file can be found [http://public.kitware.com/cgi-bin/viewcvs.cgi/Docs/cmake-mode.el?root=CMake&view=markup here].<br />
<br />
[[Category:CMake]]</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMakeUserFindClanLib&diff=14473CMakeUserFindClanLib2009-01-16T06:58:08Z<p>Plowman: </p>
<hr />
<div>[[CMake_User_Contributed_Macros|Back]]<br />
-----<br />
# - Find ClanLib<br />
# ClanLib is a cross platform SDK geared toward making games. It is<br />
# available from http://clanlib.org.<br />
#<br />
# The following are defined by this module:<br />
# ClanLib_FOUND - TRUE if ClanLib was found<br />
# ClanLib_INCLUDE_DIRS - Directory containing the ClanLib headers<br />
# ClanLib_LIBRARIES - If invoked via FIND_PACKAGE(ClanLib COMPONENTS ...),<br />
# will only contain the libraries matching each component.<br />
# otherwise, it will contain all ClanLib libraries found.<br />
# For the components Core, App, Display, GL, GUI, GUIStyleSilver, MikMod,<br />
# Network, SDL, Signals, Sound and Vorbis, the following variables are set:<br />
# ClanLib_${COMPONENT}_LIBRARY - Full path to the component's library.<br />
IF(ClanLib_INCLUDE_DIRS)<br />
SET(ClanLib_FIND_QUIETLY TRUE)<br />
ENDIF(ClanLib_INCLUDE_DIRS)<br />
<br />
IF(NOT ClanLib_FIND_COMPONENTS)<br />
SET(ClanLib_FIND_COMPONENTS<br />
App<br />
Display<br />
GL<br />
GUI<br />
GUIStyleSilver<br />
MikMod<br />
Network<br />
SDL<br />
Signals<br />
Sound<br />
Vorbis)<br />
ENDIF(NOT ClanLib_FIND_COMPONENTS)<br />
<br />
MACRO(ClanLib_MSG MSG)<br />
IF(NOT ClanLib_FIND_QUIETLY)<br />
MESSAGE(STATUS ${MSG})<br />
ENDIF(NOT ClanLib_FIND_QUIETLY)<br />
ENDMACRO(ClanLib_MSG)<br />
<br />
MACRO(ClanLib_ERR MSG)<br />
IF(ClanLib_FIND_REQUIRED)<br />
MESSAGE(SEND_ERROR ${MSG})<br />
ELSE(ClanLib_FIND_REQUIRED)<br />
ClanLib_MSG(${MSG})<br />
ENDIF(ClanLib_FIND_REQUIRED)<br />
ENDMACRO(ClanLib_ERR)<br />
<br />
MACRO(ClanLib_FIND_COMPONENT COMPONENT)<br />
ClanLib_MSG("Checking for Clan${COMPONENT}")<br />
FIND_LIBRARY(ClanLib_${COMPONENT}_LIBRARY clan${COMPONENT}<br />
${CLANLIB_ROOT_DIR}/lib /lib /usr/lib /usr/local/lib<br />
DOC "Library name for clan${COMPONENT}.")<br />
IF(ClanLib_${COMPONENT}_LIBRARY)<br />
SET(ClanLib_${COMPONENT}_FOUND TRUE)<br />
ClanLib_MSG("Checking for Clan${COMPONENT} -- ${ClanLib_${COMPONENT}_LIBRARY}")<br />
ELSE(ClanLib_${COMPONENT}_LIBRARY)<br />
SET(ClanLib_${COMPONENT}_FOUND FALSE)<br />
IF(ClanLib_FIND_REQUIRED_${COMPONENT})<br />
ClanLib_ERR("Checking for Clan${COMPONENT} -- not found")<br />
ELSE(ClanLib_FIND_REQUIRED_${COMPONENT})<br />
ClanLib_MSG("Checking for Clan${COMPONENT} -- not found")<br />
ENDIF(ClanLib_FIND_REQUIRED_${COMPONENT})<br />
ENDIF(ClanLib_${COMPONENT}_LIBRARY)<br />
ENDMACRO(ClanLib_FIND_COMPONENT)<br />
<br />
ClanLib_MSG("Checking for ClanLib")<br />
<br />
FIND_PATH(ClanLib_INCLUDE_DIRS ClanLib/core.h<br />
${ClanLib_ROOT_DIR}/include ${ClanLib_ROOT_DIR}/include/ClanLib-0.8<br />
/usr/local/include /usr/local/include/ClanLib-0.8<br />
/usr/include /usr/include/ClanLib-0.8<br />
DOC "Where to find the ClanLib includes.")<br />
IF(ClanLib_INCLUDE_DIRS)<br />
ClanLib_MSG("Checking for ClanLib -- headers")<br />
ELSE(ClanLib_INCLUDE_DIRS)<br />
ClanLib_ERR("Checking for ClanLib -- headers not found")<br />
ENDIF(ClanLib_INCLUDE_DIRS)<br />
<br />
ClanLib_FIND_COMPONENT(Core)<br />
IF(ClanLib_INCLUDE_DIRS AND ClanLib_Core_LIBRARY)<br />
SET(ClanLib_FOUND TRUE)<br />
SET(ClanLib_LIBRARIES ${ClanLib_Core_LIBRARY})<br />
ELSE(ClanLib_INCLUDE_DIRS AND ClanLib_Core_LIBRARY)<br />
SET(ClanLib_FOUND FALSE)<br />
ENDIF(ClanLib_INCLUDE_DIRS AND ClanLib_Core_LIBRARY)<br />
<br />
ClanLib_MSG("Checking for other ClanLib components")<br />
FOREACH(COMPONENT ${ClanLib_FIND_COMPONENTS})<br />
ClanLib_FIND_COMPONENT(${COMPONENT})<br />
IF(ClanLib_${COMPONENT}_LIBRARY)<br />
LIST(APPEND ClanLib_LIBRARIES ${ClanLib_${COMPONENT}_LIBRARY})<br />
ENDIF(ClanLib_${COMPONENT}_LIBRARY)<br />
ENDFOREACH(COMPONENT)<br />
<br />
MARK_AS_ADVANCED(<br />
ClanLib_INCLUDE_DIRS<br />
ClanLib_App_LIBRARY<br />
ClanLib_Core_LIBRARY<br />
ClanLib_Display_LIBRARY<br />
ClanLib_GL_LIBRARY<br />
ClanLib_GUI_LIBRARY<br />
ClanLib_GUIStyleSilver_LIBRARY<br />
ClanLib_MikMod_LIBRARY<br />
ClanLib_Network_LIBRARY<br />
ClanLib_SDL_LIBRARY<br />
ClanLib_Signals_LIBRARY<br />
ClanLib_Sound_LIBRARY<br />
ClanLib_Vorbis_LIBRARY<br />
)<br />
-----<br />
[[CMake_User_Contributed_Macros|Back]]<br />
<br />
{{CMake/Template/Footer}}<br />
[[Category:FindModules]]</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMakeMacroLibtoolFile&diff=14472CMakeMacroLibtoolFile2009-01-16T06:57:52Z<p>Plowman: </p>
<hr />
<div>[[CMake_User_Contributed_Macros|Back]]<br />
<br />
This macro creates a libtool .la file for shared libraries or plugins. The first parameter is the target name of the library, the second parameter is the directory where it will be installed to. E.g. for a KDE 3.x module named "kfoo" the usage would be as follows:<br />
<br />
The macro GET_TARGET_PROPERTY_WITH_DEFAULT is helpful to handle properties with default values.<br />
<br />
ADD_LIBRARY(foo SHARED kfoo1.cpp kfoo2.cpp)<br><br />
CREATE_LIBTOOL_FILE(foo /lib/kde3)<br><br />
<br />
-----<br />
MACRO(GET_TARGET_PROPERTY_WITH_DEFAULT _variable _target _property _default_value)<br />
GET_TARGET_PROPERTY (${_variable} ${_target} ${_property})<br />
IF (${_variable} STREQUAL NOTFOUND)<br />
SET (${_variable} ${_default_value})<br />
ENDIF (${_variable} STREQUAL NOTFOUND)<br />
ENDMACRO (GET_TARGET_PROPERTY_WITH_DEFAULT)<br />
<br />
MACRO(CREATE_LIBTOOL_FILE _target _install_DIR)<br />
GET_TARGET_PROPERTY(_target_location ${_target} LOCATION)<br />
GET_TARGET_PROPERTY_WITH_DEFAULT(_target_static_lib ${_target} STATIC_LIB "")<br />
GET_TARGET_PROPERTY_WITH_DEFAULT(_target_dependency_libs ${_target} LT_DEPENDENCY_LIBS "")<br />
GET_TARGET_PROPERTY_WITH_DEFAULT(_target_current ${_target} LT_VERSION_CURRENT 0)<br />
GET_TARGET_PROPERTY_WITH_DEFAULT(_target_age ${_target} LT_VERSION_AGE 0)<br />
GET_TARGET_PROPERTY_WITH_DEFAULT(_target_revision ${_target} LT_VERSION_REVISION 0)<br />
GET_TARGET_PROPERTY_WITH_DEFAULT(_target_installed ${_target} LT_INSTALLED yes)<br />
GET_TARGET_PROPERTY_WITH_DEFAULT(_target_shouldnotlink ${_target} LT_SHOULDNOTLINK yes)<br />
GET_TARGET_PROPERTY_WITH_DEFAULT(_target_dlopen ${_target} LT_DLOPEN "")<br />
GET_TARGET_PROPERTY_WITH_DEFAULT(_target_dlpreopen ${_target} LT_DLPREOPEN "")<br />
GET_FILENAME_COMPONENT(_laname ${_target_location} NAME_WE)<br />
GET_FILENAME_COMPONENT(_soname ${_target_location} NAME)<br />
SET(_laname ${_laname}.la)<br />
FILE(WRITE ${_laname} "# ${_laname} - a libtool library file, generated by cmake \n")<br />
FILE(APPEND ${_laname} "# The name that we can dlopen(3).\n")<br />
FILE(APPEND ${_laname} "dlname='${_soname}'\n")<br />
FILE(APPEND ${_laname} "# Names of this library\n")<br />
FILE(APPEND ${_laname} "library_names='${_soname}.${_target_current}.${_target_age}.${_target_revision} ${_soname}.${_target_current} ${_soname}'\n")<br />
FILE(APPEND ${_laname} "# The name of the static archive\n")<br />
FILE(APPEND ${_laname} "old_library='${_target_static_lib}'\n")<br />
FILE(APPEND ${_laname} "# Libraries that this one depends upon.\n")<br />
FILE(APPEND ${_laname} "dependency_libs='${_target_dependency_libs}'\n")<br />
FILE(APPEND ${_laname} "# Version information.\n")<br />
FILE(APPEND ${_laname} "current=${_target_current}\n")<br />
FILE(APPEND ${_laname} "age=${_target_age}\n")<br />
FILE(APPEND ${_laname} "revision=${_target_revision}\n")<br />
FILE(APPEND ${_laname} "# Is this an already installed library?\n")<br />
FILE(APPEND ${_laname} "installed=${_target_installed}\n")<br />
FILE(APPEND ${_laname} "# Should we warn about portability when linking against -modules?\n")<br />
FILE(APPEND ${_laname} "shouldnotlink=${_target_shouldnotlink}\n")<br />
FILE(APPEND ${_laname} "# Files to dlopen/dlpreopen\n")<br />
FILE(APPEND ${_laname} "dlopen='${_target_dlopen}'\n")<br />
FILE(APPEND ${_laname} "dlpreopen='${_target_dlpreopen}'\n")<br />
FILE(APPEND ${_laname} "# Directory that this library needs to be installed in:\n")<br />
FILE(APPEND ${_laname} "libdir='${CMAKE_INSTALL_PREFIX}${_install_DIR}'\n")<br />
INSTALL( FILES ${_laname} ${_soname}<br />
DESTINATION ${CMAKE_INSTALL_PREFIX}${_install_DIR})<br />
ENDMACRO(CREATE_LIBTOOL_FILE)<br />
-----<br />
[[CMake_User_Contributed_Macros|Back]]<br />
<br />
{{CMake/Template/Footer}}<br />
<br />
[[Category:CMakeMacro]]</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake:GNU_style_example&diff=14471CMake:GNU style example2009-01-16T06:57:30Z<p>Plowman: </p>
<hr />
<div>[[CMake#Tutorials|back to tutorials list]]<br />
<br />
GNU style projects typically have a main directory that contains ''include'' and ''src'' subdirectories. The ''src'' directory in turn contains directories for libraries and applications. This is a brief example of such a project using CMake. The heirarchy is as follows:<br />
<br />
* CMakeLists.txt<br />
* include<br />
** CMakeLists.txt<br />
** yo.h (the header file for the library)<br />
* src<br />
** CMakeLists.txt<br />
**app<br />
*** CMakeLists.txt<br />
*** hello.c (the application)<br />
**libyo<br />
*** CMakeLists.txt<br />
*** yo.c (the trivial library)<br />
<br />
The tarball for the project is available [http://www.bzflag.bz/~butler/cmake_ex.tgz here]<br />
<br />
<br />
[[Category:CMake]]</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake:ExportInterface&diff=14470CMake:ExportInterface2009-01-16T06:57:18Z<p>Plowman: </p>
<hr />
<div>=Export Interface for CMake Projects=<br />
<br />
This page documents a prototype design Alex and Brad created for exporting project information from a CMake project for use by outside projects.<br />
<br />
The EXPORT command is used to export information from a project build tree:<br />
<pre><br />
EXPORT(TARGETS <target> ...<br />
FILE somefile.cmake<br />
[PREFIX someprefix-]<br />
[APPEND]<br />
)<br />
</pre><br />
Export files generated for the build tree always have the full paths in the LOCATION properties of the IMPORT targets it creates.<br />
The contents are written immediately to the specified file, if APPEND is used then<br />
it will be appended if the file already exists. This way it can be mixed with FILE(WRITE ...)<br />
and EXPORT_LIBRARY_DEPENDENCIES() commands (... which probably doesn't make a lot of sense).<br />
<br />
The EXPORT mode of the INSTALL command is used to export information from an install tree:<br />
<pre><br />
INSTALL(<br />
EXPORT <export-name><br />
DESTINATION lib/myproj-1.2<br />
FILE <file-for-install>.cmake<br />
[PREFIX someprefix-]<br />
)<br />
INSTALL(<br />
TARGETS ...<br />
EXPORT <export-name> # attach these installed targest to the named export<br />
...)<br />
</pre><br />
<br />
Export files generated for the install tree have LOCATION properties that may be relative to the installation prefix.<br />
The INSTALL(EXPORT ...) command creates code at the top of the export script that computes the install prefix.<br />
If the export script is installed relative to the installation prefix it computes the prefix relative to its own location.<br />
If the export script is installed to an absolute path the installation prefix is hard-coded into the file.<br />
<br />
The INSTALL(TARGETS ... EXPORT ...) command creates code in the export script to specify the IMPORT target.<br />
If the destination is relative to the installation prefix the LOCATION property is specified relative to the install prefix set by the INSTALL(EXPORT ...) command. If the destination is to an absolute path that path is hard-coded into the LOCATION property.<br />
<br />
Here is an example for exporting a simple project from the build tree and install tree:<br />
<br />
<pre><br />
EXPORT( # anonymous export must be fully specified here<br />
TARGETS mylibA mylibB mygen<br />
FILE myproj-build.cmake<br />
PREFIX myproj-1.2-<br />
)<br />
INSTALL(<br />
TARGETS mylibA mylibB mygen<br />
EXPORT myproj-install<br />
RUNTIME DESTINATION bin<br />
ARCHIVE DESTINATION lib<br />
LIBRARY DESTINATION lib<br />
)<br />
INSTALL(<br />
EXPORT myproj-install<br />
DESTINATION lib/myproj-1.2<br />
FILE myproj-install.cmake<br />
PREFIX myproj-1.2-<br />
)<br />
</pre><br />
<br />
A more complicated project may be organized this way:<br />
<br />
<pre><br />
# CMakeLists.txt<br />
SET(EXPORT_FILE myproj-build.cmake)<br />
SET(EXPORT_PREFIX myproj-1.2- )<br />
<br />
INSTALL(<br />
EXPORT myproj-install<br />
DESTINATION lib/myproj-1.2<br />
FILE myproj-install.cmake<br />
PREFIX ${EXPORT_PREFIX})<br />
)<br />
<br />
# lib/CMakeLists.txt<br />
EXPORT( TARGETS mylibA mylibB<br />
FILE ${EXPORTS_FILE}<br />
PREFIX ${EXPORTS_PREFIX}<br />
)<br />
INSTALL(TARGETS mylibA mylibB<br />
EXPORT myproj-install<br />
RUNTIME DESTINATION bin<br />
ARCHIVE DESTINATION lib<br />
LIBRARY DESTINATION lib<br />
)<br />
<br />
# exe/CMakeLists.txt<br />
EXPORT(TARGETS mygen<br />
FILE ${EXPORTS_FILE}<br />
PREFIX ${EXPORTS_PREFIX}<br />
)<br />
INSTALL(TARGETS mygen<br />
EXPORT myproj-install<br />
DESTINATION bin<br />
)<br />
</pre><br />
<br />
The generated export .cmake file for the build tree will have content such as<br />
<br />
<pre><br />
add_library(myproj-1.2-mylibA IMPORT)<br />
set_target_properties(mylibA PROPERTIES<br />
LOCATION /path/to/libmylibA.a)<br />
<br />
add_library(myproj-1.2-mylibB IMPORT)<br />
set_target_properties(mylibB PROPERTIES<br />
LOCATION /path/to/libmylibB.a<br />
INTERFACE_LIBRARIES myproj-1.2-mylibA<br />
)<br />
<br />
add_executable(myproj-1.2-mygen IMPORT)<br />
set_target_properties(mylibB PROPERTIES<br />
LOCATION /path/to/mygen)<br />
</pre><br />
<br />
The generated export .cmake file for the install tree will have content such as<br />
<br />
<pre><br />
# PREFIX/lib/myproj-1.2/exports.cmake<br />
get_filename_component(myproj-1.2-_PREFIX "${CMAKE_CURRENT_LIST_FILE}" PATH)<br />
get_filename_component(myproj-1.2-_PREFIX "${myproj-1.2-_PREFIX}" PATH)<br />
get_filename_component(myproj-1.2-_PREFIX "${myproj-1.2-_PREFIX}" PATH)<br />
add_library(myproj-1.2-mylibA IMPORT)<br />
set_target_properties(mylibA PROPERTIES<br />
LOCATION ${myproj-1.2-_PREFIX}/lib/libmylibA.a)<br />
<br />
add_library(myproj-1.2-mylibB IMPORT)<br />
set_target_properties(mylibB PROPERTIES<br />
LOCATION ${myproj-1.2-_PREFIX}/lib/libmylibB.a<br />
INTERFACE_LIBRARIES myproj-1.2-mylibA<br />
)<br />
<br />
add_executable(myproj-1.2-mygen IMPORT)<br />
set_target_properties(mylibB PROPERTIES<br />
LOCATION ${myproj-1.2-_PREFIX}/bin/mygen)<br />
</pre><br />
<br />
<br />
<blockquote><br />
Alex, just writing down thoughts: <br />
In the install() commands above the COMPONENT feature is unused.<br />
<pre><br />
INSTALL(TARGETS mygen<br />
EXPORT myproj-install<br />
DESTINATION bin<br />
COMPONENT Runtime<br />
)<br />
</pre><br />
<br />
I think both COMPONENT and EXPORT are used to create groups of installed targets. Maybe the EXPORT keyword is not required but instead INSTALL(EXPORT ... ) could use the COMPONENTS ?<br />
<br />
I think the typical use case for COMPONENT is to split packages into Runtime and Development. The Development component will include headers, static libraries, import libraries and cmake files.<br />
It may contain eventual code generators and tools, but they might also be in the Runtime component.<br />
<br />
One problem is that the different parts of a shared library will typically be in different components.<br />
Maybe this could be ignored and the library could be exported if any of its parts (ARCHIVE, RUNTIME, LIBRARY) is in the given COMPONENT ?<br />
Let's say the ARCHIVE part of a library is in the Development component, and I export the Development component, then this library will also be exported.<br />
<br />
But then this library will also be exported if the Runtime component is exported, since its RUNTIME part should belong to the Runtime component. OTOH, exporting a Runtime component doesn't make a lot of sense, because if you import something you are developing, so it must be development related stuff.<br />
<br />
Then again, a code generator executable should belong to the Development component, but its DESTINATION will be specified in the RUNTIME part, while the destination of the dll part of a library will also be in the RUNTIME part but it should belong to the Runtime component. This may be slightly confusing if one INSTALL(TARGETS ...) command is used for libraries, executables and "development" executables.<br />
<br />
So if such code generators belong to the Development component, and this component is exported, this will mean that also all the library targets will end up in the exported file, which will be good for the general case.<br />
When cross compiling it would probably be better if only the executables would go in the exported file, because the libraries aren't of any use then.<br />
<br />
So a third component DevelopmentTools might be a good idea, which would contain just these executables.<br />
Then when creating a regular development package two components would have to be installed, Development and DevelopmentTools. I think this is currently not supported by the generated cmake_install.cmake scripts, don't know about cpack.<br />
<br />
This could then also be added to the EXPORT() command, so that there is not only EXPORT(TARGETS ...), but also EXPORT(COMPONENT ...)<br />
<br />
</blockquote><br />
<br />
[[Category:CMake]]</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake_Performance_Tips&diff=14469CMake Performance Tips2009-01-16T06:56:38Z<p>Plowman: </p>
<hr />
<div>While CMake itself is already very fast, there are some things you can do to ensure works<br />
as fast as possible.<br />
<br />
==Build it with optimization enabled==<br />
<br />
Ok, this is obvious, but anyway. Let's say you build CMake yourself without any special settings, e.g.<br />
<pre><br />
$ cmake ..<br />
$ make<br />
</pre><br />
<br />
If you do it this way, you will get a CMake with optimizations turned off.<br />
There are different ways to get an optimized build. You can select one of the predefined build types:<br />
<pre><br />
$ cmake -DCMAKE_BUILD_TYPE=RELEASE ..<br />
$ make<br />
</pre><br />
Also possible are RELWITHDEBINFO and MINSIZEREL.<br />
<br />
or<br />
<br />
<pre><br />
$ export CXXFLAGS=-O2<br />
$ cmake ..<br />
$ make<br />
</pre><br />
<br />
or<br />
<br />
<pre><br />
$ export CXXFLAGS=-O2<br />
$ cmake ..<br />
$ make edit_cache (or ccmake ..)<br />
... edit CMAKE_CXX_FLAGS in the advanced view<br />
$ make<br />
</pre><br />
<br />
CMake built with optimizations enabled can give you an almost 50% performance boost (time for running<br />
CMake on VTK went down from 25 s to 14 s).<br />
<br />
==Use LIST(APPEND ...)==<br />
<br />
There are two ways to append values to a variable in CMake:<br />
<br />
<pre><br />
SET(myVar ${myVar} newItem)<br />
</pre><br />
<br />
and since CMake 2.4 there is the new LIST() command:<br />
<br />
<pre><br />
LIST(APPEND myVar newItem)<br />
</pre><br />
<br />
LIST(APPEND ...) is for large lists and appends much faster than using SET().<br />
<br />
[[Category:CMake]]</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMakeMacroForceAddFlags&diff=14468CMakeMacroForceAddFlags2009-01-16T06:55:25Z<p>Plowman: </p>
<hr />
<div>[[CMake_User_Contributed_Macros|Back]]<br />
<br />
I have several projects that depend on the presence of certain arguments to various flags. If the user accidentally removes them, I want to forcefully put them back in while preserving any additional arguments the user may have added. The following macro is helpful for doing this. The operation is similar to a set union, but I don't deal with duplicates in either set.<br />
<br />
<pre><br />
# This will add arguments not found in ${parameter} to the end. It<br />
# does not attempt to remove duplicate arguments already existing in<br />
# ${parameter}.<br />
<br />
MACRO(FORCE_ADD_FLAGS parameter)<br />
# Create a separated list of the arguments to loop over<br />
SET(p_list ${${parameter}})<br />
SEPARATE_ARGUMENTS(p_list)<br />
# Make a copy of the current arguments in ${parameter}<br />
SET(new_parameter ${${parameter}})<br />
# Now loop over each required argument and see if it is in our<br />
# current list of arguments.<br />
FOREACH(required_arg ${ARGN})<br />
# This helps when we get arguments to the function that are<br />
# grouped as a string:<br />
#<br />
# ["-O3 -g"] instead of [-O3 -g]<br />
SET(TMP ${required_arg}) #elsewise the Seperate command doesn't work)<br />
SEPARATE_ARGUMENTS(TMP)<br />
FOREACH(option ${TMP})<br />
# Look for the required argument in our list of existing arguments<br />
SET(found FALSE)<br />
FOREACH(p_arg ${p_list})<br />
IF (${p_arg} STREQUAL ${option})<br />
SET(found TRUE)<br />
ENDIF (${p_arg} STREQUAL ${option})<br />
ENDFOREACH(p_arg)<br />
IF(NOT found)<br />
# The required argument wasn't found, so we need to add it in.<br />
SET(new_parameter "${new_parameter} ${option}")<br />
ENDIF(NOT found)<br />
ENDFOREACH(option ${TMP})<br />
ENDFOREACH(required_arg ${ARGN})<br />
SET(${parameter} ${new_parameter} CACHE STRING "" FORCE)<br />
ENDMACRO(FORCE_ADD_FLAGS)<br />
</pre><br />
<br />
Here is an example script using the macro.<br />
<br />
<pre><br />
SET(flags "")<br />
<br />
MESSAGE("flags = ${flags}")<br />
MESSAGE("forcing: -g3 -msse")<br />
FORCE_ADD_FLAGS(flags -g3 -msse)<br />
MESSAGE("flags = ${flags}")<br />
<br />
MESSAGE("forcing: \"-msse -msse2\" -O3")<br />
FORCE_ADD_FLAGS(flags "-msse -msse2" -O3)<br />
MESSAGE("flags = ${flags}")<br />
<br />
MESSAGE("forcing: -g3")<br />
FORCE_ADD_FLAGS(flags -g3)<br />
MESSAGE("flags = ${flags}")<br />
</pre><br />
<br />
Here's the output.<br />
<br />
<pre><br />
flags =<br />
forcing: -g3 -msse<br />
flags = -g3 -msse<br />
forcing: "-msse -msse2" -O3<br />
flags = -g3 -msse -msse2 -O3<br />
forcing: -g3<br />
flags = -g3 -msse -msse2 -O3<br />
</pre><br />
<br />
Note that forcing a particular argument only adds it if it isn't already present and any previous arguments are left intact.<br />
<br />
[[Category:CMakeMacro]]</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CmakeBlueGene&diff=14467CmakeBlueGene2009-01-16T06:54:57Z<p>Plowman: </p>
<hr />
<div>= How to build software for IBM/BlueGene=<br />
<br />
BlueGene consists of two different types of nodes, the service node, which are more or less regular PowerPC Linux machines, and the actual compute nodes, which have the same processors, but run the "Compute Node Kernel" as operating system.<br />
Building software for the service nodes is not different than building software on any other Linux system.<br />
But to build software for the actual compute nodes, you need to cross compile. For C/C++ there are <br />
typically two toolchains you can use for the compute nodes:<br />
* the GNU gcc toolchain (powerpc-bgl-blrts-gnu-gcc)<br />
* the IBM XL toolchain (blrts_xlc)<br />
<br />
In order to use them with CMake you have to write a toolchain file, more on that below.<br />
<br />
== Writing the CMake toolchain file for the GNU toolchain ==<br />
<br />
For CMake to be able to crosscompile software, it requires you to write a toolchain file, which tells CMake<br />
some information about the toolchain.<br />
<br />
For the GNU toolchain on BlueGene it could look like like the following:<br />
<pre><br />
# the name of the target operating system<br />
SET(CMAKE_SYSTEM_NAME BlueGeneL)<br />
<br />
# set the compiler<br />
set(CMAKE_C_COMPILER /bgl/BlueLight/ppcfloor/blrts-gnu/bin/powerpc-bgl-blrts-gnu-gcc )<br />
set(CMAKE_CXX_COMPILER /bgl/BlueLight/ppcfloor/blrts-gnu/bin/powerpc-bgl-blrts-gnu-g++ )<br />
<br />
# set the search path for the environment coming with the compiler<br />
# and a directory where you can install your own compiled software<br />
set(CMAKE_FIND_ROOT_PATH<br />
/bgl/BlueLight/ppcfloor/<br />
/bgl/BlueLight/V1R3M2_140_2007-070424/ppc/blrts-gnu/powerpc-bgl-blrts-gnu/<br />
/bgl/BlueLight/V1R3M2_140_2007-070424/ppc/bglsys<br />
/home/alex/bgl-install<br />
)<br />
<br />
# adjust the default behaviour of the FIND_XXX() commands:<br />
# search headers and libraries in the target environment, search <br />
# programs in the host environment<br />
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)<br />
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)<br />
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)<br />
</pre><br />
<br />
Save this file as Toolchain-BlueGeneL-gcc.cmake to some location where you will put<br />
all your toolchain files, e.g. $HOME.<br />
As you can see CMAKE_FIND_ROOT_PATH is set to three directories coming with the toolchain, which contain the headers and libraries installed with the toolchain, and /home/alex/bgl-install/. <br />
This last directory is intended to hold <br />
other libraries you will compile for the compute nodes, they should be installed under this install prefix. This way the FIND_XXX() commands in CMake will find both the headers and libraries coming with the toolchain as well<br />
as additional libraries you have built for this platform.<br />
<br />
== Building the software for BlueGene/L with the GNU toolchain==<br />
<br />
Let's say you have the classical hello world software with a CMake based buildsystem and want to build this for now for your super computer.<br />
main.c:<br />
<pre><br />
#include <stdio.h><br />
<br />
int main()<br />
{<br />
printf("Hello world\n");<br />
return 0;<br />
}<br />
</pre><br />
<br />
CMakeLists.txt:<br />
<pre><br />
ADD_EXECUTABLE(hello main.c)<br />
</pre><br />
<br />
Then run CMake on it to generate the buildfiles, the important point is that you tell it to use the toochain file you just wrote:<br />
<pre><br />
~/src/helloworld/ $ mkdir build-gcc<br />
~/src/helloworld/ $ cd build-gcc<br />
~/src/helloworld/build-gcc/ $ cmake -DCMAKE_TOOLCHAIN_FILE=~/Toolchain-BlueGeneL-gcc.cmake -DCMAKE_INSTALL_PREFIX=/home/alex/bgl-install .. <br />
-- The C compiler identification is GNU<br />
-- The CXX compiler identification is GNU<br />
...<br />
-- Configuring done<br />
-- Generating done<br />
-- Build files have been written to: /home/alex/src/helloworld/build-gcc<br />
~/src/helloworld/build-gcc/ $ make<br />
Scanning dependencies of target hello<br />
[100%] Building C object CMakeFiles/hello.dir/main.o<br />
Linking C executable hello<br />
[100%] Built target hello<br />
</pre><br />
<br />
So that's all. It actually doesn't matter whether it's just a "hello world" or some complex piece of software,<br />
the only difference is the usage of the toolchain file. If the software has all required configure checks, it should just build also with this toolchain.<br />
To run this program, write an appropriate submit script and run it via llsubmit. If everything works out fine,<br />
you will get output files with one greeting from each of the processors of the compute node. :-)<br />
<br />
CMake can help you a bit with creating this script. Create a file like the following in the source directory and save it as run_job.ksh.in:<br />
<pre><br />
#!/bin/ksh<br />
# @ job_type = BlueGene<br />
# @ executable = /bgl/BlueLight/ppcfloor/bglsys/bin/mpirun<br />
# @ arguments = -cwd ${CMAKE_BINARY_DIR} -exe ${EXE_LOCATION} -mode VN<br />
# @ input = /home/alex/empty_file<br />
# @ output = ${CMAKE_BINARY_DIR}/output.$(jobid).out<br />
# @ error = ${CMAKE_BINARY_DIR}/output.$(jobid).err<br />
# @ initialdir = ${CMAKE_BINARY_DIR}<br />
# @ notify_user = alex.neundorf@kitware.com<br />
# @ notification = complete<br />
# @ wall_clock_limit = 01:05:00<br />
# @ restart = no<br />
# @ coschedule = no<br />
# @ bg_size = 128<br />
# @ queue<br />
</pre><br />
<br />
Then add the following code to you CMakeLists.txt:<br />
<pre><br />
get_target_property(EXE_LOCATION hello LOCATION)<br />
configure_file(run_job.ksh.in ${CMAKE_BINARY_DIR}/run_job.ksh)<br />
</pre><br />
<br />
When running CMake to create the Makefiles it will replace the directories and will create a working run_job.ksh<br />
in your build directory.<br />
<br />
==Using the IBM XL toolchain for building the software for BlueGene/L==<br />
<br />
The IBM XL toolchain can also be used with CMake on BlueGene/L.<br />
You have to write a separate toolchain file for it, the main difference to the one above is that <br />
the IBM compilers are used:<br />
<pre><br />
# the name of the target operating system<br />
SET(CMAKE_SYSTEM_NAME BlueGeneL)<br />
<br />
# set the compiler<br />
set(CMAKE_C_COMPILER /opt/ibmcmp/vac/bg/8.0/bin/blrts_xlc)<br />
set(CMAKE_CXX_COMPILER /opt/ibmcmp/vacpp/bg/8.0/bin/blrts_xlC)<br />
<br />
# set the search path for the environment coming with the compiler<br />
# and a directory where you can install your own compiled software<br />
set(CMAKE_FIND_ROOT_PATH<br />
/bgl/BlueLight/ppcfloor/<br />
/bgl/BlueLight/V1R3M2_140_2007-070424/ppc/bglsys<br />
/home/alex/bgl-install<br />
)<br />
<br />
# adjust the default behaviour of the FIND_XXX() commands:<br />
# search headers and libraries in the target environment, search <br />
# programs in the host environment<br />
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)<br />
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)<br />
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)<br />
</pre><br />
<br />
Save this file as Toolchain-BlueGeneL-xlc.cmake in the same directory where you saved the toolchain file for the GNU toolchain.<br />
Then create a new build directory and run CMake there:<br />
<pre><br />
~/src/helloworld/ $ mkdir build-xlc<br />
~/src/helloworld/ $ cd build-xlc<br />
~/src/helloworld/build-xlc/ $ cmake -DCMAKE_TOOLCHAIN_FILE=~/Toolchain-BlueGeneL-xlc.cmake -DCMAKE_INSTALL_PREFIX=/home/alex/bgl-install .. <br />
-- The C compiler identification is VisualAge<br />
-- The CXX compiler identification is VisualAge<br />
...<br />
-- Configuring done<br />
-- Generating done<br />
-- Build files have been written to: /home/alex/src/helloworld/build-xlc<br />
~/src/helloworld/build-xlc/ $ make<br />
Scanning dependencies of target hello<br />
[100%] Building C object CMakeFiles/hello.dir/main.o<br />
Linking C executable hello<br />
[100%] Built target hello<br />
</pre><br />
<br />
[[Category:CMake]]</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CmakeAdsp&diff=14466CmakeAdsp2009-01-16T06:54:24Z<p>Plowman: </p>
<hr />
<div>= How to use CMake to cross compile software with the ADSP cross compiler =<br />
<br />
== Install the cross compiler ==<br />
<br />
You can download an evaluation version of Analog Device VisualDSP 4.5 for Windows on http://www.analog.com.<br />
<br />
VisualDSP 4.5 provides cross compilers for the Blackfin, SHARC, TigerSHARC and ADSP-21xx processors.<br />
<br />
== Write a CMake toolchain file ==<br />
<br />
To be able to cross compile software, CMake requires you to write a toolchain file, which tells CMake<br />
some information about the toolchain.<br />
This example shows how to configure CMake to crosscompile for a Blackfin 533 (ADSP-BF533):<br />
<pre><br />
SET( CMAKE_SYSTEM_NAME Generic )<br />
<br />
# these are ADSP specific, so it makes sense to have them separated from CMAKE_SYSTEM_PROCESSOR<br />
SET( ADSP_PROCESSOR "ADSP-BF533" )<br />
SET( ADSP_PROCESSOR_SILICIUM_REVISION "0.5" )<br />
<br />
# specify the cross compiler<br />
SET( CMAKE_C_COMPILER ccblkfn )<br />
SET( CMAKE_CXX_COMPILER ccblkfn -c++ )<br />
<br />
SET( CMAKE_ASM_COMPILER easmBLKFN )<br />
</pre><br />
<br />
This example requires that the compiler '''ccblkfn''' and the linker '''easmBLKFN''' are in the path.<br />
<br />
Save this file as Toolchain-ADSP-Blackfin.cmake to some location where you will put<br />
all your toolchain files.<br />
<br />
== Building the software ==<br />
You have to choose which make to use: gmake provides by with VisualDSP4.5 or nmake (to install from Microsoft).<br />
<br />
If your CMakeLists.txt is in C:\src and you build from C:\build then:<br />
<br />
<pre><br />
cmake -DTOOLS_CHAIN_FILE=(location)\Toolchain-ADSP-Blackfin.cmake -G "NMake Makefiles" C:\src<br />
</pre><br />
<br />
[[Category:CMake]]</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake:How_To_Find_Installed_Software&diff=14465CMake:How To Find Installed Software2009-01-16T06:53:31Z<p>Plowman: </p>
<hr />
<div>{{CMake/Template/Obsolete}}<br />
The information in the '''How to write a FindFoo.cmake module''' section is somewhat dated.<br />
<br />
If your software uses external libraries (i.e. libraries not coming with your software), you don't know in advance where its headers and libraries will be located on the system where your software will be compiled.<br />
Depending on the location appropriate include directories and library search paths will have to be added to the compile commands.<br />
<br />
CMake helps you with this by providing so-called modules. Let's say you want to use the PNG-Library, here's how you would do this with cmake:<br />
<pre><br />
FIND_PACKAGE(PNG)<br />
<br />
IF(PNG_FOUND)<br />
INCLUDE_DIRECTORIES(${PNG_INCLUDE_DIR})<br />
<br />
ADD_EXECUTABLE(imageviewer main.c image.c)<br />
TARGET_LINK_LIBRARIES(imageviewer ${PNG_LIBRARY})<br />
<br />
ENDIF(PNG_FOUND)<br />
</pre><br />
<br />
Every module is provided in the form Find<name>.cmake, they are located in the CMake module directory, on UNIX usualy <tt>/usr/local/share/CMake/Modules/ </tt> It is then used in the CMakeLists.txt with the FIND_PACKAGE(<name>) command. For details see the regular CMake documentation.<br />
Every module will define the following variables:<br />
* <name>_FOUND<br />
* <name>_INCLUDE_DIR or <name>_INCLUDES<br />
* <name>_LIBRARY or <name>_LIBRARIES<br />
<br />
As you can see, with PNG_FOUND you can test whether the package you need has actually been found. If that's the case, you have to add the include directories and link to the libraries which make up the package, in this case PNG_INCLUDE_DIR and PNG_LIBRARIES.<br />
<br />
If the package is not optional but your software can't be built at all without the package, you should use the REQUIRED argument for FIND_PACKAGE(). This will have the effect that cmake will abort with an error if it can't find the software.<br />
<br />
Another way how you can deal with optional packages you can see here:<br />
<pre><br />
<br />
SET(mySources main.cpp viewer.cpp)<br />
SET(optionalSources)<br />
SET(optionalLibs)<br />
<br />
IF(JPEG_FOUND)<br />
SET(optionalSources ${optionalSources} jpegview.cpp)<br />
INCLUDE_DIRECTORIES( ${JPEG_INCLUDE_DIR} )<br />
SET(optionalLibs ${optionalLibs} ${JPEG_LIBRARIES} )<br />
ENDIF(JPEG_FOUND)<br />
<br />
IF(PNG_FOUND)<br />
SET(optionalSources ${optionalSources} pngview.cpp)<br />
INCLUDE_DIRECTORIES( ${PNG_INCLUDE_DIR} )<br />
SET(optionalLibs ${optionalLibs} ${PNG_LIBRARIES} )<br />
ENDIF(PNG_FOUND)<br />
<br />
ADD_EXECUTABLE(viewer ${mySources} ${optionalSources} )<br />
TARGET_LINK_LIBRARIES(viewer ${optionalLibs} )<br />
<br />
</pre><br />
<br />
This way you can organize your CMakeLists.txt and they should stay clean and readable.<br />
<br />
== What to do if cmake doesn't find the package although it exists on the system ? ==<br />
<br />
Let's say the PNG library hasn't been found. If that's the case, cmake apparently didn't look good enough :-)<br />
There are several things you can do about this. <br />
The simple method, which involves quite a lot of manual work, is to just tell cmake explicitly where the software is located. To do this, you have three options:<br />
* edit the file CMakeCache.txt and search for the entries named PNG_INCLUDE_DIR and PNG_LIBRARY. They will be set to NOTFOUND. Edit these entries and enter the correct path to the PNG include directory on your system, e.g. c:stuff/png/include/ and do the same for PNG_LIBRARY: c:/stuff/png/png.dll .Then save the file and run cmake again<br />
* you can use the cmake GUIs ccmake or CMakeSetup to enter these options. This is basically the same as the point above, but with a GUI.<br />
* you can tell cmake the correct values via the command line: cmake -DPNG_INCLUDE_DIR=c:/stuff/png/include -DPNG_LIBRARY=c:/stuff/png/png.dll<br />
<br />
There are also two environment variables which you can set to help cmake find the package. These are the variables CMAKE_INCLUDE_PATH and CMAKE_LIBRARY_PATH. You can set these to the directories where the additional headers and libraries are located and then cmake will find them if they are really there.<br />
<br />
== How to write a FindFoo.cmake module ==<br />
<br />
Let's say, you have a library named foo, i.e. the library file is called libfoo.so on UNIX and foo.dll on Windows. Now you want to use this library in a cmake-based software project. You probably want to write a FindFoo.cmake, so that you can simply do <br />
<pre><br />
FIND_PACKAGE(Foo) <br />
</pre><br />
<br />
in your CMakeLists.txt.<br />
Writing such a module is easy:<br />
* find out the name of a significant header<br />
* find out the name of the library, possibly it can have more than one name. (e.g. on Windows there might be a zlib.dll, which is a libz.so on UNIX)<br />
<br />
cmake provides the FIND_FILE(), FIND_LIBRARY(), FIND_PATH() and FIND_PROGRAM() commands for this task.<br />
So you can start and create a FindFoo.cmake:<br />
<pre><br />
FIND_PATH(FOO_INCLUDE_DIR foo.h /usr/include/foo /usr/local/include/foo)<br />
<br />
FIND_LIBRARY(FOO_LIBRARY NAMES foo PATH /usr/lib /usr/local/lib) <br />
<br />
IF (FOO_INCLUDE_DIR AND FOO_LIBRARY)<br />
SET(FOO_FOUND TRUE)<br />
ENDIF (FOO_INCLUDE_DIR AND FOO_LIBRARY)<br />
<br />
<br />
IF (FOO_FOUND)<br />
IF (NOT Foo_FIND_QUIETLY)<br />
MESSAGE(STATUS "Found Foo: ${FOO_LIBRARY}")<br />
ENDIF (NOT Foo_FIND_QUIETLY)<br />
ELSE (FOO_FOUND)<br />
IF (Foo_FIND_REQUIRED)<br />
MESSAGE(FATAL_ERROR "Could not find Foo")<br />
ENDIF (Foo_FIND_REQUIRED)<br />
ENDIF (FOO_FOUND)<br />
</pre><br />
<br />
The variables Foo_FIND_QUIETLY and Foo_FIND_REQUIRED get defined if FIND_PACKAGE() is called with the REQUIRED or QUIET parameters.<br />
<br />
In order to be able to use the newly written FindFoo package, the location of the FindFoo.cmake file must be added to the cmake modules list from within a CMakeLists.txt file as follows:<br />
<pre><br />
set(CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake_modules/")<br />
</pre><br />
Assuming that FindFoo.cmake exists within a directory called cmake_modules within the top-level source directory. Note that this does not overwrite the existing, default, module path, but rather augments the path with the new user-defined extensions.<br />
<br />
<br />
For more information, have a look at the cmake manpage and the modules which come with cmake, e.g. FindJPEG.cmake. In the cmake module directory you can also find a readme.txt, which contains some more guidelines for writing cmake modules.<br />
<br />
{{CMake/Template/Footer}}<br />
<br />
<br />
[[Category:Tutorials]]</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CmakeSdcc&diff=14464CmakeSdcc2009-01-16T06:50:59Z<p>Plowman: </p>
<hr />
<div>= How to use sdcc with CMake =<br />
<br />
SDCC is a free, retargettable, optimizing ANSI - C compiler for 8- and 16bit controllers, for more information<br />
visit http://sdcc.sourceforge.net. You can use CMake to generate build files for sdcc.<br />
<br />
MinGW is the GNU toolchain for Windows, it also exists as cross compiler under<br />
Linux (and probably other UNIXes). You can use it to build Windows software on Linux.<br />
<br />
== Installing sdcc ==<br />
<br />
If you want to build (static) libraries, you need sdcc 2.7.1 (not yet released as of June 2007) or newer or sdcc from svn.<br />
If you don't need libraries, you can also use older versions of sdcc.<br />
With Ubuntu/Debian you can simply install it using apt: "apt-get install sdcc". <br />
You can of course also build this toolchain from sources yourself, you can find instructions at<br />
http://sdcc.sourceforge.net/index.php#Download .<br />
<br />
== Writing a CMake toolchain file ==<br />
<br />
For CMake to be able to crosscompile software, it requires you to write a toolchain file, which tells CMake<br />
some information about the toolchain.<br />
For sdcc it will look like:<br />
<pre><br />
# the name of the target operating system<br />
SET(CMAKE_SYSTEM_NAME Generic)<br />
<br />
# which compilers to use for C and C++<br />
SET(CMAKE_C_COMPILER sdcc)<br />
<br />
# here is the target environment is located<br />
SET(CMAKE_FIND_ROOT_PATH /usr/share/sdcc /home/alex/sdcc-install )<br />
<br />
# adjust the default behaviour of the FIND_XXX() commands:<br />
# search headers and libraries in the target environment, search <br />
# programs in the host environment<br />
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)<br />
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)<br />
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)<br />
</pre><br />
<br />
Save this file as Toolchain-sdcc.cmake to some location where you will put<br />
all your toolchain files, e.g. $HOME.<br />
As you can see CMAKE_FIND_ROOT_PATH is set to /usr/share/sdcc, which contains the headers and libraries<br />
installed with sdcc, and /home/alex/sdcc-install/. This second directory is intended to hold <br />
other libraries you will compile using sdcc, they should be installed under this install prefix. This way<br />
the FIND_XXX() commands in CMake will find both the headers and libraries coming with the toolchain as well<br />
as additional libraries you have built for this platform.<br />
<br />
== Building the software with sdcc ==<br />
<br />
Let's say you have a very simple program with a CMake based buildsystem and want to build this using sdcc.<br />
main.c:<br />
<pre><br />
int main()<br />
{<br />
return 42;<br />
}<br />
</pre><br />
<br />
CMakeLists.txt:<br />
<pre><br />
ADD_EXECUTABLE(hello main.c)<br />
</pre><br />
<br />
Then run CMake on it to generate the buildfiles, the important point is that you tell it to use the toochain file you just wrote:<br />
<pre><br />
~/src/helloworld/ $ mkdir build<br />
~/src/helloworld/ $ cd build<br />
~/src/helloworld/build/ $ cmake -DCMAKE_TOOLCHAIN_FILE=~/Toolchain-sdcc.cmake ..<br />
-- Configuring done<br />
-- Generating done<br />
-- Build files have been written to: /home/alex/src/helloworld/build<br />
~/src/helloworld/build/ $ make<br />
Scanning dependencies of target hello<br />
[100%] Building C object CMakeFiles/hello.dir/main.rel<br />
Linking C executable hello.ihx<br />
[100%] Built target hello<br />
</pre><br />
<br />
So that's all. It actually doesn't matter whether it's just a "hello world" or some complex piece of software,<br />
the only difference is the usage of the toolchain file. If the software has all required configure checks (which is quite unlikely for 8/16 bit controller systems), it should just build also with this toolchain.<br />
<br />
== Building simple software with sdcc ==<br />
<br />
If you have a software which is simple to build (which doesn't say anything about the actual code), you don't really<br />
need the toolchain file. "Simple" means that there are no platform tests, especially no FIND_XXX() commands in the CMake files.<br />
This may be the case for many embedded projects. Then all you have to set is CMAKE_SYSTEM_NAME and CMAKE_C_COMPILER:<br />
<pre><br />
$ cmake -DCMAKE_SYSTEM_NAME=Generic -DCMAKE_C_COMPILER=sdcc <source dir><br />
</pre><br />
This is enough to select the correct toolchain and target platform. If the target platform has no operating system, <br />
"Generic" has to be used.<br />
<br />
[[Category:CMake]]</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake_Package&diff=14463CMake Package2009-01-16T06:50:23Z<p>Plowman: </p>
<hr />
<div>{{CMake/Template/Obsolete}}<br />
<br />
== Using CMake Package ==<br />
<br />
FIND_PACKAGE(CME)<br />
IF(CME_FOUND)<br />
INCLUDE(${CME_USE_FILE})<br />
# ... Use library ...<br />
ENDIF(CME_FOUND)<br />
<br />
== Setup CMake Package ==<br />
<br />
<pre><br />
#-----------------------------------------------------------------------------<br />
# CMEConfig.cmake - CME CMake configuration file for external projects.<br />
#<br />
# This file is configured by CME and used by the UseCME.cmake module<br />
# to load CME's settings for an external project.<br />
<br />
# The CME include file directories.<br />
SET(CME_INCLUDE_DIRS "@CMAKE_INSTALL_PREFIX@/include")<br />
<br />
# The CME library directories.<br />
SET(CME_LIBRARY_DIRS "@CMAKE_INSTALL_PREFIX@/lib")<br />
<br />
# The CME version number.<br />
SET(CME_VERSION_MAJOR "@CME_VERSION_MAJOR@")<br />
SET(CME_VERSION_MINOR "@CME_VERSION_MINOR@")<br />
<br />
# The location of the UseCME.cmake file.<br />
SET(CME_USE_FILE "@CMAKE_INSTALL_PREFIX@/lib/cme/UseCME.cmake")<br />
<br />
# The build settings file.<br />
SET(CME_BUILD_SETTINGS_FILE<br />
"@CMAKE_INSTALL_PREFIX@/lib/cme/CMEBuildSettings.cmake")<br />
<br />
# The CME library dependencies. These can be blocked by projects<br />
# not interested in linking to CME's library.<br />
IF(NOT CME_NO_LIBRARY_DEPENDS)<br />
INCLUDE("@CMAKE_INSTALL_PREFIX@/lib/cme/CMELibraryDepends.cmake")<br />
ENDIF(NOT CME_NO_LIBRARY_DEPENDS)<br />
<br />
# Additional project-specific configuration settings can be set here.<br />
</pre><br />
<br />
<pre><br />
#-----------------------------------------------------------------------------<br />
# CMakeLists.txt<br />
<br />
# Example project "CMake Export".<br />
PROJECT(CME)<br />
<br />
# Every project should have a version number.<br />
SET(CME_VERSION_MAJOR 1)<br />
SET(CME_VERSION_MINOR 0)<br />
<br />
# Example library.<br />
ADD_LIBRARY(cme cme.cxx)<br />
<br />
# Link to libm on unix for sqrt(). This is to demonstrate library<br />
# dependency chaining.<br />
IF(UNIX)<br />
TARGET_LINK_LIBRARIES(cme m)<br />
ENDIF(UNIX)<br />
<br />
# Create the CMEConfig.cmake file for installation.<br />
CONFIGURE_FILE(${CME_SOURCE_DIR}/CMEConfig.cmake.in<br />
${CME_BINARY_DIR}/CMEConfig.cmake @ONLY IMMEIDATE)<br />
<br />
# Save the compiler settings and library dependencies so another<br />
# project can import them.<br />
INCLUDE(${CMAKE_ROOT}/Modules/CMakeExportBuildSettings.cmake)<br />
CMAKE_EXPORT_BUILD_SETTINGS(${CME_BINARY_DIR}/CMEBuildSettings.cmake)<br />
EXPORT_LIBRARY_DEPENDENCIES(${CME_BINARY_DIR}/CMELibraryDepends.cmake)<br />
<br />
# Install targets. Make sure the paths configured into<br />
# CMEConfig.cmake match.<br />
INSTALL_TARGETS(/lib cme)<br />
INSTALL_FILES(/include .h cme)<br />
INSTALL_FILES(/lib/cme .cmake CMEBuildSettings CMELibraryDepends<br />
UseCME CMEConfig)<br />
</pre><br />
<br />
<pre><br />
#-----------------------------------------------------------------------------<br />
# UseCME.cmake<br />
#<br />
# This module is provided as CME_USE_FILE by CMEConfig.cmake. It can<br />
# be INCLUDEd in a project to load the needed compiler and linker<br />
# settings to use CME.<br />
#<br />
<br />
# Load the compiler settings used for CME.<br />
IF(CME_BUILD_SETTINGS_FILE)<br />
INCLUDE(${CMAKE_ROOT}/Modules/CMakeImportBuildSettings.cmake)<br />
CMAKE_IMPORT_BUILD_SETTINGS(${CME_BUILD_SETTINGS_FILE})<br />
ENDIF(CME_BUILD_SETTINGS_FILE)<br />
<br />
# Add include directories needed to use CME.<br />
INCLUDE_DIRECTORIES(${CME_INCLUDE_DIRS})<br />
<br />
# Add link directories needed to use CME.<br />
LINK_DIRECTORIES(${CME_LIBRARY_DIRS})<br />
</pre><br />
<br />
<br />
<pre><br />
/*--------------------------------------------------------------------------*/<br />
/* cme.cxx */<br />
#include <math.h><br />
double cme()<br />
{<br />
return sqrt(2);<br />
}<br />
</pre><br />
<br />
<br />
<pre><br />
/*--------------------------------------------------------------------------*/<br />
/* cme.h */<br />
#ifndef _cme_h<br />
#define _cme_h<br />
<br />
extern double cme();<br />
<br />
#endif<br />
</pre><br />
<br />
<br />
== Reference ==<br />
* http://public.kitware.com/pipermail/cmake/2003-March/003554.html<br />
<br />
[[Category:CMake]]</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CmakeEldk&diff=14462CmakeEldk2009-01-16T06:49:50Z<p>Plowman: </p>
<hr />
<div>= How to use a Linux-to-Linux cross compiling GNU toolchain =<br />
<br />
Linux is in widespread use in embedded systems and handheld devices. There are many commercial <br />
and non-commercial projects which provide cross compiling toolchains, one of these<br />
is [http://www.denx.de Denx], which offer the [http://www.denx.de/wiki/DULG/ELDK Embedded Linux Development Kit], <br />
short ELDK. ELDK supports PowerPC, ARM and MIPS as target systems, it consists of the cross compiling toolchains and<br />
the quite complete target environment.<br />
ELDK shouldn't be much different from other cross compiling toolchains, so the information presented here should be usable also for other Linux-to-Linux cross compiling toolchains.<br />
<br />
== Installing ELDK ==<br />
<br />
You can find installation instructions at http://www.denx.de/wiki/view/DULG/ELDKDownloadPowerPC , the<br />
packages are available at ftp://ftp.sunet.se/pub/Linux/distributions/eldk/ .<br />
E.g. if your target has a MIPS processor, you will download the files you can find in <br />
ftp://ftp.sunet.se/pub/Linux/distributions/eldk/4.1/mips-linux-x86/iso . The easiest way to use them is to mount<br />
these ISO files and then install ELDK using the ''install'' executable you will find there:<br />
<pre><br />
~/ $ mkdir mount-iso/<br />
~/ $ sudo mount -tiso9660 mips-2007-01-21.iso mount-iso/ -o loop<br />
~/ $ cd mount-iso/<br />
~/mount-iso/$ ./install -d /home/alex/eldk-mips/<br />
...<br />
Preparing... ########################################### [100%]<br />
1:appWeb-mips_4KCle ########################################### [100%]<br />
Done<br />
~/mount-iso/$ ls eldk-mips/<br />
bin eldk_init etc mips_4KC mips_4KCle usr var version<br />
</pre><br />
<br />
In eldk-mips/mips_4KC/ and eldk-mips/mips_4KCle/ the target environments have been installed, i.e. complete Linux<br />
filesystems for the target platforms. In eldk-mips/bin/, eldk-mips/usr/ etc. host side tools<br />
have been installed, so the cross compiler can be found in eldk-mips/usr/bin/mips-linux-gcc.<br />
<br />
<br />
== Writing a CMake toolchain file ==<br />
<br />
For CMake to be able to crosscompile software, it requires you to write a toolchain file, which tells CMake<br />
some information about the toolchain.<br />
With the examples used above it will look like:<br />
<pre><br />
# the name of the target operating system<br />
SET(CMAKE_SYSTEM_NAME Linux)<br />
<br />
# which C and C++ compiler to use<br />
SET(CMAKE_C_COMPILER /home/alex/eldk-mips/usr/bin/mips_4KC-gcc)<br />
SET(CMAKE_CXX_COMPILER /home/alex/eldk-mips/usr/bin/mips_4KC-g++)<br />
<br />
# here is the target environment located<br />
SET(CMAKE_FIND_ROOT_PATH /home/alex/eldk-mips/mips_4KC /home/alex/eldk-mips-extra-install )<br />
<br />
# adjust the default behaviour of the FIND_XXX() commands:<br />
# search headers and libraries in the target environment, search <br />
# programs in the host environment<br />
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)<br />
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)<br />
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)<br />
</pre><br />
<br />
Save this file as Toolchain-eldk-mips4KC.cmake to some location where you will put<br />
all your toolchain files, e.g. $HOME.<br />
<br />
== Building the software for ELDK ==<br />
<br />
Let's say you have the classical hello world software with a CMake based buildsystem and want to build this for ELDK.<br />
main.c:<br />
<pre><br />
include <stdio.h><br />
<br />
int main()<br />
{<br />
printf("Hello world\n");<br />
return 0;<br />
}<br />
</pre><br />
<br />
CMakeLists.txt:<br />
<pre><br />
ADD_EXECUTABLE(hello main.c)<br />
INSTALL(TARGETS hello DESTINATION bin)<br />
</pre><br />
<br />
Then run CMake on it to generate the buildfiles, the important point is that you tell it to use the toochain file you just wrote:<br />
<pre><br />
~/src/helloworld/ $ mkdir build<br />
~/src/helloworld/ $ cd build<br />
~/src/helloworld/build/ $ cmake -DCMAKE_TOOLCHAIN_FILE=~/Toolchain-eldk-mips4KC.cmake -DCMAKE_INSTALL_PREFIX=/home/alex/eldk-mips-extra-install ..<br />
-- Configuring done<br />
-- Generating done<br />
-- Build files have been written to: /home/alex/src/helloworld/build<br />
~/src/helloworld/build/ $ make<br />
Scanning dependencies of target hello<br />
[100%] Building C object CMakeFiles/hello.dir/main.o<br />
Linking C executable hello<br />
[100%] Built target hello<br />
~/src/helloworld/build/ $ make install<br />
...<br />
-- Installing /home/alex/eldk-mips-extra-install/bin/hello<br />
</pre><br />
<br />
So that's all. It actually doesn't matter whether it's just a "hello world" or some complex piece of software,<br />
the only difference is the usage of the toolchain file. If the software has all required configure checks, it should just<br />
build also for ELDK.<br />
<br />
[[Category:CMake]]</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMake_Package&diff=14461CMake Package2009-01-16T06:48:47Z<p>Plowman: </p>
<hr />
<div>{{Template/CMake/Obsolete}}<br />
<br />
== Using CMake Package ==<br />
<br />
FIND_PACKAGE(CME)<br />
IF(CME_FOUND)<br />
INCLUDE(${CME_USE_FILE})<br />
# ... Use library ...<br />
ENDIF(CME_FOUND)<br />
<br />
== Setup CMake Package ==<br />
<br />
<pre><br />
#-----------------------------------------------------------------------------<br />
# CMEConfig.cmake - CME CMake configuration file for external projects.<br />
#<br />
# This file is configured by CME and used by the UseCME.cmake module<br />
# to load CME's settings for an external project.<br />
<br />
# The CME include file directories.<br />
SET(CME_INCLUDE_DIRS "@CMAKE_INSTALL_PREFIX@/include")<br />
<br />
# The CME library directories.<br />
SET(CME_LIBRARY_DIRS "@CMAKE_INSTALL_PREFIX@/lib")<br />
<br />
# The CME version number.<br />
SET(CME_VERSION_MAJOR "@CME_VERSION_MAJOR@")<br />
SET(CME_VERSION_MINOR "@CME_VERSION_MINOR@")<br />
<br />
# The location of the UseCME.cmake file.<br />
SET(CME_USE_FILE "@CMAKE_INSTALL_PREFIX@/lib/cme/UseCME.cmake")<br />
<br />
# The build settings file.<br />
SET(CME_BUILD_SETTINGS_FILE<br />
"@CMAKE_INSTALL_PREFIX@/lib/cme/CMEBuildSettings.cmake")<br />
<br />
# The CME library dependencies. These can be blocked by projects<br />
# not interested in linking to CME's library.<br />
IF(NOT CME_NO_LIBRARY_DEPENDS)<br />
INCLUDE("@CMAKE_INSTALL_PREFIX@/lib/cme/CMELibraryDepends.cmake")<br />
ENDIF(NOT CME_NO_LIBRARY_DEPENDS)<br />
<br />
# Additional project-specific configuration settings can be set here.<br />
</pre><br />
<br />
<pre><br />
#-----------------------------------------------------------------------------<br />
# CMakeLists.txt<br />
<br />
# Example project "CMake Export".<br />
PROJECT(CME)<br />
<br />
# Every project should have a version number.<br />
SET(CME_VERSION_MAJOR 1)<br />
SET(CME_VERSION_MINOR 0)<br />
<br />
# Example library.<br />
ADD_LIBRARY(cme cme.cxx)<br />
<br />
# Link to libm on unix for sqrt(). This is to demonstrate library<br />
# dependency chaining.<br />
IF(UNIX)<br />
TARGET_LINK_LIBRARIES(cme m)<br />
ENDIF(UNIX)<br />
<br />
# Create the CMEConfig.cmake file for installation.<br />
CONFIGURE_FILE(${CME_SOURCE_DIR}/CMEConfig.cmake.in<br />
${CME_BINARY_DIR}/CMEConfig.cmake @ONLY IMMEIDATE)<br />
<br />
# Save the compiler settings and library dependencies so another<br />
# project can import them.<br />
INCLUDE(${CMAKE_ROOT}/Modules/CMakeExportBuildSettings.cmake)<br />
CMAKE_EXPORT_BUILD_SETTINGS(${CME_BINARY_DIR}/CMEBuildSettings.cmake)<br />
EXPORT_LIBRARY_DEPENDENCIES(${CME_BINARY_DIR}/CMELibraryDepends.cmake)<br />
<br />
# Install targets. Make sure the paths configured into<br />
# CMEConfig.cmake match.<br />
INSTALL_TARGETS(/lib cme)<br />
INSTALL_FILES(/include .h cme)<br />
INSTALL_FILES(/lib/cme .cmake CMEBuildSettings CMELibraryDepends<br />
UseCME CMEConfig)<br />
</pre><br />
<br />
<pre><br />
#-----------------------------------------------------------------------------<br />
# UseCME.cmake<br />
#<br />
# This module is provided as CME_USE_FILE by CMEConfig.cmake. It can<br />
# be INCLUDEd in a project to load the needed compiler and linker<br />
# settings to use CME.<br />
#<br />
<br />
# Load the compiler settings used for CME.<br />
IF(CME_BUILD_SETTINGS_FILE)<br />
INCLUDE(${CMAKE_ROOT}/Modules/CMakeImportBuildSettings.cmake)<br />
CMAKE_IMPORT_BUILD_SETTINGS(${CME_BUILD_SETTINGS_FILE})<br />
ENDIF(CME_BUILD_SETTINGS_FILE)<br />
<br />
# Add include directories needed to use CME.<br />
INCLUDE_DIRECTORIES(${CME_INCLUDE_DIRS})<br />
<br />
# Add link directories needed to use CME.<br />
LINK_DIRECTORIES(${CME_LIBRARY_DIRS})<br />
</pre><br />
<br />
<br />
<pre><br />
/*--------------------------------------------------------------------------*/<br />
/* cme.cxx */<br />
#include <math.h><br />
double cme()<br />
{<br />
return sqrt(2);<br />
}<br />
</pre><br />
<br />
<br />
<pre><br />
/*--------------------------------------------------------------------------*/<br />
/* cme.h */<br />
#ifndef _cme_h<br />
#define _cme_h<br />
<br />
extern double cme();<br />
<br />
#endif<br />
</pre><br />
<br />
<br />
== Reference ==<br />
* http://public.kitware.com/pipermail/cmake/2003-March/003554.html</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CTest:Submission_Issues&diff=14460CTest:Submission Issues2009-01-16T06:46:44Z<p>Plowman: </p>
<hr />
<div>{{CMake/Template/Obsolete}}<br />
<br />
CTest supports four submission methods:<br />
<br />
Dart Classic:<br />
* FTP with HTTP client initiated trigger<br />
* HTTP with HTTP client initiated trigger<br />
* SCP with server side trigger<br />
<br />
Dart2:<br />
* XML-RPC with no trigger<br />
<br />
<br />
The submission methods are configured by a set of variables, which should be set in CTestConfig.cmake in your source tree. For backward compatibility also DartConfig.cmake is supported, it has the same syntax as CTestConfig.cmake, except that the variables don't have the "CTEST_" prefix (e.g. DROP_METHOD instead of CTEST_DROP_METHOD).<br />
CMake will read this file and create a DartConfiguration.tcl with the respective settings in the build tree.<br />
<br />
<br />
==XML-RPC==<br />
<br />
Dart2 uses XML-RPC over HTTP to perform submission of data and does not require triggering.<br />
<br />
Example CTestConfig.cmake flags:<br />
<br />
SET (CTEST_DROP_METHOD "xmlrpc")<br />
SET (CTEST_DROP_SITE "http://www.na-mic.org:8081/")<br />
SET (CTEST_DROP_LOCATION "Insight")<br />
<br />
Example DartConfiguration.tcl flags:<br />
<br />
DropMethod: xmlrpc<br />
DropSite: http://www.na-mic.org:8081/<br />
DropLocation: Insight<br />
<br />
<br />
==HTTP==<br />
<br />
This is preferred submission method for the original Dart dashboards. It uses Hypertext Transfer Protocol's (HTTP) PUT option to send submission data to the server. Once data is uploaded, it uses HTTP to trigger the actual submission of the data to the dashboard.<br />
<br />
Example CTestConfig.cmake flags:<br />
<br />
SET (CTEST_DROP_METHOD "http")<br />
SET (CTEST_DROP_SITE "public.kitware.com")<br />
SET (CTEST_DROP_LOCATION "/cgi-bin/HTTPUploadDartFile.cgi")<br />
SET (CTEST_TRIGGER_SITE "http://${DROP_SITE}/cgi-bin/Submit-Random-TestingResults.cgi")<br />
<br />
Example DartConfiguration.tcl flags:<br />
<br />
DropMethod: http<br />
DropSite: public.kitware.com<br />
DropLocation: /cgi-bin/HTTPUploadDartFile.cgi<br />
TriggerSite: http://public.kitware.com/cgi-bin/Submit-Random-TestingResults.cgi<br />
<br />
<br />
==FTP==<br />
<br />
Default submission method for legacy purposes. This is the method original Dart preferred. It uses File Transfer Protocol (FTP) to send submission data to the server. Once data is uploaded, it uses HTTP to trigger the actual submission of the data to the dashboard. <br />
<br />
Example CTestConfig.cmake flags:<br />
<br />
SET (CTEST_DROP_METHOD "ftp")<br />
SET (CTEST_DROP_SITE "public.kitware.com")<br />
SET (CTEST_DROP_LOCATION "/incoming")<br />
SET (CTEST_DROP_SITE_USER "ftpuser")<br />
SET (CTEST_DROP_SITE_PASSWORD "public")<br />
SET (CTEST_TRIGGER_SITE "http://${DROP_SITE}/cgi-bin/Submit-Random-TestingResults.cgi")<br />
<br />
Example DartConfiguration.tcl flags:<br />
<br />
DropMethod: ftp<br />
DropSite: public.kitware.com<br />
DropLocation: /incoming<br />
DropSiteUser: ftpuser<br />
DropSitePassword: public<br />
TriggerSite: http://public.kitware.com/cgi-bin/Submit-Random-TestingResults.cgi<br />
<br />
==SCP== <br />
<br />
When security is important SCP submission method can be used.<br />
<br />
Example CTestConfig.cmake flags:<br />
<br />
SET (CTEST_DROP_METHOD "scp")<br />
SET (CTEST_DROP_SITE "public.kitware.com")<br />
SET (CTEST_DROP_LOCATION "/incoming")<br />
SET (CTEST_DROP_SITE_USER "ftpuser")<br />
<br />
Example DartConfiguration.tcl flags:<br />
<br />
DropMethod: scp<br />
DropSite: public.kitware.com<br />
DropLocation: /incoming<br />
DropSiteUser: someuser<br />
DropSitePassword: public<br />
TriggerSite: http://public.kitware.com/cgi-bin/Submit-Random-TestingResults.cgi<br />
ScpCommand: /usr/bin/scp<br />
<br />
This method requires external tool to do the actual transfer and does not perform the trigger. Trigger has to be done on the server. Example script that will do it is this:<br />
<br />
<pre><nowiki>#!/usr/bin/perl -ws<br />
#<br />
# Script that will move testing results from the project incomming<br />
# directory to the appropriate location for dashboard summarization. <br />
#<br />
###<br />
<br />
use File::Basename;<br />
use File::Copy;<br />
use File::Path;<br />
<br />
if ( $#ARGV < 0 )<br />
{<br />
die "No project specified";<br />
$project = "Xdmf";<br />
}<br />
$project = $ARGV[0];<br />
<br />
<br />
$dropLocation = "/projects/FTP/incoming/".$project;<br />
$destination = "/projects/".$project."/Testing/".$project."-Testing/Testing/HTML/TestingResults/Sites";<br />
<br />
opendir(DIR, $dropLocation) || die "Cannot open directory ".$dropLocation." - ".$!;<br />
@files = grep { ! /^\./ && -f "$dropLocation/$_" } readdir(DIR);<br />
closedir DIR;<br />
<br />
foreach $file (@files) {<br />
$xmlfile = $file;<br />
$xmlfile =~ s/%(..)/sprintf("%c", hex($1))/g; # unquote %-quoted<br />
<br />
print "Processing file: ".$xmlfile."\n";<br />
<br />
$fullPathToIncomingXMLFile = $dropLocation . "/" . $xmlfile;<br />
if (-e $fullPathToIncomingXMLFile) {<br />
# file exists, so lets move it<br />
<br />
# first, translate the xml filename to a directory path<br />
$xmlfile =~ s|___|/|g;<br />
<br />
# for security reasons, disallow any file with ".." in the user <br />
# specified path to keep people from storing files just anywhere in<br />
# the host directory structure<br />
$securityCheck = $xmlfile;<br />
if ( ($securityCheck =~ /\.\./) ) {<br />
print "For security reasons, $xmlfile cannot be accepted.\n";<br />
exit;<br />
}<br />
<br />
# construct destination path and filename<br />
$fullPathToDestinationXMLFile = $destination . "/" . $xmlfile;<br />
mkpath( dirname( $fullPathToDestinationXMLFile ) );<br />
<br />
# now copy the file to destination<br />
move( $fullPathToIncomingXMLFile, $fullPathToDestinationXMLFile);<br />
<br />
print "$xmlfile submission successful.\n";<br />
}<br />
else {<br />
# specified file does not exist<br />
print "$xmlfile submission failed. $xmlfile is not in the dropbox.\n";<br />
}<br />
<br />
}</nowiki></pre><br />
<br />
{{CMake/Template/Footer}}</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMakeMacroMerge&diff=14459CMakeMacroMerge2009-01-16T06:45:14Z<p>Plowman: </p>
<hr />
<div>[[CMake_User_Contributed_Macros|Back]]<br />
<br />
'''NOTE:''' You can merge and sort lists using the SET() and LIST() command and no longer need this macro.<br />
<br />
set(FIRST_LIST a b c d i j k l)<br />
set(SECOND_LIST e f g h m n o p)<br />
set(COMPLETE_LIST ${FIRST_LIST} ${SECOND_LIST})<br />
list(SORT COMPLETE_LIST)<br />
# you can also remove duplicates<br />
list(REMOVE_DUPLICATES COMPLETE_LIST)<br />
<br />
----<br />
<br />
{{CMake/Template/Obsolete}}<br />
<br />
# This macro merges elements in sorted lists ALIST and BLIST and stored the result in OUTPUT<br />
MACRO(MERGE ALIST BLIST OUTPUT)<br />
SET(BTEMP ${BLIST})<br />
FOREACH(A ${ALIST})<br />
SET(SORTED)<br />
SET(UNINSERTED 1)<br />
FOREACH(B ${BTEMP})<br />
IF(${UNINSERTED})<br />
IF(${A} STRLESS ${B})<br />
SET(SORTED ${SORTED} ${A})<br />
SET(UNINSERTED 0)<br />
ENDIF(${A} STRLESS ${B})<br />
ENDIF(${UNINSERTED})<br />
SET(SORTED ${SORTED} ${B})<br />
ENDFOREACH(B ${BLIST})<br />
IF(${UNINSERTED})<br />
SET(SORTED ${SORTED} ${A})<br />
ENDIF(${UNINSERTED})<br />
SET(BTEMP ${SORTED})<br />
ENDFOREACH(A ${ALIST})<br />
SET(${OUTPUT} ${BTEMP})<br />
ENDMACRO(MERGE ALIST BLIST OUTPUT)<br />
<br />
# Here is an example that merges *.cpp files and *.h files into a single sorted list<br />
# This would be easier if FILE(GLOB...) properly matches "*.{cpp,h}"<br />
FILE(GLOB ALGEBRAIC_SRCS Implicit/Algebraic/*.cpp)<br />
FILE(GLOB ALGEBRAIC_H Implicit/Algebraic/*.h)<br />
MERGE("${ALGEBRAIC_H}" "${ALGEBRAIC_SRCS}" ALGEBRAIC_SRCS)<br />
<br />
[[CMake_User_Contributed_Macros|Back]]<br />
<br />
{{CMake/Template/Footer}}<br />
[[Category:CMakeMacro]]</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMakeMacroMerge&diff=14458CMakeMacroMerge2009-01-16T06:44:40Z<p>Plowman: </p>
<hr />
<div>[[CMake_User_Contributed_Macros|Back]]<br />
<br />
{{CMake/Template/Obsolete}}<br />
<br />
'''NOTE:''' You can merge and sort lists using the SET() and LIST() command:<br />
<br />
set(FIRST_LIST a b c d i j k l)<br />
set(SECOND_LIST e f g h m n o p)<br />
set(COMPLETE_LIST ${FIRST_LIST} ${SECOND_LIST})<br />
list(SORT COMPLETE_LIST)<br />
# you can also remove duplicates<br />
list(REMOVE_DUPLICATES COMPLETE_LIST)<br />
<br />
----<br />
<br />
# This macro merges elements in sorted lists ALIST and BLIST and stored the result in OUTPUT<br />
MACRO(MERGE ALIST BLIST OUTPUT)<br />
SET(BTEMP ${BLIST})<br />
FOREACH(A ${ALIST})<br />
SET(SORTED)<br />
SET(UNINSERTED 1)<br />
FOREACH(B ${BTEMP})<br />
IF(${UNINSERTED})<br />
IF(${A} STRLESS ${B})<br />
SET(SORTED ${SORTED} ${A})<br />
SET(UNINSERTED 0)<br />
ENDIF(${A} STRLESS ${B})<br />
ENDIF(${UNINSERTED})<br />
SET(SORTED ${SORTED} ${B})<br />
ENDFOREACH(B ${BLIST})<br />
IF(${UNINSERTED})<br />
SET(SORTED ${SORTED} ${A})<br />
ENDIF(${UNINSERTED})<br />
SET(BTEMP ${SORTED})<br />
ENDFOREACH(A ${ALIST})<br />
SET(${OUTPUT} ${BTEMP})<br />
ENDMACRO(MERGE ALIST BLIST OUTPUT)<br />
<br />
# Here is an example that merges *.cpp files and *.h files into a single sorted list<br />
# This would be easier if FILE(GLOB...) properly matches "*.{cpp,h}"<br />
FILE(GLOB ALGEBRAIC_SRCS Implicit/Algebraic/*.cpp)<br />
FILE(GLOB ALGEBRAIC_H Implicit/Algebraic/*.h)<br />
MERGE("${ALGEBRAIC_H}" "${ALGEBRAIC_SRCS}" ALGEBRAIC_SRCS)<br />
<br />
[[CMake_User_Contributed_Macros|Back]]<br />
<br />
{{CMake/Template/Footer}}<br />
[[Category:CMakeMacro]]</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMakeMacroAddCxxTest&diff=14457CMakeMacroAddCxxTest2009-01-16T06:36:15Z<p>Plowman: </p>
<hr />
<div>{{CMake/Template/Obsolete}}<br />
<br />
Please see [http://public.kitware.com/cgi-bin/viewcvs.cgi/Modules/FindCxxTest.cmake?root=CMake&view=markup FindCxxTest.cmake], currently in CMake CVS.<br />
<br />
== About ==<br />
<br />
This macro simplifies the inclusion of tests written using the [http://cxxtest.sourceforge.net/ CxxTest testing framework].<br />
<br />
Python is required to generate the test source files on the developer machine.<br />
However, since the generated source files will be placed on the source directory<br />
where the macro is called, there is no need for the end user to have Python<br />
in order to build and run the tests.<br />
<br />
== Definition ==<br />
<br />
Some preamble code:<br />
<pre><br />
# Make sure testing is enabled<br />
ENABLE_TESTING()<br />
<br />
# Use Python interpreter<br />
FIND_PACKAGE(PythonInterp)<br />
</pre><br />
<br />
You need to specify the path to the cxxtestgen.py script. Modify accordingly:<br />
<pre><br />
# Path to the cxxtestgen.py script<br />
SET(CXXTESTGEN ${CMAKE_SOURCE_DIR}/thirdparty/cxxtest/cxxtestgen.py)<br />
</pre><br />
<br />
The actual macro definition:<br />
<pre><br />
MACRO(ADD_CXXTEST NAME)<br />
IF(PYTHONINTERP_FOUND)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_SOURCE_DIR}/${NAME}.cpp<br />
COMMAND<br />
${PYTHON_EXECUTABLE} ${CXXTESTGEN}<br />
--runner=ErrorPrinter<br />
-o ${NAME}.cpp ${ARGN}<br />
DEPENDS ${ARGN}<br />
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}<br />
)<br />
ENDIF(PYTHONINTERP_FOUND)<br />
<br />
ADD_EXECUTABLE(${NAME} ${CMAKE_CURRENT_SOURCE_DIR}/${NAME}.cpp ${ARGN})<br />
<br />
ADD_TEST(${NAME} ${NAME})<br />
ENDMACRO(ADD_CXXTEST)<br />
<br />
</pre><br />
<br />
<br />
== Separate compilation ==<br />
<br />
The above macro generates a single source file for all input test headers. If by some reason you prefer separate compilation of each part, you may use the variation:<br />
<br />
<pre><br />
MACRO(ADD_CXXTEST_SEP NAME)<br />
IF(PYTHONINTERP_FOUND)<br />
# generate the parts<br />
FOREACH(_PART ${ARGN})<br />
GET_FILENAME_COMPONENT(_NAME ${_PART} NAME)<br />
GET_FILENAME_COMPONENT(_NAME_WE ${_PART} NAME_WE)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${_NAME_WE}.cpp<br />
COMMAND<br />
${PYTHON_EXECUTABLE} ${CXXTESTGEN}<br />
--part<br />
-o ${_NAME_WE}.cpp<br />
${_NAME}<br />
DEPENDS ${_PART}<br />
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}<br />
)<br />
ENDFOREACH(_PART)<br />
<br />
# generate the runner<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_SOURCE_DIR}/${NAME}_runner.cpp<br />
COMMAND<br />
${PYTHON_EXECUTABLE} ${CXXTESTGEN}<br />
--runner=ErrorPrinter --root<br />
-o ${NAME}_runner.cpp<br />
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}<br />
)<br />
ENDIF(PYTHONINTERP_FOUND)<br />
<br />
# enumerate all generated files<br />
SET(PARTS ${CMAKE_CURRENT_SOURCE_DIR}/${NAME}_runner.cpp)<br />
FOREACH(_PART ${ARGN})<br />
GET_FILENAME_COMPONENT(_PART_WE ${_PART} NAME_WE)<br />
SET(PARTS ${PARTS} ${_PART_WE}.cpp)<br />
ENDFOREACH(_PART)<br />
<br />
ADD_EXECUTABLE(${NAME} ${PARTS})<br />
<br />
ADD_TEST(${NAME} ${NAME})<br />
ENDMACRO(ADD_CXXTEST_SEP)<br />
</pre><br />
<br />
[[Category:CMake]]<br />
[[Category:CMakeMacro]]</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=Template:CMake/Template/Obsolete&diff=14456Template:CMake/Template/Obsolete2009-01-16T06:35:57Z<p>Plowman: </p>
<hr />
<div>'''CAUTION: The contents of this page may be obsolete'''<br><br />
[[Image:120px-Old_finnish_stop_sign.svg.png]]</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMakeUserUseLATEX_UseLATEX.cmake&diff=14455CMakeUserUseLATEX UseLATEX.cmake2009-01-16T06:30:40Z<p>Plowman: </p>
<hr />
<div>#[[CMakeUserUseLATEX| Back]]<br />
<br />
-----<br />
<br />
UseLATEX.cmake is now posted [[Media:UseLATEX.cmake|here]].<br />
<br />
-----<br />
<br />
#[[CMakeUserUseLATEX| Back]]<br />
<br />
{{CMake/Template/Footer}}<br />
[[Category:CMakeMacro]]</div>Plowmanhttps://public.kitware.com/Wiki/index.php?title=CMakeMacroGatherProjectFiles&diff=14454CMakeMacroGatherProjectFiles2009-01-16T06:27:46Z<p>Plowman: </p>
<hr />
<div>[[CMake_User_Contributed_Macros|Back]]<br />
<br />
This macro recursively collects the files from a project directory and caches the list for future use. Tailor the extensions that are included in the list according to your needs. <br />
<br />
-----<br />
<br />
# add extra sources to the defined project<br />
MACRO ( GatherProjectFiles ProjectName ProjectDir ProjectSources )<br />
<br />
#look for the cache file<br />
SET ( FoundCacheFile "FoundCacheFile-NOTFOUND" )<br />
FIND_FILE ( FoundCacheFile ${ProjectName}Sources.cmake PATHS ${CMAKE_CURRENT_BINARY_DIR} NO_DEFAULT_PATH NO_CMAKE_ENVIRONMENT_PATH NO_CMAKE_PATH NO_SYSTEM_ENVIRONMENT_PATH NO_CMAKE_SYSTEM_PATH)<br />
<br />
IF ( FoundCacheFile )<br />
# read cached file list<br />
MESSAGE ( STATUS " Found cache file ${FoundCacheFile}" )<br />
INCLUDE ( ${CMAKE_CURRENT_BINARY_DIR}/${ProjectName}Sources.cmake )<br />
<br />
ELSE ( FoundCacheFile )<br />
# get the file lists<br />
SET ( Dir ${CMAKE_HOME_DIRECTORY}/${ProjectDir} )<br />
<br />
# add your other extensions here (this could be probably done nicer)<br />
FILE ( GLOB_RECURSE DirSources ${Dir}/*.c ${Dir}/*.cpp ${Dir}/*.h ${Dir}/*.inl ${Dir}/*.rc ${Dir}/*.ico )<br />
<br />
# write cached file list<br />
MESSAGE ( STATUS " Generating ${ProjectName}Sources.cmake" )<br />
STRING ( CONFIGURE "@DirSources@" TempString @ONLY )<br />
STRING ( REPLACE ";" " " "DirSourcesAsString" "${TempString}" )<br />
CONFIGURE_FILE ( ${CMAKE_HOME_DIRECTORY}/CMake/SourceFilesTemplate.cmake.in ${CMAKE_CURRENT_BINARY_DIR}/${ProjectName}Sources.cmake @ONLY )<br />
<br />
ENDIF ( FoundCacheFile )<br />
SET ( "${ProjectSources}" ${DirSources} )<br />
ENDMACRO ( GatherProjectFiles )<br />
<br />
-----<br />
<br />
The template file (located in ''CMAKE_HOME_DIRECTORY\CMake\SourceFilesTemplate.cmake.in'') looks like this:<br />
<br />
# Cache source files<br />
<br />
# All sources<br />
SET ( DirSources @DirSourcesAsString@ )<br />
<br />
-----<br />
<br />
A typical use for this macro would be:<br />
<br />
GatherProjectFiles ( MyLib src/MyLib MyLibSources )<br />
ADD_LIBRARY (MyLib SHARED ${MyLibSources} )<br />
<br />
<br />
[[CMake_User_Contributed_Macros|Back]]<br />
<br />
{{CMake/Template/Footer}}<br />
[[Category:CMakeMacro]]</div>Plowman