Standard way of knowing if find_package defines INCLUDE_DIR or INCLUDE_DIRS

Question

I keep running into this problem with cmake when trying to write build files. the find_package command is supposed to define variables to be used with the include_directories directive, but it does so inconsistently. For example, consider the following code:

find_package(OpenGL REQUIRED)
find_package(glm REQUIRED)

message(STATUS ${GLM_INCLUDE_DIR})
message(STATUS ${GLM_INCLUDE_DIRS})
message(STATUS ${OPENGL_INCLUDE_DIR})
message(STATUS ${OPENGL_INCLUDE_DIRS})

Only the second and third message prints, even though one is "DIR" and the other is "DIRS"

Is there a standard way of determining which one you're supposed to use?

Answer 1

The de-facto standard is *_LIBRARIES and *_DIRS, i.e. the plural variable names are result variables. So, they are only meant to be read from not written to.

Also, with a well-written modern FindModule even those variables are rarely useful to users because the imported targets will contain all the relevant information. So, users can just do the following without using result variables directly:

add_executable(myexe OpenGL::GL)
add_library(mylibrary PUBLIC OpenGL::GL)

However, the correct way to know how to use a FindModule is to just read the documentation which will either be in docs explicitly or in CMake comments at the beginning of the FindModule.cmake file.

All the standard module files are in the CMake installation subdirectory 'Modules' and most (all?) have CMake documentation.

The location hint variables will often be named *_INCLUDE_DIR AND *_LIBRARY, which you can set before calling find_package() in your CMakeLists.txt or you can set with cmake -D or cmake-gui or ccmake.