用CLion和CMake搭建DolphinDB插件开发环境

2021-12-01知识

本文以window 10为例，介绍了如何用CLion和CMake搭建DolphinDB插件开发环境，然后结合实例讲解如何用CLion调试插件代码，以帮助初学者快速入门DolphinDB插件开发。Clion能Attach DolphinDB节点进程并用图形界面进行调试，相比gdb的命令行调试，简单友好，大大降低了开发者调试DolphinDB插件的难度。

1 环境准备

1.1 安装和配置MinGW

MinGW中包含gcc,g++等多种编译器，可从其官网下载，下载时请选择 x86_64-posix-seh 版本（posix表示启用了C++ 11 多线程特性，seh表示异常分支处理零开销，以与DolphinDB server保持一致），然后手动添加环境变量。下载地址：

为节省篇幅，具体的安装细节请参阅：windows下安装mingw-w64 - tnnmigga - 博客园。

解压时尽量解压在某个盘的根目录。

将MinGW下bin目录的路径添加到环境变量中。

验证是否配置成功，按win+r运行cmd或者powershell输入gcc -v，出现如下图所示版本信息即表明MinGW安装成功，否则需要再检查一下。

避坑指南：我曾下载安装x86_64-posix-sjlj 版本，编译某些插件比如DolphinDB官网上的mqtt插件成功，但加载插件失败，提示：The specified module could not be found。因此碰到这种错误时，请检查MinGW的版本是不是x86_64-posix-seh版本。

1.2 安装CMAKE

下载链接： https:// cmake.org/download/

选择一个后缀为.msi的安装包下载，如下图划线所示：

下载后双击安装，安装时记得勾选「Add CMake to the system PATH for all users」，这样就不用自己再配置环境变量了。

安装后按win+r运行cmd或者powershell输入cmake -v,出现如下图所示版本信息即表明安装成功：

1.3 CLion安装

下载链接：https://www. jetbrains.com/clion/dow nload

选择windows .exe下载，下载后鼠标双击CLion-2021.2.3.exe（我下载的版本是2021.2.3，版本不同，文件名相应而变），然后一路点击Next即可完成安装，非常简单。

安装后，打开CLion，进入下图点击Activate CLion输入激活码，或点击Start trial开始试用。CLion是收费软件，可以点击下图中的Buy license购买激活码，若是教师或学生，可以申请Free Educational Licenses免费使用。

1.4 安装Git

下载链接：Git - Downloading Package

下载后双击一路默认安装即可，在cmd中运行git --version，显示如下图所示版本信息即表明安装成功。

1.5 部署DolphinDB集群和客户端软件

若本机没有部署DolphinDB节点和GUI客户端。请按单节点部署教程部署和启动一个单节点，版本选择目前最新版1.30.14版本。GUI请从官网下载页面的 其它资源下载 列表第一个链接获取GUI的安装包，并按客户端软件教程和启动。

2 下载插件代码

插件代码链接：dolphindb/DolphinDBPlugin

其中的include子目录包含了DolphinDB的核心数据结构的类声明和一些工具类声明，这些类是实现插件的重要基础工具。其他子目录如odbc与mysql等包含了ODBC与MySQL等各插件的源码，在我们写插件时可参考它们的实现方法。

如下图所示，在cmd中运行git clone -b release130 https:// gitee.com/dolphindb/Dol phinDBPlugin.git 即可下载。

注意：插件分支应与DolphinDB Server的版本相匹配，即若DolphinDB Server是1.30版本，插件应用release130分支，若DolphinDB Server是2.00版本，插件应该用release200分支，其他版本依此类推。

3 编写一个插件

3.1 案例需求

导入二进制格式的level2股票行情文件到数据库中，这些股票行情数据文件有个特点，就是每个文件中包含：快照、逐笔成交和逐笔委托三种类型数据，我们需要把不同类型的数据分别倒入不同的表中。文件存储格式如下：

struct zb_tick { int type; union { struct ss_quote hq; struct ss_transaction ts; struct ss_order_onebyone o_one; } data; };

其中type为0时，表示快照数据，type为2时表示逐笔成交数据，type为3时表示逐笔委托数据。具体格式参见

cy_struct.h

6.8K

百度网盘

样本数据文件参见

600519.SH.dat

30.9M

百度网盘

3.2 编写插件格式文件

3. 2.1 基本概念

插件函数分运算符函数（operator function）和系统函数（system function）2种类型，区别在于，前者接受的参数个数小于等于2，而后者可以接受任意个参数，并支持会话的访问操作。

开发一个运算符函数，需要编写一个原型为 ConstantSP (const ConstantSP& a, const ConstantSP& b) 的C++函数。当函数参数个数为2时，a 和 b 分别为插件函数的第一和第二个参数；当参数个数为1时，b 是一个占位符，没有实际用途；当没有参数时，a 和 b 均为占位符。

开发一个系统函数，需要编写一个原型为 ConstantSP (Heap* heap, vector& args) 的C++函数。用户在DolphinDB中调用插件函数时传入的参数，都按顺序保存在C++的向量 args 中。heap 参数不需要用户传入。

