diff options
| -rw-r--r-- | Help/command/FIND_XXX.txt | 101 | ||||
| -rw-r--r-- | Help/command/FIND_XXX_MAC.txt | 24 | ||||
| -rw-r--r-- | Help/command/FIND_XXX_ORDER.txt | 12 | ||||
| -rw-r--r-- | Help/command/FIND_XXX_ROOT.txt | 14 | ||||
| -rw-r--r-- | Help/command/find_file.rst | 161 | ||||
| -rw-r--r-- | Help/command/find_library.rst | 161 | ||||
| -rw-r--r-- | Help/command/find_package.rst | 60 | ||||
| -rw-r--r-- | Help/command/find_path.rst | 162 | ||||
| -rw-r--r-- | Help/command/find_program.rst | 160 |
9 files changed, 227 insertions, 628 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt new file mode 100644 index 0000000..5889e90 --- /dev/null +++ b/Help/command/FIND_XXX.txt @@ -0,0 +1,101 @@ +A short-hand signature is: + +.. parsed-literal:: + + |FIND_XXX| (<VAR> name1 [path1 path2 ...]) + +The general signature is: + +.. parsed-literal:: + + |FIND_XXX| ( + <VAR> + name | |NAMES| + [HINTS path1 [path2 ... ENV var]] + [PATHS path1 [path2 ... ENV var]] + [PATH_SUFFIXES suffix1 [suffix2 ...]] + [DOC "cache documentation string"] + [NO_DEFAULT_PATH] + [NO_CMAKE_ENVIRONMENT_PATH] + [NO_CMAKE_PATH] + [NO_SYSTEM_ENVIRONMENT_PATH] + [NO_CMAKE_SYSTEM_PATH] + [CMAKE_FIND_ROOT_PATH_BOTH | + ONLY_CMAKE_FIND_ROOT_PATH | + NO_CMAKE_FIND_ROOT_PATH] + ) + +This command is used to find a |SEARCH_XXX_DESC|. +A cache entry named by ``<VAR>`` is created to store the result +of this command. +If the |SEARCH_XXX| is found the result is stored in the variable +and the search will not be repeated unless the variable is cleared. +If nothing is found, the result will be +``<VAR>-NOTFOUND``, and the search will be attempted again the +next time |FIND_XXX| is invoked with the same variable. +The name of the |SEARCH_XXX| that +is searched for is specified by the names listed +after the NAMES argument. Additional search locations +can be specified after the PATHS argument. If ENV var is +found in the HINTS or PATHS section the environment variable var +will be read and converted from a system environment variable to +a cmake style list of paths. For example ENV PATH would be a way +to list the system path variable. The argument +after DOC will be used for the documentation string in +the cache. +PATH_SUFFIXES specifies additional subdirectories to check below +each search path. + +If NO_DEFAULT_PATH is specified, then no additional paths are +added to the search. +If NO_DEFAULT_PATH is not specified, the search process is as follows: + +.. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace:: + <prefix>/|XXX_SUBDIR| for each <prefix> in CMAKE_PREFIX_PATH + +.. |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| replace:: + <prefix>/|XXX_SUBDIR| for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH + +1. Search paths specified in cmake-specific cache variables. + These are intended to be used on the command line with a -DVAR=value. + This can be skipped if NO_CMAKE_PATH is passed. + + * |CMAKE_PREFIX_PATH_XXX| + * |CMAKE_XXX_PATH| + * |CMAKE_XXX_MAC_PATH| + +2. Search paths specified in cmake-specific environment variables. + These are intended to be set in the user's shell configuration. + This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed. + + * |CMAKE_PREFIX_PATH_XXX| + * |CMAKE_XXX_PATH| + * |CMAKE_XXX_MAC_PATH| + +3. Search the paths specified by the HINTS option. + These should be paths computed by system introspection, such as a + hint provided by the location of another item already found. + Hard-coded guesses should be specified with the PATHS option. + +4. Search the standard system environment variables. + This can be skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument. + + * |SYSTEM_ENVIRONMENT_PATH_XXX| + +5. Search cmake variables defined in the Platform files + for the current system. This can be skipped if NO_CMAKE_SYSTEM_PATH + is passed. + + * |CMAKE_SYSTEM_PREFIX_PATH_XXX| + * |CMAKE_SYSTEM_XXX_PATH| + * |CMAKE_SYSTEM_XXX_MAC_PATH| + +6. Search the paths specified by the PATHS option + or in the short-hand version of the command. + These are typically hard-coded guesses. + +.. |FIND_ARGS_XXX| replace:: <VAR> NAMES name + +.. include:: FIND_XXX_MAC.txt +.. include:: FIND_XXX_ROOT.txt +.. include:: FIND_XXX_ORDER.txt diff --git a/Help/command/FIND_XXX_MAC.txt b/Help/command/FIND_XXX_MAC.txt new file mode 100644 index 0000000..eb3900c --- /dev/null +++ b/Help/command/FIND_XXX_MAC.txt @@ -0,0 +1,24 @@ +On Darwin or systems supporting OS X Frameworks, the cmake variable +CMAKE_FIND_FRAMEWORK can be set to empty or one of the following: + +* FIRST: Try to find frameworks before standard libraries or headers. + This is the default on Darwin. + +* LAST: Try to find frameworks after standard libraries or headers. + +* ONLY: Only try to find frameworks. + +* NEVER: Never try to find frameworks. + +On Darwin or systems supporting OS X Application Bundles, the cmake +variable CMAKE_FIND_APPBUNDLE can be set to empty or one of the +following: + +* FIRST: Try to find application bundles before standard programs. + This is the default on Darwin. + +* LAST: Try to find application bundles after standard programs. + +* ONLY: Only try to find application bundles. + +* NEVER: Never try to find application bundles. diff --git a/Help/command/FIND_XXX_ORDER.txt b/Help/command/FIND_XXX_ORDER.txt new file mode 100644 index 0000000..bac2419 --- /dev/null +++ b/Help/command/FIND_XXX_ORDER.txt @@ -0,0 +1,12 @@ +The default search order is designed to be most-specific to +least-specific for common use cases. +Projects may override the order by simply calling the command +multiple times and using the ``NO_*`` options: + +.. parsed-literal:: + + |FIND_XXX| (|FIND_ARGS_XXX| PATHS paths... NO_DEFAULT_PATH) + |FIND_XXX| (|FIND_ARGS_XXX|) + +Once one of the calls succeeds the result variable will be set +and stored in the cache so that no call will search again. diff --git a/Help/command/FIND_XXX_ROOT.txt b/Help/command/FIND_XXX_ROOT.txt new file mode 100644 index 0000000..407375a --- /dev/null +++ b/Help/command/FIND_XXX_ROOT.txt @@ -0,0 +1,14 @@ +The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more +directories to be prepended to all other search directories. This +effectively "re-roots" the entire search under given locations. By +default it is empty. It is especially useful when cross-compiling to +point to the root directory of the target environment and CMake will +search there too. By default at first the directories listed in +CMAKE_FIND_ROOT_PATH and then the non-rooted directories will be +searched. The default behavior can be adjusted by setting +|CMAKE_FIND_ROOT_PATH_MODE_XXX|. This behavior can be manually +overridden on a per-call basis. By using CMAKE_FIND_ROOT_PATH_BOTH +the search order will be as described above. If +NO_CMAKE_FIND_ROOT_PATH is used then CMAKE_FIND_ROOT_PATH will not be +used. If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted +directories will be searched. diff --git a/Help/command/find_file.rst b/Help/command/find_file.rst index c5956f8..549b317 100644 --- a/Help/command/find_file.rst +++ b/Help/command/find_file.rst @@ -1,154 +1,27 @@ find_file --------- -Find the full path to a file. - -:: - - find_file(<VAR> name1 [path1 path2 ...]) - -This is the short-hand signature for the command that is sufficient in -many cases. It is the same as find_file(<VAR> name1 [PATHS path1 -path2 ...]) - -:: - - find_file( - <VAR> - name | NAMES name1 [name2 ...] - [HINTS path1 [path2 ... ENV var]] - [PATHS path1 [path2 ... ENV var]] - [PATH_SUFFIXES suffix1 [suffix2 ...]] - [DOC "cache documentation string"] - [NO_DEFAULT_PATH] - [NO_CMAKE_ENVIRONMENT_PATH] - [NO_CMAKE_PATH] - [NO_SYSTEM_ENVIRONMENT_PATH] - [NO_CMAKE_SYSTEM_PATH] - [CMAKE_FIND_ROOT_PATH_BOTH | - ONLY_CMAKE_FIND_ROOT_PATH | - NO_CMAKE_FIND_ROOT_PATH] - ) - -This command is used to find a full path to named file. A cache entry -named by <VAR> is created to store the result of this command. If the -full path to a file is found the result is stored in the variable and -the search will not be repeated unless the variable is cleared. If -nothing is found, the result will be <VAR>-NOTFOUND, and the search -will be attempted again the next time find_file is invoked with the -same variable. The name of the full path to a file that is searched -for is specified by the names listed after the NAMES argument. -Additional search locations can be specified after the PATHS argument. -If ENV var is found in the HINTS or PATHS section the environment -variable var will be read and converted from a system environment -variable to a cmake style list of paths. For example ENV PATH would -be a way to list the system path variable. The argument after DOC -will be used for the documentation string in the cache. PATH_SUFFIXES -specifies additional subdirectories to check below each search path. - -If NO_DEFAULT_PATH is specified, then no additional paths are added to -the search. If NO_DEFAULT_PATH is not specified, the search process -is as follows: - -1. Search paths specified in cmake-specific cache variables. These -are intended to be used on the command line with a -DVAR=value. This -can be skipped if NO_CMAKE_PATH is passed. - -:: +.. |FIND_XXX| replace:: find_file +.. |NAMES| replace:: NAMES name1 [name2 ...] +.. |SEARCH_XXX| replace:: full path to a file +.. |SEARCH_XXX_DESC| replace:: full path to named file +.. |XXX_SUBDIR| replace:: include +.. |CMAKE_PREFIX_PATH_XXX| replace:: <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and - <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH - CMAKE_INCLUDE_PATH - CMAKE_FRAMEWORK_PATH - -2. Search paths specified in cmake-specific environment variables. -These are intended to be set in the user's shell configuration. This -can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed. - -:: - - <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and - <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH - CMAKE_INCLUDE_PATH - CMAKE_FRAMEWORK_PATH - -3. Search the paths specified by the HINTS option. These should be -paths computed by system introspection, such as a hint provided by the -location of another item already found. Hard-coded guesses should be -specified with the PATHS option. + |CMAKE_PREFIX_PATH_XXX_SUBDIR| +.. |CMAKE_XXX_PATH| replace:: CMAKE_INCLUDE_PATH +.. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_FRAMEWORK_PATH -4. Search the standard system environment variables. This can be -skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument. - -:: - - PATH - INCLUDE - -5. Search cmake variables defined in the Platform files for the -current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is -passed. - -:: +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: PATH and INCLUDE +.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and - <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH - CMAKE_SYSTEM_INCLUDE_PATH - CMAKE_SYSTEM_FRAMEWORK_PATH - -6. Search the paths specified by the PATHS option or in the -short-hand version of the command. These are typically hard-coded -guesses. - -On Darwin or systems supporting OS X Frameworks, the cmake variable -CMAKE_FIND_FRAMEWORK can be set to empty or one of the following: - -:: - - "FIRST" - Try to find frameworks before standard - libraries or headers. This is the default on Darwin. - "LAST" - Try to find frameworks after standard - libraries or headers. - "ONLY" - Only try to find frameworks. - "NEVER" - Never try to find frameworks. - -On Darwin or systems supporting OS X Application Bundles, the cmake -variable CMAKE_FIND_APPBUNDLE can be set to empty or one of the -following: - -:: - - "FIRST" - Try to find application bundles before standard - programs. This is the default on Darwin. - "LAST" - Try to find application bundles after standard - programs. - "ONLY" - Only try to find application bundles. - "NEVER" - Never try to find application bundles. - -The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more -directories to be prepended to all other search directories. This -effectively "re-roots" the entire search under given locations. By -default it is empty. It is especially useful when cross-compiling to -point to the root directory of the target environment and CMake will -search there too. By default at first the directories listed in -CMAKE_FIND_ROOT_PATH and then the non-rooted directories will be -searched. The default behavior can be adjusted by setting -CMAKE_FIND_ROOT_PATH_MODE_INCLUDE. This behavior can be manually -overridden on a per-call basis. By using CMAKE_FIND_ROOT_PATH_BOTH -the search order will be as described above. If -NO_CMAKE_FIND_ROOT_PATH is used then CMAKE_FIND_ROOT_PATH will not be -used. If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted -directories will be searched. - -The default search order is designed to be most-specific to -least-specific for common use cases. Projects may override the order -by simply calling the command multiple times and using the NO_* -options: - -:: + |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| +.. |CMAKE_SYSTEM_XXX_PATH| replace:: CMAKE_SYSTEM_INCLUDE_PATH +.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_FRAMEWORK_PATH - find_file(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH) - find_file(<VAR> NAMES name) +.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: + CMAKE_FIND_ROOT_PATH_MODE_INCLUDE -Once one of the calls succeeds the result variable will be set and -stored in the cache so that no call will search again. +.. include:: FIND_XXX.txt diff --git a/Help/command/find_library.rst b/Help/command/find_library.rst index 39ec4af..8598be7 100644 --- a/Help/command/find_library.rst +++ b/Help/command/find_library.rst @@ -1,157 +1,30 @@ find_library ------------ -Find a library. - -:: - - find_library(<VAR> name1 [path1 path2 ...]) - -This is the short-hand signature for the command that is sufficient in -many cases. It is the same as find_library(<VAR> name1 [PATHS path1 -path2 ...]) - -:: - - find_library( - <VAR> - name | NAMES name1 [name2 ...] [NAMES_PER_DIR] - [HINTS path1 [path2 ... ENV var]] - [PATHS path1 [path2 ... ENV var]] - [PATH_SUFFIXES suffix1 [suffix2 ...]] - [DOC "cache documentation string"] - [NO_DEFAULT_PATH] - [NO_CMAKE_ENVIRONMENT_PATH] - [NO_CMAKE_PATH] - [NO_SYSTEM_ENVIRONMENT_PATH] - [NO_CMAKE_SYSTEM_PATH] - [CMAKE_FIND_ROOT_PATH_BOTH | - ONLY_CMAKE_FIND_ROOT_PATH | - NO_CMAKE_FIND_ROOT_PATH] - ) - -This command is used to find a library. A cache entry named by <VAR> -is created to store the result of this command. If the library is -found the result is stored in the variable and the search will not be -repeated unless the variable is cleared. If nothing is found, the -result will be <VAR>-NOTFOUND, and the search will be attempted again -the next time find_library is invoked with the same variable. The -name of the library that is searched for is specified by the names -listed after the NAMES argument. Additional search locations can be -specified after the PATHS argument. If ENV var is found in the HINTS -or PATHS section the environment variable var will be read and -converted from a system environment variable to a cmake style list of -paths. For example ENV PATH would be a way to list the system path -variable. The argument after DOC will be used for the documentation -string in the cache. PATH_SUFFIXES specifies additional -subdirectories to check below each search path. - -If NO_DEFAULT_PATH is specified, then no additional paths are added to -the search. If NO_DEFAULT_PATH is not specified, the search process -is as follows: - -1. Search paths specified in cmake-specific cache variables. These -are intended to be used on the command line with a -DVAR=value. This -can be skipped if NO_CMAKE_PATH is passed. - -:: +.. |FIND_XXX| replace:: find_library +.. |NAMES| replace:: NAMES name1 [name2 ...] [NAMES_PER_DIR] +.. |SEARCH_XXX| replace:: library +.. |SEARCH_XXX_DESC| replace:: library +.. |XXX_SUBDIR| replace:: lib +.. |CMAKE_PREFIX_PATH_XXX| replace:: <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and - <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH - CMAKE_LIBRARY_PATH - CMAKE_FRAMEWORK_PATH - -2. Search paths specified in cmake-specific environment variables. -These are intended to be set in the user's shell configuration. This -can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed. - -:: - - <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and - <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH - CMAKE_LIBRARY_PATH - CMAKE_FRAMEWORK_PATH - -3. Search the paths specified by the HINTS option. These should be -paths computed by system introspection, such as a hint provided by the -location of another item already found. Hard-coded guesses should be -specified with the PATHS option. + |CMAKE_PREFIX_PATH_XXX_SUBDIR| +.. |CMAKE_XXX_PATH| replace:: CMAKE_LIBRARY_PATH +.. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_FRAMEWORK_PATH -4. Search the standard system environment variables. This can be -skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument. - -:: - - PATH - LIB - -5. Search cmake variables defined in the Platform files for the -current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is -passed. - -:: +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: PATH and LIB +.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and - <prefix>/lib for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH - CMAKE_SYSTEM_LIBRARY_PATH - CMAKE_SYSTEM_FRAMEWORK_PATH - -6. Search the paths specified by the PATHS option or in the -short-hand version of the command. These are typically hard-coded -guesses. - -On Darwin or systems supporting OS X Frameworks, the cmake variable -CMAKE_FIND_FRAMEWORK can be set to empty or one of the following: - -:: - - "FIRST" - Try to find frameworks before standard - libraries or headers. This is the default on Darwin. - "LAST" - Try to find frameworks after standard - libraries or headers. - "ONLY" - Only try to find frameworks. - "NEVER" - Never try to find frameworks. - -On Darwin or systems supporting OS X Application Bundles, the cmake -variable CMAKE_FIND_APPBUNDLE can be set to empty or one of the -following: - -:: - - "FIRST" - Try to find application bundles before standard - programs. This is the default on Darwin. - "LAST" - Try to find application bundles after standard - programs. - "ONLY" - Only try to find application bundles. - "NEVER" - Never try to find application bundles. - -The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more -directories to be prepended to all other search directories. This -effectively "re-roots" the entire search under given locations. By -default it is empty. It is especially useful when cross-compiling to -point to the root directory of the target environment and CMake will -search there too. By default at first the directories listed in -CMAKE_FIND_ROOT_PATH and then the non-rooted directories will be -searched. The default behavior can be adjusted by setting -CMAKE_FIND_ROOT_PATH_MODE_LIBRARY. This behavior can be manually -overridden on a per-call basis. By using CMAKE_FIND_ROOT_PATH_BOTH -the search order will be as described above. If -NO_CMAKE_FIND_ROOT_PATH is used then CMAKE_FIND_ROOT_PATH will not be -used. If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted -directories will be searched. - -The default search order is designed to be most-specific to -least-specific for common use cases. Projects may override the order -by simply calling the command multiple times and using the NO_* -options: - -:: + |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| +.. |CMAKE_SYSTEM_XXX_PATH| replace:: CMAKE_SYSTEM_LIBRARY_PATH +.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_FRAMEWORK_PATH - find_library(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH) - find_library(<VAR> NAMES name) +.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: + CMAKE_FIND_ROOT_PATH_MODE_LIBRARY -Once one of the calls succeeds the result variable will be set and -stored in the cache so that no call will search again. +.. include:: FIND_XXX.txt When more than one value is given to the NAMES option this command by default will consider one name at a time and search every directory diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 27d0ac7..c394a08 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -317,58 +317,14 @@ registry on non-Windows platforms. 9. Search paths specified by the PATHS option. These are typically hard-coded guesses. -On Darwin or systems supporting OS X Frameworks, the cmake variable -CMAKE_FIND_FRAMEWORK can be set to empty or one of the following: - -:: - - "FIRST" - Try to find frameworks before standard - libraries or headers. This is the default on Darwin. - "LAST" - Try to find frameworks after standard - libraries or headers. - "ONLY" - Only try to find frameworks. - "NEVER" - Never try to find frameworks. - -On Darwin or systems supporting OS X Application Bundles, the cmake -variable CMAKE_FIND_APPBUNDLE can be set to empty or one of the -following: - -:: - - "FIRST" - Try to find application bundles before standard - programs. This is the default on Darwin. - "LAST" - Try to find application bundles after standard - programs. - "ONLY" - Only try to find application bundles. - "NEVER" - Never try to find application bundles. - -The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more -directories to be prepended to all other search directories. This -effectively "re-roots" the entire search under given locations. By -default it is empty. It is especially useful when cross-compiling to -point to the root directory of the target environment and CMake will -search there too. By default at first the directories listed in -CMAKE_FIND_ROOT_PATH and then the non-rooted directories will be -searched. The default behavior can be adjusted by setting -CMAKE_FIND_ROOT_PATH_MODE_PACKAGE. This behavior can be manually -overridden on a per-call basis. By using CMAKE_FIND_ROOT_PATH_BOTH -the search order will be as described above. If -NO_CMAKE_FIND_ROOT_PATH is used then CMAKE_FIND_ROOT_PATH will not be -used. If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted -directories will be searched. - -The default search order is designed to be most-specific to -least-specific for common use cases. Projects may override the order -by simply calling the command multiple times and using the NO_* -options: - -:: - - find_package(<package> PATHS paths... NO_DEFAULT_PATH) - find_package(<package>) - -Once one of the calls succeeds the result variable will be set and -stored in the cache so that no call will search again. +.. |FIND_XXX| replace:: find_package +.. |FIND_ARGS_XXX| replace:: <package> +.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: + CMAKE_FIND_ROOT_PATH_MODE_PACKAGE + +.. include:: FIND_XXX_MAC.txt +.. include:: FIND_XXX_ROOT.txt +.. include:: FIND_XXX_ORDER.txt Every non-REQUIRED find_package() call can be disabled by setting the variable CMAKE_DISABLE_FIND_PACKAGE_<package> to TRUE. See the diff --git a/Help/command/find_path.rst b/Help/command/find_path.rst index 2ffe6aa..c85011a 100644 --- a/Help/command/find_path.rst +++ b/Help/command/find_path.rst @@ -1,158 +1,30 @@ find_path --------- -Find the directory containing a file. - -:: - - find_path(<VAR> name1 [path1 path2 ...]) - -This is the short-hand signature for the command that is sufficient in -many cases. It is the same as find_path(<VAR> name1 [PATHS path1 -path2 ...]) - -:: - - find_path( - <VAR> - name | NAMES name1 [name2 ...] - [HINTS path1 [path2 ... ENV var]] - [PATHS path1 [path2 ... ENV var]] - [PATH_SUFFIXES suffix1 [suffix2 ...]] - [DOC "cache documentation string"] - [NO_DEFAULT_PATH] - [NO_CMAKE_ENVIRONMENT_PATH] - [NO_CMAKE_PATH] - [NO_SYSTEM_ENVIRONMENT_PATH] - [NO_CMAKE_SYSTEM_PATH] - [CMAKE_FIND_ROOT_PATH_BOTH | - ONLY_CMAKE_FIND_ROOT_PATH | - NO_CMAKE_FIND_ROOT_PATH] - ) - -This command is used to find a directory containing the named file. A -cache entry named by <VAR> is created to store the result of this -command. If the file in a directory is found the result is stored in -the variable and the search will not be repeated unless the variable -is cleared. If nothing is found, the result will be <VAR>-NOTFOUND, -and the search will be attempted again the next time find_path is -invoked with the same variable. The name of the file in a directory -that is searched for is specified by the names listed after the NAMES -argument. Additional search locations can be specified after the -PATHS argument. If ENV var is found in the HINTS or PATHS section the -environment variable var will be read and converted from a system -environment variable to a cmake style list of paths. For example ENV -PATH would be a way to list the system path variable. The argument -after DOC will be used for the documentation string in the cache. -PATH_SUFFIXES specifies additional subdirectories to check below each -search path. - -If NO_DEFAULT_PATH is specified, then no additional paths are added to -the search. If NO_DEFAULT_PATH is not specified, the search process -is as follows: - -1. Search paths specified in cmake-specific cache variables. These -are intended to be used on the command line with a -DVAR=value. This -can be skipped if NO_CMAKE_PATH is passed. - -:: +.. |FIND_XXX| replace:: find_path +.. |NAMES| replace:: NAMES name1 [name2 ...] +.. |SEARCH_XXX| replace:: file in a directory +.. |SEARCH_XXX_DESC| replace:: directory containing the named file +.. |XXX_SUBDIR| replace:: include +.. |CMAKE_PREFIX_PATH_XXX| replace:: <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and - <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH - CMAKE_INCLUDE_PATH - CMAKE_FRAMEWORK_PATH - -2. Search paths specified in cmake-specific environment variables. -These are intended to be set in the user's shell configuration. This -can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed. - -:: - - <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and - <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH - CMAKE_INCLUDE_PATH - CMAKE_FRAMEWORK_PATH - -3. Search the paths specified by the HINTS option. These should be -paths computed by system introspection, such as a hint provided by the -location of another item already found. Hard-coded guesses should be -specified with the PATHS option. + |CMAKE_PREFIX_PATH_XXX_SUBDIR| +.. |CMAKE_XXX_PATH| replace:: CMAKE_INCLUDE_PATH +.. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_FRAMEWORK_PATH -4. Search the standard system environment variables. This can be -skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument. - -:: - - PATH - INCLUDE - -5. Search cmake variables defined in the Platform files for the -current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is -passed. - -:: +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: PATH and INCLUDE +.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and - <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH - CMAKE_SYSTEM_INCLUDE_PATH - CMAKE_SYSTEM_FRAMEWORK_PATH - -6. Search the paths specified by the PATHS option or in the -short-hand version of the command. These are typically hard-coded -guesses. - -On Darwin or systems supporting OS X Frameworks, the cmake variable -CMAKE_FIND_FRAMEWORK can be set to empty or one of the following: - -:: - - "FIRST" - Try to find frameworks before standard - libraries or headers. This is the default on Darwin. - "LAST" - Try to find frameworks after standard - libraries or headers. - "ONLY" - Only try to find frameworks. - "NEVER" - Never try to find frameworks. - -On Darwin or systems supporting OS X Application Bundles, the cmake -variable CMAKE_FIND_APPBUNDLE can be set to empty or one of the -following: - -:: - - "FIRST" - Try to find application bundles before standard - programs. This is the default on Darwin. - "LAST" - Try to find application bundles after standard - programs. - "ONLY" - Only try to find application bundles. - "NEVER" - Never try to find application bundles. - -The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more -directories to be prepended to all other search directories. This -effectively "re-roots" the entire search under given locations. By -default it is empty. It is especially useful when cross-compiling to -point to the root directory of the target environment and CMake will -search there too. By default at first the directories listed in -CMAKE_FIND_ROOT_PATH and then the non-rooted directories will be -searched. The default behavior can be adjusted by setting -CMAKE_FIND_ROOT_PATH_MODE_INCLUDE. This behavior can be manually -overridden on a per-call basis. By using CMAKE_FIND_ROOT_PATH_BOTH -the search order will be as described above. If -NO_CMAKE_FIND_ROOT_PATH is used then CMAKE_FIND_ROOT_PATH will not be -used. If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted -directories will be searched. - -The default search order is designed to be most-specific to -least-specific for common use cases. Projects may override the order -by simply calling the command multiple times and using the NO_* -options: - -:: + |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| +.. |CMAKE_SYSTEM_XXX_PATH| replace:: CMAKE_SYSTEM_INCLUDE_PATH +.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_FRAMEWORK_PATH - find_path(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH) - find_path(<VAR> NAMES name) +.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: + CMAKE_FIND_ROOT_PATH_MODE_INCLUDE -Once one of the calls succeeds the result variable will be set and -stored in the cache so that no call will search again. +.. include:: FIND_XXX.txt When searching for frameworks, if the file is specified as A/b.h, then the framework search will look for A.framework/Headers/b.h. If that diff --git a/Help/command/find_program.rst b/Help/command/find_program.rst index 656fbe5..da5a41d 100644 --- a/Help/command/find_program.rst +++ b/Help/command/find_program.rst @@ -1,151 +1,25 @@ find_program ------------ -Find an executable program. +.. |FIND_XXX| replace:: find_program +.. |NAMES| replace:: NAMES name1 [name2 ...] +.. |SEARCH_XXX| replace:: program +.. |SEARCH_XXX_DESC| replace:: program +.. |XXX_SUBDIR| replace:: [s]bin -:: +.. |CMAKE_PREFIX_PATH_XXX| replace:: + |CMAKE_PREFIX_PATH_XXX_SUBDIR| +.. |CMAKE_XXX_PATH| replace:: CMAKE_PROGRAM_PATH +.. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_APPBUNDLE_PATH - find_program(<VAR> name1 [path1 path2 ...]) +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: PATH -This is the short-hand signature for the command that is sufficient in -many cases. It is the same as find_program(<VAR> name1 [PATHS path1 -path2 ...]) +.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: + |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| +.. |CMAKE_SYSTEM_XXX_PATH| replace:: CMAKE_SYSTEM_PROGRAM_PATH +.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_APPBUNDLE_PATH -:: +.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: + CMAKE_FIND_ROOT_PATH_MODE_PROGRAM - find_program( - <VAR> - name | NAMES name1 [name2 ...] - [HINTS path1 [path2 ... ENV var]] - [PATHS path1 [path2 ... ENV var]] - [PATH_SUFFIXES suffix1 [suffix2 ...]] - [DOC "cache documentation string"] - [NO_DEFAULT_PATH] - [NO_CMAKE_ENVIRONMENT_PATH] - [NO_CMAKE_PATH] - [NO_SYSTEM_ENVIRONMENT_PATH] - [NO_CMAKE_SYSTEM_PATH] - [CMAKE_FIND_ROOT_PATH_BOTH | - ONLY_CMAKE_FIND_ROOT_PATH | - NO_CMAKE_FIND_ROOT_PATH] - ) - -This command is used to find a program. A cache entry named by <VAR> -is created to store the result of this command. If the program is -found the result is stored in the variable and the search will not be -repeated unless the variable is cleared. If nothing is found, the -result will be <VAR>-NOTFOUND, and the search will be attempted again -the next time find_program is invoked with the same variable. The -name of the program that is searched for is specified by the names -listed after the NAMES argument. Additional search locations can be -specified after the PATHS argument. If ENV var is found in the HINTS -or PATHS section the environment variable var will be read and -converted from a system environment variable to a cmake style list of -paths. For example ENV PATH would be a way to list the system path -variable. The argument after DOC will be used for the documentation -string in the cache. PATH_SUFFIXES specifies additional -subdirectories to check below each search path. - -If NO_DEFAULT_PATH is specified, then no additional paths are added to -the search. If NO_DEFAULT_PATH is not specified, the search process -is as follows: - -1. Search paths specified in cmake-specific cache variables. These -are intended to be used on the command line with a -DVAR=value. This -can be skipped if NO_CMAKE_PATH is passed. - -:: - - <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH - CMAKE_PROGRAM_PATH - CMAKE_APPBUNDLE_PATH - -2. Search paths specified in cmake-specific environment variables. -These are intended to be set in the user's shell configuration. This -can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed. - -:: - - <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH - CMAKE_PROGRAM_PATH - CMAKE_APPBUNDLE_PATH - -3. Search the paths specified by the HINTS option. These should be -paths computed by system introspection, such as a hint provided by the -location of another item already found. Hard-coded guesses should be -specified with the PATHS option. - -4. Search the standard system environment variables. This can be -skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument. - -:: - - PATH - - -5. Search cmake variables defined in the Platform files for the -current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is -passed. - -:: - - <prefix>/[s]bin for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH - CMAKE_SYSTEM_PROGRAM_PATH - CMAKE_SYSTEM_APPBUNDLE_PATH - -6. Search the paths specified by the PATHS option or in the -short-hand version of the command. These are typically hard-coded -guesses. - -On Darwin or systems supporting OS X Frameworks, the cmake variable -CMAKE_FIND_FRAMEWORK can be set to empty or one of the following: - -:: - - "FIRST" - Try to find frameworks before standard - libraries or headers. This is the default on Darwin. - "LAST" - Try to find frameworks after standard - libraries or headers. - "ONLY" - Only try to find frameworks. - "NEVER" - Never try to find frameworks. - -On Darwin or systems supporting OS X Application Bundles, the cmake -variable CMAKE_FIND_APPBUNDLE can be set to empty or one of the -following: - -:: - - "FIRST" - Try to find application bundles before standard - programs. This is the default on Darwin. - "LAST" - Try to find application bundles after standard - programs. - "ONLY" - Only try to find application bundles. - "NEVER" - Never try to find application bundles. - -The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more -directories to be prepended to all other search directories. This -effectively "re-roots" the entire search under given locations. By -default it is empty. It is especially useful when cross-compiling to -point to the root directory of the target environment and CMake will -search there too. By default at first the directories listed in -CMAKE_FIND_ROOT_PATH and then the non-rooted directories will be -searched. The default behavior can be adjusted by setting -CMAKE_FIND_ROOT_PATH_MODE_PROGRAM. This behavior can be manually -overridden on a per-call basis. By using CMAKE_FIND_ROOT_PATH_BOTH -the search order will be as described above. If -NO_CMAKE_FIND_ROOT_PATH is used then CMAKE_FIND_ROOT_PATH will not be -used. If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted -directories will be searched. - -The default search order is designed to be most-specific to -least-specific for common use cases. Projects may override the order -by simply calling the command multiple times and using the NO_* -options: - -:: - - find_program(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH) - find_program(<VAR> NAMES name) - -Once one of the calls succeeds the result variable will be set and -stored in the cache so that no call will search again. +.. include:: FIND_XXX.txt |