[cmake-commits] king committed CMakeCommands.html 1.31 1.32
cmake-commits at cmake.org
cmake-commits at cmake.org
Mon Oct 30 09:39:59 EST 2006
Update of /cvsroot/CMake/CMakeWeb/HTML
In directory public:/mounts/ram/cvs-serv23214
Modified Files:
CMakeCommands.html
Log Message:
BUG: Do not update docs to a more recent version than the current release.
Index: CMakeCommands.html
===================================================================
RCS file: /cvsroot/CMake/CMakeWeb/HTML/CMakeCommands.html,v
retrieving revision 1.31
retrieving revision 1.32
diff -u -d -r1.31 -r1.32
--- CMakeCommands.html 28 Oct 2006 10:00:09 -0000 1.31
+++ CMakeCommands.html 30 Oct 2006 14:39:53 -0000 1.32
@@ -2,16 +2,16 @@
<ul>
<li>
<b><code>ADD_CUSTOM_COMMAND</code></b>: Add a custom build rule to the generated build system.<br>
- <p>There are two main signatures for ADD_CUSTOM_COMMAND The first signature is for adding a custom command to produce an output.<br><pre> ADD_CUSTOM_COMMAND(OUTPUT output1 [output2 ...]<br> COMMAND command1 [ARGS] [args1...]<br> [COMMAND command2 [ARGS] [args2...] ...]<br> [MAIN_DEPENDENCY depend]<br> [DEPENDS [depends...]]<br> [WORKING_DIRECTORY dir]<br> [COMMENT comment] [VERBATIM] [APPEND])<br></pre>
+ <p>There are two main signatures for ADD_CUSTOM_COMMAND The first signature is for adding a custom command to produce an output.<br><pre> ADD_CUSTOM_COMMAND(OUTPUT output1 [output2 ...]<br> COMMAND command1 [ARGS] [args1...]<br> [COMMAND command2 [ARGS] [args2...] ...]<br> [MAIN_DEPENDENCY depend]<br> [DEPENDS [depends...]]<br> [WORKING_DIRECTORY dir]<br> [COMMENT comment])<br></pre>
<p>This defines a new command that can be executed during the build process. The outputs named should be listed as source files in the target for which they are to be generated. Note that MAIN_DEPENDENCY is completely optional and is used as a suggestion to visual studio about where to hang the custom command. In makefile terms this creates a new target in the following form:<br><pre> OUTPUT: MAIN_DEPENDENCY DEPENDS<br> COMMAND<br></pre>
- <p>If more than one command is specified they will be executed in order. The optional ARGS argument is for backward compatibility and will be ignored.<br><p>The second signature adds a custom command to a target such as a library or executable. This is useful for performing an operation before or after building the target:<br><pre> ADD_CUSTOM_COMMAND(TARGET target<br> PRE_BUILD | PRE_LINK | POST_BUILD<br> COMMAND command1 [ARGS] [args1...]<br> [COMMAND command2 [ARGS] [args2...] ...]<br> [WORKING_DIRECTORY dir]<br> [COMMENT comment] [VERBATIM])<br></pre>
+ <p>If more than one command is specified they will be executed in order. The optional ARGS argument is for backward compatibility and will be ignored.<br><p>The second signature adds a custom command to a target such as a library or executable. This is useful for performing an operation before or after building the target:<br><pre> ADD_CUSTOM_COMMAND(TARGET target<br> PRE_BUILD | PRE_LINK | POST_BUILD<br> COMMAND command1 [ARGS] [args1...]<br> [COMMAND command2 [ARGS] [args2...] ...]<br> [WORKING_DIRECTORY dir]<br> [COMMENT comment])<br></pre>
<p>This defines a new command that will be associated with building the specified target. When the command will happen is determined by which of the following is specified:<br><pre> PRE_BUILD - run before all other dependencies<br> PRE_LINK - run after other dependencies<br> POST_BUILD - run after the target has been built<br></pre>
- <p>Note that the PRE_BUILD option is only supported on Visual Studio 7 or later. For all other generators PRE_BUILD will be treated as PRE_LINK.<br><p>If WORKING_DIRECTORY is specified the command will be executed in the directory given. If COMMENT is set, the value will be displayed as a message before the commands are executed at build time. If APPEND is specified the COMMAND and DEPENDS option values are appended to the custom command for the first output specified. There must have already been a previous call to this command with the same output. The COMMENT, WORKING_DIRECTORY, and MAIN_DEPENDENCY options are currently ignored when APPEND is given, but may be used in the future.<br><p>If VERBATIM is given then all the arguments to the commands will be passed exactly as specified no matter the build tool used. Note that one level of escapes is still used by the CMake language processor before ADD_CUSTOM_TARGET even sees the arguments. Use of VERBATIM is recommended as it enables correct behavior. When VERBATIM is not given the behavior is platform specific. In the future VERBATIM may be enabled by default. The only reason it is an option is to preserve compatibility with older CMake code.<br><p>If the output of the custom command is not actually created as a file on disk it should be marked as SYMBOLIC with SET_SOURCE_FILES_PROPERTIES.
+ <p>Note that the PRE_BUILD option is only supported on Visual Studio 7 or later. For all other generators PRE_BUILD will be treated as PRE_LINK. If WORKING_DIRECTORY is specified the command will be executed in the directory given.
</li>
<li>
<b><code>ADD_CUSTOM_TARGET</code></b>: Add a target with no output so it will always be built.<br>
- <pre> ADD_CUSTOM_TARGET(Name [ALL] [command1 [args1...]]<br> [COMMAND command2 [args2...] ...]<br> [DEPENDS depend depend depend ... ]<br> [WORKING_DIRECTORY dir]<br> [COMMENT comment] [VERBATIM])<br></pre>
- <p>Adds a target with the given name that executes the given commands. The target has no output file and is ALWAYS CONSIDERED OUT OF DATE even if the commands try to create a file with the name of the target. Use ADD_CUSTOM_COMMAND to generate a file with dependencies. By default nothing depends on the custom target. Use ADD_DEPENDENCIES to add dependencies to or from other targets. If the ALL option is specified it indicates that this target should be added to the default build target so that it will be run every time (the command cannot be called ALL). The command and arguments are optional and if not specified an empty target will be created. If WORKING_DIRECTORY is set, then the command will be run in that directory. If COMMENT is set, the value will be displayed as a message before the commands are executed at build time. Dependencies listed with the DEPENDS argument may reference files and outputs of custom commands created with ADD_CUSTOM_COMMAND.<br><p>If VERBATIM is given then all the arguments to the commands will be passed exactly as specified no matter the build tool used. Note that one level of escapes is still used by the CMake language processor before ADD_CUSTOM_TARGET even sees the arguments. Use of VERBATIM is recommended as it enables correct behavior. When VERBATIM is not given the behavior is platform specific. In the future VERBATIM may be enabled by default. The only reason it is an option is to preserve compatibility with older CMake code.
+ <pre> ADD_CUSTOM_TARGET(Name [ALL] [command1 [args1...]]<br> [COMMAND command2 [args2...] ...]<br> [DEPENDS depend depend depend ... ])<br> [WORKING_DIRECTORY dir]<br></pre>
+ <p>Adds a target with the given name that executes the given commands every time the target is built. If the ALL option is specified it indicates that this target should be added to the default build target so that it will be run every time (the command cannot be called ALL). The command and arguments are optional and if not specified an empty target will be created. If WORKING_DIRECTORY is set, then the command will be run in that directory. Dependencies listed with the DEPENDS argument may reference files and outputs of custom commands created with ADD_CUSTOM_COMMAND. Dependencies on other targets may be added using the ADD_DEPENDENCIES command.
</li>
<li>
<b><code>ADD_DEFINITIONS</code></b>: Adds -D define flags to the command line of C and C++ compilers.<br>
@@ -25,15 +25,15 @@
</li>
<li>
<b><code>ADD_EXECUTABLE</code></b>: Add an executable to the project using the specified source files.<br>
- <pre> ADD_EXECUTABLE(exename [WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL]<br> source1 source2 ... sourceN)<br></pre>
+ <pre> ADD_EXECUTABLE(exename [WIN32] [MACOSX_BUNDLE] source1<br> source2 ... sourceN)<br></pre>
<p>This command adds an executable target to the current directory. The executable will be built from the list of source files specified.<br><p>After specifying the executable name, WIN32 and/or MACOSX_BUNDLE can be specified. WIN32 indicates that the executable (when compiled on windows) is a windows app (using WinMain) not a console app (using main). The variable CMAKE_MFC_FLAG be used if the windows app uses MFC. This variable can be set to the following values:<br><pre> 0: Use Standard Windows Libraries<br> 1: Use MFC in a Static Library <br> 2: Use MFC in a Shared DLL <br></pre>
<p>MACOSX_BUNDLE indicates that when build on Mac OSX, executable should be in the bundle form. The MACOSX_BUNDLE also allows several variables to be specified:<br><pre> MACOSX_BUNDLE_INFO_STRING<br> MACOSX_BUNDLE_ICON_FILE<br> MACOSX_BUNDLE_GUI_IDENTIFIER<br> MACOSX_BUNDLE_LONG_VERSION_STRING<br> MACOSX_BUNDLE_BUNDLE_NAME<br> MACOSX_BUNDLE_SHORT_VERSION_STRING<br> MACOSX_BUNDLE_BUNDLE_VERSION<br> MACOSX_BUNDLE_COPYRIGHT<br></pre>
- <p>If EXCLUDE_FROM_ALL is given the target will not be built by default. It will be built only if the user explicitly builds the target or another target that requires the target depends on it.
+
</li>
<li>
<b><code>ADD_LIBRARY</code></b>: Add a library to the project using the specified source files.<br>
- <pre> ADD_LIBRARY(libname [SHARED | STATIC | MODULE] [EXCLUDE_FROM_ALL]<br> source1 source2 ... sourceN)<br></pre>
- <p>Adds a library target. SHARED, STATIC or MODULE keywords are used to set the library type. If the keyword MODULE appears, the library type is set to MH_BUNDLE on systems which use dyld. On systems without dyld, MODULE is treated like SHARED. If no keywords appear as the second argument, the type defaults to the current value of BUILD_SHARED_LIBS. If this variable is not set, the type defaults to STATIC.<br><p>If EXCLUDE_FROM_ALL is given the target will not be built by default. It will be built only if the user explicitly builds the target or another target that requires the target depends on it.
+ <pre> ADD_LIBRARY(libname [SHARED | STATIC | MODULE]<br> source1 source2 ... sourceN)<br></pre>
+ <p>Adds a library target. SHARED, STATIC or MODULE keywords are used to set the library type. If the keyword MODULE appears, the library type is set to MH_BUNDLE on systems which use dyld. On systems without dyld, MODULE is treated like SHARED. If no keywords appear as the second argument, the type defaults to the current value of BUILD_SHARED_LIBS. If this variable is not set, the type defaults to STATIC.
</li>
<li>
<b><code>ADD_SUBDIRECTORY</code></b>: Add a subdirectory to the build.<br>
@@ -43,7 +43,7 @@
<li>
<b><code>ADD_TEST</code></b>: Add a test to the project with the specified arguments.<br>
<pre> ADD_TEST(testname Exename arg1 arg2 ...)<br></pre>
- <p>If the ENABLE_TESTING command has been run, this command adds a test target to the current directory. If ENABLE_TESTING has not been run, this command does nothing. The tests are run by the testing subsystem by executing Exename with the specified arguments. Exename can be either an executable built by this project or an arbitrary executable on the system (like tclsh). The test will be run with the current working directory set to the CMakeList.txt files corresponding directory in the binary tree.
+ <p>If the ENABLE_TESTING command has been run, this command adds a test target to the current directory. If ENABLE_TESTING has not been run, this command does nothing. The tests are run by the testing subsystem by executing Exename with the specified arguments. Exename can be either an executable built by built by this project or an arbitrary executable on the system (like tclsh). The test will be run with the current working directory set to the CMakeList.txt files corresponding directory in the binary tree.
</li>
<li>
<b><code>AUX_SOURCE_DIRECTORY</code></b>: Find all source files in a directory.<br>
@@ -81,11 +81,6 @@
<p>See the IF command.
</li>
<li>
- <b><code>ELSEIF</code></b>: Starts the ELSEIF portion of an IF block.<br>
- <pre> ELSEIF(expression)<br></pre>
- <p>See the IF command.
- </li>
- <li>
<b><code>ENABLE_LANGUAGE</code></b>: Set a name for the entire project.<br>
<pre> ENABLE_LANGUAGE(languageName)<br></pre>
<p>This command enables support for the named language in CMake.
@@ -106,11 +101,6 @@
<p>See the IF command.
</li>
<li>
- <b><code>ENDMACRO</code></b>: Ends a list of commands in a MACRO block.<br>
- <pre> ENDMACRO(expression)<br></pre>
- <p>See the MACRO command.
- </li>
- <li>
<b><code>ENDWHILE</code></b>: Ends a list of commands in a WHILE block.<br>
<pre> ENDWHILE(expression)<br></pre>
<p>See the WHILE command.
@@ -122,7 +112,7 @@
</li>
<li>
<b><code>EXECUTE_PROCESS</code></b>: Execute one or more child processes.<br>
- <pre> EXECUTE_PROCESS(COMMAND <cmd1> [args1...]]<br> [COMMAND <cmd2> [args2...] [...]]<br> [WORKING_DIRECTORY <directory>]<br> [TIMEOUT <seconds>]<br> [RESULT_VARIABLE <variable>]<br> [OUTPUT_VARIABLE <variable>]<br> [ERROR_VARIABLE <variable>]<br> [INPUT_FILE <file>]<br> [OUTPUT_FILE <file>]<br> [ERROR_FILE <file>]<br> [OUTPUT_QUIET]<br> [ERROR_QUIET]<br> [OUTPUT_STRIP_TRAILING_WHITESPACE]<br> [ERROR_STRIP_TRAILING_WHITESPACE])<br></pre>
+ <pre> EXECUTE_PROCESS(COMMAND <cmd1> [args1...]]<br> [COMMAND <cmd2> [args2...] [...]]<br> [WORKING_DIRECTORY <directory>]<br> [TIMEOUT <seconds>]<br> [RESULT_VARIABLE <variable>]<br> [OUTPUT_VARIABLE <variable>]<br> [ERROR_VARIABLE <variable>]<br> [INPUT_FILE <file>]<br> [OUTPUT_FILE <file>]<br> [ERROR_FILE <file>]<br> [OUTPUT_QUIET]<br> [ERROR_QUIET])<br></pre>
<p>Runs the given sequence of one or more commands with the standard output of each process piped to the standard input of the next. A single standard error pipe is used for all processes. If WORKING_DIRECTORY is given the named directory will be set as the current working directory of the child processes. If TIMEOUT is given the child processes will be terminated if they do not finish in the specified number of seconds (fractions are allowed). If RESULT_VARIABLE is given the variable will be set to contain the result of running the processes. This will be an integer return code from the last child or a string describing an error condition. If OUTPUT_VARIABLE or ERROR_VARIABLE are given the variable named will be set with the contents of the standard output and standard error pipes respectively. If the same variable is named for both pipes their output will be merged in the order produced. If INPUT_FILE, OUTPUT_FILE, or ERROR_FILE is given the file named will be attached to the standard input of the first process, standard output of the last process, or standard error of all processes respectively. If OUTPUT_QUIET or ERROR_QUIET is given then the standard output or standard error results will be quietly ignored. If more than one OUTPUT_* or ERROR_* option is given for the same pipe the precedence is not specified. If no OUTPUT_* or ERROR_* options are given the output will be shared with the corresponding pipes of the CMake process itself.<br><p>The EXECUTE_PROCESS command is a newer more powerful version of EXEC_PROGRAM, but the old command has been kept for compatibility.
</li>
<li>
@@ -141,7 +131,7 @@
<b><code>FIND_FILE</code></b>: Find the full path to a file.<br>
<pre> FIND_FILE(<VAR> name1 path1 path2 ...)<br></pre>
<p>This is the short-hand signature for the command that is sufficient in many cases. It is the same as FIND_FILE(<VAR> name1 PATHS path2 path2 ...)<br><pre> FIND_FILE(<br> <VAR> <br> name | NAMES name1 [name2 ...]<br> PATHS path1 [path2 ... ENV var]<br> [PATH_SUFFIXES suffix1 [suffix2 ...]]<br> [DOC "cache documentation string"]<br> [NO_DEFAULT_PATH]<br> [NO_CMAKE_ENVIRONMENT_PATH]<br> [NO_CMAKE_PATH]<br> [NO_SYSTEM_ENVIRONMENT_PATH]<br> [NO_CMAKE_SYSTEM_PATH]<br> )<br></pre>
- <p>This command is used to find a full path to named file. A cache entry named by <VAR> is created to store the result of this command. If the full path to a file is found the result is stored in the variable and the search will not be repeated unless the variable is cleared. If nothing is found, the result will be <VAR>-NOTFOUND, and the search will be attempted again the next time FIND_FILE is invoked with the same variable. The name of the full path to a file that is searched for is specified by the names listed after the NAMES argument. Additional search locations can be specified after the PATHS argument. If ENV var is found in the PATHS section the environment variable var will be read and converted from a system environment variable to a cmake style list of paths. For example ENV PATH would be a way to list the system path variable. The argument after DOC will be used for the documentation string in the cache. PATH_SUFFIXES can be used to give sub directories that will be appended to the search paths.<br><p>If NO_DEFAULT_PATH is specified, then no additional paths are added to the search. If NO_DEFAULT_PATH is not specified, the search process is as follows:<br><p>1. Search cmake specific environment variables. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed.<br><pre> CMAKE_FRAMEWORK_PATH<br> CMAKE_APPBUNDLE_PATH<br> CMAKE_INCLUDE_PATH<br></pre>
+ <p>This command is used to find a full path to named file. A cache entry named by <VAR> is created to store the result of this command. If nothing is found, the result will be <VAR>-NOTFOUND. The name of the full path to a file that is searched for is specified by the names listed after the NAMES argument. Additional search locations can be specified after the PATHS argument. If ENV var is found in the PATHS section the environment variable var will be read and converted from a system environment variable to a cmake style list of paths. For example ENV PATH would be a way to list the system path variable. The argument after DOC will be used for the documentation string in the cache. PATH_SUFFIXES can be used to give sub directories that will be appended to the search paths.<br><p>If NO_DEFAULT_PATH is specified, then no additional paths are added to the search. If NO_DEFAULT_PATH is not specified, the search process is as follows:<br><p>1. Search cmake specific environment variables. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed.<br><pre> CMAKE_FRAMEWORK_PATH<br> CMAKE_APPBUNDLE_PATH<br> CMAKE_INCLUDE_PATH<br></pre>
<p>2. Search cmake variables with the same names as the cmake specific environment variables. These are intended to be used on the command line with a -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.<br><pre> CMAKE_FRAMEWORK_PATH<br> CMAKE_APPBUNDLE_PATH<br> CMAKE_INCLUDE_PATH<br></pre>
<p>3. Search the standard system environment variables. This can be skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.<br><pre> PATH<br> INCLUDE<br></pre>
<p>4. Search cmake variables defined in the Platform files for the current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed.<br><pre> CMAKE_SYSTEM_FRAMEWORK_PATH<br> CMAKE_SYSTEM_APPBUNDLE_PATH<br> CMAKE_SYSTEM_INCLUDE_PATH<br></pre>
@@ -154,7 +144,7 @@
<b><code>FIND_LIBRARY</code></b>: Find a library.<br>
<pre> FIND_LIBRARY(<VAR> name1 path1 path2 ...)<br></pre>
<p>This is the short-hand signature for the command that is sufficient in many cases. It is the same as FIND_LIBRARY(<VAR> name1 PATHS path2 path2 ...)<br><pre> FIND_LIBRARY(<br> <VAR> <br> name | NAMES name1 [name2 ...]<br> PATHS path1 [path2 ... ENV var]<br> [PATH_SUFFIXES suffix1 [suffix2 ...]]<br> [DOC "cache documentation string"]<br> [NO_DEFAULT_PATH]<br> [NO_CMAKE_ENVIRONMENT_PATH]<br> [NO_CMAKE_PATH]<br> [NO_SYSTEM_ENVIRONMENT_PATH]<br> [NO_CMAKE_SYSTEM_PATH]<br> )<br></pre>
- <p>This command is used to find a library. A cache entry named by <VAR> is created to store the result of this command. If the library is found the result is stored in the variable and the search will not be repeated unless the variable is cleared. If nothing is found, the result will be <VAR>-NOTFOUND, and the search will be attempted again the next time FIND_LIBRARY is invoked with the same variable. The name of the library that is searched for is specified by the names listed after the NAMES argument. Additional search locations can be specified after the PATHS argument. If ENV var is found in the PATHS section the environment variable var will be read and converted from a system environment variable to a cmake style list of paths. For example ENV PATH would be a way to list the system path variable. The argument after DOC will be used for the documentation string in the cache. PATH_SUFFIXES can be used to give sub directories that will be appended to the search paths.<br><p>If NO_DEFAULT_PATH is specified, then no additional paths are added to the search. If NO_DEFAULT_PATH is not specified, the search process is as follows:<br><p>1. Search cmake specific environment variables. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed.<br><pre> CMAKE_FRAMEWORK_PATH<br> CMAKE_APPBUNDLE_PATH<br> CMAKE_LIBRARY_PATH<br></pre>
+ <p>This command is used to find a library. A cache entry named by <VAR> is created to store the result of this command. If nothing is found, the result will be <VAR>-NOTFOUND. The name of the library that is searched for is specified by the names listed after the NAMES argument. Additional search locations can be specified after the PATHS argument. If ENV var is found in the PATHS section the environment variable var will be read and converted from a system environment variable to a cmake style list of paths. For example ENV PATH would be a way to list the system path variable. The argument after DOC will be used for the documentation string in the cache. PATH_SUFFIXES can be used to give sub directories that will be appended to the search paths.<br><p>If NO_DEFAULT_PATH is specified, then no additional paths are added to the search. If NO_DEFAULT_PATH is not specified, the search process is as follows:<br><p>1. Search cmake specific environment variables. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed.<br><pre> CMAKE_FRAMEWORK_PATH<br> CMAKE_APPBUNDLE_PATH<br> CMAKE_LIBRARY_PATH<br></pre>
<p>2. Search cmake variables with the same names as the cmake specific environment variables. These are intended to be used on the command line with a -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.<br><pre> CMAKE_FRAMEWORK_PATH<br> CMAKE_APPBUNDLE_PATH<br> CMAKE_LIBRARY_PATH<br></pre>
<p>3. Search the standard system environment variables. This can be skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.<br><pre> PATH<br> LIB<br></pre>
<p>4. Search cmake variables defined in the Platform files for the current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed.<br><pre> CMAKE_SYSTEM_FRAMEWORK_PATH<br> CMAKE_SYSTEM_APPBUNDLE_PATH<br> CMAKE_SYSTEM_LIBRARY_PATH<br></pre>
@@ -165,14 +155,14 @@
</li>
<li>
<b><code>FIND_PACKAGE</code></b>: Load settings for an external project.<br>
- <pre> FIND_PACKAGE(<name> [major.minor] [QUIET] [NO_MODULE]<br> [[REQUIRED|COMPONENTS] [componets...]])<br></pre>
- <p>Finds and loads settings from an external project. <name>_FOUND will be set to indicate whether the package was found. Settings that can be used when <name>_FOUND is true are package-specific. The package is found through several steps. Directories listed in CMAKE_MODULE_PATH are searched for files called "Find<name>.cmake". If such a file is found, it is read and processed by CMake, and is responsible for finding the package. This first step may be skipped by using the NO_MODULE option. If no such file is found, it is expected that the package is another project built by CMake that has a "<name>Config.cmake" file. A cache entry called <name>_DIR is created and is expected to be set to the directory containing this file. If the file is found, it is read and processed by CMake to load the settings of the package. If <name>_DIR has not been set during a configure step, the command will generate an error describing the problem unless the QUIET argument is specified. If <name>_DIR has been set to a directory not containing a "<name>Config.cmake" file, an error is always generated. If REQUIRED is specified and the package is not found, a FATAL_ERROR is generated and the configure step stops executing. A package-specific list of components may be listed after the REQUIRED option, or after the COMPONENTS option if no REQUIRED option is given.
+ <pre> FIND_PACKAGE(<name> [major.minor] [QUIET]<br> [REQUIRED [componets...]])<br></pre>
+ <p>Finds and loads settings from an external project. <name>_FOUND will be set to indicate whether the package was found. Settings that can be used when <name>_FOUND is true are package-specific. The package is found through several steps. Directories listed in CMAKE_MODULE_PATH are searched for files called "Find<name>.cmake". If such a file is found, it is read and processed by CMake, and is responsible for finding the package. If no such file is found, it is expected that the package is another project built by CMake that has a "<name>Config.cmake" file. A cache entry called <name>_DIR is created and is expected to be set to the directory containing this file. If the file is found, it is read and processed by CMake to load the settings of the package. If <name>_DIR has not been set during a configure step, the command will generate an error describing the problem unless the QUIET argument is specified. If <name>_DIR has been set to a directory not containing a "<name>Config.cmake" file, an error is always generated. If REQUIRED is specified and the package is not found, a FATAL_ERROR is generated and the configure step stops executing. A package-specific list of components may be listed after the REQUIRED option.
</li>
<li>
<b><code>FIND_PATH</code></b>: Find the directory containing a file.<br>
<pre> FIND_PATH(<VAR> name1 path1 path2 ...)<br></pre>
<p>This is the short-hand signature for the command that is sufficient in many cases. It is the same as FIND_PATH(<VAR> name1 PATHS path2 path2 ...)<br><pre> FIND_PATH(<br> <VAR> <br> name | NAMES name1 [name2 ...]<br> PATHS path1 [path2 ... ENV var]<br> [PATH_SUFFIXES suffix1 [suffix2 ...]]<br> [DOC "cache documentation string"]<br> [NO_DEFAULT_PATH]<br> [NO_CMAKE_ENVIRONMENT_PATH]<br> [NO_CMAKE_PATH]<br> [NO_SYSTEM_ENVIRONMENT_PATH]<br> [NO_CMAKE_SYSTEM_PATH]<br> )<br></pre>
- <p>This command is used to find a directory containing the named file. A cache entry named by <VAR> is created to store the result of this command. If the file in a directory is found the result is stored in the variable and the search will not be repeated unless the variable is cleared. If nothing is found, the result will be <VAR>-NOTFOUND, and the search will be attempted again the next time FIND_PATH is invoked with the same variable. The name of the file in a directory that is searched for is specified by the names listed after the NAMES argument. Additional search locations can be specified after the PATHS argument. If ENV var is found in the PATHS section the environment variable var will be read and converted from a system environment variable to a cmake style list of paths. For example ENV PATH would be a way to list the system path variable. The argument after DOC will be used for the documentation string in the cache. PATH_SUFFIXES can be used to give sub directories that will be appended to the search paths.<br><p>If NO_DEFAULT_PATH is specified, then no additional paths are added to the search. If NO_DEFAULT_PATH is not specified, the search process is as follows:<br><p>1. Search cmake specific environment variables. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed.<br><pre> CMAKE_FRAMEWORK_PATH<br> CMAKE_APPBUNDLE_PATH<br> CMAKE_INCLUDE_PATH<br></pre>
+ <p>This command is used to find a directory containing the named file. A cache entry named by <VAR> is created to store the result of this command. If nothing is found, the result will be <VAR>-NOTFOUND. The name of the file in a directory that is searched for is specified by the names listed after the NAMES argument. Additional search locations can be specified after the PATHS argument. If ENV var is found in the PATHS section the environment variable var will be read and converted from a system environment variable to a cmake style list of paths. For example ENV PATH would be a way to list the system path variable. The argument after DOC will be used for the documentation string in the cache. PATH_SUFFIXES can be used to give sub directories that will be appended to the search paths.<br><p>If NO_DEFAULT_PATH is specified, then no additional paths are added to the search. If NO_DEFAULT_PATH is not specified, the search process is as follows:<br><p>1. Search cmake specific environment variables. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed.<br><pre> CMAKE_FRAMEWORK_PATH<br> CMAKE_APPBUNDLE_PATH<br> CMAKE_INCLUDE_PATH<br></pre>
<p>2. Search cmake variables with the same names as the cmake specific environment variables. These are intended to be used on the command line with a -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.<br><pre> CMAKE_FRAMEWORK_PATH<br> CMAKE_APPBUNDLE_PATH<br> CMAKE_INCLUDE_PATH<br></pre>
<p>3. Search the standard system environment variables. This can be skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.<br><pre> PATH<br> INCLUDE<br></pre>
<p>4. Search cmake variables defined in the Platform files for the current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed.<br><pre> CMAKE_SYSTEM_FRAMEWORK_PATH<br> CMAKE_SYSTEM_APPBUNDLE_PATH<br> CMAKE_SYSTEM_INCLUDE_PATH<br></pre>
@@ -185,7 +175,7 @@
<b><code>FIND_PROGRAM</code></b>: Find an executable program.<br>
<pre> FIND_PROGRAM(<VAR> name1 path1 path2 ...)<br></pre>
<p>This is the short-hand signature for the command that is sufficient in many cases. It is the same as FIND_PROGRAM(<VAR> name1 PATHS path2 path2 ...)<br><pre> FIND_PROGRAM(<br> <VAR> <br> name | NAMES name1 [name2 ...]<br> PATHS path1 [path2 ... ENV var]<br> [PATH_SUFFIXES suffix1 [suffix2 ...]]<br> [DOC "cache documentation string"]<br> [NO_DEFAULT_PATH]<br> [NO_CMAKE_ENVIRONMENT_PATH]<br> [NO_CMAKE_PATH]<br> [NO_SYSTEM_ENVIRONMENT_PATH]<br> [NO_CMAKE_SYSTEM_PATH]<br> )<br></pre>
- <p>This command is used to find a program. A cache entry named by <VAR> is created to store the result of this command. If the program is found the result is stored in the variable and the search will not be repeated unless the variable is cleared. If nothing is found, the result will be <VAR>-NOTFOUND, and the search will be attempted again the next time FIND_PROGRAM is invoked with the same variable. The name of the program that is searched for is specified by the names listed after the NAMES argument. Additional search locations can be specified after the PATHS argument. If ENV var is found in the PATHS section the environment variable var will be read and converted from a system environment variable to a cmake style list of paths. For example ENV PATH would be a way to list the system path variable. The argument after DOC will be used for the documentation string in the cache. PATH_SUFFIXES can be used to give sub directories that will be appended to the search paths.<br><p>If NO_DEFAULT_PATH is specified, then no additional paths are added to the search. If NO_DEFAULT_PATH is not specified, the search process is as follows:<br><p>1. Search cmake specific environment variables. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed.<br><pre> CMAKE_FRAMEWORK_PATH<br> CMAKE_APPBUNDLE_PATH<br> CMAKE_PROGRAM_PATH<br></pre>
+ <p>This command is used to find a program. A cache entry named by <VAR> is created to store the result of this command. If nothing is found, the result will be <VAR>-NOTFOUND. The name of the program that is searched for is specified by the names listed after the NAMES argument. Additional search locations can be specified after the PATHS argument. If ENV var is found in the PATHS section the environment variable var will be read and converted from a system environment variable to a cmake style list of paths. For example ENV PATH would be a way to list the system path variable. The argument after DOC will be used for the documentation string in the cache. PATH_SUFFIXES can be used to give sub directories that will be appended to the search paths.<br><p>If NO_DEFAULT_PATH is specified, then no additional paths are added to the search. If NO_DEFAULT_PATH is not specified, the search process is as follows:<br><p>1. Search cmake specific environment variables. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed.<br><pre> CMAKE_FRAMEWORK_PATH<br> CMAKE_APPBUNDLE_PATH<br> CMAKE_PROGRAM_PATH<br></pre>
<p>2. Search cmake variables with the same names as the cmake specific environment variables. These are intended to be used on the command line with a -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.<br><pre> CMAKE_FRAMEWORK_PATH<br> CMAKE_APPBUNDLE_PATH<br> CMAKE_PROGRAM_PATH<br></pre>
<p>3. Search the standard system environment variables. This can be skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.<br><pre> PATH<br> <br></pre>
<p>4. Search cmake variables defined in the Platform files for the current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed.<br><pre> CMAKE_SYSTEM_FRAMEWORK_PATH<br> CMAKE_SYSTEM_APPBUNDLE_PATH<br> CMAKE_SYSTEM_PROGRAM_PATH<br></pre>
@@ -228,7 +218,7 @@
<li>
<b><code>GET_TARGET_PROPERTY</code></b>: Get a property from a target.<br>
<pre> GET_TARGET_PROPERTY(VAR target property)<br></pre>
- <p>Get a property from a target. The value of the property is stored in the variable VAR. If the property is not found, VAR will be set to "NOTFOUND". Use SET_TARGET_PROPERTIES to set property values. Properties are usually used to control how a target is built.<br><p>The read-only property "<CONFIG>_LOCATION" provides the full path to the file on disk that will be created for the target when building under configuration <CONFIG> (in upper-case, such as "DEBUG_LOCATION"). The read-only property "LOCATION" specifies the full path to the file on disk that will be created for the target. The path may contain a build-system-specific portion that is replaced at build time with the configuration getting built (such as "$(ConfigurationName)" in VS). This is very useful for executable targets to get the path to the executable file for use in a custom command.<br><p>The read-only property "TYPE" returns which type the specified target has (EXECUTABLE, STATIC_LIBRARY, SHARED_LIBRARY, MODULE_LIBRARY, UTILITY, INSTALL_FILES or INSTALL_PROGRAMS). This command can get properties for any target so far created. The targets do not need to be in the current CMakeLists.txt file.
+ <p>Get a property from a target. The value of the property is stored in the variable VAR. If the property is not found, VAR will be set to "NOTFOUND". Use SET_TARGET_PROPERTIES to set property values. Properties are usually used to control how a target is built.<br><p>The read-only property "LOCATION" specifies the full path to the file on disk that will be created for the target. This is very useful for executable targets to get the path to the executable file for use in a custom command. The read-only property "TYPE" returns which type the specified target has (EXECUTABLE, STATIC_LIBRARY, SHARED_LIBRARY, MODULE_LIBRARY, UTILITY, INSTALL_FILES or INSTALL_PROGRAMS). This command can get properties for any target so far created. The targets do not need to be in the current CMakeLists.txt file.
</li>
<li>
<b><code>GET_TEST_PROPERTY</code></b>: Get a property of the test.<br>
@@ -244,8 +234,7 @@
<p>True if both variables would be considered true individually.<br><pre> IF(variable1 OR variable2)<br></pre>
<p>True if either variable would be considered true individually.<br><pre> IF(COMMAND command-name)<br></pre>
<p>True if the given name is a command that can be invoked.<br><pre> IF(EXISTS file-name)<br> IF(EXISTS directory-name)<br></pre>
- <p>True if the named file or directory exists. Behavior is well-defined only for full paths.<br><pre> IF(file1 IS_NEWER_THAN file2)<br></pre>
- <p>True if file1 is newer than file2 or if one of the two files doesn't exist. Behavior is well-defined only for full paths.<br><pre> IF(IS_DIRECTORY directory-name)<br></pre>
+ <p>True if the named file or directory exists. Behavior is well-defined only for full paths.<br><pre> IF(IS_DIRECTORY directory-name)<br></pre>
<p>True if the given name is a directory. Behavior is well-defined only for full paths.<br><pre> IF(variable MATCHES regex)<br> IF(string MATCHES regex)<br></pre>
<p>True if the given string or variable's value matches the given regular expression.<br><pre> IF(variable LESS number)<br> IF(string LESS number)<br> IF(variable GREATER number)<br> IF(string GREATER number)<br> IF(variable EQUAL number)<br> IF(string EQUAL number)<br></pre>
<p>True if the given string or variable's value is a valid number and the inequality or equality is true.<br><pre> IF(variable STRLESS string)<br> IF(string STRLESS string)<br> IF(variable STRGREATER string)<br> IF(string STRGREATER string)<br> IF(variable STREQUAL string)<br> IF(string STREQUAL string)<br></pre>
@@ -259,8 +248,8 @@
</li>
<li>
<b><code>INCLUDE_DIRECTORIES</code></b>: Add include directories to the build.<br>
- <pre> INCLUDE_DIRECTORIES([AFTER|BEFORE] [SYSTEM] dir1 dir2 ...)<br></pre>
- <p>Add the given directories to those searched by the compiler for include files. By default the directories are appended onto the current list of directories. This default behavior can be changed by setting CMAKE_INCLUDE_DIRECTORIES_BEFORE to ON. By using BEFORE or AFTER you can select between appending and prepending, independent from the default. If the SYSTEM option is given the compiler will be told that the directories are meant as system include directories on some platforms.
+ <pre> INCLUDE_DIRECTORIES([AFTER|BEFORE] dir1 dir2 ...)<br></pre>
+ <p>Add the given directories to those searched by the compiler for include files. By default the directories are appended onto the current list of directories. This default behavior can be changed by setting CMAKE_INCLUDE_DIRECTORIES_BEFORE to ON. By using BEFORE or AFTER you can select between appending and prepending, independent from the default.
</li>
<li>
<b><code>INCLUDE_EXTERNAL_MSPROJECT</code></b>: Include an external Microsoft project file in a workspace.<br>
@@ -275,13 +264,11 @@
</li>
<li>
<b><code>INSTALL</code></b>: Specify rules to run at install time.<br>
- <p>This command generates installation rules for a project. Rules specified by calls to this command within a source directory are executed in order during installation. The order across directories is not defined.<br><p>There are multiple signatures for this command. Some of them define installation properties for files and targets. Properties common to multiple signatures are covered here but they are valid only for signatures that specify them. DESTINATION arguments specify the directory on disk to which a file will be installed. If a full path (with a leading slash or drive letter) is given it is used directly. If a relative path is given it is interpreted relative to the value of CMAKE_INSTALL_PREFIX. PERMISSIONS arguments specify permissions for installed files. Valid permissions are OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, GROUP_READ, GROUP_WRITE, GROUP_EXECUTE, WORLD_READ, WORLD_WRITE, WORLD_EXECUTE, SETUID, and SETGID. Permissions that do not make sense on certain platforms are ignored on those platforms. The CONFIGURATIONS argument specifies a list of build configurations for which the install rule applies (Debug, Release, etc.). The COMPONENT argument specifies an installation component name with which the install rule is associated, such as "runtime" or "development". During component-specific installation only install rules associated with the given component name will be executed. During a full installation all components are installed. The RENAME argument specifies a name for an installed file that may be different from the original file. Renaming is allowed only when a single file is installed by the command. The OPTIONAL argument specifies that it is not an error if the file to be installed does not exist. <br><p>The TARGETS signature:<br><pre> INSTALL(TARGETS targets...<br> [[ARCHIVE|LIBRARY|RUNTIME]<br> [DESTINATION <dir>]<br> [PERMISSIONS permissions...]<br> [CONFIGURATIONS [Debug|Release|...]]<br> [COMPONENT <component>]<br> [OPTIONAL]<br> ] [...])<br></pre>
+ <p>This command generates installation rules for a project. Rules specified by calls to this command within a source directory are executed in order during installation. The order across directories is not defined.<br><p>There are multiple signatures for this command. Some of them define installation properties for files and targets. Properties common to multiple signatures are covered here but they are valid only for signatures that specify them. DESTINATION arguments specify the directory on disk to which a file will be installed. If a full path (with a leading slash or drive letter) is given it is used directly. If a relative path is given it is interpreted relative to the value of CMAKE_INSTALL_PREFIX. PERMISSIONS arguments specify permissions for installed files. Valid permissions are OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, GROUP_READ, GROUP_WRITE, GROUP_EXECUTE, WORLD_READ, WORLD_WRITE, WORLD_EXECUTE, SETUID, and SETGID. Permissions that do not make sense on certain platforms are ignored on those platforms. The CONFIGURATIONS argument specifies a list of build configurations for which the install rule applies (Debug, Release, etc.). The COMPONENT argument specifies an installation component name with which the install rule is associated, such as "runtime" or "development". During component-specific installation only install rules associated with the given component name will be executed. During a full installation all components are installed. The RENAME argument specifies a name for an installed file that may be different from the original file. Renaming is allowed only when a single file is installed by the command. <br><p>The TARGETS signature:<br><pre> INSTALL(TARGETS targets... [[ARCHIVE|LIBRARY|RUNTIME]<br> [DESTINATION <dir>]<br> [PERMISSIONS permissions...]<br> [CONFIGURATIONS [Debug|Release|...]]<br> [COMPONENT <component>]<br> ] [...])<br></pre>
<p>The TARGETS form specifies rules for installing targets from a project. There are three kinds of target files that may be installed: archive, library, and runtime. Executables are always treated as runtime targets. Static libraries are always treated as archive targets. Module libraries are always treated as library targets. For non-DLL platforms shared libraries are treated as library targets. For DLL platforms the DLL part of a shared library is treated as a runtime target and the corresponding import library is treated as an archive target. All Windows-based systems including Cygwin are DLL platforms. The ARCHIVE, LIBRARY, and RUNTIME arguments change the type of target to which the subsequent properties apply. If none is given the installation properties apply to all target types. If only one is given then only targets of that type will be installed (which can be used to install just a DLL or just an import library).<br><p>One or more groups of properties may be specified in a single call to the TARGETS form of this command. A target may be installed more than once to different locations. Consider hypothetical targets "myExe", "mySharedLib", and "myStaticLib". The code<br><pre> INSTALL(TARGETS myExe mySharedLib myStaticLib<br> RUNTIME DESTINATION bin<br> LIBRARY DESTINATION lib<br> ARCHIVE DESTINATION lib/static)<br> INSTALL(TARGETS mySharedLib DESTINATION /some/full/path)<br></pre>
- <p>will install myExe to <prefix>/bin and myStaticLib to <prefix>/lib/static. On non-DLL platforms mySharedLib will be installed to <prefix>/lib and /some/full/path. On DLL platforms the mySharedLib DLL will be installed to <prefix>/bin and /some/full/path and its import library will be installed to <prefix>/lib/static and /some/full/path. On non-DLL platforms mySharedLib will be installed to <prefix>/lib and /some/full/path.<br><p>The FILES signature:<br><pre> INSTALL(FILES files... DESTINATION <dir><br> [PERMISSIONS permissions...]<br> [CONFIGURATIONS [Debug|Release|...]]<br> [COMPONENT <component>]<br> [RENAME <name>] [OPTIONAL])<br></pre>
- <p>The FILES form specifies rules for installing files for a project. File names given as relative paths are interpreted with respect to the current source directory. Files installed by this form are by default given permissions OWNER_WRITE, OWNER_READ, GROUP_READ, and WORLD_READ if no PERMISSIONS argument is given.<br><p>The PROGRAMS signature:<br><pre> INSTALL(PROGRAMS files... DESTINATION <dir><br> [PERMISSIONS permissions...]<br> [CONFIGURATIONS [Debug|Release|...]]<br> [COMPONENT <component>]<br> [RENAME <name>] [OPTIONAL])<br></pre>
- <p>The PROGRAMS form is identical to the FILES form except that the default permissions for the installed file also include OWNER_EXECUTE, GROUP_EXECUTE, and WORLD_EXECUTE. This form is intended to install programs that are not targets, such as shell scripts. Use the TARGETS form to install targets built within the project.<br><p>The DIRECTORY signature:<br><pre> INSTALL(DIRECTORY dirs... DESTINATION <dir><br> [FILE_PERMISSIONS permissions...]<br> [DIRECTORY_PERMISSIONS permissions...]<br> [USE_SOURCE_PERMISSIONS]<br> [CONFIGURATIONS [Debug|Release|...]]<br> [COMPONENT <component>]<br> [[PATTERN <pattern> | REGEX <regex>]<br> [EXCLUDE] [PERMISSIONS permissions...]] [...])<br></pre>
- <p>The DIRECTORY form installs contents of one or more directories to a given destination. The directory structure is copied verbatim to the destination. The last component of each directory name is appended to the destination directory but a trailing slash may be used to avoid this because it leaves the last component empty. Directory names given as relative paths are interpreted with respect to the current source directory. If no input directory names are given the destination directory will be created but nothing will be installed into it. The FILE_PERMISSIONS and DIRECTORY_PERMISSIONS options specify permissions given to files and directories in the destination. If USE_SOURCE_PERMISSIONS is specified and FILE_PERMISSIONS is not, file permissions will be copied from the source directory structure. If no permissions are specified files will be given the default permissions specified in the FILES form of the command, and the directories will be given the default permissions specified in the PROGRAMS form of the command. The PATTERN and REGEX options specify a globbing pattern or regular expression to match directories or files encountered during traversal of an input directory. The full path to an input file or directory (with forward slashes) is matched against the expression. A PATTERN will match only complete file names: the portion of the full path matching the pattern must occur at the end of the file name and be preceded by a slash. A REGEX will match any portion of the full path but it may use '/' and '$' to simulate the PATTERN behavior. Options following one of these matching expressions are applied only to files or directories matching them. The EXCLUDE option will skip the matched file or directory. The PERMISSIONS option overrides the permissions setting for the matched file or directory. For example the code<br><pre> INSTALL(DIRECTORY icons scripts/ DESTINATION share/myproj<br> PATTERN "CVS" EXCLUDE<br> PATTERN "scripts/*"<br> PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ<br> GROUP_EXECUTE GROUP_READ)<br></pre>
- <p>will install the icons directory to share/myproj/icons and the scripts directory to share/myproj. The icons will get default file permissions, the scripts will be given specific permissions, and any CVS directories will be excluded.<br><p>The SCRIPT and CODE signature:<br><pre> INSTALL([[SCRIPT <file>] [CODE <code>]] [...])<br></pre>
+ <p>will install myExe to <prefix>/bin and myStaticLib to <prefix>/lib/static. On non-DLL platforms mySharedLib will be installed to <prefix>/lib and /some/full/path. On DLL platforms the mySharedLib DLL will be installed to <prefix>/bin and /some/full/path and its import library will be installed to <prefix>/lib/static and /some/full/path. On non-DLL platforms mySharedLib will be installed to <prefix>/lib and /some/full/path.<br><p>The FILES signature:<br><pre> INSTALL(FILES files... DESTINATION <dir><br> [PERMISSIONS permissions...]<br> [CONFIGURATIONS [Debug|Release|...]]<br> [COMPONENT <component>]<br> [RENAME <name>])<br></pre>
+ <p>The FILES form specifies rules for installing files for a project. File names given as relative paths are interpreted with respect to the current source directory. Files installed by this form are by default given permissions OWNER_WRITE, OWNER_READ, GROUP_READ, and WORLD_READ if no PERMISSIONS argument is given.<br><p>The PROGRAMS signature:<br><pre> INSTALL(PROGRAMS files... DESTINATION <dir><br> [PERMISSIONS permissions...]<br> [CONFIGURATIONS [Debug|Release|...]]<br> [COMPONENT <component>]<br> [RENAME <name>])<br></pre>
+ <p>The PROGRAMS form is identical to the FILES form except that the default permissions for the installed file also include OWNER_EXECUTE, GROUP_EXECUTE, and WORLD_EXECUTE. This form is intended to install programs that are not targets, such as shell scripts. Use the TARGETS form to install targets built within the project.<br><p>The SCRIPT and CODE signature:<br><pre> INSTALL([[SCRIPT <file>] [CODE <code>]] [...])<br></pre>
<p>The SCRIPT form will invoke the given CMake script files during installation. If the script file name is a relative path it will be interpreted with respect to the current source directory. The CODE form will invoke the given CMake code during installation. Code is specified as a single argument inside a double-quoted string. For example, the code<br><pre> INSTALL(CODE "MESSAGE(\"Sample install message.\")")<br></pre>
<p>will print a message during installation.<br><p>NOTE: This command supercedes the INSTALL_TARGETS command and the target properties PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT. It also replaces the FILES forms of the INSTALL_FILES and INSTALL_PROGRAMS commands. The processing order of these install rules relative to those generated by INSTALL_TARGETS, INSTALL_FILES, and INSTALL_PROGRAMS commands is not defined.<br>
</li>
@@ -336,8 +323,8 @@
<p>Define a macro named <name> that takes arguments named arg1 arg2 arg3 (...). Commands listed after MACRO, but before the matching ENDMACRO, are not invoked until the macro is invoked. When it is invoked, the commands recorded in the macro are first modified by replacing formal parameters (${arg1}) with the arguments passed, and then invoked as normal commands. In addition to referencing the formal parameters you can reference the variable ARGC which will be set to the number of arguments passed into the function as well as ARGV0 ARGV1 ARGV2 ... which will have the actual values of the arguments passed in. This facilitates creating macros with optional arguments. Additionally ARGV holds the list of all arguments given to the macro and ARGN holds the list of argument pass the last expected argument.
</li>
<li>
- <b><code>MAKE_DIRECTORY</code></b>: Old directory creation command. Use the FILE command.<br>
- <p>This command has been superceded by the FILE(MAKE_DIRECTORY ...) command. It is provided for compatibility with older CMake code.<br><pre> MAKE_DIRECTORY(directory)<br></pre>
+ <b><code>MAKE_DIRECTORY</code></b>: Create a directory on the file system.<br>
+ <pre> MAKE_DIRECTORY(directory)<br></pre>
<p>Creates the specified directory. Full paths should be given. Any parent directories that do not exist will also be created. Use with care.
</li>
<li>
@@ -381,8 +368,8 @@
<p>Produce .h and .cxx files for all the .ui files listed in the SourceLists. The .h files will be added to the library using the HeadersDestNamesource list. The .cxx files will be added to the library using the SourcesDestNamesource list.
</li>
<li>
- <b><code>REMOVE</code></b>: Old list item removal command. Use the LIST command.<br>
- <p>This command has been superceded by the LIST(REMOVE ...) command. It is provided for compatibility with older CMake code.<br><pre> REMOVE(VAR VALUE VALUE ...)<br></pre>
+ <b><code>REMOVE</code></b>: Remove a value from a list in a variable.<br>
+ <pre> REMOVE(VAR VALUE VALUE ...)<br></pre>
<p>Removes VALUE from the variable VAR. This is typically used to remove entries from a vector (e.g. semicolon separated list). VALUE is expanded.
</li>
<li>
@@ -411,12 +398,12 @@
<li>
<b><code>SET_SOURCE_FILES_PROPERTIES</code></b>: Source files can have properties that affect how they are built.<br>
<pre> SET_SOURCE_FILES_PROPERTIES(file1 file2 ...<br> PROPERTIES prop1 value1<br> prop2 value2 ...)<br></pre>
- <p>Set properties on a file. The syntax for the command is to list all the files you want to change, and then provide the values you want to set next. You can make up your own properties as well. The following are used by CMake. The ABSTRACT flag (boolean) is used by some class wrapping commands. If WRAP_EXCLUDE (boolean) is true then many wrapping commands will ignore this file. If GENERATED (boolean) is true then it is not an error if this source file does not exist when it is added to a target. Obviously, it must be created (presumably by a custom command) before the target is built. If the HEADER_FILE_ONLY (boolean) property is true then dependency information is not created for that file (this is set automatically, based on the file's name's extension and is probably only used by Makefiles). OBJECT_DEPENDS (string) adds dependencies to the object file. COMPILE_FLAGS (string) is passed to the compiler as additional command line arguments when the source file is compiled. If SYMBOLIC (boolean) is set to true the build system will be informed that the source file is not actually created on disk but instead used as a symbolic name for a build rule.
+ <p>Set properties on a file. The syntax for the command is to list all the files you want to change, and then provide the values you want to set next. You can make up your own properties as well. The following are used by CMake. The ABSTRACT flag (boolean) is used by some class wrapping commands. If WRAP_EXCLUDE (boolean) is true then many wrapping commands will ignore this file. If GENERATED (boolean) is true then it is not an error if this source file does not exist when it is added to a target. Obviously, it must be created (presumably by a custom command) before the target is built. If the HEADER_FILE_ONLY (boolean) property is true then dependency information is not created for that file (this is set automatically, based on the file's name's extension and is probably only used by Makefiles). OBJECT_DEPENDS (string) adds dependencies to the object file. COMPILE_FLAGS (string) is passed to the compiler as additional command line arguments when the source file is compiled.
</li>
<li>
<b><code>SET_TARGET_PROPERTIES</code></b>: Targets can have properties that affect how they are built.<br>
<pre> SET_TARGET_PROPERTIES(target1 target2 ...<br> PROPERTIES prop1 value1<br> prop2 value2 ...)<br></pre>
- <p>Set properties on a target. The syntax for the command is to list all the files you want to change, and then provide the values you want to set next. You can use any prop value pair you want and extract it later with the GET_TARGET_PROPERTY command.<br><p>Properties that affect the name of a target's output file are as follows. The PREFIX and SUFFIX properties override the default target name prefix (such as "lib") and suffix (such as ".so"). IMPORT_PREFIX and IMPORT_SUFFIX are the equivalent properties for the import library corresponding to a DLL (for SHARED library targets). OUTPUT_NAME sets the real name of a target when it is built and can be used to help create two targets of the same name even though CMake requires unique logical target names. There is also a <CONFIG>_OUTPUT_NAME that can set the output name on a per-configuration basis. <CONFIG>_POSTFIX sets a postfix for the real name of the target when it is built under the configuration named by <CONFIG> (in upper-case, such as "DEBUG_POSTFIX"). The value of this property is initialized when the target is created to the value of the variable CMAKE_<CONFIG>_POSTFIX (except for executable targets because earlier CMake versions which did not use this variable for executables).<br><p>The LINK_FLAGS property can be used to add extra flags to the link step of a target. LINK_FLAGS_<CONFIG> will add to the configuration <CONFIG>, for example, DEBUG, RELEASE, MINSIZEREL, RELWITHDEBINFO. DEFINE_SYMBOL sets the name of the preprocessor symbol defined when compiling sources in a shared library. If not set here then it is set to target_EXPORTS by default (with some substitutions if the target is not a valid C identifier). This is useful for headers to know whether they are being included from inside their library our outside to properly setup dllexport/dllimport decorations. The COMPILE_FLAGS property sets additional compiler flags used to build sources within the target. It may also be used to pass additional preprocessor definitions.<br><p>The LINKER_LANGUAGE property is used to change the tool used to link an executable or shared library. The default is set the language to match the files in the library. CXX and C are common values for this property.<br><p>For shared libraries VERSION and SOVERSION can be used to specify the build version and api version respectively. When building or installing appropriate symlinks are created if the platform supports symlinks and the linker supports so-names. If only one of both is specified the missing is assumed to have the same version number. For executables VERSION can be used to specify the build version. When building or installing appropriate symlinks are created if the platform supports symlinks. For shared libraries and executables on Windows the VERSION attribute is parsed to extract a "major.minor" version number. These numbers are used as the image version of the binary. <br><p>There are a few properties used to specify RPATH rules. INSTALL_RPATH is a semicolon-separated list specifying the rpath to use in installed targets (for platforms that support it). INSTALL_RPATH_USE_LINK_PATH is a boolean that if set to true will append directories in the linker search path and outside the project to the INSTALL_RPATH. SKIP_BUILD_RPATH is a boolean specifying whether to skip automatic generation of an rpath allowing the target to run from the build tree. BUILD_WITH_INSTALL_RPATH is a boolean specifying whether to link the target in the build tree with the INSTALL_RPATH. This takes precedence over SKIP_BUILD_RPATH and avoids the need for relinking before installation. INSTALL_NAME_DIR is a string specifying the directory portion of the "install_name" field of shared libraries on Mac OSX to use in the installed targets. When the target is created the values of the variables CMAKE_INSTALL_RPATH, CMAKE_INSTALL_RPATH_USE_LINK_PATH, CMAKE_SKIP_BUILD_RPATH, CMAKE_BUILD_WITH_INSTALL_RPATH, and CMAKE_INSTALL_NAME_DIR are used to initialize these properties.<br><p>PROJECT_LABEL can be used to change the name of the target in an IDE like visual studio. VS_KEYWORD can be set to change the visual studio keyword, for example QT integration works better if this is set to Qt4VSv1.0.<br><p>When a library is built CMake by default generates code to remove any existing library using all possible names. This is needed to support libraries that switch between STATIC and SHARED by a user option. However when using OUTPUT_NAME to build a static and shared library of the same name using different logical target names the two targets will remove each other's files. This can be prevented by setting the CLEAN_DIRECT_OUTPUT property to 1.<br><p>The PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT properties are the old way to specify CMake scripts to run before and after installing a target. They are used only when the old INSTALL_TARGETS command is used to install the target. Use the INSTALL command instead.
+ <p>Set properties on a target. The syntax for the command is to list all the files you want to change, and then provide the values you want to set next. You can use any prop value pair you want and extract it later with the GET_TARGET_PROPERTY command.<br><p>Properties that affect the name of a target's output file are as follows. The PREFIX and SUFFIX properties override the default target name prefix (such as "lib") and suffix (such as ".so"). IMPORT_PREFIX and IMPORT_SUFFIX are the equivalent properties for the import library corresponding to a DLL (for SHARED library targets). OUTPUT_NAME sets the real name of a target when it is built and can be used to help create two targets of the same name even though CMake requires unique logical target names. There is also a <CONFIG>_OUTPUT_NAME that can set the output name on a per-configuration basis. <CONFIG>_POSTFIX sets a postfix for the real name of the target when it is built under the configuration named by <CONFIG> (in upper-case, such as "DEBUG_POSTFIX"). The value of this property is initialized when the target is created to the value of the variable CMAKE_<CONFIG>_POSTFIX (except for executable targets because earlier CMake versions which did not use this variable for executables).<br><p>The LINK_FLAGS property can be used to add extra flags to the link step of a target. LINK_FLAGS_<CONFIG> will add to the configuration <CONFIG>, for example, DEBUG, RELEASE, MINSIZEREL, RELWITHDEBINFO. DEFINE_SYMBOL sets the name of the preprocessor symbol defined when compiling sources in a shared library. If not set here then it is set to target_EXPORTS by default (with some substitutions if the target is not a valid C identifier). This is useful for headers to know whether they are being included from inside their library our outside to properly setup dllexport/dllimport decorations. The COMPILE_FLAGS property sets additional compiler flags used to build sources within the target. It may also be used to pass additional preprocessor definitions.<br><p>The LINKER_LANGUAGE property is used to change the tool used to link an executable or shared library. The default is set the language to match the files in the library. CXX and C are common values for this property.<br><p>For shared libraries VERSION and SOVERSION can be used to specify the build version and api version respectively. When building or installing appropriate symlinks are created if the platform supports symlinks and the linker supports so-names. If only one of both is specified the missing is assumed to have the same version number. For executables VERSION can be used to specify the build version. When building or installing appropriate symlinks are created if the platform supports symlinks.<br><p>There are a few properties used to specify RPATH rules. INSTALL_RPATH is a semicolon-separated list specifying the rpath to use in installed targets (for platforms that support it). INSTALL_RPATH_USE_LINK_PATH is a boolean that if set to true will append directories in the linker search path and outside the project to the INSTALL_RPATH. SKIP_BUILD_RPATH is a boolean specifying whether to skip automatic generation of an rpath allowing the target to run from the build tree. BUILD_WITH_INSTALL_RPATH is a boolean specifying whether to link the target in the build tree with the INSTALL_RPATH. This takes precedence over SKIP_BUILD_RPATH and avoids the need for relinking before installation. INSTALL_NAME_DIR is a string specifying the directory portion of the "install_name" field of shared libraries on Mac OSX to use in the installed targets. When the target is created the values of the variables CMAKE_INSTALL_RPATH, CMAKE_INSTALL_RPATH_USE_LINK_PATH, CMAKE_SKIP_BUILD_RPATH, CMAKE_BUILD_WITH_INSTALL_RPATH, and CMAKE_INSTALL_NAME_DIR are used to initialize these properties.<br><p>PROJECT_LABEL can be used to change the name of the target in an IDE like visual studio. VS_KEYWORD can be set to change the visual studio keyword, for example QT integration works better if this is set to Qt4VSv1.0.<br><p>The PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT properties are the old way to specify CMake scripts to run before and after installing a target. They are used only when the old INSTALL_TARGETS command is used to install the target. Use the INSTALL command instead.
</li>
<li>
<b><code>SET_TESTS_PROPERTIES</code></b>: Set a property of the tests.<br>
More information about the Cmake-commits
mailing list