CMake: Finding Qt 5 the “Right Way”

I work on build systems a fair bit, and this is something I thought others might benefit from. I went through quite a bit of code in our projects that did not do things the “right way”, and it wasn’t clear what that was to me at first. Qt 5 improved its integration with CMake quite significantly – moving from using the qmake command to find Qt 4 components in a traditional CMake find module to providing its own CMake config files. This meant that instead of having to guess where Qt and its libraries/headers were installed we could use the information generated by Qt’s own build system. This led to many of us, myself included, finding Qt 5 modules individually:

find_package(Qt5Core REQUIRED)
find_package(Qt5Widgets REQUIRED)

This didn’t feel right to me, but I hadn’t yet seen what I think is the preferred way (and the way I would recommend) to find Qt 5. It also led to either using ‘CMAKE_PREFIX_PATH’ to specify the prefix Qt 5 was installed in, or passing in ‘Qt5Core_DIR’, ‘Qt5Widgets_DIR’, etc for the directory containing each and every Qt 5 config module – normally all within a common prefix. There is a better way, and it makes many of these things simpler again:

find_package(Qt5 COMPONENTS Core Widgets REQUIRED)

This is not only more compact, which is always nice, but it means that you can simply pass in ‘Qt5_DIR’ to your project, and it will use that when searching for the components. There are many other great features in CMake that improve Qt integration, but I want to keep this post short…

5 Responses to CMake: Finding Qt 5 the “Right Way”

  1. Alexis Girault says:

    I very much agree, I have been doing this for a little while. I also believe it should be preferable because it will insure that all COMPONENTS will belong to the same Qt5 package: I once needed the component WebKit which was missing from one package, but was present in another one. With the old way, CMake automatically found each component from the first package, but also the webkit component from the second package, and I obviously got no warnings and nice linking issues later on. By looking for Qt5 like you describe, it would indeed signal that the WebKit component was missing from that first package.

  2. Sankhesh Jhaveri says:

    One more situation that I’ve found this to be helpful is when adding another Qt5 module dependency to your CMake project or re-configuring. If CMAKE_PREFIX_PATH points to a different location than the one already set by Qt5_DIR in the CMake cache, it could lead to linker issues. Looking for components from the Qt5_DIR set in the cache eliminates this.

  3. TManhente says:

    Maybe both the CMake and Qt documentations should then be updated. They use one find_package() per Qt module in their examples and fail to mention that a find_package(Qt5) exists.

Questions or comments are always welcome!