[maven-wrapper-plugin] branch documentation updated: Add documentation

classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view
|

[maven-wrapper-plugin] branch documentation updated: Add documentation

rfscholte
This is an automated email from the ASF dual-hosted git repository.

rfscholte pushed a commit to branch documentation
in repository https://gitbox.apache.org/repos/asf/maven-wrapper-plugin.git


The following commit(s) were added to refs/heads/documentation by this push:
     new 6feec38  Add documentation
6feec38 is described below

commit 6feec38e6d4c9fd0e2eb4d4bc067c280efb61c45
Author: rfscholte <[hidden email]>
AuthorDate: Sat May 23 17:01:22 2020 +0200

    Add documentation
---
 src/site/markdown/index.md.vm   |  52 +++++++++++++++++
 src/site/markdown/usage.md      |  57 ++++++++++++++++++
 src/site/resources/download.cgi |  22 +++++++
 src/site/site.xml               |  35 +++++++++++
 src/site/xdoc/download.xml.vm   | 126 ++++++++++++++++++++++++++++++++++++++++
 5 files changed, 292 insertions(+)

diff --git a/src/site/markdown/index.md.vm b/src/site/markdown/index.md.vm
new file mode 100644
index 0000000..a6d50dd
--- /dev/null
+++ b/src/site/markdown/index.md.vm
@@ -0,0 +1,52 @@
+# Apache Maven Wrapper Plugin
+<!--
+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.
+-->
+
+The Apache Maven Wrapper Plugin helps with downloading and unpacking the wrapper distribution
+ as introduced in Apache Maven 3.7.0
+
+Goals Overview
+--------------
+
+
+ * [wrapper:wrapper](./wrapper-mojo.html) is the default goal invoked during the
+   `wrapper` phase. It downloads and unpacks the apache-maven-wrapper distribution,
+
+Usage
+-----
+
+  General instructions on how to use the Wrapper Plugin can be found on the
+  [usage page](./usage.html).
+
+  In case you still have questions regarding the plugin's usage, please have a look at the
+  [FAQ](./faq.html) and feel free to contact the [user mailing list](./mail-lists.html).
+  The posts to the mailing list are archived and could already contain the answer to your
+  question as part of an older thread. Hence, it is also worth browsing/searching
+  the [mail archive](./mail-lists.html).
+
+  If you feel like the plugin is missing a feature or has a defect, you can fill a
+  feature request or bug report in our [issue tracker](./issue-tracking.html).
+  When creating a new issue, please provide a comprehensive description of your
+  concern. Especially for fixing bugs it is crucial that the developers can
+  reproduce your problem. For this reason, entire debug logs, POMs or most
+  preferably little demo projects attached to the issue are very much appreciated.
+  Of course, patches are welcome, too. Contributors can check out the project from
+  our [source repository](./source-repository.html) and will find supplementary
+  information in the
+  [guide to helping with Maven](http://maven.apache.org/guides/development/guide-helping.html).
diff --git a/src/site/markdown/usage.md b/src/site/markdown/usage.md
new file mode 100644
index 0000000..f7f6a35
--- /dev/null
+++ b/src/site/markdown/usage.md
@@ -0,0 +1,57 @@
+# Usage
+<!--
+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.
+-->
+
+Wrapper scripts are a set of files that can be added to your Maven project.
+If people want to build this project, they don't need to install Maven first.
+Instead they can call the maven wrapper script, which will download and unpack Maven into their `${user.home}/.m2/wrapper/dists` folder.
+It is also a way to let every build the project with the same Maven version.
+
+The Apache Maven Wrapper Plugin makes it easier to add these wrapper scripts to your project.
+
+The scripts work like this:
+- download the maven-wrapper jar, if it is not available yet.
+- the wrapper-jar contains the code to download and run Apache Maven
+
+Types
+-----
+
+There are 3 types available
+
+- **Script** _(default)_: With this type the scripts will try to download the scripts via wget or curl in case of Unix based system, or use Powershell in case of Windows
+
+
+- **Bin**: With this type the maven-wrapper jar is already available in the `.mvn/wrapper` folder, so you don't have to rely on wget/curl or Powershell
+The downside is that the project will contain a binary file in the source control management system.
+
+- **Source**: Since Maven already requires Java to run, why not compile and run a classfile to download the maven-wrapper jar?
+This type comes with a `.mvn/wrapper/MavenWrapperDownloader.java` which will be compiled and executed on the fly.
+
+Maven Version
+-------------
+By default the plugin will assume the same version as the Maven runtime (calling `mvn -v`). But you can pick a different version.
+Either call `mvn wrapper -DmavenVersion=x`, where x is any valid Apache Maven Release, see https://search.maven.org/artifact/org.apache.maven/apache-maven
+Another option is adjust the `distributionUrl` in `.mvn/wrapper/maven-wrapper.properties`
+
+Debugging
+---------
+
+The apache-maven-wrapper distributions all contains the `mvnwDebug`-script for both Windows and Unix based operating systems.
+This makes it possible to debug through Apache Maven, Maven Plugin or Maven Extension.
+You can exclude these scripts by calling `mvn wrapper -DincludeDebug=false`
\ No newline at end of file
diff --git a/src/site/resources/download.cgi b/src/site/resources/download.cgi
new file mode 100644
index 0000000..1b178d2
--- /dev/null
+++ b/src/site/resources/download.cgi
@@ -0,0 +1,22 @@
+#!/bin/sh
+#
+# 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.
+#
+# Just call the standard mirrors.cgi script. It will use download.html
+# as the input template.
+exec /www/www.apache.org/dyn/mirrors/mirrors.cgi $*
\ No newline at end of file
diff --git a/src/site/site.xml b/src/site/site.xml
new file mode 100644
index 0000000..9b32692
--- /dev/null
+++ b/src/site/site.xml
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+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.
+-->
+
+<project xmlns="http://maven.apache.org/DECORATION/1.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/DECORATION/1.0.0 http://maven.apache.org/xsd/decoration-1.0.0.xsd">
+  <body>
+    <menu name="Overview">
+      <item name="Introduction" href="index.html"/>
+      <item name="Goals" href="plugin-info.html"/>
+      <item name="Usage" href="usage.html"/>
+      <!-- According to https://issues.apache.org/jira/browse/MNGSITE-152 -->
+      <item name="License" href="http://www.apache.org/licenses/"/>
+      <item name="Download" href="download.html"/>
+    </menu>
+  </body>
+</project>
diff --git a/src/site/xdoc/download.xml.vm b/src/site/xdoc/download.xml.vm
new file mode 100644
index 0000000..cf13dc9
--- /dev/null
+++ b/src/site/xdoc/download.xml.vm
@@ -0,0 +1,126 @@
+<?xml version="1.0"?>
+
+<!--
+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.
+-->
+
+<document>
+  <properties>
+    <title>Download ${project.name} Source</title>
+  </properties>
+  <body>
+    <section name="Download ${project.name} ${project.version} Source">
+
+      <p>${project.name} ${project.version} is distributed in source format. Use a source archive if you intend to build
+      ${project.name} yourself. Otherwise, simply use the ready-made binary artifacts from central repository.</p>
+
+      <p>You will be prompted for a mirror - if the file is not found on yours, please be patient, as it may take 24
+      hours to reach all mirrors.<p/>
+
+      <p>In order to guard against corrupted downloads/installations, it is highly recommended to
+      <a href="http://www.apache.org/dev/release-signing#verifying-signature">verify the signature</a>
+      of the release bundles against the public <a href="http://www.apache.org/dist/maven/KEYS">KEYS</a> used by the Apache Maven
+      developers.</p>
+
+      <p>${project.name} is distributed under the <a href="http://www.apache.org/licenses/">Apache License, version 2.0</a>.</p>
+
+      <p></p>We <b>strongly</b> encourage our users to configure a Maven repository mirror closer to their location, please read <a href="/guides/mini/guide-mirror-settings.html">How to Use Mirrors for Repositories</a>.</p>
+
+      <a name="mirror"/>
+      <subsection name="Mirror">
+
+        <p>
+          [if-any logo]
+          <a href="[link]">
+            <img align="right" src="[logo]" border="0"
+                 alt="logo"/>
+          </a>
+          [end]
+          The currently selected mirror is
+          <b>[preferred]</b>.
+          If you encounter a problem with this mirror,
+          please select another mirror.
+          If all mirrors are failing, there are
+          <i>backup</i>
+          mirrors
+          (at the end of the mirrors list) that should be available.
+        </p>
+
+        <form action="[location]" method="get" id="SelectMirror">
+          Other mirrors:
+          <select name="Preferred">
+            [if-any http]
+            [for http]
+            <option value="[http]">[http]</option>
+            [end]
+            [end]
+            [if-any ftp]
+            [for ftp]
+            <option value="[ftp]">[ftp]</option>
+            [end]
+            [end]
+            [if-any backup]
+            [for backup]
+            <option value="[backup]">[backup] (backup)</option>
+            [end]
+            [end]
+          </select>
+          <input type="submit" value="Change"/>
+        </form>
+
+        <p>
+          You may also consult the
+          <a href="http://www.apache.org/mirrors/">complete list of
+            mirrors.</a>
+        </p>
+
+      </subsection>
+      
+      <subsection name="${project.name} ${project.version}">
+        
+      <p>This is the current stable version of ${project.name}.</p>
+        
+      <table>
+        <thead>
+          <tr>
+            <th></th>
+            <th>Link</th>
+            <th>Checksum</th>
+            <th>Signature</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td>${project.name} ${project.version} (Source zip)</td>
+            <td><a href="[preferred]maven/plugins/${project.artifactId}-${project.version}-source-release.zip">maven/plugins/${project.artifactId}-${project.version}-source-release.zip</a></td>
+            <td><a href="http://www.apache.org/dist/maven/plugins/${project.artifactId}-${project.version}-source-release.zip.sha1">maven/plugins/${project.artifactId}-${project.version}-source-release.zip.sha1</a></td>
+            <td><a href="http://www.apache.org/dist/maven/plugins/${project.artifactId}-${project.version}-source-release.zip.asc">maven/plugins/${project.artifactId}-${project.version}-source-release.zip.asc</a></td>
+          </tr>
+        </tbody>
+      </table>
+      </subsection>
+
+      <subsection name="Previous Versions">
+        
+      <p>Older non-recommended releases can be found on our <a href="http://archive.apache.org/dist/maven/plugins/">archive site</a>.</p>
+
+      </subsection>
+    </section>
+  </body>
+</document>
+