A scratch-built, modern Maven plugin for seamless protoc integration. Provides support for native and JVM-based protoc plugins, as well as automatic dependency resolution and incremental code generation.
Note
Full documentation with usage examples can be found within the plugin documentation, and examples are present in the integration tests.
Getting started is very simple. The following will compile any sources that are found in
src/main/protobuf to Java classes and pop them in target/generated-sources where Maven
will automatically discover them and compile them to Java bytecode.
<plugin>
<groupId>io.github.ascopes</groupId>
<artifactId>protobuf-maven-plugin</artifactId>
<configuration>
<protocVersion>${protobuf-java.version}</protocVersion>
</configuration>
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
</plugin>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 generation targets are also available. This plugin provides support for generating all the languages that protoc supports out of the box, including Kotlin, Python, Python typeshed stubs, Ruby, PHP, C#, C++, and Rust.
The following will generate Java classes and corresponding Kotlin wrappers:
<plugin>
<groupId>io.github.ascopes</groupId>
<artifactId>protobuf-maven-plugin</artifactId>
<configuration>
<kotlinEnabled>true</kotlinEnabled>
<protocVersion>${protobuf-java.version}</protocVersion>
</configuration>
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
</plugin>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.
<project>
...
<dependencies>
<dependency>
<groupId>org.example.protos</groupId>
<artifactId>user-protos</artifactId>
<version>1.2.3</version>
<type>zip</type>
</dependency>
</dependencies>
<plugins>
<plugin>
<groupId>io.github.ascopes</groupId>
<artifactId>protobuf-maven-plugin</artifactId>
<configuration>
<protocVersion>${protobuf-java.version}</protocVersion>
</configuration>
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</project>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.
<plugin>
<groupId>io.github.ascopes</groupId>
<artifactId>protobuf-maven-plugin</artifactId>
<configuration>
<protocVersion>${protobuf-java.version}</protocVersion>
<!-- Vanilla protoc plugins - these are platform specific executables
just like protoc is. -->
<binaryMavenPlugins>
<binaryMavenPlugin>
<groupId>io.grpc</groupId>
<artifactId>protoc-gen-grpc-java</artifactId>
<version>${grpc.version}</version>
</binaryMavenPlugin>
</binaryMavenPlugins>
<!-- JVM plugins are distributed as JARs rather than native system
executables. The protobuf-maven-plugin will automatically bootstrap
them for you. -->
<jvmMavenPlugins>
<jvmMavenPlugin>
<groupId>com.salesforce.servicelibs</groupId>
<artifactId>reactor-grpc</artifactId>
<version>${reactor-grpc.version}</version>
</jvmMavenPlugin>
</jvmMavenPlugins>
</configuration>
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
</plugin>- ✅ - actively supported/available
- 💭 - not supported, but open for discussion
- ❌ - not supported, nor planned
| Feature | Support |
|---|---|
| Maven 3.8 Support | ✅ |
| Maven 3.9 Support | ✅ |
| Maven 4.x Support | ✅ |
| Java 11 Support | ✅ |
| Java 17 Support | ✅ |
| Java 21 Support | ✅ |
| Java 24 Support | ✅ |
| Linux x86_64 | ✅ |
| Linux ARM64 | ✅ |
| macOS x86_64 | ✅ |
| macOS ARM64 | ✅ |
| Windows x86_64 | ✅ |
| Android Termux | ✅* |
Note
Maven integration is tested with the newest bugfix of each minor version that is listed (e.g. 3.9.9).
Tip
* Only supports using protoc from the system $PATH at this time.
| Feature | Support |
|---|---|
| Java | ✅ |
| Kotlin | ✅ (JVM shims out of the box, multiplatform via third-party protoc plugins) |
| C# | ✅ |
| C++ | ✅ |
| Objective C | ✅ |
| PHP | ✅ |
| Ruby | ✅ |
| Rust | ✅ |
| Python and PYI stubs | ✅ |
| Other languages and frameworks | ✅ (via third-party protoc plugins) |
| Feature | Support |
|---|---|
| From Maven repositories | ✅ (any Google-released version) |
| From system path | ✅ (as long as it is installed first) |
| From a URL | ✅ (no SOCKS/HTTP proxy support at this time) |
| Feature | Support |
|---|---|
| Proto2 | ✅ |
| Proto3 | ✅ |
| Editions | ✅ |
| Failing on warnings | ✅ (opt-in via plugin configuration) |
| Lite builds | ✅ (opt-in via plugin configuration) |
| Generation of binary descriptors | ✅ (opt-in via plugin configuration) |
| Controlling import inclusion in binary descriptors | ✅ (opt-in via plugin configuration) |
| Controlling source info inclusion in binary descriptors | ✅ (opt-in via plugin configuration) |
| Building from FileDescriptorSet descriptors | ✅ |
| Feature | Support |
|---|---|
| Incremental compilation | ✅ |
| Attaching protobuf sources to generated JARs | ✅ |
| Attaching generated binary descriptors to builds | ✅ |
Detecting importable dependencies from project <dependencies/> |
✅ |
| Detecting importable dependencies from provided filesystem paths | ✅ |
Respecting project <dependencyManagement/> |
✅ |
Compiling proto files from dependencies |
✅ (opt-in) |
| Controlling binary descriptor type | ✅ |
| Controlling binary descriptor classifier | ✅ |
| Controlling binary descriptor attachment | ✅ |
| Generation of main sources | ✅ |
| Generation of test sources | ✅ |
| Controlling the dependencies that are resolved by Maven scope | ✅ |
| Marking generates sources as compilation candidates | ✅ |
| Creating protobuf ZIP archives* | 💭 |
| Creating protobuf TAR archives* | 💭 |
Generating JAR-based protoc plugins** |
💭 |
| Consuming TAR archives for imports and sources | 💭 |
Tip
* This can currently be performed using maven-assembly-plugin.
** Set the Main-Class attribute in the MANIFEST.MF to do this. Use maven-shade-plugin if you need a fat JAR
(not required for use with protobuf-maven-plugin, but may be useful for other use
cases with third party tooling and build systems).
| Feature | Support |
|---|---|
| Calling binary protoc plugins | ✅ (from Maven repositories, URLs, system path) |
| Calling JVM-based protoc plugins | ✅ (from Maven repositories, URLs, system path -- generates the shims automatically for you) |
| Calling plugins distributed in tarballs | 💭 |
| Feature | Support |
|---|---|
| Importing paths without adding to the Maven project | ✅ (via plugin configuration) |
| Generating code from additional paths without adding to the Maven project | ✅ (via plugin configuration) |
| Controlling includes and excludes by path | ✅ (via Glob expressions in plugin configuration) |
| Failing on invalid dependencies | ✅ (opt-in via plugin configuration) |
| Failing on missing sources | ✅ (opt-out via plugin configuration) |
| Controlling whether transitive dependencies are included | ✅ (globally, or per dependency via plugin configuration) |