Provide additional arguments to pass to the protoc executable.

Generally, users do not need to use this. It is useful, however, if their use-case is not covered by other configuration parameters in this goal.

Configuring arguments that are covered by other parameters in this goal is undefined behaviour and should be avoided.

Example:

  <arguments>
    <argument>--experimental_allow_proto3_optional</argument>
    <argument>--php_out=target/generated-sources/php</argument>
  </arguments>

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

Binary plugins are protoc plugins that are regular executables, and thus can work with protoc out of the box.

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.

Example:

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

If users wish to use 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 0. Higher numbers run later than lower numbers. The built-in code generators in protoc and descriptor generation has an order of 0.
• skip - set to true to skip invoking this plugin - useful if one wishes to control whether the plugin runs via a property - optional.
• outputDirectory - where to write the generated outputs to. - if unspecified, then the outputDirectory on the Maven plugin is used instead - optional.
• registerAsCompilationRoot - whether to register the output directory as a source directory for later compilation steps. If unspecified/null, then registerAsCompilationRoot is used. If the outputDirectory is not overridden, this setting has no effect, and the project-wide setting is used. If explicitly specified, then the project setting is ignored in favour of this value instead.

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

Binary plugins are protoc plugins that are regular executables, and thus can work with protoc out of the box.

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 0. Higher numbers run later than lower numbers. The built-in code generators in protoc and descriptor generation has an order of 0.
• skip - set to true to skip invoking this plugin - useful if one wishes to control whether the plugin runs via a property - optional.
• outputDirectory - where to write the generated outputs to. - if unspecified, then the outputDirectory on the Maven plugin is used instead - optional.
• registerAsCompilationRoot - whether to register the output directory as a source directory for later compilation steps. If unspecified/null, then registerAsCompilationRoot is used. If the outputDirectory is not overridden, this setting has no effect, and the project-wide setting is used. If explicitly specified, then the project setting is ignored in favour of this value instead.

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.

Binary plugins are protoc plugins that are regular executables, and thus can work with protoc out of the box.

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>zip:https://myorganisation.org/protoc/plugins/myplugin3.zip!/protoc-gen-something.exe</url>
  </binaryUrlPlugin>
</binaryUrlPlugins>

See the user guide for details on the supported protocols.

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 0. Higher numbers run later than lower numbers. The built-in code generators in protoc and descriptor generation has an order of 0.
• skip - set to true to skip invoking this plugin - useful if one wishes to control whether the plugin runs via a property - optional.
• outputDirectory - where to write the generated outputs to. - if unspecified, then the outputDirectory on the Maven plugin is used instead - optional.
• registerAsCompilationRoot - whether to register the output directory as a source directory for later compilation steps. If unspecified/null, then registerAsCompilationRoot is used. If the outputDirectory is not overridden, this setting has no effect, and the project-wide setting is used. If explicitly specified, then the project setting is ignored in favour of this value instead.
• digest - an optional digest to verify the binary against. If specified, this is a string in the format sha512:1a2b3c4d..., using any supported message digest provided by the current JDK (e.g. md5, sha1, sha256, sha512, etc).

If true, all output directories will be cleared before protoc is invoked.

Enable this to force a clean build on each invocation.

This is ignored if incrementalCompilation is enabled, since it would discard the information needed to support incremental compilation. In this case, it will be considered to be false regardless.

How to resolve transitive dependencies.

Supported values:

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

The dependency scopes to resolve dependencies for.

If unspecified, this uses a sensible default, as documented in the goal description.

Valid values include: compile, test, provided, runtime, system, and import.

Refer to the Maven documentation for scopes for more details on the implications of each.

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

If one is using dependencies as sources, then those will also be attached, and may have license implications.

Prior to v4.0.0, this defaulted to false. As of v4.0.0, this defaults to true to improve the semantics around creating importable libraries.

Additional environment variables to pass to the protoc subprocess.

This can be used to override some internal behaviours within protoc or any associated protoc plugins during execution.

By default, any environment variables made visible to Maven will be passed to protoc. Any environment variables specified here will be appended to the default environment variables, overwriting any that have duplicate names.

This will not support overriding aspects like the system path, as those are resolved statically prior to any invocation.

Source paths to protobuf sources 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 one wishes to not compile files named user.proto, message.proto, or service.proto, they should use the following configuration.

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

Use includes if one wishes to instead include files for compilation.

Fail on missing sources.

If no sources are detected, it is usually a sign that this plui is misconfigured, or that one is including this plugin in a project that does not need it. For this reason, the plugin defaults this setting to being enabled.

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.

Users should prefer to skip the plugin if a known configuration has no targets.

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

Defaults to false.

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

Generally users will want to leave this enabled unless they have a very specific case where they 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
• excludes - a set of exclusions to apply to transitive dependencies

Exclusions are a set of objects, each with the following fields:

• groupId - the group ID to exclude
• artifactId - the artifact ID to exclude
• classifier - optional - the classifier to exclude. If omitted, any classifiers are matched.
• type - optional - the type of the artifact to exclude. If omitted, any types are matched.

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

These will not be compiled into Java sources directly.

If users wish to depend on a JAR Maven artifact containing protobuf sources, then they should add it as a dependency with the provided or test scope instead, or use importDependencies rather than this parameter.

Import paths can also be specified as paths to ZIP or JAR archives on the local file system. This plugin will extract any *.proto files, and pass them to protoc.

