### Example Protobuf File

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/basic-usage.md

Define your protobuf message structure in a .proto file. This example defines a simple Greeting message.

```protobuf
syntax = "proto3";

option java_multiple_files = true;
option java_package = "org.example";

package org.example;

message Greeting {
  string greeting = 1;
}
```

--------------------------------

### FTP Protocol Example

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/url-support.md

Shows how to fetch a file from an FTP server using the 'ftp:' protocol. Authentication is not supported by the plugin.

```text
ftp://server.net/path/to/file.zip
```

--------------------------------

### Example Java Usage

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/basic-usage.md

Create a Java class to utilize the generated protobuf classes. This example demonstrates building and printing a Greeting message.

```java
package org.example;

public class Main {
  public static void main(String[] args) {
    var greeting = Greeting.newBuilder()
        .setGreeting("Hello, World!")
        .build();
    System.out.println(greeting);
  }
}
```

--------------------------------

### Complete Example with Platform-Specific Profiles

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/examples.md

Configure the plugin to generate JavaScript/TypeScript client code for a gRPC service. This example includes platform-specific profiles for Windows, Unix, and Mac, allowing you to specify the correct plugin URLs for each operating system. Ensure you edit the URLs to match the correct plugin version for your platform.

```xml
<build>
  <plugins>
    <plugin>
      <groupId>io.github.ascopes</groupId>
      <artifactId>protobuf-maven-plugin</artifactId>

      <configuration>
        <protoc kind="binary-maven">
          <version>${protobuf.version}</version>
        </protoc>
        
        <javaEnabled>false</javaEnabled>

        <plugins>
          <plugin kind="url">
            <!-- Generate JavaScript protobuf messages -->
            <url>${protoc.gen.js.url}</url>
            <options>import_style=commonjs</options>
            <outputDirectory>${project.basedir}/target/js/protobuf</outputDirectory>
          </plugin>
          <plugin kind="url">
            <!-- Generate JavaScript gRPC stubs -->
            <url>${protoc.gen.grpc.web.url}</url>
            <options>import_style=typescript,mode=grpcwebtext</options>
            <outputDirectory>${project.basedir}/target/js/grpc</outputDirectory>
          </plugin>
        </plugins>
      </configuration>
  
      <executions>
        <execution>
          <goals>
            <goal>generate</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

<!-- Platform-specific profiles for JavaScript/gRPC-Web plugins -->
<profiles>
  <profile>
    <id>windows</id>
    <activation>
      <os>
        <family>windows</family>
      </os>
    </activation>
    <properties>
      <protoc.gen.js.url>zip:https://github.com/protocolbuffers/protobuf-javascript/releases/download/v3.21.4/protobuf-javascript-3.21.4-win64.zip!/protobuf-javascript-3.21.4-win64/bin/protoc-gen-js.exe</protoc.gen.js.url>
      <protoc.gen.grpc.web.url>https://github.com/grpc/grpc-web/releases/download/1.5.0/protoc-gen-grpc-web-1.5.0-windows-x86_64.exe</protoc.gen.grpc.web.url>
    </properties>
  </profile>
  
  <profile>
    <id>unix</id>
    <activation>
      <os>
        <family>unix</family>
      </os>
    </activation>
    <properties>
      <protoc.gen.js.url>zip:https://github.com/protocolbuffers/protobuf-javascript/releases/download/v3.21.4/protobuf-javascript-3.21.4-linux-x86_64.zip!/bin/protoc-gen-js</protoc.gen.js.url>
      <protoc.gen.grpc.web.url>https://github.com/grpc/grpc-web/releases/download/1.5.0/protoc-gen-grpc-web-1.5.0-linux-x86_64</protoc.gen.grpc.web.url>
    </properties>
  </profile>
  
  <profile>
    <id>mac</id>
    <activation>
      <os>
        <family>mac</family>
      </os>
    </activation>
    <properties>
      <protoc.gen.js.url>zip:https://github.com/protocolbuffers/protobuf-javascript/releases/download/v3.21.4/protobuf-javascript-3.21.4-osx-x86_64.zip!/bin/protoc-gen-js</protoc.gen.js.url>
      <protoc.gen.grpc.web.url>https://github.com/grpc/grpc-web/releases/download/1.5.0/protoc-gen-grpc-web-1.5.0-darwin-x86_64</protoc.gen.grpc.web.url>
    </properties>
  </profile>
</profiles>
```

--------------------------------

### SFTP Protocol Example

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/url-support.md

Demonstrates fetching a file from an SFTP server using the 'sftp:' protocol. This relies on the Java standard library.

```text
sftp://server.net/path/to/file.zip
```

--------------------------------

### Install Build Tools on illumos/Solaris

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/other-os-support.md

Installs necessary tools like git, cmake, and compilers for building the protoc binary on illumos/Solaris systems using pkgsrc.

```shell
$ pkgin install git cmake gmake gcc13 openjdk21
```

--------------------------------

### HTTP Protocol Example

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/url-support.md

