kolan
/
CMake
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
CMake/Help/manual/cmake-policies.7.rst

126 lines
3.5 KiB
ReStructuredText
Raw Normal View History

Help: Glob manual/*.rst in Sphinx configuration Add the man page description line as explicit markup at the top of each Help/manual/*.rst file and scan it from conf.py to automatically generate the man_pages Sphinx configuration value. This reduces the number of places that need to be changed when a new manual is added.
2013-10-30 17:58:25 +04:00
.. cmake-manual-description: CMake Policies Reference
Convert builtin help to reStructuredText source files Run the convert-help.bash script to convert documentation: ./convert-help.bash "/path/to/CMake-build/bin" Then remove it.
2013-10-15 19:17:36 +04:00
cmake-policies(7)
*****************
Help: Drop TOC from latex manuals A latex document can have its own TOC.
2014-11-06 19:37:24 +03:00
.. only:: html
Convert builtin help to reStructuredText source files Run the convert-help.bash script to convert documentation: ./convert-help.bash "/path/to/CMake-build/bin" Then remove it.
2013-10-15 19:17:36 +04:00
.. contents::
Help: Add introduction section to cmake-policies manual Explain the concept behind policies.
2013-10-18 21:22:09 +04:00
Introduction
============
Policies in CMake are used to preserve backward compatible behavior
across multiple releases. When a new policy is introduced, newer CMake
versions will begin to warn about the backward compatible behavior. It
is possible to disable the warning by explicitly requesting the OLD, or
backward compatible behavior using the :command:`cmake_policy` command.
Help: Mark up references to NEW and OLD policy settings properly.
2014-02-03 17:16:49 +04:00
It is also possible to request ``NEW``, or non-backward compatible behavior
Help: Link to CMAKE_POLICY_DEFAULT_CMP<NNNN> in policies manual.
2014-01-09 17:53:38 +04:00
for a policy, also avoiding the warning. Each policy can also be set to
Help: Mark up references to NEW and OLD policy settings properly.
2014-02-03 17:16:49 +04:00
either ``NEW`` or ``OLD`` behavior explicitly on the command line with the
Help: Link to CMAKE_POLICY_DEFAULT_CMP<NNNN> in policies manual.
2014-01-09 17:53:38 +04:00
:variable:`CMAKE_POLICY_DEFAULT_CMP<NNNN>` variable.
Help: Add introduction section to cmake-policies manual Explain the concept behind policies.
2013-10-18 21:22:09 +04:00
Help: Document explicitly that policy OLD behavior is deprecated The most likely documentation page a project author will read in response to a policy warning is the page for the policy itself. Add to every policy documentation page a note explicitly stating that the OLD behavior is deprecated. Also mention this in the cmake_policy() command documentation that explains how to set a policy to OLD. Suggested-by: Fraser Hutchison <fraser.hutchison@gmail.com>
2015-06-09 16:29:41 +03:00
A policy is a deprecation mechanism and not a reliable feature toggle.
A policy should almost never be set to ``OLD``, except to silence warnings
in an otherwise frozen or stable codebase, or temporarily as part of a
larger migration path. The ``OLD`` behavior of each policy is undesirable
and will be replaced with an error condition in a future release.
Help: Document that policies are not feature toggles.
2014-10-21 00:20:42 +04:00
Help: Add introduction section to cmake-policies manual Explain the concept behind policies.
2013-10-18 21:22:09 +04:00
The :command:`cmake_minimum_required` command does more than report an
error if a too-old version of CMake is used to build a project. It
also sets all policies introduced in that CMake version or earlier to
Help: Mark up references to NEW and OLD policy settings properly.
2014-02-03 17:16:49 +04:00
``NEW`` behavior. To manage policies without increasing the minimum required
Help: Mark some code blocks as containing cmake code.
2013-12-26 17:57:02 +04:00
CMake version, the :command:`if(POLICY)` command may be used:
.. code-block:: cmake
Help: Mention if(POLICY) and NO_POLICY_SCOPE in policies manual.
2013-12-20 15:19:11 +04:00
if(POLICY CMP0990)
cmake_policy(SET CMP0990 NEW)
endif()
Help: Mark up references to NEW and OLD policy settings properly.
2014-02-03 17:16:49 +04:00
This has the effect of using the ``NEW`` behavior with newer CMake releases which
Help: Mention if(POLICY) and NO_POLICY_SCOPE in policies manual.
2013-12-20 15:19:11 +04:00
users may be using and not issuing a compatibility warning.
The setting of a policy is confined in some cases to not propagate to the
parent scope. For example, if the files read by the :command:`include` command
or the :command:`find_package` command contain a use of :command:`cmake_policy`,
that policy setting will not affect the caller by default. Both commands accept
an optional ``NO_POLICY_SCOPE`` keyword to control this behavior.
Help: Add introduction section to cmake-policies manual Explain the concept behind policies.
2013-10-18 21:22:09 +04:00
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.
Convert builtin help to reStructuredText source files Run the convert-help.bash script to convert documentation: ./convert-help.bash "/path/to/CMake-build/bin" Then remove it.
2013-10-15 19:17:36 +04:00
All Policies
============
.. toctree::
Help: Limit reference manual toctree depth to 1 Add a :maxdepth: option to all toctree directives to limit their depth to 1. We do not want subheadings from individual documents to pollute the already large lists of CMake Domain objects.
2013-11-01 19:12:02 +04:00
:maxdepth: 1
Convert builtin help to reStructuredText source files Run the convert-help.bash script to convert documentation: ./convert-help.bash "/path/to/CMake-build/bin" Then remove it.
2013-10-15 19:17:36 +04:00
/policy/CMP0000
/policy/CMP0001
/policy/CMP0002
/policy/CMP0003
/policy/CMP0004
/policy/CMP0005
/policy/CMP0006
/policy/CMP0007
/policy/CMP0008
/policy/CMP0009
/policy/CMP0010
/policy/CMP0011
/policy/CMP0012
/policy/CMP0013
/policy/CMP0014
/policy/CMP0015
/policy/CMP0016
/policy/CMP0017
/policy/CMP0018
/policy/CMP0019
/policy/CMP0020
/policy/CMP0021
/policy/CMP0022
/policy/CMP0023
/policy/CMP0024
/policy/CMP0025
/policy/CMP0026
Handle genexes when evaluating INTERFACE_INCLUDE_DIRECTORIES errors.
2013-06-18 18:33:33 +04:00
/policy/CMP0027
Consider targets with double colons to be IMPORTED or ALIAS targets. Introduce a policy to control the behavior. The AliasTargets unit test already tests that using a double-semicolon in the name is not an error. Change the ExportImport test to use a namespace with a double-semicolon too.
2013-07-30 11:51:56 +04:00
/policy/CMP0028
Add policy CMP0029 to disallow subdir_depends
2013-10-18 19:54:48 +04:00
/policy/CMP0029
Add policy CMP0030 to disallow use_mangled_mesa
2013-10-18 19:55:42 +04:00
/policy/CMP0030
Add policy CMP0031 to disallow load_command
2013-10-18 20:41:54 +04:00
/policy/CMP0031
Add policy CMP0032 to disallow output_required_files
2013-10-18 21:00:17 +04:00
/policy/CMP0032
Add policy CMP0033 to disallow export_library_dependencies
2013-10-18 21:09:32 +04:00
/policy/CMP0033
Add policy CMP0034 to disallow utility_source
2013-10-21 19:50:47 +04:00
/policy/CMP0034
Add policy CMP0035 to disallow variable_requires
2013-10-21 19:58:48 +04:00
/policy/CMP0035
Add policy CMP0036 to disallow build_name
2013-10-21 21:12:18 +04:00
/policy/CMP0036
Disallow invalid target names (#13140) Exclude Borland and NMake from the CMP0037 test. They do not accept the colon in a target name.
2013-11-05 20:32:30 +04:00
/policy/CMP0037
Disallow link-to-self (#13947).
2013-11-05 21:01:09 +04:00
/policy/CMP0038
Disallow linking to utility targets (#13902).
2013-11-05 22:15:53 +04:00
/policy/CMP0039
Add policy CMP0040 to disallow custom commands on missing targets
2013-11-20 12:53:06 +04:00
/policy/CMP0040
Export: Report error on relative include with genex. Diagnostics which check the sanity of exported include paths previously skipped over any path containing a generator expression. Introduce a policy to issue an error message in such cases. The export files created in the OLD behavior are not usable, because they contain relative paths or paths to the source or build location which are not suitable for use on installation. CMake will report an error on import.
2013-11-26 14:24:47 +04:00
/policy/CMP0041
OS X: Add CMP0042 to enable MACOSX_RPATH by default Also adding documentation for CMAKE_MACOSX_RPATH, and improving documentation for MACOSX_RPATH.
2013-12-19 08:25:29 +04:00
/policy/CMP0042
cmTarget: Deprecate COMPILE_DEFINITIONS_ properties with a policy.
2013-12-30 16:33:02 +04:00
/policy/CMP0043
Genex: Use case-sensitive comparison for COMPILER_ID.
2013-12-26 18:59:55 +04:00
/policy/CMP0044
get_target_property: Error on non-existent target. Introduce policy CMP0045 to control this behavior.
2014-01-08 16:16:33 +04:00
/policy/CMP0045
AddDependencies: new policy requires dependencies to exist Added new policy CMP0046 which requires dependencies added by add_dependencies() to actually exist.
2014-01-12 15:58:04 +04:00
/policy/CMP0046
QNX: Introduce QCC compiler id for that QNX platform compiler. Introduce policy CMP0047 to control resetting the id for compatibility. De-duplicate content in the QNX platform file by including the GNU one. QNX is a form of GNU platform. Do not clear CMAKE_SHARED_LIBRARY_${lang}_FLAGS variables. They are populated again later by the Compiler/GNU.cmake file anyway. Modify the CMAKE_CXX_COMPILE_OBJECT variable only when the QCC compiler id is in use, and the language is CXX. Use the QNX recommended flag for QCC instead of the gcc compatible -x flag. Populate new module files to handle system includes and depfiles when using the QCC compiler. Remove code which unsets the system include and depfiles related variables. When a GNU driver is used instead of the QCC one, the appropriate flags will be used. These variables were previously cleared for lowest-common-denominator compatibility with both drivers.
2014-01-20 20:57:40 +04:00
/policy/CMP0047
project: Manage VERSION variables Teach the project() command to set variables {PROJECT,<PROJECT-NAME>}_VERSION{,_MAJOR,_MINOR,_PATCH,_TWEAK} holding the project version number and its components. Add project() command option "VERSION" to specify the version explicitly, and default to the empty string when it is not given. Since this clears variables when no VERSION is given, this may change behavior for existing projects that set the version variables themselves prior to calling project(). Add policy CMP0048 for compatibility. Suggested-by: Alex Neundorf <neundorf@kde.org>
2014-01-29 18:28:01 +04:00
/policy/CMP0048
Add policy CMP0049 to avoid variable expansion in source lists
2014-02-11 20:41:24 +04:00
/policy/CMP0049
add_custom_command: Disallow use of SOURCE signatures. Add CMP0050 to control this behavior.
2014-02-11 21:39:55 +04:00
/policy/CMP0050
cmTarget: Include TARGET_OBJECTS genex in target SOURCES property. Add policy CMP0051 to control this behavior.
2014-03-18 19:15:15 +04:00
/policy/CMP0051
Export: Disallow exported interface includes in src/build tree (#14592). Allow directories in the source tree or build tree only if the install tree is a subdirectory of the source tree or build tree, as appropriate. Re-use the test files in the RunCMake.include_directories test to run in multiple scenarios. Bump the required CMake version in the test to 3.0 to ensure that the new policy warnings are emitted correctly.
2014-03-31 19:37:02 +04:00
/policy/CMP0052
EVIS: Add policy CMP0053 This policy switches between the old EVIS parser and the new, faster parser.
2014-04-28 22:59:11 +04:00
/policy/CMP0053
If: Introduce policy CMP0054 - don't dereference quoted variables in if()
2014-09-04 22:21:28 +04:00
/policy/CMP0054
break: Add policy CMP0055 to check calls strictly Reject break() without loop scope or any arguments. Signed-off-by: Gregor Jasny <gjasny@googlemail.com>
2014-11-18 18:34:32 +03:00
/policy/CMP0055
try_compile: Pass linker flags into test project (#14066) Copy CMAKE_EXE_LINKER_FLAGS into the test project generated by try_compile, just like we already copy CMAKE_<LANG>_FLAGS. Add CMake Policy CMP0056 to activate this behavior in a compatible way, but do not warn by default when the policy is not set since it will affect all try_compile calls. Extend the RunCMake.try_compile test with a case covering this behavior for each policy setting.
2014-12-03 19:02:31 +03:00
/policy/CMP0056
add_custom_command: Diagnose MAIN_DEPENDENCY limitation. The new policy CMP0057 diagnoses reuse of the same MAIN_DEPENDENCY across multiple custom commands.
2015-03-09 14:12:13 +03:00
/policy/CMP0057
Ninja: Add policy to require explicit custom command byproducts Add policy CMP0058 to avoid generating 'phony' ninja rules for unknown custom command dependencies. This requires projects to specify their custom command byproducts explicitly. With this requirement we no longer have to assume that unknown custom command dependencies are generated and can instead simply assume they are source files expected to exist when the build starts. This is particularly important in in-source builds. It is also helpful for out-of-source builds to allow Ninja to diagnose missing files before running custom command rules that depend on them.
2015-03-20 23:43:21 +03:00
/policy/CMP0058
Do not treat DEFINITIONS as a built-in directory property Add policy CMP0059 to cover this change. The property has been deprecated since CMake 2.4 anyway. This will help clean up cmMakefile -- the DefineFlagsOrig member should not need to exist.
2015-04-01 21:53:31 +03:00
/policy/CMP0059
Link libraries by full path even in implicit directories When CMP0003 was first introduced we wanted to link all libraries by full path. However, some projects had problems on platforms where find_library would find /usr/lib/libfoo.so when the project really wanted to link to /usr/lib/<arch>/libfoo.so and had been working by accident because pre-CMP0003 behavior used -lfoo to link. We first tried to address that in commit v2.6.0~440 (Teach find_library to avoid returning library paths in system directories, 2008-01-23) by returning just "foo" for libraries in implicit link directories. This caused problems for projects expecting find_library to always return a full path. We ended up using the solution in commit v2.6.0~366 (... switch library paths found in implicit link directories to use -l, 2008-01-31). However, the special case for libraries in implicit link directories has also proven problematic and confusing. Introduce policy CMP0060 to switch to linking all libraries by full path even if they are in implicit link directories. Explain in the policy documentation the factors that led to the original approach and now to this approach.
2015-04-07 17:43:47 +03:00
/policy/CMP0060
CTest: Stop telling 'make' to ignore errors with -i Add policy CMP0061 to maintain compatibility for existing projects.
2015-05-08 22:41:08 +03:00
/policy/CMP0061
install: Disallow installing export() result.
2015-05-14 20:08:27 +03:00
/policy/CMP0062
Honor visibility properties for all target types (#15556) The <LANG>_VISIBILITY_PRESET and VISIBILITY_INLINES_HIDDEN were first merged in commit v2.8.12~322 (Merge topic 'VISIBILITY_PRESET-property', 2013-06-05) but worked only for shared libraries and executables with exports. Prior to commit v3.0.0-rc1~581^2 (GenerateExportHeader: Deprecate add_compiler_export_flags function., 2013-09-02) the add_compiler_export_flags function was used to add visibility flags to all targets. The visibility flags are useful for sources in all target types because they may be later linked into shared libraries or executables with exports. Introduce policy CMP0063 to enable them for all target types while preserving compatibility with existing projects that do not expect this.
2015-05-22 21:01:44 +03:00
/policy/CMP0063
if: Add "TEST <test>" condition if(TEST TestNameThatExists) will return true if a test with the name TestNameThatExists has been added with add_test. The syntax is similar to if(TARGET TargetName). Since use of "TEST" as an argument to if() could previously be interpreted as a non-keyword argument, add policy CMP0064 to treat it as a keyword as NEW behavior.
2014-12-30 04:47:48 +03:00
/policy/CMP0064
CMP0065: Restrict the use of CMAKE_SHARED_LIBRARY_LINK_<LANG>_FLAGS This new policy restricts the addition of the shared library link flags to executables only when the ENABLE_EXPORTS property is set to True.
2015-08-24 21:33:31 +03:00
/policy/CMP0065