Source/cmCMakePolicyCommand.h

   1 /*============================================================================
   2   CMake - Cross Platform Makefile Generator
   3   Copyright 2000-2009 Kitware, Inc., Insight Software Consortium
   4
   5   Distributed under the OSI-approved BSD License (the "License");
   6   see accompanying file Copyright.txt for details.
   7
   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
  14
  15 #include "cmCommand.h"
  16
  17 /** \class cmCMakePolicyCommand
  18  * \brief Set how CMake should handle policies
  19  *
  20  * cmCMakePolicyCommand sets how CMake should deal with backwards
  21  * compatibility policies.
  22  */
  23 class cmCMakePolicyCommand : public cmCommand
  24 {
  25 public:
  26   /**
  27    * This is a virtual constructor for the command.
  28    */
  29   virtual cmCommand* Clone()
  30     {
  31     return new cmCMakePolicyCommand;
  32     }
  33
  34   /**
  35    * This is called when the command is first encountered in
  36    * the CMakeLists.txt file.
  37    */
  38   virtual bool InitialPass(std::vector<std::string> const& args,
  39                            cmExecutionStatus &status);
  40
  41  /**
  42    * This determines if the command is invoked when in script mode.
  43    */
  44   virtual bool IsScriptable() const { return true; }
  45
  46  /**
  47    * The name of the command as specified in CMakeList.txt.
  48    */
  49   virtual const char* GetName() const {return "cmake_policy";}
  50
  51  /**
  52    * Succinct documentation.
  53    */
  54   virtual const char* GetTerseDocumentation() const
  55     {
  56     return "Manage CMake Policy settings.";
  57     }
  58
  59   /**
  60    * More documentation.
  61    */
  62   virtual const char* GetFullDocumentation() const
  63     {
  64     return
  65       "As CMake evolves it is sometimes necessary to change existing "
  66       "behavior in order to fix bugs or improve implementations of "
  67       "existing features.  "
  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 "
  80       "behavior.  "
  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 "
  92       "policies.  "
  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."
  97       "\n"
  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."
 105       "\n"
 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."
 110       "\n"
 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."
 124       "\n"
 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."
 130       ;
 131     }
 132
 133   cmTypeMacro(cmCMakePolicyCommand, cmCommand);
 134 private:
 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);
 138 };
 139
 140
 141
 142 #endif