volo.yml Configuration File Format

Features

Multiple production files: Supports isolation of protocol and repository version conflicts through different protocols
Deduplication of single file: Supports the elimination of duplicate structures within a single generated file
Flexible code generation configuration: keep_unknown_fields, touch list, custom config, special_namings, etc.
Cross-repository references: Supports cross-library references by providing repository information for cross-references in the repos list

yaml Format

entries:
  {entry_name}: # entry_name = "default" by default
    filename: {filename} # filename = "volo_gen.rs" by default
    protocol: thrift | protobuf
    repos: # exsit 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
        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

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

init

$ 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

Using the volo init command in the project root directory will automatically create server code templates and generate code.

idl

$ 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

idl add

$ 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

[deprecated] idl update -> repo update

repo

$ 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

repo add

$ 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

Repo update

$ 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

Feedback

Was this page helpful?

Please tell us how we can improve.

Last modified April 7, 2024 : docs: add volo config guide (9d20b00)