Binary plugins to use with the protobuf compiler, sourced from a Maven repository.

Plugin artifacts must be a native executable. By default, the OS and CPU architecture is automatically generated and injected in the classifier if the classifier and type are not provided explicitly.

For example:

<binaryMavenPlugins>
  <binaryMavenPlugin>
    <groupId>com.salesforce.servicelibs</groupId>
    <artifactId>reactor-grpc</artifactId>
    <version>1.2.4</version>
  </binaryMavenPlugin>
</binaryMavenPlugins>

If you have a Java-based plugin that does not distribute a native executable, or are using a more obscure system architecture, then using a jvmMavenPlugin may be more preferable.

Objects support the following attributes:

• groupId - the group ID - required
• artifactId - the artifact ID - required
• version - the version - required
• type - the artifact type - optional
• classifier - the artifact classifier - optional
• options - a string of options to pass to the plugin - optional.
• order - an integer order to run the plugins in. Defaults to 100,000. Higher numbers run later than lower numbers.
• skip - set to true to skip invoking this plugin - useful if you want to control whether the plugin runs via a property - optional.

Binary plugins to use with the protobuf compiler, sourced from the system PATH.

For example:

<binaryPathPlugins>
  <binaryPathPlugin>
    <name>protoc-gen-grpc-java</name>
  </binaryPathPlugin>
  <binaryPathPlugin>
    <name>protoc-gen-something-else</name>
    <options>foo=bar,baz=bork</options>
  </binaryPathPlugin>
</binaryPathPlugins>

Objects support the following attributes:

• name - the name of the binary to resolve.
• options - a string of options to pass to the plugin - optional.
• order - an integer order to run the plugins in. Defaults to 100,000. Higher numbers run later than lower numbers.
• skip - set to true to skip invoking this plugin - useful if you want to control whether the plugin runs via a property - optional.

On Linux, macOS, and other POSIX-like systems, resolution looks for an executable binary matching the exact name in any directory in the $PATH environment variable.

On Windows, the case-insensitive %PATH% environment variable is searched for an executable that matches the name, ignoring case and any file extension. The file extension is expected to match any extension in the %PATHEXT% environment variable.

Binary plugins to use with the protobuf compiler, specified as a valid URL.

This includes support for:

• Local file system objects, specified using file://path/to/file
• HTTP resources, specified using http://example.website/path/to/file
• HTTPS resources, specified using https://example.website/path/to/file
• FTP resources, specified using ftp://example.server/path/to/file

Additionally, the jar protocol can be used with any of the above to enable extracting a file from a JAR or ZIP and using it directly.

For example:

<binaryUrlPlugins>
  <!-- FTP resource -->
  <binaryUrlPlugin>
    <url>ftp://myorganisation.org/protoc/plugins/myplugin.exe</url>
  </binaryUrlPlugin>

  <!-- HTTP resource with custom options-->
  <binaryUrlPlugin>
    <url>https://myorganisation.org/protoc/plugins/myplugin2.exe</url>
    <options>foo=bar,baz=bork</options>
  </binaryUrlPlugin>

  <!-- HTTP resource that is a ZIP holding the binary we want. -->
  <binaryUrlPlugin>
    <url>jar:https://myorganisation.org/protoc/plugins/myplugin3.zip!/protoc-gen-something.exe</url>
  </binaryUrlPlugin>
</binaryUrlPlugins>

Objects support the following attributes:

• url - the URL to resolve.
• options - a string of options to pass to the plugin - optional.
• order - an integer order to run the plugins in. Defaults to 100,000. Higher numbers run later than lower numbers.
• skip - set to true to skip invoking this plugin - useful if you want to control whether the plugin runs via a property - optional.

Enable generating C++ sources from the protobuf sources.

Enable generating C# sources from the protobuf sources.

The scope to resolve dependencies with.

Supported values:

• TRANSITIVE - resolve all dependencies.
• DIRECT - only resolve dependencies that were explicitly specified.

The dependency scopes to resolve dependencies for.

Set whether to attach all compiled protobuf sources to the output of this Maven project so that they are included in any generated JAR.

Note that if you are using dependencies as sources, then those will also be attached, and may have license implications. Therefore, this will default to false.

Source paths to exclude from compilation.

This can be used to limit what is compiled by protoc.