Example of fetching a file from an HTTP server using the 'http:' protocol. This is provided by the Java standard library.

```text
http://server.net/path/to/file.zip
```

--------------------------------

### Protoc Version Configuration Examples

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/changing-protoc-versions.md

Illustrates both the modern and legacy ways to configure the protoc version, demonstrating how to pull specific protoc versions from Maven repositories.

```xml
<protoc kind="binary-maven">
  <version>4.28.0</version>
</protoc>

<!-- legacy way of setting this -->
<protoc>4.28.0</protoc>
```

--------------------------------

### HTTPS Protocol Example

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/url-support.md

Shows how to fetch a file from an HTTPS server using the 'https:' protocol. This is provided by the Java standard library.

```text
https://server.net/path/to/file.zip
```

--------------------------------

### Configuring URL Protoc Plugins

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/using-protoc-plugins.md

Example of configuring protoc plugins using the 'url' kind to specify download locations for plugin binaries.

```xml
<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>
```

--------------------------------

### Deploy Executable to Package Registry with GitLab CI

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/corporate-environments.md

This example demonstrates a GitLab CI pipeline for deploying a protoc-gen-scalapb executable to a package registry. It shows how to download the artifact, unzip it, and use `mvn deploy:deploy-file` to upload it as a Maven artifact.

```yaml
stages:
  - deploy

Deploy to package registry:
  stage: deploy
  image: container-registry.example.org/maven:latest
  rules:
    - if: CI_COMMIT_TAG
  parallel:
    matrix:
      MAVEN_CLASSIFIER:
        - linux-x86_64      
  before_script:
    # Do whatever you need to in order to set up your settings.xml
    - ...
  script:
    - curl --fail --silent "https://github.com/scalapb/ScalaPB/releases/download/v${CI_COMMIT_TAG}/protoc-gen-scala-${CI_COMMIT_TAG}-${MAVEN_CLASSIFIER}.zip"
    - 'unzip *.zip'
    - >-
      mvn deploy:deploy-file
        -DgroupId=io.github.scalapb
        -DartifactId=protoc-gen-scalapb
        -Dversion="${CI_COMMIT_TAG}"
        -Dclassifier="${MAVEN_CLASSIFIER}"
        -Dpackaging=exe
        -Dfile=protoc-gen-scala
```

--------------------------------

### Use Protoc from System PATH

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/changing-protoc-versions.md

Configure the plugin to use the 'protoc' executable found in the system's PATH. This is useful when you have a specific protoc version installed globally and want the plugin to utilize it.

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

  <configuration>
    <protoc kind="path">
      <name>protoc</name>
    </protoc>
    
    <!-- legacy way of setting this. In this case, PATH will always expect it to be called `protoc',
         and you cannot change this. The above mechanism lets you specify whatever you want as the
         name, so is more flexible. -->
    <protoc>PATH</protoc>
  </configuration>
</plugin>
```

--------------------------------

### File Protocol - Relative Path

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/url-support.md

Example of using the 'file:' protocol to specify a path relative to the current Maven project directory.

```text
file://foo/bar/baz/file.zip
```

--------------------------------

### Check Java Version

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/CONTRIBUTING.md

Display the installed Java version using `java -version`.

```bash
java -version
```

--------------------------------

### File Protocol - Absolute Path

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/url-support.md

Example of using the 'file:' protocol to specify an absolute path on the local filesystem. Note the use of forward slashes, even on Windows.

```text
file:///foo/bar/baz/file.zip
```

--------------------------------

### Run Specific Integration Tests

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/it/WRITING_ITS.md

Execute a subset of integration tests by specifying their names using the `-Dinvoker.test` flag. Always include 'setup' first to ensure the aggregator test parent POM is installed.

```shell
$ ./mvnw verify -Dinvoker.test=setup,help-goal,java-test
```

--------------------------------

### Protobuf Message Definition with Imports

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/dependencies.md

Example of a .proto file that imports other proto definitions. Ensure imported files are accessible via the plugin's dependency resolution.

```protobuf
syntax = "proto3";

package org.example.ticketsystem.users;

option java_multiple_files = true;
option java_package = "org.example.ticketsystem.users";

import "org/example/ticketsystem/board/ticket_board.proto";
import "org/example/ticketsystem/users/avatar.proto";
import "org/example/ticketsystem/users/user.proto";

message Team {
  org.example.ticketsystem.users.Avatar icon = 1;
  string name = 2;
  org.example.ticketsystem.users.User owner = 3;
  org.example.ticketsystem.board.TicketBoard ticket_board = 4;
}
```

--------------------------------

### Nested Protocol Example

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/url-support.md

Demonstrates the nesting and evaluation order of protocols in a URL. The innermost URL is evaluated first, and its result is passed to the next handler.

```text
tar:gz:https://some-website.com/protoc-gen-bang.tar.gz!/bin/protoc-gen-bang
```

--------------------------------

### JAR Archiving Protocol

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/url-support.md