函数原型中的 ConstantSP 可以表示绝大多数DolphinDB对象（标量、向量、矩阵、表，等等）。其他常用的派生自它的变量类型有 VectorSP（向量）以及 TableSP（表）等。

3.2.2 格式要求

DolphinDB使用一个文本文件来描述插件。该文件格式如下：首行描述插件名字和共享库文件名，其后每一行都描述一个共享库函数和DolphinDB函数的映射关系。

module name, lib file function name in lib, function name in DolphinDB, function type, minParamCount, maxParamCount, isAggregate

其中：

module name: 表示模块名

lib file: 表示共享文件库文件名

function name in lib: 表示共享库中导出的函数名

function name in DolphinDB: 表示DolphinDB中的对应函数名

function type: 表示operator或者system函数类型

minParamCount: 最少参数个数

maxParamCount：最多参数个数

isAggregate: 是否为聚合函数

3.2.3 案例格式设计

格式文件内容如下：

loadBinaryQuotes,libPluginLoadBinQuotes.dll getTables,loadBin,system,1,1,0

即设计模块名为loadBinaryQuotes，共享文件库文件名为libPluginLoadBinQuotes.dll（若linux下为libPluginLoadBinQuotes.so），共享库中导出的函数名为getTables，DolphinDB中的对应函数名为loadBin，此函数为系统函数，参数为1个，非聚合函数。

3.3 用CLion创建工程

步骤1.先在创建DolphinDBPlugin目录下创建loadBinaryQuotes子目录，把3.2节设计的格式文件放到这个子目录下，并创建一个子目录src用于存放源代码文件，把3.1节提到的cy_struct.h放到src目录下。

步骤2. 打开CLion，点击New project，然后选择在左侧栏选择C++ Library，在右栏输入如下：

在上图中输入完成后，点击右下角的Create，这时会弹出一个对话框说目录下非空，选择Create from Existing Sources即可。

这时CLion会生成工程如下图：

它自动生成了library.h/.cpp和CMakeLists.txt。如果我们点击菜单Build/Build Project,是能编译成功的。但这里我们不要library.h/.cpp，所以选中它们，点鼠标右键，delete它们。然后在src目录下添加2文件export.h和export.cpp。

export.h主要用于导出动态库的函数，主要内容如下：

extern "C" ConstantSP getTables(Heap *heap, vector<ConstantSP> &args);

export.cpp主要用于实现插件函数getTables。两个文件具体参见：

export.cpp

9.2K

百度网盘

export.h

418

百度网盘

3.4 修改CMake文件CMakeList.txt

编写CMakeList.txt需要理解CMake的语法，学习CMake语法推荐通过例子学习CMake ，这是中译本，英语好的可直接学原项目例子。这里最简单的办法是参考已有插件的写法，比如opcua、mqtt等。修改本工程的cmake文件如下：

cmake_minimum_required(VERSION 3.20)#最低CMake版本 project(loadBinaryQuotes)# 工程名 if (WIN32 OR MINGW) set (platform_macro "-DWINDOWS") set (plugin_file "${CMAKE_CURRENT_LIST_DIR}/PluginLoadBinQuotes_win.txt") elseif (UNIX) set (platform_macro "-DLINUX") set (plugin_file "${CMAKE_CURRENT_LIST_DIR}/PluginLoadBinQuotes.txt") #为了兼容旧的编译器，libDolphinDB.so编译时使用了-D_GLIBCXX_USE_CXX11_ABI=0的选项，因此用户在编译插件的时候也应该加入该选项。若server是ABI=1的最新版，可不加。 add_compile_options("-D_GLIBCXX_USE_CXX11_ABI=0") endif () message("platform: ${platform_macro}") #添加编译选项：-std=c++11 -fPIC -DWINDOWS(linux系统为-DLINUX) add_compile_options("-std=c++11" "-fPIC" ${platform_macro} "-Wall") #包含目录 include_directories("../include") include_directories("./src") #包含库目录，libDolphinDB.dll所在目录，即安装DolphinDB的目录，请根据实际安装位置修改 link_directories(C:/DolphinDB/DolphinDB_Win64_V1.30.14/server) #库的源文件export.cpp生成动态库PluginLoadBinQuotes add_library(PluginLoadBinQuotes SHARED ./src/export.cpp) #链接库 target_link_libraries(PluginLoadBinQuotes DolphinDB ) #拷贝PluginLoadBinQuotes_win.txt(if windows)/PluginLoadBinQuotes.txt(if Linux)到build目录（这里为cmake-build-debug子目录） add_custom_command( TARGET PluginLoadBinQuotes POST_BUILD COMMAND ${CMAKE_COMMAND} -E copy ${plugin_file} ${CMAKE_BINARY_DIR}/PluginLoadBinQuotes.txt COMMENT "copy PluginLoadBinQuotes.txt")

修改后，建议重新生成Makefile：点击下图中1位置的CMake,然后点击2位置的图标，在弹出菜单项中选择Reset Cache and Reload Project。