From b868046b6bcb98983f5f0afce34dbfdc2818911a Mon Sep 17 00:00:00 2001 From: zouchengzhuo <405966530@qq.com> Date: Thu, 6 Feb 2020 21:51:00 +0800 Subject: [PATCH] update doc --- README.md | 42 ++++++++++++++++----------------- README.zh.md | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 86 insertions(+), 21 deletions(-) create mode 100644 README.zh.md diff --git a/README.md b/README.md index c6c1315..f9d798f 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,23 @@ # Tars2Node -`tars2node` can convert the Tars IDL definition file to the version used by the JavaScript language, combined with the [@ tars / stream] (https://www.npmjs.com/package/@tars/stream) module to perform codec operations. +`tars2node` can convert the Tars IDL definition file to the version used by the JavaScript language, combined with the [@tars/stream](https://www.npmjs.com/package/@tars/stream) module to perform codec operations. -If you have Tars RPC requirements, you can call it in conjunction with the [@ tars / rpc] (https://www.npmjs.com/package/@tars/rpc) module. +If you have Tars RPC requirements, you can call it in conjunction with the [@tars/rpc](https://www.npmjs.com/package/@tars/rpc) module. ## Usage Just use the `tars2node` precompiler in the build directory (Linux platform). -`` `bash +```bash tars2node [OPTIONS] tarsfile -`` ` +``` ## options Options | Functions | | ------------- | ------------- | -| --stream-path = [DIRECTORY] | Specify the codec module name, the default is @ tars / stream. | -| --rpc-path = [DIRECTORY] | Specify the RPC module name. The default is @ tars / rpc. | +| --stream-path = [DIRECTORY] | Specify the codec module name, the default is @tars/stream. | +| --rpc-path = [DIRECTORY] | Specify the RPC module name. The default is @tars/rpc. | | --allow-reserved-namespace | Whether to allow `tars` as a namespace (because this namespace is mainly used for tars file definitions for framework services). | | --dir = [DIRECTORY] | Output directory for generated files. | | --relative | Limits all `.tars` files to look in the current directory. | @@ -29,37 +29,37 @@ Options | Functions | | --server | Generate server-side framework code. | | --ts | Turning on this option will only generate TypeScript (.ts) code. | | --dts | Append a TypeScript description file (.d.ts) when generating. | -| --long-type = [number | string | bigint] | Optionally use \ to express the \ type, with a default value of \ . | -| --string-binary-encoding | When you encounter character encoding problems or need to access the original data, turn on this option to use \ to store \ . | -| --enum-reverse-mappings | Output code \ supports reverse mapping of enum values ​​to enum names. | -| --optimize = [0 \ | s] | Optimize the output code size. The default is 0 (that is, not optimized). | +| --long-type = [number | string | bigint] | Optionally use \ to express the \ type, with a default value of \. | +| --string-binary-encoding | When you encounter character encoding problems or need to access the original data, turn on this option to use \ to store \. | +| --enum-reverse-mappings | Output code \ supports reverse mapping of enum values ​​to enum names. | +| --optimize = [0 \| s] | Optimize the output code size. The default is 0 (that is, not optimized). | ## Examples -`` `bash +```bash tars2node Protocol.tars -`` ` +``` The above command will convert the constants, enumerations, and structures defined in the Protocol.tars file to generate ProtocolTars.js for encoding and decoding. -For usage, please refer to the [@ tars / stream] (https://www.npmjs.com/package/@tars/stream) module documentation. +For usage, please refer to the [@tars/stream](https://www.npmjs.com/package/@tars/stream) module documentation. -`` `bash +```bash tars2node Protocol.tars --client -`` ` +``` The above command will convert the data types such as `constant`,` enumeration value`, `structure` defined in the file, and convert the` interface` description section into a Tars RPC client interface file, and finally generate `ProtocolProxy.js` for Used by the caller. -For usage, please refer to [@ tars / rpc] (https://www.npmjs.com/package/@tars/rpc) module documentation. +For usage, please refer to [@tars/rpc](https://www.npmjs.com/package/@tars/rpc) module documentation. -`` `bash +```bash tars2node Protocol.tars --server -`` ` +``` -The above command will convert data types such as `constant`,` enumeration value`, `struct` defined in the file, and convert the` interface` description section into a Tars RPC server interface file, and finally generate `Protocol.js` and `ProtocolImp.js` is used by the service provider. +The above command will convert data types such as `constant`,` enumeration value`, `struct` defined in the file, and convert the` interface` description section into a Tars RPC server interface file, and finally generate `Protocol.js` and `ProtocolImp.js` is used by the service provider. Developers do not need to change `Protocol.js`, they only need to continue to improve the specific functions in the` ProtocolImp.js` implementation file to provide services as Tars RPC server. -For usage, please refer to [@ tars / rpc] (https://www.npmjs.com/package/@tars/rpc) module documentation. +For usage, please refer to [@tars/rpc](https://www.npmjs.com/package/@tars/rpc) module documentation. ## Compile from source 1. Install build-essential for the corresponding platform -2. Install [CMake] (https://cmake.org/) +2. Install [CMake](https://cmake.org/) 3. Execute `cmake ../ && make` in the source build directory diff --git a/README.zh.md b/README.zh.md new file mode 100644 index 0000000..383da86 --- /dev/null +++ b/README.zh.md @@ -0,0 +1,65 @@ +# Tars2Node + +`tars2node` 可以将 Tars IDL 定义文件转换为 JavaScript 语言所使用的版本，结合 [@tars/stream](https://www.npmjs.com/package/@tars/stream) 模块执行编解码操作。 + +如您有 Tars RPC 需求可结合 [@tars/rpc](https://www.npmjs.com/package/@tars/rpc) 模块进行调用。 + +## 用法 + +直接使用 build 目录中的 `tars2node` 预编译程序即可（Linux 平台）。 + +```bash +tars2node [OPTIONS] tarsfile +``` + +## 选项 + +| 选项 | 作用 | +| ------------- | ------------- | +| --stream-path=[DIRECTORY] | 指定编解码模块名称，默认为 @tars/stream。 | +| --rpc-path=[DIRECTORY] | 指定 RPC 模块名称，默认为 @tars/rpc。 | +| --allow-reserved-namespace | 是否允许 `tars` 作为命名空间（因为此命名空间主要用于框架服务的 tars 文件定义）。 | +| --dir=[DIRECTORY] | 生成文件的输出目录。 | +| --relative | 限定所有的 `.tars` 文件都在当前目录寻找。| +| --tarsBase=[DIRECTORY] | 指定 `.tars` 文件的搜索目录。| +| --r | 转换嵌套的 `.tars` 文件。| +| --r-minimal | 精简依赖文件，移除非必须成员。| +| --r-reserved | 精简依赖文件时需保留的成员。| +| --client | 生成客户端的调用类代码。| +| --server | 生成服务端的框架代码。| +| --ts | 打开此选项将后将只生成 TypeScript (.ts) 代码。| +| --dts | 生成时附加 TypeScript 描述文件（.d.ts）。| +| --long-type=[number|string|bigint] | 可选择使用 \ 表达 \ 类型，默认值为 \。| +| --string-binary-encoding | 遇到字符编码问题或需对原始数据进行存取时，打开此选项使用 \ 存储 \。| +| --enum-reverse-mappings | 输出代码 \ 支持枚举值到枚举名的反向映射 。| +| --optimize=[0\|s] | 优化输出代码大小，默认为 0（也就是不优化）。| + +## 例子 + +```bash +tars2node Protocol.tars +``` + +上述命令将转换 `Protocol.tars` 文件中定义的 `常量`、`枚举`、`结构体` 等数据类型生成 `ProtocolTars.js` 供编解码使用。 +使用方法请参考 [@tars/stream](https://www.npmjs.com/package/@tars/stream) 模块说明文档。 + +```bash +tars2node Protocol.tars --client +``` + +上述命令将转换文件中定义的 `常量`、`枚举值`、`结构体` 等数据类型，并将 `interface` 描述段转换为 Tars RPC 客户端接口文件，最终生成 `ProtocolProxy.js` 供调用方使用。 +使用方法请参考 [@tars/rpc](https://www.npmjs.com/package/@tars/rpc) 模块说明文档。 + +```bash +tars2node Protocol.tars --server +``` + +上述命令将转换文件中定义的 `常量`、`枚举值`、`结构体` 等数据类型，并将 `interface` 描述段转换为 Tars RPC 服务端接口文件，最终生成 `Protocol.js` 以及 `ProtocolImp.js` 供服务提供方使用。 +开发者无需改动 `Protocol.js`，只需要继续完善 `ProtocolImp.js` 实现文件中具体的函数，即可作为 Tars RPC 服务端提供服务。 +使用方法请参考 [@tars/rpc](https://www.npmjs.com/package/@tars/rpc) 模块说明文档。 + +## 从源码编译 + +1. 安装对应平台的 build-essential +2. 安装 [CMake](https://cmake.org/) +3. 在源码 build 目录下执行 `cmake ../ && make` \ No newline at end of file