If users wish to compile these proto sources rather than simply including them on the import path, they should use the sourceDirectories parameter instead.

Protobuf 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 a user only wanted to compile files named user.proto, message.proto, or service.proto, then they would use the following configuration.

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

Use excludes to instead omit files from compilation.

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 when changes have been made since the last build.

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 0. Higher numbers run later than lower numbers. The built-in code generators in protoc and descriptor generation has an order of 0.
• skip - set to true to skip invoking this plugin - useful if one wishes to control whether the plugin runs via a property - optional.
• outputDirectory - where to write the generated outputs to. - if unspecified, then the outputDirectory on the Maven plugin is used instead - optional.
• registerAsCompilationRoot - whether to register the output directory as a source directory for later compilation steps. If unspecified/null, then registerAsCompilationRoot is used. If the outputDirectory is not overridden, this setting has no effect, and the project-wide setting is used. If explicitly specified, then the project setting is ignored in favour of this value instead.
• mainClass - if the plugin is not an assembled JAR at the time the protobuf-maven-plugin is run, then users must ensure they provide the fully qualified class name of the plugin entrypoint here. This is usually only needed if 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.

Generate 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.

Generate "lite" messages rather than full messages, where possible.

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.

Attach the generated protobuf descriptor file as a Maven project artifact.

This is ignored if outputDescriptorFile is not provided.

See also: outputDescriptorFile

The Maven artifact classifier for the file descriptor set descriptor when attached to the Maven project.

This is ignored if outputDescriptorAttached is false.

See also: outputDescriptorFile

The Maven artifact type for the file descriptor set descriptor when attached to the Maven project.

This is ignored if outputDescriptorAttached is false, or if outputDescriptorFile is not provided.

See also: outputDescriptorAttached, outputDescriptorFile

The path to write the protobuf descriptor file to.

Leave unspecified to disable. Writes a FileDescriptorSet (a protocol buffer, defined by descriptor.proto) containing all the input files in outputDescriptorFile.

If this is specified, then incremental compilation will always be disabled to prevent issues with inconsistent build results.

See also: outputDescriptorAttached

Include imports in generated file descriptor set descriptor files.

This is ignored if outputDescriptorFile is not provided.

See also: outputDescriptorFile

Include source information in generated file descriptor set descriptors. files.

This is ignored if outputDescriptorFile is not provided.

See also: outputDescriptorFile

Retain option details in generated file descriptor set descriptors.

This is ignored if outputDescriptorFile is not provided.

See also: outputDescriptorFile

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/.

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 users need to use an unsupported architecture/OS, or a development version of protoc.

Users may also specify a URL. See the user guide for a list of supported protocols.

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.

Optional digest to verify protoc against.

Generally, users should not need to provide this, as the Maven Central protoc binaries will already be digest-verified as part of distribution. Users may wish to specify this if using a PATH-based binary, or using a URL for protoc.

This is a string in the format sha512:1a2b3c..., using any message digest algorithm supported by the current JDK.

Generate Python sources from the protobuf sources.

Users may also want to enable Python stubs to enable generating *.pyi files for static type checkers.

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

Users will also want to enable Python itself to get actual source code to accompany the stubs.

Register the output directories as compilation roots with Maven.

This allows maven-compiler-plugin to detect and compile generated code.

Generally, users want to do this, but there may be edge cases where one wishes to control this behaviour manually instead. In this case, they should set this parameter to be false.

Generate Ruby sources from the protobuf sources.

Corporate-sanctioned path to run native executables from.

Most users SHOULD NOT specify this.

If users operate in an overly locked-down corporate environment that disallows running shell/batch scripts or native executables outside sanctioned locations on their local file system, they can specify the path here either via this configuration parameter or via a property such that any executables are first moved to a directory within this location. This is designed to be able to be used within a Maven profile if desired.

When specified, any executables will be copied to this directory prior to invoking them. These executables will be located in a nested sub-directory to allow this setting to be shared across plugin invocations whilst retaining build reproducibility.

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
• excludes - a set of exclusions to apply to transitive dependencies

Exclusions are a set of objects, each with the following fields:

• groupId - the group ID to exclude
• artifactId - the artifact ID to exclude
• classifier - optional - the classifier to exclude. If omitted, any classifiers are matched.
• type - optional - the type of the artifact to exclude. If omitted, any types are matched.

Protobuf Descriptor files to compile.

For example:

<sourceDescriptorDependencies>
  <sourceDescriptorDependency>
    <groupId>com.mycompany</groupId>
    <artifactId>common-protos</artifactId>
    <version>1.2.4</version>
    <type>protobin</type>
  </sourceDescriptorDependency>
</sourceDescriptorDependencies>

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
• excludes - a set of exclusions to apply to transitive dependencies

If users wish to use descriptor files from the local file system, use the sourceDescriptorPaths parameter instead.

Descriptor files to compile from.

The source directories to compile protobuf sources from.

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

Note that specifying custom directories will override the default directories rather than adding to them.

Source directories can also be specified as paths to ZIP or JAR archives on the local file system. This plugin will extract any *.proto files, and pass them to protoc.

If users wish to compile sources from within a Maven artifact holding a JAR or ZIP, use the sourceDependencies parameter instead.

If users wish to compile sources from descriptor files from the local file system, use the sourceDescriptorPaths parameter instead.

If uzers wish to compile sources from within a Maven artifact holding a protobuf descriptor file, use sourceDescriptorDependencies instead.