yetus-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From a.@apache.org
Subject [yetus] 02/02: YETUS-731. docs need to be written for yetus-maven-plugin
Date Tue, 08 Jan 2019 22:07:30 GMT
This is an automated email from the ASF dual-hosted git repository.

aw pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/yetus.git

commit c9f7af7d30179dc19550c1342c249f372262d403
Author: Allen Wittenauer <aw@apache.org>
AuthorDate: Fri Jan 4 22:07:38 2019 -0800

    YETUS-731. docs need to be written for yetus-maven-plugin
    
    Signed-off-by: Allen Wittenauer <aw@apache.org>
---
 .../source/documentation/in-progress.html.md       |   6 +-
 .../in-progress/yetus-maven-plugin.md              | 197 +++++++++++++++++++++
 .../yetus/maven/plugin/fileops/CreateDirsMojo.java |   9 +
 .../maven/plugin/rdm/ReleaseDocMakerMojo.java      |   6 +
 .../org/apache/yetus/maven/plugin/utils/Utils.java |   8 +-
 yetus-minimaven-plugin/pom.xml                     |   5 +
 .../maven/plugin/fileops/CreateSymLinkMojo.java    |   5 +
 .../yetus/maven/plugin/fileops/MakeBins4Libs.java  |   4 +
 8 files changed, 238 insertions(+), 2 deletions(-)

