diff options
Diffstat (limited to 'Help')
39 files changed, 445 insertions, 104 deletions
diff --git a/Help/command/find_library.rst b/Help/command/find_library.rst index 1eb50f7..e912040 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 :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable is set all +search paths will be tested as normal, with the suffix appended, and with +all matches of ``lib/`` replaced with +``lib${CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX}/``. This variable overrides +the :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` +and :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` global properties. + 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 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 c478a1b..5e96d79 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -229,6 +229,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 0e3eb86..5bd6365 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -45,6 +45,7 @@ Properties of Global Scope /prop_gbl/TARGET_SUPPORTS_SHARED_LIBS /prop_gbl/USE_FOLDERS /prop_gbl/XCODE_EMIT_EFFECTIVE_PLATFORM_NAME + /prop_gbl/XCODE_GENERATE_SCHEME .. _`Directory Properties`: @@ -115,14 +116,17 @@ Properties on Targets /prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG /prop_tgt/ARCHIVE_OUTPUT_NAME /prop_tgt/AUTOGEN_TARGET_DEPENDS + /prop_tgt/AUTOMOC_DEPEND_FILTERS /prop_tgt/AUTOMOC_MOC_OPTIONS /prop_tgt/AUTOMOC /prop_tgt/AUTOUIC /prop_tgt/AUTOUIC_OPTIONS + /prop_tgt/AUTOUIC_SEARCH_PATHS /prop_tgt/AUTORCC /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-qt.7.rst b/Help/manual/cmake-qt.7.rst index 56d4ca7..3b95b05 100644 --- a/Help/manual/cmake-qt.7.rst +++ b/Help/manual/cmake-qt.7.rst @@ -63,26 +63,33 @@ If a ``Q_OBJECT`` or ``Q_GADGET`` macro is found in a header file, ``moc`` will be run on the file. The result will be put into a file named according to ``moc_<basename>.cpp``. If the macro is found in a C++ implementation file, the moc output will be put into a file named according to -``<basename>.moc``, following the Qt conventions. The ``moc file`` may be -included by the user in the C++ implementation file with a preprocessor -``#include``. If it is not so included, it will be added to a separate file -which is compiled into the target. +``<basename>.moc``, following the Qt conventions. The ``<basename>.moc`` must +be included by the user in the C++ implementation file with a preprocessor +``#include``. -The ``moc`` command line will consume the :prop_tgt:`COMPILE_DEFINITIONS` and -:prop_tgt:`INCLUDE_DIRECTORIES` target properties from the target it is being -invoked for, and for the appropriate build configuration. - -The generated ``moc_*.cpp`` and ``*.moc`` files are placed in the +Included ``moc_*.cpp`` and ``*.moc`` files will be generated in the ``<CMAKE_CURRENT_BINARY_DIR>/<TARGETNAME>_autogen/include`` directory which is automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`. (This differs from CMake 3.7 and below; see their documentation for details.) +Not included ``moc_<basename>.cpp`` files will be generated in custom +folders to avoid name collisions and included in a separate +``<CMAKE_CURRENT_BINARY_DIR>/<TARGETNAME>_autogen/moc_compilation.cpp`` +file which is compiled into the target. + +The ``moc`` command line will consume the :prop_tgt:`COMPILE_DEFINITIONS` and +:prop_tgt:`INCLUDE_DIRECTORIES` target properties from the target it is being +invoked for, and for the appropriate build configuration. + The :prop_tgt:`AUTOMOC` target property may be pre-set for all following targets by setting the :variable:`CMAKE_AUTOMOC` variable. The :prop_tgt:`AUTOMOC_MOC_OPTIONS` target property may be populated to set options to pass to ``moc``. The :variable:`CMAKE_AUTOMOC_MOC_OPTIONS` variable may be populated to pre-set the options for all following targets. +Additional ``moc`` dependency file names can be extracted from source code +by using :prop_tgt:`AUTOMOC_DEPEND_FILTERS`. + Source C++ files can be excluded from :prop_tgt:`AUTOMOC` processing by enabling :prop_sf:`SKIP_AUTOMOC` or the broader :prop_sf:`SKIP_AUTOGEN`. @@ -97,7 +104,9 @@ be run, and to create rules to execute ``uic`` at the appropriate time. If a preprocessor ``#include`` directive is found which matches ``ui_<basename>.h``, and a ``<basename>.ui`` file exists, then ``uic`` will -be executed to generate the appropriate file. +be executed to generate the appropriate file. The ``<basename>.ui`` file is +searched for first in the vicinity of including file and afterwards in the +optional :prop_tgt:`AUTOUIC_SEARCH_PATHS` of the target. The generated generated ``ui_*.h`` files are placed in the ``<CMAKE_CURRENT_BINARY_DIR>/<TARGETNAME>_autogen/include`` directory which is diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 38444d1..79c7cd8 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -130,6 +130,7 @@ Variables that Change Behavior /variable/CMAKE_SYSROOT /variable/CMAKE_FIND_APPBUNDLE /variable/CMAKE_FIND_FRAMEWORK + /variable/CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX /variable/CMAKE_FIND_LIBRARY_PREFIXES /variable/CMAKE_FIND_LIBRARY_SUFFIXES /variable/CMAKE_FIND_NO_INSTALL_PREFIX @@ -256,13 +257,16 @@ Variables that Control the Build /variable/CMAKE_ANDROID_STL_TYPE /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG + /variable/CMAKE_AUTOMOC_DEPEND_FILTERS /variable/CMAKE_AUTOMOC_MOC_OPTIONS /variable/CMAKE_AUTOMOC /variable/CMAKE_AUTORCC /variable/CMAKE_AUTORCC_OPTIONS /variable/CMAKE_AUTOUIC /variable/CMAKE_AUTOUIC_OPTIONS + /variable/CMAKE_AUTOUIC_SEARCH_PATHS /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 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_gbl/FIND_LIBRARY_USE_LIB32_PATHS.rst b/Help/prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS.rst index ce18b65..8396026 100644 --- a/Help/prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS.rst +++ b/Help/prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS.rst @@ -8,3 +8,5 @@ Whether the :command:`find_library` command should automatically search :command:`find_library` command should automatically search the ``lib32`` variant of directories called ``lib`` in the search path when building 32-bit binaries. + +See also the :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable. diff --git a/Help/prop_gbl/FIND_LIBRARY_USE_LIB64_PATHS.rst b/Help/prop_gbl/FIND_LIBRARY_USE_LIB64_PATHS.rst index e52f8eb..ed343ba 100644 --- a/Help/prop_gbl/FIND_LIBRARY_USE_LIB64_PATHS.rst +++ b/Help/prop_gbl/FIND_LIBRARY_USE_LIB64_PATHS.rst @@ -8,3 +8,5 @@ FIND_LIBRARY_USE_LIB64_PATHS is a boolean specifying whether the :command:`find_library` command should automatically search the lib64 variant of directories called lib in the search path when building 64-bit binaries. + +See also the :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable. diff --git a/Help/prop_gbl/XCODE_GENERATE_SCHEME.rst b/Help/prop_gbl/XCODE_GENERATE_SCHEME.rst new file mode 100644 index 0000000..be8b5b0 --- /dev/null +++ b/Help/prop_gbl/XCODE_GENERATE_SCHEME.rst @@ -0,0 +1,11 @@ +XCODE_GENERATE_SCHEME +--------------------- + +If enabled, the Xcode generator will generate schema files. Those are +are useful to invoke analyze, archive, build-for-testing and test +actions from the command line. + +.. note:: + + The Xcode Schema Generator is still experimental and subject to + change. diff --git a/Help/prop_tgt/AUTOMOC.rst b/Help/prop_tgt/AUTOMOC.rst index b42643f..b729c0b 100644 --- a/Help/prop_tgt/AUTOMOC.rst +++ b/Help/prop_tgt/AUTOMOC.rst @@ -8,31 +8,41 @@ preprocessor automatically, i.e. without having to use the :module:`QT4_WRAP_CPP() <FindQt4>` or QT5_WRAP_CPP() macro. Currently Qt4 and Qt5 are supported. -When this property is set ``ON``, CMake will scan the +When this property is set ``ON``, CMake will scan the header and source files at build time and invoke moc accordingly. -* If an ``#include`` statement like ``#include "moc_foo.cpp"`` is found, - the ``Q_OBJECT`` class declaration is expected in the header, and - ``moc`` is run on the header file. A ``moc_foo.cpp`` file will be - generated from the source's header into the - ``<CMAKE_CURRENT_BINARY_DIR>/<TARGETNAME>_autogen/include`` - directory which is automatically added to the target's +* If an ``#include`` statement like ``#include "moc_<basename>.cpp"`` is found, + the ``Q_OBJECT`` or ``Q_GADGET`` macros are expected in an otherwise empty + line of the ``<basename>.h(xx)`` header file. ``moc`` is run on the header file to + generate ``moc_<basename>.cpp`` in the + ``<CMAKE_CURRENT_BINARY_DIR>/<TARGETNAME>_autogen/include`` directory + which is automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`. This allows the compiler to find the - included ``moc_foo.cpp`` file regardless of the location the original source. - However, if multiple source files in different directories do this then their - generated moc files would collide. In this case a diagnostic will be issued. - -* If an ``#include`` statement like ``#include "foo.moc"`` is found, - then a ``Q_OBJECT`` is expected in the current source file and ``moc`` - is run on the file itself. Additionally, header files with the same - base name (like ``foo.h``) or ``_p`` appended to the base name (like - ``foo_p.h``) are parsed for ``Q_OBJECT`` macros, and if found, ``moc`` - is also executed on those files. ``AUTOMOC`` checks multiple header - alternative extensions, such as ``hpp``, ``hxx`` etc when searching - for headers. The resulting moc files, which are not included as shown - above in any of the source files are included in a generated - ``moc_compilation.cpp`` file, which is compiled as part of the - target. + included ``moc_<basename>.cpp`` file regardless of the location the + original source. + +* If an ``#include`` statement like ``#include "<basename>.moc"`` is found, + then ``Q_OBJECT`` or ``Q_GADGET`` macros are expected in the current source + file and ``moc`` is run on the source file itself. + +* Header files that are not included by an ``#include "moc_<basename>.cpp"`` + statement are nonetheless scanned for ``Q_OBJECT`` or ``Q_GADGET`` macros. + The resulting ``moc_<basename>.cpp`` files are generated in custom + directories and automatically included in the generated + ``<CMAKE_CURRENT_BINARY_DIR>/<TARGETNAME>_autogen/moc_compilation.cpp`` file, + which is compiled as part of the target. The custom directories help to + avoid name collisions for moc files with the same ``<basename>``. + +* Additionally, header files with the same base name as a source file, + (like ``<basename>.h``) or ``_p`` appended to the base name (like + ``<basename>_p.h``), are parsed for ``Q_OBJECT`` or ``Q_GADGET`` macros, + and if found, ``moc`` is also executed on those files. + +* ``AUTOMOC`` always checks multiple header alternative extensions, + such as ``hpp``, ``hxx``, etc. when searching for headers. + +* ``AUTOMOC`` looks for the ``Q_PLUGIN_METADATA`` macro and reruns the + ``moc`` when the file addressed by the ``FILE`` argument of the macro changes. This property is initialized by the value of the :variable:`CMAKE_AUTOMOC` variable if it is set when a target is created. @@ -47,6 +57,9 @@ See the documentation for this variable for more details. The global property :prop_gbl:`AUTOGEN_TARGETS_FOLDER` can be used to group the automoc targets together in an IDE, e.g. in MSVS. +Additional ``moc`` dependency file names can be extracted from source code +by using :prop_tgt:`AUTOMOC_DEPEND_FILTERS`. + Source C++ files can be excluded from :prop_tgt:`AUTOMOC` processing by enabling :prop_sf:`SKIP_AUTOMOC` or the broader :prop_sf:`SKIP_AUTOGEN`. diff --git a/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst b/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst new file mode 100644 index 0000000..810cbf4 --- /dev/null +++ b/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst @@ -0,0 +1,45 @@ +AUTOMOC_DEPEND_FILTERS +---------------------- + +Filter definitions used by :prop_tgt:`AUTOMOC` to extract file names from +source code as additional dependencies for the ``moc`` file. + +This property is only used if the :prop_tgt:`AUTOMOC` property is ``ON`` +for this target. + +Filters are defined as ``KEYWORD;REGULAR_EXPRESSION`` pairs. First the file +content is searched for ``KEYWORD``. If it is found at least once, then file +names are extracted by successively searching for ``REGULAR_EXPRESSION`` and +taking the first match group. + +Consider a filter extracts the file name ``DEP`` from the content of a file +``FOO``. If ``DEP`` changes, then the ``moc`` file for ``FOO`` gets rebuilt. +The file ``DEP`` is searched for first in the vicinity +of ``FOO`` and afterwards in the target's :prop_tgt:`INCLUDE_DIRECTORIES`. + +By default :prop_tgt:`AUTOMOC_DEPEND_FILTERS` is initialized from +:variable:`CMAKE_AUTOMOC_DEPEND_FILTERS`, which is empty by default. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. + + +Example +------- + +Consider a file ``FOO.hpp`` holds a custom macro ``OBJ_JSON_FILE`` and we +want the ``moc`` file to depend on the macro`s file name argument:: + + class My_Class : public QObject + { + Q_OBJECT + OBJ_JSON_FILE ( "DEP.json" ) + ... + }; + +Then we might use :variable:`CMAKE_AUTOMOC_DEPEND_FILTERS` to +define a filter like this:: + + set(CMAKE_AUTOMOC_DEPEND_FILTERS + "OBJ_JSON_FILE" "[\n][ \t]*OBJ_JSON_FILE[ \t]*\\([ \t]*\"([^\"]+)\"" + ) diff --git a/Help/prop_tgt/AUTOUIC.rst b/Help/prop_tgt/AUTOUIC.rst index fbf24c3..91d95e5 100644 --- a/Help/prop_tgt/AUTOUIC.rst +++ b/Help/prop_tgt/AUTOUIC.rst @@ -10,8 +10,13 @@ Qt4 and Qt5 are supported. When this property is ``ON``, CMake will scan the source files at build time and invoke ``uic`` accordingly. If an ``#include`` statement like -``#include "ui_foo.h"`` is found in ``foo.cpp``, a ``foo.ui`` file is -expected next to ``foo.cpp``, and ``uic`` is run on the ``foo.ui`` file. +``#include "ui_foo.h"`` is found in ``source.cpp``, a ``foo.ui`` file is +searched for first in the vicinity of ``source.cpp`` and afterwards in the +optional :prop_tgt:`AUTOUIC_SEARCH_PATHS` of the target. +``uic`` is run on the ``foo.ui`` file to generate ``ui_foo.h`` in the directory +``<CMAKE_CURRENT_BINARY_DIR>/<TARGETNAME>_autogen/include``, +which is added to the target's :prop_tgt:`INCLUDE_DIRECTORIES` automatically. + This property is initialized by the value of the :variable:`CMAKE_AUTOUIC` variable if it is set when a target is created. diff --git a/Help/prop_tgt/AUTOUIC_OPTIONS.rst b/Help/prop_tgt/AUTOUIC_OPTIONS.rst index dc3bee5..9fb042e 100644 --- a/Help/prop_tgt/AUTOUIC_OPTIONS.rst +++ b/Help/prop_tgt/AUTOUIC_OPTIONS.rst @@ -1,7 +1,7 @@ AUTOUIC_OPTIONS --------------- -Additional options for uic when using :prop_tgt:`AUTOUIC` +Additional options for ``uic`` when using :prop_tgt:`AUTOUIC` This property holds additional command line options which will be used when ``uic`` is executed during the build via :prop_tgt:`AUTOUIC`, i.e. it is diff --git a/Help/prop_tgt/AUTOUIC_SEARCH_PATHS.rst b/Help/prop_tgt/AUTOUIC_SEARCH_PATHS.rst new file mode 100644 index 0000000..96d9f89 --- /dev/null +++ b/Help/prop_tgt/AUTOUIC_SEARCH_PATHS.rst @@ -0,0 +1,12 @@ +AUTOUIC_SEARCH_PATHS +-------------------- + +Search path list used by :prop_tgt:`AUTOUIC` to find included +``.ui`` files. + +This property is initialized by the value of the +:variable:`CMAKE_AUTOUIC_SEARCH_PATHS` variable if it is set +when a target is created. Otherwise it is empty. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. 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/Autogen_depends.rst b/Help/release/dev/Autogen_depends.rst new file mode 100644 index 0000000..c774386 --- /dev/null +++ b/Help/release/dev/Autogen_depends.rst @@ -0,0 +1,10 @@ +AutoGen depends +--------------- + +* Variable :variable:`CMAKE_AUTOMOC_DEPEND_FILTERS` was introduced to + allow :variable:`CMAKE_AUTOMOC` to extract additional dependency file names + for ``moc`` from the contents of source files. + +* The new target property :prop_tgt:`AUTOMOC_DEPEND_FILTERS` was introduced to + allow :prop_tgt:`AUTOMOC` to extract additional dependency file names + for ``moc`` from the contents of source files. diff --git a/Help/release/dev/Autogen_json.rst b/Help/release/dev/Autogen_json.rst new file mode 100644 index 0000000..73bbdf1 --- /dev/null +++ b/Help/release/dev/Autogen_json.rst @@ -0,0 +1,10 @@ +AutoGen json +------------ + +* When using :prop_tgt:`AUTOMOC`, CMake scans for the presence of the + ``Q_PLUGIN_METADATA`` macro and reruns moc when the file from the + macro's ``FILE`` argument changes. + +* When :prop_tgt:`AUTOMOC` detects an include statement of the form + ``#include "moc_<basename>.cpp"`` the respective header file is searched + for in the :prop_tgt:`INCLUDE_DIRECTORIES` of the target as well. diff --git a/Help/release/dev/Autogen_uic_paths.rst b/Help/release/dev/Autogen_uic_paths.rst new file mode 100644 index 0000000..0893194 --- /dev/null +++ b/Help/release/dev/Autogen_uic_paths.rst @@ -0,0 +1,10 @@ +AutoGen uic paths +----------------- + +* Variable :variable:`CMAKE_AUTOUIC_SEARCH_PATHS` was introduced to + allow :variable:`CMAKE_AUTOUIC` to search for ``foo.ui`` in more + places than the vicinity of the ``ui_foo.h`` including file. + +* The new target property :prop_tgt:`AUTOUIC_SEARCH_PATHS` was introduced to + allow :prop_tgt:`AUTOUIC` to search for ``foo.ui`` in more + places than the vicinity of the ``ui_foo.h`` including file. 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/cmake-xcode-schemes.rst b/Help/release/dev/cmake-xcode-schemes.rst new file mode 100644 index 0000000..27c19d7 --- /dev/null +++ b/Help/release/dev/cmake-xcode-schemes.rst @@ -0,0 +1,6 @@ +cmake-xcode-schemes +------------------- + +* The :generator:`Xcode` generator got the ability to create schema files. + This is still an experimental feature and can be activated by setting the + :prop_gbl:`XCODE_GENERATE_SCHEME` global property to a ``TRUE`` value. diff --git a/Help/release/dev/find_library-custom-lib-suffix.rst b/Help/release/dev/find_library-custom-lib-suffix.rst new file mode 100644 index 0000000..824b27e --- /dev/null +++ b/Help/release/dev/find_library-custom-lib-suffix.rst @@ -0,0 +1,6 @@ +find_library-custom-lib-suffix +------------------------------ + +* A :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable was added to + tell the :command:`find_library` command to search in a ``lib<suffix>`` + directory before each ``lib`` directory that would normally be searched. 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_AUTOMOC_DEPEND_FILTERS.rst b/Help/variable/CMAKE_AUTOMOC_DEPEND_FILTERS.rst new file mode 100644 index 0000000..5c3662d --- /dev/null +++ b/Help/variable/CMAKE_AUTOMOC_DEPEND_FILTERS.rst @@ -0,0 +1,12 @@ +CMAKE_AUTOMOC_DEPEND_FILTERS +---------------------------- + +Filter definitions used by :variable:`CMAKE_AUTOMOC` +to extract file names from source code as additional dependencies +for the ``moc`` file. + +This variable is used to initialize the :prop_tgt:`AUTOMOC_DEPEND_FILTERS` +property on all the targets. See that target property for additional +information. + +By default it is empty. diff --git a/Help/variable/CMAKE_AUTOUIC_SEARCH_PATHS.rst b/Help/variable/CMAKE_AUTOUIC_SEARCH_PATHS.rst new file mode 100644 index 0000000..aa132bf --- /dev/null +++ b/Help/variable/CMAKE_AUTOUIC_SEARCH_PATHS.rst @@ -0,0 +1,11 @@ +CMAKE_AUTOUIC_SEARCH_PATHS +-------------------------- + +Search path list used by :variable:`CMAKE_AUTOUIC` to find included +``.ui`` files. + +This variable is used to initialize the :prop_tgt:`AUTOUIC_SEARCH_PATHS` +property on all the targets. See that target property for additional +information. + +By default it is empty. 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_FIND_LIBRARY_CUSTOM_LIB_SUFFIX.rst b/Help/variable/CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX.rst new file mode 100644 index 0000000..f7c6524 --- /dev/null +++ b/Help/variable/CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX.rst @@ -0,0 +1,11 @@ +CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX +------------------------------------ + +Specify a ``<suffix>`` to tell the :command:`find_library` command to +search in a ``lib<suffix>`` directory before each ``lib`` directory that +would normally be searched. + +This overrides the behavior of related global properties: + +* :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` +* :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` |