1 /*============================================================================
2 CMake - Cross Platform Makefile Generator
3 Copyright 2000-2009 Kitware, Inc., Insight Software Consortium
5 Distributed under the OSI-approved BSD License (the "License");
6 see accompanying file Copyright.txt for details.
8 This software is distributed WITHOUT ANY WARRANTY; without even the
9 implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
10 See the License for more information.
11 ============================================================================*/
12 #ifndef cmCMakePolicyCommand_h
13 #define cmCMakePolicyCommand_h
15 #include "cmCommand.h"
17 /** \class cmCMakePolicyCommand
18 * \brief Set how CMake should handle policies
20 * cmCMakePolicyCommand sets how CMake should deal with backwards
21 * compatibility policies.
23 class cmCMakePolicyCommand : public cmCommand
27 * This is a virtual constructor for the command.
29 virtual cmCommand* Clone()
31 return new cmCMakePolicyCommand;
35 * This is called when the command is first encountered in
36 * the CMakeLists.txt file.
38 virtual bool InitialPass(std::vector<std::string> const& args,
39 cmExecutionStatus &status);
42 * This determines if the command is invoked when in script mode.
44 virtual bool IsScriptable() const { return true; }
47 * The name of the command as specified in CMakeList.txt.
49 virtual const char* GetName() const {return "cmake_policy";}
52 * Succinct documentation.
54 virtual const char* GetTerseDocumentation() const
56 return "Manage CMake Policy settings.";
62 virtual const char* GetFullDocumentation() const
65 "As CMake evolves it is sometimes necessary to change existing "
66 "behavior in order to fix bugs or improve implementations of "
68 "The CMake Policy mechanism is designed to help keep existing projects "
69 "building as new versions of CMake introduce changes in behavior. "
70 "Each new policy (behavioral change) is given an identifier of "
71 "the form \"CMP<NNNN>\" where \"<NNNN>\" is an integer index. "
72 "Documentation associated with each policy describes the OLD and NEW "
73 "behavior and the reason the policy was introduced. "
74 "Projects may set each policy to select the desired behavior. "
75 "When CMake needs to know which behavior to use it checks for "
76 "a setting specified by the project. "
77 "If no setting is available the OLD behavior is assumed and a warning "
78 "is produced requesting that the policy be set.\n"
79 "The cmake_policy command is used to set policies to OLD or NEW "
81 "While setting policies individually is supported, we encourage "
82 "projects to set policies based on CMake versions.\n"
83 " cmake_policy(VERSION major.minor[.patch[.tweak]])\n"
84 "Specify that the current CMake list file is written for the "
85 "given version of CMake. "
86 "All policies introduced in the specified version or earlier "
87 "will be set to use NEW behavior. "
88 "All policies introduced after the specified version will be unset "
89 "(unless variable CMAKE_POLICY_DEFAULT_CMP<NNNN> sets a default). "
90 "This effectively requests behavior preferred as of a given CMake "
91 "version and tells newer CMake versions to warn about their new "
93 "The policy version specified must be at least 2.4 or the command "
94 "will report an error. "
95 "In order to get compatibility features supporting versions earlier "
96 "than 2.4 see documentation of policy CMP0001."
98 " cmake_policy(SET CMP<NNNN> NEW)\n"
99 " cmake_policy(SET CMP<NNNN> OLD)\n"
100 "Tell CMake to use the OLD or NEW behavior for a given policy. "
101 "Projects depending on the old behavior of a given policy may "
102 "silence a policy warning by setting the policy state to OLD. "
103 "Alternatively one may fix the project to work with the new behavior "
104 "and set the policy state to NEW."
106 " cmake_policy(GET CMP<NNNN> <variable>)\n"
107 "Check whether a given policy is set to OLD or NEW behavior. "
108 "The output variable value will be \"OLD\" or \"NEW\" if the "
109 "policy is set, and empty otherwise."
111 "CMake keeps policy settings on a stack, so changes made by the "
112 "cmake_policy command affect only the top of the stack. "
113 "A new entry on the policy stack is managed automatically for each "
114 "subdirectory to protect its parents and siblings. "
115 "CMake also manages a new entry for scripts loaded by include() and "
116 "find_package() commands except when invoked with the NO_POLICY_SCOPE "
117 "option (see also policy CMP0011). "
118 "The cmake_policy command provides an interface to manage custom "
119 "entries on the policy stack:\n"
120 " cmake_policy(PUSH)\n"
121 " cmake_policy(POP)\n"
122 "Each PUSH must have a matching POP to erase any changes. "
123 "This is useful to make temporary changes to policy settings."
125 "Functions and macros record policy settings when they are created "
126 "and use the pre-record policies when they are invoked. "
127 "If the function or macro implementation sets policies, the changes "
128 "automatically propagate up through callers until they reach the "
129 "closest nested policy stack entry."
133 cmTypeMacro(cmCMakePolicyCommand, cmCommand);
135 bool HandleSetMode(std::vector<std::string> const& args);
136 bool HandleGetMode(std::vector<std::string> const& args);
137 bool HandleVersionMode(std::vector<std::string> const& args);