grpc-swift/docs/plugin.md

protoc gRPC Swift plugin

gRPC Swift provides a plugin for the protocol buffer compiler protoc to generate classes for clients and services.

Building the Plugin

The protoc-gen-grpc-swift plugin can be built by using the Makefile in the top-level directory:

$ make plugins

The Swift Package Manager may also be invoked directly to build the plugin:

$ swift build --product protoc-gen-grpc-swift

The plugin must be in your PATH environment variable or specified directly when invoking protoc.

Plugin Options

Visibility

The Visibility option determines the access control for generated code.

• Possible values: Public, Internal, Package
• Default value: Internal

Server

The Server option determines whether server code is generated. The generated server code includes a protocol which users must implement to provide the logic for their service.

• Possible values: true, false
• Default value: true

Client

The Client option determines whether client code is generated. The generated client code includes a protocol and a class conforming to that protocol.

• Possible values: true, false
• Default value: true

TestClient

The TestClient option determines whether test client code is generated. This does not include the protocol generated by the Client option.

• Possible values: true, false
• Default value: false

FileNaming

The FileNaming option determines how generated source files should be named.

• Possible values:
  • FullPath: The full path of the input file will be used; foo/bar/baz.proto will generate foo/bar/baz.grpc.proto
  • PathToUnderscores: Directories structures are flattened; foo/bar/baz.proto will generate foo_bar_baz.grpc.proto
  • DropPath: The path is dropped and only the name of the file is kept; foo/bar/baz.proto will generate baz.grpc.proto
• Default value: FullPath

ProtoPathModuleMappings

The ProtoPathModuleMappings option allows module mappings to be specified. See the SwiftProtobuf documentation.

KeepMethodCasing

The KeepMethodCasing determines whether the casing of generated function names is kept.

For example, for the following RPC definition:

rpc Foo(FooRequest) returns (FooRequest) {}

Will generate stubs named foo by default. However, in some cases this is not desired, and setting KeepMethodCasing=true will yield stubs named Foo.

• Possible values: true, false
• Default value: false

GRPCModuleName

The GRPCModuleName option allows the name of the gRPC Swift runtime module to be specified. The value, if not specified, defaults to "GRPC".

Note: most users will not need to use this option.

SwiftProtobufModuleName

The SwiftProtobufModuleName option allows the name of the SwiftProtobuf runtime module to be specified. The value, if not specified, defaults to "SwiftProtobuf".

*Note: most users will not need to use this option. Introduced to match the option that exists in SwiftProtobuf.

Specifying Options

To pass extra parameters to the plugin, use a comma-separated parameter list separated from the output directory by a colon. Alternatively use the --grpc-swift_opt flag.

For example, to generate only client stubs:

protoc <your proto> --grpc-swift_out=Client=true,Server=false:.

Or, in the alternate syntax:

protoc <your proto> --grpc-swift_opt=Client=true,Server=false --grpc-swift_out=.