4

I need to write a CMake FindXYZ-type module. Googling, I've found this guide:

https://cmake.org/Wiki/CMake:How_To_Find_Libraries

from Kitware, but there's a disclaimer about it being deprecated. Which significant changes, if any, have been made to how these modules are written over the past, say, 6-7 years?

einpoklum
  • 118,144
  • 57
  • 340
  • 684
  • No, I don't think there's any significant changes. I still use it. I think they are just trying to get you to look at their other documentation, like [find_package](https://cmake.org/cmake/help/v3.11/command/find_package.html). I normally just look at the other FindXXX.cmake as examples and go from there. – Timothy Brown Feb 26 '18 at 16:14
  • @TimothyBrown: If you're certain enough to make this an answer, I'll accept. – einpoklum Feb 26 '18 at 16:40

2 Answers2

4

Yes, the CMake Wiki's content now officially moved inside CMake's documentation, so the "deprecated" warning is more a general one that the Wiki is no longer looked after.

In your case the main part of CMake Wiki: How To Find Libraries moved to CMake's documentation cmake-packages chapter.

What has changed?

I think the major change over the last years is what Stephen Kelly in his "Embracing Modern CMake" talk called:

Modern CMake packages define IMPORTED targets

find_package(Foo REQUIRED)

add_executable(hello main.cpp)
target_link_libraries(hello
    Foo::Core
)

The same basic tint is found in CMake's documentation cmake-developer - Find Modules chapter:

The traditional approach is to use variables for everything, including libraries and executables. This is what most of the existing find modules provided by CMake do.

The more modern approach is to behave as much like config file packages files as possible, by providing imported target. This has the advantage of propagating Transitive Usage Requirements to consumers.

Details

You can see this "modern approach" as an extension of the previous methods (like in "FindZLIB: Add imported target and documentation" commit).

What should definitely be there (the core of all "Find Modules" for years now) is the find_package_handle_standard_args() macro. This macro is build around the ..._FOUND cached variable handling.

My recommendation would be to concentrate on the imported targets and the ..._INCLUDE_DIRS and ..._LIBRARIES variables are just a side effect of having to cache your find results somewhere.

Florian
  • 39,996
  • 9
  • 133
  • 149
  • I'll check out that video, but your example is not explicit enough IMO. Also, you've provided 4 different links in addition to the video, and it's not clear how they relate to each other. – einpoklum Feb 26 '18 at 20:33
  • @einpoklum Sorry, it's getting late here. Just wanted to cover the major sources/references. I've tried to clarify my answer. – Florian Feb 26 '18 at 20:51
  • @einpoklum After thinking about it for a while, I will add some minimal example CMake code over the next days to clarify the "modern approach" from the linked/quoted information sources. – Florian Feb 27 '18 at 12:54
  • The advice here is correct but incomplete. These days, there is a preference to move away from creating Find modules and instead encourage the project being found to define its own Config file package. Find modules should now really be considered a last resort when that isn't a viable path. – Craig Scott Mar 04 '18 at 21:57
  • @CraigScott Do you have any links showing what this config file looks like? Thanks. – Timothy Brown Mar 04 '18 at 22:59
  • It's covered in the [packages](https://cmake.org/cmake/help/latest/manual/cmake-packages.7.html) part of the CMake documentation. – Craig Scott Mar 04 '18 at 23:06
  • @TimothyBrown One example showing both cases (find module and config file package) I just came across is the blog post ["It's Time To Do CMake Right"](https://pabloariasal.github.io/2018/02/19/its-time-to-do-cmake-right/) by Pablo Arias. – Florian Mar 05 '18 at 20:47
1

No, I don't think there's any significant changes. I still use it.

I think they are just trying to get you to look at their other documentation, like find_package.

In writing new Find modules, I normally just look at the other FindXXX.cmake as examples/templates and go from there.

Timothy Brown
  • 2,220
  • 18
  • 22
  • There have been changes. The move to the use of import targets in preference to relying on passing details through variables is a significant change in direction. There has also been a strong push to encourage projects to define their own Config file packages for other projects to import them rather than relying on Find modules being externally defined. – Craig Scott Mar 04 '18 at 22:00