From 1c0e1702c02ad769da93c9670bd29ee394eebfd7 Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 17 Mar 2008 20:30:47 -0400 Subject: [PATCH] ENH: Improve documentation of cmake_policy command. - Add a paragraph introducing the policy mechanism - Explicitly introduce the CMP, OLD, and NEW notation - Note that setting policies by CMake version is preferred - Fix SET signature to use CMP notation - Add more details about the policy stack --- Source/cmCMakePolicyCommand.h | 36 +++++++++++++++++++++++++++-------- 1 file changed, 28 insertions(+), 8 deletions(-) diff --git a/Source/cmCMakePolicyCommand.h b/Source/cmCMakePolicyCommand.h index 2e93ba7eb..54c494c66 100644 --- a/Source/cmCMakePolicyCommand.h +++ b/Source/cmCMakePolicyCommand.h @@ -58,7 +58,7 @@ public: */ virtual const char* GetTerseDocumentation() { - return "Manage CMake policy settings."; + return "Manage CMake Policy settings."; } /** @@ -67,13 +67,31 @@ public: virtual const char* GetFullDocumentation() { return + "As CMake evolves it is sometimes necessary to change existing " + "behavior in order to fix bugs or improve implementations of " + "existing features. " + "The CMake Policy mechanism is designed to help keep existing projects " + "building as new versions of CMake introduce changes in behavior. " + "Each new policy (behavioral change) is given an identifier of " + "the form \"CMP\" where \"\" is an integer index. " + "Documentation associated with each policy describes the OLD and NEW " + "behavior and the reason the policy was introduced. " + "Projects may set each policy to select the desired behavior. " + "When CMake needs to know which behavior to use it checks for " + "a setting specified by the project. " + "If no setting is available the OLD behavior is assumed and a warning " + "is produced requesting that the policy be set.\n" + "The cmake_policy command is used to set policies to OLD or NEW " + "behavior. " + "While setting policies individually is supported, we encourage " + "projects to set policies based on CMake versions.\n" " cmake_policy(VERSION major.minor[.patch])\n" "Specify that the current CMake list file is written for the " "given version of CMake. " "All policies introduced in the specified version or earlier " - "will be set NEW. " - "All policies introduced after the specified version will be set " - "to WARN, which is like OLD but also produces a warning. " + "will be set to use NEW behavior. " + "All policies introduced after the specified version will be reset " + "to use OLD behavior with a warning. " "This effectively requests behavior preferred as of a given CMake " "version and tells newer CMake versions to warn about their new " "policies. " @@ -82,8 +100,8 @@ public: "In order to get compatibility features supporting versions earlier " "than 2.4 see documentation of policy CMP0001." "\n" - " cmake_policy(SET NEW)\n" - " cmake_policy(SET OLD)\n" + " cmake_policy(SET CMP NEW)\n" + " cmake_policy(SET CMP OLD)\n" "Tell CMake to use the OLD or NEW behavior for a given policy. " "Projects depending on the old behavior of a given policy may " "silence a policy warning by setting the policy state to OLD. " @@ -96,8 +114,10 @@ public: "Each PUSH must have a matching POP. " "This is useful when mixing multiple projects, subprojects, and " "files included from external projects that may each have been " - "written for a different version of CMake." - ; + "written for a different version of CMake. " + "Each subdirectory entered by the project automatically pushes " + "a new level on the stack to isolate the subdirectories from " + "their parents."; } cmTypeMacro(cmCMakePolicyCommand, cmCommand);