Linux Qt6 安装教程及错误解决

在Linux环境，通常为Ubuntu，安装Qt开发环境，与Windows安装相比，还是稍显繁琐，需要多做几个步骤。

这里的Ubuntu版本采用的是ubuntu-22.04.2-desktop-amd64，所以，比旧版本会少很多坑，但本文会尽量写出可能遇到的坑。

下载Qt在线安装包

这里采用镜像地址进行下载，避免网络过慢。
镜像地址：http://mirrors.ustc.edu.cn/qtproject/archive/online_installers/4.5/
选择最新版本下载，如截至目前最新版本为qt-unified-linux-x64-4.5.2-online.run文件

安装必需环境

Debian/Ubuntu (apt-get)

sudo apt-get install build-essential libgl1-mesa-dev

Fedora/RHEL/CentOS (yum)

sudo yum groupinstall "C Development Tools and Libraries"
sudo yum install mesa-libGL-devel

运行安装程序

首先需要增加执行权限，才能运行。

chmod +x qt-unified-linux-x64-4.5.2-online.run
./qt-unified-linux-x64-4.5.2-online.run

为了使用国内镜像源安装可以使用以下方法：

（推荐）新版本的安装器（4.0.1-1 后）支持 --mirror 命令行参数。在命令行中执行安装器，添加 --mirror https://mirrors.ustc.edu.cn/qtproject 参数。

例如 Windows 下执行当前目录的安装器的命令为

.\qt-unified-windows-x86-online.exe --mirror https://mirrors.ustc.edu.cn/qtproject

Linux为：

./qt-unified-linux-x64-4.5.2-online.run --mirror https://mirrors.ustc.edu.cn/qtproject

或在启动安装器后在设置中禁用默认源，添加新源

 http://mirrors.ustc.edu.cn/qtproject/online/qtsdkrepository/linux_x64/root/qt/ （其他版本注意更改地址）。

安装过程中可能遇到的错误：

在执行run文件时

$ ./qt-unified-linux-x64-4.5.2-online.run 
./qt-unified-linux-x64-4.5.2-online.run: error while loading shared libraries: libxcb-xinerama.so.0: cannot open shared object file: No such file or directory

安装libxcb-xinerama0解决问题

sudo apt install libxcb-xinerama0

之后就是熟悉的安装界面了

下载所需的Qt版本即可，这里我选择的是最新的Qt 6.5

运行demo可能遇到的问题

以下问题均在Ubuntu-22.04.2 Qt 6.5 版本中遇到的问题，对于低版本也具有参考性。

Could NOT find XKB (missing: XKB_LIBRARY XKB_INCLUDE_DIR) (Required is at least version “0.5.0”)

安装

sudo apt install libxkbcommon-dev

The link interface of target “Qt6::GuiPrivate” contains: XKB::XKB but the target was not found

CMake Error at /home/leo/Qt/6.5.0/gcc_64/lib/cmake/Qt6Gui/Qt6GuiTargets.cmake:93 (set_target_properties):
  The link interface of target "Qt6::GuiPrivate" contains:

    XKB::XKB

  but the target was not found.  Possible reasons include:

    * There is a typo in the target name.
    * A find_package call is missing for an IMPORTED target.
    * An ALIAS target is missing.

Call Stack (most recent call first):
  /home/leo/Qt/6.5.0/gcc_64/lib/cmake/Qt6Gui/Qt6GuiConfig.cmake:52 (include)
  /home/leo/Qt/6.5.0/gcc_64/lib/cmake/Qt6/Qt6Config.cmake:157 (find_package)
  src/CMakeLists.txt:7 (find_package)


-- Generating done (0.0s)
CMake Generate step failed.  Build files cannot be regenerated correctly.

安装

sudo apt install libxkbcommon-dev

Could NOT find WrapVulkanHeaders (missing: Vulkan_INCLUDE_DIR)

sudo apt install libvulkan-dev

Qt6Gui could not be found because dependency WrapOpenGL could not be found

当安装完成之后，运行第一个helloworld程序，无法正常运行。

会遇到如下错误：