Each entry is treated as a glob pattern, and is applied to the path of each discovered compilation candidate file, relative to the sourceDirectory or sourceDependency that provides them.

See java.nio.file.FileSystem#getPathMatcher for full details of the supported syntax within glob patterns.

If a file matches any of these patterns, it is automatically excluded.

If not provided, then the default is to not exclude anything.

For example, if you wanted to not compile files named user.proto, message.proto, or service.proto, you could use the following configuration.

<excludes>
  <exclude>**/user.proto</exclude>
  <exclude>**/message.proto</exclude>
  <exclude>**/service.proto</exclude>
</excludes>

Use includes if you wish to instead include files for compilation.

Whether to fail if any invalid direct or transitive dependencies are encountered.

If true, the build will be aborted with an error if any invalid dependency is encountered.

If false, then the build will report any invalid dependencies as errors in the logs, before proceeding with the build. Any invalid dependencies will be discarded.

Prior to v2.4.0, any invalid dependencies would result in an error being raised and the build being aborted. In v2.4.0, this has been relaxed.

Whether to fail on missing sources.

If no sources are detected, it is usually a sign that this plugin is misconfigured, or that you are including this plugin in a project that does not need it. For this reason, the plugin defaults this setting to being enabled. If you wish to not fail, you can explicitly set this to false instead.

Whether to fail if no output languages and no plugins are enabled.

This defaults to true, but may be set to false if all plugins are optional and no languages are enabled.

Specify that any warnings emitted by protoc should be treated as errors and fail the build.

Defaults to false.

Whether to ignore the <dependencies/> blocks in the Maven project when discovering *.proto files to add to the import paths.

Generally you will want to leave this enabled unless you have a very specific case where you wish to take control of how dependency resolution works.

Specify additional dependencies to import protobuf sources from.

These will not be compiled into Java sources directly.

Objects support the following attributes:

• groupId - the group ID - required
• artifactId - the artifact ID - required
• version - the version - required
• type - the artifact type - optional
• classifier - the artifact classifier - optional
• dependencyResolutionDepth - the dependency resolution depth to override the project settings with - optional

Specify additional paths to import protobuf sources from on the local file system.

These will not be compiled into Java sources directly.

If you wish to depend on a JAR containing protobuf sources, add it as a dependency with the provided or test scope instead, or use importDependencies.

Source paths to include in compilation.

This can be used to limit what is compiled by protoc.

Each entry is treated as a glob pattern, and is applied to the path of each discovered compilation candidate file, relative to the sourceDirectory or sourceDependency that provides them

See java.nio.file.FileSystem#getPathMatcher for full details of the supported syntax within glob patterns.

If a file matches any of these patterns, it is automatically included.

If not provided, then the default is to allow any Protobuf source file.

For example, if you only wanted to compile files named user.proto, message.proto, or service.proto, you could use the following configuration.

<includes>
  <include>**/user.proto</include>
  <include>**/message.proto</include>
  <include>**/service.proto</include>
</includes>

Use excludes if you wish to instead omit files from compilation.

Whether to enable "incremental" compilation.

When enabled, this plugin will track changes to sources and importable protobuf dependencies between builds, making a best-effort attempt to only rebuild files that have changed since the last build. This will reduce the time that large projects take to build when repeatedly rebuilt during development.

Warning: this is highly experimental, and may change or be removed in a future release.

By default, this is set to false, although it may be changed to true eventually.

Enable generating Java sources from the protobuf sources.

Defaults to true, although some users may wish to disable this if using an alternative plugin that covers generating the code for models instead.

Additional pure-Java plugins to use with the protobuf compiler.

Unlike artifact-based plugins, these are pure Java JAR applications that abide by the protoc compiler API, and will be provided to the compiler via generated scripts.

For example:

<jvmMavenPlugins>
  <jvmMavenPlugin>
    <groupId>com.salesforce.servicelibs</groupId>
    <artifactId>reactor-grpc</artifactId>
    <version>1.2.4</version>
  </jvmMavenPlugin>
</jvmMavenPlugins>

This mechanism allows plugin vendors to implement their plugins in Java and just distribute platform-independent JAR instead.

Objects support the following attributes:

