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

**版本**：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_library`CMake宏里，已经对当前工程目标引入了如下路径：

* 头文件目录

```
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适配器名称为准，不要随意改动
* **厂商名称**：厂商名称一旦确定，就不可更改

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

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

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

## 错误示范

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

```cmake
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`** 加入到头文件的搜索路径中，所以在编码时，只要所需引用的头文件在这两个文件夹中，无需再单独加相对路径，直接引用头文件名称即可，**否则有可能会出现找不到头文件或找错头文件而出现报错的风险**。

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

```c++
#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返回的相关字段中。