Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
5a3a0be
commit 555306b
Showing
2 changed files
with
486 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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] <NAME> <IDL> | ||
|
|
||
| Arguments: | ||
| <NAME> The name of project | ||
| <IDL> 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 <REPO> Specify the git repo name for repo. | ||
| Example: cloudwego_volo | ||
| -v, --verbose... Turn on the verbose mode. | ||
| -g, --git <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 <REF> Specify the git repo ref(branch) for idl. | ||
| Example: main / $TAG | ||
| -i, --includes <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] <COMMAND> | ||
|
|
||
| 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 <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] <IDL> | ||
|
|
||
| Arguments: | ||
| <IDL> 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 <REPO> Specify the git repo name for repo. | ||
| Example: cloudwego_volo | ||
| -v, --verbose... Turn on the verbose mode. | ||
| -g, --git <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 <ENTRY_NAME> The entry name, defaults to 'default'. [default: default] | ||
| -r, --ref <REF> Specify the git repo ref(branch) for idl. | ||
| Example: main / $TAG | ||
| -i, --includes <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 <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] <COMMAND> | ||
|
|
||
| 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 <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 <GIT> | ||
|
|
||
| Options: | ||
| --repo <REPO> Specify the git repo name for repo. | ||
| Example: cloudwego_volo | ||
| -v, --verbose... Turn on the verbose mode. | ||
| -g, --git <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 <ENTRY_NAME> The entry name, defaults to 'default'. [default: default] | ||
| -r, --ref <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 <ENTRY_NAME> The entry name, defaults to 'default'. [default: default] | ||
| -h, --help Print help | ||
| -V, --version Print version | ||
| ``` |
Oops, something went wrong.