Commit 480d733d authored by Brad King's avatar Brad King
Browse files

ENH: Updated find_package documentation to describe common usage first.

parent 2b48e716
...@@ -68,6 +68,38 @@ cmFindPackageCommand::cmFindPackageCommand() ...@@ -68,6 +68,38 @@ cmFindPackageCommand::cmFindPackageCommand()
this->VersionPatch = 0; this->VersionPatch = 0;
this->VersionCount = 0; this->VersionCount = 0;
this->CommandDocumentation = this->CommandDocumentation =
" find_package(<package> [major[.minor[.patch]]] [QUIET]\n"
" [[REQUIRED|COMPONENTS] [components...]])\n"
"Finds and loads settings from an external project. "
"<package>_FOUND will be set to indicate whether the package was found. "
"When the package is found package-specific information is provided "
"through variables documented by the package itself. "
"The QUIET option disables messages if the package cannot be found. "
"The REQUIRED option stops processing with an error message if the "
"package cannot be found. "
"A package-specific list of components may be listed after the "
"REQUIRED option or after the COMPONENTS option if no REQUIRED "
"option is given. "
"The \"[major[.minor[.patch]]]\" version argument specifies a desired "
"version with which the package found should be compatible. "
"Version support is currently provided only on a package-by-package "
"basis and is not enforced by the command.\n"
"User code should generally look for packages using the above simple "
"signature. The remainder of this command documentation specifies the "
"full command signature and details of the search process. Project "
"maintainers wishing to provide a package to be found by this command "
"are encouraged to read on.\n"
"The command has two modes by which it searches for packages: "
"\"Module\" mode and \"Config\" mode. "
"Module mode is available when the command is invoked with the above "
"reduced signature. "
"CMake searches for a file called \"Find<package>.cmake\" in "
"the CMAKE_MODULE_PATH followed by the CMake installation. "
"If the file is found, it is read and processed by CMake. "
"It is responsible for finding the package or producing an error message "
"if package content cannot be found. "
"Otherwise the command proceeds to Config mode.\n"
"The complete Config mode command signature is:\n"
" find_package(<package> [major[.minor[.patch]]] [QUIET] [NO_MODULE]\n" " find_package(<package> [major[.minor[.patch]]] [QUIET] [NO_MODULE]\n"
" [[REQUIRED|COMPONENTS] [components...]]\n" " [[REQUIRED|COMPONENTS] [components...]]\n"
" [NAMES name1 [name2 ...]]\n" " [NAMES name1 [name2 ...]]\n"
...@@ -83,29 +115,9 @@ cmFindPackageCommand::cmFindPackageCommand() ...@@ -83,29 +115,9 @@ cmFindPackageCommand::cmFindPackageCommand()
" [CMAKE_FIND_ROOT_PATH_BOTH |\n" " [CMAKE_FIND_ROOT_PATH_BOTH |\n"
" ONLY_CMAKE_FIND_ROOT_PATH |\n" " ONLY_CMAKE_FIND_ROOT_PATH |\n"
" NO_CMAKE_FIND_ROOT_PATH])\n" " NO_CMAKE_FIND_ROOT_PATH])\n"
"Finds and loads settings from an external project. <package>_FOUND " "The NO_MODULE option may be used to skip Module mode explicitly. "
"will be set to indicate whether the package was found. Settings that " "It is also implied by use of options not specified in the reduced "
"can be used when <package>_FOUND is true are package-specific. " "signature. "
"A package-specific list of components may be listed after the "
"REQUIRED option, or after the COMPONENTS option if no REQUIRED "
"option is given. The \"[major[.minor[.patch]]]\" version argument "
"specifies a desired version with which the package found should be "
"compatible. Version support is currently provided only on a "
"package-by-package basis and is not enforced by the command. "
"The command has two modes by which it searches for packages: "
"\"Module\" mode and \"Config\" mode."
"\n"
"Module mode has a reduced signature:\n"
" find_package(<package> [major[.minor[.patch]]] [QUIET]\n"
" [[REQUIRED|COMPONENTS] [components...]])\n"
"CMake searches for a file called \"Find<package>.cmake\" in "
"the CMAKE_MODULE_PATH followed by the CMake installation. "
"If the file is found, it is read and processed by CMake. "
"It is responsible for finding the package "
"or producing an error message if package content cannot be found. "
"Otherwise the command proceeds to Config mode. The NO_MODULE "
"option may be used to skip Module mode explicitly, but the option "
"is implied by use of options not specified in the reduced signature."
"\n" "\n"
"Config mode attempts to locate a configuration file provided by the " "Config mode attempts to locate a configuration file provided by the "
"package to be found. A cache entry called <package>_DIR is created to " "package to be found. A cache entry called <package>_DIR is created to "
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment