diff --git a/pom.xml b/pom.xml index 6233beb0..2c319b96 100644 --- a/pom.xml +++ b/pom.xml @@ -81,7 +81,7 @@ </scm> <distributionManagement> - <downloadUrl>https://github.com/sergei-ivanov/maven-protoc-plugin/downloads</downloadUrl> + <downloadUrl>https://bintray.com/sergei-ivanov/maven/maven-protoc-plugin/view</downloadUrl> <site> <id>maven-protoc-plugin-site</id> <url>file:../maven-protoc-plugin-site</url> diff --git a/src/changes/changes.xml b/src/changes/changes.xml index efcc3a66..c652d7ee 100644 --- a/src/changes/changes.xml +++ b/src/changes/changes.xml @@ -7,7 +7,10 @@ <body> - <release version="0.4.1" date="In progress" description="Support for native protoc plugins"> + <release version="0.4.1" date="2015-04-27" description="Support for native protoc plugins"> + <action dev="sergei-ivanov" type="add" issue="33"> + Added an option to download protoc binary artifact from Maven repo. + </action> <action dev="sergei-ivanov" type="add" issue="21"> Generated descriptor set can be attached to the build. </action> diff --git a/src/main/java/com/google/protobuf/maven/AbstractProtocMojo.java b/src/main/java/com/google/protobuf/maven/AbstractProtocMojo.java index 2b7fb366..9caa9c71 100644 --- a/src/main/java/com/google/protobuf/maven/AbstractProtocMojo.java +++ b/src/main/java/com/google/protobuf/maven/AbstractProtocMojo.java @@ -611,6 +611,7 @@ protected String detectJavaHome() { * Adds mojo-specific parameters to the protoc builder. * * @param protocBuilder the builder to be modified. + * @throws MojoExecutionException if parameters cannot be resolved or configured. */ protected void addProtocBuilderParameters(final Protoc.Builder protocBuilder) throws MojoExecutionException { if (protocPlugins != null) { diff --git a/src/site/apt/examples/protoc-artifact.apt.vm b/src/site/apt/examples/protoc-artifact.apt.vm new file mode 100644 index 00000000..8961f4be --- /dev/null +++ b/src/site/apt/examples/protoc-artifact.apt.vm @@ -0,0 +1,65 @@ + ------------------------------------------------- + Resolving Protoc Artifact From Maven Central Repo + ------------------------------------------------- + +~~ APT Format: http://maven.apache.org/doxia/references/apt-format.html + +Resolving Protoc Artifact From Maven Central Repo + +* Overview + + Starting with versions <<<2.6.1>>> and <<<3.0.0-alpha-2>>> of <<<protoc>>>, its binary executables + for all major operating systems are available as artifacts in Maven central. + These artifacts can be referenced in plugin configuration as described below. + The plugin automatically resolves and downloads the <<<protoc>>> executable, + and uses it for compiling protobuf definitions. + +* Usage + + It is recommended to use {{{https://github.com/trustin/os-maven-plugin} os-maven-plugin}} to automatically + generate a classifier for the current OS and architecture. The same plugin is used by protobuf team at Google + to generate classifiers for <<<protoc>>> artifacts. + + Plugin parameter <<<protocArtifact>>> can be used for specifying artifact coordinates in a + <<<groupId:artifactId:version\[:type\[:classifier\]\]>>> format. + + A sample configuration is provided below: + ++-----+ + +<project> + ... + <build> + <extensions> + <extension> + <groupId>kr.motd.maven</groupId> + <artifactId>os-maven-plugin</artifactId> + <version>1.2.3.Final</version> + </extension> + </extensions> + <plugins> + <plugin> + <groupId>${project.groupId}</groupId> + <artifactId>${project.artifactId}</artifactId> + <version>${project.version}</version> + <extensions>true</extensions> + <executions> + <execution> + <goals> + <goal>compile</goal> + <goal>test-compile</goal> + </goals> + <configuration> + <protocArtifact>com.google.protobuf:protoc:2.6.1:exe:${os.detected.classifier}</protocArtifact> + </configuration> + </execution> + </executions> + </plugin> + ... + </plugins> + ... + </build> + ... +</project> + ++-----+ diff --git a/src/site/apt/examples/protoc-plugin.apt.vm b/src/site/apt/examples/protoc-plugin.apt.vm index f6d7adbe..6e6b1258 100644 --- a/src/site/apt/examples/protoc-plugin.apt.vm +++ b/src/site/apt/examples/protoc-plugin.apt.vm @@ -6,18 +6,21 @@ Using Custom Protoc Plugins - It is possible to customize <<<protoc>>>'s output with plugins. This is done by - adding adding a <<<protocPlugins>>> element containing one of more <<<protocPlugin>>> elements - to the <<<configuration>>> section. Protoc plugins are executables that are invoked by <<<protoc>>>. + It is possible to customize <<<protoc>>>'s output with plugins. + Protoc plugins are executables that are invoked by <<<protoc>>>. They read code generator requests from <<<stdin>>> and output results to <<<stdout>>>. - In the current version only plugins written in Java (or any other JVM - language) and resolvable as Maven artifacts are supported. Also, the output - directory for generated files is the same as the Java output directory. + Currently, both native and pure Java plugins are supported. - In future versions support for other types of executables will be added as well. + Plugins written in Java (or any other JVM language) have to be resolvable as Maven artifacts. + Also, the output directory for generated files is the same as the Java output directory. + They are configured by adding a <<<protocPlugins>>> element containing one of more <<<protocPlugin>>> elements + to the <<<configuration>>> section. -* Using a <<<protoc>>> plugin + Native plugins are supported by two dedicated goals: {{{../compile-custom-mojo.html}protoc:compile-custom}} + and {{{../test-compile-custom-mojo.html}protoc:test-compile-custom}}. + +* Using a pure Java <<<protoc>>> plugin The following example includes uses a single plugin to generate Java code in addition to <<<protoc>>>'s regular output. @@ -98,7 +101,7 @@ Using Custom Protoc Plugins * Java plugin generation - An Java-based executable is assembled on the fly from the specified artifact and its dependencies and executed by + A Java-based executable is assembled on the fly from the specified artifact and its dependencies and executed by <<<protoc>>>. The way this is done is platform-dependent. On UNIX, a shell script is created in <<<target/protoc-plugins>>> that builds a classpath from local repository @@ -106,7 +109,6 @@ Using Custom Protoc Plugins On Windows, a WinRun4J executable (bundled inside the Maven plugin jar) is copied into <<<target/protoc-plugins>>> and an <<<.ini>>> is generated with the required classpath, <<<jvm.dll>>> location, main class and arguments. - Please note that at the moment only 32-bit JVMs are supported on Windows. The <<<target/protoc-plugins>>> directory is prepended to the <<<PATH>>> in <<<protoc>>>'s runtime environment. diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt index 0847db8f..933ec210 100644 --- a/src/site/apt/index.apt +++ b/src/site/apt/index.apt @@ -31,6 +31,9 @@ Maven Protoc Plugin * {{{./compile-cpp-mojo.html}protoc:compile-cpp}} compiles main <<<.proto>>> definitions into C++ files and attaches the generated C++ sources to the project. + * {{{./compile-custom-mojo.html}protoc:compile-custom}} + compiles main <<<.proto>>> definitions using a custom <<<protoc>>> plugin. + * {{{./test-compile-cpp-mojo.html}protoc:test-compile-cpp}} compiles test <<<.proto>>> definitions into C++ files and attaches the generated C++ test sources to the project. @@ -40,6 +43,9 @@ Maven Protoc Plugin * {{{./test-compile-python-mojo.html}protoc:test-compile-python}} compiles test <<<.proto>>> definitions into Python files and attaches the generated Python test sources to the project. + * {{{./test-compile-custom-mojo.html}protoc:test-compile-custom}} + compiles test <<<.proto>>> definitions using a custom <<<protoc>>> plugin. + [] * Usage @@ -66,6 +72,8 @@ Maven Protoc Plugin * {{{./examples/protobuf-toolchain.html} Using Protobuf Toolchain}} + * {{{./examples/protoc-artifact.html} Resolving Protoc Artifact From Maven Central Repo}} + * {{{./examples/protoc-plugin.html} Using Custom Protoc Plugins}} [] diff --git a/src/site/apt/usage.apt.vm b/src/site/apt/usage.apt.vm index 5a7d1025..ccaf052e 100644 --- a/src/site/apt/usage.apt.vm +++ b/src/site/apt/usage.apt.vm @@ -191,6 +191,10 @@ mvn toolchains:toolchain protoc:test-compile metadata for generated classes. Descriptor sets are written by passing the <<<--descriptor_set_out>>> and <<<--include_imports>>> arguments to <<<protoc>>>. + Generated descriptor sets can optionally be attached to the build as artifacts. + The default type and extension for descriptor sets is <<<protobin>>>, and the plugin extensions need + to be enabled in order to support the correct resolution of those dependencies in downstream projects. + The following plugin options configure descriptor set output: * <<<writeDescriptorSet>>> - determines if a descriptor set is written; default is <<<false>>>. @@ -203,4 +207,8 @@ mvn toolchains:toolchain protoc:test-compile * <<<descriptorSetOutputDirectory>>> - the directory where the descriptor set file will be created + * <<<attachDescriptorSet>>> - attach the generated descriptor set as an artifact to the build + + * <<<descriptorSetClassifier>>> - an optional artifact classifier for the attached descriptor + [] diff --git a/src/site/fml/faq.fml b/src/site/fml/faq.fml index 9d17c59d..0bb0a336 100644 --- a/src/site/fml/faq.fml +++ b/src/site/fml/faq.fml @@ -11,9 +11,13 @@ Can the plugin automatically download and use the required version of <code>protoc</code>? </question> <answer> + It depends on the version of <code>protoc</code>. Protocol Buffer Compiler is a native application and is distributed as a binary executable file. - For the time being, it is not distributed via Maven repository (and unlikely that it will ever be). - Therefore the application developer will need to configure <code>protoc</code> executable location + Previously, it was not distributed via Maven repository, but that policy has recently changed. + Starting with versions <code>2.6.1</code> and <code>3.0.0-alpha-2</code>, binary executables + for all major operating systems are available as artifacts in Maven central, and these artifacts + can be referenced in plugin configuration. + For any prior versions the application developer will need to configure <code>protoc</code> executable location for the plugin, either explicitly with <code>protocExecutable</code> plugin configuration parameter, or, preferably, by using protobuf <a href="./examples/protobuf-toolchain.html">toolchain</a>. </answer> diff --git a/src/site/site.xml b/src/site/site.xml index 3d572bdb..da7c9285 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -20,6 +20,7 @@ <menu name="Examples"> <!-- TODO --> <item name="Protobuf Toolchain" href="examples/protobuf-toolchain.html"/> + <item name="Protoc Artifact" href="examples/protoc-artifact.html"/> <item name="Custom Protoc Plugins" href="examples/protoc-plugin.html"/> </menu>