You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@yetus.apache.org by aw...@apache.org on 2019/01/08 22:07:30 UTC
[yetus] 02/02: YETUS-731. docs need to be written for
yetus-maven-plugin
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 {
/**