diff --git a/asf-site-src/source/documentation/in-progress.html.md b/asf-site-src/source/documentation/in-progress.html.md
index fbfab4b..06a0470 100644
--- a/asf-site-src/source/documentation/in-progress.html.md
+++ b/asf-site-src/source/documentation/in-progress.html.md
@@ -35,7 +35,7 @@ For help with CI tools and automation, see our documentation about [robots](prec
 # Yetus Release Doc Maker
 
 The Release Documentation Maker allows projects to generate nicely formated Markdown Changelogs
and Release Notes based upon JIRA. You can view that
-documenation [here](releasedocmaker).
+documenation [here](releasedocmaker). See also the (yetus-maven-plugin)[#yetus-maven-plugin]
for Apache Maven-specific information.
 
 # Yetus Shelldocs
 
@@ -58,6 +58,10 @@ Options:
 
 You can mark a file to be ignored by shelldocs by adding "SHELLDOC-IGNORE" as a comment in
its own line.
 
+# yetus-maven-plugin
+
+Many Apache Yetus functions are available directly from Apache Maven and compatible build
systems, without the need to use annoying wrappers!  The (yetus-maven-plugin documentation)[yetus-maven-plugin/]
provides all the key details.
+
 # Javadocs: Yetus Audience Annotations and more
 
 Audience Annotations allows you to use Java Annotations to denote which parts of your Java
library is publicly consumable and which parts are reserved for a more restricted use. It
also provides doclets and examples for generating javadocs limited by audience.
diff --git a/asf-site-src/source/documentation/in-progress/yetus-maven-plugin.md b/asf-site-src/source/documentation/in-progress/yetus-maven-plugin.md
new file mode 100644
index 0000000..d8cc191
--- /dev/null
+++ b/asf-site-src/source/documentation/in-progress/yetus-maven-plugin.md
@@ -0,0 +1,197 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+Yetus Maven Plug-in
+===================
+
+* [Introduction](#introduction)
+* [File Utility Goals](#file-utility-goals)
+  * [bin4libs](#bin4libs)
+  * [symlink](#symlink)
+  * [parallel-mkdirs](#parallel-mkdirs)
+* [releasedocmaker](#releasedocmaker)
+
+# Introduction
+
+Apache Yetus a plug-in built for Apache Maven and compatible build tools.  This plug-in offers
an easy way to integrate some of Apache Yetus' functionality in addition to offering a way
to get some additional functionality that is missing from the base Maven environment.
+
+    NOTE: This functionality should be considered experimental. Defaults, in particular,
are likely to change in future revisions.
+
+# File Utility Goals
+
+As part of building Apache Yetus, we needed some portable functionality that we couldn't
find elsewhere.  Just so others don't have to re-invent the wheel, we offer these goals as
part of the plug-in:
+
+## bin4libs
+
+Apache Yetus builds wrappers in `bin/` that point to executables in `lib/`.  This goal provides
a way to do this generically, including providing the capability to put a license file in
the wrapper.
+
+      <plugin>
+        <groupId>org.apache.yetus</groupId>
+        <artifactId>yetus-maven-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>bins4libs</id>
+            <phase>prepare-package</phase>
+            <goals>
+              <goal>bin4libs</goal>
+            </goals>
+            <configuration>
+              <libdir>lib/shelldocs</libdir>
+              <basedir>${project.build.directory}/dist/</basedir>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+
+This example will take all the files located in `${project.build.directory}/dist/lib/shelldocs/`
and create wrappers in `${project.build.directory}/dist/bin` with any extensions stripped
off.  If the `${project.build.directory}/dist/lib/shelldocs/` contains the file `shelldocs.py`,
then the `bin/shelldocs` wrapper will look like this:
+
+```bash
+#!/usr/bin/env bash
+[LICENSE TEXT]
+exec "$(dirname -- "${BASH_SOURCE-0}")/../lib/shelldocs/shelldocs.py" "$@"
+```
+
+The wrapper as written above makes sure that nearly all forms of referencing (relative, absolute,
bash -x, etc.) locates the real executable, passing along any options.
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `basedir` | parent dir of `bindir` and `lib` to create relative paths | `${project.build.directory}/${project.artifactId}-${project.version}`
|
+| `bindir` | where to create wrapper | `bin` |
+| `encoding` | encoding to use when reading license files | `${project.build.sourceEncoding}`
|
+| `goal` | the goal to use when creating the wrappers | `package` |
+| `lib` | where the actual executable is located | `lib` |
+| `license` | the license to put into the wrapper. See below. | `ASL20` |
+| `wrapper` | the bash wrapper to actually use | `exec "$(dirname -- "${BASH_SOURCE-0}")/../"`
|
+
+### Licenses
+
+The `license` field translates to `licenses/NAME.txt` as the name of the file to load from
the CLASSPATH.  The `ASL20` license is the Apache Software License v2.0.
+
+If no license is wanted, then set `license` to the string `none`.
+
+## symlink
+
+Since Java 7, there has been a portable way to build symlinks.  Unfortunately, standard plug-ins
like the `maven-antrun-plugin` have not been updated to include the symlink task. The `yetus-maven-plugin`
now exposes this functionality via the `symlink` goal:
+
+      <plugin>
+        <groupId>org.apache.yetus</groupId>
+        <artifactId>yetus-maven-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>exec-id</id>
+            <phase>compile</phase>
+            <goals>
+              <goal>symlink</goal>
+            </goals>
+            <configuration>
+              <basedir>${project.build.directory}</basedir>
+              <target>existing-file-or-dir</target>
+              <newLink>link-to-create</newLink>
+              <ignoreExist>true</ignoreExist>
+            </configuration>
+          </execution>
+        </plugin>
+
+Available configuration options:
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `basedir` | where to create the symlink, if `newLink` is not absolute | `${project.build.directory}`
|
+| `goal` | the goal to use when to create the symlink | `package` |
+| `ignoreExist` | a boolean that determines whether the goal should fail if the `newLink`
already exists. | `true`. |
+| `target` | the file or directory to link to | none |
+| `newLink` | the symlink to create | none |
+
+## parallel-mkdirs
+
+Maven surefire (as of at least 2.x and earlier versions) has calculations to determine the
number of tests to run in parallel.  However, the result is not shared in a way that allows
creating directory structures before execution.  For specific build flows, this is problematic.
+
+      <plugin>
+        <groupId>org.apache.yetus</groupId>
+        <artifactId>yetus-maven-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>parallel-mkdirs</id>
+            <phase>compile</phase>
+            <goals>
+              <goal>parallel-mkdirs</goal>
+            </goals>
+            <configuration>
+              <buildDir>${project.build.directory}/test-dir</buildDir>
+            </configuration>
+          </execution>
+        </plugin>
+
+Available configuration options:
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `buildDir` | where to create the directories | `${project.build.directory}/test-dir` |
+| `forkCount` | the number of directories to create| see blow |
+| `goal` | the goal to use to create the directories | `generate-test-resources` |
+
+By default, `forkCount` is inherited from surefire and therefore follows the same rules as
described in its [documentation](https://maven.apache.org/surefire/maven-surefire-plugin/examples/fork-options-and-parallel-execution.html).
 Of special note is that 'C' (aka core) values are honored.
+
+# releasedocmaker
+
+This goal runs releasedocmaker without the need to download or build an Apache Yetus tarball.
 Instead, yetus-maven-plugin contains all the necessary components in a native maven way!
+
+      <plugin>
+        <groupId>org.apache.yetus</groupId>
+        <artifactId>yetus-maven-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>rdm</id>
+            <phase>pre-site</phase>
+            <goals>
+              <goal>releaseodcmaker</goal>
+            </goals>
+            <configuration>
+              <projects>
+                <project>HADOOP</project>
+                <project>HDFS</project>
+                <project>MAPRED</project>
+                <project>YARN</project>
+              </projects>
+            </configuration>
+          </execution>
+        </plugin>
+
+
+
+The configuration options generally map 1:1 to the `releasedocmaker` executable's options.
 Unless otherwise specified, defaults are set by the actual executable.
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `baseUrl` | --baseurl | |
+| `dirversions` | boolean; same as --dirversions | false |
+| `fileversions` | boolean; same as --fileversions | false |
+| `incompatibleLabel` | --incompatiblelabel | |
+| `index` | boolean; --index | false  |
+| `license` | boolean; --license | false |
+| `lint` | boolean; --lint | false |
+| `outputDir` | --outputdir | `${project.build.directory}/generated-site/markdown` |
+| `projects` | ArrayList; --projects | `${project.name}` |
+| `projectTitle` | --projecttitle | |
+| `range` | boolean; --range | false |
+| `skipcredits` | boolean; --skipcredits | false |
+| `sortorder` | --sortorder | older |
+| `sorttype` | --sorttype | resolutiondate |
+| `useToday` | --usetoday | false |
+| `versions` | ArrayList; --versions | `${project.version}` |
diff --git a/yetus-maven-plugin/src/main/java/org/apache/yetus/maven/plugin/fileops/CreateDirsMojo.java
b/yetus-maven-plugin/src/main/java/org/apache/yetus/maven/plugin/fileops/CreateDirsMojo.java
index 8c61cd4..bec4af8 100644
--- a/yetus-maven-plugin/src/main/java/org/apache/yetus/maven/plugin/fileops/CreateDirsMojo.java
+++ b/yetus-maven-plugin/src/main/java/org/apache/yetus/maven/plugin/fileops/CreateDirsMojo.java
@@ -21,12 +21,17 @@ import org.apache.maven.plugins.annotations.LifecyclePhase;
 import org.apache.maven.plugins.annotations.Mojo;
 import org.apache.maven.plugins.annotations.Parameter;
 
+import org.apache.yetus.audience.InterfaceAudience;
+import org.apache.yetus.audience.InterfaceStability;
+
 /**
  * Goal which creates the X directories.
  */
 @Mojo(name = "parallel-mkdirs",
       defaultPhase = LifecyclePhase.GENERATE_TEST_RESOURCES,
         threadSafe = true)
+@InterfaceAudience.Private
+@InterfaceStability.Unstable
 public final class CreateDirsMojo extends AbstractMojo {
 
   /**
@@ -45,6 +50,8 @@ public final class CreateDirsMojo extends AbstractMojo {
    * Execute our plugin.
    * @throws MojoExecutionException  an error occurred
    */
+  @InterfaceAudience.Private
+  @InterfaceStability.Unstable
   public void execute() throws MojoExecutionException {
     int numDirs = getForkCount();
 
@@ -55,6 +62,8 @@ public final class CreateDirsMojo extends AbstractMojo {
    * Get the real number of parallel threads.
    * @return int number of threads
    */
+  @InterfaceAudience.Private
+  @InterfaceStability.Unstable
   public int getForkCount() {
     int calcForkCount = 1;
     if (forkCount != null) {
diff --git a/yetus-maven-plugin/src/main/java/org/apache/yetus/maven/plugin/rdm/ReleaseDocMakerMojo.java
b/yetus-maven-plugin/src/main/java/org/apache/yetus/maven/plugin/rdm/ReleaseDocMakerMojo.java
index 8736ddd..7badb75 100644
--- a/yetus-maven-plugin/src/main/java/org/apache/yetus/maven/plugin/rdm/ReleaseDocMakerMojo.java
+++ b/yetus-maven-plugin/src/main/java/org/apache/yetus/maven/plugin/rdm/ReleaseDocMakerMojo.java
@@ -23,6 +23,8 @@ import org.apache.maven.plugins.annotations.LifecyclePhase;
 import org.apache.maven.plugins.annotations.Mojo;
 import org.apache.maven.plugins.annotations.Parameter;
 
+import org.apache.yetus.audience.InterfaceAudience;
+import org.apache.yetus.audience.InterfaceStability;
 import org.apache.yetus.releasedocmaker.ReleaseDocMaker;
 
 /**
@@ -31,6 +33,8 @@ import org.apache.yetus.releasedocmaker.ReleaseDocMaker;
 @Mojo(name = "releasedocmaker",
       defaultPhase = LifecyclePhase.PRE_SITE,
         threadSafe = true)
+@InterfaceAudience.Private
+@InterfaceStability.Unstable
 public final class ReleaseDocMakerMojo extends AbstractMojo {
 
   /**
@@ -144,6 +148,8 @@ public final class ReleaseDocMakerMojo extends AbstractMojo {
    * Execute our plugin.
    * @throws MojoExecutionException  an error occurred
    */
+  @InterfaceAudience.Private
+  @InterfaceStability.Unstable
   public void execute() throws MojoExecutionException {
 
     buildArgs();
diff --git a/yetus-maven-plugin/src/main/java/org/apache/yetus/maven/plugin/utils/Utils.java
b/yetus-maven-plugin/src/main/java/org/apache/yetus/maven/plugin/utils/Utils.java
index e8616f9..651d6c3 100644
--- a/yetus-maven-plugin/src/main/java/org/apache/yetus/maven/plugin/utils/Utils.java
+++ b/yetus-maven-plugin/src/main/java/org/apache/yetus/maven/plugin/utils/Utils.java
@@ -32,7 +32,7 @@ import org.apache.yetus.audience.InterfaceStability;
  * Random utilities for running Yetus components.
  */
 @InterfaceAudience.Private
-@InterfaceStability.Unstable
+@InterfaceStability.Evolving
 public final class Utils {
 
   /**
@@ -55,6 +55,8 @@ public final class Utils {
   /**
    * Constructor for generic utilities.
    */
+  @InterfaceAudience.Private
+  @InterfaceStability.Evolving
   public Utils() {
     this.zipFile = new ZipInputStream(this.getClass()
           .getClassLoader()
@@ -69,6 +71,8 @@ public final class Utils {
    * @throws InterruptedException an error occurred
    * @return int process return code
    */
+  @InterfaceAudience.Private
+  @InterfaceStability.Evolving
   public int execCmd(final String cmd, final String... args)
       throws IOException, InterruptedException {
     File cmdFile = new File(binDir, cmd);
@@ -91,6 +95,8 @@ public final class Utils {
    * @param destDir The unzip directory where to extractthe  file.
    * @throws IOException an error occurred
    */
+  @InterfaceAudience.Private
+  @InterfaceStability.Evolving
   public void extractYetus(final File destDir) throws IOException {
     this.binDir = new File(destDir, "bin");
 
diff --git a/yetus-minimaven-plugin/pom.xml b/yetus-minimaven-plugin/pom.xml
index 49dd4e5..5af8663 100644
--- a/yetus-minimaven-plugin/pom.xml
+++ b/yetus-minimaven-plugin/pom.xml
@@ -51,6 +51,11 @@
       <version>${maven.api.version}</version>
       <scope>provided</scope>
     </dependency>
+    <dependency>
+      <groupId>org.apache.yetus</groupId>
+      <artifactId>audience-annotations</artifactId>
+      <version>${project.version}</version>
+    </dependency>
   </dependencies>
 
   <build>
diff --git a/yetus-minimaven-plugin/src/main/java/org/apache/yetus/maven/plugin/fileops/CreateSymLinkMojo.java
b/yetus-minimaven-plugin/src/main/java/org/apache/yetus/maven/plugin/fileops/CreateSymLinkMojo.java
index c93a9ed..d0e6146 100644
--- a/yetus-minimaven-plugin/src/main/java/org/apache/yetus/maven/plugin/fileops/CreateSymLinkMojo.java
+++ b/yetus-minimaven-plugin/src/main/java/org/apache/yetus/maven/plugin/fileops/CreateSymLinkMojo.java
@@ -26,12 +26,17 @@ import org.apache.maven.plugins.annotations.LifecyclePhase;
 import org.apache.maven.plugins.annotations.Mojo;
 import org.apache.maven.plugins.annotations.Parameter;
 
+import org.apache.yetus.audience.InterfaceAudience;
+import org.apache.yetus.audience.InterfaceStability;
+
 /**
  * Goal which creates symlinks.
  */
 @Mojo(name = "symlink",
       defaultPhase = LifecyclePhase.PACKAGE,
       threadSafe = true)
+@InterfaceAudience.Private
+@InterfaceStability.Unstable
 public final class CreateSymLinkMojo extends AbstractMojo {
 
   /**
diff --git a/yetus-minimaven-plugin/src/main/java/org/apache/yetus/maven/plugin/fileops/MakeBins4Libs.java
b/yetus-minimaven-plugin/src/main/java/org/apache/yetus/maven/plugin/fileops/MakeBins4Libs.java
index cb6b2cc..a34e9d2 100644
--- a/yetus-minimaven-plugin/src/main/java/org/apache/yetus/maven/plugin/fileops/MakeBins4Libs.java
+++ b/yetus-minimaven-plugin/src/main/java/org/apache/yetus/maven/plugin/fileops/MakeBins4Libs.java
@@ -32,6 +32,8 @@ import org.apache.maven.plugins.annotations.Parameter;
 import org.apache.commons.io.FilenameUtils;
 import org.apache.commons.io.IOUtils;
 
+import org.apache.yetus.audience.InterfaceAudience;
+import org.apache.yetus.audience.InterfaceStability;
 
 /**
  * Goal which creates symlinks.
@@ -39,6 +41,8 @@ import org.apache.commons.io.IOUtils;
 @Mojo(name = "bin4libs",
       defaultPhase = LifecyclePhase.PACKAGE,
       threadSafe = true)
+@InterfaceAudience.Private
+@InterfaceStability.Unstable
 public final class MakeBins4Libs extends AbstractMojo {
 
   /**


Mime
View raw message