自己动手编译QGIS 3.18源代码，含出错大全和解决办法

从2月19日开始打包，到2月23日，QGIS 3.18的安装包经过漫长的4天才完成打包，在这等待的4天里，大家有没有像我一样萌生出自己动手编译源代码的想法呢？今天想分享的是QGIS3.18源代码编译的过程，并在最后整理出编译过程遇到的错误和解决办法。

 

 01 编译环境

 

• 操作系统

 

本次编译选用Ubuntu 20.04操作系统，理由如下：

 

从第一个版本开始，QGIS大部分开发是在Linux环境下进行的，与Linux系统的兼容性更好（实际上，我在Windows系统也试着编译过QGIS源码，编译环境的安装、编译过程难度比在Linux系统大得多）；

 

Ubuntu 20.04是一个与Windows系统相类似的、以桌面应用为主的Linux发行版本，对Linux新手来说比较符合操作习惯、易于上手。而且 20.04版本是Ubuntu的长期支持（LTS）版本，社区可提供5年的支持，比最新的20.10版稳定性和成熟度好很多。

 

• 其他编译环境

 

CMake：3.16.3

Flex ：2.6.4

Bison：3.5.1

Python：3.8.5

 

 02 下载源代码

 

建议将不同版本的QGIS源代码用单独的目录存放，打开命令行终端，输入如下命令，建立工作目录并切换到该目录：

 

mkdir -p ${HOME}/dev/QGIScd ${HOME}/dev/QGIS

 

下载源代码： 

 

wget https://github.com/qgis/QGIS/archive/final-3_18_0.tar.gz

 

解压缩下载回来的代码包：

 

tar -zxf QGIS-final-3_18_0.tar.gz

 

 03 安装依赖库

 

从Ubuntu系统的左下角的开始菜单打开一个命令行终端，参照github的“Building QGIS from source - step by step”文档（https://github.com/qgis/QGIS/blob/master/INSTALL.md），输入如下命令安装QGIS编译需要的依赖库：

 

sudo apt-get install bison ca-certificates ccache cmake cmake-curses-gui dh-python doxygen expect flex flip gdal-bin git graphviz grass-dev libexiv2-dev libexpat1-dev libfcgi-dev libgdal-dev libgeos-dev libgsl-dev libpdal-dev libpq-dev libproj-dev libprotobuf-dev libqca-qt5-2-dev libqca-qt5-2-plugins libqscintilla2-qt5-dev libqt5opengl5-dev libqt5serialport5-dev libqt5sql5-sqlite libqt5svg5-dev libqt5webkit5-dev libqt5xmlpatterns5-dev libqwt-qt5-dev libspatialindex-dev libspatialite-dev libsqlite3-dev libsqlite3-mod-spatialite libyaml-tiny-perl libzip-dev libzstd-dev lighttpd locales ninja-build ocl-icd-opencl-dev opencl-headers pdal pkg-config poppler-utils protobuf-compiler pyqt5-dev pyqt5-dev-tools pyqt5.qsci-dev python3-all-dev python3-autopep8 python3-dateutil python3-dev python3-future python3-gdal python3-httplib2 python3-jinja2 python3-lxml python3-markupsafe python3-mock python3-nose2 python3-owslib python3-plotly python3-psycopg2 python3-pygments python3-pyproj python3-pyqt5 python3-pyqt5.qsci python3-pyqt5.qtsql python3-pyqt5.qtsvg python3-pyqt5.qtwebkit python3-requests python3-sip python3-sip-dev python3-six python3-termcolor python3-tz python3-yaml qt3d-assimpsceneimport-plugin qt3d-defaultgeometryloader-plugin qt3d-gltfsceneio-plugin qt3d-scene2d-plugin qt3d5-dev qt5-default qt5keychain-dev qtbase5-dev qtbase5-private-dev qtpositioning5-dev qttools5-dev qttools5-dev-tools saga spawn-fcgi xauth xfonts-100dpi xfonts-75dpi xfonts-base xfonts-scalable xvfb

 

下载的时间视网络状况而定，有时候会达到几个小时，耐心等待就好。当所有软件包下载完成后，系统汇总需要安装的软件包信息，询问是否继续，输入 “Y”，回车，并等待所有依赖库安装完成。

 04 编译

 

接下来开始编译过程。依次执行如下命令，创建build目录，执行ccmake：

 

cd QGIS-final-3_18_0mkdir build-mastercd build-masterccmake ..

 

ccmake是一个图形化的配置界面，启动后界面如下：

 

 

