QGIS 二次开发笔记(1)——环境配置
众所周知,QGIS是一个用户界面友好的桌面地理信息系统,可运行在Linux、Unix、Mac OSX和Windows等平台之上。 QGIS 基于 Qt 开发,除了提供可执行程序,还提供了一套用于二次开发的接口,可进行跨平台地理信息系统软件的定制开发。
正如所有的开发都是从安装编译器开始的,所有的二次开发都是从配置环境开始的。 然而,QGIS 的开发环境实属难配,如果要配置可调试的 Debug 环境更是难上加难。 经过了一段时间的开发之后,笔者总结了 QGIS 开发环境配置的基本过程,以及容易遇到的坑,在这里和大家分享。
Release 版开发环境配置
Release 版开发环境配置相对比较简单,可以使用 OSGeo4W 直接下载各种预编译好的库。 除了下载比较慢以外,基本不会遇到其他问题。
使用 OSGeo4W 安装相关库
在 OSGeo4W 官网下载安装程序后,即可进行安装。
- 安装方式选择 Advanced Install
- 安装源选择 Install from Internet ,当然如果是帮别人装可以选择 Download Without Installing ,如果用别人下载好的可以 Install from Local Directory
- 安装目录可以自己选
- 本地包下载路径可以自己选,安装完后就会删除
- 网络连接方式,如果没有梯子,就可以选择 Direct Connection ;有的话可以选择 Use IE5 Settings 直接导入系统代理配置,或者选择 Use HTTP/FTP Proxy 自己定义代理
- 然后会下载一些包,进入到下载点选择,可以直接选择 http://download.osgeo.org 那个。如果觉得网速比较慢,可以使用 GWmodel 实验室提供的 OSGeo4W 的镜像,在 User URL 里面输入 http://gwmodel.whu.edu.cn/mirrors/osgeo4w 然后点击 Add 按钮即可添加。
- 安装内容,可以在搜索框里面输入 qgis 进行搜索。可以看到有多种 qgis 版本安装包。综合各种因素考虑,最好是选择 qgis-rel-dev 这个版本的包,这个包是最新的 QGIS Release 版本的源代码(这里我之前安装了 qgis-dev)。点击 Skip 按钮选择版本号。OSGeo4W 会自动下载各种依赖包。
- 点击下一步后,要同意一些用户协议,之后即可进行安装。
Qt 安装
为什么先说 OSGeo4W 安装再说 Qt 安装呢?因为 Qt 要安装的版本与 OSGeo4W 中安装的版本有关。 我们首先要查看已经安装了的 Qt 版本号,然后再安装对应的 Qt 开发工具。
当然,如果你不准备进行 Debug 环境的配置,那么其实可以只安装一个 Qt Creator 等相关工具。 开发的时候直接使用 OSGeo4W 安装的 Qt 库进行开发。
工程中引用
工程引用其实非常简单,只需要在 pro 文件中加入 include 和 lib 的生命引用即可,此外再加一个 GDAL 的配置。
1 | ## QGIS |
这里面引用了一个 OSGEO_HOME
的环境变量,可以将这个变量设置到系统环境变量中,或者加入到工程环境变量中,变量值就是 OSGeo4W 的安装目录。
运行配置
该部分主要参考知乎文章 QtCreator进行QGis二次开发(1) ,有修改。
我们编译好自己的工程,运行的时候会提示缺 DLL 。常用的方法就是把需要的 DLL 放到工程生成的可执行程序目录下。主要需要这些 DLL :(为了描述方便,我直接写我的 Qt 工具的路径 C:/Qt/5.11.2/msvc2017_64 )
- 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 同级目录下(示例图中采用的是这种方法)。
- OSGeo4W 安装的 DLL 。直接把 $(OSGEO_HOME)/bin 下的 DLL 拷过来。
- QGIS 相关的 DLL 。直接把 $(OSGEO_HOME)/apps/qgis-rel-dev/bin 下的 DLL 拷过来。
- QGIS 相关的 plugins 。直接把 $(OSGEO_HOME)/apps/qgis-rel-dev/plugins 下的 DLL 拷过来。
此外还有一些资源文件,主要有
- $(OSGEO_HOME)/share/gdal 文件夹拷贝到工程生成的 exe 文件同级 share 目录下(如果没有就新建一个)
- $(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 文件:
- qca (非常重要,必须编译)
- qwt (最好编译)
- qtkeychain (最好编译,但理论上可以不编译)
- 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 还是出错,就采用以下三种方式解决:
- 从 OSGeo4W 中下载相应的库文件
- 自己编译以提供相应的库文件
- 推荐做法:关闭相关的 WITH 选项
编译后
如果使用 VS 编译的,那么有 INSTALL 工程可以直接安装。如果是 QT 编译的,那么就手动把 dll 和 lib 等库拷贝出来吧, include 文件可以使用 qgis-rel-dev 的。还有 resource 文件夹别忘了。
至此,所有 QGIS 开发的环境配置已经完成了。