diff options
Diffstat (limited to 'Help')
69 files changed, 903 insertions, 280 deletions
diff --git a/Help/command/FIND_XXX_ROOT.txt b/Help/command/FIND_XXX_ROOT.txt index 407375a..b5cab68 100644 --- a/Help/command/FIND_XXX_ROOT.txt +++ b/Help/command/FIND_XXX_ROOT.txt @@ -1,14 +1,23 @@ -The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more +The CMake variable :variable:`CMAKE_FIND_ROOT_PATH` specifies one or more directories to be prepended to all other search directories. This -effectively "re-roots" the entire search under given locations. By -default it is empty. It is especially useful when cross-compiling to +effectively "re-roots" the entire search under given locations. +Paths which are descendants of the :variable:`CMAKE_STAGING_PREFIX` are excluded +from this re-rooting, because that variable is always a path on the host system. +By default the :variable:`CMAKE_FIND_ROOT_PATH` is empty. + +The :variable:`CMAKE_SYSROOT` variable can also be used to specify exactly one +directory to use as a prefix. Setting :variable:`CMAKE_SYSROOT` also has other +effects. See the documentation for that variable for more. + +These variables are especially useful when cross-compiling to point to the root directory of the target environment and CMake will search there too. By default at first the directories listed in -CMAKE_FIND_ROOT_PATH and then the non-rooted directories will be +:variable:`CMAKE_FIND_ROOT_PATH` are searched, then the :variable:`CMAKE_SYSROOT` +directory is searched, and then the non-rooted directories will be searched. The default behavior can be adjusted by setting |CMAKE_FIND_ROOT_PATH_MODE_XXX|. This behavior can be manually overridden on a per-call basis. By using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as described above. If -NO_CMAKE_FIND_ROOT_PATH is used then CMAKE_FIND_ROOT_PATH will not be +NO_CMAKE_FIND_ROOT_PATH is used then :variable:`CMAKE_FIND_ROOT_PATH` will not be used. If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted -directories will be searched. +directories and directories below :variable:`CMAKE_STAGING_PREFIX` will be searched. diff --git a/Help/command/ctest_submit.rst b/Help/command/ctest_submit.rst index 29d2f5d..ed801bb 100644 --- a/Help/command/ctest_submit.rst +++ b/Help/command/ctest_submit.rst @@ -22,6 +22,7 @@ Valid part names are: MemCheck = ctest_memcheck results, in DynamicAnalysis.xml Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES + Upload = Files prepared for upload by ctest_upload(), in Upload.xml Submit = nothing The FILES option explicitly lists specific files to be submitted. diff --git a/Help/command/find_file.rst b/Help/command/find_file.rst index 549b317..db7e151 100644 --- a/Help/command/find_file.rst +++ b/Help/command/find_file.rst @@ -22,6 +22,6 @@ find_file .. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_FRAMEWORK_PATH .. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: - CMAKE_FIND_ROOT_PATH_MODE_INCLUDE + :variable:`CMAKE_FIND_ROOT_PATH_MODE_INCLUDE` .. include:: FIND_XXX.txt diff --git a/Help/command/find_library.rst b/Help/command/find_library.rst index 8598be7..91342ba 100644 --- a/Help/command/find_library.rst +++ b/Help/command/find_library.rst @@ -22,7 +22,7 @@ find_library .. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_FRAMEWORK_PATH .. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: - CMAKE_FIND_ROOT_PATH_MODE_LIBRARY + :variable:`CMAKE_FIND_ROOT_PATH_MODE_LIBRARY` .. include:: FIND_XXX.txt diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index c394a08..f09cb41 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -320,7 +320,7 @@ hard-coded guesses. .. |FIND_XXX| replace:: find_package .. |FIND_ARGS_XXX| replace:: <package> .. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: - CMAKE_FIND_ROOT_PATH_MODE_PACKAGE + :variable:`CMAKE_FIND_ROOT_PATH_MODE_PACKAGE` .. include:: FIND_XXX_MAC.txt .. include:: FIND_XXX_ROOT.txt diff --git a/Help/command/find_path.rst b/Help/command/find_path.rst index c85011a..95d49e7 100644 --- a/Help/command/find_path.rst +++ b/Help/command/find_path.rst @@ -22,7 +22,7 @@ find_path .. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_FRAMEWORK_PATH .. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: - CMAKE_FIND_ROOT_PATH_MODE_INCLUDE + :variable:`CMAKE_FIND_ROOT_PATH_MODE_INCLUDE` .. include:: FIND_XXX.txt diff --git a/Help/command/find_program.rst b/Help/command/find_program.rst index da5a41d..c62a8a5 100644 --- a/Help/command/find_program.rst +++ b/Help/command/find_program.rst @@ -20,6 +20,6 @@ find_program .. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_APPBUNDLE_PATH .. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: - CMAKE_FIND_ROOT_PATH_MODE_PROGRAM + :variable:`CMAKE_FIND_ROOT_PATH_MODE_PROGRAM` .. include:: FIND_XXX.txt diff --git a/Help/command/foreach.rst b/Help/command/foreach.rst index 8f9710c..348ebd8 100644 --- a/Help/command/foreach.rst +++ b/Help/command/foreach.rst @@ -42,5 +42,6 @@ three types of this iteration: Iterates over a precise list of items. The LISTS option names list-valued variables to be traversed, including empty elements (an -empty string is a zero-length list). The ITEMS option ends argument +empty string is a zero-length list). (Note macro +arguments are not variables.) The ITEMS option ends argument parsing and includes all arguments following it in the iteration. diff --git a/Help/command/if.rst b/Help/command/if.rst index b879ae1..0279be7 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -166,7 +166,8 @@ major[.minor[.patch[.tweak]]]). if(DEFINED <variable>) True if the given variable is defined. It does not matter if the -variable is true or false just if it has been set. +variable is true or false just if it has been set. (Note macro +arguments are not variables.) :: diff --git a/Help/command/list.rst b/Help/command/list.rst index f044dba..aeb1e94 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -50,7 +50,8 @@ propagation. NOTES: A list in cmake is a ; separated group of strings. To create a list the set command can be used. For example, set(var a b c d e) creates a list with a;b;c;d;e, and set(var "a b c d e") creates a -string or a list with one item in it. +string or a list with one item in it. (Note macro arguments are not +variables, and therefore cannot be used in LIST commands.) When specifying index values, if <element index> is 0 or greater, it is indexed from the beginning of the list, with 0 representing the diff --git a/Help/command/macro.rst b/Help/command/macro.rst index aa16352..258dc50 100644 --- a/Help/command/macro.rst +++ b/Help/command/macro.rst @@ -15,19 +15,53 @@ 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 +parameters (``${arg1}``) with the arguments passed, and then invoked as normal commands. In addition to referencing the formal parameters you -can reference the values ${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 +can reference the values ``${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 arguments past the last expected -argument. Note that the parameters to a macro and values such as ARGN -are not variables in the usual CMake sense. They are string -replacements much like the C preprocessor would do with a macro. If -you want true CMake variables and/or better CMake scope control you -should look at the function command. +Additionally ``${ARGV}`` holds the list of all arguments given to the +macro and ``${ARGN}`` holds the list of arguments past the last expected +argument. See the cmake_policy() command documentation for the behavior of policies inside macros. + +Macro Argument Caveats +^^^^^^^^^^^^^^^^^^^^^^ + +Note that the parameters to a macro and values such as ``ARGN`` are +not variables in the usual CMake sense. They are string +replacements much like the C preprocessor would do with a macro. +Therefore you will NOT be able to use commands like:: + + if(ARGV1) # ARGV1 is not a variable + foreach(loop_var IN LISTS ARGN) # ARGN is not a variable + +In the first case you can use ``if(${ARGV1})``, in the second case, you can +use ``foreach(loop_var ${ARGN})`` but this will skip empty arguments. +If you need to include them, you can use:: + + set(list_var "${ARGN}") + foreach(loop_var IN LISTS list_var) + +Note that if you have a variable with the same name in the scope from +which the macro is called, using unreferenced names will use the +existing variable instead of the arguments. For example:: + + macro(_BAR) + foreach(arg IN LISTS ARGN) + [...] + endforeach() + endmacro() + + function(_FOO) + _bar(x y z) + endfunction() + + _foo(a b c) + +Will loop over ``a;b;c`` and not over ``x;y;z`` as one might be expecting. +If you want true CMake variables and/or better CMake scope control you +should look at the function command. diff --git a/Help/generator/CodeBlocks - NMake Makefiles.rst b/Help/generator/CodeBlocks - NMake Makefiles.rst deleted file mode 100644 index c7f944a..0000000 --- a/Help/generator/CodeBlocks - NMake Makefiles.rst +++ /dev/null @@ -1,11 +0,0 @@ -CodeBlocks - NMake Makefiles ----------------------------- - -Generates CodeBlocks project files. - -Project files for CodeBlocks will be created in the top directory and -in every subdirectory which features a CMakeLists.txt file containing -a PROJECT() call. Additionally a hierarchy of makefiles is generated -into the build tree. The appropriate make program can build the -project through the default make target. A "make install" target is -also provided. diff --git a/Help/generator/CodeBlocks - Ninja.rst b/Help/generator/CodeBlocks - Ninja.rst deleted file mode 100644 index 0253af6..0000000 --- a/Help/generator/CodeBlocks - Ninja.rst +++ /dev/null @@ -1,11 +0,0 @@ -CodeBlocks - Ninja ------------------- - -Generates CodeBlocks project files. - -Project files for CodeBlocks will be created in the top directory and -in every subdirectory which features a CMakeLists.txt file containing -a PROJECT() call. Additionally a hierarchy of makefiles is generated -into the build tree. The appropriate make program can build the -project through the default make target. A "make install" target is -also provided. diff --git a/Help/generator/CodeBlocks - Unix Makefiles.rst b/Help/generator/CodeBlocks - Unix Makefiles.rst deleted file mode 100644 index 0a29835..0000000 --- a/Help/generator/CodeBlocks - Unix Makefiles.rst +++ /dev/null @@ -1,11 +0,0 @@ -CodeBlocks - Unix Makefiles ---------------------------- - -Generates CodeBlocks project files. - -Project files for CodeBlocks will be created in the top directory and -in every subdirectory which features a CMakeLists.txt file containing -a PROJECT() call. Additionally a hierarchy of makefiles is generated -into the build tree. The appropriate make program can build the -project through the default make target. A "make install" target is -also provided. diff --git a/Help/generator/CodeBlocks - MinGW Makefiles.rst b/Help/generator/CodeBlocks.rst index f54eb11..01798c7 100644 --- a/Help/generator/CodeBlocks - MinGW Makefiles.rst +++ b/Help/generator/CodeBlocks.rst @@ -1,5 +1,5 @@ -CodeBlocks - MinGW Makefiles ----------------------------- +CodeBlocks +---------- Generates CodeBlocks project files. @@ -9,3 +9,17 @@ a PROJECT() call. Additionally a hierarchy of makefiles is generated into the build tree. The appropriate make program can build the project through the default make target. A "make install" target is also provided. + +This "extra" generator may be specified as: + +``CodeBlocks - MinGW Makefiles`` + Generate with :generator:`MinGW Makefiles`. + +``CodeBlocks - NMake Makefiles`` + Generate with :generator:`NMake Makefiles`. + +``CodeBlocks - Ninja`` + Generate with :generator:`Ninja`. + +``CodeBlocks - Unix Makefiles`` + Generate with :generator:`Unix Makefiles`. diff --git a/Help/generator/Eclipse CDT4 - NMake Makefiles.rst b/Help/generator/Eclipse CDT4 - NMake Makefiles.rst deleted file mode 100644 index b5133ad..0000000 --- a/Help/generator/Eclipse CDT4 - NMake Makefiles.rst +++ /dev/null @@ -1,11 +0,0 @@ -Eclipse CDT4 - NMake Makefiles ------------------------------- - -Generates Eclipse CDT 4.0 project files. - -Project files for Eclipse will be created in the top directory. In -out of source builds, a linked resource to the top level source -directory will be created. Additionally a hierarchy of makefiles is -generated into the build tree. The appropriate make program can build -the project through the default make target. A "make install" target -is also provided. diff --git a/Help/generator/Eclipse CDT4 - Ninja.rst b/Help/generator/Eclipse CDT4 - Ninja.rst deleted file mode 100644 index 270011f..0000000 --- a/Help/generator/Eclipse CDT4 - Ninja.rst +++ /dev/null @@ -1,11 +0,0 @@ -Eclipse CDT4 - Ninja --------------------- - -Generates Eclipse CDT 4.0 project files. - -Project files for Eclipse will be created in the top directory. In -out of source builds, a linked resource to the top level source -directory will be created. Additionally a hierarchy of makefiles is -generated into the build tree. The appropriate make program can build -the project through the default make target. A "make install" target -is also provided. diff --git a/Help/generator/Eclipse CDT4 - Unix Makefiles.rst b/Help/generator/Eclipse CDT4 - Unix Makefiles.rst deleted file mode 100644 index c3449a7..0000000 --- a/Help/generator/Eclipse CDT4 - Unix Makefiles.rst +++ /dev/null @@ -1,11 +0,0 @@ -Eclipse CDT4 - Unix Makefiles ------------------------------ - -Generates Eclipse CDT 4.0 project files. - -Project files for Eclipse will be created in the top directory. In -out of source builds, a linked resource to the top level source -directory will be created. Additionally a hierarchy of makefiles is -generated into the build tree. The appropriate make program can build -the project through the default make target. A "make install" target -is also provided. diff --git a/Help/generator/Eclipse CDT4 - MinGW Makefiles.rst b/Help/generator/Eclipse CDT4.rst index 9e7a26e..eb68bf0 100644 --- a/Help/generator/Eclipse CDT4 - MinGW Makefiles.rst +++ b/Help/generator/Eclipse CDT4.rst @@ -1,5 +1,5 @@ -Eclipse CDT4 - MinGW Makefiles ------------------------------- +Eclipse CDT4 +------------ Generates Eclipse CDT 4.0 project files. @@ -9,3 +9,17 @@ directory will be created. Additionally a hierarchy of makefiles is generated into the build tree. The appropriate make program can build the project through the default make target. A "make install" target is also provided. + +This "extra" generator may be specified as: + +``Eclipse CDT4 - MinGW Makefiles`` + Generate with :generator:`MinGW Makefiles`. + +``Eclipse CDT4 - NMake Makefiles`` + Generate with :generator:`NMake Makefiles`. + +``Eclipse CDT4 - Ninja`` + Generate with :generator:`Ninja`. + +``Eclipse CDT4 - Unix Makefiles`` + Generate with :generator:`Unix Makefiles`. diff --git a/Help/generator/KDevelop3 - Unix Makefiles.rst b/Help/generator/KDevelop3 - Unix Makefiles.rst deleted file mode 100644 index 2a29a2e..0000000 --- a/Help/generator/KDevelop3 - Unix Makefiles.rst +++ /dev/null @@ -1,13 +0,0 @@ -KDevelop3 - Unix Makefiles --------------------------- - -Generates KDevelop 3 project files. - -Project files for KDevelop 3 will be created in the top directory and -in every subdirectory which features a CMakeLists.txt file containing -a PROJECT() call. If you change the settings using KDevelop cmake -will try its best to keep your changes when regenerating the project -files. Additionally a hierarchy of UNIX makefiles is generated into -the build tree. Any standard UNIX-style make program can build the -project through the default make target. A "make install" target is -also provided. diff --git a/Help/generator/KDevelop3.rst b/Help/generator/KDevelop3.rst index 788d557..eaa218b 100644 --- a/Help/generator/KDevelop3.rst +++ b/Help/generator/KDevelop3.rst @@ -11,3 +11,15 @@ files. Additionally a hierarchy of UNIX makefiles is generated into the build tree. Any standard UNIX-style make program can build the project through the default make target. A "make install" target is also provided. + +This "extra" generator may be specified as: + +``KDevelop3 - Unix Makefiles`` + Generate with :generator:`Unix Makefiles`. + +``KDevelop3`` + Generate with :generator:`Unix Makefiles`. + + For historical reasons this extra generator may be specified + directly as the main generator and it will be used as the + extra generator with :generator:`Unix Makefiles` automatically. diff --git a/Help/generator/Kate.rst b/Help/generator/Kate.rst new file mode 100644 index 0000000..9b61a93 --- /dev/null +++ b/Help/generator/Kate.rst @@ -0,0 +1,26 @@ +Kate +---- + +Generates Kate project files. + +A project file for Kate will be created in the top directory in the top level +build directory. +To use it in kate, the Project plugin must be enabled. +The project file is loaded in kate simply by opening the +ProjectName.kateproject file in the editor. +If the kate Build-plugin is enabled, all targets generated by CMake are +available for building. + +This "extra" generator may be specified as: + +``Kate - MinGW Makefiles`` + Generate with :generator:`MinGW Makefiles`. + +``Kate - NMake Makefiles`` + Generate with :generator:`NMake Makefiles`. + +``Kate - Ninja`` + Generate with :generator:`Ninja`. + +``Kate - Unix Makefiles`` + Generate with :generator:`Unix Makefiles`. diff --git a/Help/generator/Sublime Text 2 - NMake Makefiles.rst b/Help/generator/Sublime Text 2 - NMake Makefiles.rst deleted file mode 100644 index 5e02fd4..0000000 --- a/Help/generator/Sublime Text 2 - NMake Makefiles.rst +++ /dev/null @@ -1,11 +0,0 @@ -Sublime Text 2 - NMake Makefiles --------------------------------- - -Generates Sublime Text 2 project files. - -Project files for Sublime Text 2 will be created in the top directory -and in every subdirectory which features a CMakeLists.txt file -containing a PROJECT() call. Additionally Makefiles (or build.ninja -files) are generated into the build tree. The appropriate make -program can build the project through the default make target. A -"make install" target is also provided. diff --git a/Help/generator/Sublime Text 2 - Ninja.rst b/Help/generator/Sublime Text 2 - Ninja.rst deleted file mode 100644 index b7a2b88..0000000 --- a/Help/generator/Sublime Text 2 - Ninja.rst +++ /dev/null @@ -1,11 +0,0 @@ -Sublime Text 2 - Ninja ----------------------- - -Generates Sublime Text 2 project files. - -Project files for Sublime Text 2 will be created in the top directory -and in every subdirectory which features a CMakeLists.txt file -containing a PROJECT() call. Additionally Makefiles (or build.ninja -files) are generated into the build tree. The appropriate make -program can build the project through the default make target. A -"make install" target is also provided. diff --git a/Help/generator/Sublime Text 2 - Unix Makefiles.rst b/Help/generator/Sublime Text 2 - Unix Makefiles.rst deleted file mode 100644 index 67d329e..0000000 --- a/Help/generator/Sublime Text 2 - Unix Makefiles.rst +++ /dev/null @@ -1,11 +0,0 @@ -Sublime Text 2 - Unix Makefiles -------------------------------- - -Generates Sublime Text 2 project files. - -Project files for Sublime Text 2 will be created in the top directory -and in every subdirectory which features a CMakeLists.txt file -containing a PROJECT() call. Additionally Makefiles (or build.ninja -files) are generated into the build tree. The appropriate make -program can build the project through the default make target. A -"make install" target is also provided. diff --git a/Help/generator/Sublime Text 2 - MinGW Makefiles.rst b/Help/generator/Sublime Text 2.rst index 6e2ed02..0597a95 100644 --- a/Help/generator/Sublime Text 2 - MinGW Makefiles.rst +++ b/Help/generator/Sublime Text 2.rst @@ -1,5 +1,5 @@ -Sublime Text 2 - MinGW Makefiles --------------------------------- +Sublime Text 2 +-------------- Generates Sublime Text 2 project files. @@ -9,3 +9,17 @@ containing a PROJECT() call. Additionally Makefiles (or build.ninja files) are generated into the build tree. The appropriate make program can build the project through the default make target. A "make install" target is also provided. + +This "extra" generator may be specified as: + +``Sublime Text 2 - MinGW Makefiles`` + Generate with :generator:`MinGW Makefiles`. + +``Sublime Text 2 - NMake Makefiles`` + Generate with :generator:`NMake Makefiles`. + +``Sublime Text 2 - Ninja`` + Generate with :generator:`Ninja`. + +``Sublime Text 2 - Unix Makefiles`` + Generate with :generator:`Unix Makefiles`. diff --git a/Help/index.rst b/Help/index.rst index 0d33825..4ef5c3f 100644 --- a/Help/index.rst +++ b/Help/index.rst @@ -27,6 +27,7 @@ Reference Manuals /manual/cmake-commands.7 /manual/cmake-generators.7 + /manual/cmake-toolchains.7 /manual/cmake-modules.7 /manual/cmake-policies.7 /manual/cmake-properties.7 diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index ddde183..ed28abd 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -7,80 +7,180 @@ cmake-generator-expressions(7) .. contents:: -Generator Expressions -===================== - -Generator expressions are evaluated during build -system generation to produce information specific to each build -configuration. Valid expressions are: - -:: - - $<0:...> = empty string (ignores "...") - $<1:...> = content of "..." - $<CONFIG:cfg> = '1' if config is "cfg", else '0' - $<CONFIGURATION> = configuration name - $<BOOL:...> = '1' if the '...' is true, else '0' - $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0' - $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example. - $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example. - $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'. - $<JOIN:list,...> = joins the list with the content of "..." - $<TARGET_NAME:...> = Marks ... as being the name of a target. This is required if exporting targets to multiple dependent export sets. The '...' must be a literal name of a target- it may not contain generator expressions. - $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise. - $<BUILD_INTERFACE:...> = content of "..." when the property is exported using export(), or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise. - $<PLATFORM_ID> = The CMake-id of the platform $<PLATFORM_ID:comp> = '1' if the The CMake-id of the platform matches comp, otherwise '0'. - $<C_COMPILER_ID> = The CMake-id of the C compiler used. - $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'. - $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used. - $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'. - $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'. - $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'. - $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'. - $<C_COMPILER_VERSION> = The version of the C compiler used. - $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'. - $<CXX_COMPILER_VERSION> = The version of the CXX compiler used. - $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'. - $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a) - $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so) - $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3) - -where "tgt" is the name of a target. Target file expressions produce -a full path, but _DIR and _NAME versions can produce the directory and -file name components: - -:: - - $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt> - $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt> - $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt> - - - -:: - - $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt. - -Note that tgt is not added as a dependency of the target this -expression is evaluated on. - -:: - - $<TARGET_POLICY:pol> = '1' if the policy was NEW when the 'head' target was created, else '0'. If the policy was not set, the warning message for the policy will be emitted. This generator expression only works for a subset of policies. - $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise. - -Boolean expressions: - -:: - - $<AND:?[,?]...> = '1' if all '?' are '1', else '0' - $<OR:?[,?]...> = '0' if all '?' are '0', else '1' - $<NOT:?> = '0' if '?' is '1', else '1' - -where '?' is always either '0' or '1'. - -Expressions with an implicit 'this' target: - -:: - - $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated. +Introduction +============ + +Generator expressions are evaluated during build system generation to produce +information specific to each build configuration. + +Generator expressions are allowed in the context of many target properties, +such as :prop_tgt:`LINK_LIBRARIES`, :prop_tgt:`INCLUDE_DIRECTORIES`, +:prop_tgt:`COMPILE_DEFINITIONS` and others. They may also be used when using +commands to populate those properties, such as :command:`target_link_libraries`, +:command:`target_include_directories`, :command:`target_compile_definitions` +and others. + +This means that they enable conditional linking, conditional +definitions used when compiling, and conditional include directories and +more. The conditions may be based on the build configuration, target +properties, platform information or any other queryable information. + +Logical Expressions +=================== + +Logical expressions are used to create conditional output. The basic +expressions are the ``0`` and ``1`` expressions. Because other logical +expressions evaluate to either ``0`` or ``1``, they can be composed to +create conditional output:: + + $<$<CONFIG:Debug>:DEBUG_MODE> + +expands to ``DEBUG_MODE`` when the ``Debug`` configuration is used, and +otherwise expands to nothing. + +``$<0:...>`` + Empty string (ignores ``...``) +``$<1:...>`` + Content of ``...`` +``$<BOOL:...>`` + ``1`` if the ``...`` is true, else ``0`` +``$<AND:?[,?]...>`` + ``1`` if all ``?`` are ``1``, else ``0`` + + The ``?`` must always be either ``0`` or ``1`` in boolean expressions. + +``$<OR:?[,?]...>`` + ``0`` if all ``?`` are ``0``, else ``1`` +``$<NOT:?>`` + ``0`` if ``?`` is ``1``, else ``1`` +``$<STREQUAL:a,b>`` + ``1`` if ``a`` is STREQUAL ``b``, else ``0`` +``$<CONFIG:cfg>`` + ``1`` if config is ``cfg``, else ``0``. This is a case-insensitive comparison. + The mapping in :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by + this expression when it is evaluated on a property on an :prop_tgt:`IMPORTED` + target. +``$<PLATFORM_ID:comp>`` + ``1`` if the CMake-id of the platform matches ``comp``, otherwise ``0``. +``$<C_COMPILER_ID:comp>`` + ``1`` if the CMake-id of the C compiler matches ``comp``, otherwise ``0``. +``$<CXX_COMPILER_ID:comp>`` + ``1`` if the CMake-id of the CXX compiler matches ``comp``, otherwise ``0``. +``$<VERSION_GREATER:v1,v2>`` + ``1`` if ``v1`` is a version greater than ``v2``, else ``0``. +``$<VERSION_LESS:v1,v2>`` + ``1`` if ``v1`` is a version less than ``v2``, else ``0``. +``$<VERSION_EQUAL:v1,v2>`` + ``1`` if ``v1`` is the same version as ``v2``, else ``0``. +``$<C_COMPILER_VERSION:ver>`` + ``1`` if the version of the C compiler matches ``ver``, otherwise ``0``. +``$<CXX_COMPILER_VERSION:ver>`` + ``1`` if the version of the CXX compiler matches ``ver``, otherwise ``0``. +``$<TARGET_POLICY:pol>`` + ``1`` if the policy ``pol`` was NEW when the 'head' target was created, + else ``0``. If the policy was not set, the warning message for the policy + will be emitted. This generator expression only works for a subset of + policies. + +Informational Expressions +========================= + +These expressions expand to some information. The information may be used +directly, eg:: + + include_directories(/usr/include/$<CXX_COMPILER_ID>/) + +expands to ``/usr/include/GNU/`` or ``/usr/include/Clang/`` etc, depending on +the Id of the compiler. + +These expressions may also may be combined with logical expressions:: + + $<$<VERSION_LESS:$<CXX_COMPILER_VERSION>,4.2.0>:OLD_COMPILER> + +expands to ``OLD_COMPILER`` if the +:variable:`CMAKE_CXX_COMPILER_VERSION <CMAKE_<LANG>_COMPILER_VERSION>` is less +than 4.2.0. + +``$<CONFIGURATION>`` + Configuration name +``$<PLATFORM_ID>`` + The CMake-id of the platform +``$<C_COMPILER_ID>`` + The CMake-id of the C compiler used. +``$<CXX_COMPILER_ID>`` + The CMake-id of the CXX compiler used. +``$<C_COMPILER_VERSION>`` + The version of the C compiler used. +``$<CXX_COMPILER_VERSION>`` + The version of the CXX compiler used. +``$<TARGET_FILE:tgt>`` + Full path to main file (.exe, .so.1.2, .a) where ``tgt`` is the name of a target. +``$<TARGET_FILE_NAME:tgt>`` + Name of main file (.exe, .so.1.2, .a). +``$<TARGET_FILE_DIR:tgt>`` + Directory of main file (.exe, .so.1.2, .a). +``$<TARGET_LINKER_FILE:tgt>`` + File used to link (.a, .lib, .so) where ``tgt`` is the name of a target. +``$<TARGET_LINKER_FILE_NAME:tgt>`` + Name of file used to link (.a, .lib, .so). +``$<TARGET_LINKER_FILE_DIR:tgt>`` + Directory of file used to link (.a, .lib, .so). +``$<TARGET_SONAME_FILE:tgt>`` + File with soname (.so.3) where ``tgt`` is the name of a target. +``$<TARGET_SONAME_FILE_NAME:tgt>`` + Name of file with soname (.so.3). +``$<TARGET_SONAME_FILE_DIR:tgt>`` + Directory of with soname (.so.3). +``$<TARGET_PROPERTY:tgt,prop>`` + Value of the property ``prop`` on the target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. +``$<TARGET_PROPERTY:prop>`` + Value of the property ``prop`` on the target on which the generator + expression is evaluated. +``$<INSTALL_PREFIX>`` + Content of the install prefix when the target is exported via + :command:`install(EXPORT)` and empty otherwise. + +Output Expressions +================== + +These expressions generate output, in some cases depending on an input. These +expressions may be combined with other expressions for information or logical +comparison:: + + -I$<JOIN:$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>, -I> + +generates a string of the entries in the :prop_tgt:`INCLUDE_DIRECTORIES` target +property with each entry preceeded by ``-I``. Note that a more-complete use +in this situation would require first checking if the INCLUDE_DIRECTORIES +property is non-empty:: + + $<$<BOOL:$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>>:-I$<JOIN:$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>, -I>> + +``$<JOIN:list,...>`` + Joins the list with the content of ``...`` +``$<ANGLE-R>`` + A literal ``>``. Used to compare strings which contain a ``>`` for example. +``$<COMMA>`` + A literal ``,``. Used to compare strings which contain a ``,`` for example. +``$<SEMICOLON>`` + A literal ``;``. Used to prevent list expansion on an argument with ``;``. +``$<TARGET_NAME:...>`` + Marks ``...`` as being the name of a target. This is required if exporting + targets to multiple dependent export sets. The ``...`` must be a literal + name of a target- it may not contain generator expressions. +``$<INSTALL_INTERFACE:...>`` + Content of ``...`` when the property is exported using :command:`install(EXPORT)`, + and empty otherwise. +``$<BUILD_INTERFACE:...>`` + Content of ``...`` when the property is exported using :command:`export`, or + when the target is used by another target in the same buildsystem. Expands to + the empty string otherwise. +``$<LOWER_CASE:...>`` + Content of ``...`` converted to lower case. +``$<UPPER_CASE:...>`` + Content of ``...`` converted to upper case. +``$<MAKE_C_IDENTIFIER:...>`` + Content of ``...`` converted to a C identifier. diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index ec1f58a..b72c7ef 100644 --- a/Help/manual/cmake-generators.7.rst +++ b/Help/manual/cmake-generators.7.rst @@ -7,40 +7,79 @@ cmake-generators(7) .. contents:: -All Generators -============== +Introduction +============ + +A *CMake Generator* is responsible for writing the input files for +a native build system. Exactly one of the `CMake Generators`_ must be +selected for a build tree to determine what native build system is to +be used. Optionally one of the `Extra Generators`_ may be selected +as a variant of some of the `Command-Line Build Tool Generators`_ to +produce project files for an auxiliary IDE. + +CMake Generators are platform-specific so each may be available only +on certain platforms. The :manual:`cmake(1)` command-line tool ``--help`` +output lists available generators on the current platform. Use its ``-G`` +option to specify the generator for a new build tree. +The :manual:`cmake-gui(1)` offers interactive selection of a generator +when creating a new build tree. + +CMake Generators +================ + +Command-Line Build Tool Generators +---------------------------------- + +These generators support command-line build tools. In order to use them, +one must launch CMake from a command-line prompt whose environment is +already configured for the chosen compiler and build tool. .. toctree:: :maxdepth: 1 /generator/Borland Makefiles - /generator/CodeBlocks - MinGW Makefiles - /generator/CodeBlocks - Ninja - /generator/CodeBlocks - NMake Makefiles - /generator/CodeBlocks - Unix Makefiles - /generator/Eclipse CDT4 - MinGW Makefiles - /generator/Eclipse CDT4 - Ninja - /generator/Eclipse CDT4 - NMake Makefiles - /generator/Eclipse CDT4 - Unix Makefiles - /generator/KDevelop3 - /generator/KDevelop3 - Unix Makefiles - /generator/MinGW Makefiles /generator/MSYS Makefiles - /generator/Ninja - /generator/NMake Makefiles JOM + /generator/MinGW Makefiles /generator/NMake Makefiles - /generator/Sublime Text 2 - MinGW Makefiles - /generator/Sublime Text 2 - Ninja - /generator/Sublime Text 2 - NMake Makefiles - /generator/Sublime Text 2 - Unix Makefiles + /generator/NMake Makefiles JOM + /generator/Ninja /generator/Unix Makefiles - /generator/Visual Studio 10 2010 - /generator/Visual Studio 11 2012 - /generator/Visual Studio 12 2013 + /generator/Watcom WMake + +IDE Build Tool Generators +------------------------- + +These generators support Integrated Development Environment (IDE) +project files. Since the IDEs configure their own environment +one may launch CMake from any environment. + +.. toctree:: + :maxdepth: 1 + /generator/Visual Studio 6 - /generator/Visual Studio 7 .NET 2003 /generator/Visual Studio 7 + /generator/Visual Studio 7 .NET 2003 /generator/Visual Studio 8 2005 /generator/Visual Studio 9 2008 - /generator/Watcom WMake + /generator/Visual Studio 10 2010 + /generator/Visual Studio 11 2012 + /generator/Visual Studio 12 2013 /generator/Xcode + +Extra Generators +================ + +Some of the `CMake Generators`_ listed in the :manual:`cmake(1)` +command-line tool ``--help`` output may have variants that specify +an extra generator for an auxiliary IDE tool. Such generator +names have the form ``<extra-generator> - <main-generator>``. +The following extra generators are known to CMake. + +.. toctree:: + :maxdepth: 1 + + /generator/CodeBlocks + /generator/Eclipse CDT4 + /generator/KDevelop3 + /generator/Kate + /generator/Sublime Text 2 diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index 7285897..61d0a42 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -312,6 +312,9 @@ inside out, e.g. ``${outer_${inner_variable}_variable}``. The `Variables`_ section documents the scope of variable names and how their values are set. +An *environment variable reference* has the form ``$ENV{VAR}`` and +is evaluated in the same contexts as a normal variable reference. + Comments -------- diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 01efcf7..f148a51 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -74,6 +74,7 @@ All Modules /module/FindAVIFile /module/FindBISON /module/FindBLAS + /module/FindBacktrace /module/FindBoost /module/FindBullet /module/FindBZip2 diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 2430ee9..5e94f89 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -73,3 +73,5 @@ All Policies /policy/CMP0037 /policy/CMP0038 /policy/CMP0039 + /policy/CMP0040 + /policy/CMP0041 diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index d6d42ad..d569e31 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -27,7 +27,9 @@ Properties of Global Scope /prop_gbl/IN_TRY_COMPILE /prop_gbl/PACKAGES_FOUND /prop_gbl/PACKAGES_NOT_FOUND + /prop_gbl/JOB_POOLS /prop_gbl/PREDEFINED_TARGETS_FOLDER + /prop_gbl/ECLIPSE_EXTRA_NATURES /prop_gbl/REPORT_UNDEFINED_PROPERTIES /prop_gbl/RULE_LAUNCH_COMPILE /prop_gbl/RULE_LAUNCH_CUSTOM @@ -79,6 +81,7 @@ Properties on Targets /prop_tgt/ARCHIVE_OUTPUT_DIRECTORY /prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG /prop_tgt/ARCHIVE_OUTPUT_NAME + /prop_tgt/AUTOGEN_TARGET_DEPENDS /prop_tgt/AUTOMOC_MOC_OPTIONS /prop_tgt/AUTOMOC /prop_tgt/AUTOUIC @@ -138,6 +141,7 @@ Properties on Targets /prop_tgt/INSTALL_NAME_DIR /prop_tgt/INSTALL_RPATH /prop_tgt/INSTALL_RPATH_USE_LINK_PATH + /prop_tgt/INTERFACE_AUTOUIC_OPTIONS /prop_tgt/INTERFACE_COMPILE_DEFINITIONS /prop_tgt/INTERFACE_COMPILE_OPTIONS /prop_tgt/INTERFACE_INCLUDE_DIRECTORIES @@ -146,6 +150,8 @@ Properties on Targets /prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES /prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG /prop_tgt/INTERPROCEDURAL_OPTIMIZATION + /prop_tgt/JOB_POOL_COMPILE + /prop_tgt/JOB_POOL_LINK /prop_tgt/LABELS /prop_tgt/LANG_VISIBILITY_PRESET /prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst new file mode 100644 index 0000000..fbe546e --- /dev/null +++ b/Help/manual/cmake-toolchains.7.rst @@ -0,0 +1,160 @@ +.. cmake-manual-description: CMake Toolchains Reference + +cmake-toolchains(7) +******************* + +.. only:: html or latex + + .. contents:: + +Introduction +============ + +CMake uses a toolchain of utilities to compile, link libraries and create +archives, and other tasks to drive the build. The toolchain utilities available +are determined by the languages enabled. In normal builds, CMake automatically +determines the toolchain for host builds based on system introspection and +defaults. In cross-compiling scenarios, a toolchain file may be specified +with information about compiler and utility paths. + +Languages +========= + +Languages are enabled by the :command:`project` command. If no project command +is in the top-level CMakeLists file, one will be implicitly generated. By default +the enabled languages are C and CXX:: + + project(C_Only C) + +A special value of NONE can also be used with the :command:`project` command +to enable no languages:: + + project(MyProject NONE) + +The :command:`enable_language` command can be used to enable languages after the +:command:`project` command:: + + enable_language(CXX) + +When a language is enabled, CMake finds a compiler for that language, and +determines some information, such as the vendor and version of the compiler, +the target architecture and bitwidth, the location of corresponding utilities +etc. + +The :prop_gbl:`ENABLED_LANGUAGES` global property contains the languages which +are currently enabled. + +Variables and Properties +======================== + +Several variables relate to the language components of a toolchain which are +enabled. :variable:`CMAKE_<LANG>_COMPILER` is the full path to the compiler used +for ``<LANG>``. :variable:`CMAKE_<LANG>_COMPILER_ID` is the identifier used +by CMake for the compiler and :variable:`CMAKE_<LANG>_COMPILER_VERSION` is the +version of the compiler. + +The :variable:`CMAKE_<LANG>_FLAGS` variables and the configuration-specific +equivalents contain flags that will be added to the compile command when +compiling a file of a particular language. + +As the linker is invoked by the compiler driver, CMake needs a way to determine +which compiler to use to invoke the linker. This is calculated by the +:prop_sf:`LANGUAGE` of source files in the target, and in the case of static +libraries, the language of the dependent libraries. The choice CMake makes may +be overridden with the :prop_tgt:`LINKER_LANGUAGE` target property. + +Toolchain Features +================== + +CMake provides the :command:`try_compile` command and wrapper macros such as +:module:`CheckCXXSourceCompiles`, :module:`CheckCXXSymbolExists` and +:module:`CheckIncludeFile` to test capability and availability of various +toolchain features. These APIs test the toolchain in some way and cache the +result so that the test does not have to be performed again the next time +CMake runs. + +Some toolchain features have built-in handling in CMake, and do not require +compile-tests. For example, :prop_tgt:`POSITION_INDEPENDENT_CODE` allows +specifying that a target should be built as position-independent code, if +the compiler supports that feature. The :prop_tgt:`<LANG>_VISIBILITY_PRESET` +and :prop_tgt:`VISIBILITY_INLINES_HIDDEN` target properties add flags for +hidden visibility, if supported by the compiler. + +Cross Compiling +=============== + +If :manual:`cmake(1)` is invoked with the command line parameter +``-DCMAKE_TOOLCHAIN_FILE=path/to/file``, the file will be loaded early to set +values for the compilers. A typical cross-compiling toolchain has content such +as:: + + set(CMAKE_SYSTEM_NAME Linux) + + set(CMAKE_SYSROOT /home/devel/rasp-pi-rootfs) + set(CMAKE_STAGING_PREFIX /home/devel/stage) + + set(CMAKE_C_COMPILER /home/devel/gcc-4.7-linaro-rpi-gnueabihf/bin/arm-linux-gnueabihf-gcc) + set(CMAKE_CXX_COMPILER /home/devel/gcc-4.7-linaro-rpi-gnueabihf/bin/arm-linux-gnueabihf-g++) + + set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) + set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) + set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY) + set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY) + +The :variable:`CMAKE_SYSTEM_NAME` is the CMake-identifier of the target platform +to build for. + +The :variable:`CMAKE_SYSROOT` is optional, and may be specified if a sysroot +is available. + +The :variable:`CMAKE_STAGING_PREFIX` is also optional. It may be used to specify +a path on the host to install to. The :variable:`CMAKE_INSTALL_PREFIX` is always +the runtime installation location, even when cross-compiling. + +The :variable:`CMAKE_<LANG>_COMPILER` variables may be set to full paths, or to +names of compilers to search for in standard locations. In cases where CMake does +not have enough information to extract information from the compiler, the +:module:`CMakeForceCompiler` module can be used to bypass some of the checks. + +CMake ``find_*`` commands will look in the sysroot, and the :variable:`CMAKE_FIND_ROOT_PATH` +entries by default in all cases, as well as looking in the host system root prefix. +Although this can be controlled on a case-by-case basis, when cross-compiling, it +can be useful to exclude looking in either the host or the target for particular +artifacts. Generally, includes, libraries and packages should be found in the +target system prefixes, whereas executables which must be run as part of the build +should be found only on the host and not on the target. This is the purpose of +the ``CMAKE_FIND_ROOT_PATH_MODE_*`` variables. + +Some compilers are inherently cross compilers, such as Clang and the QNX QCC +compiler. The :variable:`CMAKE_<LANG>_COMPILER_TARGET` can be set to pass a +value to those supported compilers when compiling:: + + set(CMAKE_SYSTEM_NAME Linux) + + set(triple arm-linux-gnueabihf) + + set(CMAKE_C_COMPILER clang) + set(CMAKE_C_COMPILER_TARGET ${triple}) + set(CMAKE_CXX_COMPILER clang++) + set(CMAKE_CXX_COMPILER_TARGET ${triple}) + +Or, for QCC:: + + set(CMAKE_SYSTEM_NAME QNX) + + set(arch gcc_ntoarmv7le) + + set(CMAKE_C_COMPILER qcc) + set(CMAKE_C_COMPILER_TARGET ${arch}) + set(CMAKE_CXX_COMPILER QCC) + set(CMAKE_CXX_COMPILER_TARGET ${arch}) + + +Similarly, some compilers do not ship their own supplementary utilities +such as linkers, but provide a way to specify the location of the external +toolchain which will be used by the compiler driver. The +:variable:`CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN` variable can be set in a +toolchain file to pass the path to the compiler driver. + +The :variable:`CMAKE_CROSSCOMPILING` variable is set to true when CMake is +cross-compiling. diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index d1176ad..d86db37 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -41,6 +41,8 @@ Variables that Provide Information /variable/CMAKE_HOME_DIRECTORY /variable/CMAKE_IMPORT_LIBRARY_PREFIX /variable/CMAKE_IMPORT_LIBRARY_SUFFIX + /variable/CMAKE_JOB_POOL_COMPILE + /variable/CMAKE_JOB_POOL_LINK /variable/CMAKE_LINK_LIBRARY_SUFFIX /variable/CMAKE_MAJOR_VERSION /variable/CMAKE_MAKE_PROGRAM @@ -62,6 +64,7 @@ Variables that Provide Information /variable/CMAKE_STANDARD_LIBRARIES /variable/CMAKE_STATIC_LIBRARY_PREFIX /variable/CMAKE_STATIC_LIBRARY_SUFFIX + /variable/CMAKE_TOOLCHAIN_FILE /variable/CMAKE_TWEAK_VERSION /variable/CMAKE_VERBOSE_MAKEFILE /variable/CMAKE_VERSION @@ -94,10 +97,16 @@ Variables that Change Behavior /variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName /variable/CMAKE_ERROR_DEPRECATED /variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION + /variable/CMAKE_SYSROOT /variable/CMAKE_FIND_LIBRARY_PREFIXES /variable/CMAKE_FIND_LIBRARY_SUFFIXES - /variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE /variable/CMAKE_FIND_NO_INSTALL_PREFIX + /variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE + /variable/CMAKE_FIND_ROOT_PATH + /variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE + /variable/CMAKE_FIND_ROOT_PATH_MODE_LIBRARY + /variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE + /variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM /variable/CMAKE_IGNORE_PATH /variable/CMAKE_INCLUDE_PATH /variable/CMAKE_INCLUDE_DIRECTORIES_BEFORE @@ -112,6 +121,7 @@ Variables that Change Behavior /variable/CMAKE_PREFIX_PATH /variable/CMAKE_PROGRAM_PATH /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY + /variable/CMAKE_STAGING_PREFIX /variable/CMAKE_SYSTEM_IGNORE_PATH /variable/CMAKE_SYSTEM_INCLUDE_PATH /variable/CMAKE_SYSTEM_LIBRARY_PATH @@ -203,6 +213,7 @@ Variables that Control the Build /variable/CMAKE_NO_BUILTIN_CHRPATH /variable/CMAKE_NO_SYSTEM_FROM_IMPORTED /variable/CMAKE_PDB_OUTPUT_DIRECTORY + /variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_POSITION_INDEPENDENT_CODE /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY /variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG @@ -237,6 +248,8 @@ Variables for Languages /variable/CMAKE_LANG_COMPILER_ID /variable/CMAKE_LANG_COMPILER_LOADED /variable/CMAKE_LANG_COMPILER + /variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN + /variable/CMAKE_LANG_COMPILER_TARGET /variable/CMAKE_LANG_COMPILER_VERSION /variable/CMAKE_LANG_CREATE_SHARED_LIBRARY /variable/CMAKE_LANG_CREATE_SHARED_MODULE diff --git a/Help/module/FindBacktrace.rst b/Help/module/FindBacktrace.rst new file mode 100644 index 0000000..e1ca48c --- /dev/null +++ b/Help/module/FindBacktrace.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindBacktrace.cmake diff --git a/Help/policy/CMP0037.rst b/Help/policy/CMP0037.rst index 5df3c00..059b2e6 100644 --- a/Help/policy/CMP0037.rst +++ b/Help/policy/CMP0037.rst @@ -1,19 +1,24 @@ CMP0037 ------- -Target names should match a validity pattern. +Target names should not be reserved and should match a validity pattern. -CMake 2.8.12 and lower allowed creating targets using :command:`add_library` and -:command:`add_executable` with unrestricted choice for the target name. Newer -cmake features such as :manual:`cmake-generator-expressions(7)` and some +CMake 2.8.12 and lower allowed creating targets using :command:`add_library`, +:command:`add_executable` and :command:`add_custom_target` with unrestricted +choice for the target name. Newer cmake features such +as :manual:`cmake-generator-expressions(7)` and some diagnostics expect target names to match a restricted pattern. Target names may contain upper and lower case letters, numbers, the underscore character (_), dot(.), plus(+) and minus(-). As a special case, ALIAS targets and INTERFACE library targets may contain two consequtive colons. -The OLD behavior for this policy is to allow creating targets which do not match -the validity pattern. The NEW behavior for this policy is to report an error +Target names reserved by one or more CMake generators are not allowed. +Among others these include "all", "help" and "test". + +The OLD behavior for this policy is to allow creating targets with +reserved names or which do not match the validity pattern. +The NEW behavior for this policy is to report an error if an add_* command is used with an invalid target name. This policy was introduced in CMake version 3.0.0. CMake version diff --git a/Help/policy/CMP0040.rst b/Help/policy/CMP0040.rst new file mode 100644 index 0000000..5d27f62 --- /dev/null +++ b/Help/policy/CMP0040.rst @@ -0,0 +1,16 @@ +CMP0040 +------- + +The target in the TARGET signature of add_custom_command() must exist. + +CMake 2.8.12 and lower silently ignored a custom command created with +the TARGET signature of :command:`add_custom_command` +if the target is unknown. + +The OLD behavior for this policy is to ignore custom commands +for unknown targets. The NEW behavior for this policy is to report an error +if the target referenced in :command:`add_custom_command` is unknown. + +This policy was introduced in CMake version 3.0.0. CMake version +|release| warns when the policy is not set and uses OLD behavior. Use +the cmake_policy command to set it to OLD or NEW explicitly. diff --git a/Help/policy/CMP0041.rst b/Help/policy/CMP0041.rst new file mode 100644 index 0000000..acb85af --- /dev/null +++ b/Help/policy/CMP0041.rst @@ -0,0 +1,25 @@ +CMP0041 +------- + +Error on relative include with generator expression. + +Diagnostics in CMake 2.8.12 and lower silently ignored an entry in the +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of a target if it contained a generator +expression at any position. + +The path entries in that target property should not be relative. High-level +API should ensure that by adding either a source directory or a install +directory prefix, as appropriate. + +As an additional diagnostic, the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` generated +on an :prop_tgt:`IMPORTED` target for the install location should not contain +paths in the source directory or the build directory. + +The OLD behavior for this policy is to ignore relative path entries if they +contain a generator expression. The NEW behavior for this policy is to report +an error if a generator expression appears in another location and the path is +relative. + +This policy was introduced in CMake version 3.0.0. CMake version +|release| warns when the policy is not set and uses OLD behavior. Use +the cmake_policy command to set it to OLD or NEW explicitly. diff --git a/Help/prop_gbl/ECLIPSE_EXTRA_NATURES.rst b/Help/prop_gbl/ECLIPSE_EXTRA_NATURES.rst new file mode 100644 index 0000000..6d1529d --- /dev/null +++ b/Help/prop_gbl/ECLIPSE_EXTRA_NATURES.rst @@ -0,0 +1,8 @@ +ECLIPSE_EXTRA_NATURES +--------------------- + +List of natures to add to the generated Eclipse project file. + +Eclipse projects specify language plugins by using natures. This property +should be set to the unique identifier for a nature (which looks like a Java +package name). diff --git a/Help/prop_gbl/JOB_POOLS.rst b/Help/prop_gbl/JOB_POOLS.rst new file mode 100644 index 0000000..98b9f7e --- /dev/null +++ b/Help/prop_gbl/JOB_POOLS.rst @@ -0,0 +1,20 @@ +JOB_POOLS +--------- + +Ninja only: List of available pools. + +A pool is a named integer property and defines the maximum number +of concurrent jobs which can be started by a rule assigned to the pool. +The :prop_gbl:`JOB_POOLS` property is a semicolon-separated list of +pairs using the syntax NAME=integer (without a space after the equality sign). + +For instance: + +.. code-block:: cmake + + set_property(GLOBAL PROPERTY JOB_POOLS two_jobs=2 ten_jobs=10) + +Defined pools could be used globally by setting +:variable:`CMAKE_JOB_POOL_COMPILE` and :variable:`CMAKE_JOB_POOL_LINK` +or per target by setting the target properties +:prop_tgt:`JOB_POOL_COMPILE` and :prop_tgt:`JOB_POOL_LINK`. diff --git a/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst new file mode 100644 index 0000000..006c83a --- /dev/null +++ b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst @@ -0,0 +1,14 @@ +AUTOGEN_TARGET_DEPENDS +---------------------- + +Target dependencies of the corresponding ``_automoc`` target. + +Targets which have their :prop_tgt:`AUTOMOC` target set to true have a +corresponding ``_automoc`` target which is used to autogenerate generate moc +files. As this ``_automoc`` target is created at generate-time, it is not +possible to define dependencies of it, such as to create inputs for the moc +executable. + +The ``AUTOGEN_TARGET_DEPENDS`` target can be set instead to a list of dependencies +for the ``_automoc`` target. The buildsystem will be generated to depend on its +contents. diff --git a/Help/prop_tgt/AUTOUIC_OPTIONS.rst b/Help/prop_tgt/AUTOUIC_OPTIONS.rst index c6cf885..aeec38b 100644 --- a/Help/prop_tgt/AUTOUIC_OPTIONS.rst +++ b/Help/prop_tgt/AUTOUIC_OPTIONS.rst @@ -15,3 +15,7 @@ This property is initialized by the value of the variable The options set on the target may be overridden by :prop_sf:`AUTOUIC_OPTIONS` set on the .ui source file. + +This property may use "generator expressions" with the syntax "$<...>". +See the :manual:`cmake-generator-expressions(7)` manual for available +expressions. diff --git a/Help/prop_tgt/INTERFACE_AUTOUIC_OPTIONS.rst b/Help/prop_tgt/INTERFACE_AUTOUIC_OPTIONS.rst new file mode 100644 index 0000000..e97d293 --- /dev/null +++ b/Help/prop_tgt/INTERFACE_AUTOUIC_OPTIONS.rst @@ -0,0 +1,14 @@ +INTERFACE_AUTOUIC_OPTIONS +------------------------- + +List of interface options to pass to uic. + +Targets may populate this property to publish the options +required to use when invoking ``uic``. Consuming targets can add entries to their +own :prop_tgt:`AUTOUIC_OPTIONS` property such as +``$<TARGET_PROPERTY:foo,INTERFACE_AUTOUIC_OPTIONS>`` to use the uic options +specified in the interface of ``foo``. This is done automatically by +the :command:`target_link_libraries` command. + +This property supports generator expressions. See the +:manual:`cmake-generator-expressions(7)` manual for available expressions. diff --git a/Help/prop_tgt/JOB_POOL_COMPILE.rst b/Help/prop_tgt/JOB_POOL_COMPILE.rst new file mode 100644 index 0000000..5d8e940 --- /dev/null +++ b/Help/prop_tgt/JOB_POOL_COMPILE.rst @@ -0,0 +1,17 @@ +JOB_POOL_COMPILE +---------------- + +Ninja only: Pool used for compiling. + +The number of parallel compile processes could be limited by defining +pools with the global :prop_gbl:`JOB_POOLS` +property and then specifying here the pool name. + +For instance: + +.. code-block:: cmake + + set_property(TARGET myexe PROPERTY JOB_POOL_COMPILE ten_jobs) + +This property is initialized by the value of +:variable:`CMAKE_JOB_POOL_COMPILE`. diff --git a/Help/prop_tgt/JOB_POOL_LINK.rst b/Help/prop_tgt/JOB_POOL_LINK.rst new file mode 100644 index 0000000..716f53f --- /dev/null +++ b/Help/prop_tgt/JOB_POOL_LINK.rst @@ -0,0 +1,16 @@ +JOB_POOL_LINK +------------- + +Ninja only: Pool used for linking. + +The number of parallel link processes could be limited by defining +pools with the global :prop_gbl:`JOB_POOLS` +property and then specifing here the pool name. + +For instance: + +.. code-block:: cmake + + set_property(TARGET myexe PROPERTY JOB_POOL_LINK two_jobs) + +This property is initialized by the value of :variable:`CMAKE_JOB_POOL_LINK`. diff --git a/Help/prop_tgt/PDB_NAME.rst b/Help/prop_tgt/PDB_NAME.rst index fe059e0..e8fc3be 100644 --- a/Help/prop_tgt/PDB_NAME.rst +++ b/Help/prop_tgt/PDB_NAME.rst @@ -1,10 +1,13 @@ PDB_NAME -------- -Output name for MS debug symbols .pdb file from linker. +Output name for the MS debug symbol ``.pdb`` file generated by the +linker for an executable or shared library target. -Set the base name for debug symbols file created for an executable or -shared library target. If not set, the logical target name is used by -default. +This property specifies the base name for the debug symbols file. +If not set, the logical target name is used by default. -This property is not implemented by the Visual Studio 6 generator. +.. include:: PDB_NOTE.txt + +This property is not implemented by the :generator:`Visual Studio 6` +generator. diff --git a/Help/prop_tgt/PDB_NAME_CONFIG.rst b/Help/prop_tgt/PDB_NAME_CONFIG.rst index 50c3aa2..c846b57 100644 --- a/Help/prop_tgt/PDB_NAME_CONFIG.rst +++ b/Help/prop_tgt/PDB_NAME_CONFIG.rst @@ -1,8 +1,10 @@ PDB_NAME_<CONFIG> ----------------- -Per-configuration name for MS debug symbols .pdb file. +Per-configuration output name for the MS debug symbol ``.pdb`` file +generated by the linker for an executable or shared library target. -This is the configuration-specific version of PDB_NAME. +This is the configuration-specific version of :prop_tgt:`PDB_NAME`. -This property is not implemented by the Visual Studio 6 generator. +This property is not implemented by the :generator:`Visual Studio 6` +generator. diff --git a/Help/prop_tgt/PDB_NOTE.txt b/Help/prop_tgt/PDB_NOTE.txt new file mode 100644 index 0000000..e55aba2 --- /dev/null +++ b/Help/prop_tgt/PDB_NOTE.txt @@ -0,0 +1,8 @@ +.. note:: + This property does not apply to STATIC library targets because no linker + is invoked to produce them so they have no linker-generated ``.pdb`` file + containing debug symbols. + + The compiler-generated program database files specified by the MSVC + ``/Fd`` flag are not the same as linker-generated program database + files and so are not influenced by this property. diff --git a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst index d973e90d..9a863a1 100644 --- a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst +++ b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst @@ -1,11 +1,15 @@ PDB_OUTPUT_DIRECTORY -------------------- -Output directory for MS debug symbols .pdb file from linker. +Output directory for the MS debug symbols ``.pdb`` file +generated by the linker for an executable or shared library target. This property specifies the directory into which the MS debug symbols will be placed by the linker. This property is initialized by the -value of the variable CMAKE_PDB_OUTPUT_DIRECTORY if it is set when a -target is created. +value of the :variable:`CMAKE_PDB_OUTPUT_DIRECTORY` variable if it is +set when a target is created. -This property is not implemented by the Visual Studio 6 generator. +.. include:: PDB_NOTE.txt + +This property is not implemented by the :generator:`Visual Studio 6` +generator. diff --git a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst index 25ab944..caec2de 100644 --- a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst +++ b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst @@ -1,13 +1,15 @@ PDB_OUTPUT_DIRECTORY_<CONFIG> ----------------------------- -Per-configuration output directory for MS debug symbols .pdb files. +Per-configuration output directory for the MS debug symbol ``.pdb`` file +generated by the linker for an executable or shared library target. -This is a per-configuration version of PDB_OUTPUT_DIRECTORY, but -multi-configuration generators (VS, Xcode) do NOT append a +This is a per-configuration version of :prop_tgt:`PDB_OUTPUT_DIRECTORY`, +but multi-configuration generators (VS, Xcode) do NOT append a per-configuration subdirectory to the specified directory. This -property is initialized by the value of the variable -CMAKE_PDB_OUTPUT_DIRECTORY_<CONFIG> if it is set when a target is -created. +property is initialized by the value of the +:variable:`CMAKE_PDB_OUTPUT_DIRECTORY_<CONFIG>` variable if it is +set when a target is created. -This property is not implemented by the Visual Studio 6 generator. +This property is not implemented by the :generator:`Visual Studio 6` +generator. diff --git a/Help/variable/CMAKE_DEBUG_TARGET_PROPERTIES.rst b/Help/variable/CMAKE_DEBUG_TARGET_PROPERTIES.rst index 2ded823..6b17f6e 100644 --- a/Help/variable/CMAKE_DEBUG_TARGET_PROPERTIES.rst +++ b/Help/variable/CMAKE_DEBUG_TARGET_PROPERTIES.rst @@ -6,6 +6,6 @@ Enables tracing output for target properties. This variable can be populated with a list of properties to generate debug output for when evaluating target properties. Currently it can only be used when evaluating the INCLUDE_DIRECTORIES, -COMPILE_DEFINITIONS and COMPILE_OPTIONS target properties. In that -case, it outputs a backtrace for each entry in the target property. +COMPILE_DEFINITIONS, COMPILE_OPTIONS and AUTOUIC_OPTIONS target properties. +In that case, it outputs a backtrace for each entry in the target property. Default is unset. diff --git a/Help/variable/CMAKE_FIND_NO_INSTALL_PREFIX.rst b/Help/variable/CMAKE_FIND_NO_INSTALL_PREFIX.rst index 91231b0..70d920b 100644 --- a/Help/variable/CMAKE_FIND_NO_INSTALL_PREFIX.rst +++ b/Help/variable/CMAKE_FIND_NO_INSTALL_PREFIX.rst @@ -3,11 +3,13 @@ CMAKE_FIND_NO_INSTALL_PREFIX Ignore the :variable:`CMAKE_INSTALL_PREFIX` when searching for assets. -CMake adds the :variable:`CMAKE_INSTALL_PREFIX` to the +CMake adds the :variable:`CMAKE_INSTALL_PREFIX` and the +:variable:`CMAKE_STAGING_PREFIX` variable to the :variable:`CMAKE_SYSTEM_PREFIX_PATH` by default. This variable may be set on the command line to control that behavior. Set :variable:`CMAKE_FIND_NO_INSTALL_PREFIX` to TRUE to tell find_package not -to search in the :variable:`CMAKE_INSTALL_PREFIX` by default. Note that the +to search in the :variable:`CMAKE_INSTALL_PREFIX` or +:variable:`CMAKE_STAGING_PREFIX` by default. Note that the prefix may still be searched for other reasons, such as being the same prefix as the CMake installation, or for being a built-in system prefix. diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH.rst b/Help/variable/CMAKE_FIND_ROOT_PATH.rst new file mode 100644 index 0000000..67948f7 --- /dev/null +++ b/Help/variable/CMAKE_FIND_ROOT_PATH.rst @@ -0,0 +1,8 @@ +CMAKE_FIND_ROOT_PATH +-------------------- + +List of root paths to search on the filesystem. + +This variable is most useful when cross-compiling. CMake uses the paths in +this list as alternative roots to find filesystem items with :command:`find_package`, +:command:`find_library` etc. diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.rst b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.rst new file mode 100644 index 0000000..df1af5a --- /dev/null +++ b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.rst @@ -0,0 +1,6 @@ +CMAKE_FIND_ROOT_PATH_MODE_INCLUDE +--------------------------------- + +.. |FIND_XXX| replace:: :command:`find_file` and :command:`find_path` + +.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.rst b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.rst new file mode 100644 index 0000000..52ab89d --- /dev/null +++ b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.rst @@ -0,0 +1,6 @@ +CMAKE_FIND_ROOT_PATH_MODE_LIBRARY +--------------------------------- + +.. |FIND_XXX| replace:: :command:`find_library` + +.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.rst b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.rst new file mode 100644 index 0000000..3872947 --- /dev/null +++ b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.rst @@ -0,0 +1,6 @@ +CMAKE_FIND_ROOT_PATH_MODE_PACKAGE +--------------------------------- + +.. |FIND_XXX| replace:: :command:`find_package` + +.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.rst b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.rst new file mode 100644 index 0000000..d24a78a --- /dev/null +++ b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.rst @@ -0,0 +1,6 @@ +CMAKE_FIND_ROOT_PATH_MODE_PROGRAM +--------------------------------- + +.. |FIND_XXX| replace:: :command:`find_program` + +.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_XXX.txt b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_XXX.txt new file mode 100644 index 0000000..ab65e09 --- /dev/null +++ b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_XXX.txt @@ -0,0 +1,8 @@ +This variable controls whether the :variable:`CMAKE_FIND_ROOT_PATH` and +:variable:`CMAKE_SYSROOT` are used by |FIND_XXX|. + +If set to ``ONLY``, then only the roots in :variable:`CMAKE_FIND_ROOT_PATH` +will be searched. If set to ``NEVER``, then the roots in +:variable:`CMAKE_FIND_ROOT_PATH` will be ignored and only the host system +root will be used. If set to ``BOTH``, then the host system paths and the +paths in :variable:`CMAKE_FIND_ROOT_PATH` will be searched. diff --git a/Help/variable/CMAKE_JOB_POOL_COMPILE.rst b/Help/variable/CMAKE_JOB_POOL_COMPILE.rst new file mode 100644 index 0000000..e5c2d9a --- /dev/null +++ b/Help/variable/CMAKE_JOB_POOL_COMPILE.rst @@ -0,0 +1,6 @@ +CMAKE_JOB_POOL_COMPILE +---------------------- + +This variable is used to initialize the :prop_tgt:`JOB_POOL_COMPILE` +property on all the targets. See :prop_tgt:`JOB_POOL_COMPILE` +for additional information. diff --git a/Help/variable/CMAKE_JOB_POOL_LINK.rst b/Help/variable/CMAKE_JOB_POOL_LINK.rst new file mode 100644 index 0000000..338f771 --- /dev/null +++ b/Help/variable/CMAKE_JOB_POOL_LINK.rst @@ -0,0 +1,6 @@ +CMAKE_JOB_POOL_LINK +---------------------- + +This variable is used to initialize the :prop_tgt:`JOB_POOL_LINK` +property on all the targets. See :prop_tgt:`JOB_POOL_LINK` +for additional information. diff --git a/Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst b/Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst new file mode 100644 index 0000000..033998d --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst @@ -0,0 +1,13 @@ +CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN +---------------------------------------- + +The external toolchain for cross-compiling, if supported. + +Some compiler toolchains do not ship their own auxilliary utilities such as +archivers and linkers. The compiler driver may support a command-line argument +to specify the location of such tools. CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN +may be set to a path to a path to the external toolchain and will be passed +to the compiler driver if supported. + +This variable may only be set in a toolchain file specified by +the :variable:`CMAKE_TOOLCHAIN_FILE` variable. diff --git a/Help/variable/CMAKE_LANG_COMPILER_TARGET.rst b/Help/variable/CMAKE_LANG_COMPILER_TARGET.rst new file mode 100644 index 0000000..656c57d --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_TARGET.rst @@ -0,0 +1,11 @@ +CMAKE_<LANG>_COMPILER_TARGET +---------------------------- + +The target for cross-compiling, if supported. + +Some compiler drivers are inherently cross-compilers, such as clang and +QNX qcc. These compiler drivers support a command-line argument to specify +the target to cross-compile for. + +This variable may only be set in a toolchain file specified by +the :variable:`CMAKE_TOOLCHAIN_FILE` variable. diff --git a/Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY.rst b/Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY.rst index 938d159..763bcb3 100644 --- a/Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY.rst +++ b/Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY.rst @@ -1,8 +1,9 @@ CMAKE_PDB_OUTPUT_DIRECTORY -------------------------- -Where to put all the MS debug symbol files from linker. +Output directory for MS debug symbol ``.pdb`` files generated by the +linker for executable and shared library targets. -This variable is used to initialize the PDB_OUTPUT_DIRECTORY property -on all the targets. See that target property for additional +This variable is used to initialize the :prop_tgt:`PDB_OUTPUT_DIRECTORY` +property on all the targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG.rst b/Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG.rst new file mode 100644 index 0000000..4d18eec --- /dev/null +++ b/Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,11 @@ +CMAKE_PDB_OUTPUT_DIRECTORY_<CONFIG> +----------------------------------- + +Per-configuration output directory for MS debug symbol ``.pdb`` files +generated by the linker for executable and shared library targets. + +This is a per-configuration version of :variable:`CMAKE_PDB_OUTPUT_DIRECTORY`. +This variable is used to initialize the +:prop_tgt:`PDB_OUTPUT_DIRECTORY_<CONFIG>` +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_STAGING_PREFIX.rst b/Help/variable/CMAKE_STAGING_PREFIX.rst new file mode 100644 index 0000000..c4de7da --- /dev/null +++ b/Help/variable/CMAKE_STAGING_PREFIX.rst @@ -0,0 +1,13 @@ +CMAKE_STAGING_PREFIX +-------------------- + +This variable may be set to a path to install to when cross-compiling. This can +be useful if the path in :variable:`CMAKE_SYSROOT` is read-only, or otherwise +should remain pristine. + +The CMAKE_STAGING_PREFIX location is also used as a search prefix by the ``find_*`` +commands. This can be controlled by setting the :variable:`CMAKE_FIND_NO_INSTALL_PREFIX` +variable. + +If any RPATH/RUNPATH entries passed to the linker contain the CMAKE_STAGING_PREFIX, +the matching path fragments are replaced with the :variable:`CMAKE_INSTALL_PREFIX`. diff --git a/Help/variable/CMAKE_SYSROOT.rst b/Help/variable/CMAKE_SYSROOT.rst new file mode 100644 index 0000000..7aa0450 --- /dev/null +++ b/Help/variable/CMAKE_SYSROOT.rst @@ -0,0 +1,12 @@ +CMAKE_SYSROOT +------------- + +Path to pass to the compiler in the ``--sysroot`` flag. + +The ``CMAKE_SYSROOT`` content is passed to the compiler in the ``--sysroot`` +flag, if supported. The path is also stripped from the RPATH/RUNPATH if +necessary on installation. The ``CMAKE_SYSROOT`` is also used to prefix +paths searched by the ``find_*`` commands. + +This variable may only be set in a toolchain file specified by +the :variable:`CMAKE_TOOLCHAIN_FILE` variable. diff --git a/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst index 2dbae1f..537eaba 100644 --- a/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst +++ b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst @@ -9,8 +9,8 @@ appropriate subdirectories to the base directories. So FIND_PROGRAM() adds /bin to each of the directories in the path, FIND_LIBRARY() appends /lib to each of the directories, and FIND_PATH() and FIND_FILE() append /include . By default this contains the standard -directories for the current system and the CMAKE_INSTALL_PREFIX. It -is NOT intended to be modified by the project, use CMAKE_PREFIX_PATH -for this. See also CMAKE_SYSTEM_INCLUDE_PATH, +directories for the current system, the CMAKE_INSTALL_PREFIX and +the :variable:`CMAKE_STAGING_PREFIX`. It is NOT intended to be modified by +the project, use CMAKE_PREFIX_PATH for this. See also CMAKE_SYSTEM_INCLUDE_PATH, CMAKE_SYSTEM_LIBRARY_PATH, CMAKE_SYSTEM_PROGRAM_PATH, and CMAKE_SYSTEM_IGNORE_PATH. diff --git a/Help/variable/CMAKE_TOOLCHAIN_FILE.rst b/Help/variable/CMAKE_TOOLCHAIN_FILE.rst new file mode 100644 index 0000000..e1a65e1 --- /dev/null +++ b/Help/variable/CMAKE_TOOLCHAIN_FILE.rst @@ -0,0 +1,9 @@ +CMAKE_TOOLCHAIN_FILE +-------------------- + +Path to toolchain file supplied to :manual:`cmake(1)`. + +This variable is specified on the command line when cross-compiling with CMake. +It is the path to a file which is read early in the CMake run and which specifies +locations for compilers and toolchain utilities, and other target platform and +compiler related information. |