QGIS 二次开发笔记（1）——环境配置

QGIS 二次开发笔记（1）——环境配置

  • 2020-03-28

众所周知，QGIS是一个用户界面友好的桌面地理信息系统，可运行在Linux、Unix、Mac OSX和Windows等平台之上。 QGIS 基于 Qt 开发，除了提供可执行程序，还提供了一套用于二次开发的接口，可进行跨平台地理信息系统软件的定制开发。

正如所有的开发都是从安装编译器开始的，所有的二次开发都是从配置环境开始的。 然而，QGIS 的开发环境实属难配，如果要配置可调试的 Debug 环境更是难上加难。 经过了一段时间的开发之后，笔者总结了 QGIS 开发环境配置的基本过程，以及容易遇到的坑，在这里和大家分享。

Release 版开发环境配置

Release 版开发环境配置相对比较简单，可以使用 OSGeo4W 直接下载各种预编译好的库。 除了下载比较慢以外，基本不会遇到其他问题。

使用 OSGeo4W 安装相关库

在 OSGeo4W 官网下载安装程序后，即可进行安装。

  1. 安装方式选择 Advanced Install
  2. 安装源选择 Install from Internet ，当然如果是帮别人装可以选择 Download Without Installing ，如果用别人下载好的可以 Install from Local Directory
  3. 安装目录可以自己选
  4. 本地包下载路径可以自己选，安装完后就会删除
  5. 网络连接方式，如果没有梯子，就可以选择 Direct Connection ；有的话可以选择 Use IE5 Settings 直接导入系统代理配置，或者选择 Use HTTP/FTP Proxy 自己定义代理
  6. 然后会下载一些包，进入到下载点选择，可以直接选择 http://download.osgeo.org 那个。如果觉得网速比较慢，可以使用 GWmodel 实验室提供的 OSGeo4W 的镜像，在 User URL 里面输入 http://gwmodel.whu.edu.cn/mirrors/osgeo4w 然后点击 Add 按钮即可添加。
  7. 安装内容，可以在搜索框里面输入 qgis 进行搜索。可以看到有多种 qgis 版本安装包。综合各种因素考虑，最好是选择 qgis-rel-dev 这个版本的包，这个包是最新的 QGIS Release 版本的源代码（这里我之前安装了 qgis-dev）。点击 Skip 按钮选择版本号。OSGeo4W 会自动下载各种依赖包。
  8. 点击下一步后，要同意一些用户协议，之后即可进行安装。

Qt 安装

为什么先说 OSGeo4W 安装再说 Qt 安装呢？因为 Qt 要安装的版本与 OSGeo4W 中安装的版本有关。 我们首先要查看已经安装了的 Qt 版本号，然后再安装对应的 Qt 开发工具。

当然，如果你不准备进行 Debug 环境的配置，那么其实可以只安装一个 Qt Creator 等相关工具。 开发的时候直接使用 OSGeo4W 安装的 Qt 库进行开发。

工程中引用

工程引用其实非常简单，只需要在 pro 文件中加入 include 和 lib 的生命引用即可，此外再加一个 GDAL 的配置。

1
2
3
4
5
6
7
## QGIS
INCLUDEPATH += "$(OSGEO_HOME)/include"
INCLUDEPATH += "$(OSGEO_HOME)/apps/qgis-rel-dev/include"
LIBS += -L"$(OSGEO_HOME)/apps/qgis-rel-dev/lib" -lqgis_core -lqgis_gui
LIBS += -L"$(OSGEO_HOME)/lib" -lgdal_i
GDAL_DATA = ".\share\gdal"
## QGIS END

这里面引用了一个 OSGEO_HOME 的环境变量，可以将这个变量设置到系统环境变量中，或者加入到工程环境变量中，变量值就是 OSGeo4W 的安装目录。

运行配置

该部分主要参考知乎文章 QtCreator进行QGis二次开发（1） ，有修改。

我们编译好自己的工程，运行的时候会提示缺 DLL 。常用的方法就是把需要的 DLL 放到工程生成的可执行程序目录下。主要需要这些 DLL ：（为了描述方便，我直接写我的 Qt 工具的路径 C:/Qt/5.11.2/msvc2017_64 ）

  1. Qt 相关的 DLL 。可以使用 Qt 提供的 windeploy 工具直接部署。但是由于 QGIS 所引用的 DLL 用这个工具是无法部署过来的，因此还需要将缺少的 C:/Qt/5.11.2/msvc2017_64/bin 中的 DLL 拷贝过来（注意不需要以 d.dll 结尾的动态链接库）。如果嫌 windeploy 麻烦，可以直接将 C:/Qt/5.11.2/msvc2017_64/bin 的 DLL 拷贝过来，然后再把 C:/Qt/5.11.2/msvc2017_64/plugins 文件夹拷贝到工程生成的 exe 同级目录下（示例图中采用的是这种方法）。
  2. OSGeo4W 安装的 DLL 。直接把 $(OSGEO_HOME)/bin 下的 DLL 拷过来。
  3. QGIS 相关的 DLL 。直接把 $(OSGEO_HOME)/apps/qgis-rel-dev/bin 下的 DLL 拷过来。
  4. QGIS 相关的 plugins 。直接把 $(OSGEO_HOME)/apps/qgis-rel-dev/plugins 下的 DLL 拷过来。

此外还有一些资源文件，主要有

  1. $(OSGEO_HOME)/share/gdal 文件夹拷贝到工程生成的 exe 文件同级 share 目录下（如果没有就新建一个）
  2. $(OSGEO_HOME)/apps/qgis-rel-dev/resources 文件夹拷贝到工程生成的 exe 文件目录下。

