ENH: Updated DEFINE_PROPERTY command to be more extendible and more consistent with new SET_PROPERTY and GET_PROPERTY signatures.

Modules/CTestTargets.cmake

@@ -37,10 +37,10 @@ ENDIF(CMAKE_CONFIGURATION_TYPES)
 
 # Add convenience targets.  Do this at most once in case of nested
 # projects.
-DEFINE_PROPERTY(CTEST_TARGETS_ADDED GLOBAL
+DEFINE_PROPERTY(GLOBAL PROPERTY CTEST_TARGETS_ADDED
-  "Internal property used by CTestTargets module."
+  BRIEF_DOCS "Internal property used by CTestTargets module."
-  "Set by the CTestTargets module to track addition of testing targets."
+  FULL_DOCS "Set by the CTestTargets module to track addition of testing targets."
-  FALSE)
+  )
 GET_PROPERTY(_CTEST_TARGETS_ADDED GLOBAL PROPERTY CTEST_TARGETS_ADDED)
 IF(NOT _CTEST_TARGETS_ADDED)
   SET_PROPERTY(GLOBAL PROPERTY CTEST_TARGETS_ADDED 1)

Source/cmDefinePropertyCommand.cxx

@@ -21,51 +21,123 @@
 bool cmDefinePropertyCommand
 ::InitialPass(std::vector<std::string> const& args, cmExecutionStatus &)
 {
-  if(args.size() < 5 )
+  if(args.size() < 1)
     {
     this->SetError("called with incorrect number of arguments");
     return false;
     }
 
-  // determine the scope
+  // Get the scope in which to define the property.
   cmProperty::ScopeType scope;
-  if (args[1] == "GLOBAL")
+  if(args[0] == "GLOBAL")
     {
     scope = cmProperty::GLOBAL;
     }
-  else if (args[1] == "DIRECTORY")
+  else if(args[0] == "DIRECTORY")
     {
     scope = cmProperty::DIRECTORY;
     }
-  else if (args[1] == "TARGET")
+  else if(args[0] == "TARGET")
     {
     scope = cmProperty::TARGET;
     }
-  else if (args[1] == "SOURCE_FILE")
+  else if(args[0] == "SOURCE")
     {
     scope = cmProperty::SOURCE_FILE;
     }
-  else if (args[1] == "TEST")
+  else if(args[0] == "TEST")
     {
     scope = cmProperty::TEST;
     }
-  else if (args[1] == "VARIABLE")
+  else if(args[0] == "VARIABLE")
     {
     scope = cmProperty::VARIABLE;
     }
-  else if (args[1] == "CACHED_VARIABLE")
+  else if (args[0] == "CACHED_VARIABLE")
     {
     scope = cmProperty::CACHED_VARIABLE;
     }
   else
     {
-    this->SetError("called with illegal arguments.");
+    cmOStringStream e;
+    e << "given invalid scope " << args[0] << ".  "
+      << "Valid scopes are "
+      << "GLOBAL, DIRECTORY, TARGET, SOURCE, "
+      << "TEST, VARIABLE, CACHED_VARIABLE.";
+    this->SetError(e.str().c_str());
     return false;
     }
 
+  // Parse remaining arguments.
+  bool inherited = false;
+  enum Doing { DoingNone, DoingProperty, DoingBrief, DoingFull };
+  Doing doing = DoingNone;
+  for(unsigned int i=1; i < args.size(); ++i)
+    {
+    if(args[i] == "PROPERTY")
+      {
+      doing = DoingProperty;
+      }
+    else if(args[i] == "BRIEF_DOCS")
+      {
+      doing = DoingBrief;
+      }
+    else if(args[i] == "FULL_DOCS")
+      {
+      doing = DoingFull;
+      }
+    else if(args[i] == "INHERITED")
+      {
+      doing = DoingNone;
+      inherited = true;
+      }
+    else if(doing == DoingProperty)
+      {
+      doing = DoingNone;
+      this->PropertyName = args[i];
+      }
+    else if(doing == DoingBrief)
+      {
+      doing = DoingNone;
+      this->BriefDocs = args[i];
+      }
+    else if(doing == DoingFull)
+      {
+      doing = DoingNone;
+      this->FullDocs = args[i];
+      }
+    else
+      {
+      cmOStringStream e;
+      e << "given invalid argument \"" << args[i] << "\".";
+      this->SetError(e.str().c_str());
+      return false;
+      }
+    }
+
+  // Make sure a property name was found.
+  if(this->PropertyName.empty())
+    {
+    this->SetError("not given a PROPERTY <name> argument.");
+    return false;
+    }
+
+  // Make sure documentation was given.
+  if(this->BriefDocs.empty())
+    {
+    this->SetError("not given a BRIEF_DOCS <brief-doc> argument.");
+    return false;
+    }
+  if(this->FullDocs.empty())
+    {
+    this->SetError("not given a FULL_DOCS <full-doc> argument.");
+    return false;
+    }
+
+  // Actually define the property.
   this->Makefile->GetCMakeInstance()->DefineProperty
-    (args[0].c_str(), scope,args[2].c_str(), args[3].c_str(),
+    (this->PropertyName.c_str(), scope,
-     cmSystemTools::IsOn(args[4].c_str()));
+     this->BriefDocs.c_str(), this->FullDocs.c_str(), inherited);
 
   return true;
 }

Source/cmDefinePropertyCommand.h

@@ -44,7 +44,7 @@ public:
    */
   virtual const char* GetTerseDocumentation() 
     {
-    return "Define properties used by CMake.";
+    return "Define and document custom properties.";
     }
   
   /**
@@ -53,21 +53,44 @@ public:
   virtual const char* GetFullDocumentation()
     {
       return
-        "  define_property(property_name scope_value\n"
+        "  define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |\n"
-        "                  short_description\n"
+        "                   TEST | VARIABLE | CACHED_VARIABLE>\n"
-        "                  full_description inherit)\n"
+        "                   PROPERTY <name> [INHERITED]\n"
-        "Define a property for a scope. scope_value is either GLOBAL, "
+        "                   BRIEF_DOCS <brief-doc>\n"
-        "DIRECTORY, TARGET, TEST, SOURCE_FILE, VARIABLE or CACHED_VARIABLE. "
+        "                   FULL_DOCS <full-doc>)\n"
-        "The short and full descriptions are used to document the property. "
+        "Define one property in a scope for use with the "
-        "If inherit is TRUE, it will inherit its value from the next more "
+        "set_property and get_property commands.  "
-        "global property if it hasn't been set at the specified scope. "
+        "This is primarily useful to associate documentation with property "
-        "This means that e.g. a TARGET property inherits it's value from the "
+        "names that may be retrieved with the get_property command.  "
-        "DIRECTORY property with the same name if it hasn't been set for the "
+        "The first argument determines the kind of scope in which the "
-        "target, and then from GLOBAL if it hasn't been set for the directory."
+        "property should be used.  It must be one of the following:\n"
-        ;
+        "  GLOBAL    = associated with the global namespace\n"
+        "  DIRECTORY = associated with one directory\n"
+        "  TARGET    = associated with one target\n"
+        "  SOURCE    = associated with one source file\n"
+        "  TEST      = associated with a test named with add_test command\n"
+        "  VARIABLE  = documents a CMake language variable\n"
+        "  CACHED_VARIABLE = documents a CMake cache variable\n"
+        "Note that unlike set_property and get_property no actual scope "
+        "needs to be given; only the kind of scope is important.\n"
+        "The required PROPERTY option is immediately followed by the name "
+        "of the property being defined.\n"
+        "If the INHERITED option then the get_property command will chain "
+        "up to the next higher scope when the requested property is not "
+        "set in the scope given to the command.  "
+        "DIRECTORY scope chains to GLOBAL.  "
+        "TARGET, SOURCE, and TEST chain to DIRECTORY.\n"
+        "The BRIEF_DOCS and FULL_DOCS options are followed by strings to be "
+        "associated with the property as its brief and full documentation.  "
+        "Corresponding options to the get_property command will retrieve the "
+        "documentation.";
     }
   
   cmTypeMacro(cmDefinePropertyCommand, cmCommand);
+private:
+  std::string PropertyName;
+  std::string BriefDocs;
+  std::string FullDocs;
 };
 
 

Tests/Complex/Library/CMakeLists.txt

@@ -46,8 +46,11 @@ ADD_LIBRARY(CMakeTestLibraryShared SHARED ${SharedLibrarySources})
 ADD_LIBRARY(CMakeTestModule MODULE moduleFile.c)
 SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -DTEST_C_FLAGS")
 ADD_LIBRARY(CMakeTestCLibraryShared SHARED testConly.c)
-DEFINE_PROPERTY(FOO TARGET "a test property"
+DEFINE_PROPERTY(
-  "A simple etst proerty that means nothign and is used for nothing" 0)
+  TARGET PROPERTY FOO
+  BRIEF_DOCS "a test property"
+  FULL_DOCS "A simple etst proerty that means nothign and is used for nothing"
+  )
 SET_TARGET_PROPERTIES(CMakeTestCLibraryShared PROPERTIES FOO BAR)
 IF(NOT BEOS)  # No libm on BeOS.
   SET_TARGET_PROPERTIES(CMakeTestCLibraryShared PROPERTIES LINK_FLAGS "-lm")

Tests/ComplexOneConfig/Library/CMakeLists.txt

@@ -46,8 +46,11 @@ ADD_LIBRARY(CMakeTestLibraryShared SHARED ${SharedLibrarySources})
 ADD_LIBRARY(CMakeTestModule MODULE moduleFile.c)
 SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -DTEST_C_FLAGS")
 ADD_LIBRARY(CMakeTestCLibraryShared SHARED testConly.c)
-DEFINE_PROPERTY(FOO TARGET "a test property"
+DEFINE_PROPERTY(
-  "A simple etst proerty that means nothign and is used for nothing" 0)
+  TARGET PROPERTY FOO
+  BRIEF_DOCS "a test property"
+  FULL_DOCS "A simple etst proerty that means nothign and is used for nothing"
+  )
 SET_TARGET_PROPERTIES(CMakeTestCLibraryShared PROPERTIES FOO BAR)
 IF(NOT BEOS)  # No libm on BeOS.
   SET_TARGET_PROPERTIES(CMakeTestCLibraryShared PROPERTIES LINK_FLAGS "-lm")

Tests/ComplexRelativePaths/Library/CMakeLists.txt

@@ -46,8 +46,11 @@ ADD_LIBRARY(CMakeTestLibraryShared SHARED ${SharedLibrarySources})
 ADD_LIBRARY(CMakeTestModule MODULE moduleFile.c)
 SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -DTEST_C_FLAGS")
 ADD_LIBRARY(CMakeTestCLibraryShared SHARED testConly.c)
-DEFINE_PROPERTY(FOO TARGET "a test property"
+DEFINE_PROPERTY(
-  "A simple etst proerty that means nothign and is used for nothing" 0)
+  TARGET PROPERTY FOO
+  BRIEF_DOCS "a test property"
+  FULL_DOCS "A simple etst proerty that means nothign and is used for nothing"
+  )
 SET_TARGET_PROPERTIES(CMakeTestCLibraryShared PROPERTIES FOO BAR)
 IF(NOT BEOS)  # No libm on BeOS.
   SET_TARGET_PROPERTIES(CMakeTestCLibraryShared PROPERTIES LINK_FLAGS "-lm")

Tests/Properties/CMakeLists.txt

@@ -22,8 +22,10 @@ include_directories("${Properties_SOURCE_DIR}" "${Properties_BINARY_DIR}")
 
 
 # test generic property interfaces
-define_property(GLOBALTEST GLOBAL "A test property" 
+define_property(GLOBAL PROPERTY GLOBALTEST
-  "A long description of this test property" 0)
+  BRIEF_DOCS "A test property"
+  FULL_DOCS "A long description of this test property"
+  )
 set_property(GLOBAL PROPERTY GLOBALTEST 1)
 set_property(DIRECTORY PROPERTY DIRECTORYTEST 1)
 set_property(SOURCE SubDir/properties3.cxx PROPERTY SOURCETEST 1)