# Naming pattern for \`Find\*.cmake\` module variables

**URL:** <https://discourse.cmake.org/t/naming-pattern-for-find-cmake-module-variables/3713>\
**Category:** Code\
**Created:** [July 8, 2021, 4:40pm UTC](https://discourse.cmake.org/t/naming-pattern-for-find-cmake-module-variables/3713 "2021-07-08T16:40:47Z")\
**Posts on this page:** 9\
**Page:** 1

<div class="post-metadata">

**Author:** ![KartikSoneji](https://discourse.cmake.org/letter_avatar_proxy/v4/letter/k/e480ec/32.png) [@KartikSoneji](https://discourse.cmake.org/u/KartikSoneji)\
**Post date:** [July 8, 2021, 4:40pm UTC](https://discourse.cmake.org/t/naming-pattern-for-find-cmake-module-variables/3713/1 "2021-07-08T16:40:47Z")

</div>

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](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?

---

<div class="post-metadata">

**Author:** ![KartikSoneji](https://discourse.cmake.org/letter_avatar_proxy/v4/letter/k/e480ec/32.png) [@KartikSoneji](https://discourse.cmake.org/u/KartikSoneji)\
**Post date:** [July 8, 2021, 4:51pm UTC](https://discourse.cmake.org/t/naming-pattern-for-find-cmake-module-variables/3713/2 "2021-07-08T16:51:38Z")

</div>

After analysing some of the modules in [https://gitlab.kitware.com/cmake/cmake/-/tree/master/Modules](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>)_*`

---

<div class="post-metadata">

**Author:** ![ben.boeckel](https://discourse.cmake.org/letter_avatar_proxy/v4/letter/b/ea5d25/32.png) [@ben.boeckel](https://discourse.cmake.org/u/ben.boeckel)\
**Post date:** [July 8, 2021, 6:33pm UTC](https://discourse.cmake.org/t/naming-pattern-for-find-cmake-module-variables/3713/3 "2021-07-08T18:33:45Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![KartikSoneji](https://discourse.cmake.org/letter_avatar_proxy/v4/letter/k/e480ec/32.png) [@KartikSoneji](https://discourse.cmake.org/u/KartikSoneji)\
**Post date:** [July 8, 2021, 8:04pm UTC](https://discourse.cmake.org/t/naming-pattern-for-find-cmake-module-variables/3713/4 "2021-07-08T20:04:17Z")

</div>

> [@ben.boeckel](#):
>
> use the package name casing for everything and to provide targets rather than variables like `_LIBRARIES` or `_INCLUDE_DIRS`

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.

---

<div class="post-metadata">

**Author:** ![ben.boeckel](https://discourse.cmake.org/letter_avatar_proxy/v4/letter/b/ea5d25/32.png) [@ben.boeckel](https://discourse.cmake.org/u/ben.boeckel)\
**Post date:** [July 8, 2021, 9:03pm UTC](https://discourse.cmake.org/t/naming-pattern-for-find-cmake-module-variables/3713/5 "2021-07-08T21:03:12Z")

</div>

Yes, those make sense.

> [@KartikSoneji](#):
>
> There should be a recommend template for Find\* modules, with a proper style guide.

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](https://gitlab.kitware.com/vtk/vtk), [ParaView](https://gitlab.kitware.com/paraview/paraview), or [SMTK](https://gitlab.kitware.com/cmb/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.

> [@KartikSoneji](#):
>
> That way, at least new modules will be consistent

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.

---

<div class="post-metadata">

**Author:** ![craig.scott](https://discourse.cmake.org/user_avatar/discourse.cmake.org/craig.scott/32/20_2.png) [@craig.scott](https://discourse.cmake.org/u/craig.scott)\
**Post date:** [July 8, 2021, 10:06pm UTC](https://discourse.cmake.org/t/naming-pattern-for-find-cmake-module-variables/3713/6 "2021-07-08T22:06:40Z")

</div>

The [cmake-developer(7)](https://cmake.org/cmake/help/latest/manual/cmake-developer.7.html) manual has a detailed discussion of naming conventions for Find modules, including a sample Find module.

---

<div class="post-metadata">

**Author:** ![KartikSoneji](https://discourse.cmake.org/letter_avatar_proxy/v4/letter/k/e480ec/32.png) [@KartikSoneji](https://discourse.cmake.org/u/KartikSoneji)\
**Post date:** [July 8, 2021, 10:09pm UTC](https://discourse.cmake.org/t/naming-pattern-for-find-cmake-module-variables/3713/7 "2021-07-08T22:09:46Z")

</div>

> [@ben.boeckel](#):
>
> Variables are almost never renamed due to backwards compatibility guarantees.

True, but new variables can always be added (and hopefully the old ones marked deprecated), like in the case of [`FindBZip2`](https://cmake.org/cmake/help/latest/module/FindBZip2.html#result-variables).

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

```

---

<div class="post-metadata">

**Author:** ![KartikSoneji](https://discourse.cmake.org/letter_avatar_proxy/v4/letter/k/e480ec/32.png) [@KartikSoneji](https://discourse.cmake.org/u/KartikSoneji)\
**Post date:** [July 8, 2021, 10:19pm UTC](https://discourse.cmake.org/t/naming-pattern-for-find-cmake-module-variables/3713/8 "2021-07-08T22:19:32Z")

</div>

Thank you, this is exactly what I was looking for.  
Maybe this should be repeated (or linked) on the [`find_package`](https://cmake.org/cmake/help/latest/command/find_package.html) page?

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

---

<div class="post-metadata">

**Author:** ![craig.scott](https://discourse.cmake.org/user_avatar/discourse.cmake.org/craig.scott/32/20_2.png) [@craig.scott](https://discourse.cmake.org/u/craig.scott)\
**Post date:** [July 9, 2021, 11:05pm UTC](https://discourse.cmake.org/t/naming-pattern-for-find-cmake-module-variables/3713/9 "2021-07-09T23:05:36Z")

</div>

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.