如何使用VS2017編譯DolphinDB C++ API動態庫

語言: CN / TW / HK

Microsoft Visual Studio 是微軟推出的一款功能強大的開發工具包,為各種平臺和語言的軟體開發提供了基本完整的工具集。本篇中我們將以VS2017 Release/x64 平臺為例,向大家簡要概述如何在 DolphinDB 搭建 C++ API 開發環境,並編譯相應動態庫。

本文示例的 DolphinDB C++ API 編譯配置如下:
編譯環境:Visual Studio 2017
編譯模式:Release x64

1. 環境準備

1.1 下載安裝Visual Studio 2017

下載連結:Visual Studio 2017 15.9 Release Notes | Microsoft Docs

下載後雙擊一路預設安裝即可。

1.2 安裝Git

下載連結:Git - Downloading Package 

下載後雙擊一路預設安裝即可,在cmd中執行git --version,顯示如下圖所示版本資訊即表明安裝成功。

2. 下載C++ API程式碼

C++ API連結:dolphindb/api-cplusplus

在終端執行git clone -b release130 https://github.com/dolphindb/api-cplusplus.git 即可下載。

若 Github 網速較慢,可訪問國內映象

注意: API 分支須與 DolphinDB Server 的版本相匹配,可通過 git 指令的 -b 指定版本對應的分支,即若 DolphinDB Server 是 1.30 版本,API 須切換到 release130 分支進行下載;若 DolphinDB Server 是 2.00 版本,API 須切換到 release200 分支下載,其他版本依此類推。

3. 建立和編譯專案

3.1 新建專案

開啟 Visual Studio 後,點選主選單檔案 -> 新建 -> 專案,彈出 新建專案對話方塊。在對話方塊左側面板中的 Visual C++ 下選擇windows 桌面,中間面板中選擇動態連結庫(DLL),然後在下面編輯框中輸入工程名稱和儲存路徑,如下圖所示:

3.2 新增原始碼到專案

專案預設生成了一些框架程式碼檔案,可如下圖所示選中移除:

 

然後選擇主選單原始檔 -> 新增 -> 現有項,彈出新增現有項對話方塊,如下圖所示,選中下載的 API 程式碼(src 子目錄下所有 .cpp 檔案和 .h 標頭檔案),再點選新增按鈕:

 

新增現有項成功後,原始碼會被新增到專案的原始檔目錄下,如下圖所示:

3.3 配置專案屬性

選中解決方案資源管理器中的專案 cppApi130,然後再選擇主選單專案->屬性,彈出“屬性頁”對話方塊。或者右鍵該專案彈出選單後選中屬性

 

在屬性頁對話方塊中先選擇配置(Debug/Release),再選擇平臺(x86/x64)。本文以 Release x64 為例,修改如下屬性配置:

(1) 目標檔名

常規 -> 目標檔名:輸入libDolphinDBAPI,用於配置生成解決方案後輸出的動態庫名(libDolphinDBAPI.dll)。

(2) 包含 SSL 的標頭檔案和庫目錄

VC++目錄 ->

  • 包含目錄:新增 OpenSSL 的標頭檔案目錄。
  • 庫目錄:新增 OpenSSL 庫目錄。

目前 DolphinDB 預設支援 ssl 1.0,編譯 SSL 可參閱 Windows10+VS2017下安裝和 編譯openssl庫,或者使用已編譯的 Binaries

DolphinDB api-cplusplus 專案也在 bin 子目錄下提供了一個 SSL 庫方便大家編譯。

如下圖所示即採用了 API 自身攜帶的 SSL 庫:

(3) 配置預處理巨集定義

C/C++ -> 前處理器:新增選項WIN32_LEAN_AND_MEAN;_WINSOCK_DEPRECATED_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;WINDOWS;NOMINMAX;

注意:

x86 平臺須新增選項   BIT32
SSL1.1 須新增選項   SSL1_1

 

(4) 設定預編譯頭

C/C++ -> 預編譯頭:選擇“不使用預編譯頭”。

(5) 設定依賴項

連結器 -> 輸入 -> 附加依賴項 :新增依賴項ws2_32.lib;ssleay32MD.lib;libeay32MD.lib;

3.4 編譯動態庫

選擇主選單生成 -> 生成解決方案即可編譯。注意須在編譯介面上方編譯選項中選擇 Debug/Release 和 x64/x86(如下圖所示)。

注意:編譯時選擇 Release/x64 生成 lib 位於 ./x64/Release 目錄,選擇 Debug/x64 生成 lib 在 ./x64/Debug 目錄,選擇 Release/x86 生成 lib 在 ./Release 目錄,選擇 Debug/x86 生成 lib 在 ./Debug 目錄。

4. 案例驗證

該案例的將時序資料庫DolphinDB和TimescaleDB 效能對比測試報告中提到的小資料集(4.2GB)匯入到DolphinDB分散式資料表中。對不方便下載4.2GB資料集的使用者,本文也準備了一個樣本檔案供下載。

程式的實現思路是利用開源軟體 rapidCsv 讀入csv檔案,然後呼叫DolphinDB C++ API中的 BatchTableWriter 物件寫入分散式表。

資料集包含了 3000 個裝置在 10000 個時間間隔(2016.11.15 - 2016.11.18)內的電池、 記憶體和 CPU 等指標的統計資訊。

分割槽方案:將 time 作為分割槽的第一個維度,每天一個分割槽共 4 個區,再將 device_id 作為分割槽的第二個維度,每天按 HASH 方式分 10 個區,每個分割槽所包含的原始資料大小約為 100 MB。