Example of using the 'jar:' protocol to access content within a JAR archive. The specified path is extracted from the archive.

```text
jar:...!/path/to/file
```

--------------------------------

### gRPC Vert.x Integration with Maven

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/examples.md

Configure the plugin to use the Vert.x gRPC plugin for integrating with the Vert.x framework. This example shows how to set JVM arguments for client, service, and service prefix.

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

  <configuration>
    <protoc kind="binary-maven">
      <version>${protobuf.version}</version>
    </protoc>
    
    <plugins>
      <plugin kind="jvm-maven">
        <groupId>io.vertx</groupId>
        <artifactId>vertx-grpc-protoc-plugin2</artifactId>
        <version>${vertx.version}</version>
        <mainClass>io.vertx.grpc.plugin.VertxGrpcGenerator</mainClass>
        <jvmArgs>
          <jvmArg>--grpc-client</jvmArg>
          <jvmArg>--grpc-service</jvmArg>
          <jvmArg>--service-prefix=Vertx</jvmArg>
        </jvmArgs>
      </plugin>
    </plugins>
  </configuration>
</plugin>
```

--------------------------------

### Digest Verification Example

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/url-support.md

Illustrates how digest verification applies to the final artifact within a URL, not the outer archive. The digest is compared against the content of 'data/some-file.txt'.

```text
zip:ftp://some-server.net/archives/data.zip!/data/some-file.txt
```

--------------------------------

### ZIP Archiving Protocol

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/url-support.md

Example of treating a URL as a ZIP archive and extracting a file from within it. The format is 'PROTOCOL:url!/PATH'.

```text
zip:...!/path/to/file
```

--------------------------------

### Get Full Exception Stacktraces with Maven

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/gh-contributing.md

Run Maven with the --errors flag to obtain detailed exception stacktraces for debugging.

```bash
mvn --errors
```

--------------------------------

### Enable C++ Output with Custom Arguments

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/other-language-support.md

Use the `<arguments>` block to pass custom flags to `protoc` for languages not directly supported by boolean flags. This example enables C++ code generation to a specified directory.

```xml
<configuration>
  <arguments>
    <argument>--cpp_out=target/generated-sources/cxx</argument>
  </arguments>

  <protoc kind="binary-maven">
    <version>${protobuf.version}</version>
  </protoc>
</configuration>
```

--------------------------------

### Default Invoker Goals Configuration

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/it/WRITING_ITS.md

Configure the default Maven goals to be executed by the Invoker for each integration test. This example sets the goals to 'clean package'.

```properties
invoker.goals = clean package
```

--------------------------------

### EAR Archiving Protocol

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/url-support.md

Example of using the 'ear:' protocol to extract a file from an EAR archive. This functionality is provided by Apache Commons Compress.

```text
ear:...!/path/to/file
```

--------------------------------

### Corporate Workstation Profile Configuration

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/corporate-environments.md

Configure a Maven profile in an organization's parent POM that activates based on development environment prerequisites, such as not being in a CI environment and running on Windows. This example shows two options for setting the sanctioned executable path within the profile.

```xml
<project>
    ...
    <profiles>
      <profile>
        <id>corporate-workstation</id>
        <activation>
          <property>
            <name>!env.CI</name>
          </property>
          <os>
            <family>Windows</family>
          </os>
        </activation>

        <!-- Option 1: configure via a property. Quick and simple. -->
        <properties>
          <protobuf.sanctioned-executable-path>C:\dev\protobuf-maven-plugin</protobuf.sanctioned-executable-path>
        </properties>

        <!-- Option 2: configure via additional plugin management. Verbose but clear. -->
        <build>
          <pluginManagement>
            <plugins>
              <plugin>
                <groupId>io.github.ascopes</groupId>
                <artifactId>protobuf-maven-plugin</artifactId>
                <version>${protobuf-maven-plugin.version}</version>

                <configuration>
                  <sanctionedExecutablePath>C:\dev\protobuf-maven-plugin</sanctionedExecutablePath>
                </configuration>
              </plugin>
            </plugins>
          </pluginManagement>
        </build>
      </profile>
    </profiles>
  </project>
```

--------------------------------

### Set Plugin Execution Order

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/using-protoc-plugins.md

Control the execution order of a protoc plugin using the 'order' attribute. A negative value runs the plugin earlier, while a positive value runs it later. This example ensures the plugin runs before Java sources are generated.

```xml
<plugin kind="jvm-maven">
  ...
  <!-- Always run before generating Java sources. -->
  <order>-999</order>
