GitHub - ascopes/protobuf-maven-plugin: Protoc integration for Maven. Supports Protoc plugins (such as gRPC), building from descriptors, discovery of sources from the classpath. (original) (raw)

A scratch-built, modern Maven plugin for seamless protoc integration. Features include:

Running protoc from Maven Central, the system path, or URLs
Running protoc plugins from binaries on the system path, Maven Central, or from various URLs
- This includes when packaged within tarballs or ZIP files!
Running protoc plugins that are packaged as regular JARs
Building from descriptor files
Building from dependencies
Generating descriptor files
Discovering *.proto sources from your project dependencies
Filtering sources based upon globs
Injecting custom arguments and environment variables into protoc
Incremental analysis to avoid rebuilding large projects when no changes have been made
Digest verification of protoc and any plugins
Running any executables from an optional sanctioned path, for corporate users in tightly-locked-down build environments
Ability to dynamically skip plugins if not resolved on certain platforms (e.g. if working with plugins that are only packaged for Linux)

Full documentation with usage examples can be found within the plugin documentation, and examples are present in the integration tests.

Quick start

Basic code generation

Getting started is very simple. The following will compile any sources that are found insrc/main/protobuf to Java classes and pop them in target/generated-sources where Maven will automatically discover them and compile them to Java bytecode.

io.github.ascopes protobuf-maven-plugin ${protobuf-java.version} generate

Tip

Any *.proto files that are discovered in project dependencies will be made available to protoc, so you can import them in exactly the same way you would with Java classes!

Other language support

Other language generation targets are also available. This plugin provides support for generating all the languages that protoc supports out of the box, including Kotlin (JVM), Python, Python typeshed stubs, and Ruby.

The following will generate Java classes and corresponding Kotlin wrappers:

io.github.ascopes protobuf-maven-plugin true

<protoc kind="binary-maven">
  <version>${protobuf-java.version}</version>
</protoc>

generate

Dependencies

Native Maven dependency management is supported out of the box, allowing you to use Maven as an artifact registry for bundles of Proto files seamlessly.

... org.example.protos user-protos 1.2.3 zip io.github.ascopes protobuf-maven-plugin

  <configuration>
    <protoc kind="binary-maven">
      <version>${protobuf-java.version}</version>
    </protoc>
  </configuration>

  <executions>
    <execution>
      <goals>
        <goal>generate</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Plugins

The following snippet will compile any protobuf sources in src/main/protobuf to Java source code, and then proceed to generate gRPC wrappers and Reactor gRPC wrappers.

io.github.ascopes protobuf-maven-plugin ${protobuf-java.version}

<plugins>
  <!-- Vanilla protoc plugins - these are platform specific executables
       just like protoc is. -->
  <plugin kind="binary-maven">
    <groupId>io.grpc</groupId>
    <artifactId>protoc-gen-grpc-java</artifactId>
    <version>${grpc.version}</version>
  </plugin>

  <!-- JVM plugins are distributed as JARs rather than native system
       executables. The protobuf-maven-plugin will automatically bootstrap
       them for you, without the need for additional
       tooling for your platform. It should "just work". -->
  <plugin kind="jvm-maven">
    <groupId>com.salesforce.servicelibs</groupId>
    <artifactId>reactor-grpc</artifactId>
    <version>${reactor-grpc.version}</version>
  </plugin>
</plugins>

generate