scalapb / ScalaPB

Protocol buffer compiler for Scala.
https://scalapb.github.io/
Apache License 2.0
1.3k stars 278 forks source link

Documentation refers to wrong maven plugin #892

Open stephen-smith opened 4 years ago

stephen-smith commented 4 years ago

https://github.com/scalapb/ScalaPB/blob/49a3b59ae811b7e3bd7f286e44dc77efcd575f21/docs/src/main/markdown/faq.md#how-do-i-use-scalapb-with-maven

It says "protobuf-maven-plugin" in two places, but that plugin doesn't (yet) was any support for scala. Instead the correct plugin is "protoc-jar-maven-plugin". The example code (https://github.com/thesamet/scalapb-maven-example/blob/fa3eb585bbbb3e20c461aefbe821e0e75e922eb4/pom.xml#L125) also refers the the wrong plugin in XML comment: "Add protobuf-maven-plugin and provide ScalaPB [...]".

It's confusing, and since I was already using protobuf-maven-plugin it implied some compatibility that was not there; the plugs differ in where they load *.proto files from, on where the output source files to, and how to specify artifacts in a OS-independent way so that I can use the same pom.xml on the (Linux) docker images used by our CI and the (MS Windows) laptops used by other developers on the project.

thesamet commented 4 years ago

Hi @stephen-smith , thanks for reporting this.

In fact, you can still use protobuf-maven-plugin, but there's caveat: it doesn't support passing options (like grpc or flat_package) into ScalaPB. If you look at a previous revision, you can see how it was used: https://github.com/thesamet/scalapb-maven-example/commit/b8fd20ccf632ece9e5bdce4603f5ca6adcd54ff0#diff-600376dffeb79835ede4a0b285078036 - protobuf-maven-plugin also doesn't require os-dependent artifacts.

If you don't need to pass custom options to the plugin it should be ok to use protobuf-maven-plugin. There is an open issue there to enable passing custom options here - feel free to drop a line there: https://github.com/xolstice/protobuf-maven-plugin/issues/56

I'll leave this issue open to address the documentation issues you pointed out, and revisit our maven support options in case there was any improvement in any of the possibilities.

stephen-smith commented 4 years ago

Thanks for the quick reply! Unfortunately, I do need to generate gRPC stubs as well, but I'll still look over that previous version and the issue you linked.