</plugin>
```

--------------------------------

### Prepare Protobuf Source Tree

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/other-os-support.md

Clones the protobuf repository, checks out a specific version (35.1), and initializes submodules to prepare for building.

```shell
$ git clone https://github.com/protocolbuffers/protobuf.git
$ cd protobuf/
$ git checkout v35.1
$ git submodule update --init --recursive
```

--------------------------------

### Format License Headers

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/CONTRIBUTING.md

Run `./mvnw license:format` to add or update license headers in all project files. Builds will fail if new files lack these headers.

```bash
./mvnw license:format
```

--------------------------------

### Build and Verify Project

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/CONTRIBUTING.md

Before submitting a Pull Request, run `./mvnw clean verify` locally to ensure the project builds and all tests pass.

```bash
./mvnw clean verify
```

--------------------------------

### Basic pom.xml Configuration

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/basic-usage.md

Configure the plugin in your pom.xml to download Protoc and compile protobuf sources. Replace %VERSION% with the actual plugin version.

```xml
<project>
  <modelVersion>4.0.0</modelVersion>
  
  <groupId>org.example</groupId>
  <artifactId>hello-world</artifactId>
  <version>0.0.1-SNAPSHOT</version>

  <properties>
    <protobuf.version>4.31.1</protobuf.version>
    
    <maven.compiler.release>24</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>

  <dependencies>
    <dependency>
      <groupId>com.google.protobuf</groupId>
      <artifactId>protobuf-java</artifactId>
      <version>${protobuf.version}</version>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>io.github.ascopes</groupId>
        <artifactId>protobuf-maven-plugin</artifactId>
        <version>%VERSION%</version>

        <configuration>
          <protoc kind="binary-maven">
            <version>${protobuf.version}</version>
          </protoc>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>
```

--------------------------------

### Use Protoc from System PATH with Digest Verification

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/changing-protoc-versions.md

Configure the plugin to use a 'protoc' executable from the system's PATH and verify its integrity using a SHA1 digest. This ensures reproducible builds by confirming the binary has not been tampered with.

```xml
<protoc kind="path">
  <name>protoc</name>
  <digest>sha1:e4c905a33adcb9a589896d09f3604a7c5653b2c0</digest>
</protoc>
```

--------------------------------

### Deploy Protoc Binary to Maven Repository

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/other-os-support.md

Deploys a locally built protoc binary to a Maven repository using the 'deploy-file' goal. This makes the binary available for the protobuf-maven-plugin to download.

```shell
$ mvn deploy:deploy-file \
-DrepositoryId=third-party \
-Durl=https://reposilite.example.com/third-party/ \
-Dfile="protoc-4.35.1-sunos-x86_64.exe" \
-DgroupId="com.google.protobuf" \
-DartifactId="protoc" \
-Dversion="4.35.1" \
-Dpackaging=exe \
-Dclassifier="sunos-x86_64" \
-DcreateChecksum=true
```

--------------------------------

### Get Full Exception Stacktraces with Maven Wrapper

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/gh-contributing.md

Use the Maven Wrapper with the --errors flag to obtain detailed exception stacktraces for debugging.

```bash
./mvnw --errors
```

--------------------------------

### Configure and Build Protobuf Compiler

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/other-os-support.md

Configures the build using CMake with specific options to disable tests, enable library and binary builds, and fetch dependencies. Then, it builds the Protobuf compiler using make.

```shell
$ rm -rf build CMakeCache.txt CMakeFiles
$ cmake . -DCMAKE_CXX_STANDARD=17 \
-DCMAKE_INSTALL_PREFIX=/opt/local \
-Dprotobuf_BUILD_TESTS=OFF \
-Dprotobuf_BUILD_LIBPROTOC=ON \
-Dprotobuf_BUILD_PROTOC_BINARIES=ON \
-Dprotobuf_BUILD_PROTOBUF_BINARIES=ON \
-Dprotobuf_FORCE_FETCH_DEPENDENCIES=ON
$ cmake --build . -j4
```

--------------------------------

### Add Local File System Import Paths

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/dependencies.md

Configure 'importPaths' to make *.proto files from local directories visible to protoc. The plugin will recursively search these directories.

```xml
<plugin>
  <groupId>io.github.ascopes</groupId>
  <artifactId>protobuf-maven-plugin</artifactId>
  
  <configuration>
    <importPaths>
      <importPath>/path/to/protos/root</importPath>
      ...
    </importPaths>
  </configuration>
</plugin>
```

--------------------------------

### Use Maven Wrapper

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/CONTRIBUTING.md

Always use `./mvnw` or `.\mvnw.cmd` instead of `mvn` directly to ensure the correct Maven version for the project.

```bash
./mvnw
.\mvnw.cmd
```

--------------------------------

### Build from Local Descriptor File

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/descriptor-files.md

Configure the plugin to use a descriptor file from the local file system by specifying its path in `sourceDescriptorPaths`.

```xml
<plugin>
  <groupId>io.github.ascopes</groupId>
  <artifactId>protobuf-maven-plugin</artifactId>
  <version>%VERSION%</version>

  <configuration>
    ...
    <sourceDescriptorPaths>
      <sourceDescriptorPath>${project.basedir}/src/main/resources/some-descriptor.binpb</sourceDescriptorPath>
    </sourceDescriptorPaths>
  </configuration>
