diff options
Diffstat (limited to 'Help')
23 files changed, 245 insertions, 73 deletions
diff --git a/Help/command/execute_process.rst b/Help/command/execute_process.rst index 71233d9..d617243 100644 --- a/Help/command/execute_process.rst +++ b/Help/command/execute_process.rst @@ -70,10 +70,21 @@ Options: ``ENCODING <name>`` On Windows, the encoding that is used to decode output from the process. Ignored on other platforms. - Valid encoding names are: ``AUTO`` (the default), ``NONE``, ``UTF8``, - ``ANSI`` and ``OEM``. - ``AUTO`` encoding means current active console's codepage will be used - or if that isn't available then ``ANSI`` codepage will be used. + Valid encoding names are: + + ``NONE`` + Perform no decoding. This assumes that the process output is encoded + in the same way as CMake's internal encoding (UTF-8). + This is the default. + ``AUTO`` + Use the current active console's codepage or if that isn't + available then use ANSI. + ``ANSI`` + Use the ANSI codepage. + ``OEM`` + Use the original equipment manufacturer (OEM) code page. + ``UTF8`` + Use the UTF-8 codepage. If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the same pipe the precedence is not specified. diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst index d0c2986..611c989 100644 --- a/Help/manual/cmake-commands.7.rst +++ b/Help/manual/cmake-commands.7.rst @@ -7,91 +7,103 @@ cmake-commands(7) .. contents:: -Normal Commands -=============== +Scripting Commands +================== -These commands may be used freely in CMake projects. +These commands are always available. .. toctree:: :maxdepth: 1 - /command/add_compile_options - /command/add_custom_command - /command/add_custom_target - /command/add_definitions - /command/add_dependencies - /command/add_executable - /command/add_library - /command/add_subdirectory - /command/add_test - /command/aux_source_directory /command/break - /command/build_command /command/cmake_host_system_information /command/cmake_minimum_required /command/cmake_parse_arguments /command/cmake_policy /command/configure_file /command/continue - /command/create_test_sourcelist - /command/define_property /command/elseif /command/else - /command/enable_language - /command/enable_testing /command/endforeach /command/endfunction /command/endif /command/endmacro /command/endwhile /command/execute_process - /command/export /command/file /command/find_file /command/find_library /command/find_package /command/find_path /command/find_program - /command/fltk_wrap_ui /command/foreach /command/function /command/get_cmake_property /command/get_directory_property /command/get_filename_component /command/get_property + /command/if + /command/include + /command/list + /command/macro + /command/mark_as_advanced + /command/math + /command/message + /command/option + /command/return + /command/separate_arguments + /command/set_directory_properties + /command/set_property + /command/set + /command/site_name + /command/string + /command/unset + /command/variable_watch + /command/while + +Project Commands +================ + +These commands are available only in CMake projects. + +.. toctree:: + :maxdepth: 1 + + /command/add_compile_options + /command/add_custom_command + /command/add_custom_target + /command/add_definitions + /command/add_dependencies + /command/add_executable + /command/add_library + /command/add_subdirectory + /command/add_test + /command/aux_source_directory + /command/build_command + /command/create_test_sourcelist + /command/define_property + /command/enable_language + /command/enable_testing + /command/export + /command/fltk_wrap_ui /command/get_source_file_property /command/get_target_property /command/get_test_property - /command/if /command/include_directories /command/include_external_msproject /command/include_regular_expression - /command/include /command/install /command/link_directories /command/link_libraries - /command/list /command/load_cache - /command/macro - /command/mark_as_advanced - /command/math - /command/message - /command/option /command/project /command/qt_wrap_cpp /command/qt_wrap_ui /command/remove_definitions - /command/return - /command/separate_arguments - /command/set_directory_properties - /command/set_property - /command/set /command/set_source_files_properties /command/set_target_properties /command/set_tests_properties - /command/site_name /command/source_group - /command/string /command/target_compile_definitions /command/target_compile_features /command/target_compile_options @@ -100,9 +112,30 @@ These commands may be used freely in CMake projects. /command/target_sources /command/try_compile /command/try_run - /command/unset - /command/variable_watch - /command/while + +.. _`CTest Commands`: + +CTest Commands +============== + +These commands are available only in CTest scripts. + +.. toctree:: + :maxdepth: 1 + + /command/ctest_build + /command/ctest_configure + /command/ctest_coverage + /command/ctest_empty_binary_directory + /command/ctest_memcheck + /command/ctest_read_custom_files + /command/ctest_run_script + /command/ctest_sleep + /command/ctest_start + /command/ctest_submit + /command/ctest_test + /command/ctest_update + /command/ctest_upload Deprecated Commands =================== @@ -129,27 +162,3 @@ versions of CMake. Do not use them in new code. /command/utility_source /command/variable_requires /command/write_file - -.. _`CTest Commands`: - -CTest Commands -============== - -These commands are available only in ctest scripts. - -.. toctree:: - :maxdepth: 1 - - /command/ctest_build - /command/ctest_configure - /command/ctest_coverage - /command/ctest_empty_binary_directory - /command/ctest_memcheck - /command/ctest_read_custom_files - /command/ctest_run_script - /command/ctest_sleep - /command/ctest_start - /command/ctest_submit - /command/ctest_test - /command/ctest_update - /command/ctest_upload diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index d4712ba..2dd56c7 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -228,6 +228,7 @@ All Modules /module/GenerateExportHeader /module/GetPrerequisites /module/GNUInstallDirs + /module/GoogleTest /module/InstallRequiredSystemLibraries /module/MacroAddFileDependencies /module/ProcessorCount diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 3266958..0c9ee2d 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.9 +================================ + +.. toctree:: + :maxdepth: 1 + + CMP0068: RPATH settings on macOS do not affect install_name. </policy/CMP0068> + Policies Introduced by CMake 3.8 ================================ diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 38aba81..5fad10c 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -123,6 +123,7 @@ Properties on Targets /prop_tgt/AUTORCC_OPTIONS /prop_tgt/BINARY_DIR /prop_tgt/BUILD_RPATH + /prop_tgt/BUILD_WITH_INSTALL_NAME_DIR /prop_tgt/BUILD_WITH_INSTALL_RPATH /prop_tgt/BUNDLE_EXTENSION /prop_tgt/BUNDLE diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 95f780a..6112e65 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -263,6 +263,7 @@ Variables that Control the Build /variable/CMAKE_AUTOUIC /variable/CMAKE_AUTOUIC_OPTIONS /variable/CMAKE_BUILD_RPATH + /variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR /variable/CMAKE_BUILD_WITH_INSTALL_RPATH /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG @@ -353,6 +354,7 @@ Variables for Languages /variable/CMAKE_CUDA_EXTENSIONS /variable/CMAKE_CUDA_STANDARD /variable/CMAKE_CUDA_STANDARD_REQUIRED + /variable/CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES /variable/CMAKE_CXX_COMPILE_FEATURES /variable/CMAKE_CXX_EXTENSIONS /variable/CMAKE_CXX_STANDARD diff --git a/Help/module/GoogleTest.rst b/Help/module/GoogleTest.rst new file mode 100644 index 0000000..3d4cc97 --- /dev/null +++ b/Help/module/GoogleTest.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/GoogleTest.cmake diff --git a/Help/policy/CMP0068.rst b/Help/policy/CMP0068.rst new file mode 100644 index 0000000..978a6e3 --- /dev/null +++ b/Help/policy/CMP0068.rst @@ -0,0 +1,35 @@ +CMP0068 +------- + +``RPATH`` settings on macOS do not affect ``install_name``. + +CMake 3.9 and newer remove any effect the following settings may have on the +``install_name`` of a target on macOS: + +* :prop_tgt:`BUILD_WITH_INSTALL_RPATH` target property +* :prop_tgt:`SKIP_BUILD_RPATH` target property +* :variable:`CMAKE_SKIP_RPATH` variable +* :variable:`CMAKE_SKIP_INSTALL_RPATH` variable + +Previously, setting :prop_tgt:`BUILD_WITH_INSTALL_RPATH` had the effect of +setting both the ``install_name`` of a target to :prop_tgt:`INSTALL_NAME_DIR` +and the ``RPATH`` to :prop_tgt:`INSTALL_RPATH`. In CMake 3.9, it only affects +setting of ``RPATH``. However, if one wants :prop_tgt:`INSTALL_NAME_DIR` to +apply to the target in the build tree, one may set +:prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR`. + +If :prop_tgt:`SKIP_BUILD_RPATH`, :variable:`CMAKE_SKIP_RPATH` or +:variable:`CMAKE_SKIP_INSTALL_RPATH` were used to strip the directory portion +of the ``install_name`` of a target, one may set ``INSTALL_NAME_DIR=""`` +instead. + +The ``OLD`` behavior of this policy is to use the ``RPATH`` settings for +``install_name`` on macOS. The ``NEW`` behavior of this policy is to ignore +the ``RPATH`` settings for ``install_name`` on macOS. + +This policy was introduced in CMake version 3.9. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/prop_tgt/BUILD_WITH_INSTALL_NAME_DIR.rst b/Help/prop_tgt/BUILD_WITH_INSTALL_NAME_DIR.rst new file mode 100644 index 0000000..bbb9a24 --- /dev/null +++ b/Help/prop_tgt/BUILD_WITH_INSTALL_NAME_DIR.rst @@ -0,0 +1,13 @@ +BUILD_WITH_INSTALL_NAME_DIR +--------------------------- + +``BUILD_WITH_INSTALL_NAME_DIR`` is a boolean specifying whether the macOS +``install_name`` of a target in the build tree uses the directory given by +:prop_tgt:`INSTALL_NAME_DIR`. This setting only applies to targets on macOS. + +This property is initialized by the value of the variable +:variable:`CMAKE_BUILD_WITH_INSTALL_NAME_DIR` if it is set when a target is +created. + +If this property is not set and policy :policy:`CMP0068` is not ``NEW``, the +value of :prop_tgt:`BUILD_WITH_INSTALL_RPATH` is used in its place. diff --git a/Help/prop_tgt/BUILD_WITH_INSTALL_RPATH.rst b/Help/prop_tgt/BUILD_WITH_INSTALL_RPATH.rst index abcf28f..0244351 100644 --- a/Help/prop_tgt/BUILD_WITH_INSTALL_RPATH.rst +++ b/Help/prop_tgt/BUILD_WITH_INSTALL_RPATH.rst @@ -1,11 +1,15 @@ BUILD_WITH_INSTALL_RPATH ------------------------ -Should build tree targets have install tree rpaths. +``BUILD_WITH_INSTALL_RPATH`` is a boolean specifying whether to link the target +in the build tree with the :prop_tgt:`INSTALL_RPATH`. This takes precedence +over :prop_tgt:`SKIP_BUILD_RPATH` and avoids the need for relinking before +installation. -BUILD_WITH_INSTALL_RPATH is a boolean specifying whether to link the -target in the build tree with the INSTALL_RPATH. This takes -precedence over SKIP_BUILD_RPATH and avoids the need for relinking -before installation. This property is initialized by the value of the -variable CMAKE_BUILD_WITH_INSTALL_RPATH if it is set when a target is -created. +This property is initialized by the value of the +:variable:`CMAKE_BUILD_WITH_INSTALL_RPATH` variable if it is set when a target +is created. + +If policy :policy:`CMP0068` is not ``NEW``, this property also controls use of +:prop_tgt:`INSTALL_NAME_DIR` in the build tree on macOS. Either way, the +:prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR` target property takes precedence. diff --git a/Help/release/dev/0-sample-topic.rst b/Help/release/dev/0-sample-topic.rst new file mode 100644 index 0000000..e4cc01e --- /dev/null +++ b/Help/release/dev/0-sample-topic.rst @@ -0,0 +1,7 @@ +0-sample-topic +-------------- + +* This is a sample release note for the change in a topic. + Developers should add similar notes for each topic branch + making a noteworthy change. Each document should be named + and titled to match the topic name to avoid merge conflicts. diff --git a/Help/release/dev/ExtractGTestMacro.rst b/Help/release/dev/ExtractGTestMacro.rst new file mode 100644 index 0000000..574982c --- /dev/null +++ b/Help/release/dev/ExtractGTestMacro.rst @@ -0,0 +1,5 @@ +ExtractGTestMacro +----------------- + +* A new :module:`GoogleTest` module was added to provide the + ``gtest_add_tests`` macro independently of the :module:`FindGTest` module. diff --git a/Help/release/dev/FeatureSummary_description.rst b/Help/release/dev/FeatureSummary_description.rst new file mode 100644 index 0000000..c56e4ce --- /dev/null +++ b/Help/release/dev/FeatureSummary_description.rst @@ -0,0 +1,11 @@ +FeatureSummary_description +-------------------------- + +* The :command:`feature_summary` command in the :module:`FeatureSummary` module + accepts the new ``DEFAULT_DESCRIPTION`` option that will print the default + title for the selected package type. + +* The global property :variable:`FeatureSummary_<TYPE>_DESCRIPTION` can be + defined for each ``<TYPE>`` to replace the type name with the specified string + whenever the package type is used in an output string by the + :module:`FeatureSummary` module. diff --git a/Help/release/dev/FindProtobuf-static-libs.rst b/Help/release/dev/FindProtobuf-static-libs.rst new file mode 100644 index 0000000..fcc0678 --- /dev/null +++ b/Help/release/dev/FindProtobuf-static-libs.rst @@ -0,0 +1,5 @@ +FindProtobuf-static-libs +------------------------ + +* The :module:`FindProtobuf` module now supports usage of static libraries + for Unix via a new ``Protobuf_USE_STATIC_LIBS`` input variable. diff --git a/Help/release/dev/install_name_policy.rst b/Help/release/dev/install_name_policy.rst new file mode 100644 index 0000000..7fe9a86 --- /dev/null +++ b/Help/release/dev/install_name_policy.rst @@ -0,0 +1,11 @@ +install_name_policy +------------------- + +* A :prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR` target property and corresponding + :variable:`CMAKE_BUILD_WITH_INSTALL_NAME_DIR` variable were added to + control whether to use the :prop_tgt:`INSTALL_NAME_DIR` target property + value for binaries in the build tree. This is for macOS ``install_name`` + as :prop_tgt:`BUILD_WITH_INSTALL_RPATH` is for ``RPATH``. + +* On macOS, ``RPATH`` settings such as :prop_tgt:`BUILD_WITH_INSTALL_RPATH` + no longer affect the ``install_name`` field. See policy :policy:`CMP0068`. diff --git a/Help/release/dev/productbuild_component_plist.rst b/Help/release/dev/productbuild_component_plist.rst new file mode 100644 index 0000000..78d305c --- /dev/null +++ b/Help/release/dev/productbuild_component_plist.rst @@ -0,0 +1,7 @@ +productbuild_component_plist +---------------------------- + +* The :module:`CPackComponent` module :command:`cpack_add_component` command + gained a new ``PLIST <filename>`` option to specify the ``pkgbuild`` + ``--component-plist`` argument when using the + :module:`productbuild <CPackProductBuild>` generator. diff --git a/Help/release/dev/productbuild_resources.rst b/Help/release/dev/productbuild_resources.rst new file mode 100644 index 0000000..f381e63 --- /dev/null +++ b/Help/release/dev/productbuild_resources.rst @@ -0,0 +1,7 @@ +productbuild_resources +---------------------- + +* The :module:`CPackProductBuild` module gained a new + :variable:`CPACK_PRODUCTBUILD_RESOURCES_DIR` variable to + specify resources to be copied into the ``Resources`` + directory. diff --git a/Help/release/dev/update-curl.rst b/Help/release/dev/update-curl.rst new file mode 100644 index 0000000..852ad5a --- /dev/null +++ b/Help/release/dev/update-curl.rst @@ -0,0 +1,6 @@ +update-curl +----------- + +* The version of curl bundled with CMake no longer accepts URLs of the form + ``file://c:/...`` on Windows due to a change in upstream curl 7.52. Use + the form ``file:///c:/...`` instead to work on all versions. diff --git a/Help/release/dev/vs-nasm.rst b/Help/release/dev/vs-nasm.rst new file mode 100644 index 0000000..bb082a4 --- /dev/null +++ b/Help/release/dev/vs-nasm.rst @@ -0,0 +1,5 @@ +vs-nasm +------- + +* :ref:`Visual Studio Generators` for VS 2010 and above learned to support + the ``ASM_NASM`` language when ``nasm`` is installed. diff --git a/Help/release/dev/wix-custom-root-id.rst b/Help/release/dev/wix-custom-root-id.rst new file mode 100644 index 0000000..3e10fdd --- /dev/null +++ b/Help/release/dev/wix-custom-root-id.rst @@ -0,0 +1,7 @@ +wix-custom-root-id +------------------ + +* The CPack WIX generator implemented a new + :variable:`CPACK_WIX_ROOT_FOLDER_ID` variable which allows + using a custom root folder ID instead of the default + ``ProgramFilesFolder`` / ``ProgramFiles64Folder``. diff --git a/Help/release/index.rst b/Help/release/index.rst index 8f0f252..292c9a8 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -5,6 +5,8 @@ CMake Release Notes This file should include the adjacent "dev.txt" file in development versions but not in release versions. +.. include:: dev.txt + Releases ======== diff --git a/Help/variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR.rst b/Help/variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR.rst new file mode 100644 index 0000000..30d5d3b --- /dev/null +++ b/Help/variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR.rst @@ -0,0 +1,7 @@ +CMAKE_BUILD_WITH_INSTALL_NAME_DIR +--------------------------------- + +Whether to use :prop_tgt:`INSTALL_NAME_DIR` on targets in the build tree. + +This variable is used to initialize the :prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR` +property on all targets. diff --git a/Help/variable/CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES.rst b/Help/variable/CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES.rst new file mode 100644 index 0000000..768f571 --- /dev/null +++ b/Help/variable/CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES.rst @@ -0,0 +1,7 @@ +CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES +-------------------------------------- + +When the ``CUDA`` language has been enabled, this provides a +:ref:`;-list <CMake Language Lists>` of include directories provided +by the CUDA Toolkit. The value may be useful for C++ source files +to include CUDA headers. |