注意：“ccmake ..”命令后一定要加上两个英文状态的点，表示要读取的CMakeLists.txt配置文件所在位置为当前目录的上一级目录。

 

按键盘“c”键，开始将CMakeLists.txt配置信息读取进来：

 

 

完成读入后，配置项和默认取值将显示在窗口中：

 

 

用键盘↑、↓箭头在配置项之间移动，如果想修改一个配置项的取值，按“Enter”键，在右边输入要设置的值，再回车确认修改。

 

我们可以先最简单的编译开始，按默认配置继续走下去。按键盘上的“c”键将配置生成缓存（注意，这里可能需要多次按“c”键）直到下方出现“Press [g] to generate and exit”选项：

 

 

按键盘“g”键，生成本地化的makefile：

 

 

完成后将自动退出ccmake界面，回到命令行终端。输入“make”命令，回车，开始编译可执行文件：

 

 

编译过程需要耗费很长时间，有多种加快编译的方法，例如，“make”命令后可加入处理器个数参数变为“make -j4”，4即处理器个数，多个处理器一起编译将提高速度。

 

 

耐心等待进度显示100%，此时我们完成了从源代码编译QGIS软件的整个过程。但是默认设置不包含三维，我们将在下一节详细讨论如何将三维模块加进来。

 

 05 编译三维模块

 

默认配置中，三维模块和3.18新增支持的内存数据库SAP HANA模块并没有启用，所以编译完成后得到的QGIS不包含三维浏览和SAP HANA数据库存储功能，如果需要使用这两个模块，在ccmake的配置阶段需将WITH_3D和WITH_HANA设置为“ON”。操作步骤为：

 

1. 使用上下箭头将光标移动到WITH_3D项，

2. 按回车键，将右边的取值从“OFF”切换到“ON”，

3. 同样的方法可设置WITH_HANA模块。

 

 

因为QGIS的三维模块需要Qt53DExtras的支持，加入额外的三维模块将显著增加编译的难度。默认情况下Debian发行版本的Qt模块中不包含Qt53DExtras，所以QGIS源代码仓库根目录下的external/qt3dextra-headers子目录自带了Qt53DExtras相关头文件。

 

在QGIS源代码编译中启用三维，需要配置5个编译选项把相关文件的路径传递给编译器：WITH_3D、CMAKE_PREFIX_PATH、QT5_3DEXTRA_INCLUDE_DIR、QT5_3DEXTRA_LIBRARY、Qt53DExtras_DIR，各选项的取值如下：

 

WITH_3D：TRUE；

CMAKE_PREFIX_PATH：｛QGIS源代码目录｝/external/qt3dextra-headers/cmake；

QT5_3DEXTRA_INCLUDE_DIR：｛QGIS源代码目录｝/external/qt3dextra-headers/；

QT5_3DEXTRA_LIBRARY：/usr/lib/x86_64-linux-gnu/libQt53DExtras.so；

Qt53DExtras_DIR：｛QGIS源代码目录｝/external/qt3dextra-headers/cmake/Qt53DExtras。

 

因为CMakeLists.txt中并没有包含上述所有参数，所以不能使用图形界面ccmake来配置参数，需要借助命令行的cmake命令，以我本次编译为例，运行的cmake命令为：

 

cmake -DWITH_3D=TRUE -DCMAKE_PREFIX_PATH=/home/wujianling/dev/QGIS-final-3_18_0/QGIS-final-3_18_0/external/qt3dextra-headers/cmake -DQT5_3DEXTRA_INCLUDE_DIR=/home/wujianling/dev/QGIS-final-3_18_0/QGIS-final-3_18_0/external/qt3dextra-headers -DQT5_3DEXTRA_LIBRARY=/usr/lib/x86_64-linux-gnu/libQt53DExtras.so -DQt53DExtras_DIR=/home/wujianling/dev/QGIS-final-3_18_0/QGIS-final-3_18_0/external/qt3dextra-headers/cmake/Qt53DExtras ..

 

 

拷贝这个命令时，注意把所有路径参数修改为自己电脑上对应路径，否则将会出现找不到文件的错误。另外，最后的两个英文状态的“..”不能省略！

 

 

完成配置后，使用“make”命令重新编译生成QGIS可执行文件。

 