</plugin>
```

--------------------------------

### Generate Proto Descriptor File

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/descriptor-files.md

Configure the plugin to generate a `FileDescriptorSet` binary blob by specifying the `outputDescriptorFile`.

```xml
<plugin>
  <groupId>io.github.ascopes</groupId>
  <artifactId>protobuf-maven-plugin</artifactId>
  <version>%VERSION%</version>

  <configuration>
    ...
    <outputDescriptorFile>${project.basedir}/target/protos.desc</outputDescriptorFile>
  </configuration>
</plugin>
```

--------------------------------

### Configure Path Plugin

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/using-protoc-plugins.md

Specifies a protoc plugin to be found in the system's PATH environment variable. The 'kind' must be set to 'path' and the 'name' attribute should be the executable's name.

```xml
<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>
```

--------------------------------

### Use System PATH for Protoc

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/it/WRITING_ITS.md

Activate the -Pinvoker-path-protoc profile to force all tests to use the protoc executable found in the system's PATH. Note that this profile is incompatible with the debug profile.

```bash
./mvnw -Pinvoker-path-protoc ...
```

--------------------------------

### Generate Main and Test Sources

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/basic-usage.md

Configure the plugin to generate sources for both main application code and test code simultaneously. Main sources are read from src/main/protobuf and test sources from src/test/protobuf.

```xml
<plugin>
  <groupId>io.github.ascopes</groupId>
  <artifactId>protobuf-maven-plugin</artifactId>
  <version>%VERSION%</version>

  <configuration>
    <protoc>${protobuf.version}</protoc>
  </configuration>

  <executions>
    <execution>
      <goals>
        <goal>generate</goal>
        <goal>generate-test</goal>
      </goals>
    </execution>
  </executions>
</plugin>
```

--------------------------------

### Specify Protoc from FTP Server

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/changing-protoc-versions.md

Configure the plugin to download and use a protoc executable from an FTP server. Ensure the legitimacy and security of the URL.

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

  <configuration>
    <protoc kind="url">
      <url>ftp://company-server.internal/protoc/protoc.exe</url>
    </protoc>

    <!-- or -->

    <protoc kind="url">
      <url>http://company-server.internal/protoc/protoc.exe</url>
    </protoc>

    <!-- or -->

    <protoc kind="url">
      <url>https://company-server.internal/protoc/protoc.exe</url>
    </protoc>
  </configuration>
</plugin>
```

--------------------------------

### Basic Protobuf Code Generation with Maven

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/README.md

Configure the plugin to compile *.proto files found in src/main/protobuf to Java classes. Maven automatically discovers these generated sources for compilation.

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

  <configuration>
    <protoc kind="binary-maven">
      <version>${protobuf-java.version}</version>
    </protoc>
  </configuration>

  <executions>
    <execution>
      <goals>
        <goal>generate</goal>
      </goals>
    </execution>
  </executions>
</plugin>
```

--------------------------------

### Configure ScalaPB with Protobuf Maven Plugin

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/examples.md

Configure the plugin to use ScalaPB for generating Scala sources. Ensure the ScalaPB binary is downloaded from a URL and the protoc binary is managed by Maven.

```xml
<plugins>
  <plugin>
    <groupId>io.github.ascopes</groupId>
    <artifactId>protobuf-maven-plugin</artifactId>

    <configuration>
      <javaEnabled>false</javaEnabled>

      <plugins>
        <plugin kind="url">
          <url>zip:https://github.com/scalapb/ScalaPB/releases/download/v${scalapb.version}/protoc-gen-scala-${scalapb.version}-linux-x86_64.zip!/protoc-gen-scala</url>
          <options>flat_package,grpc,scala3_sources</options>
        </plugin>
      </plugins>

      <protoc kind="binary-maven">
        <version>${protobuf.version}</version>
      </protoc>
    </configuration>

    <executions>
      <execution>
        <goals>
          <goal>generate</goal>
        </goals>
      </execution>
    </executions>
  </plugin>


  <plugin>
    <groupId>net.alchim31.maven</groupId>
    <artifactId>scala-maven-plugin</artifactId>

    <configuration>
      <failOnMultipleScalaVersions>true</failOnMultipleScalaVersions>
    </configuration>
  </plugin>
</plugins>
```

--------------------------------

### Specify Protoc from Local File Path

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/changing-protoc-versions.md

Configure the plugin to use a protoc executable located at a specific file path. Supports both relative and absolute paths. Use forward-slashes for Windows paths.

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

  <configuration>
    <protoc kind="url">
      <url>file:///opt/protoc/protoc.exe</url>
    </protoc>
    
    <!-- Legacy way of setting this -->
    <protoc>file:///opt/protoc/protoc.exe</protoc>
  </configuration>
</plugin>
```

--------------------------------

### Configure Multiple Output Directories for Java and Python

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/examples.md

Configure the plugin to generate Java sources in one directory and Python sources in another. This is achieved by defining separate executions for each language with distinct output directories and language enablement flags.

