Improved and updated site documentation

sergei-ivanov · Apr 27, 2015 · 22e8f7f · 22e8f7f
1 parent fb1778d
commit 22e8f7f
Show file tree

Hide file tree

Showing 9 changed files with 106 additions and 14 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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,15 +101,14 @@ 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
   paths of all resolved artifacts and then runs the configured <<<java>>> command.
 
   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
@@ -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
@@ -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
@@ -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
@@ -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>