CMake configure fails to find Qt5 on Linux

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. Qt5 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: CMake configure fails to find Qt5.

Understanding the Issue

When we configure a CMake project with Qt5, CMake needs to find the Qt5 package, which includes required libraries, header files and other necessary files. CMake uses the find_package(Qt5) command to search for Qt5. This command searches for Qt5 installation directory in system environment variables, CMAKE_PREFIX_PATH and Qt5_DIR.

However, sometimes CMake fails to find the Qt5 package, even when Qt5 is installed on the system. This can happen due to several reasons, such as incorrect installation, missing environment variables, or incorrect paths.

Common Reasons for Failure

• Incorrect Installation CMake needs to know the location of Qt5 installation directory to find required files. If Qt5 is not installed correctly, it can lead to CMake failing to find the package.

• Missing Environment Variables CMake uses system environment variables to find Qt5 package. If environment variables are missing or incorrectly set, CMake fails to locate the installation.

• Incorrect Path If the path to Qt5 installation directory is incorrect, CMake cannot find the package. The correct path must be added to environment variables and CMake configuration.

• Missing Qt5 Components Qt5 is a modular framework, and you need to install required components for your project. If required components are missing, CMake fails to find the package.

Solutions

1. Verify Qt5 Installation

First, verify that Qt5 is installed correctly by checking the version:

qmake -v

If Qt5 is installed correctly, you should see the version number in the output.

2. Set Environment Variables

Set the necessary environment variables to point to your Qt5 installation:

export CMAKE_PREFIX_PATH=/path/to/qt5:$CMAKE_PREFIX_PATH
export Qt5_DIR=/path/to/qt5/lib/cmake/Qt5
export PATH=/path/to/qt5/bin:$PATH

Replace /path/to/qt5 with the actual path to your Qt5 installation directory.

3. Configure CMakeLists.txt

In your CMakeLists.txt file, explicitly set the Qt5 directory and use the proper find_package command:

# Set Qt5 directory (if needed)
set(Qt5_DIR "/path/to/qt5/lib/cmake/Qt5")

# Find Qt5 package with required components
find_package(Qt5 REQUIRED COMPONENTS Core Widgets Gui)

# Link Qt5 libraries to your target
target_link_libraries(your_target Qt5::Core Qt5::Widgets Qt5::Gui)

4. Install Qt5 Development Packages

On Ubuntu/Debian systems, install the Qt5 development packages:

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

On Red Hat/CentOS systems:

sudo yum install qt5-qtbase-devel qt5-qtdeclarative-devel

Additional Troubleshooting Tips

• Clear CMake Cache Delete the CMake cache file and regenerate it to remove any cached incorrect values:

rm -rf CMakeCache.txt CMakeFiles/

• Use pkg-config On Linux systems with pkg-config support, you can verify Qt5 installation:

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

• Specify Qt5 Path Directly Pass the Qt5 directory directly to CMake during configuration:

cmake -DQt5_DIR=/path/to/qt5/lib/cmake/Qt5 ..

Example CMake Configuration

Here's a complete example of a working CMakeLists.txt file for a Qt5 project:

cmake_minimum_required(VERSION 3.10)
project(MyQt5App)

set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Find Qt5 components
find_package(Qt5 REQUIRED COMPONENTS Core Widgets Gui)

# Add executable
add_executable(MyQt5App main.cpp mainwindow.cpp)

# Link Qt5 libraries
target_link_libraries(MyQt5App Qt5::Core Qt5::Widgets Qt5::Gui)

Conclusion

CMake failing to find Qt5 on Linux is typically caused by missing environment variables, incorrect installation paths, or missing development packages. By setting proper environment variables, installing the correct Qt5 development packages, and configuring CMakeLists.txt correctly, developers can resolve this issue and successfully configure their CMake projects with Qt5.