```xml
<plugin>
  <groupId>io.github.ascopes</groupId>
  <artifactId>protobuf-maven-plugin</artifactId>
  
  <executions>
    <!-- Java sources -->
    <execution>
      <id>java</id>
      <goals>
        <goal>generate</goal>
      </goals>
      <configuration>
        <outputDirectory>${project.basedir}/target/java</outputDirectory>

        <protoc kind="binary-maven">
          <version>${protobuf.version}</version>
        </protoc>
      </configuration>
    </execution>
    
    <!-- Python sources -->
    <execution>
      <id>python</id>
      <goals>
        <goal>generate</goal>
      </goals>
      <configuration>
        <javaEnabled>false</javaEnabled>
        <outputDirectory>${project.basedir}/target/python</outputDirectory>
        <pythonEnabled>true</pythonEnabled>

        <protoc kind="binary-maven">
          <version>${protobuf.version}</version>
        </protoc>
      </configuration>
    </execution>
  </executions>
</plugin>
```

--------------------------------

### Generate Protobuf, gRPC, and Reactor gRPC Code

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/README.md

Configure the plugin to compile protobuf sources and generate gRPC and Reactor gRPC wrappers. Supports both binary and JVM plugins.

```xml
<plugins>
  <groupId>io.github.ascopes</groupId>
  <artifactId>protobuf-maven-plugin</artifactId>

  <configuration>
    <protoc kind="binary-maven">
      <version>${protobuf-java.version}</version>
    </protoc>
    
    <plugins>
      <!-- Vanilla protoc plugins - these are platform specific executables
           just like protoc is. -->
      <plugin kind="binary-maven">
        <groupId>io.grpc</groupId>
        <artifactId>protoc-gen-grpc-java</artifactId>
        <version>${grpc.version}</version>
      </plugin>

      <!-- JVM plugins are distributed as JARs rather than native system
           executables. The protobuf-maven-plugin will automatically bootstrap
           them for you, without the need for additional
           tooling for your platform. It should "just work". -->
      <plugin kind="jvm-maven">
        <groupId>com.salesforce.servicelibs</groupId>
        <artifactId>reactor-grpc</artifactId>
        <version>${reactor-grpc.version}</version>
      </plugin>
    </plugins>
  </configuration>

  <executions>
    <execution>
      <goals>
        <goal>generate</goal>
      </goals>
    </execution>
  </executions>
</plugin>
```

--------------------------------

### Run All Integration Tests

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/it/WRITING_ITS.md

Execute all integration tests defined in the project. This command should be used before raising pull requests to ensure the entire pipeline succeeds locally.

```shell
$ ./mvnw verify
```

--------------------------------

### Configure Global Source Directories

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/basic-usage.md

Override the default source directories for protobuf compilation in the global plugin configuration. Multiple paths can be specified.

```xml
<plugin>
  <groupId>io.github.ascopes</groupId>
  <artifactId>protobuf-maven-plugin</artifactId>
  <version>%VERSION%</version>

  <configuration>
    <protoc>${protobuf.version}</protoc>

    <sourceDirectories>
      <sourceDirectory>path/to/directory</sourceDirectory>
    </sourceDirectories>
  </configuration>
</plugin>
```

--------------------------------

### Configure Per-Execution Source Directories

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/basic-usage.md

Configure source directories individually for the 'generate' and 'generate-test' goals within the plugin's executions. This allows for different source paths for main and test protobuf files.

```xml
<plugin>
  <groupId>io.github.ascopes</groupId>
  <artifactId>protobuf-maven-plugin</artifactId>
  <version>%VERSION%</version>

  <configuration>
    <protoc>${protobuf.version}</protoc>
  </configuration>

  <executions>
    <execution>
      <goals>
        <goal>generate</goal>
      </goals>
      <configuration>
        <sourceDirectories>
          <sourceDirectory>path/to/main/directory</sourceDirectory>
        </sourceDirectories>  
      </configuration>
    </execution>

    <execution>
      <goals>
        <goal>generate-test</goal>
      </goals>
      <configuration>
        <sourceDirectories>
          <sourceDirectory>path/to/test/directory</sourceDirectory>
        </sourceDirectories>  
      </configuration>
    </execution>
  </executions>
</plugin>
```

--------------------------------

### Protobuf Definition for Helloworld Service

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/examples.md

Defines a simple gRPC service for greeting messages, including request and response types.

```protobuf
syntax = "proto3";

option java_multiple_files = true;
option java_package = "org.example.helloworld";

package org.example.helloworld;

message GreetingRequest {
  string name = 1;
}

message GreetingResponse {
  string text = 1;
}

service GreetingService {
  rpc Greet(GreetingRequest) returns (GreetingResponse);
}
```

--------------------------------

### Specify Protoc from Local File with Digest

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/changing-protoc-versions.md

Configure the plugin to use a protoc executable from a local file path and verify its integrity using a SHA1 digest for reproducible builds.

```xml
<protoc kind="url">
  <url>file:///opt/protoc/protoc.exe</url>
  <digest>sha1:e4c905a33adcb9a589896d09f3604a7c5653b2c0</digest>
</protoc>
```

