Naming pattern for `Find*.cmake` module variables

Code
1

Hi
I am still new to CMake, so apologies if I have missed something obvious

The find_package command (https://cmake.org/cmake/help/latest/command/find_package.html) doesn’t specify any conventions for the variables that Find*.cmake modules define.

For example:

  • find_package(JPEG) sets JPEG_INCLUDE_DIRS
  • find_package(LibXml2) sets both LIBXML2_INCLUDE_DIR and LIBXML2_INCLUDE_DIRS
  • find_package(Ice) sets Ice_INCLUDE_DIRS
  • find_package(GLUT) sets GLUT_INCLUDE_DIR

Is there any published “official” naming pattern for variables set by custom Find* modules?

2

After analysing some of the modules in https://gitlab.kitware.com/cmake/cmake/-/tree/master/Modules most of them seem to follow these rules:

For find_package(<package>):

  • <package> can be any case
  • <package>_FOUND is set if the package is found
  • uppercase(<package>)_LIBRARIES contains the path to link
  • uppercase(<package>)_INCLUDE_DIRS contains the folder for header files
  • Additional variables are in the form of uppercase(<package>)_*
3

My preference is to use the package name casing for everything and to provide targets rather than variables like _LIBRARIES or _INCLUDE_DIRS. A lot of CMake modules use various patterns or are trying to match what upstream packages now do; I don’t think they’re a good sampling of good practices unless it’s a brand new module that has no considerations for backwards compat.

4

OK, even if you use targets, you still might need variables for additional information like version numbers or for backwards compatibility.

There should be a recommend template for Find* modules, with a proper style guide.
That way, at least new modules will be consistent and old modules can slowly be updated to fit the style.

5

Yes, those make sense.

Yeah, this would be good to have. I think there’s an issue tracking CMake making better config.cmake files somewhere. Those guidelines are basically what you’re looking for here.

If you want examples of more complicated projects, take a look at VTK, ParaView, or SMTK (those are ones I worked on at least). VTK and ParaView have some backwards compat bits in there, but the overall structure has what you’re looking for.

CMake itself has a high bar for new Find modules. It is far better for projects to ship their own package-config.cmake file than a Find modules. However, the guidelines are largely the same. Old modules do get updated, but it’s usually as someone notices that they don’t provide imported targets. Variables are almost never renamed due to backwards compatibility guarantees.

6

The cmake-developer(7) manual has a detailed discussion of naming conventions for Find modules, including a sample Find module.

7

True, but new variables can always be added (and hopefully the old ones marked deprecated), like in the case of FindBZip2.

BZIP2_INCLUDE_DIRS
    New in version 3.12: the BZip2 include directories
    (BZIP2_INCLUDE_DIR is still set)
8

Thank you, this is exactly what I was looking for.
Maybe this should be repeated (or linked) on the find_package page?

Unfortunately, a lot of the standard modules don’t follow the case convention.
Are there any plans to fix that?

9

Many of the existing modules are very old. Those that don’t follow the conventions are unlikely to be updated. The existing names would have to be kept to preserve backward compatibility. Other variables could be added to match the standard names where this didn’t conflict with the existing variables, but there’s probably not a lot of motivation to do that work.