protobuf:generate
Full name:
io.github.ascopes:protobuf-maven-plugin:3.10.1:generate
Description:
Generate source code from protobuf files.
This treats generated code as being part of the main source set. For test sources, use the generate-test
goal instead.
Any project dependencies using the compile
, provided
, or system
scopes will be made available to import from protobuf sources.
By default, sources will be read from src/main/protobuf
(src/main/proto
, is also supported to assist in migration off of other unmaintained Maven plugins), and generated sources will be written to target/generated-sources/protobuf
.
Attributes:
- Requires a Maven project to be executed.
- Requires dependency resolution of artifacts in scope:
test
. - The goal is thread-safe and supports parallel builds.
- Binds by default to the lifecycle phase:
generate-sources
.
Required Parameters
Name | Type | Since | Description |
---|---|---|---|
<protocVersion> |
String |
0.0.1 |
Where to find protoc or which version to download.
This usually should correspond to the version of If set to " You can also specify a URL. See the user guide for a list of supported protocols. Note that specifying 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 resolution on Windows, the case-insensitive User Property: protobuf.compiler.version Alias: protoc |
Optional Parameters
Name | Type | Since | Description |
---|---|---|---|
<arguments> |
List<String> |
3.8.0 |
Provide additional arguments to pass to the protoc executable.
Note that generally, you should not need to use this. It is useful, however, if your 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. |
<binaryMavenPlugins> |
List<MavenProtocPluginBean> |
0.3.0 |
Binary plugins to use with the protobuf compiler, sourced from a Maven repository.
Binary plugins are 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:
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 Objects support the following attributes:
|
<binaryPathPlugins> |
List<PathProtocPluginBean> |
2.0.0 |
Binary plugins to use with the protobuf compiler, sourced from the system PATH .
Binary plugins are For example:
Objects support the following attributes:
On Linux, macOS, and other POSIX-like systems, resolution looks for an executable binary matching the exact name in any directory in the On Windows, the case-insensitive |
<binaryUrlPlugins> |
List<UriProtocPluginBean> |
2.0.0 |
Binary plugins to use with the protobuf compiler, specified as a valid URL.
Binary plugins are For example:
See the user guide for details on the supported protocols. Objects support the following attributes:
|
<cleanOutputDirectories> |
boolean |
3.6.0 |
If true , all output directories will be cleared before protoc is invoked.
Enable this to force a clean build on each invocation. Note that this is ignored if Default: false |
<cppEnabled> |
boolean |
1.1.0 |
Deprecated. will be removed in v4.0.0. Users wishing to generate C++ sources should use the arguments to specify --cpp_out=path .Enable generating C++ sources and headers from the protobuf sources. Default: false |
<csharpEnabled> |
boolean |
1.1.0 |
Deprecated. will be removed in v4.0.0. Users wishing to generate C# sources should use the arguments to specify --csharp_out=path .Enable generating C# sources from the protobuf sources. Default: false |
<dependencyResolutionDepth> |
DependencyResolutionDepth |
1.2.0 |
How to resolve transitive dependencies.
Supported values:
Default: TRANSITIVE |
<dependencyScopes> |
Set<String> |
2.4.0 |
The dependency scopes to resolve dependencies for.
If unspecified, this uses a sensible default, as documented in the goal description. Valid values include: Refer to the Maven documentation for scopes for more details on the implications of each. |
<embedSourcesInClassOutputs> |
boolean |
2.1.0 |
Enable attaching 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. Default: false |
<environmentVariables> |
Map<String,String> |
3.7.0 |
Additional environment variables to pass to the protoc subprocess.
This can be used to override some internal behaviours within By default, any environment variables made visible to Maven will be passed to Note that this will not support overriding aspects like the system path, as those are resolved statically prior to any invocation. |
<excludes> |
List<String> |
2.2.0 |
Source paths to protobuf sources to exclude from compilation.
This can be used to limit what is compiled by Each entry is treated as a glob pattern, and is applied to the path of each discovered compilation candidate file, relative to the See 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
Use User Property: protobuf.compiler.excludes |
<failOnInvalidDependencies> |
boolean |
2.4.0 |
Deprecated. will be removed in v4.0.0: invalid dependencies will be ignored. Fail the build if any invalid direct or transitive dependencies are encountered. If If Prior to Default: false |
<failOnMissingSources> |
boolean |
0.5.0 |
Deprecated. will be removed in v4.0.0: missing sources will always be an error. 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 Default: true |
<failOnMissingTargets> |
boolean |
2.0.0 |
Fail if no output languages and no plugins are enabled.
This defaults to Users should prefer to Default: true |
<fatalWarnings> |
boolean |
0.0.1 |
Specify that any warnings emitted by protoc should be treated as errors and fail the build.
Defaults to Default: false |
<ignoreProjectDependencies> |
boolean |
1.2.0 |
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. Default: false |
<importDependencies> |
List<MavenDependencyBean> |
1.2.0 |
Specify additional dependencies to import protobuf sources from.
These will not be compiled into Java sources directly. Objects support the following attributes:
Exclusions are a set of objects, each with the following fields:
|
<importPaths> |
List<Path> |
0.1.0 |
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 Maven artifact containing protobuf sources, add it as a dependency with the Import paths can also be specified as paths to ZIP or JAR archives on the local file system. This plugin will extract any If you wish to also compile proto sources, use the |
<includes> |
List<String> |
2.2.0 |
Protobuf source paths to include in compilation.
This can be used to limit what is compiled by Each entry is treated as a glob pattern, and is applied to the path of each discovered compilation candidate file, relative to the See 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
Use User Property: protobuf.compiler.includes |
<incrementalCompilation> |
boolean |
2.7.0 |
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. Default: true User Property: protobuf.compiler.incremental |
<javaEnabled> |
boolean |
0.1.1 |
Enable generating Java sources from the protobuf sources.
Defaults to Default: true |
<jvmMavenPlugins> |
List<MavenProtocPluginBean> |
0.3.0 |
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:
This mechanism allows plugin vendors to implement their plugins in Java and just distribute platform-independent JAR instead. Objects support the following attributes:
|
<kotlinEnabled> |
boolean |
0.1.0 |
Generate Kotlin API wrapper code around the generated Java code.
This may require Default: false |
<liteOnly> |
boolean |
0.0.1 |
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. Default: false |
<objcEnabled> |
boolean |
1.1.0 |
Deprecated. will be removed in v4.0.0. Users wishing to generate Objective-C sources should use the arguments to specify --objc_out=path .Generate Objective-C sources from the protobuf sources. Default: false |
<outputDescriptorAttached> |
boolean |
2.11.0 |
Attach the generated protobuf descriptor file as a Maven project artifact.
This is ignored if See also: outputDescriptorFile Default: false |
<outputDescriptorAttachmentClassifier> |
String |
2.11.0 |
The Maven artifact classifier for the file descriptor set descriptor when attached to the Maven project.
This is ignored if See also: outputDescriptorFile |
<outputDescriptorAttachmentType> |
String |
2.11.0 |
The Maven artifact type for the file descriptor set descriptor when attached to the Maven project.
This is ignored if See also: outputDescriptorAttached, outputDescriptorFile |
<outputDescriptorFile> |
Path |
2.9.0 |
The path to write the protobuf descriptor file to.
Leave unspecified to disable. Writes a FileDescriptorSet (a protocol buffer, defined by If this is specified, then incremental compilation will always be disabled to prevent issues with inconsistent build results. See also: outputDescriptorAttached |
<outputDescriptorIncludeImports> |
boolean |
2.10.0 |
Include imports in generated file descriptor set descriptor files.
This is ignored if See also: outputDescriptorFile Default: false |
<outputDescriptorIncludeSourceInfo> |
boolean |
2.10.0 |
Include source information in generated file descriptor set descriptors. files.
This is ignored if See also: outputDescriptorFile Default: false |
<outputDescriptorRetainOptions> |
boolean |
2.10.0 |
Retain option details in generated file descriptor set descriptors.
This is ignored if See also: outputDescriptorFile Default: false |
<outputDirectory> |
Path |
0.1.0 |
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 |
<phpEnabled> |
boolean |
1.1.0 |
Deprecated. will be removed in v4.0.0. Users wishing to generate PHP sources should use the arguments to specify --php_out=path .Generate PHP sources from the protobuf sources. Default: false |
<protocDigest> |
Digest |
3.5.0 |
Optional digest to verify protoc against.
Generally, you will not need to provide this, as the Maven Central This is a string in the format User Property: protobuf.compiler.digest |
<pythonEnabled> |
boolean |
1.1.0 |
Generate Python sources from the protobuf sources.
If you enable this, you probably will also want to enable Python stubs to enable generating Default: false |
<pythonStubsEnabled> |
boolean |
1.1.0 |
Generate 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. Default: false |
<registerAsCompilationRoot> |
boolean |
0.5.0 |
Register the output directories as compilation roots with Maven.
This allows 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 Default: true |
<rubyEnabled> |
boolean |
1.1.0 |
Generate Ruby sources from the protobuf sources. Default: false |
<rustEnabled> |
boolean |
1.1.0 |
Deprecated. will be removed in v4.0.0. Users wishing to generate Rust sources should use the arguments to specify --rust_out=path .Generate Rust sources from the protobuf sources. Default: false |
<sanctionedExecutablePath> |
Path |
3.9.0 |
Corporate-sanctioned path to run native executables from.
Most users SHOULD NOT specify this. If you operate in an overly locked-down corporate environment that disallows running shell/batch scripts or native executables outside sanctioned locations on your local file system, you 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. User Property: protobuf.sanctioned-executable-path |
<skip> |
boolean |
2.0.0 |
Whether to skip the plugin execution entirely. Default: false User Property: protobuf.skip |
<sourceDependencies> |
List<MavenDependencyBean> |
1.2.0 |
Additional dependencies to compile, pulled from the Maven repository.
Note that this will resolve dependencies recursively unless For example:
Objects support the following attributes:
Exclusions are a set of objects, each with the following fields:
|
<sourceDescriptorDependencies> |
List<MavenDependencyBean> |
3.1.0 |
Protobuf Descriptor files to compile.
For example:
Objects support the following attributes:
If you wish to use descriptor files from the local file system, use the |
<sourceDescriptorPaths> |
List<Path> |
3.1.0 |
Descriptor files to compile from. |
<sourceDirectories> |
List<Path> |
0.0.1 |
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 If you wish to compile sources from within a Maven artifact holding a JAR or ZIP, use the If you wish to compile sources from descriptor files from the local file system, use the If you wish to compile sources from within a Maven artifact holding a protobuf descriptor file, use Alias: sourcePaths |
Parameter Details
<arguments>
protoc
executable.
Note that generally, you should not need to use this. It is useful, however, if your 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.
- Type:
java.util.List<java.lang.String>
- Since:
3.8.0
- Required:
No
<binaryMavenPlugins>
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.
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 - requiredartifactId
- the artifact ID - requiredversion
- the version - requiredtype
- the artifact type - optionalclassifier
- the artifact classifier - optionaloptions
- 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 inprotoc
and descriptor generation has an order of 0.skip
- set totrue
to skip invoking this plugin - useful if you want to control whether the plugin runs via a property - optional.outputDirectory
- where to write the generated outputs to. - if unspecified, then theoutputDirectory
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, thenregisterAsCompilationRoot
is used. If theoutputDirectory
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.
- Type:
java.util.List<io.github.ascopes.protobufmavenplugin.plugins.MavenProtocPluginBean>
- Since:
0.3.0
- Required:
No
<binaryPathPlugins>
PATH
.
Binary plugins are protoc
plugins that are regular executables, and thus can work with protoc
out of the box.
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 0. Higher numbers run later than lower numbers. The built-in code generators inprotoc
and descriptor generation has an order of 0.skip
- set totrue
to skip invoking this plugin - useful if you want to control whether the plugin runs via a property - optional.outputDirectory
- where to write the generated outputs to. - if unspecified, then theoutputDirectory
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, thenregisterAsCompilationRoot
is used. If theoutputDirectory
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.
- Type:
java.util.List<io.github.ascopes.protobufmavenplugin.plugins.PathProtocPluginBean>
- Since:
2.0.0
- Required:
No
<binaryUrlPlugins>
Binary plugins are protoc
plugins that are regular executables, and thus can work with protoc
out of the box.
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>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 inprotoc
and descriptor generation has an order of 0.skip
- set totrue
to skip invoking this plugin - useful if you want to control whether the plugin runs via a property - optional.outputDirectory
- where to write the generated outputs to. - if unspecified, then theoutputDirectory
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, thenregisterAsCompilationRoot
is used. If theoutputDirectory
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 formatsha512:1a2b3c4d...
, using any supported message digest provided by your JDK (e.g.md5
,sha1
,sha256
,sha512
, etc).
- Type:
java.util.List<io.github.ascopes.protobufmavenplugin.plugins.UriProtocPluginBean>
- Since:
2.0.0
- Required:
No
<cleanOutputDirectories>
true
, all output directories will be cleared before protoc
is invoked.
Enable this to force a clean build on each invocation.
Note that this is ignored if incrementalCompilation
is enabled.
- Type:
boolean
- Since:
3.6.0
- Required:
No
- Default:
false
<cppEnabled>
will be removed in v4.0.0. Users wishing to generate C++ sources should use the
arguments
to specify --cpp_out=path
.- Type:
boolean
- Since:
1.1.0
- Required:
No
- Default:
false
<csharpEnabled>
will be removed in v4.0.0. Users wishing to generate C# sources should use the
arguments
to specify --csharp_out=path
.- Type:
boolean
- Since:
1.1.0
- Required:
No
- Default:
false
<dependencyResolutionDepth>
Supported values:
TRANSITIVE
- resolve transitive dependencies.DIRECT
- only resolve direct dependencies that were explicitly specified.
- Type:
io.github.ascopes.protobufmavenplugin.dependencies.DependencyResolutionDepth
- Since:
1.2.0
- Required:
No
- Default:
TRANSITIVE
<dependencyScopes>
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.
- Type:
java.util.Set<java.lang.String>
- Since:
2.4.0
- Required:
No
<embedSourcesInClassOutputs>
Note that if you are using dependencies as sources, then those will also be attached, and may have license implications.
- Type:
boolean
- Since:
2.1.0
- Required:
No
- Default:
false
<environmentVariables>
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.
Note that this will not support overriding aspects like the system path, as those are resolved statically prior to any invocation.
- Type:
java.util.Map<java.lang.String, java.lang.String>
- Since:
3.7.0
- Required:
No
<excludes>
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.
- Type:
java.util.List<java.lang.String>
- Since:
2.2.0
- Required:
No
- User Property:
protobuf.compiler.excludes
<failOnInvalidDependencies>
will be removed in v4.0.0: invalid dependencies will be ignored.
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.
- Type:
boolean
- Since:
2.4.0
- Required:
No
- Default:
false
<failOnMissingSources>
will be removed in v4.0.0: missing sources will always be an error.
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.
- Type:
boolean
- Since:
0.5.0
- Required:
No
- Default:
true
<failOnMissingTargets>
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.
- Type:
boolean
- Since:
2.0.0
- Required:
No
- Default:
true
<fatalWarnings>
protoc
should be treated as errors and fail the build.
Defaults to false
.
- Type:
boolean
- Since:
0.0.1
- Required:
No
- Default:
false
<ignoreProjectDependencies>
<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.
- Type:
boolean
- Since:
1.2.0
- Required:
No
- Default:
false
<importDependencies>
These will not be compiled into Java sources directly.
Objects support the following attributes:
groupId
- the group ID - requiredartifactId
- the artifact ID - requiredversion
- the version - requiredtype
- the artifact type - optionalclassifier
- the artifact classifier - optionaldependencyResolutionDepth
- the dependency resolution depth to override the project settings with - optionalexcludes
- 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 excludeartifactId
- the artifact ID to excludeclassifier
- 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.
- Type:
java.util.List<io.github.ascopes.protobufmavenplugin.dependencies.MavenDependencyBean>
- Since:
1.2.0
- Required:
No
<importPaths>
These will not be compiled into Java sources directly.
If you wish to depend on a JAR Maven artifact containing protobuf sources, 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 for you, and pass them to protoc
.
If you wish to also compile proto sources, use the sourceDirectories
parameter instead.
- Type:
java.util.List<java.nio.file.Path>
- Since:
0.1.0
- Required:
No
<includes>
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.
- Type:
java.util.List<java.lang.String>
- Since:
2.2.0
- Required:
No
- User Property:
protobuf.compiler.includes
<incrementalCompilation>
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.
- Type:
boolean
- Since:
2.7.0
- Required:
No
- User Property:
protobuf.compiler.incremental
- Default:
true
<javaEnabled>
Defaults to true
, although some users may wish to disable this if using an alternative plugin that covers generating the code for models instead.
- Type:
boolean
- Since:
0.1.1
- Required:
No
- Default:
true
<jvmMavenPlugins>
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 - requiredartifactId
- the artifact ID - requiredversion
- the version - requiredtype
- the artifact type - optionalclassifier
- the artifact classifier - optionaloptions
- a string of options to pass to the plugin. This uses the standardprotoc
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 inprotoc
and descriptor generation has an order of 0.skip
- set totrue
to skip invoking this plugin - useful if you want to control whether the plugin runs via a property - optional.outputDirectory
- where to write the generated outputs to. - if unspecified, then theoutputDirectory
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, thenregisterAsCompilationRoot
is used. If theoutputDirectory
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 theprotobuf-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, theMain-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.
- Type:
java.util.List<io.github.ascopes.protobufmavenplugin.plugins.MavenProtocPluginBean>
- Since:
0.3.0
- Required:
No
<kotlinEnabled>
This may require javaEnabled
to also be true
, otherwise compilation may fail unless other sources are generated to replace the expected Java ones.
- Type:
boolean
- Since:
0.1.0
- Required:
No
- Default:
false
<liteOnly>
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.
- Type:
boolean
- Since:
0.0.1
- Required:
No
- Default:
false
<objcEnabled>
will be removed in v4.0.0. Users wishing to generate Objective-C sources should use the
arguments
to specify --objc_out=path
.- Type:
boolean
- Since:
1.1.0
- Required:
No
- Default:
false
<outputDescriptorAttached>
This is ignored if outputDescriptorFile
is not provided.
See also: outputDescriptorFile
- Type:
boolean
- Since:
2.11.0
- Required:
No
- Default:
false
<outputDescriptorAttachmentClassifier>
This is ignored if outputDescriptorAttached
is false.
See also: outputDescriptorFile
- Type:
java.lang.String
- Since:
2.11.0
- Required:
No
<outputDescriptorAttachmentType>
This is ignored if outputDescriptorAttached
is false, or if outputDescriptorFile
is not provided.
See also: outputDescriptorAttached, outputDescriptorFile
- Type:
java.lang.String
- Since:
2.11.0
- Required:
No
<outputDescriptorFile>
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
- Type:
java.nio.file.Path
- Since:
2.9.0
- Required:
No
<outputDescriptorIncludeImports>
This is ignored if outputDescriptorFile
is not provided.
See also: outputDescriptorFile
- Type:
boolean
- Since:
2.10.0
- Required:
No
- Default:
false
<outputDescriptorIncludeSourceInfo>
This is ignored if outputDescriptorFile
is not provided.
See also: outputDescriptorFile
- Type:
boolean
- Since:
2.10.0
- Required:
No
- Default:
false
<outputDescriptorRetainOptions>
This is ignored if outputDescriptorFile
is not provided.
See also: outputDescriptorFile
- Type:
boolean
- Since:
2.10.0
- Required:
No
- Default:
false
<outputDirectory>
Leave unspecified or explicitly null to use the default for the goal. This defaults to the Maven generated sources directory within target/
.
- Type:
java.nio.file.Path
- Since:
0.1.0
- Required:
No
<phpEnabled>
will be removed in v4.0.0. Users wishing to generate PHP sources should use the
arguments
to specify --php_out=path
.- Type:
boolean
- Since:
1.1.0
- Required:
No
- Default:
false
<protocDigest>
protoc
against.
Generally, you will not need to provide this, as the Maven Central protoc
binaries will already be digest-verified as part of distribution. You may wish to specify this if you are 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 your JDK.
- Type:
io.github.ascopes.protobufmavenplugin.digests.Digest
- Since:
3.5.0
- Required:
No
- User Property:
protobuf.compiler.digest
<protocVersion>
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. 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. In v4.0.0, this will be renamed to <protoc />
.
- Type:
java.lang.String
- Since:
0.0.1
- Required:
Yes
- User Property:
protobuf.compiler.version
- Alias:
protoc
<pythonEnabled>
If you enable this, you probably will also want to enable Python stubs to enable generating *.pyi
files for static type checkers.
- Type:
boolean
- Since:
1.1.0
- Required:
No
- Default:
false
<pythonStubsEnabled>
*.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.
- Type:
boolean
- Since:
1.1.0
- Required:
No
- Default:
false
<registerAsCompilationRoot>
This allows maven-compiler-plugin
to detect and compile generated code.
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
.
- Type:
boolean
- Since:
0.5.0
- Required:
No
- Default:
true
<rubyEnabled>
- Type:
boolean
- Since:
1.1.0
- Required:
No
- Default:
false
<rustEnabled>
will be removed in v4.0.0. Users wishing to generate Rust sources should use the
arguments
to specify --rust_out=path
.- Type:
boolean
- Since:
1.1.0
- Required:
No
- Default:
false
<sanctionedExecutablePath>
Most users SHOULD NOT specify this.
If you operate in an overly locked-down corporate environment that disallows running shell/batch scripts or native executables outside sanctioned locations on your local file system, you 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.
- Type:
java.nio.file.Path
- Since:
3.9.0
- Required:
No
- User Property:
protobuf.sanctioned-executable-path
<skip>
- Type:
boolean
- Since:
2.0.0
- Required:
No
- User Property:
protobuf.skip
- Default:
false
<sourceDependencies>
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 - requiredartifactId
- the artifact ID - requiredversion
- the version - requiredtype
- the artifact type - optionalclassifier
- the artifact classifier - optionaldependencyResolutionDepth
- the dependency resolution depth to override the project settings with - optionalexcludes
- 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 excludeartifactId
- the artifact ID to excludeclassifier
- 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.
- Type:
java.util.List<io.github.ascopes.protobufmavenplugin.dependencies.MavenDependencyBean>
- Since:
1.2.0
- Required:
No
<sourceDescriptorDependencies>
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 - requiredartifactId
- the artifact ID - requiredversion
- the version - requiredtype
- the artifact type - optionalclassifier
- the artifact classifier - optionalexcludes
- a set of exclusions to apply to transitive dependencies
If you wish to use descriptor files from the local file system, use the sourceDescriptorPaths
parameter instead.
- Type:
java.util.List<io.github.ascopes.protobufmavenplugin.dependencies.MavenDependencyBean>
- Since:
3.1.0
- Required:
No
<sourceDescriptorPaths>
- Type:
java.util.List<java.nio.file.Path>
- Since:
3.1.0
- Required:
No
<sourceDirectories>
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 for you, and pass them to protoc
.
If you wish to compile sources from within a Maven artifact holding a JAR or ZIP, use the sourceDependencies
parameter instead.
If you wish to compile sources from descriptor files from the local file system, use the sourceDescriptorPaths
parameter instead.
If you wish to compile sources from within a Maven artifact holding a protobuf descriptor file, use sourceDescriptorDependencies
instead.
- Type:
java.util.List<java.nio.file.Path>
- Since:
0.0.1
- Required:
No
- Alias:
sourcePaths