# cWrapMaker

**Repository Path**: anse_725/c-wrap-maker

## Basic Information

- **Project Name**: cWrapMaker
- **Description**: 该工具可以自动将一个含有动态库导出定义的C工程的目录转换为其他编程语言的wrap代码.
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2023-04-05
- **Last Updated**: 2023-04-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Wrap 工具
#### 介绍
该工具是一个用于生成C语言与其他编程语言之间互相调用的接口的工具，可以自动将一个含有动态库导出定义的C工程的目录转换为其他编程语言的wrap代码。

#### 工作过程
输入 含动态库导出定义的 C 工程的目录 ，自动输出相对应 语言Wrap代码，来对接C 的动态库函数接口。

*目前支持语言：c、c#*

#### 实现原理
本工具使用antlr4，来生成 词法、语法 解析器，配合语义分析逻辑来处理，C语言到其他语言的转换。

### 如何使用
使用该工具需要符合一些特定的声明约定，以便在不同语言之间传递参数和调用函数时正确解析和处理数据。在生成Wrap代码前，用户需要先按照约定调整源C项目中的声明。该工具也提供了一些命令行选项，例如生成Wrap代码文件、打印帮助和版本信息等。

通过使用 命令行工具 wrapCLI.exe 来生成Wrap文件，它是由于wrapCLI 项目发布而来。

常见命令：
- ? ：打印帮助
- -v ：打印版本
- -g ：生成Wrap文件
- -f ：强制Wrap生成安全代码
```` c
wrapCLI.exe -g ./c项目源目录/ ./输出Wrap目录/ ./动态库.dll
//简单使用 -g 命令，指定源c项目目录，设定.dll 动态库的文件路径 ，生成wrap文件保存到指定的输出目录。
//还可以使用 ? 打印帮助，查看更多选项。
````



### 源C项目(.h code) 声明细节约定
以下约定是为了便于其他语言接入和使用，不符合约定的声明，会在工具生成时用黄色字体进行提示。
如果wrapCLI.exe 开启了 -f 则使用强制安全模式,用户就必须在c项目侧按约定调整声明后，再次生成Wrap才能正常使用。

#### 指针消歧义

##### char16_t*
使用 char16_t* 作为 字符串类型(string)
````c
char16_t* func( char16_t* texH);   //函数的返回值 和 参数 都作为 字符串
````

##### void*
使用 void* 作为 句柄handle(地址值 Uint64)
````c
void* func( void* texH);   //函数的返回值和参数 都作为 句柄
````

##### 空结构体*

*空结构体： 是指 没有任何定义的结构体。*
空结构* 只能用作 句柄，不表示 数组、传出值。
````c
struct Texture;                 //声明一个 空结构体
Texture* func(Texture* texH);   //函数的返回值 和 参数 都作为 句柄
````

##### 函数形参指针：
> 通过在指针类型形参名后缀，标记字符来区分该指针的使用意图。 
- 用作传出值，需要参数命名以_out 结尾。

- 用作句柄，需要参数命名以_handle 结尾。

- 用作数组，需要参数命名以_arr 结尾。
```` c
void func(int* val_out);                //函数参数 作为 传出值
void func1(int* val_handle);            //函数参数 作为 句柄
void func2(int* val_arr);               //函数参数 作为 数组
````

##### 函数返回值指针：
> 通过给指针类型，声明别名来区分该指针的使用意图。 
- 用作数组，需要声明别名，使用该别名，且要求别名以_Array 结尾，且还需要函数参数列表中包含(int * __retArrLen_out)的声明。
```` c
typedef int* int_Array;     //别名以_Array 结尾
int_Array func(int * __retArrLen_out);           //函数返回值使用 别名
````

- 用作句柄 直接使用 void*