Binary plugins from Maven Central

If the plugin you wish to use is on Maven Central or any other Maven repository, you can reference that plugin directly via the group ID, artifact ID, and version (like any other Maven artifact).

<plugin>
  <groupId>io.github.ascopes</groupId>
  <artifactId>protobuf-maven-plugin</artifactId>
  <version>...</version>

  <configuration>
    ...
    <binaryMavenPlugins>
      <binaryMavenPlugin>
        <groupId>io.grpc</groupId>
        <artifactId>protoc-gen-grpc-java</artifactId>
        <version>${grpc.version}</version>
      </binaryMavenPlugin>
    </binaryMavenPlugins>
  </configuration>

  ...
</plugin>

Binary plugins from the system path

If you instead wish to read the executable from the system $PATH, then you can specify an executable name instead:

<plugin>
  <groupId>io.github.ascopes</groupId>
  <artifactId>protobuf-maven-plugin</artifactId>
  <version>...</version>

  <configuration>
    ...
    <binaryPathPlugins>
      <binaryPathPlugin>
        <name>protoc-gen-grpc-java</name>
      </binaryPathPlugin>
    </binaryPathPlugins>
  </configuration>

  ...
</plugin>

You can also mark these plugins as being optional by setting <optional>true</optional> on the individual plugin objects. This will prevent the Maven plugin from failing the build if the protoc plugin cannot be resolved on the system path. This is useful for specific cases where resources may only be available during CI builds but do not prevent the application being built locally.

On Linux, MacOS, and other POSIX-like operating systems, this will read the $PATH environment variable and search for a binary named the given name case-sensitively. The executable MUST be executable by the current user (i.e. chmod +x /path/to/binary), otherwise it will be ignored.

On Windows, this will respect the %PATH% environment variable (case insensitive). The path will be searched for files where their name matches the binary case-insensitively, ignoring the file extension. The file extension must match one of the extensions specified in the %PATHEXT% environment variable. The above example would therefore match protoc-gen-grpc-java.EXE on Windows, as an example.

Binary plugins from specific locations

In some situations, you may wish to download plugins directly from a URL or run them from a specific file system path:

<plugin>
  <groupId>io.github.ascopes</groupId>
  <artifactId>protobuf-maven-plugin</artifactId>
  <version>...</version>

  <configuration>
    ...
    <binaryUrlPlugins>
      <binaryUrlPlugin>
        <url>file:///opt/protoc/protoc-gen-grpc-java</url>
      </binaryUrlPlugin>
      <binaryUrlPlugin>
        <url>ftp://company-server.internal/some-other-plugin.exe</url>
      </binaryUrlPlugin>
      <binaryUrlPlugin>
        <url>https://some-website.net/downloads/my-cool-protoc-plugin.exe</url>
        <options>some-option=some-value</options>
      </binaryUrlPlugin>
    </binaryUrlPlugins>
  </configuration>

  ...
</plugin>

Any protocols supported by your JRE should be able to be used here, including:

• file
• http
• https
• ftp
• jar - this also works for ZIP files, and can be used to dereference files within the archive, e.g. jar:https://github.com/some-project/some-repo/releases/download/v1.1.1/plugin.zip!/plugin.exe, which would download https://github.com/some-project/some-repo/releases/download/v1.1.1/plugin.zip and internally extract plugin.exe from that archive.

You can also mark these plugins as being optional by setting <optional>true</optional> on the individual plugin objects. This will prevent the Maven plugin from failing the build if the protoc plugin cannot be resolved. This is useful for specific cases where resources may only be available during CI builds but do not prevent the application being built locally. If set to optional, then any “not found” response provided by the underlying URL protocol will be ignored.

This is not recommended outside specific use cases, and care should be taken to ensure the legitimacy and security of any URLs being provided prior to adding them.

Providing authentication details or proxy details is not supported at this time.

Commandline arguments

Since JVM plugins work by internally bootstrapping a Java process per invocation, you can pass some extra options here.

If you wish to provide some commandline arguments, you can provide the <jvmArgs> parameter in each <jvmMavenPlugin> block. This is a list of string arguments. Of course, support for this relies entirely on the plugin supporting the use of commandline arguments in the first place.

For example:

<jvmMavenPlugin>
  ...
  <jvmArgs>
    <jvmArg>--logger.level=DEBUG</jvmArg>
    <jvmArg>--include-comments</jvmArg>
  </jvmArgs>
</jvmMavenPlugin>

JVM configuration arguments

You can also override the JVM configuration arguments itself if you need to tune how the JVM is running. By default, JVM configuration arguments are passed that disable the full server JIT, and enable class sharing where supported. This optimises build times for short-lived JVM processes. Overriding this argument will replace these default arguments as well.

An example of providing custom arguments would be:

<jvmMavenPlugin>
  ...
  <jvmConfigArgs>
    <jvmConfigArg>-Xshare:off</jvmConfigArg>
    <jvmConfigArg>-Xms100m</jvmConfigArg>
    <jvmConfigArg>-Xmx500m</jvmConfigArg>
    <jvmConfigArg>org.slf4j.simpleLogger.defaultLogLevel=DEBUG</jvmConfigArg>
  </jvmConfigArgs>
</jvmMavenPlugin>