建庫建表指令碼如下:

login(`admin, `123456)
if (exists('dfs://iot') ) dropDatabase('dfs://iot')
db1 = database('',VALUE,2016.11.15..2016.11.18)
db2 = database('',HASH,[SYMBOL,10])
db = database('dfs://iot',COMPO,[db1,db2])

schema=table(1:0,`time`device_id`battery_level`battery_status`battery_temperature`bssid`cpu_avg_1min`cpu_avg_5min`cpu_avg_15min`mem_free`mem_used`rssi`ssid,
 [DATETIME,SYMBOL,INT,SYMBOL,DOUBLE,SYMBOL,DOUBLE,DOUBLE,DOUBLE,LONG,LONG,SHORT,SYMBOL])
 db.createPartitionedTable(schema,`readings,`time`device_id)

4.1 新建專案

開啟 Visual Studio 後,點選主選單檔案 -> 新建 -> 專案,彈出“新建專案”對話方塊。在對話方塊左側面板中的 Visual C++ 下選擇 windows桌面, 中間面板中選擇控制檯應用,然後在下面編輯框中輸入工程名稱 appApiDemo 和儲存路徑,如下圖所示:

4.2 匯入例子程式碼

下載 cppApiDemo.cpp 並替換專案同名檔案 D:\DolphinDB\api-cplusplus\cppApiDemo\cppApiDemo\cppApiDemo.cpp,下載 rapidcsv.h 並拷貝到 cppApiDemo.cpp 所在目錄。

4.3 配置專案屬性

先選中解決方案資源管理器中的專案cppApiDemo,然後再選擇主選單 專案 -> 屬性,或者右鍵解決方案資源管理器中的專案cppApiDemo,然後選擇屬性,彈出“屬性頁”對話方塊。

在屬性頁對話方塊中先選擇 Debug 還是 Release 模式,再選擇 x86 還是 x64 平臺。本文以 Release x64 為例,修改如下屬性配置:

(1) 包含標頭檔案和庫目錄

VC++目錄 ->

  • 包含目錄:新增 OpenSSL 和 API 的標頭檔案目錄
  • 庫目錄:新增 OpenSSL 和 API 的庫目錄。

(2) 配置預處理巨集定義

C/C++ ->前處理器:新增選項WIN32_LEAN_AND_MEAN;_WINSOCK_DEPRECATED_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;WINDOWS;NOMINMAX;

注意:x86平臺還要新增選項 BIT32

(3) 設定預編譯頭

C/C++ -> 預編譯頭:選擇不使用預編譯頭

(4) 設定依賴項

連結器 -> 輸入 -> 附加依賴項:新增依賴項libDolphinDBAPI.lib;ssleay32MD.lib;libeay32MD.lib;

4.4 編譯和執行

選擇主選單生成 -> 生成解決方案即可編譯。

執行前需要在本地部署一個 DolphinDB server,並用上述建庫建表指令碼先建立 dfs://iot/readings

在普通的桌上型電腦上,部署 DolphinDB 單節點模式,採用社群版預設配置,匯入上述資料集(1200萬條記錄),約耗時2分鐘。

在此過程中如果遇到如下問題:

  • 生成解決方案時報無法開啟原始檔 "openssl/err.h"的錯誤
    解決方案:可能由於選擇的編譯平臺不正確,比如下圖所示錯選了 Release x86,沒有選本例要求的 Release x64。

  • 生成失敗,報錯LINK : fatal error LNK1181: 無法開啟輸入檔案“libDolphinDBAPI.lib”
    解決方案:可能由於庫檔案目錄書寫錯誤,請檢查4.3節步驟(1)中包含的標頭檔案和目錄是否正確。
  • 執行時報 libDolphinDBAPI.dll 或 ssleay32MD.dll、libeay32MD.dll 庫找不到的錯誤
    解決方案:需要把對應庫拷貝至可執行程式所在目錄(如本例對應的目錄是D:\DolphinDB\api-cplusplus\cppApiDemo\cppApiDemo\x64\Release)。
    另外,在下載的D:\DolphinDB\api-cplusplus\bin\vs2017_x64子目錄中提供了 ssleay32MD.dll、libeay32MD.dll。
  • 執行丟擲異常ios_base::failbit set: iostream stream error
    解決方案:該異常有可能是由於沒有更改 cppApiDemo.cpp 原始碼中的本地 csv 路徑:path = "d:/data/devices_big_readings.csv";
    若更改過路徑,檢查是否需要修改 Windows 中的路徑(如”d:\data\devices_big_readings.csv”,需要修改 “\” 為 “/”)。

5. 說明

本文以 VS2017 Release/x64 平臺為例,一步一步介紹瞭如何搭建 DolphinDB C++ API 的 Visual Studio 開發環境,並用原始碼編譯 API 動態庫。然後結合例項講解如何利用API動態庫開發 API 應用程式。讀者可以參照本文的描述舉一反三,自己動手編譯其他 Release/Debug 模式,其他 x64/x86 平臺,或其他 Visual Studio 版本如 VS2015/VS2019/VS2022 等的動態庫。

若使用 Visual Studio 2017 或 Visual Studio 2019 Release 模式在 x64/x86 平臺上開發,且不需要修改原始碼,可以直接使用 api-cplusplus/bin 下提供的已編譯完成的 Visual Studio 2017 Release 模式動態庫。

更多 API 介面的使用教程,請參閱 C++ API使用教程  C++ API 資料讀寫指南