Difference between revisions of "Development/CMake/FAQs"

(Replaced content with link to Community WIki.)
Line 1: Line 1:
==Can I safely change the cmake_minimum_required version?==
Moved to the [https://community.kde.org/Guidelines_and_HOWTOs/CMake/FAQs Community wiki].
Your two main considerations, of course, are that if you set it to a too-recent version, your users will not have a recent enough CMake (especially if they are using the one provided by their Linux distribution), and that if you set it to a too-old version, you won't be able to use new features.
Bear in mind that you may be able to optionally use new features by doing something like
<syntaxhighlight lang="cmake">
  # do stuff that requires CMake 3.0 or later
However, [http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:cmake_minimum_required cmake_minimum_required] also sets some [http://www.cmake.org/cmake/help/v2.8.12/cmake.html#section_Policies CMake Policies] to NEW, changing CMake's behaviour in some corner cases. Normally, CMake should have been warning you about these Policies if you have done something that would be affected by them, so you if don't get any warnings when you build with CMake version X or later, you should be safe to set the minimum required version to X.
==Why isn't find_package working?==
If a find_package call isn't finding something you think it should, there are a few things to check. First, the obvious things:
* Was the package name spelled correctly? Case is important!
* Do you have the right version installed?
Of course, it may not be obvious what the "correct" spelling of the package name is, especially when it comes to upper- or lower-case letters.
At this point, it is useful to know what a [http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:find_package find_package] call actually does. The CMake documentation contains [http://www.cmake.org/cmake/help/v3.3/command/find_package.html a complete description], but it is long and rather daunting. So here is a simplified description.
find_package has two ways of finding the information it needs. The first method is called the ''module'' search. If you do <code>find_package(Foo)</code>, it progresses like this:
* CMake searches for a file called <tt>FindFoo.cmake</tt> in the same places it looks for files when you use the [http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:include include] command (the entries in [http://www.cmake.org/cmake/help/v2.8.12/cmake.html#variable:CMAKE_MODULE_PATH CMAKE_MODULE_PATH] followed by the CMake installation).
* It sets some variables describing what you are looking for (such as what version you want).
* CMake effectively includes the <tt>FindFoo.cmake</tt> file, as though you had copied the text in place of the find_package call.
* After this, it unsets the variables it set at the start, but any variables set by the <tt>FindFoo.cmake</tt> file remain (which is how the results of the search are communicated back to your <tt>CMakeLists.txt</tt>.
These ''find modules'' are intended to be provided by CMake directly, by Extra CMake Modules or by your project directly (typically in a <tt>cmake</tt> subfolder, but don't forget to add it to CMAKE_MODULE_PATH).
The second search method is called the ''config'' search. This uses files installed by the packages you are looking for. In other words, CMake expects the files to exist if the package is installed, and to not exist if it is not. It progresses like this:
* CMake searches for the files <tt>FooConfig.cmake</tt> and <tt>FooConfigVersion.cmake</tt> in one of a few standard locations:
** It constructs a list of ''prefixes'' to search in using several bits of information. The easiest to affect are [http://www.cmake.org/cmake/help/v2.8.12/cmake.html#variable:CMAKE_PREFIX_PATH CMAKE_PREFIX_PATH] and PATH (the parent directories of entries in PATH are used, so /usr for /usr/bin and so on).
** Within those prefixes, it looks in some subdirectories; the full list is in the [http://www.cmake.org/cmake/help/v3.3/command/find_package.html documentation], but in practice they tend to be in <tt>share/Foo</tt> or <tt><libdir>/cmake/Foo</tt> on UNIX systems.
* The <tt>FooConfigVersion.cmake</tt> is used to determine whether the package version is compatible with the requested version.
* <tt>FooConfig.cmake</tt> is included (in much the same way as for find modules).
It is possible to force CMake to use only one mode or the other. Passing the MODULE argument to find_package will cause it to only use find modules, and passing NO_MODULE or CONFIG will cause it to only use config files.

Latest revision as of 10:27, 28 April 2019

Moved to the Community wiki.

This page was last edited on 28 April 2019, at 10:27. Content is available under Creative Commons License SA 4.0 unless otherwise noted.