--------------------------------

### Generate Test Sources Configuration

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/basic-usage.md

Configure the plugin to generate sources specifically for testing. This uses the 'generate-test' goal and defaults to reading from src/test/protobuf.

```xml
<plugin>
  <groupId>io.github.ascopes</groupId>
  <artifactId>protobuf-maven-plugin</artifactId>
  <version>%VERSION%</version>

  <configuration>
    <protoc>${protobuf.version}</protoc>
  </configuration>

  <executions>
    <execution>
      <goals>
        <goal>generate-test</goal>
      </goals>
    </execution>
  </executions>
</plugin>
```

--------------------------------

### Legacy Protoc Version Configuration

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/changing-protoc-versions.md

The legacy method involves providing the protoc version as a direct string value within the <protoc/> tag, without specifying the 'kind' attribute.

```xml
<protoc>4.28.0</protoc>
```

--------------------------------

### TAR Archiving Protocol

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/url-support.md

Demonstrates using the 'tar:' protocol to treat a decompressed resource as a TAR archive and extract a file from it.

```text
tar:...!/path/to/file
```

--------------------------------

### Modern Protoc Version Configuration

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/changing-protoc-versions.md

Use the modern XML format to specify the protoc version by setting the 'kind' attribute to 'binary-maven' and providing the version in a nested element.

```xml
<protoc kind="binary-maven">
  <version>4.28.0</version>
</protoc>
```

--------------------------------

### Compile Dependencies from Maven Artifacts and Local Paths

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/dependencies.md

Configure 'sourceDependencies' for Maven artifacts and 'sourceDirectories' for local file system paths (including JARs and ZIPs) to compile them.

```xml
<plugin>
  <groupId>io.github.ascopes</groupId>
  <artifactId>protobuf-maven-plugin</artifactId>
  
  <configuration>
    <sourceDependencies>
      <sourceDependency>
        <groupId>org.example.foobar</groupId>
        <artifactId>core-protos</artifactId>
        <version>1.2.3</version>
        <type>zip</type>
      </sourceDependency>
    </sourceDependencies>
    
    <sourceDirectories>
      <!-- Keep the default path -->
      <sourceDirectory>${project.basedir}/src/protobuf</sourceDirectory>

      <!-- Add something else from the local system -->
      <sourceDirectory>/path/to/something/else/to/include</sourceDirectory>
      <sourceDirectory>/path/to/something/else/archive.jar</sourceDirectory>
      <sourceDirectory>/path/to/something/else/archive.zip</sourceDirectory>
    </sourceDirectories>
  </configuration>
</plugin>
```

--------------------------------

### KAR Archiving Protocol

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/url-support.md

Demonstrates using the 'kar:' protocol to treat a URL as a KAR archive and extract a specific file. This relies on Apache Commons Compress.

```text
kar:...!/path/to/file
```

--------------------------------

### Configure Multiple Protoc Plugins

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/using-protoc-plugins.md

Use this configuration to include multiple protoc plugins, such as gRPC Java and Salesforce Reactor, in your build. Ensure the correct groupId, artifactId, and version are specified for each plugin.

```xml
<plugins>
  <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>
        <order>1</order>
      </plugin>
      <plugin kind="jvm-maven">
        <!-- Use the JAR that Salesforce distributes -->
        <groupId>com.salesforce.servicelibs</groupId>
        <artifactId>reactor-grpc</artifactId>
        <version>${reactor-grpc.version}</version>
        <order>2</order>
      </plugin>
    </plugins>
  </configuration>

  ...
</plugin>
```

--------------------------------

### Plugin Kinds Configuration

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/using-protoc-plugins.md

Specifies the different types of plugins that can be configured for the protobuf-maven-plugin. Use the 'kind' attribute to differentiate between binary-maven, jvm-maven, path, and url plugins.

```xml
<plugins>
  <plugin kind="binary-maven">
    ...
  </plugin>
  <plugin kind="jvm-maven">
    ...
  </plugin>
  <plugin kind="path">
    ...
  </plugin>
  <plugin kind="url">
    ...
  </plugin>
</plugins>
```

--------------------------------

### Pass Command Line Arguments to JVM Plugin

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/using-protoc-plugins.md

Provide additional command-line arguments to a JVM-based protoc plugin using the `<jvmArgs>` parameter. This relies on the plugin's support for such arguments.

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

--------------------------------

### Configure JVM Maven Plugin

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/using-protoc-plugins.md

Specify a JVM-based protoc plugin by providing its Maven coordinates. The plugin's kind must be set to 'jvm-maven'.

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

  <configuration>
    ...
    <plugins>
      <plugin kind="jvm-maven">
        <!-- Use the JAR that Salesforce distributes -->
        <groupId>com.salesforce.servicelibs</groupId>
        <artifactId>reactor-grpc</artifactId>
        <version>${reactor-grpc.version}</version>
      </plugin>
    </plugins>
  </configuration>

  ...
