myvtm/DevAdapter/DevelopGuide.md

信创版本厂商源码编写事项

版本：V1.0.1

最后更新日期：2021年1月14日19点07分

首要说明

• **不允许改动 **DeviceAdapter/CMakeLists.txt
• **不允许改动 **DeviceAdapter/include 文件夹内容，主要是我行提供的适配器头文件
• 厂商文件夹（*比如 DevAdapter/keba*）下的任何内容均可以改动，只要你清楚你改动内容会造成哪些影响，但是有些要求声明的语句必须要保留（详见提供的Demo文件夹 cmbsz）

特别说明

• rvc_dev_target_install语句调用
  • 第一次说明的时候要求所有的适配器和提供源码的依赖库的CMakeLists.txt文件的最后必须加上面这条语句
  • 现补充：如果生成的时静态库文件（.a类型文件），则无需添加此条语句！！！！

编译模式

• 通过CMake管理构建和编译
• 我行编译环境与其他编译环境的区分通过RVC_INTEGRATE_BUILD判断
  • RVC_INTEGRATE_BUILD用于判断是否处于我行集成编译环境，厂商在编写 CMakeLists.txt 文件时，对于一些输出逻辑的声明等，可以通过 if(NOT RVC_INTEGRATE_BUILD)来添加自己的逻辑

注意事项

我行编译环境的特殊点

库管理

我行的源码管理工具不允许上传二进制库文件（主要是.so库），为更好的管理厂商提供的库文件，行内在编译之前会将厂商提供的几个文件夹：

• assets
• lib
• bin
• include

剪切到其他地方进行管理，其他适配器工程文件夹和 deps 文件夹保持不变

所以厂商在编码引用上诉这些文件目录的路径时，务必请使用我们提供的宏，而不要使用相对路径，见路径引用请使用我们提供的宏，不要用.开头的相对路径，更不要使用绝对路径

链接库和头文件目录引用

不允许使用：

include_directories
link_directories

因为这种声明是全局生效的，会影响到其他工程目标的编译，请改用：

target_include_directories
target_link_directories

这种声明的作用范围是针对工程目标的

已引入部分头文件和链接库目录，厂商无需单独引入

已声明在我行定义的rvc_dev_config_libraryCMake宏里，已经对当前工程目标引入了如下路径：

• 头文件目录

  DevAdapter/include
  DevAdapter/{厂商文件夹}/include
  

• 链接库目录

  DevAdapter/lib/gcc_aarch64
  DevAdapter/{厂商文件夹}/lib/gcc_aarch64
  

路径引用请使用我们提供的宏，不要用..开头的相对路径，更不要使用绝对路径

行内提供的宏定义如下：

• DEVADAPTER_CURRENT_INCLUDES_DIR
  • 实际指向：/DevAdapter/include
  • 说明：存放我行提供的适配器头文件的目录，已在rvc_dev_config_library引入，无需再单独引入
• DEVADAPTER_CURRENT_ASSET_DIR
  • 实际指向：/DevAdapter/assets
  • 说明：存放我行的资源文件
• DEVADAPTER_CURRENT_LIB_DIR
  • 实际指向：/DevAdapter/lib/gcc_aarch64，里头的非.lib内容安装时会拷贝到我行应用程序运行目录的dep文件夹下
• DEVADAPTER_CURRENT_BIN_DIR
  • 实际指向：/DevAdapter/bin/gcc_aarch64，里头内容安装时会拷贝到我行应用程序运行目录的dep文件夹下
• VENDOR_LOG_LIB_NAME
  • 说明：我行提供的日志库名称，供适配器工程在target_link_libraries中使用
• VENDOR_CURRENT_DEPS_DIR
  • 实际指向：/DevAdapter/{当前厂商目录}/deps
  • 说明：存放当前厂商存放的有源码的依赖库工程
• VENDOR_CURRENT_INCLUDE_DIR
  • 实际指向：/DevAdapter/{当前厂商目录}/include
  • 说明：存放当前厂商的公有头文件，已在rvc_dev_config_library引入，无需再单独引入
• VENDOR_CURRENT_ASSET_DIR
  • 实际指向：/DevAdapter/{当前厂商目录}/assets
  • 说明：存放当前厂商的资源文件，里头内容安装时会拷贝到我行应用程序运行目录的dep文件夹下
