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 <[email protected]> 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 <[email protected]> --- .../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) [email protected] [email protected] 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) [email protected] [email protected] 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 [email protected] [email protected] 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) [email protected] [email protected] 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) [email protected] [email protected] public final class MakeBins4Libs extends AbstractMojo { /**