注意：每次重新编译，都需要使用“rm -f ./*”命令将build-master目录下的所有之前编译生成的缓存清空，否则会遇到意想不到的错误。

 

 06 运行编译结果

 

在命令行终端运行“./output/bin/qgis”，将启动刚编译好的QGIS程序，当出现启动界面时，是不是很激动？

 

 

点击菜单【View】，如果出现【New 3D Map View】子菜单，点击弹出三维浏览窗口，说明三维模块已编译成功。

 

 

 07 出错大全和解决办法

 

这一节将列出这次编译过程所遇到的所有报错和解决办法，避免大家踩到相同的坑。

 

• 安装依赖库可能出现的问题及解决办法

 

权限不足

 

按照官网的编译步骤，使用“ apt-get install”命令安装依赖库时，如果当前登陆Ubuntu系统的用户不是root用户，会出现权限不足。

 

解决办法：在命令前加sudo，并按照提示输入当前用户的密码（注意，不是root用户的密码！）。

 

依赖库下载失败

 

这是最常见的问题，是网络连接不稳定导致，解决办法是重新运行前面安装依赖库命令“ apt-get install …”，Ubuntu将会跳过已经下载的软件包，将没有成功下载的包补下回来，然后继续安装过程。

 

 

Lighttpd错误

 

报错信息如下：

 

Job for lighttpd.service failed because  the control process exited with error code.

see "systemctl status lighttpd.service" and "journalctl -xe" for details.

invoke-rc.d:initscript lighttpd,action "start" failed.

 

这是lighttpd的一个bug，是由于lighttpd的配置中引用了gamin，而系统没有安装gamin引起。

 

安装gamin可消除该错误，命令如下：

 

sudo apt-get install gamin

 

• 编译中遇到的问题及解决办法

 

警告：Policy CMP0075 is not set：Include file check macros honor CMAKE_REQUIRED_LIBRARIES.

 

这是检查包含文件宏（Include file check macros）在不同cmake版本的执行策略。在cmake 3.12及以上版本，包含文件检查宏使用CMAKE_REQUIRED_LIBRARIES变量，cmake 3.11以下版本则使用CheckIncludeFile模块的check_include_file宏。

 

该警告在cmake 3.16.3版本可忽略，（但是不能保证将来的cmake版本仍然兼容），所以目前看到这个警告时，直接按“e”键继续即可。

 

 

错误：找不到C++编译器

 

报错信息：No CMAKE_CXX_COMPILER could be found。

 

 

这是因为Ubuntu 20.04默认没有安装g++编译器，运行下面命令安装：

 

sudo apt-get install build-essential

 

 

错误：找不到Qt53DExtras相关配置文件

 

报错信息：

 

Could not find a package configuration file provided by "Qt53DExtras" with any of the following names:

Qt53DExtrasConfig.cmake

qt53dextras-config.cmake

 

 

这是编译三维模块最常见错误，再次检查三维配置的相关选项：CMAKE_PREFIX_PATH、QT5_3DEXTRA_INCLUDE_DIR、QT5_3DEXTRA_LIBRARY、Qt53DExtras_DIR，其中，Qt53DExtras_DIR配置项指向的目录应包含Qt53DExtrasConfig.cmake或者qt53dextras-config.cmake，确保路径正确并且路径下包含这两个文件之一。

 

错误：找不到Qt5::3DExtras

 

报错信息：c++ error:Qt5::3DExtras-NOTFOUND: No  such file or directory。

 

C++编译进度到41%左右，如果出现c++ error:Qt5::3DExtras-NOTFOUND导致编译失败，则需要检查三维相关选项：CMAKE_PREFIX_PATH、QT5_3DEXTRA_INCLUDE_DIR、QT5_3DEXTRA_LIBRARY，使用带上述参数的“cmake”命令重新设置，确保指向的路径正确。

 

 

错误：找不到Qt3DExtrax/QCuboidMesh

 

报错信息：fatal error:Qt3DExtras/QCuboidMesh:No such file or directory。

 

这是编译进行到43%左右出现的错误，仍然是三维的问题，｛QGIS源代码目录｝/src/3d/qgsskyboxentity.h文件引用了Qt3DExtras/QCuboidMesh文件，然而/src/3d/目录下并没有Qt3DExtras/QCuboidMesh文件，所以出现错误。

 

 

解决办法是，到｛QGIS源代码目录｝/external/qt3dextra-headers/，将Qt3DExtras目录拷贝到｛QGIS源代码目录｝/src/3d/目录下。

 

 

QGIS 3.18源代码编译就介绍到这里，大家可以按照步骤试着编译，也可以尝试编译其他版本的QGIS源代码，编译过程中遇到的问题欢迎关注公众号并在后台留言一起讨论。

 

---

版权声明

 

本文欢迎转载，转载时请注明出处。