</plugin>
```

--------------------------------

### Run Maven with Full Exception Stacktraces

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/CONTRIBUTING.md

Use the `--errors` flag with `mvn` or `mvnw` to obtain full exception stacktraces when reporting bugs.

```bash
mvn --errors
./mvnw --errors
```

--------------------------------

### Specify Protoc from Remote Server with Digest

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/changing-protoc-versions.md

Configure the plugin to download a protoc executable from a remote server (HTTPS) and verify its integrity using a SHA1 digest for reproducible builds.

```xml
<protoc kind="url">
  <url>https://company-server.internal/protoc/protoc.exe</url>
  <digest>sha1:e4c905a33adcb9a589896d09f3604a7c5653b2c0</digest>
</protoc>
```

--------------------------------

### Configuring Binary Plugin from Maven Central

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/using-protoc-plugins.md

Adds a binary plugin to the build by referencing its Maven coordinates (groupId, artifactId, version). This is suitable for plugins available on Maven Central or other Maven repositories. The 'kind' must be set to 'binary-maven'.

```xml
<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>

  ...
```

--------------------------------

### Check Maven Version

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/CONTRIBUTING.md

Verify the version of Maven in use by running `mvn --version` or `./mvnw --version`.

```bash
mvn --version
./mvnw --version
```

--------------------------------

### WAR Archiving Protocol

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/url-support.md

Shows how to use the 'war:' protocol to extract a file from a WAR archive. The syntax follows the 'PROTOCOL:url!/PATH' pattern.

```text
war:...!/path/to/file
```

--------------------------------

### Configure JVM Arguments for Protoc

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/using-protoc-plugins.md

Override default JVM configuration arguments to tune the JVM's performance for protoc execution. This replaces default arguments like disabling JIT and enabling class sharing.

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

--------------------------------

### Validate Code Style with Checkstyle

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/CONTRIBUTING.md

Use `./mvnw validate` to check if the code style conforms to Checkstyle rules. Builds will fail if issues are found.

```bash
./mvnw validate
```

--------------------------------

### Check Maven Wrapper Version

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/gh-contributing.md

Verify the version of the Maven Wrapper being used in the project.

```bash
./mvnw --version
```

--------------------------------

### Check Maven Version

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/gh-contributing.md

Verify the version of Maven being used in the project.

```bash
mvn --version
```

--------------------------------

### Configure Protobuf Dependency in Maven

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/README.md

Declare proto file bundles as Maven dependencies. Ensure the artifact type is set to 'zip'.

```xml
<project>
  ...

  <dependencies>
    <dependency>
      <groupId>org.example.protos</groupId>
      <artifactId>user-protos</artifactId>
      <version>1.2.3</version>
      <type>zip</type>
    </dependency>
  </dependencies>

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

      <configuration>
        <protoc kind="binary-maven">
          <version>${protobuf-java.version}</version>
        </protoc>
      </configuration>

      <executions>
        <execution>
          <goals>
            <goal>generate</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</project>
```

--------------------------------

### gRPC with Reactor Integration using Maven

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/examples.md

Configure the plugin to use the Salesforce Reactor gRPC plugin for generating reactive streams-based gRPC service stubs.

```xml
<plugins>
  <groupId>io.github.ascopes</groupId>
  <artifactId>protobuf-maven-plugin</artifactId>

  <configuration>
    <protoc kind="binary-maven">
      <version>${protobuf.version}</version>
    </protoc>

    <plugins>
      <plugin kind="binary-maven">
        <groupId>io.grpc</groupId>
        <artifactId>protoc-gen-grpc-java</artifactId>
        <version>${grpc.version}</version>
      </plugin>

      <plugin kind="jvm-maven">
        <groupId>com.salesforce.servicelibs</groupId>
        <artifactId>reactor-grpc</artifactId>
        <version>${reactor-grpc.version}</version>
      </plugin>
    </plugins>
  </configuration>
</plugin>
```

--------------------------------

### Configure Sanctioned Executable Path via Properties

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/site/markdown/corporate-environments.md

Configure a property within the project or parent plugin management to set the sanctioned executable path.

```xml
<properties>
    <protobuf.sanctioned-executable-path>C:\dev\protobuf-maven-plugin</protobuf.sanctioned-executable-path>
  </properties>
```

--------------------------------

### Protobuf Code Generation with Kotlin Support

Source: https://github.com/ascopes/protobuf-maven-plugin/blob/main/README.md

Enable Kotlin generation alongside Java by setting 'kotlinEnabled' to true. This configuration generates both Java classes and corresponding Kotlin wrappers.

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

  <configuration>
    <kotlinEnabled>true</kotlinEnabled>

    <protoc kind="binary-maven">
      <version>${protobuf-java.version}</version>
    </protoc>
  </configuration>

  <executions>
    <execution>
      <goals>
        <goal>generate</goal>
      </goals>
    </execution>
  </executions>
</plugin>
```