此外还有一个运行时的环境变量 PROJ_LIB 需要配置，配置到 $(OSGEO_HOME)/apps/proj-dev/share/proj 目录即可。如果没有这个目录，就配置到 $(OSGEO_HOME)/share/proj 。这个主要是版本的问题。

如果后面开发中遇到了无法进行投影转换的问题，而且有 proj.db 相关数据库查询的保存，则很有可能就是这个 PROJ_LIB 变量的位置配错了，配成了不同版本的。因为 Proj 7.0 版本的数据库和 6.x 版本的数据库不一样。

这样我们的程序就可以运行了。

Debug 版环境的配置

事先声明：笔者编译出了 DEBUG 版可以执行的 qgis.exe ，但是不知道什么原因无法加载了 qgis_app.dll 因而无法运行。但是编译出来的库是可以在二次开发中使用的。

因为 OSGeo4W 只提供了 Release 版的库，如果要 Debug 版需要自己编译。整个过程没有那么复杂，但是容易遇到一些奇奇怪怪的问题。

首先需要下载 QGIS 最新 Release 版本的代码。你会发现最新 Release 的代码和 qgis-rel-dev 的版本是一致的，这就是之前选择 qgis-rel-dev 的原因。

然后用 Qt Creator 打开这个库的 CMakeList.txt 文件，就开始进行 CMake 工程的配置。

配置之前的准备

配置之前要提前编译如下库的 Debug 版本的 lib 文件和 dll 文件：

  1. qca （非常重要，必须编译）
  2. qwt （最好编译）
  3. qtkeychain （最好编译，但理论上可以不编译）
  4. expat （可以不编译）

这些库基本都有 CMakeList.txt 文件，因此可以直接使用 Qt Creator 打开编译。但是如果用 CMake GUI 配置好生成 VS 解决方案，用 VS 打开进行编译，你会发现有一个 BUILD_ALL 和 INSTALL 项目，编译好后直接生成这个项目，就可以安装到 CMake 配置时 INSTALL_PREFIX 变量指定的目录。

理论上，Debug 程序是可以调用 Release 版本的库的，但是在 GUI 环境下，混用 Debug 和 Release 的库会导致程序崩溃。对于 QCA ，如果使用了 Release 版本的 QCA 库，那么程序运行的时候在初始化 QCA 的时候就会发生崩溃。所以 QCA 必须编译 DEBUG 版本。qwt 和 qtkeychain 最好也编译一下，毕竟也不麻烦。但是 qtkeychain 好像并不涉及 GUI ，如果嫌麻烦可以不编译。expat 库纯粹是因为其 release 和 debug 版本的库文件名不一样，可能 DEBUG 和 RELEASE 有区别，因此我编译了一下，但是直接用 OSGeo4W 的应该也是可以的。

至于如何编译这些库，网上有其他教程，这是个体力活，这里就不赘述了。

还要安装 Cygwin ，并且安装如下两个工具。安装完记得把 Cygwin/bin 目录添加到 PATH 环境变量中。

  • bison
  • flex

还需要安装 ninja.exe 并拷贝到 $(OSGEO_HOME)/bin （其实理论上放到系统 PATH 环境变量包含的目录中都可以）。

编译配置

打开 QGIS 的 CMakeLists.txt 文件，会有许多东西需要配置，因为所有的依赖库都要指定其 INCLUDE_DIR 和 LIBRARY 。用 OSGeo4W 安装的库都可以这样指定

自己编译的库也用类似的方式指定就可以了。

选择 WITH_QTWEBKIT 最好去掉，因为在 Qt 5.5 以后的版本中已经去掉了 QtWebKit 组件。虽然下个版本会加回来。选择 WITH_BINDINGS（Python 相关模块）、WITH_SERVER、WITH_POSTGRE 如果不需要相关的功能就可以去掉，如果勾选的话就需要相关的库。

选项 WITH_INTERNEL_MDAL 可以勾上，让 QGIS 自己编译 MDAL，当然就需要指定 HDF5、NetCDF 等库的位置，如果没有这些库可以从 OSGeo4W 中安装。如果关闭，那就自己编译 MDAL，然后提供 MDAL_INCLUDE_DIR 和 MDAL_LIBRARY 。

还要注意，如果勾选了 WITH_INTERNEL_MDAL 要给 CMAKE_CXX_FLAGS 开头的几个变量后面要添加 /D H5_BUILT_AS_DYNAMIC_LIB" 选项，否则无法编译。另外，需要在这几个变量中加上 /utf-8 选项，否则会报告“常量中有换行符”等错误。

然后代码基本就可以编译了。如果 CMAKE 还是出错，就采用以下三种方式解决：

  1. 从 OSGeo4W 中下载相应的库文件
  2. 自己编译以提供相应的库文件
  3. 推荐做法：关闭相关的 WITH 选项

编译后

如果使用 VS 编译的，那么有 INSTALL 工程可以直接安装。如果是 QT 编译的，那么就手动把 dll 和 lib 等库拷贝出来吧， include 文件可以使用 qgis-rel-dev 的。还有 resource 文件夹别忘了。

至此，所有 QGIS 开发的环境配置已经完成了。

感谢您的阅读，本文由 HPDell 的个人博客 版权所有。如若转载，请注明出处：HPDell 的个人博客（http://hpdell.github.io/编程/qgisdev1-build/）
测试使用 StackEdit 更新博客
QGIS 二次开发笔记（2）——显示图层