[Cmake-commits] [cmake-commits] king committed cmCMakePolicyCommand.h 1.4 1.5

[cmake-commits at cmake.org]

Update of /cvsroot/CMake/CMake/Source
In directory public:/mounts/ram/cvs-serv14638/Source

Modified Files:
	cmCMakePolicyCommand.h 
Log Message:
ENH: Improve documentation of cmake_policy command.

  - Add a paragraph introducing the policy mechanism
  - Explicitly introduce the CMP<NNNN>, OLD, and NEW notation
  - Note that setting policies by CMake version is preferred
  - Fix SET signature to use CMP<NNNN> notation
  - Add more details about the policy stack


Index: cmCMakePolicyCommand.h
===================================================================
RCS file: /cvsroot/CMake/CMake/Source/cmCMakePolicyCommand.h,v
retrieving revision 1.4
retrieving revision 1.5
diff -C 2 -d -r1.4 -r1.5
*** cmCMakePolicyCommand.h	13 Mar 2008 15:38:46 -0000	1.4
--- cmCMakePolicyCommand.h	18 Mar 2008 00:30:47 -0000	1.5
***************
*** 59,63 ****
    virtual const char* GetTerseDocumentation() 
      {
!     return "Manage CMake policy settings.";
      }
    
--- 59,63 ----
    virtual const char* GetTerseDocumentation() 
      {
!     return "Manage CMake Policy settings.";
      }
    
***************
*** 68,78 ****
      {
      return
        "  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.  "
        "This effectively requests behavior preferred as of a given CMake "
        "version and tells newer CMake versions to warn about their new "
--- 68,96 ----
      {
      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<NNNN>\" where \"<NNNN>\" 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 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 "
***************
*** 83,88 ****
        "than 2.4 see documentation of policy CMP0001."
        "\n"
!       "  cmake_policy(SET <CMPNNNN> NEW)\n"
!       "  cmake_policy(SET <CMPNNNN> 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 "
--- 101,106 ----
        "than 2.4 see documentation of policy CMP0001."
        "\n"
!       "  cmake_policy(SET CMP<NNNN> NEW)\n"
!       "  cmake_policy(SET CMP<NNNN> 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 "
***************
*** 97,102 ****
        "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."
!       ;
      }
    
--- 115,122 ----
        "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.  "
!       "Each subdirectory entered by the project automatically pushes "
!       "a new level on the stack to isolate the subdirectories from "
!       "their parents.";
      }