[CMake] New FIND_* stuff checked into CVS
Bill Hoffman
bill.hoffman at kitware.com
Thu Mar 2 13:47:58 EST 2006
I have checked in a change to the way that the FIND_* commands work.
It should be backwards compatible with the old commands, but allow for
more control over search paths and how things are searched for.
All 4 commands now use the same code to parse the arguments, so they are
now consistent. They can all disable the 4 external search paths used.
Also, they have a PATH_SUFFIXES argument that allows for the specification of
a directory name that can be added into all search paths. For example, if
you wanted to find a header like qt.h but this is always found in qt/qt.h,
you could do this:
FIND_PATH(QT_INCLUDE NAMES qt.h PATH_SUFFIXES qt)
CMake will find it in /usr/local/include/qt/qt.h and set QT_INCLUDE
to /usr/local/include.
Attached is the --help-command output for each of the changed FIND_* commands.
I have not updated all the Modules in cmake to take advantage of the new stuff,
and if you have contributed a module, you may want to take a look at the contribution
and see if it can take advantage of the new style of FIND.
FIND_PROGRAM
Find an executable program.
FIND_PROGRAM(<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_PROGRAM(<VAR> NAMES name1 PATHS
path2 path2 ...)
FIND_PROGRAM(
<VAR>
NAMES name1 [name2 ...]
PATHS path1 [path2 ...]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[DOC "cache documentation string"]
[NO_CMAKE_ENVIRONMENT_PATH]
[NO_CMAKE_PATH]
[NO_SYSTEM_PATH]
[NO_CMAKE_SYSTEM_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 nothing is found,
the result will be <VAR>-NOTFOUND. 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. The argument after DOC will be used for the
documentation string in the cache. PATH_SUFFIXES can be used to give
sub directories that will be appended to the search paths.
The search process is as follows:
1. Search cmake specific environment variables. This can be skipped
if NO_CMAKE_ENVIRONMENT_PATH is passed.
CMAKE_FRAMEWORK_PATH
CMAKE_PROGRAM_PATH
2. Search cmake variables with the same names as the cmake specific
environment 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_FRAMEWORK_PATH
CMAKE_PROGRAM_PATH
3. Search the standard system environment variables. This can be
skipped if NO_SYSTEM_PATH is an argument.
PATH
4. 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_FRAMEWORK_PATH
CMAKE_SYSTEM_PROGRAM_PATH
5. Search the paths specified after PATHS or in the short-hand
version of the command.
On Darwin or systems supporting OSX 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.
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> NAMES name1 PATHS
path2 path2 ...)
FIND_LIBRARY(
<VAR>
NAMES name1 [name2 ...]
PATHS path1 [path2 ...]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[DOC "cache documentation string"]
[NO_CMAKE_ENVIRONMENT_PATH]
[NO_CMAKE_PATH]
[NO_SYSTEM_PATH]
[NO_CMAKE_SYSTEM_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 nothing is found,
the result will be <VAR>-NOTFOUND. 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. The argument after DOC will be used for the
documentation string in the cache. PATH_SUFFIXES can be used to give
sub directories that will be appended to the search paths.
The search process is as follows:
1. Search cmake specific environment variables. This can be skipped
if NO_CMAKE_ENVIRONMENT_PATH is passed.
CMAKE_FRAMEWORK_PATH
CMAKE_LIBRARY_PATH
2. Search cmake variables with the same names as the cmake specific
environment 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_FRAMEWORK_PATH
CMAKE_LIBRARY_PATH
3. Search the standard system environment variables. This can be
skipped if NO_SYSTEM_PATH is an argument.
PATH
LIB
4. 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_FRAMEWORK_PATH
CMAKE_SYSTEM_LIBRARY_PATH
5. Search the paths specified after PATHS or in the short-hand
version of the command.
On Darwin or systems supporting OSX 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.
If the library found is a framework, then VAR will be set to the full
path to the framework <fullPath>/A.framework. When a full path to a
framework is used as a library, CMake will use a -framework A, and a
-F<fullPath> to link the framework to the target.
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> NAMES name1 PATHS path2
path2 ...)
FIND_PATH(
<VAR>
NAMES name1 [name2 ...]
PATHS path1 [path2 ...]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[DOC "cache documentation string"]
[NO_CMAKE_ENVIRONMENT_PATH]
[NO_CMAKE_PATH]
[NO_SYSTEM_PATH]
[NO_CMAKE_SYSTEM_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 nothing is found, the result will be <VAR>-NOTFOUND. 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. The argument
after DOC will be used for the documentation string in the cache.
PATH_SUFFIXES can be used to give sub directories that will be
appended to the search paths.
The search process is as follows:
1. Search cmake specific environment variables. This can be skipped
if NO_CMAKE_ENVIRONMENT_PATH is passed.
CMAKE_FRAMEWORK_PATH
CMAKE_INCLUDE_PATH
2. Search cmake variables with the same names as the cmake specific
environment 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_FRAMEWORK_PATH
CMAKE_INCLUDE_PATH
3. Search the standard system environment variables. This can be
skipped if NO_SYSTEM_PATH is an argument.
PATH
INCLUDE
4. 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_FRAMEWORK_PATH
CMAKE_SYSTEM_INCLUDE_PATH
5. Search the paths specified after PATHS or in the short-hand
version of the command.
On Darwin or systems supporting OSX 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.
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
is found the path will be set to the path to the framework. CMake
will convert this to the correct -F option to include the file.
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> NAMES name1 PATHS path2
path2 ...)
FIND_FILE(
<VAR>
NAMES name1 [name2 ...]
PATHS path1 [path2 ...]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[DOC "cache documentation string"]
[NO_CMAKE_ENVIRONMENT_PATH]
[NO_CMAKE_PATH]
[NO_SYSTEM_PATH]
[NO_CMAKE_SYSTEM_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
nothing is found, the result will be <VAR>-NOTFOUND. 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. The argument after DOC will be
used for the documentation string in the cache. PATH_SUFFIXES can be
used to give sub directories that will be appended to the search
paths.
The search process is as follows:
1. Search cmake specific environment variables. This can be skipped
if NO_CMAKE_ENVIRONMENT_PATH is passed.
CMAKE_FRAMEWORK_PATH
CMAKE_INCLUDE_PATH
2. Search cmake variables with the same names as the cmake specific
environment 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_FRAMEWORK_PATH
CMAKE_INCLUDE_PATH
3. Search the standard system environment variables. This can be
skipped if NO_SYSTEM_PATH is an argument.
PATH
INCLUDE
4. 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_FRAMEWORK_PATH
CMAKE_SYSTEM_INCLUDE_PATH
5. Search the paths specified after PATHS or in the short-hand
version of the command.
On Darwin or systems supporting OSX 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.
More information about the CMake
mailing list