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

Binary Maven plugins should have the kind attribute set to binary-maven.

Note that this is equivalent to passing a list of <binaryMavenPlugins> in previous versions. This old behaviour will be removed in v5.0.0.

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

  <configuration>
    ...
    <plugins>
      <plugin kind="binary-maven">
        <groupId>io.grpc</groupId>
        <artifactId>protoc-gen-grpc-java</artifactId>
        <version>${grpc.version}</version>
      </plugin>
    </plugins>
  </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 to find instead.

Path plugins should have the kind attribute set to path.

Note that this is equivalent to passing a list of <binaryPathPlugins> in previous versions. This old behaviour will be removed in v5.0.0.

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

  <configuration>
    ...
    <plugins>
      <plugin kind="path">
        <name>protoc-gen-grpc-java</name>
      </plugin>
    </plugins>
  </configuration>

  ...
</plugin>

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. URL plugins help you achieve this goal.

URL Maven plugins should have the kind attribute set to url.

Note that this is equivalent to passing a list of <binaryUrlPlugins> in previous versions. This old behaviour will be removed in v5.0.0.

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

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

  ...
</plugin>

Caveats

Currently, you are required to be able to execute *.bat files on Windows, or have sh available on the system $PATH for any other platform in order for this feature to work.

Overriding the entrypoint class

If you are supplying the JVM plugin from the same Maven project where it is not assembled yet, or the plugin does not specify a Main-Class attribute in the manifest, then you can specify (or override) the main class via the mainClass attribute.

<plugin kind="jvm-maven">
  <groupId>${project.parent.groupId}</groupId>
  <artifactId>my-super-awesome-plugin</artifactId>
  <version>${project.parent.version}</version>
  <mainClass>org.example.protocplugin.MySuperAwesomePluginMainClass</mainClass>
</plugin>

Command line 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 command line arguments, you can provide the <jvmArgs> parameter in each <plugin kind="jvm-maven"> block. This is a list of string arguments. Of course, support for this relies entirely on the plugin supporting the use of command line arguments in the first place.

For example:

<plugin kind="jvm-maven">
  ...
  <jvmArgs>
    <jvmArg>--logger.level=DEBUG</jvmArg>
    <jvmArg>--include-comments</jvmArg>
  </jvmArgs>
</plugin>

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:

<plugin kind="jvm-maven">
  ...
  <jvmConfigArgs>
    <jvmConfigArg>-Xshare:off</jvmConfigArg>
    <jvmConfigArg>-Xms100m</jvmConfigArg>
    <jvmConfigArg>-Xmx500m</jvmConfigArg>
    <jvmConfigArg>-Dorg.slf4j.simpleLogger.defaultLogLevel=DEBUG</jvmConfigArg>
  </jvmConfigArgs>
</plugin>