[CMake] Confusion on how find_package works.

[Michael Jackson]

 From the Help page:

All CMake commands

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

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

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

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.

---
Mike Jackson                 www.bluequartz.net



On Jan 13, 2009, at 5:08 PM, Robert Dailey wrote:

> Hi,
>
> I'm currently looking at FindZLIB.cmake trying to understand how it  
> works and I just can't seem to make sense of it. I have a few  
> questions:
> 	• How does find_path() know where to look? Where is it looking?  
> Where is it told where to look?
> 	• Question #1 with find_library() as well.
> It would be great to be able to set a root directory with all my  
> libraries in it and have it recursively go through it and find the  
> file it is looking for. This would be a convenient (but slow) way of  
> getting find_path() and find_library() to work reliably in my case.  
> Thanks in advance for any help.
> _______________________________________________
> CMake mailing list
> CMake at cmake.org
> http://www.cmake.org/mailman/listinfo/cmake