# `protoc` gRPC Swift plugin

gRPC Swift provides a plugin for the [protocol buffer][protocol-buffers]
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:

```sh
$ make plugins
```

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

```sh
$ 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
- **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][swift-protobuf-module-mappings].

### KeepMethodCasing

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

For example, for the following RPC definition:

```proto
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][swift-protobuf-module-name].

## 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:

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

Or, in the alternate syntax:

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

[protocol-buffers]: https://developers.google.com/protocol-buffers/docs/overview
[swift-protobuf-filenaming]: https://github.com/apple/swift-protobuf/blob/master/Documentation/PLUGIN.md#generation-option-filenaming---naming-of-generated-sources
[swift-protobuf-module-mappings]: https://github.com/apple/swift-protobuf/blob/master/Documentation/PLUGIN.md#generation-option-protopathmodulemappings---swift-module-names-for-proto-paths
[swift-protobuf-module-name]: https://github.com/apple/swift-protobuf/commit/9df381f72ff22062080d434e9c2f68e71ee44298#diff-1b08f0a80bd568509049d851b8d8af90d1f2db3cd8711eaba974b5380cd59bf3