# protoc-gen-prost-serde

A `protoc` plugin that generates _[serde]_ serialization implementations that
follow the conventions of protobuf-JSON.

[serde]: https://serde.rs

When used in projects that use only Rust code, the preferred mechanism for
generating protobuf definitions with _Prost!_ is to use [`prost-build`] from
within a `build.rs` file and then generate _serde_ implementations using
[`pbjson-build`]. However, when working in polyglot environments,
it can be advantageous to utilize common tooling in the Protocol Buffers
ecosystem. One common tool used for this purpose is _[buf]_, which simplifies
the code generation process and includes several useful features, including
linting, package management, and breaking change detection.

[`prost-build`]: https://docs.rs/prost-build
[`pbjson-build`]: https://docs.rs/pbjson-build
[buf]: https://buf.build

## Usage

Ensure that `protoc-gen-prost-serde` has been installed within a directory
on your `$PATH`. Then invoke `protoc` from the command line as follows:

```shell
protoc --prost-serde_out=proto/gen -I proto proto/greeter/v1/greeter.proto
```

### Options

This tool supports all the same options from `pbjson-build`. For more
information on the effects of these settings, see the related documentation
from that crate:

* `btree_map=<proto_path>`: [btree_map](https://docs.rs/pbjson-build/latest/pbjson_build/struct.Builder.html#method.btree_map)
* `default_package_filename=<value>`: [default_package_filename](https://docs.rs/prost-build/latest/prost_build/struct.Config.html#method.default_package_filename)
* `extern_path=<proto_path>=<rust_path>`: [extern_path](https://docs.rs/pbjson-build/latest/pbjson_build/struct.Builder.html#method.extern_path)
* `retain_enum_prefix(=<boolean>)`: [retain_enum_prefix](https://docs.rs/pbjson-build/latest/pbjson_build/struct.Builder.html#method.retain_enum_prefix)
* `preserve_proto_field_names=(<boolean>)`: [preserve_proto_field_names](https://docs.rs/pbjson-build/latest/pbjson_build/struct.Builder.html#method.preserve_proto_field_names)
* `ignore_unknown_fields=(<boolean>)`: [ignore_unknown_fields](https://docs.rs/pbjson-build/latest/pbjson_build/struct.Builder.html#method.ignore_unknown_fields)
* `emit_fields=(<boolean>)`: [emit_fields](https://docs.rs/pbjson-build/latest/pbjson_build/struct.Builder.html#method.emit_fields)
* `use_integers_for_enums=(<boolean>)`: [use_integers_for_enums](https://docs.rs/pbjson-build/latest/pbjson_build/struct.Builder.html#method.use_integers_for_enums)

In addition, the following options can also be specified:

* `no_include(=<boolean>)`:  Skips adding an include into the file generated
  by `protoc-gen-prost`. This behavior may be desired if this plugin is run
  in a separate `protoc` invocation and you encounter a `Tried to insert into
  file that doesn't exist` error.

A note on parameter values:

* `<proto_path>`: Protobuf paths beginning with `.` will be matched from the
  global root (prefix matches). All other paths will be matched as suffix
  matches.
* `(=<boolean>)`: Boolean values may be specified after a parameter, but if
  not, the value is assumed to be `true` by virtue of having listed the
  parameter.

### Usage with `protoc` and `protoc-gen-prost`

To make it easier to work with the base definitions generated by `prost`,
this plugin assumes that it is being run in a chained mode in the same
`protoc` invocation as `protoc-gen-prost`. This can be done by specifying
multiple plugins in the same `protoc` invocation like so:

```shell
protoc -I proto proto/greeter/v1/greeter.proto \
    --prost_out=proto/gen \
    --prost_opt=compile_well_known_types \
    --prost_opt=extern_path=.google.protobuf=::pbjson_types \
    --prost-serde_out=proto/gen
```

When running as separate invocations, `protoc` won't be aware of the
base definitions that were generated by `protoc-gen-prost`. In this case,
using the `no_include` directive is necessary, and you will need to
separately include the generated `.serde.rs` file.

```shell
protoc -I proto proto/greeter/v1/greeter.proto \
    --prost_out=proto/gen \
    --prost_opt=compile_well_known_types \
    --prost_opt=extern_path=.google.protobuf=::pbjson_types

protoc -I proto proto/greeter/v1/greeter.proto \
    --prost-serde_out=proto/gen \
    --prost-serde_opt=no_include
```

### Usage with _buf_

When used with _buf_, options can be specified in the `buf.gen.yaml` file.
`protoc-gen-prost-serde` should appear as a plugin step after any
`protoc-gen-prost` steps. In addition, the `compile_well_known_types`
and `extern_path=.google.protobuf=::pbjson_types` options should be specified.

```yaml
version: v1
plugins:
  - plugin: prost
    out: gen
    opt:
      - compile_well_known_types
      - extern_path=.google.protobuf=::pbjson_types
  - plugin: prost-serde
    out: gen
```

The `protoc-gen-prost-serde` plugin is also published on the Buf Schema Registry as
a plugin which you can execute remotely, without needing to explicitly install
this tool. See the [plugin listing][1] to identify the latest published version
for use. The plugin is referenced as follows:

[1]: https://buf.build/community/neoeinstein-prost-serde

```yaml
version: v1
plugins:
  - plugin: buf.build/community/neoeinstein-prost-serde:v0.2.3
    out: gen
```

`protoc-gen-prost-serde` is also compatible with the `protoc-gen-prost-crate`
plugin:

```yaml
version: v1
plugins:
  - plugin: prost
    out: gen
    opt:
      - compile_well_known_types
      - extern_path=.google.protobuf=::pbjson_types
  - plugin: prost-serde
    out: gen
  - plugin: prost-crate
    strategy: all
    out: gen
    opt:
      - no_features
```