Guidelines and HOWTOs/CMake/FAQs

Can I safely change the cmake_minimum_required version?

Maybe.

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

if (NOT CMAKE_VERSION VERSION_LESS 3.0)
  # do stuff that requires CMake 3.0 or later
endif()

However, cmake_minimum_required also sets some 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 find_package call actually does. The CMake documentation contains 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 find_package(Foo), it progresses like this:

CMakel searches for a file called FindFoo.cmake in the same places it looks for files when you use the include command (the entries in 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 FindFoo.cmake 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 FindFoo.cmake file remain (which is how the results of the search are communicated back to your CMakeLists.txt.

The second search method is called the config search.

TODO: describe config search.