CMake configure fails to find Qt5 on Linux

Introduction

CMake is an open-source cross-platform tool used for building, testing and packaging software. It is widely used in industry for its portability and ability to generate build scripts for various build systems such as make, ninja, etc. Qt is a cross-platform application development framework that is widely used in creating GUI applications. In this article, we will discuss a common issue that developers face while configuring a CMake project on Linux, i.e. "CMake configure fails to find Qt5".

Understanding Issue

When we configure a CMake project with Qt5, CMake needs to find Qt5 package, which includes required libraries, header files and other necessary files. CMake uses a module named "FindQt5.cmake" to search for Qt5 package. This module searches for Qt5 installation directory in system environment variables, CMAKE_PREFIX_PATH and QT5DIR.

However, sometimes CMake fails to find Qt5 package, even when Qt5 is installed on system. This can happen due to several reasons, such as incorrect installation, missing environment variables, incorrect paths, etc. Let's discuss some common reasons why CMake fails to find Qt5.

Common Reasons for CMake configure failure

• Incorrect Installation − CMake needs to know location of Qt5 installation directory to find required files. If Qt5 is not installed correctly, it can lead to CMake failing to find package. In such cases, we need to make sure that Qt5 is installed correctly, and installation directory is added to system environment variables.

• Missing Environment Variables − CMake uses system environment variables to find Qt5 package. If environment variables are missing or incorrectly set, it can lead to CMake failing to find package. We need to make sure that environment variables, such as CMAKE_PREFIX_PATH and QT5DIR, are correctly set and point to correct Qt5 installation directory.

• Incorrect Path − If path to Qt5 installation directory is incorrect, CMake fails to find package. In such cases, we need to make sure that correct path is added to environment variables and CMake configuration file.

• Outdated FindQt5.cmake Module − FindQt5.cmake module is responsible for finding Qt5 package. If this module is outdated or missing, it can lead to CMake failing to find package. In such cases, we need to update FindQt5.cmake module or install it if it's missing.

• Missing Qt5 Components − Qt5 is a modular framework, and we need to install required components for our project. If required components are missing, CMake fails to find package. In such cases, we need to make sure that required components are installed.

Solution to Issue

Now that we understand common reasons why CMake fails to find Qt5, let's discuss solutions to issue.

• Correct Installation − We need to make sure that Qt5 is installed correctly, and installation directory is added to system environment variables. To verify installation, we can check version of Qt5 by running command "qmake -v" in terminal. If Qt5 is installed correctly, we can see version number in output.

• Set Environment Variables − We need to make sure that environment variables, such as CMAKE_PREFIX_PATH and QT5DIR, are correctly set and point to correct Qt5 installation directory. We can set environment variables by running following command in terminal −

export CMAKE_PREFIX_PATH=/path/to/qt5:$CMAKE_PREFIX_PATH export QT5DIR=/path/to/qt5

We need to replace "/path/to/qt5" with actual path to Qt5 installation directory.

• Update Path − If path to Qt5 installation directory is incorrect, we need to update it. We can update path by adding correct path to environment variables and CMake configuration file.

To add path to environment variables, we can run following command in terminal −

export PATH=/path/to/qt5/bin:$PATH

To add path to CMake configuration file, we can add following line to CMakeLists.txt file −

set(Qt5_DIR "/path/to/qt5/lib/cmake/Qt5")

• Update FindQt5.cmake Module − If FindQt5.cmake module is outdated or missing, we need to update it or install it. We can update module by running following command in terminal −

sudo apt-get update sudo apt-get install qtbase5-dev

This command will update package manager and install latest version of Qt5 development files, which includes FindQt5.cmake module.

• Install Required Qt5 Components − We need to make sure that required components for our project are installed. We can install required components by running following command in terminal −

sudo apt-get install qtdeclarative5-dev

This command will install required Qt5 components for developing Qt5 QML applications.

Additional Tips

Here are some additional tips that can help you resolve "CMake configure fails to find Qt5" issue −

• Check CMake Cache − CMake creates a cache file for each project that it configures. This file contains values of all CMake variables and options that were set during configuration process. Sometimes, cache file contains incorrect values, which can cause CMake to fail to find Qt5 package. To resolve this issue, you can delete CMake cache file and re-run CMake to regenerate it. You can delete cache file by running following command in build directory −

rm -rf CMakeCache.txt

• Use FindPackage Command − Instead of using FindQt5.cmake module, you can use built-in CMake command FindPackage to find Qt5 package. This command automatically searches for package in standard installation locations and sets necessary CMake variables. To use this command, add following line to your CMakeLists.txt file −

find_package(Qt5 COMPONENTS REQUIRED Core Gui Widgets)

This line tells CMake to search for Qt5 package and required components. If package is found, CMake sets necessary CMake variables, such as Qt5_FOUND, Qt5_INCLUDE_DIRS, Qt5_LIBRARIES, etc.

• Use pkg-config − If you are using a Linux distribution that supports pkg-config tool, you can use it to find Qt5 package. Pkg-config is a command-line tool that provides a unified interface for querying installed libraries and their dependencies. To use pkg-config to find Qt5 package, run following command in terminal −

pkg-config --cflags --libs Qt5Core Qt5Gui Qt5Widgets

This command will print necessary C and C++ compiler flags and linker flags for using Qt5 package. You can copy these flags to your CMakeLists.txt file by setting necessary CMake variables.

• Use CMake Toolchain File − If you are cross-compiling your CMake project for a Linux-based embedded system, you can use a CMake toolchain file to set necessary environment variables and toolchain options. A toolchain file is a CMake script that defines cross-compilation environment and sets necessary CMake variables. To use a toolchain file, run CMake with "-DCMAKE_TOOLCHAIN_FILE" option and path to toolchain file, like this −

cmake -DCMAKE_TOOLCHAIN_FILE=/path/to/toolchain/file ...

Conclusion

In this article, we discussed a common issue that developers face while configuring a CMake project with Qt5 on Linux, i.e. "CMake configure fails to find Qt5". We discussed common reasons for issue and solutions to issue, such as correcting installation, setting environment variables, updating path and FindQt5.cmake module, and installing required Qt5 components. By following solutions discussed in this article, developers can overcome issue and configure their CMake project with Qt5 on Linux.