CMake Warning at /usr/local/share/cmake-3.26/Modules/CMakeFindDependencyMacro.cmake:76 (find_package):
  Found package configuration file:                 
    /home/Leo/Qt/6.5.0/gcc_64/lib/cmake/Qt6Gui/Qt6GuiConfig.cmake                                             
  but it set Qt6Gui_FOUND to FALSE so package "Qt6Gui" is considered to be NOT FOUND.  Reason given by package:                                                                   
  Qt6Gui could not be found because dependency WrapOpenGL could not be found.                                 
  Configuring with --debug-find-pkg=WrapOpenGL might reveal details why the package was not found.                                                                                 
  Configuring with -DQT_DEBUG_FIND_PACKAGE=ON will print the values of some of the path variables that find_package uses to try and find the package.                                   

Call Stack (most recent call first):                                                                     /home/Leo/Qt/6.5.0/gcc_64/lib/cmake/Qt6/QtPublicDependencyHelpers.cmake:111 (find_dependency)               
/home/Leo/Qt/6.5.0/gcc_64/lib/cmake/Qt6Widgets/Qt6WidgetsDependencies.cmake:39 (_qt_internal_find_qt_dependencies)                                                                                               /home/Leo/Qt/6.5.0/gcc_64/lib/cmake/Qt6Widgets/Qt6WidgetsConfig.cmake:40 (include)                          
/home/Leo/Qt/6.5.0/gcc_64/lib/cmake/Qt6/Qt6Config.cmake:157 (find_package)                                  
  CMakeLists.txt:15 (find_package)                                                                       
CMake Warning at /home/Leo/Qt/6.5.0/gcc_64/lib/cmake/Qt6/Qt6Config.cmake:157 (find_package):
  Found package configuration file:                 
    /home/Leo/Qt/6.5.0/gcc_64/lib/cmake/Qt6Widgets/Qt6WidgetsConfig.cmake                                   
   
  but it set Qt6Widgets_FOUND to FALSE so package "Qt6Widgets" is considered to be NOT FOUND.  Reason given by package:                                    
  Qt6Widgets could not be found because dependency Qt6Gui could not be found.                                 
                                                                                                              
  Configuring with --debug-find-pkg=Qt6Gui might reveal details why the  package was not found.                                                                                 
  Configuring with -DQT_DEBUG_FIND_PACKAGE=ON will print the values of some                                   
  of the path variables that find_package uses to try and find the package.                           
Call Stack (most recent call first):                                                                     
  CMakeLists.txt:15 (find_package)                                                                            
                                                     
CMake Error at CMakeLists.txt:15 (find_package):
  Found package configuration file:                                                                     
    /home/Leo/Qt/6.5.0/gcc_64/lib/cmake/Qt6/Qt6Config.cmake                                                   

  but it set Qt6_FOUND to FALSE so package "Qt6" is considered to be NOT FOUND.  Reason given by package:                                                                                                                    
  Failed to find required Qt component "Widgets".                                                       
  Expected Config file at                                                                               "/home/Leo/Qt/6.5.0/gcc_64/lib/cmake/Qt6Widgets/Qt6WidgetsConfig.cmake"                                     
  exists                                                                                                      

  Configuring with --debug-find-pkg=Qt6Widgets might reveal details why the package was not found.                                                                                 
  Configuring with -DQT_DEBUG_FIND_PACKAGE=ON will print the values of some of the path variables that find_package uses to try and find the package.

原因是因为没有按照第一步安装环境，缺失libgl1-mesa-dev

使用sudo apt install libgl1-mesa-dev安装之后，即可正常运行。

安装Qt 5.15.2程序无法运行

报错信息：

qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found.
This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem.

Available platform plugins are: eglfs, linuxfb, minimal, minimalegl, offscreen, vnc, wayland-egl, wayland, wayland-xcomposite-egl, wayland-xcomposite-glx, xcb.

这是Qt 5.15.2的一个bug，动态库依赖libxcb-util.so.1，但实际上没有这个动态库链接，故创建一个链接即可。

sudo ln -s /usr/lib/x86_64-linux-gnu/libxcb-util.so.0.0.0 /usr/lib/x86_64-linux-gnu/libxcb-util.so.1

https://doc.qt.io/qt-6/linux.html

https://wiki.qt.io/Install_Qt_5_on_Ubuntu