Modified: maven/website/content/guides/mini/guide-reproducible-builds.html ============================================================================== --- maven/website/content/guides/mini/guide-reproducible-builds.html (original) +++ maven/website/content/guides/mini/guide-reproducible-builds.html Sat Feb 18 20:40:58 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/mini/guide-reproducible-builds.md at 2023-02-18 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-reproducible-builds.apt at 2023-02-18 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -48,7 +48,7 @@ <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Guide to Configuring for Reproducible Builds <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/mini/guide-reproducible-builds.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li class="active ">Guide to Configuring for Reproducible Builds <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/mini/guide-reproducible-builds.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-18</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> @@ -154,151 +154,131 @@ </div> </header> <main id="bodyColumn" class="span10" > -<!-- -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. ---> -<section><section> -<h2>Configuring for Reproducible Builds</h2><section> -<h3>What are Reproducible Builds?</h3> -<p><a href="https://reproducible-builds.org/"; class="externalLink">Reproducible builds</a> are a set of software development practices that create an independently-verifiable path from source to binary code. A build is <strong>reproducible</strong> if given the same source code, build environment and build instructions, any party can recreate <strong>bit-by-bit</strong> identical copies of all specified artifacts.</p> -<p><a href="https://github.com/jvm-repo-rebuild/reproducible-central"; class="externalLink">Reproducible Central</a> lists projects releases that have been checked as reproducible by rebuilding independently from the reference build published in Central Repository.</p></section><section> -<h3>How do I configure my Maven build?</h3> +<section> +<h1>Configuring for Reproducible Builds</h1><section> +<h2>What are Reproducible Builds?</h2> +<p><a class="externalLink" href="https://reproducible-builds.org/";>Reproducible builds</a> are a set of software development practices that create an independently-verifiable path from source to binary code. A build is <b>reproducible</b> if given the same source code, build environment and build instructions, any party can recreate <b>bit-by-bit</b> identical copies of all specified artifacts.</p> +<p><a class="externalLink" href="https://github.com/jvm-repo-rebuild/reproducible-central";>Reproducible Central</a> lists projects releases that have been checked as reproducible by rebuilding independently from the reference build published in Central Repository.</p></section><section> +<h2>How do I configure my Maven build?</h2> <p>There is no Maven version prerequisite. Everything happens at plugin level:</p> -<p>1 Upgrade your plugins to reproducible versions: to easily detect <a href="/plugins/maven-artifact-plugin/plugin-issues.html">required upgrades</a>, run</p> - -<div class="source"><pre class="prettyprint linenums"><code>mvn artifact:check-buildplan -</code></pre></div> -<p>1 Enable Reproducible Builds mode for plugins, by adding <a href="https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=74682318#Reproducible/VerifiableBuilds-OutputArchiveEntriesTimestamp"; class="externalLink"><code>project.build.outputTimestamp</code> property</a> to the project's <code>pom.xml</code>:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"> <properties> +<ol style="list-style-type: decimal"> +<li>Upgrade your plugins to reproducible versions: to easily detect <a href="/plugins/maven-artifact-plugin/plugin-issues.html">required upgrades</a>, run +<div> +<pre>mvn artifact:check-buildplan</pre></div></li> +<li>Enable Reproducible Builds mode for plugins, by adding <a class="externalLink" href="https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=74682318#Reproducible/VerifiableBuilds-OutputArchiveEntriesTimestamp";><code>project.build.outputTimestamp</code> property</a> to the project's <code>pom.xml</code>: +<div class="source"><pre class="prettyprint linenums"> <properties> <project.build.outputTimestamp>2023-01-01T00:00:00Z</project.build.outputTimestamp> - </properties> -</code></pre></div> + </properties></pre></div></li></ol> <p>You have the basics configured. The output should be mostly reproducible now.</p></section><section> -<h3>How to test my Maven build reproducibility?</h3> +<h2>How to test my Maven build reproducibility?</h2> <p>Using <a href="/plugins/maven-artifact-plugin/compare-mojo.html"><code>maven-artifact-plugin</code>'s <code>compare</code> goal</a>, you can check that the second build of your project produce the same output than an initial build:</p> -<p>1 build and <code>install</code> your project (don't hesitate to customize arguments to better match your project):</p> - -<div class="source"><pre class="prettyprint linenums"><code>mvn clean install -</code></pre></div> -<p>1 rebuild (<code>verify</code> only, without installing) and check against the previous install:</p> - -<div class="source"><pre class="prettyprint linenums"><code>mvn clean verify artifact:compare -</code></pre></div></section><section> -<h3>How to fix my Maven build reproducibility?</h3> +<ol style="list-style-type: decimal"> +<li>build and <code>install</code> your project (don't hesitate to customize arguments to better match your project): +<div> +<pre>mvn clean install </pre></div></li> +<li>rebuild (<code>verify</code> only, without installing) and check against the previous install: +<div> +<pre>mvn clean verify artifact:compare</pre></div></li></ol></section><section> +<h2>How to fix my Maven build reproducibility?</h2> <p>If something is still not reproducible after initial setup and <a href="/plugins/maven-artifact-plugin/plugin-issues.html">automatic check from <code>artifact:check-buildplan</code></a>:</p> -<p>1 Use <a href="https://diffoscope.org/"; class="externalLink">diffoscope</a> to find the unstable output between builds. The <code>artifact:buildinfo</code> goal proposes a command with path to files: just copy/paste to launch.</p> -<p>1 Find the plugin that generated this output.</p> -<p>1 Check if a reproducible version of the plugin is available. If not, please open an issue to help plugin maintainers improving Reproducible Builds support at every plugin level.</p></section><section> -<h3>More Details</h3> +<ol style="list-style-type: decimal"> +<li>Use <a class="externalLink" href="https://diffoscope.org/";>diffoscope</a> to find the unstable output between builds. The <code>artifact:buildinfo</code> goal proposes a command with path to files: just copy/paste to launch.</li> +<li>Find the plugin that generated this output.</li> +<li>Check if a reproducible version of the plugin is available. If not, please open an issue to help plugin maintainers improving Reproducible Builds support at every plugin level.</li></ol></section><section> +<h2>More Details</h2> <p>Reproducible Builds for Maven:</p> <ul> - -<li> -<p>Require <strong>no version ranges</strong> in dependencies,</p></li> -<li> -<p>Generally give <strong>different results on Windows and Unix</strong> because of different newlines. (carriage return linefeed on Windows, linefeed on Unixes)</p></li> -<li> -<p>Generally depend on the <strong>major version of the JDK</strong> used to compile. (Even with source/target defined, each major JDK version changes the generated bytecode)</p></li> -</ul> -<p>For detailed explanations, see <a href="https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=74682318"; class="externalLink">Maven “Reproducible/Verifiable Builds” Wiki page</a>.</p></section><section> -<h3>FAQ</h3> +<li>Require <b>no version ranges</b> in dependencies,</li> +<li>Generally give <b>different results on Windows and Unix</b> because of different newlines. (carriage return linefeed on Windows, linefeed on Unixes)</li> +<li>Generally depend on the <b>major version of the JDK</b> used to compile. (Even with source/target defined, each major JDK version changes the generated bytecode)</li></ul> +<p>For detailed explanations, see <a class="externalLink" href="https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=74682318";>Maven "Reproducible/Verifiable Builds" Wiki page</a>.</p></section><section> +<h2>FAQ</h2> <ul> - -<li> -<p>Q. Can the <code>project.build.outputTimestamp</code> property in <code>pom.xml</code> be updated automatically at release time?</p> +<li>Q. Can the <code>project.build.outputTimestamp</code> property in <code>pom.xml</code> be updated automatically at release time? <p>A. Yes.</p> -<p>Details depend on your release process tooling:</p></li> -<li> -<p>if you use <a href="/plugins/maven-release-plugin/">maven-release-plugin</a>, you'll need <strong>version 3.0.0-M1 or later</strong>: it will automatically update the timestamp value in <code>pom.xml</code> during the release in the same commit that updates version,</p></li> -<li> -<p>if you have a custom release process tooling, you'll need to add the feature to your release tooling. Notice that if you're using <code>versions-maven-plugin</code> in custom release scripts, starting with release 2.9.0, <a href="https://github.com/mojohaus/versions-maven-plugin/issues/453"; class="externalLink"><code>versions:set</code> goal updates the property</a>.</p></li> -<li> -<p>instead of explicitely writing a timestamp in their <code>pom.xml</code>, some people tend to prefer using last Git commit timestamp, like <code>${git.commit.time}</code> from <a href="https://github.com/git-commit-id/git-commit-id-maven-plugin"; class="externalLink">git-commit-id-maven-plugin</a>.</p></li> -</ul> +<p>Details depend on your release process tooling:</p> +<ul> +<li>if you use <a href="/plugins/maven-release-plugin/">maven-release-plugin</a>, you'll need <b>version 3.0.0-M1 or later</b>: it will automatically update the timestamp value in <code>pom.xml</code> during the release in the same commit that updates version,</li> +<li>if you have a custom release process tooling, you'll need to add the feature to your release tooling. Notice that if you're using <code>versions-maven-plugin</code> in custom release scripts, starting with release 2.9.0, <a class="externalLink" href="https://github.com/mojohaus/versions-maven-plugin/issues/453";><code>versions:set</code> goal updates the property</a>.</li> +<li>instead of explicitely writing a timestamp in their <code>pom.xml</code>, some people tend to prefer using last Git commit timestamp, like <code>${git.commit.time}</code> from <a class="externalLink" href="https://github.com/git-commit-id/git-commit-id-maven-plugin";>git-commit-id-maven-plugin</a>.</li></ul></li></ul> <p>Don't hesitate to share your questions or solutions on <a href="/mailing-lists.html">user mailing-list</a>.</p> <ul> - -<li> -<p>Q. Which additional plugins need to be updated for Reproducible Builds?</p> -<p>A. Here is a simplified list:</p></li> -</ul> -<table class="table table-striped"> -<thead> +<li>Q. Which additional plugins need to be updated for Reproducible Builds? +<p>A. Here is a simplified list:</p> +<table class="bodyTable bodyTableBorder"> <tr class="a"> -<th><strong>plugin</strong></th> -<th><strong>minimum version</strong></th> -<th><strong>comments</strong></th></tr></thead><tbody> +<td style="text-align: left;"><b>plugin</b></td> +<td style="text-align: left;"><b>minimum version</b></td> +<td style="text-align: left;"><b>comments</b></td></tr> <tr class="b"> -<td><a href="/plugins/maven-assembly-plugin/">maven-assembly-plugin</a></td> -<td colspan="2">3.2.0</td></tr> +<td style="text-align: left;"><a href="/plugins/maven-assembly-plugin/">maven-assembly-plugin</a></td> +<td style="text-align: left;">3.2.0</td> +<td style="text-align: left;"></td></tr> <tr class="a"> -<td><a href="/plugins/maven-jar-plugin/">maven-jar-plugin</a></td> -<td colspan="2">3.2.0</td></tr> +<td style="text-align: left;"><a href="/plugins/maven-jar-plugin/">maven-jar-plugin</a></td> +<td style="text-align: left;">3.2.0</td> +<td style="text-align: left;"></td></tr> <tr class="b"> -<td><a href="/plugins/maven-ejb-plugin/">maven-ejb-plugin</a></td> -<td colspan="2">3.1.0</td></tr> +<td style="text-align: left;"><a href="/plugins/maven-ejb-plugin/">maven-ejb-plugin</a></td> +<td style="text-align: left;">3.1.0</td> +<td style="text-align: left;"></td></tr> <tr class="a"> -<td><a href="/plugins/maven-javadoc-plugin/">maven-javadoc-plugin</a></td> -<td>3.2.0</td> -<td>requires also <code><notimestamp>true</notimestamp></code> configuration in <code>pluginManagement</code> (for automatic use both from plugins and reports)</td></tr> +<td style="text-align: left;"><a href="/plugins/maven-javadoc-plugin/">maven-javadoc-plugin</a></td> +<td style="text-align: left;">3.2.0</td> +<td style="text-align: left;">requires also <code><notimestamp>true</notimestamp></code> configuration in <code>pluginManagement</code> (for automatic use both from plugins and reports)</td></tr> <tr class="b"> -<td><a href="/plugin-tools/maven-plugin-plugin/">maven-plugin-plugin</a></td> -<td colspan="2">3.5.1</td></tr> +<td style="text-align: left;"><a href="/plugin-tools/maven-plugin-plugin/">maven-plugin-plugin</a></td> +<td style="text-align: left;">3.5.1</td> +<td style="text-align: left;"></td></tr> <tr class="a"> -<td><a href="/plugins/maven-remote-resources-plugin/">maven-remote-resources-plugin</a></td> -<td colspan="2">1.7.0</td></tr> +<td style="text-align: left;"><a href="/plugins/maven-remote-resources-plugin/">maven-remote-resources-plugin</a></td> +<td style="text-align: left;">1.7.0</td> +<td style="text-align: left;"></td></tr> <tr class="b"> -<td><a href="/plugins/maven-shade-plugin/">maven-shade-plugin</a></td> -<td colspan="2">3.2.3</td></tr> +<td style="text-align: left;"><a href="/plugins/maven-shade-plugin/">maven-shade-plugin</a></td> +<td style="text-align: left;">3.2.3</td> +<td style="text-align: left;"></td></tr> <tr class="a"> -<td><a href="/plugins/maven-site-plugin/">maven-site-plugin</a></td> -<td colspan="2">3.9.0</td></tr> +<td style="text-align: left;"><a href="/plugins/maven-site-plugin/">maven-site-plugin</a></td> +<td style="text-align: left;">3.9.0</td> +<td style="text-align: left;"></td></tr> <tr class="b"> -<td><a href="/plugins/maven-source-plugin/">maven-source-plugin</a></td> -<td colspan="2">3.2.1</td></tr> +<td style="text-align: left;"><a href="/plugins/maven-source-plugin/">maven-source-plugin</a></td> +<td style="text-align: left;">3.2.1</td> +<td style="text-align: left;"></td></tr> <tr class="a"> -<td><a href="/plugins/maven-war-plugin/">maven-war-plugin</a></td> -<td colspan="2">3.3.1</td></tr> +<td style="text-align: left;"><a href="/plugins/maven-war-plugin/">maven-war-plugin</a></td> +<td style="text-align: left;">3.3.1</td> +<td style="text-align: left;"></td></tr> <tr class="b"> -<td><a href="/plugins/maven-ear-plugin/">maven-ear-plugin</a></td> -<td colspan="2">3.1.0</td></tr> +<td style="text-align: left;"><a href="/plugins/maven-ear-plugin/">maven-ear-plugin</a></td> +<td style="text-align: left;">3.1.0</td> +<td style="text-align: left;"></td></tr> <tr class="a"> -<td><a href="https://codehaus-plexus.github.io/plexus-containers/plexus-component-metadata/"; class="externalLink">plexus-component-metadata</a></td> -<td colspan="2">2.1.0</td></tr> +<td style="text-align: left;"><a class="externalLink" href="https://codehaus-plexus.github.io/plexus-containers/plexus-component-metadata/";>plexus-component-metadata</a></td> +<td style="text-align: left;">2.1.0</td> +<td style="text-align: left;"></td></tr> <tr class="b"> -<td colspan="2"><a href="https://github.com/bndtools/bnd/tree/master/maven-plugins/bnd-maven-plugin"; class="externalLink">bnd-maven-plugin</a></td> -<td>see <a href="https://github.com/bndtools/bnd/tree/master/maven-plugins/bnd-maven-plugin#reproducible-builds"; class="externalLink">documentation</a></td></tr> +<td style="text-align: left;"><a class="externalLink" href="https://github.com/bndtools/bnd/tree/master/maven-plugins/bnd-maven-plugin";>bnd-maven-plugin</a></td> +<td style="text-align: left;"></td> +<td style="text-align: left;">see <a class="externalLink" href="https://github.com/bndtools/bnd/tree/master/maven-plugins/bnd-maven-plugin#reproducible-builds";>documentation</a></td></tr> <tr class="a"> -<td>Apache Felix <a href="https://felix.apache.org/documentation/subprojects/apache-felix-maven-bundle-plugin-bnd.html"; class="externalLink">maven-bundle-plugin</a></td> -<td colspan="2">5.1.3</td></tr> +<td style="text-align: left;">Apache Felix <a class="externalLink" href="https://felix.apache.org/documentation/subprojects/apache-felix-maven-bundle-plugin-bnd.html";>maven-bundle-plugin</a></td> +<td style="text-align: left;">5.1.3</td> +<td style="text-align: left;"></td></tr> <tr class="b"> -<td>Eclipse <a href="https://www.eclipse.org/sisu/docs/api/org.eclipse.sisu.mojos/"; class="externalLink">Sisu Maven Plugin</a></td> -<td colspan="2">0.3.4</td></tr> +<td style="text-align: left;">Eclipse <a class="externalLink" href="https://www.eclipse.org/sisu/docs/api/org.eclipse.sisu.mojos/";>Sisu Maven Plugin</a></td> +<td style="text-align: left;">0.3.4</td> +<td style="text-align: left;"></td></tr> <tr class="a"> -<td colspan="2"><a href="https://docs.spring.io/spring-boot/docs/current/maven-plugin/reference/htmlsingle/"; class="externalLink">springboot-maven-plugin</a></td> -<td>not reproducible</td></tr> +<td style="text-align: left;"><a class="externalLink" href="https://docs.spring.io/spring-boot/docs/current/maven-plugin/reference/htmlsingle/";>springboot-maven-plugin</a></td> +<td style="text-align: left;"></td> +<td style="text-align: left;">not reproducible</td></tr> <tr class="b"> -<td>MojoHaus <a href="https://www.mojohaus.org/properties-maven-plugin/"; class="externalLink">properties-maven-plugin</a></td> -<td colspan="2">1.1.0</td></tr></tbody> -</table> - -<p>For more details, see <a href="https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=74682318#Reproducible/VerifiableBuilds-Whataretheissuestosolve?"; class="externalLink">Maven “Reproducible/Verifiable Builds” Wiki page</a></p></section></section></section> +<td style="text-align: left;">MojoHaus <a class="externalLink" href="https://www.mojohaus.org/properties-maven-plugin/";>properties-maven-plugin</a></td> +<td style="text-align: left;">1.1.0</td> +<td style="text-align: left;"></td></tr></table> +<p>For more details, see <a class="externalLink" href="https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=74682318#Reproducible/VerifiableBuilds-Whataretheissuestosolve?";>Maven "Reproducible/Verifiable Builds" Wiki page</a></p></li></ul></section></section> </main> </div> </div>
Modified: maven/website/content/guides/mini/guide-site.html ============================================================================== --- maven/website/content/guides/mini/guide-site.html (original) +++ maven/website/content/guides/mini/guide-site.html Sat Feb 18 20:40:58 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/mini/guide-site.md at 2023-02-18 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-site.apt at 2023-02-18 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -10,7 +10,8 @@ <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M4" /> - <meta name="author" content="Brett Porter, Jason van Zyl" /> + <meta name="author" content="Brett Porter +Jason van Zyl" /> <meta name="date" content="2015-07-18" /> <title>Maven – Guide to creating a site</title> <link rel="stylesheet" href="../../css/apache-maven-fluido-1.11.1.min.css" /> @@ -48,7 +49,7 @@ <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Guide to creating a site <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/mini/guide-site.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li class="active ">Guide to creating a site <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/mini/guide-site.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-18</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> @@ -141,30 +142,12 @@ </div> </header> <main id="bodyColumn" class="span10" > -<!-- -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. ---> -<section><section> -<h2>Creating a site</h2><section> -<h3>Creating Content</h3> +<section> +<h1>Creating a site</h1><section> +<h2>Creating Content</h2> <p>The first step to creating your site is to create some content. In Maven, the site content is separated by format, as there are several available.</p> - -<div class="source"><pre class="prettyprint linenums"><code>+- src/ +<div> +<pre>+- src/ +- site/ +- apt/ | +- index.apt @@ -179,42 +162,30 @@ under the License. +- xdoc/ | +- other.xml | - +- site.xml -</code></pre></div> + +- site.xml</pre></div> <p>You will notice there is now a <code>${basedir}/src/site</code> directory within which is contained a <code>site.xml</code> site descriptor along with various directories corresponding to the supported document types.</p> <p>Let's take a look at the examples of the various document types:</p> <ul> - -<li> -<p><code>apt</code>: the APT format, “Almost Plain Text”, is a wiki-like format that allows you to write simple, structured documents (like this one) very quickly. A full reference of the <a href="/doxia/references/apt-format.html">APT Format</a> is available,</p></li> -<li> -<p><code>markdown</code>: the well known <a href="https://en.wikipedia.org/wiki/Markdown"; class="externalLink">Markdown</a> format,</p></li> -<li> -<p><code>fml</code>: the FML format is the <a href="/doxia/references/fml-format.html">FAQ format</a>,</p></li> -<li> -<p><code>xdoc</code>: an XML document conforming to a small and simple set of tags, see the <a href="/doxia/references/xdoc-format.html">full reference</a>.</p></li> -</ul> +<li><code>apt</code>: the APT format, "Almost Plain Text", is a wiki-like format that allows you to write simple, structured documents (like this one) very quickly. A full reference of the <a href="/doxia/references/apt-format.html">APT Format</a> is available,</li> +<li><code>markdown</code>: the well known <a class="externalLink" href="https://en.wikipedia.org/wiki/Markdown";>Markdown</a> format,</li> +<li><code>fml</code>: the FML format is the <a href="/doxia/references/fml-format.html">FAQ format</a>,</li> +<li><code>xdoc</code>: an XML document conforming to a small and simple set of tags, see the <a href="/doxia/references/xdoc-format.html">full reference</a>.</li></ul> <p>Other formats are available, but at this point these 4 are the best tested.</p> <p>There are also several possible output formats, but as of Maven Site Plugin, only XHTML is available.</p> <p>Note that all of the above is optional - just one index file is required in one of the input trees. Each of the paths will be merged together to form the root directory of the site.</p></section><section> -<h3>Customizing the Look & Feel</h3> -<p>If you want to tune the way your site looks, you can use a custom <strong>skin</strong> to provide your own CSS styles. If that is still not enough, you can even tweak the output templates that Maven uses to generate the site documentation.</p> -<p>You can visit the <a href="/skins/">Skins index</a> to have a look at some of the skins that you can use to change the look of your site.</p><!-- TODO: The following link is currently not available. Restore it when it becomes available again. --> -<!-- For an in-depth discussion of site customization, please have a look at the --> -<!-- {{{http://www.sonatype.com/book/site-generation.html} Maven User Guide, Chapter 9, "Site Generation"}}. --> -</section><section> -<h3>Generating the Site</h3> +<h2>Customizing the Look & Feel</h2> +<p>If you want to tune the way your site looks, you can use a custom <b>skin</b> to provide your own CSS styles. If that is still not enough, you can even tweak the output templates that Maven uses to generate the site documentation.</p> +<p>You can visit the <a href="/skins/">Skins index</a> to have a look at some of the skins that you can use to change the look of your site.</p></section><section> +<h2>Generating the Site</h2> <p>Generating the site is very simple, and fast!</p> - -<div class="source"><pre class="prettyprint linenums"><code>mvn site -</code></pre></div> +<div> +<pre>mvn site</pre></div> <p>By default, the resulting site will be in <code>target/site/...</code></p> -<p>For more information on the Maven Site Plugin, see the <a href="../../plugins/maven-site-plugin/">maven-site-plugin reference</a>.</p></section><section> -<h3>Deploying the Site</h3><section> -<h4>Classical Website deployment</h4> +<p>For more information on the Maven Site Plugin, see the <a href="../../plugins/maven-site-plugin/"> maven-site-plugin reference</a>.</p></section><section> +<h2>Deploying the Site</h2><section> +<h3>Classical Website deployment</h3> <p>To be able to deploy the site with a classical network protocol (ftp, scp, webdav), you must first declare a location to distribute to in your <code>pom.xml</code>, similar to the repository for deployment:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><project> +<div class="source"><pre class="prettyprint linenums"><project> ... <distributionManagement> <site> @@ -223,24 +194,17 @@ under the License. </site> </distributionManagement> ... -</project> -</code></pre></div> +</project></pre></div> <ul> - -<li> -<p>the <code><id></code> element identifies the repository, so that you can attach credentials to it in your <code>settings.xml</code> file using the <a href="../../settings.html#Servers"><code><servers></code> element</a> as you would for any other repository,</p></li> -<li> -<p>the <code><url></code> gives the location to deploy to. Currently, only SSH is supported by default, as above which copies to the host <code>www.mycompany.com</code> in the path <code>/www/docs/project/</code>, but you can <a href="/plugins/maven-site-plugin/examples/adding-deploy-protocol.html">add more protocols as required</a>. If subprojects inherit the site URL from a parent POM, they will automatically get their <code><artifactId></code> appended to form their effective deployment location.</p></li> -</ul> +<li>the <code><id></code> element identifies the repository, so that you can attach credentials to it in your <code>settings.xml</code> file using the <a href="../../settings.html#Servers"> <code><servers></code> element</a> as you would for any other repository,</li> +<li>the <code><url></code> gives the location to deploy to. Currently, only SSH is supported by default, as above which copies to the host <code>www.mycompany.com</code> in the path <code>/www/docs/project/</code>, but you can <a href="/plugins/maven-site-plugin/examples/adding-deploy-protocol.html">add more protocols as required</a>. If subprojects inherit the site URL from a parent POM, they will automatically get their <code><artifactId></code> appended to form their effective deployment location.</li></ul> <p>Once distribution location is configured, deploying the site is done by using the <code>site-deploy</code> phase of the site lifecycle.</p> - -<div class="source"><pre class="prettyprint linenums"><code>mvn site-deploy -</code></pre></div></section><section> -<h4>GitHub Pages, Apache svnpubsub/gitpubsub Deployment</h4> -<p>When site publication is done with a SCM commit, like with <a href="https://pages.github.com/"; class="externalLink">GitHub Pages</a> or <a href="https://infra.apache.org/project-site.html#tools"; class="externalLink">Apache svnpubsub/gitpubsub</a>, deploying the site will be done with <a href="/plugins/maven-scm-publish-plugin/">Maven SCM Publish Plugin</a>.</p> +<div> +<pre>mvn site-deploy</pre></div></section><section> +<h3>GitHub Pages, Apache svnpubsub/gitpubsub Deployment</h3> +<p>When site publication is done with a SCM commit, like with <a class="externalLink" href="https://pages.github.com/";>GitHub Pages</a> or <a class="externalLink" href="https://infra.apache.org/project-site.html#tools";>Apache svnpubsub/gitpubsub</a>, deploying the site will be done with <a href="/plugins/maven-scm-publish-plugin/">Maven SCM Publish Plugin</a>. </p> <p>For example with a project hosted on GitHub and using GitHub Pages for its site publication:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"> <plugin> +<div class="source"><pre class="prettyprint linenums"> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-scm-publish-plugin</artifactId> <version>3.1.0</version> @@ -248,15 +212,14 @@ under the License. <pubScmUrl>${project.scm.developerConnection}</pubScmUrl> <scmBranch>gh-pages</scmBranch> </configuration> - </plugin> -</code></pre></div> + </plugin></pre></div> <p>Deploying the site is done in 2 steps:</p> -<p>1 staging the content by using the <code>site</code> phase of the site lifecycle followed by <code>site:stage</code>: <code>mvn site site:stage</code></p> -<p>1 publishing the staged site to the SCM: <code>mvn scm-publish:publish-scm</code></p></section></section><section> -<h3>Creating a Site Descriptor</h3> +<ol style="list-style-type: decimal"> +<li>staging the content by using the <code>site</code> phase of the site lifecycle followed by <code>site:stage</code>: <code>mvn site site:stage</code></li> +<li>publishing the staged site to the SCM: <code>mvn scm-publish:publish-scm</code></li></ol></section></section><section> +<h2>Creating a Site Descriptor</h2> <p>The <code>site.xml</code> file is used to describe the structure of the site. A sample is given below:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><?xml version="1.0" encoding="ISO-8859-1"?> +<div class="source"><pre class="prettyprint linenums"><?xml version="1.0" encoding="ISO-8859-1"?> <project xmlns="http://maven.apache.org/DECORATION/1.8.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/DECORATION/1.8.0 https://maven.apache.org/xsd/decoration-1.8.0.xsd" name="Maven"> @@ -289,49 +252,36 @@ under the License. ... </body> -</project> -</code></pre></div><!-- TODO: deserves more explanation. --> - -<p><strong>Note:</strong> The <code><menu ref="reports"></code> element above. When building the site, this is replaced by a menu with links to all the reports that you have configured.</p> +</project></pre></div> +<p><b>Note:</b> The <code><menu ref="reports"/></code> element above. When building the site, this is replaced by a menu with links to all the reports that you have configured.</p> <p>More information about the site descriptor is available at the <a href="/plugins/maven-site-plugin/examples/sitedescriptor.html">dedicated page of Maven Site Plugin</a>.</p></section><section> -<h3>Adding Extra Resources</h3> +<h2>Adding Extra Resources</h2> <p>You can add any arbitrary resource to your site by including them in a <code>resources</code> directory as shown below. Additional CSS files will be picked up when they are placed in the <code>css</code> directory within the <code>resources</code> directory.</p> - -<div class="source"><pre class="prettyprint linenums"><code>+- src/ +<div> +<pre>+- src/ +- site/ +- resources/ +- css/ | +- site.css | +- images/ - +- pic1.jpg -</code></pre></div> + +- pic1.jpg</pre></div> <p>The file <code>site.css</code> will be added to the default XHTML output, so it can be used to adjust the default Maven stylesheets if desired.</p> <p>The file <code>pic1.jpg</code> will be available via a relative reference to the <code>images</code> directory from any page in your site.</p></section><section> -<h3>Configuring Reports</h3> +<h2>Configuring Reports</h2> <p>Maven has several reports that you can add to your web site to display the current state of the project. These reports take the form of plugins, just like those used to build the project.</p> <p>There are many standard reports that are available by gleaning information from the POM. Currently what is provided by default are:</p> <ul> - -<li> -<p>Dependencies Report</p></li> -<li> -<p>Mailing Lists</p></li> -<li> -<p>Continuous Integration</p></li> -<li> -<p>Source Repository</p></li> -<li> -<p>Issue Tracking</p></li> -<li> -<p>Project Team</p></li> -<li> -<p>License</p></li> -</ul> +<li>Dependencies Report</li> +<li>Mailing Lists</li> +<li>Continuous Integration</li> +<li>Source Repository</li> +<li>Issue Tracking</li> +<li>Project Team</li> +<li>License</li></ul> <p>To find out more please refer to the <a href="../../plugins/maven-project-info-reports-plugin/">Project Info Reports Plugin</a>.</p> <p>To add these reports to your site, you must add the Project Info Reports plugin to a special <code><reporting></code> section in the POM. The following example shows how to configure the standard project information reports that display information from the POM in a friendly format:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><project> +<div class="source"><pre class="prettyprint linenums"><project> ... <reporting> <plugins> @@ -343,17 +293,14 @@ under the License. </plugins> </reporting> ... -</project> -</code></pre></div> -<p>If you have included the appropriate <code><menu ref="reports"></code> tag in your <code>site.xml</code> descriptor, then when you regenerate the site those items will appear in the menu.</p> -<p>Many other plugins provide reporting goals: look for “R” (Reporting) value in the “Type” column of the <a href="/plugins/">list of plugins</a>. When plugins are both Build and Reporting plugins, defining explicitely the version in the reporting section is usually not necessary since reporting will use the version from <code>build/plugins</code> or <code>build/pluginManagement</code>. Since Maven Site Plugin 3.4, reporting plugin also get configuration from <code>build/pluginManagement</code>.</p> -<p><strong>Note:</strong> Many report plugins provide a parameter called <code>outputDirectory</code> or similar to specify the destination for their report outputs. This parameter is only relevant if the report plugin is run standalone, i.e. by invocation directly from the command line. In contrast, when reports are generated as part of the site, the configuration of the Maven Site Plugin will determine the effective output directory to ensure that all reports end up in a central location.</p><!-- TODO: explain report sets --> -</section><section> -<h3>Internationalization</h3> -<p>Internationalization in Maven is very simple, as long as the reports you are using have that particular locale defined. For an overview of supported languages and instructions on how to add further languages, please see the related article <a href="../../plugins/maven-site-plugin/i18n.html">Internationalization</a> from the Maven Site Plugin.</p> +</project></pre></div> +<p>If you have included the appropriate <code><menu ref="reports"/></code> tag in your <code>site.xml</code> descriptor, then when you regenerate the site those items will appear in the menu.</p> +<p>Many other plugins provide reporting goals: look for "R" (Reporting) value in the "Type" column of the <a href="/plugins/"> list of plugins</a>. When plugins are both Build and Reporting plugins, defining explicitely the version in the reporting section is usually not necessary since reporting will use the version from <code>build/plugins</code> or <code>build/pluginManagement</code>. Since Maven Site Plugin 3.4, reporting plugin also get configuration from <code>build/pluginManagement</code>.</p> +<p><b>Note:</b> Many report plugins provide a parameter called <code>outputDirectory</code> or similar to specify the destination for their report outputs. This parameter is only relevant if the report plugin is run standalone, i.e. by invocation directly from the command line. In contrast, when reports are generated as part of the site, the configuration of the Maven Site Plugin will determine the effective output directory to ensure that all reports end up in a central location.</p></section><section> +<h2>Internationalization</h2> +<p>Internationalization in Maven is very simple, as long as the reports you are using have that particular locale defined. For an overview of supported languages and instructions on how to add further languages, please see the related article <a href="../../plugins/maven-site-plugin/i18n.html"> Internationalization</a> from the Maven Site Plugin.</p> <p>To enable multiple locales, add a configuration similar to the following to your POM:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><project> +<div class="source"><pre class="prettyprint linenums"><project> ... <build> <plugins> @@ -368,12 +315,11 @@ under the License. </plugins> </build> ... -</project> -</code></pre></div> +</project></pre></div> <p>This will generate both an English and a French version of the site. If <code>en</code> is your current locale, then it will be generated at the root of the site, with a copy of the French translation of the site in the <code>fr/</code> subdirectory.</p> <p>To add your own content for that translation instead of using the default, place a subdirectory with that locale name in your site directory and create a new site descriptor with the locale in the file name. For example:</p> - -<div class="source"><pre class="prettyprint linenums"><code>+- src/ +<div> +<pre>+- src/ +- site/ +- apt/ | +- index.apt (Default version) @@ -383,9 +329,8 @@ under the License. | +- index.apt (French version) | +- site.xml (Default site descriptor) - +- site_fr.xml (French site descriptor) -</code></pre></div> -<p>With one site descriptor per language, the translated site(s) can evolve independently.</p></section></section></section> + +- site_fr.xml (French site descriptor)</pre></div> +<p>With one site descriptor per language, the translated site(s) can evolve independently.</p></section></section> </main> </div> </div> Modified: maven/website/content/guides/mini/guide-snippet-macro.html ============================================================================== --- maven/website/content/guides/mini/guide-snippet-macro.html (original) +++ maven/website/content/guides/mini/guide-snippet-macro.html Sat Feb 18 20:40:58 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/mini/guide-snippet-macro.md at 2023-02-18 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-snippet-macro.apt at 2023-02-18 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -48,7 +48,7 @@ <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Guide to the Snippet Macro <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/mini/guide-snippet-macro.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li class="active ">Guide to the Snippet Macro <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/mini/guide-snippet-macro.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-18</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> @@ -141,46 +141,24 @@ </div> </header> <main id="bodyColumn" class="span10" > -<!-- -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. ---> -<!-- @todo dennisl: We should drop this document and refer to the macros page in the Doxia site --> -<section><section> -<h2>Guide to the Snippet Macro</h2> -<p>When generating your project website with Maven, you have the option of dynamically including _snippet_s of source code in your pages.</p> -<p>A <em>snippet</em> is a section of a source code file that is surrounded by specially formatted comments.</p> -<p>This functionality is inspired by the <a href="http://www.atlassian.com/software/confluence/"; class="externalLink">Confluence</a> snippet macro, and is provided by the Maven Doxia project by way of the Maven Site Plugin.</p> +<section> +<h1>Guide to the Snippet Macro</h1> +<p>When generating your project website with Maven, you have the option of dynamically including <i>snippet</i>s of source code in your pages.</p> +<p>A <i>snippet</i> is a section of a source code file that is surrounded by specially formatted comments.</p> +<p>This functionality is inspired by the <a class="externalLink" href="http://www.atlassian.com/software/confluence/";>Confluence</a> snippet macro, and is provided by the Maven Doxia project by way of the Maven Site Plugin.</p> <p>To include snippets of source code in your documentation, first add comments in the source document surrounding the lines you want to include, and then refer to the snippet by its id in the documentation file. Each snippet must be assigned an id, and the id must be unique within the source document. The id parameter is not required if you want to include the entire file.</p> <p>Following are examples of snippets in various source documents, as well as the corresponding macros in the APT documentation format.</p> -<p>See the Doxia <a href="/doxia/macros/index.html#snippet-macro">Macros Guide</a> for more information and examples.</p><section> -<h3>Snippets in Sources</h3><section> -<h4>Java</h4> - -<div class="source"><pre class="prettyprint linenums"><code class="language-java"> // START SNIPPET: snip-id +<p>See the Doxia <a href="/doxia/macros/index.html#Snippet_Macro">Macros Guide</a> for more information and examples.</p><section> +<h2>Snippets in Sources</h2><section> +<h3>Java</h3> +<div class="source"><pre class="prettyprint linenums"> // START SNIPPET: snip-id public static void main( String[] args ) { System.out.println( "Hello World!" ); } - // END SNIPPET: snip-id -</code></pre></div></section><section> -<h4>XML</h4> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"> <!-- START SNIPPET: snip-id --> + // END SNIPPET: snip-id</pre></div></section><section> +<h3>XML</h3> +<div class="source"><pre class="prettyprint linenums"> <!-- START SNIPPET: snip-id --> <navigation-rule> <from-view-id>/logon.jsp</from-view-id> <navigation-case> @@ -188,36 +166,25 @@ under the License. <to-view-id>/mainMenu.jsp</to-view-id> </navigation-case> </navigation-rule> - <!-- END SNIPPET: snip-id --> -</code></pre></div></section><section> -<h4>JSP</h4> - -<div class="source"><pre class="prettyprint linenums"><code> <%-- START SNIPPET: snip-id --%> + <!-- END SNIPPET: snip-id --></pre></div></section><section> +<h3>JSP</h3> +<div class="source"><pre class="prettyprint linenums"> <%-- START SNIPPET: snip-id --%> <ul> <li><a href="newPerson!input.action">Create</a> a new person</li> <li><a href="listPeople.action">List</a> all people</li> </ul> - <%-- END SNIPPET: snip-id --%> -</code></pre></div></section></section><section> -<h3>Snippets in Documentation</h3><section> -<h4>APT</h4> - -<div class="source"><pre class="prettyprint linenums"><code> %{snippet|id=snip-id|url=http://svn.example.com/path/to/Sample.java} - - %{snippet|id=snip-id|url=file:///path/to/Sample.java} -</code></pre></div> -<p>As of doxia-core version 1.0-alpha-9, a ‘file’ parameter is also available. If a full path is not specified, the location is assumed to be relative to <code>${basedir}</code>.</p> - -<div class="source"><pre class="prettyprint linenums"><code> ~~ Since doxia-core 1.0-alpha-9 - %{snippet|id=abc|file=src/main/webapp/index.jsp} -</code></pre></div> + <%-- END SNIPPET: snip-id --%></pre></div></section></section><section> +<h2>Snippets in Documentation</h2><section> +<h3>APT</h3> +<div class="source"><pre class="prettyprint linenums"> %{snippet|id=snip-id|url=http://svn.example.com/path/to/Sample.java} + + %{snippet|id=snip-id|url=file:///path/to/Sample.java}</pre></div> +<p>As of doxia-core version 1.0-alpha-9, a 'file' parameter is also available. If a full path is not specified, the location is assumed to be relative to ${basedir}.</p> +<div class="source"><pre class="prettyprint linenums"> ~~ Since doxia-core 1.0-alpha-9 + %{snippet|id=abc|file=src/main/webapp/index.jsp}</pre></div> <ul> - -<li> -<p>Macros in apt <strong>must not</strong> be indented.</p></li> -<li> -<p>Exactly one of <code>url</code> or <code>file</code> <strong>must</strong> be specified.</p></li> -</ul></section></section></section></section> +<li>Macros in apt <b>must not</b> be indented.</li> +<li>Exactly one of <code>url</code> or <code>file</code> <b>must</b> be specified.</li></ul></section></section></section> </main> </div> </div> Modified: maven/website/content/guides/mini/guide-using-ant.html ============================================================================== --- maven/website/content/guides/mini/guide-using-ant.html (original) +++ maven/website/content/guides/mini/guide-using-ant.html Sat Feb 18 20:40:58 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/mini/guide-using-ant.md at 2023-02-18 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-using-ant.apt at 2023-02-18 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -48,7 +48,7 @@ <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Guide to using Ant with Maven <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/mini/guide-using-ant.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li class="active ">Guide to using Ant with Maven <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/mini/guide-using-ant.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-18</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> @@ -154,29 +154,10 @@ </div> </header> <main id="bodyColumn" class="span10" > -<!-- -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. ---> -<section><section> -<h2>Guide to using Ant with Maven</h2> -<p>The example above illustrates how to bind an ant script to a lifecycle phase. You can add a script to each lifecycle phase, by duplicating the <em>execution/</em> section and specifying a new phase.</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"> +<section> +<h1>Guide to using Ant with Maven</h1> +<p>The example above illustrates how to bind an ant script to a lifecycle phase. You can add a script to each lifecycle phase, by duplicating the <i>execution/</i> section and specifying a new phase.</p> +<div class="source"><pre class="prettyprint linenums"> <project> <modelVersion>4.0.0</modelVersion> <artifactId>my-test-app</artifactId> @@ -210,11 +191,9 @@ under the License. </plugins> </build> </project> - -</code></pre></div> +</pre></div> <p>So a concrete example would be something like the following:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"> +<div class="source"><pre class="prettyprint linenums"> <project> <modelVersion>4.0.0</modelVersion> <artifactId>my-test-app</artifactId> @@ -247,8 +226,7 @@ under the License. </plugins> </build> </project> - -</code></pre></div></section></section> +</pre></div></section> </main> </div> </div> Modified: maven/website/content/guides/mini/guide-using-extensions.html ============================================================================== --- maven/website/content/guides/mini/guide-using-extensions.html (original) +++ maven/website/content/guides/mini/guide-using-extensions.html Sat Feb 18 20:40:58 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/mini/guide-using-extensions.md at 2023-02-18 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-using-extensions.apt at 2023-02-18 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -10,7 +10,8 @@ <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M4" /> - <meta name="author" content="Jason van Zyl, Konrad Windszus" /> + <meta name="author" content="Jason van Zyl +Konrad Windszus" /> <meta name="date" content="2022-11-16" /> <title>Maven – Guide to using Extensions</title> <link rel="stylesheet" href="../../css/apache-maven-fluido-1.11.1.min.css" /> @@ -48,7 +49,7 @@ <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Guide to using Extensions <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/mini/guide-using-extensions.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li class="active ">Guide to using Extensions <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/mini/guide-using-extensions.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-18</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> @@ -154,50 +155,23 @@ </div> </header> <main id="bodyColumn" class="span10" > -<!-- -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. ---> -<section><section> -<h2>Using Extensions</h2> -<p>Extensions are a way to add classes to either the <a href="./guide-maven-classloading.html#core-classloader">Core Classloader</a> (Core Extensions) or the <a href="./guide-maven-classloading.html#Project_Classloaders">Project Classloader</a> (Build Extensions). This is necessary for adjusting Maven in a way that affects more than just one plug-in.</p> -<p>The mechanism allows extensions to either replace default <a href="https://www.eclipse.org/sisu/"; class="externalLink">Sisu components</a> with custom ones or add new components which are used at run time. In addition one could also expose additional packages from the Core Classloader.</p> +<section> +<h1>Using Extensions</h1> +<p>Extensions are a way to add classes to either the <a href="./guide-maven-classloading.html#Core_Classloader">Core Classloader</a> (Core Extensions) or the <a href="./guide-maven-classloading.html#Project_Classloaders">Project Classloader</a> (Build Extensions). This is necessary for adjusting Maven in a way that affects more than just one plug-in.</p> +<p>The mechanism allows extensions to either replace default <a class="externalLink" href="https://www.eclipse.org/sisu/";>Sisu components</a> with custom ones or add new components which are used at run time. In addition one could also expose additional packages from the Core Classloader.</p> <p>Extensions are typically used to enable <a href="../../wagon/wagon-providers/">Wagon providers</a>, used for the transport of artifact between repositories, and plug-ins which <a href="../../examples/maven-3-lifecycle-extensions.html">provide lifecycle enhancements</a>.</p><section> -<h3>Loading Extensions</h3> -<p>There are different means of loading extensions depending on the type. There are <em>core extensions</em> which are loaded <strong>early</strong> and build extensions which are loaded <strong>late</strong>. Some extensions require early loading as they fundamentally change Maven behaviour. An extension's documentation should indicate whether it provides a core or a build extension.</p><section> -<h4>Core Extension</h4> +<h2>Loading Extensions</h2> +<p>There are different means of loading extensions depending on the type. There are <i>core extensions</i> which are loaded <b>early</b> and build extensions which are loaded <b>late</b>. Some extensions require early loading as they fundamentally change Maven behaviour. An extension's documentation should indicate whether it provides a core or a build extension.</p><section> +<h3>Core Extension</h3> <ul> - -<li> -<p>Registered via extension jar in <code>${maven.home}/lib/ext</code></p></li> -<li> -<p>Registered via CLI argument <code>mvn -Dmaven.ext.class.path=extension.jar</code></p></li> -<li> -<p>Registered via <a href="../../configure.html#mvn-extensions-xml-file"><code>.mvn/extensions.xml</code> file</a></p></li> -</ul></section><section> -<h4>Build Extension</h4> +<li>Registered via extension jar in <code>${maven.home}/lib/ext</code></li> +<li>Registered via CLI argument <code>mvn -Dmaven.ext.class.path=extension.jar</code></li> +<li>Registered via <a href="../../configure.html#mvn-extensions-xml-file"><code>.mvn/extensions.xml</code> file</a></li></ul></section><section> +<h3>Build Extension</h3> <ul> - -<li> -<p>Registered via <a href="../../pom.html#plugins"><code>project-\>build-\>plugins-\>plugin</code></a> with element <code>extensions</code> being set to <code>true</code>. This is useful for regular plug-ins carrying some extensions.</p> -<p>Example:</p></li> -</ul> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"> +<li>Registered via <a href="../../pom.html#Plugins"><code>project->build->plugins->plugin</code></a> with element <code>extensions</code> being set to <code>true</code>. This is useful for regular plug-ins carrying some extensions. +<p>Example:</p> +<div class="source"><pre class="prettyprint linenums"> <project> ... <build> @@ -214,16 +188,10 @@ under the License. </build> ... </project> - -</code></pre></div> -<ul> - -<li> -<p>Registered as build extension in <a href="../../pom.html#extensions"><code>project-\>build-\>extensions-\>extension</code></a></p> -<p>Example:</p></li> -</ul> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"> +</pre></div></li> +<li>Registered as build extension in <a href="../../pom.html#Extensions"><code>project->build->extensions->extension</code></a> +<p>Example:</p> +<div class="source"><pre class="prettyprint linenums"> <project> ... <build> @@ -237,8 +205,7 @@ under the License. </build> ... </project> - -</code></pre></div></section></section></section></section> +</pre></div></li></ul></section></section></section> </main> </div> </div> Modified: maven/website/content/guides/mini/guide-using-modello.html ============================================================================== --- maven/website/content/guides/mini/guide-using-modello.html (original) +++ maven/website/content/guides/mini/guide-using-modello.html Sat Feb 18 20:40:58 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/mini/guide-using-modello.md at 2023-02-18 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-using-modello.apt at 2023-02-18 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -10,7 +10,8 @@ <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M4" /> - <meta name="author" content="Jason van Zyl, Hervé Boutemy" /> + <meta name="author" content="Jason van Zyl +Hervé Boutemy" /> <meta name="date" content="2009-03-01" /> <title>Maven – Guide to using Modello</title> <link rel="stylesheet" href="../../css/apache-maven-fluido-1.11.1.min.css" /> @@ -48,7 +49,7 @@ <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Guide to using Modello <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/mini/guide-using-modello.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li class="active ">Guide to using Modello <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/mini/guide-using-modello.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-18</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> @@ -154,43 +155,17 @@ </div> </header> <main id="bodyColumn" class="span10" > -<!-- -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. ---> -<section><section> -<h2>Guide to using Modello</h2> -<p><a href="https://codehaus-plexus.github.io/modello/"; class="externalLink">Modello</a> is a tool for generating resources from a simple model. From a <a href="https://codehaus-plexus.github.io/modello/modello.html"; class="externalLink">simple model</a> you can generate things like:</p> +<section> +<h1>Guide to using Modello</h1> +<p><a class="externalLink" href="https://codehaus-plexus.github.io/modello/";>Modello</a> is a tool for generating resources from a simple model. From a <a class="externalLink" href="https://codehaus-plexus.github.io/modello/modello.html";>simple model</a> you can generate things like:</p> <ul> - -<li> -<p>Java sources</p></li> -<li> -<p>XML serialization code for the model</p></li> -<li> -<p>XML deserialization code for model</p></li> -<li> -<p>Model documentation</p></li> -<li> -<p>XSD</p></li> -</ul> +<li>Java sources</li> +<li>XML serialization code for the model</li> +<li>XML deserialization code for model</li> +<li>Model documentation</li> +<li>XSD</li></ul> <p>A typical modello model looks like the following:</p> - -<div class="source"><pre class="prettyprint linenums"><code><model xmlns="https://codehaus-plexus.github.io/MODELLO/1.8.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" +<div class="source"><pre class="prettyprint linenums"><model xmlns="https://codehaus-plexus.github.io/MODELLO/1.8.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://codehaus-plexus.github.io/MODELLO/1.8.0 https://codehaus-plexus.github.io/modello/xsd/modello-1.8.0.xsd" xml.namespace="https://maven.apache.org/plugins/maven-archetype-plugin/archetype-descriptor/${version}" xml.schemaLocation="http://maven.apache.org/xsd/archetype-descriptor-${version}.xsd"> @@ -413,11 +388,9 @@ under the License. </class> </classes> </model> - -</code></pre></div> -<p>To utilize Modello, you would configure the <code>modello-maven-plugin</code> something like the following where you want to generate the Java sources for the model, the xpp3 serialization code and the xpp3 deserialization code (see <a href="https://codehaus-plexus.github.io/modello/modello-plugins/modello-plugin-xpp3/"; class="externalLink">modello-plugin-xpp3</a> for more details):</p> - -<div class="source"><pre class="prettyprint linenums"><code> +</pre></div> +<p>To utilize Modello, you would configure the <code>modello-maven-plugin</code> something like the following where you want to generate the Java sources for the model, the xpp3 serialization code and the xpp3 deserialization code (see <a class="externalLink" href="https://codehaus-plexus.github.io/modello/modello-plugins/modello-plugin-xpp3/";>modello-plugin-xpp3</a> for more details):</p> +<div class="source"><pre class="prettyprint linenums"> <project> ... <build> @@ -450,8 +423,7 @@ under the License. </build> ... </project> - -</code></pre></div></section></section> +</pre></div></section> </main> </div> </div> Modified: maven/website/content/guides/mini/guide-using-one-source-directory.html ============================================================================== --- maven/website/content/guides/mini/guide-using-one-source-directory.html (original) +++ maven/website/content/guides/mini/guide-using-one-source-directory.html Sat Feb 18 20:40:58 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/mini/guide-using-one-source-directory.md at 2023-02-18 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-using-one-source-directory.apt at 2023-02-18 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -48,7 +48,7 @@ <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Guide to Using Maven when You Can't Use the Conventions <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/mini/guide-using-one-source-directory.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li class="active ">Guide to Using Maven when You Can't Use the Conventions <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/mini/guide-using-one-source-directory.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-18</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> @@ -123,59 +123,34 @@ </div> </header> <main id="bodyColumn" class="span10" > -<!-- -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. ---> -<section><section> -<h2>Using Maven When You Can't Use the Conventions</h2> +<section> +<h1>Using Maven When You Can't Use the Conventions</h1> <p>There is a common misconception that Maven can't build a project that doesn't conform to certain directory structures or build practices. This often isn't the case. However, it is true that some Maven features or plugins (especially by third parties) may not work or work completely.</p> <p>This guide will help you set up Maven on your project when the directive from on high is to not change the existing layout, and detail some of the feature that you might miss when doing so.</p> <p>Use this as a last resort. There are good reasons why the defaults are the way they are, and we strongly recommend you use them if you can. It encourages consistency and means one less thing you ever need to worry about when starting a new project. There are more interesting things to do than change your layout for the sake of it. Hopefully having used any of these techniques you find that Maven proves itself capable, you will reconsider restructuring to address these issues.></p><section> -<h3>Using Multiple Source Directories</h3> +<h2>Using Multiple Source Directories</h2> <p>This occurs when you are producing a single JAR (or other artifact), and have several source directories with classes you want to include.</p><section> -<h4>Why isn't this recommended?</h4> -<p>…</p><!-- TODO --> -</section><section> -<h4>How do I do this?</h4> -<p>…</p><!-- TODO --> -</section><section> -<h4>What are the limitations?</h4> +<h3>Why isn't this recommended?</h3> +<p>...</p></section><section> +<h3>How do I do this?</h3> +<p>...</p></section><section> +<h3>What are the limitations?</h3> <p>There should be no limitations in this approach. Maven natively supports multiple source directories for the purposes of generated sources.</p></section></section><section> -<h3>Producing Multiple Unique JARs from a Single Source Directory</h3> +<h2>Producing Multiple Unique JARs from a Single Source Directory</h2> <p>As many people that complain about not being able to spread out their sources into multiple source directories seem to complain about not wanting to spread anything out, producing several unique artifacts from a single directory using includes and excludes.</p><section> -<h4>Why isn't this recommended?</h4> +<h3>Why isn't this recommended?</h3> <p>This practice can be confusing and risky.</p> <ul> - -<li> -<p>You may end up building two JARs that include the same classes - this indicates that the common functionality should have been abstracted into a separate dependency.</p></li> -<li> -<p>You may end up introducing a dependency between the two JARs that you didn't realise, and often a circular dependency. This indicates that the classes are in the wrong JAR, or perhaps that everything should just be a single JAR.</p></li> -</ul></section><section> -<h4>How do I do this?</h4> +<li>You may end up building two JARs that include the same classes - this indicates that the common functionality should have been abstracted into a separate dependency.</li> +<li>You may end up introducing a dependency between the two JARs that you didn't realise, and often a circular dependency. This indicates that the classes are in the wrong JAR, or perhaps that everything should just be a single JAR.</li></ul></section><section> +<h3>How do I do this?</h3> <p>You still should adhere to producing one artifact per POM, but this requires having multiple POMs, and hence multiple subdirectories. The positive to this is that these introduced directories won't change the layout of existing code, and will establish a future layout should you decide to separate.</p> <p>Here is an example of setting it up when there is a project with two JARs produced: <code>core</code> and <code>module</code>.</p> -<p>You might like to review the <a href="../getting-started/">Getting Started Guide</a></p><!-- or {{{guide-multi-module.html} Guide to Using Multiple Modules}} --> - +<p>You might like to review the <a href="../getting-started/"> Getting Started Guide</a></p> <p>that demonstrates how this is normally done in Maven, as it is quite similar.</p> <p>Your directory will look something like this:</p> - -<div class="source"><pre class="prettyprint linenums"><code>/ +<div> +<pre>/ +- pom.xml +- src/ +- main/ @@ -183,11 +158,9 @@ under the License. +- core/ +- Core.java +- module/ - +- Module.java -</code></pre></div> + +- Module.java</pre></div> <p>First, you set up your <code>pom.xml</code> at the top level not to produce anything, but to include the other modules we plan to create:</p> - -<div class="source"><pre class="prettyprint linenums"><code><project> +<div class="source"><pre class="prettyprint linenums"><project> <artifactId>my-parent</artifactId> <packaging>pom</packaging> ... @@ -195,11 +168,9 @@ under the License. <module>core</module> <module>module</module> </modules> -</project> -</code></pre></div> +</project></pre></div> <p>Next, the modules themselves are created. Here is the <code>core/pom.xml</code> file you should create. The one in the <code>module</code> subdirectory will be similar.</p> - -<div class="source"><pre class="prettyprint linenums"><code><project> +<div class="source"><pre class="prettyprint linenums"><project> <modelVersion>4.0.0</modelVersion> <parent> <groupId>my-groupId</groupId> @@ -222,12 +193,11 @@ under the License. </plugin> </plugins> </build> -</project> -</code></pre></div> +</project></pre></div> <p>In this example, the sources are found in the parent directory <code>../src/main/java</code>, and only Java files within a <code>core</code> package are included.</p> <p>The final result when building will look like this:</p> - -<div class="source"><pre class="prettyprint linenums"><code>/ +<div> +<pre>/ +- pom.xml +- src/ +- main/ @@ -243,19 +213,14 @@ under the License. +- module/ +- pom.xml +- target/ - +- my-module-1.0-SNAPSHOT.jar -</code></pre></div></section><section> -<h4>What are the limitations?</h4> + +- my-module-1.0-SNAPSHOT.jar</pre></div></section><section> +<h3>What are the limitations?</h3> <p>There is no universal inclusion/exclusion specification, so each plugin needs to be configured individually, and some might not have that capability. In particular, expect that site reports may include all sources, for example.</p></section></section><section> -<h3>Producing Multiple JARs from a single POM</h3> +<h2>Producing Multiple JARs from a single POM</h2> <p>Source directories aside, sometimes people desire to produce multiple JARs from a single POM. Depending on your use case, Maven can support this.</p> <ul> - -<li> -<p>If you are looking to produce JARs that are different (i.e., they have their own dependencies and metadata), Maven doesn't support this. This usually is only needed when sharing a source directory for intrinsically different things, so the use case above applies instead.</p></li> -<li> -<p>If you are producing a JAR that is a derivative of the original (e.g., just a subset of classes, or the same JAR with debugging enabled), Maven supports this using profiles. See <a href="../introduction/introduction-to-profiles.html">Introduction to Profiles</a> for more information.</p></li> -</ul></section></section></section> +<li>If you are looking to produce JARs that are different (i.e., they have their own dependencies and metadata), Maven doesn't support this. This usually is only needed when sharing a source directory for intrinsically different things, so the use case above applies instead.</li> +<li>If you are producing a JAR that is a derivative of the original (e.g., just a subset of classes, or the same JAR with debugging enabled), Maven supports this using profiles. See <a href="../introduction/introduction-to-profiles.html"> Introduction to Profiles</a> for more information.</li></ul></section></section> </main> </div> </div>
