[cmake-commits] king committed CMakeCommands.html 1.29 1.30
cmake-commits at cmake.org
cmake-commits at cmake.org
Sat Oct 14 06:00:11 EDT 2006
Update of /cvsroot/CMake/CMakeWeb/HTML
In directory public:/mounts/ram/cvs-serv11548
Modified Files:
CMakeCommands.html
Log Message:
STYLE: Documentation update.
Index: CMakeCommands.html
===================================================================
RCS file: /cvsroot/CMake/CMakeWeb/HTML/CMakeCommands.html,v
retrieving revision 1.29
retrieving revision 1.30
diff -u -d -r1.29 -r1.30
--- CMakeCommands.html 25 Jul 2006 10:00:07 -0000 1.29
+++ CMakeCommands.html 14 Oct 2006 10:00:09 -0000 1.30
@@ -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])<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] [VERBATIM] [APPEND])<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])<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>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. If WORKING_DIRECTORY is specified the command will be executed in the directory given.
+ <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.
</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></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.
+ <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.
</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] source1<br> source2 ... sourceN)<br></pre>
+ <pre> ADD_EXECUTABLE(exename [WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL]<br> source1 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]<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.
+ <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.
</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 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 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,6 +81,11 @@
<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.
@@ -101,6 +106,11 @@
<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.
@@ -218,7 +228,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 "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.
+ <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.
</li>
<li>
<b><code>GET_TEST_PROPERTY</code></b>: Get a property of the test.<br>
@@ -234,7 +244,8 @@
<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(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(FILE_IS_NEWER file1 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 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>
@@ -248,8 +259,8 @@
</li>
<li>
<b><code>INCLUDE_DIRECTORIES</code></b>: Add include directories to the build.<br>
- <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.
+ <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.
</li>
<li>
<b><code>INCLUDE_EXTERNAL_MSPROJECT</code></b>: Include an external Microsoft project file in a workspace.<br>
@@ -264,11 +275,13 @@
</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. <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>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>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>])<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>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>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>
@@ -323,8 +336,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>: Create a directory on the file system.<br>
- <pre> MAKE_DIRECTORY(directory)<br></pre>
+ <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>
<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>
@@ -368,8 +381,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>: Remove a value from a list in a variable.<br>
- <pre> REMOVE(VAR VALUE VALUE ...)<br></pre>
+ <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>
<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>
@@ -398,12 +411,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.
+ <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.
</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.<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.
+ <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>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.
</li>
<li>
<b><code>SET_TESTS_PROPERTIES</code></b>: Set a property of the tests.<br>
More information about the Cmake-commits
mailing list