diff options
Diffstat (limited to 'Help')
26 files changed, 220 insertions, 90 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index 8a0fc8d..7db221c 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -16,7 +16,6 @@ The general signature is: [PATH_SUFFIXES suffix1 [suffix2 ...]] [DOC "cache documentation string"] [NO_DEFAULT_PATH] - [NO_PACKAGE_ROOT_PATH] [NO_CMAKE_PATH] [NO_CMAKE_ENVIRONMENT_PATH] [NO_SYSTEM_ENVIRONMENT_PATH] @@ -61,10 +60,6 @@ If ``NO_DEFAULT_PATH`` is specified, then no additional paths are added to the search. If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: -.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| replace:: - |prefix_XXX_SUBDIR| for each ``<prefix>`` in ``PackageName_ROOT`` if called - from within a find module - .. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace:: |prefix_XXX_SUBDIR| for each ``<prefix>`` in :variable:`CMAKE_PREFIX_PATH` @@ -76,18 +71,7 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: |prefix_XXX_SUBDIR| for each ``<prefix>`` in :variable:`CMAKE_SYSTEM_PREFIX_PATH` -1. If called from within a find module, search prefix paths unique to the - current package being found. Specifically look in the ``PackageName_ROOT`` - CMake and environment variables. The package root variables are maintained - as a stack so if called from nested find modules, root paths from the - parent's find module will be searchd after paths from the current module, - i.e. ``CurrentPackage_ROOT``, ``ENV{CurrentPackage_ROOT}``, - ``ParentPackage_ROOT``, ``ENV{ParentPacakge_ROOT}``, etc. - This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed. - - * |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| - -2. Search paths specified in cmake-specific cache variables. +1. Search paths specified in cmake-specific cache variables. These are intended to be used on the command line with a ``-DVAR=value``. The values are interpreted as :ref:`;-lists <CMake Language Lists>`. This can be skipped if ``NO_CMAKE_PATH`` is passed. @@ -96,7 +80,7 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: * |CMAKE_XXX_PATH| * |CMAKE_XXX_MAC_PATH| -3. Search paths specified in cmake-specific environment variables. +2. Search paths specified in cmake-specific environment variables. These are intended to be set in the user's shell configuration, and therefore use the host's native path separator (``;`` on Windows and ``:`` on UNIX). @@ -106,17 +90,17 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: * |CMAKE_XXX_PATH| * |CMAKE_XXX_MAC_PATH| -4. Search the paths specified by the ``HINTS`` option. +3. Search the paths specified by the ``HINTS`` option. These should be paths computed by system introspection, such as a hint provided by the location of another item already found. Hard-coded guesses should be specified with the ``PATHS`` option. -5. Search the standard system environment variables. +4. Search the standard system environment variables. This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is an argument. * |SYSTEM_ENVIRONMENT_PATH_XXX| -6. Search cmake variables defined in the Platform files +5. Search cmake variables defined in the Platform files for the current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is passed. @@ -124,7 +108,7 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: * |CMAKE_SYSTEM_XXX_PATH| * |CMAKE_SYSTEM_XXX_MAC_PATH| -7. Search the paths specified by the PATHS option +6. Search the paths specified by the PATHS option or in the short-hand version of the command. These are typically hard-coded guesses. diff --git a/Help/command/find_file.rst b/Help/command/find_file.rst index 2a14ad7..e56097b 100644 --- a/Help/command/find_file.rst +++ b/Help/command/find_file.rst @@ -8,9 +8,6 @@ find_file .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include`` .. |entry_XXX_SUBDIR| replace:: ``<entry>/include`` -.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace:: - ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` - is set, and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| .. |CMAKE_PREFIX_PATH_XXX| replace:: ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, and |CMAKE_PREFIX_PATH_XXX_SUBDIR| diff --git a/Help/command/find_library.rst b/Help/command/find_library.rst index 0861d67..f774f17 100644 --- a/Help/command/find_library.rst +++ b/Help/command/find_library.rst @@ -8,9 +8,6 @@ find_library .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/lib`` .. |entry_XXX_SUBDIR| replace:: ``<entry>/lib`` -.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace:: - ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, - and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| .. |CMAKE_PREFIX_PATH_XXX| replace:: ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, and |CMAKE_PREFIX_PATH_XXX_SUBDIR| diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 08c6ccd..83f4716 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -64,7 +64,6 @@ The complete Config mode command signature is:: [PATHS path1 [path2 ... ]] [PATH_SUFFIXES suffix1 [suffix2 ...]] [NO_DEFAULT_PATH] - [NO_PACAKGE_ROOT_PATH] [NO_CMAKE_PATH] [NO_CMAKE_ENVIRONMENT_PATH] [NO_SYSTEM_ENVIRONMENT_PATH] @@ -250,13 +249,7 @@ The set of installation prefixes is constructed using the following steps. If ``NO_DEFAULT_PATH`` is specified all ``NO_*`` options are enabled. -1. Search paths specified in the ``PackageName_ROOT`` CMake and environment - variables. The package root variables are maintained as a stack so if - called from within a find module, root paths from the parent's find - module will also be searched after paths for the current package. This can - be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed. - -2. Search paths specified in cmake-specific cache variables. These +1. Search paths specified in cmake-specific cache variables. These are intended to be used on the command line with a ``-DVAR=value``. The values are interpreted as :ref:`;-lists <CMake Language Lists>`. This can be skipped if ``NO_CMAKE_PATH`` is passed:: @@ -265,7 +258,7 @@ enabled. CMAKE_FRAMEWORK_PATH CMAKE_APPBUNDLE_PATH -3. Search paths specified in cmake-specific environment variables. +2. Search paths specified in cmake-specific environment variables. These are intended to be set in the user's shell configuration, and therefore use the host's native path separator (``;`` on Windows and ``:`` on UNIX). @@ -276,26 +269,26 @@ enabled. CMAKE_FRAMEWORK_PATH CMAKE_APPBUNDLE_PATH -4. Search paths specified by the ``HINTS`` option. These should be paths +3. Search paths specified by the ``HINTS`` option. These should be paths computed by system introspection, such as a hint provided by the location of another item already found. Hard-coded guesses should be specified with the ``PATHS`` option. -5. Search the standard system environment variables. This can be +4. Search the standard system environment variables. This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed. Path entries ending in ``/bin`` or ``/sbin`` are automatically converted to their parent directories:: PATH -6. Search paths stored in the CMake :ref:`User Package Registry`. +5. Search paths stored in the CMake :ref:`User Package Registry`. This can be skipped if ``NO_CMAKE_PACKAGE_REGISTRY`` is passed or by setting the :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` to ``TRUE``. See the :manual:`cmake-packages(7)` manual for details on the user package registry. -7. Search cmake variables defined in the Platform files for the +6. Search cmake variables defined in the Platform files for the current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is passed:: @@ -303,14 +296,14 @@ enabled. CMAKE_SYSTEM_FRAMEWORK_PATH CMAKE_SYSTEM_APPBUNDLE_PATH -8. Search paths stored in the CMake :ref:`System Package Registry`. +7. Search paths stored in the CMake :ref:`System Package Registry`. This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed or by setting the :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` to ``TRUE``. See the :manual:`cmake-packages(7)` manual for details on the system package registry. -9. Search paths specified by the ``PATHS`` option. These are typically +8. Search paths specified by the ``PATHS`` option. These are typically hard-coded guesses. .. |FIND_XXX| replace:: find_package diff --git a/Help/command/find_path.rst b/Help/command/find_path.rst index 988a3fa..76342d0 100644 --- a/Help/command/find_path.rst +++ b/Help/command/find_path.rst @@ -8,9 +8,6 @@ find_path .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include`` .. |entry_XXX_SUBDIR| replace:: ``<entry>/include`` -.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace:: - ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` - is set, and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| .. |CMAKE_PREFIX_PATH_XXX| replace:: ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, and |CMAKE_PREFIX_PATH_XXX_SUBDIR| diff --git a/Help/command/find_program.rst b/Help/command/find_program.rst index 4f00773..d3430c0 100644 --- a/Help/command/find_program.rst +++ b/Help/command/find_program.rst @@ -8,8 +8,6 @@ find_program .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/[s]bin`` .. |entry_XXX_SUBDIR| replace:: ``<entry>/[s]bin`` -.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace:: - |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| .. |CMAKE_PREFIX_PATH_XXX| replace:: |CMAKE_PREFIX_PATH_XXX_SUBDIR| .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_PROGRAM_PATH` diff --git a/Help/command/if.rst b/Help/command/if.rst index edd343d..f04f233 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -30,7 +30,7 @@ else and endif clause is optional. Long expressions can be used and there is a traditional order of precedence. Parenthetical expressions are evaluated first followed by unary tests such as ``EXISTS``, ``COMMAND``, and ``DEFINED``. Then any binary tests such as -``EQUAL``, ``LESS``, ``LESS_EQUAL, ``GREATER``, ``GREATER_EQUAL``, +``EQUAL``, ``LESS``, ``LESS_EQUAL``, ``GREATER``, ``GREATER_EQUAL``, ``STREQUAL``, ``STRLESS``, ``STRLESS_EQUAL``, ``STRGREATER``, ``STRGREATER_EQUAL``, ``VERSION_EQUAL``, ``VERSION_LESS``, ``VERSION_LESS_EQUAL``, ``VERSION_GREATER``, ``VERSION_GREATER_EQUAL``, diff --git a/Help/command/string.rst b/Help/command/string.rst index 4f0c45c..ba4a412 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -132,6 +132,15 @@ APPEND Append all the input arguments to the string. +PREPEND +""""""" + +:: + + string(PREPEND <string variable> [<input>...]) + +Prepend all the input arguments to the string. + CONCAT """""" diff --git a/Help/dev/review.rst b/Help/dev/review.rst index 9450bf0..985b1b7 100644 --- a/Help/dev/review.rst +++ b/Help/dev/review.rst @@ -185,6 +185,54 @@ commands to ``@kwrobot`` using the form ``Do: ...``: See the corresponding sections for details on permissions and options for each command. +Commit Messages +--------------- + +Part of the human review is to check that each commit message is appropriate. +The first line of the message should begin with one or two words indicating the +area the commit applies to, followed by a colon and then a brief summary. +Committers should aim to keep this first line short. Any subsequent lines +should be separated from the first by a blank line and provide relevant, useful +information. + +The appropriateness of the initial word describing the area the commit applies +to is not something the automatic robot review can judge, so it is up to the +human reviewer to confirm that the area is specified and that it is +appropriate. Good area words include the module name the commit is primarily +fixing, the main C++ source file being edited, ``Help`` for generic +documentation changes or a feature or functionality theme the changes apply to +(e.g. ``server`` or ``Autogen``). Examples of suitable first lines of a commit +message include: + +* ``Help: Fix example in cmake-buildsystem(7) manual`` +* ``FindBoost: Add support for 1.64`` +* ``Autogen: Extended mocInclude tests`` +* ``cmLocalGenerator: Explain standard flag selection logic in comments`` + +If the commit fixes a particular reported issue, this information should +ideally also be part of the commit message. The recommended way to do this is +to place a line at the end of the message in the form ``Fixes: #xxxxx`` where +``xxxxx`` is the GitLab issue number and to separate it from the rest of the +text by a blank line. For example:: + + Help: Fix FooBar example robustness issue + + FooBar supports option X, but the example provided + would not work if Y was also specified. + + Fixes: #12345 + +GitLab will automatically create relevant links to the merge request and will +close the issue when the commit is merged into master. GitLab understands a few +other synonyms for ``Fixes`` and allows much more flexible forms than the +above, but committers should aim for this format for consistency. Note that +such details can alternatively be specified in the merge request description. + +Reviewers are encouraged to ask the committer to amend commit messages to +follow these guidelines, but prefer to focus on the changes themselves as a +first priority. Maintainers will also make a check of commit messages before +merging. + Topic Testing ============= diff --git a/Help/dev/source.rst b/Help/dev/source.rst index 16a9252..b40a884 100644 --- a/Help/dev/source.rst +++ b/Help/dev/source.rst @@ -23,20 +23,18 @@ format only a subset of files, such as those that are locally modified. C++ Subset Permitted ==================== -CMake supports compiling as C++98 in addition to C++11 and C++14. -In order to support building on older toolchains some constructs -need to be handled with care: +CMake requires compiling as C++11 or above. However, in order to support +building on older toolchains some constructs need to be handled with care: -* Use ``CM_AUTO_PTR`` instead of ``std::auto_ptr``. +* Do not use ``CM_AUTO_PTR`` or ``std::auto_ptr``. - 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. + The ``std::auto_ptr`` template is deprecated in C++11. The ``CM_AUTO_PTR`` + macro remains leftover from C++98 support until its uses can be ported to + ``std::unique_ptr``. Do not add new uses of the macro. * Use ``CM_EQ_DELETE;`` instead of ``= delete;``. - Defining functions as *deleted* is not supported in C++98. Using + Older C++11 compilers do not support deleting functions. Using ``CM_EQ_DELETE`` will delete the functions if the compiler supports it and give them no implementation otherwise. Calling such a function will lead to compiler errors if the compiler supports *deleted* functions and linker diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index cc8c356..f1378c8 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -123,6 +123,7 @@ Properties on Targets /prop_tgt/AUTOGEN_BUILD_DIR /prop_tgt/AUTOGEN_TARGET_DEPENDS /prop_tgt/AUTOMOC_DEPEND_FILTERS + /prop_tgt/AUTOMOC_MACRO_NAMES /prop_tgt/AUTOMOC_MOC_OPTIONS /prop_tgt/AUTOMOC /prop_tgt/AUTOUIC diff --git a/Help/manual/cmake-qt.7.rst b/Help/manual/cmake-qt.7.rst index b3b09d1..55121df 100644 --- a/Help/manual/cmake-qt.7.rst +++ b/Help/manual/cmake-qt.7.rst @@ -70,7 +70,8 @@ be included by the user in the C++ implementation file with a preprocessor Included ``moc_*.cpp`` and ``*.moc`` files will be generated in the ``<AUTOGEN_BUILD_DIR>/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.) + +* This differs from CMake 3.7 and below; see their documentation for details. * For multi configuration generators, the include directory is ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>``. @@ -94,6 +95,10 @@ following targets by setting the :variable:`CMAKE_AUTOMOC` variable. The options to pass to ``moc``. The :variable:`CMAKE_AUTOMOC_MOC_OPTIONS` variable may be populated to pre-set the options for all following targets. +The appearance of the strings ``Q_OBJECT`` or ``Q_GADGET`` in a source file +determines if it needs to be ``moc`` processed. To search for additional +strings, list them in :prop_tgt:`AUTOMOC_MACRO_NAMES`. + Additional ``moc`` dependency file names can be extracted from source code by using :prop_tgt:`AUTOMOC_DEPEND_FILTERS`. @@ -110,15 +115,23 @@ inspects the C++ files in the target to determine if they require ``uic`` to 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. 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. +``<path>ui_<basename>.h``, and a ``<basename>.ui`` file exists, +then ``uic`` will be executed to generate the appropriate file. +The ``<basename>.ui`` file is searched for in the following places + +1. ``<source_dir>/<basename>.ui`` +2. ``<source_dir>/<path><basename>.ui`` +3. ``<AUTOUIC_SEARCH_PATHS>/<basename>.ui`` +4. ``<AUTOUIC_SEARCH_PATHS>/<path><basename>.ui`` + +where ``<source_dir>`` is the directory of the C++ file and +:prop_tgt:`AUTOUIC_SEARCH_PATHS` is a list of additional search paths. The generated generated ``ui_*.h`` files are placed in the ``<AUTOGEN_BUILD_DIR>/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.) + +* This differs from CMake 3.7 and below; see their documentation for details. * For multi configuration generators, the include directory is ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>``. diff --git a/Help/manual/cmake-server.7.rst b/Help/manual/cmake-server.7.rst index f6d3032..c56e5a7 100644 --- a/Help/manual/cmake-server.7.rst +++ b/Help/manual/cmake-server.7.rst @@ -277,7 +277,9 @@ Giving the "major" version of the requested protocol version will make the serve use the latest minor version of that protocol. Use this if you do not explicitly need to depend on a specific minor version. -Each protocol version may request additional attributes to be present. +If the build directory already contains a CMake cache, it is sufficient to set +the "buildDirectory" attribute. To create a fresh build directory, additional +attributes are required depending on the protocol version. Protocol version 1.0 requires the following attributes to be set: @@ -664,8 +666,7 @@ and will not survive the build directory getting cleaned out. Type "cache" ^^^^^^^^^^^^ -The "cache" request can be used once a project is configured and will -list the cached configuration values. +The "cache" request will list the cached configuration values. Example:: diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 363b90f..bef1171 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -270,6 +270,7 @@ Variables that Control the Build /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_AUTOMOC /variable/CMAKE_AUTOMOC_DEPEND_FILTERS + /variable/CMAKE_AUTOMOC_MACRO_NAMES /variable/CMAKE_AUTOMOC_MOC_OPTIONS /variable/CMAKE_AUTORCC /variable/CMAKE_AUTORCC_OPTIONS diff --git a/Help/policy/CMP0069.rst b/Help/policy/CMP0069.rst index b8f5d80..0d5ddfd 100644 --- a/Help/policy/CMP0069.rst +++ b/Help/policy/CMP0069.rst @@ -55,8 +55,8 @@ Produce a fatal error if support is not available: cmake_minimum_required(VERSION 3.9) # CMP0069 NEW project(foo) - include(CheckIPOSupport) - check_ipo_support() + include(CheckIPOSupported) + check_ipo_supported() # ... @@ -69,11 +69,11 @@ Apply IPO flags only if compiler supports it: cmake_minimum_required(VERSION 3.9) # CMP0069 NEW project(foo) - include(CheckIPOSupport) + include(CheckIPOSupported) # ... - check_ipo_support(RESULT result) + check_ipo_supported(RESULT result) if(result) set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE) endif() diff --git a/Help/prop_test/FIXTURES_CLEANUP.rst b/Help/prop_test/FIXTURES_CLEANUP.rst index f0a4be0..3075b4d 100644 --- a/Help/prop_test/FIXTURES_CLEANUP.rst +++ b/Help/prop_test/FIXTURES_CLEANUP.rst @@ -2,7 +2,8 @@ FIXTURES_CLEANUP ---------------- Specifies a list of fixtures for which the test is to be treated as a cleanup -test. +test. These fixture names are distinct from test case names and are not +required to have any similarity to the names of tests associated with them. Fixture cleanup tests are ordinary tests with all of the usual test functionality. Setting the ``FIXTURES_CLEANUP`` property for a test has two diff --git a/Help/prop_test/FIXTURES_REQUIRED.rst b/Help/prop_test/FIXTURES_REQUIRED.rst index e37dfb5..e3f60c4 100644 --- a/Help/prop_test/FIXTURES_REQUIRED.rst +++ b/Help/prop_test/FIXTURES_REQUIRED.rst @@ -2,7 +2,7 @@ FIXTURES_REQUIRED ----------------- Specifies a list of fixtures the test requires. Fixture names are case -sensitive. +sensitive and they are not required to have any similarity to test names. Fixtures are a way to attach setup and cleanup tasks to a set of tests. If a test requires a given fixture, then all tests marked as setup tasks for that @@ -19,7 +19,9 @@ some setup tests fail. When CTest is asked to execute only a subset of tests (e.g. by the use of regular expressions or when run with the ``--rerun-failed`` command line option), it will automatically add any setup or cleanup tests for fixtures -required by any of the tests that are in the execution set. +required by any of the tests that are in the execution set. This behavior can +be overridden with the ``-FS``, ``-FC`` and ``-FA`` command line options to +:manual:`ctest(1)` if desired. Since setup and cleanup tasks are also tests, they can have an ordering specified by the :prop_test:`DEPENDS` test property just like any other tests. diff --git a/Help/prop_test/FIXTURES_SETUP.rst b/Help/prop_test/FIXTURES_SETUP.rst index a220215..fdb21cc 100644 --- a/Help/prop_test/FIXTURES_SETUP.rst +++ b/Help/prop_test/FIXTURES_SETUP.rst @@ -2,14 +2,15 @@ FIXTURES_SETUP -------------- Specifies a list of fixtures for which the test is to be treated as a setup -test. +test. These fixture names are distinct from test case names and are not +required to have any similarity to the names of tests associated with them. Fixture setup tests are ordinary tests with all of the usual test functionality. Setting the ``FIXTURES_SETUP`` property for a test has two primary effects: - CTest will ensure the test executes before any other test which lists the - fixture(s) in its :prop_test:`FIXTURES_REQUIRED` property. + fixture name(s) in its :prop_test:`FIXTURES_REQUIRED` property. - If CTest is asked to run only a subset of tests (e.g. using regular expressions or the ``--rerun-failed`` option) and the setup test is not in diff --git a/Help/prop_tgt/AUTOMOC.rst b/Help/prop_tgt/AUTOMOC.rst index e70fe0d..61813be68 100644 --- a/Help/prop_tgt/AUTOMOC.rst +++ b/Help/prop_tgt/AUTOMOC.rst @@ -5,8 +5,8 @@ Should the target be processed with automoc (for Qt projects). AUTOMOC is a boolean specifying whether CMake will handle the Qt ``moc`` 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. +: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 header and source files at build time and invoke moc accordingly. @@ -37,7 +37,7 @@ source files at build time and invoke moc accordingly. which is compiled as part of the target. * The custom directories with checksum - based names help to avoid name collisions for moc files with the same + based names help to avoid name collisions for ``moc`` files with the same ``<basename>``. * See :prop_tgt:`AUTOGEN_BUILD_DIR`. @@ -56,11 +56,11 @@ source files at build time and invoke moc accordingly. This property is initialized by the value of the :variable:`CMAKE_AUTOMOC` variable if it is set when a target is created. -Additional command line options for moc can be set via the +Additional command line options for ``moc`` can be set via the :prop_tgt:`AUTOMOC_MOC_OPTIONS` property. By enabling the :variable:`CMAKE_AUTOMOC_RELAXED_MODE` variable the -rules for searching the files which will be processed by moc can be relaxed. +rules for searching the files which will be processed by ``moc`` can be relaxed. See the documentation for this variable for more details. The global property :prop_gbl:`AUTOGEN_TARGETS_FOLDER` can be used to group the @@ -69,6 +69,10 @@ automoc targets together in an IDE, e.g. in MSVS. The global property :prop_gbl:`AUTOGEN_SOURCE_GROUP` can be used to group files generated by :prop_tgt:`AUTOMOC` together in an IDE, e.g. in MSVS. +The appearance of the strings ``Q_OBJECT`` or ``Q_GADGET`` in a source file +determines if it needs to be ``moc`` processed. To search for additional +strings, list them in :prop_tgt:`AUTOMOC_MACRO_NAMES`. + Additional ``moc`` dependency file names can be extracted from source code by using :prop_tgt:`AUTOMOC_DEPEND_FILTERS`. diff --git a/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst b/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst new file mode 100644 index 0000000..0639bc8 --- /dev/null +++ b/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst @@ -0,0 +1,28 @@ +AUTOMOC_MACRO_NAMES +------------------- + +Additional macro names used by :prop_tgt:`AUTOMOC` +to determine if a C++ file needs to be processed by ``moc``. + +This property is only used if the :prop_tgt:`AUTOMOC` property is ``ON`` +for this target. + +CMake searches for the strings ``Q_OBJECT`` and ``Q_GADGET`` to +determine if a file needs to be processed by ``moc``. +:prop_tgt:`AUTOMOC_MACRO_NAMES` allows to add additional strings to the +search list. This is useful for cases where the ``Q_OBJECT`` or ``Q_GADGET`` +macro is hidden inside another macro. + +By default :prop_tgt:`AUTOMOC_MACRO_NAMES` is initialized from +:variable:`CMAKE_AUTOMOC_MACRO_NAMES`, which is empty by default. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. + +Example +------- +In this case the the ``Q_OBJECT`` macro is hidden inside an other macro +called ``CUSTOM_MACRO``. To let CMake know that source files, that contain +``CUSTOM_MACRO``, need to be ``moc`` processed, we call:: + + set_property(TARGET tgt PROPERTY AUTOMOC_MACRO_NAMES "CUSTOM_MACRO") diff --git a/Help/release/3.9.rst b/Help/release/3.9.rst index 14e8699..5087b43 100644 --- a/Help/release/3.9.rst +++ b/Help/release/3.9.rst @@ -42,12 +42,6 @@ Commands * The :command:`add_library` command ``IMPORTED`` option learned to support :ref:`Object Libraries`. -* All ``find_`` commands now have a ``PACKAGE_ROOT`` search path group that - is first in the search heuristics. If a ``find_`` command is called from - inside a find module, then the CMake variable and environment variable named - ``<PackageName>_ROOT`` are used as prefixes and are the first set of paths - to be searched. - * The :command:`find_library` command learned to search ``libx32`` paths when the build targets the ``x32`` ABI. See the :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` global property. @@ -316,9 +310,6 @@ Other Changes in dependent targets may now compile without waiting for their targets' dependencies to link. -* On macOS, the default application bundle ``Info.plist`` file now enables - Hi-DPI support. - * On macOS, ``RPATH`` settings such as :prop_tgt:`BUILD_WITH_INSTALL_RPATH` no longer affect the ``install_name`` field. See policy :policy:`CMP0068`. @@ -326,3 +317,23 @@ Other Changes a change to the ``v140`` toolset made by a VS 2015 update. VS changed the set of values it understands for the ``GenerateDebugInformation`` linker setting that produces the ``-DEBUG`` linker flag variants. + +Updates +======= + +Changes made since CMake 3.9.0 include the following. + +3.9.1 +----- + +* The ``find_`` command ``PACKAGE_ROOT`` search path group added by + CMake 3.9.0 has been removed for the 3.9 series due to regressions + caused by new use of ``<PackageName>_ROOT`` variables. The behavior + may be re-introduced in the future in a more-compatible way. + +3.9.2 +----- + +* On macOS, the default application bundle ``Info.plist`` file no longer + enables Hi-DPI support as it did in 3.9.0 and 3.9.1. The change had + to be reverted because it broke iOS applications. diff --git a/Help/release/dev/autogen-macro-names.rst b/Help/release/dev/autogen-macro-names.rst new file mode 100644 index 0000000..736dd3a --- /dev/null +++ b/Help/release/dev/autogen-macro-names.rst @@ -0,0 +1,12 @@ +autogen-macro-names +------------------- + +* When using :prop_tgt:`AUTOMOC`, CMake searches for the strings ``Q_OBJECT`` + and ``Q_OBJECT`` in a source file to determine if it needs to be ``moc`` + processed. The new variable :variable:`CMAKE_AUTOMOC_MACRO_NAMES` allows to + register additional strings (macro names) so search for. + +* When using :prop_tgt:`AUTOMOC`, CMake searches for the strings ``Q_OBJECT`` + and ``Q_OBJECT`` in a source file to determine if it needs to be ``moc`` + processed. The new target property :prop_tgt:`AUTOMOC_MACRO_NAMES` allows to + register additional strings (macro names) so search for. diff --git a/Help/release/dev/cpackifw-package-file-extension.rst b/Help/release/dev/cpackifw-package-file-extension.rst new file mode 100644 index 0000000..e264081 --- /dev/null +++ b/Help/release/dev/cpackifw-package-file-extension.rst @@ -0,0 +1,6 @@ +cpackifw-package-file-extension +------------------------------- + +* The :module:`CPackIFW` module gained new + :variable:`CPACK_IFW_PACKAGE_FILE_EXTENSION` variable to customize + target binary format. diff --git a/Help/release/dev/require-c++11.rst b/Help/release/dev/require-c++11.rst new file mode 100644 index 0000000..7b849e7 --- /dev/null +++ b/Help/release/dev/require-c++11.rst @@ -0,0 +1,5 @@ +require-c++11 +------------- + +* Support for building CMake itself with C++98 compilers was dropped. + CMake is now implemented using C++11. diff --git a/Help/release/dev/string_prepend.rst b/Help/release/dev/string_prepend.rst new file mode 100644 index 0000000..f896e91 --- /dev/null +++ b/Help/release/dev/string_prepend.rst @@ -0,0 +1,4 @@ +string_prepend +-------------- + +* The :command:`string` command learned a new ``PREPEND`` subcommand. diff --git a/Help/variable/CMAKE_AUTOMOC_MACRO_NAMES.rst b/Help/variable/CMAKE_AUTOMOC_MACRO_NAMES.rst new file mode 100644 index 0000000..7ed3445 --- /dev/null +++ b/Help/variable/CMAKE_AUTOMOC_MACRO_NAMES.rst @@ -0,0 +1,19 @@ +CMAKE_AUTOMOC_MACRO_NAMES +---------------------------- + +Additional macro names used by :variable:`CMAKE_AUTOMOC` +to determine if a C++ file needs to be processed by ``moc``. + +This variable is used to initialize the :prop_tgt:`AUTOMOC_MACRO_NAMES` +property on all the targets. See that target property for additional +information. + +By default it is empty. + +Example +------- +Let CMake know that source files that contain ``CUSTOM_MACRO`` must be ``moc`` +processed as well:: + + set(CMAKE_AUTOMOC ON) + set(CMAKE_AUTOMOC_MACRO_NAMES "CUSTOM_MACRO") |