• VENDOR_CURRENT_LIB_DIR
  • 实际指向：/DevAdapter/{当前厂商目录}/lib/gcc_aarch64
  • 说明：存放当前厂商的无源码提供的依赖库文件，已在rvc_dev_config_library引入，里头的非.lib内容安装时会拷贝到我行应用程序运行目录的dep文件夹下
• VENDOR_CURRENT_BIN_DIR
  • 实际指向：/DevAdapter/{当前厂商目录}/bin/gcc_aarch64
  • 说明：存放当前厂商提供的执行库文件，Linux下一般不应该有，里头内容安装时会拷贝到我行应用程序运行目录的dep文件夹下

大小写敏感

• 适配器文件名：适配器名称请以提供的Demo适配器名称为准，不要随意改动

• 厂商名称：厂商名称一旦确定，就不可更改

  rvc_dev_define_module("{此处填写的适配器名称需注意}")
  set(${MODULE_PREFIX}_VENDOR "{当前厂商名称}")
  

厂商	简称
科堡	keba
南天	nantian
广电	grg
恒银	cw
长城	gwi

厂商文件夹名称、适配器的Vendor字段请与如上表格保持一致。

错误示范

下方是在某个适配器工程的CMakeLists.txt文件的一部分内容：问题详见注释处

set(INCLUDE_PINPAD ../../include
                   ../include
                   ../include/SDK
                   )
#1.  ../../include：引用的我行头文件，已在rvc_dev_config_library引入，没必要
#2. ../include：引用当前厂商的头文件，（新增）已在rvc_dev_config_library引入，可废弃
#3. ../include/SDK：引用当前厂商的头文件的子目录，不能已.开头，务必使用：${VENDOR_CURRENT_INCLUDE_DIR}/SDK
                   
                   
set(${MODULE_PREFIX}_SRCS SHARED
        ${SRC_LIST}
        )

include_directories(${INCLUDE_PINPAD})
#1.不能使用 include_directories，改用target_include_directories(${MODULE_FULL_NAME} ${INCLUDE_PINPAD}),当然，得在rvc_dev_config_library调用之后


link_directories(${DEVADAPTER_CURRENT_LIB_DIR})
link_directories(${VENDOR_CURRENT_LIB_DIR})
# 1. 两条路径均已在rvc_dev_config_library引入，没必要再单独引入
# 2. 不能使用 link_directories，改用 target_link_directories

其他注意事项请看模板内相关 CMakeLists.txt 的注释内容和编码规范文档

代码编写

头文件引用

上面提到，在招行的编译环境中，会把厂商的头文件目录（如：DevAdapter/cmbsz/include）放置在其他独立开来，所以在编码时不要使用相对路径！！。我行提供的CMake宏rvc_dev_config_library已经将DevAdapter/include和DevAdapter/{当前厂商名称}/include 加入到头文件的搜索路径中，所以在编码时，只要所需引用的头文件在这两个文件夹中，无需再单独加相对路径，直接引用头文件名称即可，否则有可能会出现找不到头文件或找错头文件而出现报错的风险。

例如，在某个厂商适配器实现中

#include "../include/DRV_IDCardReader.h"
#include "../../include/IDCerClass.h"
#include "../include/CILIX_AUX_UTILS.h"
#include "../include/log4vendor.h"

需要改成：

#include "DRV_IDCardReader.h"
#include "IDCerClass.h"
#include "CILIX_AUX_UTILS.h"
#include "log4vendor.h"

请勿将我行公用头文件拷贝到适配器目录内引用

我行提供的库文件，一般都会放置在DevAdapter/include目录中，包括适配器头文件、日志库头文件等，不要将这些头文件拷贝到厂商目录（如：DevAdapter/cmbsz）下的任意目录中然后再加以引用，避免后续我行在更新公共文件时出现引用错误导致编译报错。

提交要求

1. 仅需提供厂商文件夹，无需提供整个DevAdapter文件夹

2. 提供的厂商文件夹以厂商名称命名，而不是我行提供的Demo名称”cmbsz"！！

3. 提供的内容注意去掉无关文件：生成的日志文件、CMake构建残留文件、有源码的适配器库生成文件或依赖库文件、我行提供的Demo（空文件夹也不允许，没用就删掉）

4. 建议：厂商文件夹首层目录提供CHANGELOG文件，该文件需要记录几个重要元素：版本变更记录，提交日期，版本号等。并合适地将对应的版本号同步填充到适配器接口GetDevCategory返回的相关字段中。