kolan
/
CMake
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Help: Factor out find_* command duplication 

These documents were represented in the builtin documentation using a
common starting point with placeholders substituted by each command.
Convert them back to this approach using the reStructuredText include
directive and substitutions to avoid duplication.
This commit is contained in:
Brad King 2013-10-01 12:37:02 -04:00
parent 30b21860ad
commit 898216137a
9 changed files with 226 additions and 627 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
Help/command/FIND_XXX.txt Normal file
View File

@ -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

24
Help/command/FIND_XXX_MAC.txt Normal file
View File

@ -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.

12
Help/command/FIND_XXX_ORDER.txt Normal file
View File

@ -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.

14
Help/command/FIND_XXX_ROOT.txt Normal file
View File

@ -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.

161
Help/command/find_file.rst
View File

@ -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
|CMAKE_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_XXX_PATH| replace:: CMAKE_INCLUDE_PATH
.. |CMAKE_XXX_MAC_PATH| replace:: 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.
::
.. |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_PREFIX_PATH
CMAKE_INCLUDE_PATH
CMAKE_FRAMEWORK_PATH
|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
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_FIND_ROOT_PATH_MODE_XXX| replace::
CMAKE_FIND_ROOT_PATH_MODE_INCLUDE
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.
::
<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:
::
find_file(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
find_file(<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

161
Help/command/find_library.rst
View File

@ -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
|CMAKE_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_XXX_PATH| replace:: CMAKE_LIBRARY_PATH
.. |CMAKE_XXX_MAC_PATH| replace:: 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.
::
.. |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_PREFIX_PATH
CMAKE_LIBRARY_PATH
CMAKE_FRAMEWORK_PATH
|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
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_FIND_ROOT_PATH_MODE_XXX| replace::
CMAKE_FIND_ROOT_PATH_MODE_LIBRARY
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.
::
<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:
::
find_library(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
find_library(<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
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

58
Help/command/find_package.rst
View File

@ -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:
.. |FIND_XXX| replace:: find_package
.. |FIND_ARGS_XXX| replace:: <package>
.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
CMAKE_FIND_ROOT_PATH_MODE_PACKAGE
::
"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.
.. 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

162
Help/command/find_path.rst
View File

@ -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
|CMAKE_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_XXX_PATH| replace:: CMAKE_INCLUDE_PATH
.. |CMAKE_XXX_MAC_PATH| replace:: 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.
::
.. |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_PREFIX_PATH
CMAKE_INCLUDE_PATH
CMAKE_FRAMEWORK_PATH
|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
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_FIND_ROOT_PATH_MODE_XXX| replace::
CMAKE_FIND_ROOT_PATH_MODE_INCLUDE
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.
::
<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:
::
find_path(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
find_path(<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
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

160
Help/command/find_program.rst
View File

@ -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