diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/FIND_XXX.txt | 28 | ||||
| -rw-r--r-- | Help/command/find_file.rst | 3 | ||||
| -rw-r--r-- | Help/command/find_library.rst | 3 | ||||
| -rw-r--r-- | Help/command/find_package.rst | 23 | ||||
| -rw-r--r-- | Help/command/find_path.rst | 3 | ||||
| -rw-r--r-- | Help/command/find_program.rst | 2 | ||||
| -rw-r--r-- | Help/dev/review.rst | 48 | ||||
| -rw-r--r-- | Help/policy/CMP0069.rst | 8 | ||||
| -rw-r--r-- | Help/prop_test/FIXTURES_CLEANUP.rst | 3 | ||||
| -rw-r--r-- | Help/prop_test/FIXTURES_REQUIRED.rst | 6 | ||||
| -rw-r--r-- | Help/prop_test/FIXTURES_SETUP.rst | 5 | ||||
| -rw-r--r-- | Help/release/3.9.rst | 19 |
12 files changed, 88 insertions, 63 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/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/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/release/3.9.rst b/Help/release/3.9.rst index 14e8699..ae55105 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. @@ -326,3 +320,16 @@ 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. |