From 555306b1242a35f1ce8855dc1c995a8b971647bb Mon Sep 17 00:00:00 2001 From: Pure White Date: Sun, 7 Apr 2024 15:38:51 +0800 Subject: [PATCH] docs: add volo config guide (#1053) --- content/en/docs/volo/guide/config.md | 243 +++++++++++++++++++++++++++ content/zh/docs/volo/guide/config.md | 243 +++++++++++++++++++++++++++ 2 files changed, 486 insertions(+) create mode 100644 content/en/docs/volo/guide/config.md create mode 100644 content/zh/docs/volo/guide/config.md diff --git a/content/en/docs/volo/guide/config.md b/content/en/docs/volo/guide/config.md new file mode 100644 index 0000000000..0aad6427e2 --- /dev/null +++ b/content/en/docs/volo/guide/config.md @@ -0,0 +1,243 @@ +--- +title: "volo.yml Configuration File Format" +linkTitle: "volo.yml Configuration File Format" +weight: 5 +description: > + +--- + +## Features + +1. Multiple production files: Supports isolation of protocol and repository version conflicts through different protocols +2. Deduplication of single file: Supports the elimination of duplicate structures within a single generated file +3. Flexible code generation configuration: `keep_unknown_fields`, `touch list`, `custom config`, `special_namings`, etc. +4. Cross-repository references: Supports cross-library references by providing repository information for cross-references in the `repos` list + +## yaml Format + +```YAML +entries: + {entry_name}: # entry_name = "default" by default + filename: {filename} # filename = "volo_gen.rs" by default + protocol: thrift | protobuf + repos: # exist if non-local + {repo}: # repo = extract the name from url by default + url: {git} # url = repo git url + ref: {ref} # ref = "HEAD" by default + lock: {commit hash} # lock is the last commit hash + services: + - idl: + source: git | local + repo: {repo} # required for git source + path: {path} # git path must be relative to the repo root dir + includes: {includes list} # required for protobuf + codegen_option: + touch: [] # + keep_unknown_fields: false # A->B->C, B could use this to transfer the unknown fields which is needed by A and C. + config: {custom config} + touch_all: false + dedups: [] # remove the repeated structure generation in one entry + special_namings: [] +``` + +volo.yml example + +```YAML +entries: + proto: + filename: proto_gen.rs + protocol: protobuf + repos: + protobuf: + url: https://github.com/protocolbuffers/protobuf.git + ref: HEAD + lock: 704d0454ddc58da683e8cec22896ff3498089549 + services: + - idl: + source: local + path: ../proto/echo.proto + includes: + - ../proto + - idl: + source: local + path: ../proto/streaming.proto + includes: + - ../proto + - idl: + source: local + path: ../proto/hello.proto + includes: + - ../proto + - idl: + source: git + repo: protobuf + path: examples/addressbook.proto + includes: + - examples + thrift: + filename: thrift_gen.rs + protocol: thrift + repos: + thrift: + url: https://github.com/apache/thrift.git + ref: HEAD + lock: 9bd1f1bee7bf59080492bbd3213ca1fed57ab4d6 + services: + - idl: + source: local + path: ../thrift_idl/hello.thrift + - idl: + source: local + path: ../thrift_idl/echo.thrift + - idl: + source: local + path: ../thrift_idl/echo_unknown.thrift + codegen_option: + keep_unknown_fields: true + - idl: + source: git + repo: thrift + path: test/Service.thrift +``` + +### volo-cli + +1. init + + 1. ```bash + $ volo init --help + init your thrift or grpc project + + Usage: volo init [OPTIONS] + + Arguments: + The name of project + Specify the path for idl. + If -g or --git is specified, then this should be the path in the specified git repo. + Example: -g not specified: ./idl/server.thrift + -g specified: /path/to/idl/server.thrift + + Options: + --repo Specify the git repo name for repo. + Example: cloudwego_volo + -v, --verbose... Turn on the verbose mode. + -g, --git Specify the git repo for idl. + Should be in the format of "git@domain:path/repo.git". + Example: git@github.com:cloudwego/volo.git + -r, --ref Specify the git repo ref(branch) for idl. + Example: main / $TAG + -i, --includes Specify the include dirs for idl. + If -g or --git is specified, then this should be the path in the specified git repo. + -h, --help Print help + -V, --version Print version + ``` + + 2. Using the `volo init` command in the project root directory will automatically create server code templates and generate code. + +2. idl + + 1. ```bash + $ volo idl --help + manage your idl + + Usage: volo idl [OPTIONS] + + Commands: + add + help Print this message or the help of the given subcommand(s) + + Options: + -v, --verbose... Turn on the verbose mode. + -n, --entry-name The entry name, defaults to 'default'. [default: default] + -h, --help Print help + -V, --version Print version + ``` + + 2. idl add + + 1. ```bash + $ volo idl add --help + Usage: volo idl add [OPTIONS] + + Arguments: + Specify the path for idl. + If -g or --git is specified, then this should be the path in the specified git repo. + Example: -g not specified: ./idl/client.thrift + -g specified: /path/to/idl/client.thrift + + Options: + --repo Specify the git repo name for repo. + Example: cloudwego_volo + -v, --verbose... Turn on the verbose mode. + -g, --git Specify the git repo for idl. + Should be in the format of "git@domain:path/repo.git". + Example: git@github.com:cloudwego/volo.git + -n, --entry-name The entry name, defaults to 'default'. [default: default] + -r, --ref Specify the git repo ref(branch) for idl. + Example: main / $TAG + -i, --includes Specify the include dirs for idl. + If -g or --git is specified, then this should be the path in the specified git repo. + -f, --filename Specify the output filename, defaults to 'volo_gen.rs'. [default: volo_gen.rs] + -h, --help Print help + -V, --version Print version + ``` + + 3. [deprecated] idl update -> repo update + +3. repo + + 1. ```bash + $ volo repo --help + manage your repo + + Usage: volo repo [OPTIONS] + + Commands: + update update your repo by repo name, split by ',' + add + help Print this message or the help of the given subcommand(s) + + Options: + -v, --verbose... Turn on the verbose mode. + -n, --entry-name The entry name, defaults to 'default'. [default: default] + -h, --help Print help + -V, --version Print version + ``` + + 2. repo add + + 1. ```bash + $ volo repo add --help + Usage: volo repo add [OPTIONS] --git + + Options: + --repo Specify the git repo name for repo. + Example: cloudwego_volo + -v, --verbose... Turn on the verbose mode. + -g, --git Specify the git repo for idl. + Should be in the format of "git@domain:path/repo.git". + Example: git@github.com:cloudwego/volo.git + -n, --entry-name The entry name, defaults to 'default'. [default: default] + -r, --ref Specify the git repo ref(branch) for idl. + Example: main / $TAG + -h, --help Print help + -V, --version Print version + ``` + + 3. repo update + + 1. ```bash + $ volo repo update --help + update your repo by repo name, split by ',' + + Usage: volo repo update [OPTIONS] [REPOS]... + + Arguments: + [REPOS]... + + Options: + -v, --verbose... Turn on the verbose mode. + -n, --entry-name The entry name, defaults to 'default'. [default: default] + -h, --help Print help + -V, --version Print version + ``` diff --git a/content/zh/docs/volo/guide/config.md b/content/zh/docs/volo/guide/config.md new file mode 100644 index 0000000000..09f1c4117a --- /dev/null +++ b/content/zh/docs/volo/guide/config.md @@ -0,0 +1,243 @@ +--- +title: "volo.yml 配置文件格式" +linkTitle: "volo.yml 配置文件格式" +weight: 5 +description: > + +--- + +## 功能 + +1. 多个生产文件：支持不同协议和仓库版本冲突隔离 +2. 单文件去重：支持单个生成文件中的重复结构消除 +3. 灵活的生成代码配置：keep_unknown_fields、touch list、custom config、special_namings 等 +4. 跨库引用：在 repos 列表中给出跨仓库引用的仓库信息，即可支持跨库引用 + +## yaml 格式 + +```YAML +entries: + {entry_name}: # entry_name = "default" by default + filename: {filename} # filename = "volo_gen.rs" by default + protocol: thrift | protobuf + repos: # exist if non-local + {repo}: # repo = extract the name from url by default + url: {git} # url = repo git url + ref: {ref} # ref = "HEAD" by default + lock: {commit hash} # lock is the last commit hash + services: + - idl: + source: git | local + repo: {repo} # required for git source + path: {path} # git path must be relative to the repo root dir + includes: {includes list} # required for protobuf + codegen_option: + touch: [] # + keep_unknown_fields: false # A->B->C, B could use this to transfer the unknown fields which is needed by A and C. + config: {custom config} + touch_all: false + dedups: [] # remove the repeated structure generation in one entry + special_namings: [] +``` + +volo.yml 文件示例 + +```YAML +entries: + proto: + filename: proto_gen.rs + protocol: protobuf + repos: + protobuf: + url: https://github.com/protocolbuffers/protobuf.git + ref: HEAD + lock: 704d0454ddc58da683e8cec22896ff3498089549 + services: + - idl: + source: local + path: ../proto/echo.proto + includes: + - ../proto + - idl: + source: local + path: ../proto/streaming.proto + includes: + - ../proto + - idl: + source: local + path: ../proto/hello.proto + includes: + - ../proto + - idl: + source: git + repo: protobuf + path: examples/addressbook.proto + includes: + - examples + thrift: + filename: thrift_gen.rs + protocol: thrift + repos: + thrift: + url: https://github.com/apache/thrift.git + ref: HEAD + lock: 9bd1f1bee7bf59080492bbd3213ca1fed57ab4d6 + services: + - idl: + source: local + path: ../thrift_idl/hello.thrift + - idl: + source: local + path: ../thrift_idl/echo.thrift + - idl: + source: local + path: ../thrift_idl/echo_unknown.thrift + codegen_option: + keep_unknown_fields: true + - idl: + source: git + repo: thrift + path: test/Service.thrift +``` + +### volo-cli + +1. init + + 1. ```bash + $ volo init --help + init your thrift or grpc project + + Usage: volo init [OPTIONS] + + Arguments: + The name of project + Specify the path for idl. + If -g or --git is specified, then this should be the path in the specified git repo. + Example: -g not specified: ./idl/server.thrift + -g specified: /path/to/idl/server.thrift + + Options: + --repo Specify the git repo name for repo. + Example: cloudwego_volo + -v, --verbose... Turn on the verbose mode. + -g, --git Specify the git repo for idl. + Should be in the format of "git@domain:path/repo.git". + Example: git@github.com:cloudwego/volo.git + -r, --ref Specify the git repo ref(branch) for idl. + Example: main / $TAG + -i, --includes Specify the include dirs for idl. + If -g or --git is specified, then this should be the path in the specified git repo. + -h, --help Print help + -V, --version Print version + ``` + + 2. 在项目根目录下使用 volo init 命令，会自动创建 server 代码模版和生成代码 + +2. idl + + 1. ```bash + $ volo idl --help + manage your idl + + Usage: volo idl [OPTIONS] + + Commands: + add + help Print this message or the help of the given subcommand(s) + + Options: + -v, --verbose... Turn on the verbose mode. + -n, --entry-name The entry name, defaults to 'default'. [default: default] + -h, --help Print help + -V, --version Print version + ``` + + 2. idl add + + 1. ```bash + $ volo idl add --help + Usage: volo idl add [OPTIONS] + + Arguments: + Specify the path for idl. + If -g or --git is specified, then this should be the path in the specified git repo. + Example: -g not specified: ./idl/client.thrift + -g specified: /path/to/idl/client.thrift + + Options: + --repo Specify the git repo name for repo. + Example: cloudwego_volo + -v, --verbose... Turn on the verbose mode. + -g, --git Specify the git repo for idl. + Should be in the format of "git@domain:path/repo.git". + Example: git@github.com:cloudwego/volo.git + -n, --entry-name The entry name, defaults to 'default'. [default: default] + -r, --ref Specify the git repo ref(branch) for idl. + Example: main / $TAG + -i, --includes Specify the include dirs for idl. + If -g or --git is specified, then this should be the path in the specified git repo. + -f, --filename Specify the output filename, defaults to 'volo_gen.rs'. [default: volo_gen.rs] + -h, --help Print help + -V, --version Print version + ``` + + 3. [deprecated] idl update -> repo update + +3. repo + + 1. ```bash + $ volo repo --help + manage your repo + + Usage: volo repo [OPTIONS] + + Commands: + update update your repo by repo name, split by ',' + add + help Print this message or the help of the given subcommand(s) + + Options: + -v, --verbose... Turn on the verbose mode. + -n, --entry-name The entry name, defaults to 'default'. [default: default] + -h, --help Print help + -V, --version Print version + ``` + + 2. repo add + + 1. ```bash + $ volo repo add --help + Usage: volo repo add [OPTIONS] --git + + Options: + --repo Specify the git repo name for repo. + Example: cloudwego_volo + -v, --verbose... Turn on the verbose mode. + -g, --git Specify the git repo for idl. + Should be in the format of "git@domain:path/repo.git". + Example: git@github.com:cloudwego/volo.git + -n, --entry-name The entry name, defaults to 'default'. [default: default] + -r, --ref Specify the git repo ref(branch) for idl. + Example: main / $TAG + -h, --help Print help + -V, --version Print version + ``` + + 3. repo update + + 1. ```bash + $ volo repo update --help + update your repo by repo name, split by ',' + + Usage: volo repo update [OPTIONS] [REPOS]... + + Arguments: + [REPOS]... + + Options: + -v, --verbose... Turn on the verbose mode. + -n, --entry-name The entry name, defaults to 'default'. [default: default] + -h, --help Print help + -V, --version Print version + ```