ENH: Clarify documentation of find_package command.

This commit is contained in:
Brad King 2008-01-17 20:59:57 -05:00
parent 9d57dbd098
commit 119e02631c
1 changed files with 20 additions and 8 deletions

View File

@ -125,13 +125,25 @@ cmFindPackageCommand::cmFindPackageCommand()
"a configuration file a fatal error is always generated because user " "a configuration file a fatal error is always generated because user "
"intervention is required." "intervention is required."
"\n" "\n"
"Config mode provides an elaborate interface and search procedure. "
"Much of the interface is provided for completeness and for use "
"internally by find-modules loaded by Module mode. "
"Most user code should simply call\n"
" find_package(<package> [REQUIRED|QUIET])\n"
"in order to find a package. Package maintainers providing CMake "
"package configuration files are encouraged to name and install "
"them such that the procedure outlined below will find them "
"without requiring use of additional options."
"\n"
"CMake constructs a set of possible installation prefixes for the " "CMake constructs a set of possible installation prefixes for the "
"package. Under each prefix the following directories are searched " "package. Under each prefix several directories are searched for a "
"for a configuration file:\n" "configuration file. The tables below show the directories searched. "
"Each entry is meant for installation trees following Windows (W), "
"UNIX (U), or Apple (A) conventions.\n"
" <prefix>/ (W)\n" " <prefix>/ (W)\n"
" <prefix>/(cmake|CMake)/ (W)\n" " <prefix>/(cmake|CMake)/ (W)\n"
" <prefix>/(share|lib)/<name>*/ (P)\n" " <prefix>/(share|lib)/<name>*/ (U)\n"
" <prefix>/(share|lib)/<name>*/(cmake|CMake)/ (P)\n" " <prefix>/(share|lib)/<name>*/(cmake|CMake)/ (U)\n"
"On systems supporting OS X Frameworks and Application Bundles " "On systems supporting OS X Frameworks and Application Bundles "
"the following directories are searched for frameworks or bundles " "the following directories are searched for frameworks or bundles "
"containing a configuration file:\n" "containing a configuration file:\n"
@ -144,14 +156,14 @@ cmFindPackageCommand::cmFindPackageCommand()
"In all cases the <name> is treated as case-insensitive and corresponds " "In all cases the <name> is treated as case-insensitive and corresponds "
"to any of the names specified (<package> or names given by NAMES). " "to any of the names specified (<package> or names given by NAMES). "
"If PATH_SUFFIXES is specified the suffixes are appended to each " "If PATH_SUFFIXES is specified the suffixes are appended to each "
"(W) or (P) directory entry one-by-one.\n" "(W) or (U) directory entry one-by-one.\n"
"This set of directories is intended to work in cooperation with " "This set of directories is intended to work in cooperation with "
"projects that provide configuration files in their installation trees. " "projects that provide configuration files in their installation trees. "
"Directories above marked with (W) are intended for installations on " "Directories above marked with (W) are intended for installations on "
"Windows where the prefix may point at the top of an application's " "Windows where the prefix may point at the top of an application's "
"installation directory. Those marked with (P) are intended for " "installation directory. Those marked with (U) are intended for "
"installations on POSIX platforms where the prefix is shared by " "installations on UNIX platforms where the prefix is shared by "
"multiple packages. This is merely a convention, so all (W) and (P) " "multiple packages. This is merely a convention, so all (W) and (U) "
"directories are still searched on all platforms. " "directories are still searched on all platforms. "
"Directories marked with (A) are intended for installations on " "Directories marked with (A) are intended for installations on "
"Apple platforms. The cmake variables CMAKE_FIND_FRAMEWORK and " "Apple platforms. The cmake variables CMAKE_FIND_FRAMEWORK and "