View Issue Details [ Jump to Notes ] [ Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0013142CMakeCMakepublic2012-04-17 22:122013-01-09 10:55
ReporterDave Abrahams 
Assigned ToBrad King 
PrioritynormalSeverityminorReproducibilityalways
StatusclosedResolutionfixed 
PlatformMacOSOS XOS Version10.7
Product VersionCMake 2.8.7 
Target VersionCMake 2.8.9Fixed in VersionCMake 2.8.9 
Summary0013142: Treatment of [components…] argument to find_package undocumented
DescriptionThere's no description of how components... is actually dealt with. In a project I'm working with, for example,

  find_package( Boost COMPONENTS date_time filesystem system ... )

works, yet it finds a file called BoostDateTimeConfig.cmake

How that can possibly work is lost on me. The docs for find_package /seem/ to indicate that it will only find BoostConfig.cmake... and it's hard to imagine the textual transformation from date_time to DateTime.
TagsNo tags attached.
Attached Files

 Relationships

  Notes
(0029206)
Brad King (manager)
2012-04-18 08:22

 The wording of find_package documentation is changing for 2.8.8 already:

 http://cmake.org/gitweb?p=cmake.git;a=blob;f=Source/cmFindPackageCommand.cxx;hb=d61d860d#l104 [^]

The key wording is

 "Available components and their influence on whether a package is considered to be found are defined by the target package."

IOW it is up to each package to deal with components in a way that makes sense for itself. The FindXYZ.cmake module for package XYZ should document what it does. To aid developers contributing such modules to CMake there is a Modules/readme.txt in the source tree:

 http://cmake.org/gitweb?p=cmake.git;a=blob;f=Modules/readme.txt;hb=d61d860d#l127 [^]
(0029207)
Brad King (manager)
2012-04-18 09:21

 Here is some new documentation:

 http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=6c12e820 [^]

Note that optional components and the possibility that a package configuration file can set <package>_FOUND to false are both new in CMake 2.8.8. Everything else has been around for a long time.
(0029209)
Dave Abrahams (reporter)
2012-04-18 09:24

 Thanks Brad, that's a big help. Is there a difference between a component listed after COMPONENTS (rather than REQUIRED), which we have in 2.8.7 and an "optional component?" If so, that isn't very clear from the docs you pointed at.
(0029210)
Brad King (manager)
2012-04-18 09:42

 Components listed after either REQUIRED or COMPONENTS are always required. Perhaps just a slight change in markup can clarify that without making the wording too verbose. How is this?

diff --git a/Source/cmFindPackageCommand.cxx b/Source/cmFindPackageCommand.cxx
index 0a055a2..4f9ba7e 100644
--- a/Source/cmFindPackageCommand.cxx
+++ b/Source/cmFindPackageCommand.cxx
@@ -89,7 +89,7 @@ void cmFindPackageCommand::GenerateDocumentation()
                                "FIND_XXX", "find_package");
   this->CommandDocumentation =
     "  find_package(<package> [version] [EXACT] [QUIET] [MODULE]\n"
-    "               [[REQUIRED|COMPONENTS] [components...]]\n"
+    "               [REQUIRED] [[COMPONENTS] [components...]]\n"
     "               [OPTIONAL_COMPONENTS components...]\n"
     "               [NO_POLICY_SCOPE])\n"
     "Finds and loads settings from an external project.  "
@@ -102,7 +102,7 @@ void cmFindPackageCommand::GenerateDocumentation()
     "package cannot be found."
     "\n"
     "A package-specific list of required components may be listed after the "
-    "COMPONENTS option or directly after the REQUIRED option.  "
+    "COMPONENTS option (or after the REQUIRED option if present).  "
     "Additional optional components may be listed after OPTIONAL_COMPONENTS.  "
     "Available components and their influence on whether a package is "
     "considered to be found are defined by the target package."
@@ -136,7 +136,7 @@ void cmFindPackageCommand::GenerateDocumentation()
     "proceeds to Config mode.\n"
     "The complete Config mode command signature is:\n"
     "  find_package(<package> [version] [EXACT] [QUIET]\n"
-    "               [[REQUIRED|COMPONENTS] [components...]]\n"
+    "               [REQUIRED] [[COMPONENTS] [components...]]\n"
     "               [CONFIG|NO_MODULE]\n"
     "               [NO_POLICY_SCOPE]\n"
     "               [NAMES name1 [name2 ...]]\n"
(0029214)
Dave Abrahams (reporter)
2012-04-18 11:43

 The new markup says something different from the old markup. Namely, that

   REQUIRED COMPONENTS foo

is allowed

Seems to me that maybe you should deprecate "REQUIRED" and "COMPONENTS" and add support for "REQUIRED_COMPONENTS", so the interface is symmetrical.
(0029215)
Brad King (manager)
2012-04-18 11:50

 REQUIRED has meaning on its own, in that the package itself is required and that find_package should abort if it is not found. It is allowed to have both REQUIRED and COMPONENTS. The old documentation was wrong.

Originally someone contributed the components feature with syntax

  find_package(... REQUIRED comp1 comp2 ...)

Later someone pointed out that components are useful even when the package is not required so we added

  find_package(... COMPONENTS comp1 comp2 ...)

Since then the command has always accepted

  find_package(... REQUIRED COMPONENTS comp1 comp2 ...)

too so the documentation was just wrong before. The patch in 0013142:0029210 fixes that.

As of CMake 2.8.7 all named components are required no matter which of the above forms is used. What is new in 2.8.8 is OPTIONAL_COMPONENTS.
(0029216)
Brad King (manager)
2012-04-18 11:53

 To clarify 0013142:0029215, the REQUIRED option existed prior to any component support and has the same meaning then and now. The "Originally someone contributed" sentence refers to the original contribution of components support which abused the REQUIRED option as a separator.
(0029244)
Brad King (manager)
2012-04-19 09:44

 Patch from 0013142:0029210 applied:

  http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=5ed93db4 [^]
(0029245)
Brad King (manager)
2012-04-19 09:45

 Resolving since the original issue has been resolved.
(0032023)
Robert Maynard (manager)
2013-01-09 10:55

 Closing resolved issues that have not been updated in more than 4 months.

 Issue History
Date Modified Username Field Change
2012-04-17 22:12 Dave Abrahams New Issue
2012-04-18 08:22 Brad King Note Added: 0029206
2012-04-18 08:56 Brad King Assigned To => Brad King
2012-04-18 08:56 Brad King Status new => assigned
2012-04-18 09:21 Brad King Note Added: 0029207
2012-04-18 09:24 Dave Abrahams Note Added: 0029209
2012-04-18 09:42 Brad King Note Added: 0029210
2012-04-18 11:43 Dave Abrahams Note Added: 0029214
2012-04-18 11:50 Brad King Note Added: 0029215
2012-04-18 11:53 Brad King Note Added: 0029216
2012-04-19 09:44 Brad King Note Added: 0029244
2012-04-19 09:45 Brad King Note Added: 0029245
2012-04-19 09:45 Brad King Status assigned => resolved
2012-04-19 09:45 Brad King Resolution open => fixed
2012-08-09 17:00 David Cole Fixed in Version => CMake 2.8.9
2012-08-09 17:00 David Cole Target Version => CMake 2.8.9
2013-01-09 10:55 Robert Maynard Note Added: 0032023
2013-01-09 10:55 Robert Maynard Status resolved => closed

Copyright © 2000 - 2018 MantisBT Team