diff options
Diffstat (limited to 'Help')
72 files changed, 560 insertions, 87 deletions
diff --git a/Help/command/ctest_update.rst b/Help/command/ctest_update.rst index 74af1f7..b205bca 100644 --- a/Help/command/ctest_update.rst +++ b/Help/command/ctest_update.rst @@ -25,3 +25,7 @@ The options are: have otherwise printed to the console. CTest will still report the new revision of the repository and any conflicting files that were found. + +The update always follows the version control branch currently checked +out in the source directory. See the :ref:`CTest Update Step` +documentation for more information. diff --git a/Help/command/find_library.rst b/Help/command/find_library.rst index 31e6ec0..1eb50f7 100644 --- a/Help/command/find_library.rst +++ b/Help/command/find_library.rst @@ -49,6 +49,13 @@ path to the framework ``<fullPath>/A.framework``. When a full path to a framework is used as a library, CMake will use a ``-framework A``, and a ``-F<fullPath>`` to link the framework to the target. +If the :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` global property is set +all search paths will be tested as normal, with ``32/`` appended, and +with all matches of ``lib/`` replaced with ``lib32/``. This property is +automatically set for the platforms that are known to need it if at +least one of the languages supported by the :command:`project` command +is enabled. + If the :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` global property is set all search paths will be tested as normal, with ``64/`` appended, and with all matches of ``lib/`` replaced with ``lib64/``. This property is diff --git a/Help/command/set.rst b/Help/command/set.rst index d04b880..b24ebef 100644 --- a/Help/command/set.rst +++ b/Help/command/set.rst @@ -25,7 +25,9 @@ If the ``PARENT_SCOPE`` option is given the variable will be set in the scope above the current scope. Each new directory or function creates a new scope. This command will set the value of a variable into the parent directory or calling function (whichever is applicable -to the case at hand). +to the case at hand). The previous state of the variable's value stays the +same in the current scope (e.g., if it was undefined before, it is still +undefined and if it had a value, it is still that value). Set Cache Entry ^^^^^^^^^^^^^^^ diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 07bf33f..4950fee 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -860,7 +860,7 @@ with :prop_tgt:`IMPORTED` targets. Alias Targets ------------- -An ``ALIAS`` target is a name which may be used interchangably with +An ``ALIAS`` target is a name which may be used interchangeably with a binary target name in read-only contexts. A primary use-case for ``ALIAS`` targets is for example or unit test executables accompanying a library, which may be part of the same buildsystem or built separately based on user diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index 7bfdcad..afaccc6 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -24,9 +24,10 @@ to build with such toolchains. std::auto_ptr ------------- -Some implementations have a ``std::auto_ptr`` which can not be used as a -return value from a function. ``std::auto_ptr`` may not be used. Use -``cmsys::auto_ptr`` instead. +The ``std::auto_ptr`` template is deprecated in C++11. We want to use it +so we can build on C++98 compilers but we do not want to turn off compiler +warnings about deprecated interfaces in general. Use the ``CM_AUTO_PTR`` +macro instead. size_t ------ diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 62910cf..e905ef4 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -60,6 +60,7 @@ All Modules /module/CPackIFW /module/CPackNSIS /module/CPackPackageMaker + /module/CPackProductBuild /module/CPackRPM /module/CPack /module/CPackWIX @@ -120,6 +121,7 @@ All Modules /module/FindHTMLHelp /module/FindIce /module/FindIcotool + /module/FindICU /module/FindImageMagick /module/FindIntl /module/FindITK @@ -209,6 +211,7 @@ All Modules /module/FindTIFF /module/FindUnixCommands /module/FindVTK + /module/FindVulkan /module/FindWget /module/FindWish /module/FindwxWidgets diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 43f4637..0cfe983 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,14 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used to determine whether to report an error on use of deprecated macros or functions. +Policies Introduced by CMake 3.7 +================================ + +.. toctree:: + :maxdepth: 1 + + CMP0066: Honor per-config flags in try_compile() source-file signature. </policy/CMP0066> + Policies Introduced by CMake 3.4 ================================ diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 3403dcd..0f1bfad 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -24,6 +24,7 @@ Properties of Global Scope /prop_gbl/DISABLED_FEATURES /prop_gbl/ENABLED_FEATURES /prop_gbl/ENABLED_LANGUAGES + /prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS /prop_gbl/FIND_LIBRARY_USE_LIB64_PATHS /prop_gbl/FIND_LIBRARY_USE_OPENBSD_VERSIONING /prop_gbl/GLOBAL_DEPENDS_DEBUG_MODE @@ -217,6 +218,7 @@ Properties on Targets /prop_tgt/LINK_LIBRARIES /prop_tgt/LINK_SEARCH_END_STATIC /prop_tgt/LINK_SEARCH_START_STATIC + /prop_tgt/LINK_WHAT_YOU_USE /prop_tgt/LOCATION_CONFIG /prop_tgt/LOCATION /prop_tgt/MACOSX_BUNDLE_INFO_PLIST @@ -274,6 +276,7 @@ Properties on Targets /prop_tgt/VS_SCC_LOCALPATH /prop_tgt/VS_SCC_PROJECTNAME /prop_tgt/VS_SCC_PROVIDER + /prop_tgt/VS_SDK_REFERENCES /prop_tgt/VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION /prop_tgt/VS_WINRT_COMPONENT /prop_tgt/VS_WINRT_EXTENSIONS @@ -341,9 +344,11 @@ Properties on Source Files /prop_sf/VS_SHADER_FLAGS /prop_sf/VS_SHADER_MODEL /prop_sf/VS_SHADER_TYPE + /prop_sf/VS_TOOL_OVERRIDE.rst /prop_sf/VS_XAML_TYPE /prop_sf/WRAP_EXCLUDE /prop_sf/XCODE_EXPLICIT_FILE_TYPE + /prop_sf/XCODE_FILE_ATTRIBUTES /prop_sf/XCODE_LAST_KNOWN_FILE_TYPE .. _`Cache Entry Properties`: diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 85b8eae..1138b82 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -253,7 +253,9 @@ Variables that Control the Build /variable/CMAKE_DEBUG_POSTFIX /variable/CMAKE_ENABLE_EXPORTS /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG + /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT /variable/CMAKE_EXE_LINKER_FLAGS + /variable/CMAKE_EXE_LINKER_FLAGS_INIT /variable/CMAKE_Fortran_FORMAT /variable/CMAKE_Fortran_MODULE_DIRECTORY /variable/CMAKE_GNUtoMS @@ -275,11 +277,14 @@ Variables that Control the Build /variable/CMAKE_LINK_INTERFACE_LIBRARIES /variable/CMAKE_LINK_LIBRARY_FILE_FLAG /variable/CMAKE_LINK_LIBRARY_FLAG + /variable/CMAKE_LINK_WHAT_YOU_USE /variable/CMAKE_MACOSX_BUNDLE /variable/CMAKE_MACOSX_RPATH /variable/CMAKE_MAP_IMPORTED_CONFIG_CONFIG /variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG + /variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT /variable/CMAKE_MODULE_LINKER_FLAGS + /variable/CMAKE_MODULE_LINKER_FLAGS_INIT /variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX /variable/CMAKE_NO_BUILTIN_CHRPATH /variable/CMAKE_NO_SYSTEM_FROM_IMPORTED @@ -292,11 +297,15 @@ Variables that Control the Build /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG + /variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG_INIT /variable/CMAKE_SHARED_LINKER_FLAGS + /variable/CMAKE_SHARED_LINKER_FLAGS_INIT /variable/CMAKE_SKIP_BUILD_RPATH /variable/CMAKE_SKIP_INSTALL_RPATH /variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG + /variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT /variable/CMAKE_STATIC_LINKER_FLAGS + /variable/CMAKE_STATIC_LINKER_FLAGS_INIT /variable/CMAKE_TRY_COMPILE_CONFIGURATION /variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES /variable/CMAKE_TRY_COMPILE_TARGET_TYPE @@ -343,10 +352,15 @@ Variables for Languages /variable/CMAKE_LANG_CREATE_SHARED_MODULE /variable/CMAKE_LANG_CREATE_STATIC_LIBRARY /variable/CMAKE_LANG_FLAGS_DEBUG + /variable/CMAKE_LANG_FLAGS_DEBUG_INIT /variable/CMAKE_LANG_FLAGS_MINSIZEREL + /variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT /variable/CMAKE_LANG_FLAGS_RELEASE + /variable/CMAKE_LANG_FLAGS_RELEASE_INIT /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO + /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT /variable/CMAKE_LANG_FLAGS + /variable/CMAKE_LANG_FLAGS_INIT /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 65153af..8f7c336 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -108,6 +108,11 @@ Options Like ``--trace``, but with variables expanded. +``--trace-source=<file>`` + Put cmake in trace mode, but output only lines of a specified file. + + Multiple options are allowed. + ``--warn-uninitialized`` Warn about uninitialized values. diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 1179f56..ce81578 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -56,7 +56,7 @@ Options Enable failover. This option allows ctest to resume a test set execution that was - previously interrupted. If no interruption occurred, the -F option + previously interrupted. If no interruption occurred, the ``-F`` option will have no effect. ``-j <jobs>, --parallel <jobs>`` @@ -77,12 +77,12 @@ Options Make ctest quiet. This option will suppress all the output. The output log file will - still be generated if the --output-log is specified. Options such - as --verbose, --extra-verbose, and --debug are ignored if --quiet is - specified. + still be generated if the ``--output-log`` is specified. Options such + as ``--verbose``, ``--extra-verbose``, and ``--debug`` are ignored + if ``--quiet`` is specified. ``-O <file>, --output-log <file>`` - Output to log file + Output to log file. This option tells ctest to write all its output to a log file. @@ -90,7 +90,7 @@ Options Disable actual execution of tests. This option tells ctest to list the tests that would be run but not - actually run them. Useful in conjunction with the -R and -E + actually run them. Useful in conjunction with the ``-R`` and ``-E`` options. ``-L <regex>, --label-regex <regex>`` @@ -118,7 +118,7 @@ Options given regular expression. ``-D <dashboard>, --dashboard <dashboard>`` - Execute dashboard test + Execute dashboard test. This option tells ctest to act as a CDash client and perform a dashboard test. All tests are <Mode><Test>, where Mode can be @@ -126,26 +126,27 @@ Options Update, Configure, Build, Test, Coverage, and Submit. ``-D <var>:<type>=<value>`` - Define a variable for script mode + Define a variable for script mode. Pass in variable values on the command line. Use in conjunction - with -S to pass variable values to a dashboard script. Parsing -D + with ``-S`` to pass variable values to a dashboard script. Parsing ``-D`` arguments as variable values is only attempted if the value - following -D does not match any of the known dashboard types. + following ``-D`` does not match any of the known dashboard types. ``-M <model>, --test-model <model>`` - Sets the model for a dashboard + Sets the model for a dashboard. - This option tells ctest to act as a CDash client where the TestModel - can be Experimental, Nightly, and Continuous. Combining -M and -T - is similar to -D + This option tells ctest to act as a CDash client where the ``<model>`` + can be ``Experimental``, ``Nightly``, and ``Continuous``. + Combining ``-M`` and ``-T`` is similar to ``-D``. ``-T <action>, --test-action <action>`` - Sets the dashboard action to perform + Sets the dashboard action to perform. This option tells ctest to act as a CDash client and perform some - action such as start, build, test etc. Combining -M and -T is - similar to -D + action such as ``start``, ``build``, ``test`` etc. See + `Dashboard Client Steps`_ for the full list of actions. + Combining ``-M`` and ``-T`` is similar to ``-D``. ``--track <track>`` Specify the track to submit dashboard to @@ -156,24 +157,24 @@ Options arbitrary. ``-S <script>, --script <script>`` - Execute a dashboard for a configuration + Execute a dashboard for a configuration. This option tells ctest to load in a configuration script which sets a number of parameters such as the binary and source directories. Then ctest will do what is required to create and run a dashboard. - This option basically sets up a dashboard and then runs ctest -D + This option basically sets up a dashboard and then runs ``ctest -D`` with the appropriate options. ``-SP <script>, --script-new-process <script>`` - Execute a dashboard for a configuration + Execute a dashboard for a configuration. - This option does the same operations as -S but it will do them in a + This option does the same operations as ``-S`` but it will do them in a separate process. This is primarily useful in cases where the script may modify the environment and you do not want the modified - environment to impact other -S scripts. + environment to impact other ``-S`` scripts. ``-A <file>, --add-notes <file>`` - Add a notes file with submission + Add a notes file with submission. This option tells ctest to include a notes file when submitting dashboard. @@ -188,19 +189,19 @@ Options contains the same syntax as the command line. ``-U, --union`` - Take the Union of -I and -R + Take the Union of ``-I`` and ``-R``. - When both -R and -I are specified by default the intersection of - tests are run. By specifying -U the union of tests is run instead. + When both ``-R`` and ``-I`` are specified by default the intersection of + tests are run. By specifying ``-U`` the union of tests is run instead. ``--rerun-failed`` - Run only the tests that failed previously + Run only the tests that failed previously. This option tells ctest to perform only the tests that failed during its previous run. When this option is specified, ctest ignores all - other options intended to modify the list of tests to run (-L, -R, - -E, -LE, -I, etc). In the event that CTest runs and no tests fail, - subsequent calls to ctest with the --rerun-failed option will run + other options intended to modify the list of tests to run (``-L``, ``-R``, + ``-E``, ``-LE``, ``-I``, etc). In the event that CTest runs and no tests + fail, subsequent calls to ctest with the ``--rerun-failed`` option will run the set of tests that most recently failed (if any). ``--repeat-until-fail <n>`` @@ -209,7 +210,7 @@ Options This is useful in finding sporadic failures in test cases. ``--max-width <width>`` - Set the max width for a test name to output + Set the max width for a test name to output. Set the maximum width for each test name to show in the output. This allows the user to widen the output to avoid clipping the test @@ -232,26 +233,25 @@ Options label associated with the tests run. If there are no labels on the tests, nothing extra is printed. -``--build-and-test`` +``--build-and-test <path-to-source> <path-to-build>`` Configure, build and run a test. This option tells ctest to configure (i.e. run cmake on), build, and or execute a test. The configure and test steps are optional. The arguments to this command line are the source and binary - directories. By default this will run CMake on the Source/Bin - directories specified unless --build-nocmake is specified. - The --build-generator option *must* be provided to use - --build-and-test. If --test-command is specified then that will be + directories. + The ``--build-generator`` option *must* be provided to use + ``--build-and-test``. If ``--test-command`` is specified then that will be run after the build is complete. Other options that affect this - mode are --build-target --build-nocmake, --build-run-dir, - --build-two-config, --build-exe-dir, - --build-project,--build-noclean, --build-options + mode are ``--build-target``, ``--build-nocmake``, ``--build-run-dir``, + ``--build-two-config``, ``--build-exe-dir``, + ``--build-project``, ``--build-noclean`` and ``--build-options``. ``--build-target`` Specify a specific target to build. - This option goes with the --build-and-test option, if left out the - all target is built. + This option goes with the ``--build-and-test`` option, if left out the + ``all`` target is built. ``--build-nocmake`` Run the build without running cmake first. @@ -264,13 +264,13 @@ Options Directory where programs will be after it has been compiled. ``--build-two-config`` - Run CMake twice + Run CMake twice. ``--build-exe-dir`` Specify the directory for the executable. ``--build-generator`` - Specify the generator to use. + Specify the generator to use. See the :manual:`cmake-generators(7)` manual. ``--build-generator-platform`` Specify the generator-specific platform. @@ -288,25 +288,23 @@ Options Skip the make clean step. ``--build-config-sample`` - A sample executable to use to determine the configuration - A sample executable to use to determine the configuration that - should be used. e.g. Debug/Release/etc + should be used. e.g. Debug/Release/etc. ``--build-options`` Add extra options to the build step. This option must be the last option with the exception of - --test-command + ``--test-command`` ``--test-command`` - The test to run with the --build-and-test option. + The test to run with the ``--build-and-test`` option. ``--test-output-size-passed <size>`` - Limit the output for passed tests to <size> bytes. + Limit the output for passed tests to ``<size>`` bytes. ``--test-output-size-failed <size>`` - Limit the output for failed tests to <size> bytes. + Limit the output for failed tests to ``<size>`` bytes. ``--test-timeout`` The time limit in seconds, internal use only. @@ -335,14 +333,14 @@ Options This option will submit extra files to the dashboard. ``--force-new-ctest-process`` - Run child CTest instances as new processes + Run child CTest instances as new processes. By default CTest will run child CTest instances within the same process. If this behavior is not desired, this argument will enforce new processes for child CTest processes. ``--schedule-random`` - Use a random order for scheduling tests + Use a random order for scheduling tests. This option will run the tests in a random order. It is commonly used to detect implicit dependencies in a test suite. @@ -361,7 +359,7 @@ Options Set a time at which all tests should stop running. Set a real time of day at which all tests should timeout. Example: - 7:00:00 -0400. Any time format understood by the curl date parser + ``7:00:00 -0400``. Any time format understood by the curl date parser is accepted. Local time is assumed if no timezone is specified. ``--http1.0`` @@ -589,6 +587,11 @@ Configuration settings to specify the version control tool include: * `CTest Script`_ variable: :variable:`CTEST_GIT_COMMAND` * :module:`CTest` module variable: ``GITCOMMAND`` + The source tree is updated by ``git fetch`` followed by + ``git reset --hard`` to the ``FETCH_HEAD``. The result is the same + as ``git pull`` except that any local moficiations are overwritten. + Use ``GITUpdateCustom`` to specify a different approach. + ``GITInitSubmodules`` If set, CTest will update the repository's submodules before updating. diff --git a/Help/module/CPackProductBuild.rst b/Help/module/CPackProductBuild.rst new file mode 100644 index 0000000..6081fe4 --- /dev/null +++ b/Help/module/CPackProductBuild.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CPackProductBuild.cmake diff --git a/Help/module/FindICU.rst b/Help/module/FindICU.rst new file mode 100644 index 0000000..ee3f4a9 --- /dev/null +++ b/Help/module/FindICU.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindICU.cmake diff --git a/Help/module/FindVulkan.rst b/Help/module/FindVulkan.rst new file mode 100644 index 0000000..adf824e --- /dev/null +++ b/Help/module/FindVulkan.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindVulkan.cmake diff --git a/Help/policy/CMP0066.rst b/Help/policy/CMP0066.rst new file mode 100644 index 0000000..d1dcb0e --- /dev/null +++ b/Help/policy/CMP0066.rst @@ -0,0 +1,27 @@ +CMP0066 +------- + +Honor per-config flags in :command:`try_compile` source-file signature. + +The source file signature of the :command:`try_compile` command uses the value +of the :variable:`CMAKE_<LANG>_FLAGS` variable in the test project so that the +test compilation works as it would in the main project. However, CMake 3.6 and +below do not also honor config-specific compiler flags such as those in the +:variable:`CMAKE_<LANG>_FLAGS_DEBUG` variable. CMake 3.7 and above prefer to +honor config-specific compiler flags too. This policy provides compatibility +for projects that do not expect config-specific compiler flags to be used. + +The ``OLD`` behavior of this policy is to ignore config-specific flag +variables like :variable:`CMAKE_<LANG>_FLAGS_DEBUG` and only use CMake's +built-in defaults for the current compiler and platform. + +The ``NEW`` behavior of this policy is to honor config-specific flag +variabldes like :variable:`CMAKE_<LANG>_FLAGS_DEBUG`. + +This policy was introduced in CMake version 3.7. Unlike most policies, +CMake version |release| does *not* warn by default when this policy +is not set and simply uses OLD behavior. See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0066 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/prop_dir/VS_STARTUP_PROJECT.rst b/Help/prop_dir/VS_STARTUP_PROJECT.rst index edd4832..04441b6 100644 --- a/Help/prop_dir/VS_STARTUP_PROJECT.rst +++ b/Help/prop_dir/VS_STARTUP_PROJECT.rst @@ -3,10 +3,16 @@ VS_STARTUP_PROJECT Specify the default startup project in a Visual Studio solution. +The :ref:`Visual Studio Generators` create a ``.sln`` file for each directory +whose ``CMakeLists.txt`` file calls the :command:`project` command. Set this +property in the same directory as a :command:`project` command call (e.g. in +the top-level ``CMakeLists.txt`` file) to specify the default startup project +for the correpsonding solution file. + The property must be set to the name of an existing target. This will cause that project to be listed first in the generated solution file causing Visual Studio to make it the startup project if the solution has never been opened before. -If this property is not specified, then the "ALL_BUILD" project +If this property is not specified, then the ``ALL_BUILD`` project will be the default. diff --git a/Help/prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS.rst b/Help/prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS.rst new file mode 100644 index 0000000..ce18b65 --- /dev/null +++ b/Help/prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS.rst @@ -0,0 +1,10 @@ +FIND_LIBRARY_USE_LIB32_PATHS +---------------------------- + +Whether the :command:`find_library` command should automatically search +``lib32`` directories. + +``FIND_LIBRARY_USE_LIB32_PATHS`` is a boolean specifying whether the +:command:`find_library` command should automatically search the ``lib32`` +variant of directories called ``lib`` in the search path when building 32-bit +binaries. diff --git a/Help/prop_sf/VS_TOOL_OVERRIDE.rst b/Help/prop_sf/VS_TOOL_OVERRIDE.rst new file mode 100644 index 0000000..8bdc5ca --- /dev/null +++ b/Help/prop_sf/VS_TOOL_OVERRIDE.rst @@ -0,0 +1,5 @@ +VS_TOOL_OVERRIDE +---------------- + +Override the default Visual Studio tool that will be applied to the source file +with a new tool not based on the extension of the file. diff --git a/Help/prop_sf/XCODE_FILE_ATTRIBUTES.rst b/Help/prop_sf/XCODE_FILE_ATTRIBUTES.rst new file mode 100644 index 0000000..39e6966 --- /dev/null +++ b/Help/prop_sf/XCODE_FILE_ATTRIBUTES.rst @@ -0,0 +1,11 @@ +XCODE_FILE_ATTRIBUTES +--------------------- + +Add values to the Xcode ``ATTRIBUTES`` setting on its reference to a +source file. Among other things, this can be used to set the role on +a mig file:: + + set_source_files_properties(defs.mig + PROPERTIES + XCODE_FILE_ATTRIBUTES "Client;Server" + ) diff --git a/Help/prop_tgt/BUNDLE_EXTENSION.rst b/Help/prop_tgt/BUNDLE_EXTENSION.rst index ea265b3..6b3d580 100644 --- a/Help/prop_tgt/BUNDLE_EXTENSION.rst +++ b/Help/prop_tgt/BUNDLE_EXTENSION.rst @@ -1,7 +1,8 @@ BUNDLE_EXTENSION ---------------- -The file extension used to name a :prop_tgt:`BUNDLE` target on the OS X and iOS. +The file extension used to name a :prop_tgt:`BUNDLE`, a :prop_tgt:`FRAMEWORK`, +or a :prop_tgt:`MACOSX_BUNDLE` target on the OS X and iOS. -The default value is ``bundle`` - you can also use ``plugin`` or whatever -file extension is required by the host app for your bundle. +The default value is ``bundle``, ``framework``, or ``app`` for the respective +target types. diff --git a/Help/prop_tgt/CXX_EXTENSIONS.rst b/Help/prop_tgt/CXX_EXTENSIONS.rst index 0f547e2..280bb3a 100644 --- a/Help/prop_tgt/CXX_EXTENSIONS.rst +++ b/Help/prop_tgt/CXX_EXTENSIONS.rst @@ -6,7 +6,8 @@ Boolean specifying whether compiler specific extensions are requested. This property specifies whether compiler specific extensions should be used. For some compilers, this results in adding a flag such as ``-std=gnu++11`` instead of ``-std=c++11`` to the compile line. This -property is ``ON`` by default. +property is ``ON`` by default. The basic C++ standard level is +controlled by the :prop_tgt:`CXX_STANDARD` target property. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/prop_tgt/CXX_STANDARD.rst b/Help/prop_tgt/CXX_STANDARD.rst index edc9ba5..5b186c1 100644 --- a/Help/prop_tgt/CXX_STANDARD.rst +++ b/Help/prop_tgt/CXX_STANDARD.rst @@ -22,6 +22,8 @@ with a compiler which does not support ``-std=gnu++11`` or an equivalent flag will not result in an error or warning, but will instead add the ``-std=gnu++98`` flag if supported. This "decay" behavior may be controlled with the :prop_tgt:`CXX_STANDARD_REQUIRED` target property. +Additionally, the :prop_tgt:`CXX_EXTENSIONS` target property may be used to +control whether compiler-specific extensions are enabled on a per-target basis. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/prop_tgt/C_EXTENSIONS.rst b/Help/prop_tgt/C_EXTENSIONS.rst index fce67f4..05b14ce 100644 --- a/Help/prop_tgt/C_EXTENSIONS.rst +++ b/Help/prop_tgt/C_EXTENSIONS.rst @@ -6,7 +6,8 @@ Boolean specifying whether compiler specific extensions are requested. This property specifies whether compiler specific extensions should be used. For some compilers, this results in adding a flag such as ``-std=gnu11`` instead of ``-std=c11`` to the compile line. This -property is ``ON`` by default. +property is ``ON`` by default. The basic C standard level is +controlled by the :prop_tgt:`C_STANDARD` target property. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/prop_tgt/C_STANDARD.rst b/Help/prop_tgt/C_STANDARD.rst index 5e36821..815a686 100644 --- a/Help/prop_tgt/C_STANDARD.rst +++ b/Help/prop_tgt/C_STANDARD.rst @@ -22,6 +22,8 @@ with a compiler which does not support ``-std=gnu11`` or an equivalent flag will not result in an error or warning, but will instead add the ``-std=gnu99`` or ``-std=gnu90`` flag if supported. This "decay" behavior may be controlled with the :prop_tgt:`C_STANDARD_REQUIRED` target property. +Additionally, the :prop_tgt:`C_EXTENSIONS` target property may be used to +control whether compiler-specific extensions are enabled on a per-target basis. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/prop_tgt/FRAMEWORK.rst b/Help/prop_tgt/FRAMEWORK.rst index 6c212c3..8120c36 100644 --- a/Help/prop_tgt/FRAMEWORK.rst +++ b/Help/prop_tgt/FRAMEWORK.rst @@ -26,6 +26,10 @@ Example of creation ``dynamicFramework``: FRAMEWORK_VERSION C MACOSX_FRAMEWORK_IDENTIFIER com.cmake.dynamicFramework MACOSX_FRAMEWORK_INFO_PLIST Info.plist + # "current version" in semantic format in Mach-O binary file + VERSION 16.4.0 + # "compatibility version" in semantic format in Mach-O binary file + SOVERSION 1.0.0 PUBLIC_HEADER dynamicFramework.h XCODE_ATTRIBUTE_CODE_SIGN_IDENTITY "iPhone Developer" ) diff --git a/Help/prop_tgt/LINK_WHAT_YOU_USE.rst b/Help/prop_tgt/LINK_WHAT_YOU_USE.rst new file mode 100644 index 0000000..32d6edb --- /dev/null +++ b/Help/prop_tgt/LINK_WHAT_YOU_USE.rst @@ -0,0 +1,15 @@ +LINK_WHAT_YOU_USE +--------------------------- + +This is a boolean option that when set to ``TRUE`` will automatically run +``ldd -r -u`` on the target after it is linked. In addition, the linker flag +``-Wl,--no-as-needed`` will be passed to the target with the link command so +that all libraries specified on the command line will be linked into the +target. This will result in the link producing a list of libraries that +provide no symbols used by this target but are being linked to it. +This is only applicable to executable and shared library targets and +will only work when ld and ldd accept the flags used. + +This property is initialized by the value of +the :variable:`CMAKE_LINK_WHAT_YOU_USE` variable if it is set +when a target is created. diff --git a/Help/prop_tgt/SOVERSION.rst b/Help/prop_tgt/SOVERSION.rst index 672ff23..82b6b97 100644 --- a/Help/prop_tgt/SOVERSION.rst +++ b/Help/prop_tgt/SOVERSION.rst @@ -3,12 +3,25 @@ SOVERSION What version number is this target. -For shared libraries VERSION and SOVERSION can be used to specify the -build version and API version respectively. When building or +For shared libraries :prop_tgt:`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. -SOVERSION is ignored if NO_SONAME property is set. For shared -libraries and executables on Windows the VERSION attribute is parsed -to extract a "major.minor" version number. These numbers are used as -the image version of the binary. +``SOVERSION`` is ignored if :prop_tgt:`NO_SONAME` property is set. + +Windows Versions +^^^^^^^^^^^^^^^^ + +For shared libraries and executables on Windows the :prop_tgt:`VERSION` +attribute is parsed to extract a ``<major>.<minor>`` version number. +These numbers are used as the image version of the binary. + +Mach-O Versions +^^^^^^^^^^^^^^^ + +For shared libraries and executables on Mach-O systems (e.g. OS X, iOS), +the ``SOVERSION`` property corresponds to *compatibility version* and +:prop_tgt:`VERSION` to *current version*. See the :prop_tgt:`FRAMEWORK` target +property for an example. Versions of Mach-O binaries may be checked with the +``otool -L <binary>`` command. diff --git a/Help/prop_tgt/VERSION.rst b/Help/prop_tgt/VERSION.rst index 87f6c49..66e7bde 100644 --- a/Help/prop_tgt/VERSION.rst +++ b/Help/prop_tgt/VERSION.rst @@ -3,14 +3,27 @@ VERSION What version number is this target. -For shared libraries VERSION and SOVERSION can be used to specify the -build version and API version respectively. When building or +For shared libraries ``VERSION`` and :prop_tgt:`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 +executables ``VERSION`` can be used to specify the build version. When building or installing appropriate symlinks are created if the -platform supports symlinks. For shared libraries and executables on -Windows the VERSION attribute is parsed to extract a "major.minor" -version number. These numbers are used as the image version of the -binary. +platform supports symlinks. + +Windows Versions +^^^^^^^^^^^^^^^^ + +For shared libraries and executables on Windows the ``VERSION`` +attribute is parsed to extract a ``<major>.<minor>`` version number. +These numbers are used as the image version of the binary. + +Mach-O Versions +^^^^^^^^^^^^^^^ + +For shared libraries and executables on Mach-O systems (e.g. OS X, iOS), +the :prop_tgt:`SOVERSION` property correspond to *compatibility version* and +``VERSION`` to *current version*. See the :prop_tgt:`FRAMEWORK` target +property for an example. Versions of Mach-O binaries may be checked with the +``otool -L <binary>`` command. diff --git a/Help/prop_tgt/VS_SDK_REFERENCES.rst b/Help/prop_tgt/VS_SDK_REFERENCES.rst new file mode 100644 index 0000000..769a0d1 --- /dev/null +++ b/Help/prop_tgt/VS_SDK_REFERENCES.rst @@ -0,0 +1,7 @@ +VS_SDK_REFERENCES +----------------- + +Visual Studio project SDK references. +Specify a :ref:`;-list <CMake Language Lists>` of SDK references +to be added to a generated Visual Studio project, e.g. +``Microsoft.AdMediatorWindows81, Version=1.0``. diff --git a/Help/prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS.rst b/Help/prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS.rst index 3f48af8..06c3e6d 100644 --- a/Help/prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS.rst +++ b/Help/prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS.rst @@ -5,8 +5,9 @@ This property is implemented only for MS-compatible tools on Windows. Enable this boolean property to automatically create a module definition (``.def``) file with all global symbols found in the input ``.obj`` files -for a ``SHARED`` library on Windows. The module definition file will be -passed to the linker causing all symbols to be exported from the ``.dll``. +for a ``SHARED`` library (or executable with :prop_tgt:`ENABLE_EXPORTS`) +on Windows. The module definition file will be passed to the linker +causing all symbols to be exported from the ``.dll``. For global *data* symbols, ``__declspec(dllimport)`` must still be used when compiling against the code in the ``.dll``. All other function symbols will be automatically exported and imported by callers. This simplifies porting diff --git a/Help/release/3.6.rst b/Help/release/3.6.rst index 5c08b39..144537d 100644 --- a/Help/release/3.6.rst +++ b/Help/release/3.6.rst @@ -42,11 +42,6 @@ Commands commands gained support for the ``%s`` placeholder. This is the number of seconds since the UNIX Epoch. -* The :command:`try_compile` command source file signature now honors - configuration-specific flags (e.g. :variable:`CMAKE_<LANG>_FLAGS_DEBUG`) - in the generated test project. Previously only the default such flags - for the current toolchain were used. - Variables --------- @@ -313,3 +308,9 @@ Other Changes preferred future use is upper cased component names in variables. New variables that will be added to CPackRPM in later versions will only support upper cased component variable format. + +* The CPack NSIS generator's configuration file template was fixed to + quote the path to the uninstaller tool used by the + :variable:`CPACK_NSIS_ENABLE_UNINSTALL_BEFORE_INSTALL` option. + This avoids depending on an insecure Windows feature to run an + uninstaller tool with a space in the path. diff --git a/Help/release/dev/FindBISON-report-file.rst b/Help/release/dev/FindBISON-report-file.rst new file mode 100644 index 0000000..0b59128 --- /dev/null +++ b/Help/release/dev/FindBISON-report-file.rst @@ -0,0 +1,5 @@ +FindBISON-report-file +--------------------- + +* The :module:`FindBISON` module ``BISON_TARGET`` macro learned a new + ``REPORT_FILE`` option to specify the bison ``--report-file=`` option. diff --git a/Help/release/dev/FindOpenCL-imported-target.rst b/Help/release/dev/FindOpenCL-imported-target.rst new file mode 100644 index 0000000..259c745 --- /dev/null +++ b/Help/release/dev/FindOpenCL-imported-target.rst @@ -0,0 +1,4 @@ +FindOpenCL-imported-target +-------------------------- + +* The :module:`FindOpenCL` module now provides imported targets. diff --git a/Help/release/dev/FindOpenMP-updates.rst b/Help/release/dev/FindOpenMP-updates.rst new file mode 100644 index 0000000..cb29a71 --- /dev/null +++ b/Help/release/dev/FindOpenMP-updates.rst @@ -0,0 +1,5 @@ +FindOpenMP-updates +------------------ + +* The :module:`FindOpenMP` module learned to detect the OpenMP + version (specification date) from the compiler. diff --git a/Help/release/dev/FindVulkan.rst b/Help/release/dev/FindVulkan.rst new file mode 100644 index 0000000..bb5447e --- /dev/null +++ b/Help/release/dev/FindVulkan.rst @@ -0,0 +1,4 @@ +FindVulkan +---------- + +* A :module:`FindVulkan` module was added. diff --git a/Help/release/dev/GenerateExportHeader-custom-content.rst b/Help/release/dev/GenerateExportHeader-custom-content.rst new file mode 100644 index 0000000..161261c --- /dev/null +++ b/Help/release/dev/GenerateExportHeader-custom-content.rst @@ -0,0 +1,6 @@ +GenerateExportHeader-custom-content +----------------------------------- + +* The :module:`GenerateExportHeader` module learned a new + ``CUSTOM_CONTENT_FROM_VARIABLE`` option to specify a variable + containing custom content for inclusion in the generated header. diff --git a/Help/release/dev/aix-clang.rst b/Help/release/dev/aix-clang.rst new file mode 100644 index 0000000..2ff53bf --- /dev/null +++ b/Help/release/dev/aix-clang.rst @@ -0,0 +1,4 @@ +aix-clang +--------- + +* The Clang compiler is now supported on AIX. diff --git a/Help/release/dev/app-framework-bundle-extension.rst b/Help/release/dev/app-framework-bundle-extension.rst new file mode 100644 index 0000000..01855a2 --- /dev/null +++ b/Help/release/dev/app-framework-bundle-extension.rst @@ -0,0 +1,5 @@ +app-framework-bundle-extension +------------------------------ + +* On Apple platforms the :prop_tgt:`BUNDLE_EXTENSION` now also applies to + Frameworks and App Bundles. diff --git a/Help/release/dev/ccmake-vim-navigation.rst b/Help/release/dev/ccmake-vim-navigation.rst new file mode 100644 index 0000000..8fc1416 --- /dev/null +++ b/Help/release/dev/ccmake-vim-navigation.rst @@ -0,0 +1,4 @@ +ccmake-vim-navigation +--------------------- + +* :manual:`ccmake(1)` learned to support vim-like navigation bindings. diff --git a/Help/release/dev/cmake-trace-source.rst b/Help/release/dev/cmake-trace-source.rst new file mode 100644 index 0000000..9b17f6c --- /dev/null +++ b/Help/release/dev/cmake-trace-source.rst @@ -0,0 +1,4 @@ +cmake-trace-source +------------------ + +* The :manual:`cmake(1)` command learned a ``--trace-source=<file>`` option. diff --git a/Help/release/dev/find-lib32.rst b/Help/release/dev/find-lib32.rst new file mode 100644 index 0000000..00818dc --- /dev/null +++ b/Help/release/dev/find-lib32.rst @@ -0,0 +1,7 @@ +find-lib32 +---------- + +* The :command:`find_library` and :command:`find_package` commands learned + to search in ``lib32/`` directories when the build targets a 32-bit + architecture. See the :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` global + property. diff --git a/Help/release/dev/findicu.rst b/Help/release/dev/findicu.rst new file mode 100644 index 0000000..0950327 --- /dev/null +++ b/Help/release/dev/findicu.rst @@ -0,0 +1,5 @@ +findicu +------- + +* A :module:`FindICU` module was introduced to find the International + Components for Unicode (ICU) libraries and programs. diff --git a/Help/release/dev/java-export-targets.rst b/Help/release/dev/java-export-targets.rst new file mode 100644 index 0000000..5b70e97 --- /dev/null +++ b/Help/release/dev/java-export-targets.rst @@ -0,0 +1,6 @@ +java-export-targets +------------------- + +* The :module:`UseJava` module gained APIs to "export" jar targets + for use by external CMake projects. See the ``install_jar_exports`` + and ``export_jars`` functions. diff --git a/Help/release/dev/link_what_you_use.rst b/Help/release/dev/link_what_you_use.rst new file mode 100644 index 0000000..8d1e598 --- /dev/null +++ b/Help/release/dev/link_what_you_use.rst @@ -0,0 +1,7 @@ +link_what_you_use +----------------- + +* A :prop_tgt:`LINK_WHAT_YOU_USE` target property and supporting + :variable:`CMAKE_LINK_WHAT_YOU_USE` variable were introduced + to detect (on UNIX) shared libraries that are linked but not + needed by running ``ldd -r -u``. diff --git a/Help/release/dev/productbuild.rst b/Help/release/dev/productbuild.rst new file mode 100644 index 0000000..ebe213b --- /dev/null +++ b/Help/release/dev/productbuild.rst @@ -0,0 +1,5 @@ +productbuild +------------ + +* CPack gained a ``productbuild`` generator on OS X, configured by + the :module:`CPackProductBuild` module. diff --git a/Help/release/dev/toolchain-flag-init.rst b/Help/release/dev/toolchain-flag-init.rst new file mode 100644 index 0000000..37e363d --- /dev/null +++ b/Help/release/dev/toolchain-flag-init.rst @@ -0,0 +1,16 @@ +toolchain-flag-init +------------------- + +* :variable:`Toolchain files <CMAKE_TOOLCHAIN_FILE>` may now set a + :variable:`CMAKE_<LANG>_FLAGS_INIT` variable to initialize the + :variable:`CMAKE_<LANG>_FLAGS` cache entry the first time a language is + enabled in a build tree. + +* :variable:`Toolchain files <CMAKE_TOOLCHAIN_FILE>` may now set + :variable:`CMAKE_EXE_LINKER_FLAGS_INIT`, + :variable:`CMAKE_SHARED_LINKER_FLAGS_INIT`, and + :variable:`CMAKE_MODULE_LINKER_FLAGS_INIT` variables to initialize the + :variable:`CMAKE_EXE_LINKER_FLAGS`, + :variable:`CMAKE_SHARED_LINKER_FLAGS`, and + :variable:`CMAKE_MODULE_LINKER_FLAGS` cache entries the first time + a language is enabled in a build tree. diff --git a/Help/release/dev/try_compile-config-flags.rst b/Help/release/dev/try_compile-config-flags.rst new file mode 100644 index 0000000..ebfd6a4 --- /dev/null +++ b/Help/release/dev/try_compile-config-flags.rst @@ -0,0 +1,7 @@ +try_compile-config-flags +------------------------ + +* The :command:`try_compile` command source file signature now honors + configuration-specific flags (e.g. :variable:`CMAKE_<LANG>_FLAGS_DEBUG`) + in the generated test project. Previously only the default such flags + for the current toolchain were used. See policy :policy:`CMP0066`. diff --git a/Help/release/dev/vs-natvis.rst b/Help/release/dev/vs-natvis.rst new file mode 100644 index 0000000..7cc9844 --- /dev/null +++ b/Help/release/dev/vs-natvis.rst @@ -0,0 +1,5 @@ +vs-natvis +--------- + +* :ref:`Visual Studio Generators` for VS 2010 and above learned to + place ``.natvis`` source files into VS project files properly. diff --git a/Help/release/dev/vs-sdk-refs.rst b/Help/release/dev/vs-sdk-refs.rst new file mode 100644 index 0000000..55232e3 --- /dev/null +++ b/Help/release/dev/vs-sdk-refs.rst @@ -0,0 +1,5 @@ +vs-sdk-refs +----------- + +* A :prop_tgt:`VS_SDK_REFERENCES` target property was added to tell + :ref:`Visual Studio Generators` to reference the named SDKs. diff --git a/Help/release/dev/vs-tool-override.rst b/Help/release/dev/vs-tool-override.rst new file mode 100644 index 0000000..e1177c8 --- /dev/null +++ b/Help/release/dev/vs-tool-override.rst @@ -0,0 +1,5 @@ +vs-tool-override +---------------- + +* A :prop_sf:`VS_TOOL_OVERRIDE` source file property was created to tell + :ref:`Visual Studio Generators` what tool to use for a source file. diff --git a/Help/release/dev/windows-export-all-from-exe.rst b/Help/release/dev/windows-export-all-from-exe.rst new file mode 100644 index 0000000..48c16ec --- /dev/null +++ b/Help/release/dev/windows-export-all-from-exe.rst @@ -0,0 +1,5 @@ +windows-export-all-from-exe +--------------------------- + +* The :prop_tgt:`WINDOWS_EXPORT_ALL_SYMBOLS` target property now applies + to executable targets with the :prop_tgt:`ENABLE_EXPORTS` property set. diff --git a/Help/release/dev/wix-disabled-components.rst b/Help/release/dev/wix-disabled-components.rst new file mode 100644 index 0000000..a7e4d5f --- /dev/null +++ b/Help/release/dev/wix-disabled-components.rst @@ -0,0 +1,6 @@ +wix-disabled-components +----------------------- + +* The CPack WIX generator now supports + :variable:`CPACK_COMPONENT_<compName>_DISABLED`. + This can be used to deselect a component from being installed by default. diff --git a/Help/release/dev/wix-root-description.rst b/Help/release/dev/wix-root-description.rst new file mode 100644 index 0000000..24afed2 --- /dev/null +++ b/Help/release/dev/wix-root-description.rst @@ -0,0 +1,7 @@ +wix-root-description +-------------------- + +* The CPack WIX generator now supports + :variable:`CPACK_WIX_ROOT_FEATURE_TITLE` and + :variable:`CPACK_WIX_ROOT_FEATURE_DESCRIPTION` to allow the specification + of a custom title and description for the root feature element. diff --git a/Help/release/dev/xcode-file-attributes.rst b/Help/release/dev/xcode-file-attributes.rst new file mode 100644 index 0000000..35824fa --- /dev/null +++ b/Help/release/dev/xcode-file-attributes.rst @@ -0,0 +1,6 @@ +xcode-file-attributes +--------------------- + +* A :prop_sf:`XCODE_FILE_ATTRIBUTES` source file property was + added to tell the :generator:`Xcode` generator to generate + custom content in the Xcode project attributes for the file. diff --git a/Help/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT.rst b/Help/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT.rst new file mode 100644 index 0000000..592a369 --- /dev/null +++ b/Help/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT.rst @@ -0,0 +1,10 @@ +CMAKE_EXE_LINKER_FLAGS_<CONFIG>_INIT +------------------------------------ + +Value used to initialize the :variable:`CMAKE_EXE_LINKER_FLAGS_<CONFIG>` +cache entry the first time a build tree is configured. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also :variable:`CMAKE_EXE_LINKER_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_EXE_LINKER_FLAGS_INIT.rst b/Help/variable/CMAKE_EXE_LINKER_FLAGS_INIT.rst new file mode 100644 index 0000000..0b8afe4 --- /dev/null +++ b/Help/variable/CMAKE_EXE_LINKER_FLAGS_INIT.rst @@ -0,0 +1,11 @@ +CMAKE_EXE_LINKER_FLAGS_INIT +--------------------------- + +Value used to initialize the :variable:`CMAKE_EXE_LINKER_FLAGS` +cache entry the first time a build tree is configured. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also the configuration-specific variable +:variable:`CMAKE_EXE_LINKER_FLAGS_<CONFIG>_INIT`. diff --git a/Help/variable/CMAKE_INSTALL_PREFIX.rst b/Help/variable/CMAKE_INSTALL_PREFIX.rst index 3f3347f..86f1944 100644 --- a/Help/variable/CMAKE_INSTALL_PREFIX.rst +++ b/Help/variable/CMAKE_INSTALL_PREFIX.rst @@ -5,7 +5,7 @@ Install directory used by :command:`install`. If ``make install`` is invoked or ``INSTALL`` is built, this directory is prepended onto all install directories. This variable defaults to -``/usr/local`` on UNIX and ``c:/Program Files`` on Windows. +``/usr/local`` on UNIX and ``c:/Program Files/${PROJECT_NAME}`` on Windows. On UNIX one can use the ``DESTDIR`` mechanism in order to relocate the whole installation. ``DESTDIR`` means DESTination DIRectory. It is diff --git a/Help/variable/CMAKE_LANG_FLAGS_DEBUG_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_DEBUG_INIT.rst new file mode 100644 index 0000000..dcddb2e --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_DEBUG_INIT.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_FLAGS_DEBUG_INIT +----------------------------- + +Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_DEBUG` cache +entry the first time a build tree is configured for language ``<LANG>``. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also :variable:`CMAKE_<LANG>_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_LANG_FLAGS_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_INIT.rst new file mode 100644 index 0000000..1d32cc3 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_INIT.rst @@ -0,0 +1,15 @@ +CMAKE_<LANG>_FLAGS_INIT +----------------------- + +Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS` cache entry +the first time a build tree is configured for language ``<LANG>``. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also the configuration-specific variables: + +* :variable:`CMAKE_<LANG>_FLAGS_DEBUG_INIT` +* :variable:`CMAKE_<LANG>_FLAGS_RELEASE_INIT` +* :variable:`CMAKE_<LANG>_FLAGS_MINSIZEREL_INIT` +* :variable:`CMAKE_<LANG>_FLAGS_RELWITHDEBINFO_INIT` diff --git a/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT.rst new file mode 100644 index 0000000..c0aedf4 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_FLAGS_MINSIZEREL_INIT +---------------------------------- + +Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_MINSIZEREL` +cache entry the first time a build tree is configured for language ``<LANG>``. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also :variable:`CMAKE_<LANG>_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_LANG_FLAGS_RELEASE_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_RELEASE_INIT.rst new file mode 100644 index 0000000..59f92ff --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_RELEASE_INIT.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_FLAGS_RELEASE_INIT +------------------------------- + +Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_RELEASE` +cache entry the first time a build tree is configured for language ``<LANG>``. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also :variable:`CMAKE_<LANG>_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT.rst new file mode 100644 index 0000000..915f023 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_FLAGS_RELWITHDEBINFO_INIT +-------------------------------------- + +Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_RELWITHDEBINFO` +cache entry the first time a build tree is configured for language ``<LANG>``. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also :variable:`CMAKE_<LANG>_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst b/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst new file mode 100644 index 0000000..90c4d3f --- /dev/null +++ b/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst @@ -0,0 +1,6 @@ +CMAKE_LINK_WHAT_YOU_USE +--------------------------------- + +Default value for :prop_tgt:`LINK_WHAT_YOU_USE` target property. +This variable is used to initialize the property on each target as it is +created. diff --git a/Help/variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT.rst b/Help/variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT.rst new file mode 100644 index 0000000..3279014 --- /dev/null +++ b/Help/variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT.rst @@ -0,0 +1,10 @@ +CMAKE_MODULE_LINKER_FLAGS_<CONFIG>_INIT +--------------------------------------- + +Value used to initialize the :variable:`CMAKE_MODULE_LINKER_FLAGS_<CONFIG>` +cache entry the first time a build tree is configured. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also :variable:`CMAKE_MODULE_LINKER_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_MODULE_LINKER_FLAGS_INIT.rst b/Help/variable/CMAKE_MODULE_LINKER_FLAGS_INIT.rst new file mode 100644 index 0000000..91b39f6 --- /dev/null +++ b/Help/variable/CMAKE_MODULE_LINKER_FLAGS_INIT.rst @@ -0,0 +1,11 @@ +CMAKE_MODULE_LINKER_FLAGS_INIT +------------------------------ + +Value used to initialize the :variable:`CMAKE_MODULE_LINKER_FLAGS` +cache entry the first time a build tree is configured. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also the configuration-specific variable +:variable:`CMAKE_MODULE_LINKER_FLAGS_<CONFIG>_INIT`. diff --git a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst index 582f9e4..36cf75f 100644 --- a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst +++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst @@ -15,6 +15,8 @@ warn by default: policy :policy:`CMP0060`. * ``CMAKE_POLICY_WARNING_CMP0065`` controls the warning for policy :policy:`CMP0065`. +* ``CMAKE_POLICY_WARNING_CMP0066`` controls the warning for + policy :policy:`CMP0066`. This variable should not be set by a project in CMake code. Project developers running CMake may set this variable in their cache to diff --git a/Help/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG_INIT.rst b/Help/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG_INIT.rst new file mode 100644 index 0000000..185df38 --- /dev/null +++ b/Help/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG_INIT.rst @@ -0,0 +1,10 @@ +CMAKE_SHARED_LINKER_FLAGS_<CONFIG>_INIT +--------------------------------------- + +Value used to initialize the :variable:`CMAKE_SHARED_LINKER_FLAGS_<CONFIG>` +cache entry the first time a build tree is configured. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also :variable:`CMAKE_SHARED_LINKER_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_SHARED_LINKER_FLAGS_INIT.rst b/Help/variable/CMAKE_SHARED_LINKER_FLAGS_INIT.rst new file mode 100644 index 0000000..cb819a7 --- /dev/null +++ b/Help/variable/CMAKE_SHARED_LINKER_FLAGS_INIT.rst @@ -0,0 +1,11 @@ +CMAKE_SHARED_LINKER_FLAGS_INIT +------------------------------ + +Value used to initialize the :variable:`CMAKE_SHARED_LINKER_FLAGS` +cache entry the first time a build tree is configured. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also the configuration-specific variable +:variable:`CMAKE_SHARED_LINKER_FLAGS_<CONFIG>_INIT`. diff --git a/Help/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT.rst b/Help/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT.rst new file mode 100644 index 0000000..a49d1cb --- /dev/null +++ b/Help/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT.rst @@ -0,0 +1,10 @@ +CMAKE_STATIC_LINKER_FLAGS_<CONFIG>_INIT +--------------------------------------- + +Value used to initialize the :variable:`CMAKE_STATIC_LINKER_FLAGS_<CONFIG>` +cache entry the first time a build tree is configured. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also :variable:`CMAKE_STATIC_LINKER_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_STATIC_LINKER_FLAGS_INIT.rst b/Help/variable/CMAKE_STATIC_LINKER_FLAGS_INIT.rst new file mode 100644 index 0000000..113ca71 --- /dev/null +++ b/Help/variable/CMAKE_STATIC_LINKER_FLAGS_INIT.rst @@ -0,0 +1,11 @@ +CMAKE_STATIC_LINKER_FLAGS_INIT +------------------------------ + +Value used to initialize the :variable:`CMAKE_STATIC_LINKER_FLAGS` +cache entry the first time a build tree is configured. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also the configuration-specific variable +:variable:`CMAKE_STATIC_LINKER_FLAGS_<CONFIG>_INIT`. diff --git a/Help/variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES.rst b/Help/variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES.rst index 8e43465..0f96787 100644 --- a/Help/variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES.rst +++ b/Help/variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES.rst @@ -8,3 +8,19 @@ the host project. This variable should not be set by project code. It is meant to be set by CMake's platform information modules for the current toolchain, or by a toolchain file when used with :variable:`CMAKE_TOOLCHAIN_FILE`. + +Variables meaningful to CMake, such as :variable:`CMAKE_<LANG>_FLAGS`, are +propagated automatically. The ``CMAKE_TRY_COMPILE_PLATFORM_VARIABLES`` +variable may be set to pass custom variables meaningful to a toolchain file. +For example, a toolchain file may contain: + +.. code-block:: cmake + + set(CMAKE_SYSTEM_NAME ...) + set(CMAKE_TRY_COMPILE_PLATFORM_VARIABLES MY_CUSTOM_VARIABLE) + # ... use MY_CUSTOM_VARIABLE ... + +If a user passes ``-DMY_CUSTOM_VARIABLE=SomeValue`` to CMake then this +setting will be made visible to the toolchain file both for the main +project and for test projects generated by the :command:`try_compile` +command source file signature. diff --git a/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE.rst b/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE.rst index 9af0d97..622278e 100644 --- a/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE.rst +++ b/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE.rst @@ -14,8 +14,10 @@ variables that must be set before CMake builds its first test project to check that the compiler for a language works. It should not be used to load a file in cases that a normal :command:`include` will work. Use it only as a last resort for behavior that cannot be achieved any -other way. For example, one may set ``CMAKE_C_FLAGS_INIT`` to change the -default value used to initialize :variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>` +other way. For example, one may set the +:variable:`CMAKE_C_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>` variable +to change the default value used to initialize the +:variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>` variable before it is cached. The override file should NOT be used to set anything that could be set after languages are enabled, such as variables like :variable:`CMAKE_RUNTIME_OUTPUT_DIRECTORY` that affect the placement of |