What does find_package in Config mode set?

Is there a way to get a list of all variables set by a call to find_package? I find that in practice, find_package is like a method with an undocumented interface. It does things, but you can’t know what it does.

In my situation, I call find_package in a subdirectory (where I find all the things I need to find – historically in module mode). I then end up promoting the variables I need via:


I’ve changed my system such that I no longer need to promote everything to PARENT_SCOPE. So, in one sense this issue is resolved.

However, the greater issue still remains. I have often needed to know what a call to find_package() does (what variables it creates and sets, etc.). This seems to never be documented or correct. This lack of transparency makes debugging a complex build system even harder.

A sledgehammer approach would be a command that takes a snapshot of the environment before and after the call to find_package – and then reports just the differences.

The documentation of the package is what you can rely on.

Please file issues with the maintainers of the relevant module to have this explained better in the documentation.

This is possible via the VARIABLES directory property.

I was afraid this might be the answer.

Perhaps CMake’s documentation can be improved to emplore maintainers to document their packages in this manner – at least by providing good examples to follow.

In my experience, I have never come across a package that made any attempt to document what was set when you call find_package in config mode.

I understand the impossibility of centralizing development of all this stuff – but punting it all to the community with no standardization and guidelines is a poor design choice that will only lead to chaos.

Thanks for that tip. I may look into hacking something together with ‘cmake -e compare_files’ to generate a report.

As I understand it, this will only work when run with a clean cache? After a first CMake run, later runs will already have any added variables?

Thanks for the information.

It is lacking, but I’ve yet to seen a technical solution to “bad docs”.

Output variables from find modules should always be local variables. Cache variables are for stateful remembering or input to the searching process(es).

I agree that documentation of all this is the first step. But I wondered why it wouldn’t be possible to find a technical solution for this. At least one that works in like 90% of the cases.
The Config Files are generated to a good extent by cmake itself. There are cases where parts of it are done by the developers itself. But this most of the time is only finding some deps with also some standard cmake commands. In rather rare cases there is more involved logic.

I could see how cmake could write some helper variables, which would allow cmake to generate a help message / documentation of that package, if people say find_package(XYZ HELP) for instance.

To support that more work could be done to avoid writing custom configs file in the first place. For example most projects just specify some dependencies. It shouldn’t be too hard to allow doing that without specifying your own config. But these considerations would be off topic perhaps here.

The files made by export(EXPORT) and install(EXPORT) should not leak variables. Their only “side-effect” should be new IMPORTED targets being created.

Also, lots of configs don’t clean up their own variables very well. Additionally, if one finds a package that finds a dependency, knowing what comes from which at the top-level is difficult.

I suppose --find-package mode could be “enhanced” to instrument the execution and try to trace what ended up being created in which package, but it doesn’t sound trivial to me.