• groupId - the group ID - required
• artifactId - the artifact ID - required
• version - the version - required
• type - the artifact type - optional
• classifier - the artifact classifier - optional
• options - a string of options to pass to the plugin. This uses the standard protoc interface for specifying options - optional.
• order - an integer order to run the plugins in. Defaults to 100,000. Higher numbers run later than lower numbers.
• skip - set to true to skip invoking this plugin - useful if you want to control whether the plugin runs via a property - optional.
• mainClass - if the plugin is not an assembled JAR at the time the protobuf-maven-plugin is run, then you will need to provide the fully qualified class name of the plugin entrypoint here. This is usually only needed if you are creating the JVM plugin within the same project. If the plugin is an assembled JAR, then this option is optional, the Main-Class manifest entry will be used when present if this is not provided.
• jvmArgs - a list of commandline arguments to pass to the plugin process - optional.
• jvmConfigArgs - a list of commandline arguments to configure the JVM itself. This is used to control factors such as JIT compilation, JVM properties, heap size, etc. Users should leave this as the default value (which optimises for short-lived processes) unless they know exactly what they are doing - optional.

Enable generating Kotlin API wrapper code around the generated Java code.

This may require javaEnabled to also be true, otherwise compilation may fail unless other sources are generated to replace the expected Java ones.

Whether to only generate "lite" messages or not.

These are bare-bones sources that do not contain most of the metadata that regular Protobuf sources contain, and are designed for low-latency/low-overhead scenarios.

See the protobuf documentation for the pros and cons of this.

Enable generating Objective-C sources from the protobuf sources.

Override the directory to output generated code to.

Leave unspecified or explicitly null to use the default for the goal. This defaults to the Maven generated sources directory within target/.

Enable generating PHP sources from the protobuf sources.

Specifies where to find protoc or which version to download.

This usually should correspond to the version of protobuf-java or similar that is in use.

If set to "PATH", then protoc is resolved from the system path rather than being downloaded. This is useful if you need to use an unsupported architecture/OS, or a development version of protoc.

You can also specify a URL that points to:

• Local file system objects, specified using file://path/to/file
• HTTP resources, specified using http://example.website/path/to/file
• HTTPS resources, specified using https://example.website/path/to/file
• FTP resources, specified using ftp://example.server/path/to/file

Note that specifying -Dprotobuf.compiler.version in the MAVEN_OPTS or on the command line overrides the version specified in the POM. This enables users to easily override the version of protoc in use if their system is unable to support the version specified in the POM. Termux users in particular will find -Dprotobuf.compiler.version=PATH to be useful, due to platform limitations with libpthread that can result in SIGSYS (Bad System Call) being raised.

Path resolution on Linux, macOS, and other POSIX-like systems, resolution looks for an executable binary matching the exact name in any directory in the $PATH environment variable.

Path resolution on Windows, the case-insensitive %PATH% environment variable is searched for an executable that matches the name, ignoring case and any file extension. The file extension is expected to match any extension in the %PATHEXT% environment variable.

Enable generating Python sources from the protobuf sources.

If you enable this, you probably will also want to enable Python stubs to enable generating *.pyi files for static type checkers.

Enable generating Python stubs (*.pyi files) for static typechecking from the protobuf sources.

If you enable this, you probably will also want to enable Python itself to get actual source code to accompany the stubs.

Whether to register the output directories as compilation roots with Maven.

Generally, you want to do this, but there may be edge cases where you wish to control this behaviour manually instead. In this case, set this parameter to be false.

Enable generating Ruby sources from the protobuf sources.

Enable generating Rust sources from the protobuf sources.

Whether to skip the plugin execution entirely.

Additional dependencies to compile, pulled from the Maven repository.

Note that this will resolve dependencies recursively unless dependencyResolutionDepth is set to DIRECT.

For example:

<sourceDependencies>
  <sourceDependency>
    <groupId>com.mycompany</groupId>
    <artifactId>common-protos</artifactId>
    <version>1.2.4</version>
    <type>zip</type>
  </sourceDependency>
</sourceDependencies>

Objects support the following attributes:

• groupId - the group ID - required
• artifactId - the artifact ID - required
• version - the version - required
• type - the artifact type - optional
• classifier - the artifact classifier - optional
• dependencyResolutionDepth - the dependency resolution depth to override the project settings with - optional

Override the source directories to compile from.

Leave unspecified or explicitly null/empty to use the defaults.