Modified: maven/website/content/guides/development/guide-testing-releases.html ============================================================================== --- maven/website/content/guides/development/guide-testing-releases.html (original) +++ maven/website/content/guides/development/guide-testing-releases.html Sat May 11 11:53:23 2024 @@ -2,17 +2,17 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M10 from content/apt/guides/development/guide-testing-releases.apt at 2024-05-11 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M18 from content/apt/guides/development/guide-testing-releases.apt at 2024-05-11 | Rendered using Apache Maven Fluido Skin 2.0.0-M6 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang="en"> <head> <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-M10" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M18" /> <meta name="author" content="Maven Team" /> <meta name="date" content="2007-12-21" /> - <title>Maven â Guide to Testing Staged Releases</title> + <title>Maven</title> <link rel="stylesheet" href="../../css/apache-maven-fluido-2.0.0-M6.min.css" /> <link rel="stylesheet" href="../../css/site.css" /> <link rel="stylesheet" href="../../css/print.css" media="print" /> @@ -39,8 +39,10 @@ <div class="container-fluid"> <header> <div id="banner"> - <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><img src="../../images/apache-maven-project.png" alt="Apache Maven Site" style="" /></a></div> - <div class="pull-right"><a href="../.././" id="bannerRight"><img src="../../images/maven-logo-black-on-white.png" alt="" style="" /></a></div> + <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><h1>Apache Maven Site</h1> +</a></div> + <div class="pull-right"><a href="../.././" id="bannerRight"><h1>$esc.xml( $banner.name )</h1> +</a></div> <div class="clear"><hr/></div> </div> @@ -48,7 +50,8 @@ <ul class="breadcrumb"> <li><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Guide to Testing Staged Releases <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/development/guide-testing-releases.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + + <li class="active ">Maven <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/development/guide-testing-releases.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-11</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> @@ -144,7 +147,7 @@ </div> </header> <main id="bodyColumn" class="span10" > -<section> +<section><a id="Guide_to_Testing_Staged_Releases"></a> <h1>Guide to Testing Staged Releases</h1> <p>As part of the release process, the artifacts are staged in a temporary repository for testing and evaluation before voting. Such repositories are not available by default, so to use them your project must be configured appropriately.</p> <p>The steps are as follows:</p> @@ -155,15 +158,15 @@ <li>remove the repository from your POM if it was specified there</li> <li>remove the artifacts from your local repository when you have completed testing</li></ul> <p>The repository configuration for testing a plugin will typically look something like this (it will be provided in the vote email):</p> -<div class="verbatim source"><pre class="prettyprint linenums"> ... +<pre><code> ... <pluginRepositories> <pluginRepository> <id>staged-releases</id> <url>https://repository.apache.org/content/groups/staging/</url> </pluginRepository> </pluginRepositories> - ...</pre></div> -<p>The important thing is that the staged release does not pollute your eventual environment as it may change if the vote fails and the release is made again. This is why clearing the local repository is necessary, but if you are using a repository manager this is also important to clear. The following provides instructions for setting Archiva up in such a way that the artifacts are isolated already.</p><section> + ...</code></pre> +<p>The important thing is that the staged release does not pollute your eventual environment as it may change if the vote fails and the release is made again. This is why clearing the local repository is necessary, but if you are using a repository manager this is also important to clear. The following provides instructions for setting Archiva up in such a way that the artifacts are isolated already.</p><section><a id="Setting_up_Archiva_to_Test_Staged_Releases"></a> <h2>Setting up Archiva to Test Staged Releases</h2> <p>These steps will be similar for any repository manager - please refer to their individual documentation for instructions on how to configure remote proxies.</p> <p>For Archiva, the first step is to create a new managed repository for the staged releases. This will ensure they remain isolated from your environment. On the repositories tab, add a new managed repository with the settings:</p> @@ -188,16 +191,16 @@ <p>The advantage of this approach is that you can usually remove your entire local repository afterwards and after removing the staged repository from your POM the artifacts will no longer be used. There is no need to remove the repository or artifacts from Archiva itself - unless a staged release is updated for further testing.</p> <p>It is also quite easy to test another staged release at a later date by reusing the repository, or adding a proxy connector and remote repository for a different staging repository.</p> <p>If you are using the repository mirroring technique to lock down to the repository manager in your environment, you would add an additional mirror to correspond to the additional repository in the POM, such as:</p> -<div class="verbatim source"><pre class="prettyprint linenums"> ... +<pre><code> ... <mirror> <id>staged-releases-mirror</id> <url>http://localhost:8080/archiva/repository/staged-releases/</url> <mirrorOf>staged-releases</mirrorOf> </mirror> - ...</pre></div></section><section> + ...</code></pre></section><section><a id="Using_a_Settings_Profile"></a> <h2>Using a Settings Profile</h2> <p>If you regularly test staged releases and want to have a more convenient way to add the repository to a build without modifying your POM, you may add a profile to your <code>~/.m2/settings.xml</code>:</p> -<div class="verbatim source"><pre class="prettyprint linenums"> ... +<pre><code> ... <profiles> <profile> <id>staged-releases</id> @@ -208,10 +211,9 @@ </pluginRepository> </pluginRepositories> </profile> - ...</pre></div> + ...</code></pre> <p>With this in place, you can activate it by simply changing the plugin version to the one you are testing in the POM as above, then run the build with the following command:</p> -<div class="verbatim"> -<pre>mvn verify -Pstaged-releases</pre></div> +<pre>mvn verify -Pstaged-releases</pre> <p>Note that the same conditions apply as above about cleaning out the local repository to prevent pollution of your local build environment.</p></section></section> </main> </div>
Modified: maven/website/content/guides/getting-started/index.html ============================================================================== --- maven/website/content/guides/getting-started/index.html (original) +++ maven/website/content/guides/getting-started/index.html Sat May 11 11:53:23 2024 @@ -2,18 +2,18 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M10 from content/apt/guides/getting-started/index.apt at 2024-05-11 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M18 from content/apt/guides/getting-started/index.apt at 2024-05-11 | Rendered using Apache Maven Fluido Skin 2.0.0-M6 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang="en"> <head> <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-M10" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M18" /> <meta name="author" content="Jason van Zyl" /> <meta name="author" content="Vincent Siveton" /> <meta name="date" content="2006-11-01" /> - <title>Maven â Maven Getting Started Guide</title> + <title>Maven</title> <link rel="stylesheet" href="../../css/apache-maven-fluido-2.0.0-M6.min.css" /> <link rel="stylesheet" href="../../css/site.css" /> <link rel="stylesheet" href="../../css/print.css" media="print" /> @@ -40,8 +40,10 @@ <div class="container-fluid"> <header> <div id="banner"> - <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><img src="../../images/apache-maven-project.png" alt="Apache Maven Site" style="" /></a></div> - <div class="pull-right"><a href="../.././" id="bannerRight"><img src="../../images/maven-logo-black-on-white.png" alt="" style="" /></a></div> + <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><h1>Apache Maven Site</h1> +</a></div> + <div class="pull-right"><a href="../.././" id="bannerRight"><h1>$esc.xml( $banner.name )</h1> +</a></div> <div class="clear"><hr/></div> </div> @@ -49,7 +51,8 @@ <ul class="breadcrumb"> <li><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Maven Getting Started Guide <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/getting-started/index.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + + <li class="active ">Maven <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/getting-started/index.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-11</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> @@ -152,10 +155,10 @@ </div> </header> <main id="bodyColumn" class="span10" > -<section> +<section><a id="Maven_Getting_Started_Guide"></a> <h1>Maven Getting Started Guide</h1> <p>This guide is intended as a reference for those working with Maven for the first time, but is also intended to serve as a cookbook with self-contained references and solutions for common use cases. For first time users, it is recommended that you step through the material in a sequential fashion. For users more familiar with Maven, this guide endeavours to provide a quick solution for the need at hand. It is assumed at this point that you have downloaded Maven and installed Maven on your local machine. If you have not done so please refer to the <a href="../../download.html">Download and Installation</a> instructions.</p> -<p>Ok, so you now have Maven installed and we're ready to go. Before we jump into our examples we'll very briefly go over what Maven is and how it can help you with your daily work and collaborative efforts with team members. Maven will, of course, work for small projects, but Maven shines in helping teams operate more effectively by allowing team members to focus on what the stakeholders of a project require. You can leave the build infrastructure to Maven!</p></section><section> +<p>Ok, so you now have Maven installed and we're ready to go. Before we jump into our examples we'll very briefly go over what Maven is and how it can help you with your daily work and collaborative efforts with team members. Maven will, of course, work for small projects, but Maven shines in helping teams operate more effectively by allowing team members to focus on what the stakeholders of a project require. You can leave the build infrastructure to Maven!</p></section><section><a id="Sections"></a> <h1>Sections</h1> <ul> <li><a href="./index.html#what-is-maven">What is Maven?</a></li> @@ -193,10 +196,9 @@ <h2><a id="How_do_I_make_my_first_Maven_project.3F">How do I make my first Maven project?</a></h2> <p>We are going to jump headlong into creating your first Maven project! To create our first Maven project we are going to use Maven's archetype mechanism. An archetype is defined as <i>an original pattern or model from which all other things of the same kind are made</i>. In Maven, an archetype is a template of a project which is combined with some user input to produce a working Maven project that has been tailored to the user's requirements. We are going to show you how the archetype mechanism works now, but if you would like to know more about archetypes please refer to our <a href="../introduction/introduction-to-archetypes.html">Introduction to Archetypes</a>.</p> <p>On to creating your first project! In order to create the simplest of Maven projects, execute the following from the command line:</p> -<div class="verbatim"> -<pre>mvn -B archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4</pre></div> +<pre>mvn -B archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4</pre> <p>Once you have executed this command, you will notice a few things have happened. First, you will notice that a directory named <code>my-app</code> has been created for the new project, and this directory contains a file named <code>pom.xml</code> that should look like this:</p> -<div class="verbatim source"><pre class="prettyprint linenums"><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" +<pre><code><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> @@ -228,7 +230,7 @@ ... lots of helpful plugins </pluginManagement> </build> -</project></pre></div> +</project></code></pre> <p><code>pom.xml</code> contains the Project Object Model (POM) for this project. The POM is the basic unit of work in Maven. This is important to remember because Maven is inherently project-centric in that everything revolves around the notion of a project. In short, the POM contains every important piece of information about your project and is essentially one-stop-shopping for finding anything related to your project. Understanding the POM is important and new users are encouraged to refer to the <a href="../introduction/introduction-to-the-pom.html">Introduction to the POM</a>.</p> <p>This is a very simple POM but still displays the key elements every POM contains, so let's walk through each of them to familiarize you with the POM essentials:</p> <ul> @@ -244,7 +246,6 @@ <li><b>build</b> This element handles things like declaring your project's directory structure and managing plugins.</li></ul> <p>For a complete reference of what elements are available for use in the POM please refer to our <a href="/ref/current/maven-model/maven.html">POM Reference</a>. Now let's get back to the project at hand.</p> <p>After the archetype generation of your first project you will also notice that the following directory structure has been created:</p> -<div class="verbatim"> <pre>my-app |-- pom.xml `-- src @@ -259,16 +260,14 @@ `-- com `-- mycompany `-- app - `-- AppTest.java</pre></div> + `-- AppTest.java</pre> <p>As you can see, the project created from the archetype has a POM, a source tree for your application's sources and a source tree for your test sources. This is the standard layout for Maven projects (the application sources reside in <code>${project.basedir}/src/main/java</code> and test sources reside in <code>${project.basedir}/src/test/java</code>, where <code>${project.basedir}</code> represents the directory containing <code>pom.xml</code>).</p> <p>If you were to create a Maven project by hand this is the directory structure that we recommend using. This is a Maven convention and to learn more about it you can read our <a href="../introduction/introduction-to-the-standard-directory-layout.html">Introduction to the Standard Directory Layout</a>.</p> <p>Now that we have a POM, some application sources, and some test sources you are probably asking...</p></section><section> <h2><a id="How_do_I_compile_my_application_sources.3F">How do I compile my application sources?</a></h2> <p>Change to the directory where <code>pom.xml</code> is created by archetype:generate and execute the following command to compile your application sources:</p> -<div class="verbatim"> -<pre>mvn compile</pre></div> +<pre>mvn compile</pre> <p>Upon executing this command you should see output like the following:</p> -<div class="verbatim"> <pre>[INFO] Scanning for projects... [INFO] [INFO] ----------------------< com.mycompany.app:my-app >---------------------- @@ -287,17 +286,15 @@ [INFO] ------------------------------------------------------------------------ [INFO] Total time: 0.899 s [INFO] Finished at: 2020-07-12T11:31:54+01:00 -[INFO] ------------------------------------------------------------------------</pre></div> +[INFO] ------------------------------------------------------------------------</pre> <p>The first time you execute this (or any other) command, Maven will need to download all the plugins and related dependencies it needs to fulfill the command. From a clean installation of Maven, this can take quite a while (in the output above, it took almost 4 minutes). If you execute the command again, Maven will now have what it needs, so it won't need to download anything new and will be able to execute the command much more quickly.</p> <p>As you can see from the output, the compiled classes were placed in <code>${project.basedir}/target/classes</code>, which is another standard convention employed by Maven. So, if you're a keen observer, you'll notice that by using the standard conventions, the POM above is very small and you haven't had to tell Maven explicitly where any of your sources are or where the output should go. By following the standard Maven conventions, you can get a lot done with very little effort! Just as a casual comparison, let's take a look at what you might have had to do in <a class="externalLink" href="http://ant.apache.org";>Ant</a> to accomplish the same <a href="../../ant/build-a1.xml">thing</a>.</p> <p>Now, this is simply to compile a single tree of application sources and the Ant script shown is pretty much the same size as the POM shown above. But we'll see how much more we can do with just that simple POM!</p></section><section> <h2><a id="How_do_I_compile_my_test_sources_and_run_my_unit_tests.3F">How do I compile my test sources and run my unit tests?</a></h2> <p>Now you're successfully compiling your application's sources and now you've got some unit tests that you want to compile and execute (because every programmer always writes and executes their unit tests *nudge nudge wink wink*).</p> <p>Execute the following command:</p> -<div class="verbatim"> -<pre>mvn test</pre></div> +<pre>mvn test</pre> <p>Upon executing this command you should see output like the following:</p> -<div class="verbatim"> <pre>[INFO] Scanning for projects... [INFO] [INFO] ----------------------< com.mycompany.app:my-app >---------------------- @@ -336,25 +333,21 @@ [INFO] ------------------------------------------------------------------------ [INFO] Total time: 1.881 s [INFO] Finished at: 2020-07-12T12:00:33+01:00 -[INFO] ------------------------------------------------------------------------</pre></div> +[INFO] ------------------------------------------------------------------------</pre> <p>Some things to notice about the output:</p> <ul> <li>Maven downloads more dependencies this time. These are the dependencies and plugins necessary for executing the tests (it already has the dependencies it needs for compiling and won't download them again).</li> <li>Before compiling and executing the tests Maven compiles the main code (all these classes are up to date because we haven't changed anything since we compiled last).</li></ul> <p>If you simply want to compile your test sources (but not execute the tests), you can execute the following:</p> -<div class="verbatim"> -<pre> mvn test-compile</pre></div> +<pre> mvn test-compile</pre> <p>Now that you can compile your application sources, compile your tests, and execute the tests, you'll want to move on to the next logical step so you'll be asking ...</p></section><section> <h2><a id="How_do_I_create_a_JAR_and_install_it_in_my_local_repository.3F">How do I create a JAR and install it in my local repository?</a></h2> <p>Making a JAR file is straight forward enough and can be accomplished by executing the following command:</p> -<div class="verbatim"> -<pre>mvn package</pre></div> +<pre>mvn package</pre> <p>You can now take a look in the <code>${project.basedir}/target</code> directory and you will see the generated JAR file.</p> <p>Now you'll want to install the artifact you've generated (the JAR file) in your local repository (<code>${user.home}/.m2/repository</code> is the default location). For more information on repositories you can refer to our <a href="../introduction/introduction-to-repositories.html">Introduction to Repositories</a> but let's move on to installing our artifact! To do so execute the following command:</p> -<div class="verbatim"> -<pre>mvn install</pre></div> +<pre>mvn install</pre> <p>Upon executing this command you should see the following output:</p> -<div class="verbatim"> <pre>[INFO] Scanning for projects... [INFO] [INFO] ----------------------< com.mycompany.app:my-app >---------------------- @@ -395,7 +388,7 @@ [INFO] ------------------------------------------------------------------------ [INFO] Total time: 1.678 s [INFO] Finished at: 2020-07-12T12:04:45+01:00 -[INFO] ------------------------------------------------------------------------</pre></div> +[INFO] ------------------------------------------------------------------------</pre> <p>Note that the surefire plugin (which executes the test) looks for tests contained in files with a particular naming convention. By default the tests included are:</p> <ul> <li><code>**/*Test.java</code></li> @@ -407,29 +400,27 @@ <li><code>**/Abstract*TestCase.java</code></li></ul> <p>You have walked through the process for setting up, building, testing, packaging, and installing a typical Maven project. This is likely the vast majority of what projects will be doing with Maven and if you've noticed, everything you've been able to do up to this point has been driven by an 18-line file, namely the project's model or POM. If you look at a typical Ant <a href="../../ant/build-a1.xml">build file</a> that provides the same functionality that we've achieved thus far you'll notice it's already twice the size of the POM and we're just getting started! There is far more functionality available to you from Maven without requiring any additions to our POM as it currently stands. To get any more functionality out of our example Ant build file you must keep making error-prone additions.</p> <p>So what else can you get for free? There are a great number of Maven plugins that work out of the box with even a simple POM like we have above. We'll mention one here specifically as it is one of the highly prized features of Maven: without any work on your part this POM has enough information to generate a web site for your project! You will most likely want to customize your Maven site but if you're pressed for time all you need to do to provide basic information about your project is execute the following command:</p> -<div class="verbatim"> -<pre>mvn site</pre></div> +<pre>mvn site</pre> <p>There are plenty of other standalone goals that can be executed as well, for example:</p> -<div class="verbatim"> -<pre>mvn clean</pre></div> +<pre>mvn clean</pre> <p>This will remove the <code>target</code> directory with all the build data before starting so that it is fresh.</p></section><section> <h2><a id="What_is_a_SNAPSHOT_version.3F">What is a SNAPSHOT version?</a></h2> <p>Notice the value of the <b>version</b> tag in the <code>pom.xml</code> file shown below has the suffix: <code>-SNAPSHOT</code>.</p> -<div class="verbatim source"><pre class="prettyprint linenums"><project xmlns="http://maven.apache.org/POM/4.0.0" +<pre><code><project xmlns="http://maven.apache.org/POM/4.0.0" ... <groupId>...</groupId> <artifactId>my-app</artifactId> ... <version>1.0-SNAPSHOT</version> <name>Maven Quick Start Archetype</name> - ...</pre></div> + ...</code></pre> <p>The <code>SNAPSHOT</code> value refers to the 'latest' code along a development branch, and provides no guarantee the code is stable or unchanging. Conversely, the code in a 'release' version (any version value without the suffix <code>SNAPSHOT</code>) is unchanging.</p> <p>In other words, a SNAPSHOT version is the 'development' version before the final 'release' version. The SNAPSHOT is "older" than its release.</p> <p>During the <a href="../../plugins/maven-release-plugin/">release</a> process, a version of <b>x.y-SNAPSHOT</b> changes to <b>x.y</b>. The release process also increments the development version to <b>x.(y+1)-SNAPSHOT</b>. For example, version <b>1.0-SNAPSHOT</b> is released as version <b>1.0</b>, and the new development version is version <b>1.1-SNAPSHOT</b>.</p></section><section> <h2><a id="How_do_I_use_plugins.3F">How do I use plugins?</a></h2> <p>Whenever you want to customise the build for a Maven project, this is done by adding or reconfiguring plugins.</p> <p>For this example, we will configure the Java compiler to allow JDK 5.0 sources. This is as simple as adding this to your POM:</p> -<div class="verbatim source"><pre class="prettyprint linenums">... +<pre><code>... <build> <plugins> <plugin> @@ -443,14 +434,13 @@ </plugin> </plugins> </build> -...</pre></div> +...</code></pre> <p>You'll notice that all plugins in Maven look much like a dependency - and in some ways they are. This plugin will be automatically downloaded and used - including a specific version if you request it (the default is to use the latest available).</p> <p>The <code>configuration</code> element applies the given parameters to every goal from the compiler plugin. In the above case, the compiler plugin is already used as part of the build process and this just changes the configuration. It is also possible to add new goals to the process, and configure specific goals. For information on this, see the <a href="../introduction/introduction-to-the-lifecycle.html"> Introduction to the Build Lifecycle</a>.</p> <p>To find out what configuration is available for a plugin, you can see the <a href="../../plugins/"> Plugins List</a> and navigate to the plugin and goal you are using. For general information about how to configure the available parameters of a plugin, have a look at the <a href="../mini/guide-configuring-plugins.html">Guide to Configuring Plugins</a>.</p></section><section> <h2><a id="How_do_I_add_resources_to_my_JAR.3F">How do I add resources to my JAR?</a></h2> <p>Another common use case that can be satisfied which requires no changes to the POM that we have above is packaging resources in the JAR file. For this common task, Maven again relies on the <a href="../introduction/introduction-to-the-standard-directory-layout.html">Standard Directory Layout</a>, which means by using standard Maven conventions you can package resources within JARs simply by placing those resources in a standard directory structure.</p> <p>You see below in our example we have added the directory <code>${project.basedir}/src/main/resources</code> into which we place any resources we wish to package in our JAR. The simple rule employed by Maven is this: any directories or files placed within the <code>${project.basedir}/src/main/resources</code> directory are packaged in your JAR with the exact same structure starting at the base of the JAR.</p> -<div class="verbatim"> <pre>my-app |-- pom.xml `-- src @@ -468,9 +458,8 @@ `-- com `-- mycompany `-- app - `-- AppTest.java</pre></div> + `-- AppTest.java</pre> <p>So you can see in our example that we have a <code>META-INF</code> directory with an <code>application.properties</code> file within that directory. If you unpacked the JAR that Maven created for you and took a look at it you would see the following:</p> -<div class="verbatim"> <pre>|-- META-INF | |-- MANIFEST.MF | `-- application.properties @@ -482,16 +471,14 @@ `-- com `-- mycompany `-- app - `-- App.class</pre></div> + `-- App.class</pre> <p>As you can see, the contents of <code>${project.basedir}/src/main/resources</code> can be found starting at the base of the JAR and our <code>application.properties</code> file is there in the <code>META-INF</code> directory. You will also notice some other files there like <code>META-INF/MANIFEST.MF</code> as well as a <code>pom.xml</code> and <code>pom.properties</code> file. These come standard with generation of a JAR in Maven. You can create your own manifest if you choose, but Maven will generate one by default if you don't. (You can also modify the entries in the default manifest. We will touch on this later.) The <code>pom.xml</code> and <code>pom.properties</code> files are packaged up in the JAR so that each artifact produced by Maven is self-describing and also allows you to utilize the metadata in your own application if the need arises. One simple use might be to retrieve the version of your application. Operating on the POM file would require you to use some Maven u tilities but the properties can be utilized using the standard Java API and look like the following:</p> -<div class="verbatim"> <pre>#Generated by Maven #Tue Oct 04 15:43:21 GMT-05:00 2005 version=1.0-SNAPSHOT groupId=com.mycompany.app -artifactId=my-app</pre></div> +artifactId=my-app</pre> <p>To add resources to the classpath for your unit tests, you follow the same pattern as you do for adding resources to the JAR except the directory you place resources in is <code>${project.basedir}/src/test/resources</code>. At this point you would have a project directory structure that would look like the following:</p> -<div class="verbatim"> <pre>my-app |-- pom.xml `-- src @@ -511,20 +498,20 @@ artifactId=my-app</pre></div> | `-- app | `-- AppTest.java `-- resources - `-- test.properties</pre></div> + `-- test.properties</pre> <p>In a unit test you could use a simple snippet of code like the following to access the resource required for testing:</p> -<div class="verbatim source"><pre class="prettyprint linenums">... +<pre><code>... // Retrieve resource InputStream is = getClass().getResourceAsStream( "/test.properties" ); // Do something with the resource -...</pre></div></section><section> +...</code></pre></section><section> <h2><a id="How_do_I_filter_resource_files.3F">How do I filter resource files?</a></h2> <p>Sometimes a resource file will need to contain a value that can only be supplied at build time. To accomplish this in Maven, put a reference to the property that will contain the value into your resource file using the syntax <code>${<property name>}</code>. The property can be one of the values defined in your <code>pom.xml</code>, a value defined in the user's <code>settings.xml</code>, a property defined in an external properties file, or a system property.</p> <p>To have Maven filter resources when copying, simply set <code>filtering</code> to true for the resource directory in your <code>pom.xml</code>:</p> -<div class="verbatim source"><pre class="prettyprint linenums"><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" +<pre><code><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> @@ -553,28 +540,24 @@ InputStream is = getClass().getResourceA </resource> </resources> </build> -</project></pre></div> +</project></code></pre> <p>You'll notice that we had to add the <code>build</code>, <code>resources</code>, and <code>resource</code> elements which weren't there before. In addition, we had to explicitly state that the resources are located in the <code>src/main/resources</code> directory. All of this information was provided as default values previously, but because the default value for <code>filtering</code> is false, we had to add this to our <code>pom.xml</code> in order to override that default value and set <code>filtering</code> to true.</p> <p>To reference a property defined in your <code>pom.xml</code>, the property name uses the names of the XML elements that define the value, with "pom" being allowed as an alias for the project (root) element. So <code>${project.name}</code> refers to the name of the project, <code>${project.version}</code> refers to the version of the project, <code>${project.build.finalName}</code> refers to the final name of the file created when the built project is packaged, etc. Note that some elements of the POM have default values, so don't need to be explicitly defined in your <code>pom.xml</code> for the values to be available here. Similarly, values in the user's <code>settings.xml</code> can be referenced using property names beginning with "settings" (for example, <code>${settings.localRepository}</code> refers to the path of the user's local repository).</p> <p>To continue our example, let's add a couple of properties to the <code>application.properties</code> file (which we put in the <code>src/main/resources</code> directory) whose values will be supplied when the resource is filtered:</p> -<div class="verbatim"> <pre># application.properties application.name=${project.name} -application.version=${project.version}</pre></div> +application.version=${project.version}</pre> <p>With that in place, you can execute the following command (process-resources is the build lifecycle phase where the resources are copied and filtered):</p> -<div class="verbatim"> -<pre>mvn process-resources</pre></div> +<pre>mvn process-resources</pre> <p>and the <code>application.properties</code> file under <code>target/classes</code> (and will eventually go into the jar) looks like this:</p> -<div class="verbatim"> <pre># application.properties application.name=Maven Quick Start Archetype -application.version=1.0-SNAPSHOT</pre></div> +application.version=1.0-SNAPSHOT</pre> <p>To reference a property defined in an external file, all you need to do is add a reference to this external file in your <code>pom.xml</code>. First, let's create our external properties file and call it <code>src/main/filters/filter.properties</code>:</p> -<div class="verbatim"> <pre># filter.properties -my.filter.value=hello!</pre></div> +my.filter.value=hello!</pre> <p>Next, we'll add a reference to this new file in the <code>pom.xml</code>:</p> -<div class="verbatim source"><pre class="prettyprint linenums"><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" +<pre><code><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> @@ -606,15 +589,14 @@ my.filter.value=hello!</pre></div> </resource> </resources> </build> -</project></pre></div> +</project></code></pre> <p>Then, if we add a reference to this property in the <code>application.properties</code> file:</p> -<div class="verbatim"> <pre># application.properties application.name=${project.name} application.version=${project.version} -message=${my.filter.value}</pre></div> +message=${my.filter.value}</pre> <p>the next execution of the <code>mvn process-resources</code> command will put our new property value into <code>application.properties</code>. As an alternative to defining the my.filter.value property in an external file, you could also have defined it in the <code>properties</code> section of your <code>pom.xml</code> and you'd get the same effect (notice I don't need the references to <code>src/main/filters/filter.properties</code> either):</p> -<div class="verbatim source"><pre class="prettyprint linenums"><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" +<pre><code><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> @@ -647,19 +629,17 @@ message=${my.filter.value}</pre></div> <properties> <my.filter.value>hello</my.filter.value> </properties> -</project></pre></div> +</project></code></pre> <p>Filtering resources can also get values from system properties; either the system properties built into Java (like <code>java.version</code> or <code>user.home</code>) or properties defined on the command line using the standard Java -D parameter. To continue the example, let's change our <code>application.properties</code> file to look like this:</p> -<div class="verbatim"> <pre># application.properties java.version=${java.version} -command.line.prop=${command.line.prop}</pre></div> +command.line.prop=${command.line.prop}</pre> <p>Now, when you execute the following command (note the definition of the command.line.prop property on the command line), the <code>application.properties</code> file will contain the values from the system properties.</p> -<div class="verbatim"> -<pre>mvn process-resources "-Dcommand.line.prop=hello again"</pre></div></section><section> +<pre>mvn process-resources "-Dcommand.line.prop=hello again"</pre></section><section> <h2><a id="How_do_I_use_external_dependencies.3F">How do I use external dependencies?</a></h2> <p>You've probably already noticed a <code>dependencies</code> element in the POM we've been using as an example. You have, in fact, been using an external dependency all this time, but here we'll talk about how this works in a bit more detail. For a more thorough introduction, please refer to our <a href="../introduction/introduction-to-dependency-mechanism.html">Introduction to Dependency Mechanism</a>.</p> <p>The <code>dependencies</code> section of the <code>pom.xml</code> lists all of the external dependencies that our project needs in order to build (whether it needs that dependency at compile time, test time, run time, or whatever). Right now, our project is depending on JUnit only (I took out all of the resource filtering stuff for clarity):</p> -<div class="verbatim source"><pre class="prettyprint linenums"><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" +<pre><code><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> @@ -679,11 +659,11 @@ command.line.prop=${command.line.prop}</ <scope>test</scope> </dependency> </dependencies> -</project></pre></div> +</project></code></pre> <p>For each external dependency, you'll need to define at least 4 things: groupId, artifactId, version, and scope. The groupId, artifactId, and version are the same as those given in the <code>pom.xml</code> for the project that built that dependency. The scope element indicates how your project uses that dependency, and can be values like <code>compile</code>, <code>test</code>, and <code>runtime</code>. For more information on everything you can specify for a dependency, see the <a href="/ref/current/maven-model/maven.html">Project Descriptor Reference</a>.</p> <p>For more information about the dependency mechanism as a whole, see <a href="../introduction/introduction-to-dependency-mechanism.html">Introduction to Dependency Mechanism</a>.</p> <p>With this information about a dependency, Maven will be able to reference the dependency when it builds the project. Where does Maven reference the dependency from? Maven looks in your local repository (<code>${user.home}/.m2/repository</code> is the default location) to find all dependencies. In a <a href="#How_do_I_create_a_JAR_and_install_it_in_my_local_repository">previous section</a>, we installed the artifact from our project (my-app-1.0-SNAPSHOT.jar) into the local repository. Once it's installed there, another project can reference that jar as a dependency simply by adding the dependency information to its <code>pom.xml</code>:</p> -<div class="verbatim source"><pre class="prettyprint linenums"><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" +<pre><code><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <groupId>com.mycompany.app</groupId> <artifactId>my-other-app</artifactId> @@ -697,10 +677,10 @@ command.line.prop=${command.line.prop}</ <scope>compile</scope> </dependency> </dependencies> -</project></pre></div> +</project></code></pre> <p>What about dependencies built somewhere else? How do they get into my local repository? Whenever a project references a dependency that isn't available in the local repository, Maven will download the dependency from a remote repository into the local repository. You probably noticed Maven downloading a lot of things when you built your very first project (these downloads were dependencies for the various plugins used to build the project). By default, the remote repository Maven uses can be found (and browsed) at <a class="externalLink" href="https://repo.maven.apache.org/maven2/";>https://repo.maven.apache.org/maven2/</a>. You can also set up your own remote repository (maybe a central repository for your company) to use instead of or in addition to the default remote repository. For more information on repositories you can refer to the <a href="../introduction/introduction-to-repositories.html">Introduction to Repositories</a>.</p> <p>Let's add another dependency to our project. Let's say we've added some logging to the code and need to add log4j as a dependency. First, we need to know what the groupId, artifactId, and version are for log4j. The appropriate directory on Maven Central is called <a class="externalLink" href="https://repo.maven.apache.org/maven2/log4j/log4j/";>/maven2/log4j/log4j</a>. In that directory is a file called maven-metadata.xml. Here's what the maven-metadata.xml for log4j looks like:</p> -<div class="verbatim source"><pre class="prettyprint linenums"><metadata> +<pre><code><metadata> <groupId>log4j</groupId> <artifactId>log4j</artifactId> <version>1.1.3</version> @@ -717,10 +697,10 @@ command.line.prop=${command.line.prop}</ <version>1.2.12</version> </versions> </versioning> -</metadata></pre></div> +</metadata></code></pre> <p>From this file, we can see that the groupId we want is "log4j" and the artifactId is "log4j". We see lots of different version values to choose from; for now, we'll just use the latest version, 1.2.12 (some maven-metadata.xml files may also specify which version is the current release version: see <a href="/ref/current/maven-repository-metadata/repository-metadata.html">repository metadata reference</a>). Alongside the maven-metadata.xml file, we can see a directory corresponding to each version of the log4j library. Inside each of these, we'll find the actual jar file (e.g. log4j-1.2.12.jar) as well as a pom file (this is the <code>pom.xml</code> for the dependency, indicating any further dependencies it might have and other information) and another maven-metadata.xml file. There's also an md5 file corresponding to each of these, which contains an MD5 hash for these files. You can use this to authenticate the library or to figure out which version of a partic ular library you may be using already.</p> <p>Now that we know the information we need, we can add the dependency to our pom.xml:</p> -<div class="verbatim source"><pre class="prettyprint linenums"><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" +<pre><code><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> @@ -746,12 +726,12 @@ command.line.prop=${command.line.prop}</ <scope>compile</scope> </dependency> </dependencies> -</project></pre></div> +</project></code></pre> <p>Now, when we compile the project (<code>mvn compile</code>), we'll see Maven download the log4j dependency for us.</p></section><section> <h2><a id="How_do_I_deploy_my_jar_in_my_remote_repository.3F">How do I deploy my jar in my remote repository?</a></h2> <p>For deploying jars to an external repository, you have to configure the repository url in the <code>pom.xml</code> and the authentication information for connecting to the repository in the <code>settings.xml</code>.</p> <p>Here is an example using scp and username/password authentication:</p> -<div class="verbatim source"><pre class="prettyprint linenums"><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" +<pre><code><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> @@ -800,8 +780,8 @@ command.line.prop=${command.line.prop}</ <url>scp://repository.mycompany.com/repository/maven2</url> </repository> </distributionManagement> -</project></pre></div> -<div class="verbatim source"><pre class="prettyprint linenums"><settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" +</project></code></pre> +<pre><code><settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd"> ... <servers> @@ -814,28 +794,26 @@ command.line.prop=${command.line.prop}</ </server> </servers> ... -</settings></pre></div> +</settings></code></pre> <p>Note that if you are connecting to an openssh ssh server which has the parameter "PasswordAuthentication" set to "no" in the sshd_config, you will have to type your password each time for username/password authentication (although you can log in using another ssh client by typing in the username and password). You might want to switch to public key authentication in this case.</p> <p>Care should be taken if using passwords in <code>settings.xml</code>. For more information, see <a href="../mini/guide-encryption.html"> Password Encryption</a>.</p></section><section> <h2><a id="How_do_I_create_documentation.3F">How do I create documentation?</a></h2> <p>To get you jump started with Maven's documentation system you can use the archetype mechanism to generate a site for your existing project using the following command:</p> -<div class="verbatim"> <pre>mvn archetype:generate \ -DarchetypeGroupId=org.apache.maven.archetypes \ -DarchetypeArtifactId=maven-archetype-site \ -DgroupId=com.mycompany.app \ - -DartifactId=my-app-site</pre></div> + -DartifactId=my-app-site</pre> <p>Now head on over to the <a href="../mini/guide-site.html">Guide to creating a site</a> to learn how to create the documentation for your project.</p></section><section> <h2><a id="How_do_I_build_other_types_of_projects.3F">How do I build other types of projects?</a></h2> <p>Note that the lifecycle applies to any project type. For example, back in the base directory we can create a simple web application:</p> -<div class="verbatim"> <pre>mvn archetype:generate \ -DarchetypeGroupId=org.apache.maven.archetypes \ -DarchetypeArtifactId=maven-archetype-webapp \ -DgroupId=com.mycompany.app \ - -DartifactId=my-webapp</pre></div> + -DartifactId=my-webapp</pre> <p>Note that these must all be on a single line. This will create a directory called <code>my-webapp</code> containing the following project descriptor:</p> -<div class="verbatim source"><pre class="prettyprint linenums"><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" +<pre><code><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> @@ -856,15 +834,13 @@ command.line.prop=${command.line.prop}</ <build> <finalName>my-webapp</finalName> </build> -</project></pre></div> +</project></code></pre> <p>Note the <code><packaging></code> element - this tells Maven to build as a WAR. Change into the webapp project's directory and try:</p> -<div class="verbatim"> -<pre>mvn package</pre></div> +<pre>mvn package</pre> <p>You'll see <code>target/my-webapp.war</code> is built, and that all the normal steps were executed.</p></section><section> <h2><a id="How_do_I_build_more_than_one_project_at_once.3F">How do I build more than one project at once?</a></h2> <p>The concept of dealing with multiple modules is built in to Maven. In this section, we will show how to build the WAR above, and include the previous JAR as well in one step.</p> <p>Firstly, we need to add a parent <code>pom.xml</code> file in the directory above the other two, so it should look like this:</p> -<div class="verbatim"> <pre>+- pom.xml +- my-app | +- pom.xml @@ -875,9 +851,9 @@ command.line.prop=${command.line.prop}</ | +- pom.xml | +- src | +- main -| +- webapp</pre></div> +| +- webapp</pre> <p>The POM file you'll create should contain the following:</p> -<div class="verbatim source"><pre class="prettyprint linenums"><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" +<pre><code><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> @@ -890,9 +866,9 @@ command.line.prop=${command.line.prop}</ <module>my-app</module> <module>my-webapp</module> </modules> -</project></pre></div> +</project></code></pre> <p>We'll need a dependency on the JAR from the webapp, so add this to <code>my-webapp/pom.xml</code>:</p> -<div class="verbatim source"><pre class="prettyprint linenums"> ... +<pre><code> ... <dependencies> <dependency> <groupId>com.mycompany.app</groupId> @@ -900,21 +876,19 @@ command.line.prop=${command.line.prop}</ <version>1.0-SNAPSHOT</version> </dependency> ... - </dependencies></pre></div> + </dependencies></code></pre> <p>Finally, add the following <code><parent></code> element to both of the other <code>pom.xml</code> files in the subdirectories:</p> -<div class="verbatim source"><pre class="prettyprint linenums"><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" +<pre><code><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <parent> <groupId>com.mycompany.app</groupId> <artifactId>app</artifactId> <version>1.0-SNAPSHOT</version> </parent> - ...</pre></div> + ...</code></pre> <p>Now, try it... from the top level directory, run:</p> -<div class="verbatim"> -<pre>mvn verify</pre></div> +<pre>mvn verify</pre> <p>The WAR has now been created in <code>my-webapp/target/my-webapp.war</code>, and the JAR is included:</p> -<div class="verbatim"> <pre>$ jar tvf my-webapp/target/my-webapp-1.0-SNAPSHOT.war 0 Fri Jun 24 10:59:56 EST 2005 META-INF/ 222 Fri Jun 24 10:59:54 EST 2005 META-INF/MANIFEST.MF @@ -927,7 +901,7 @@ command.line.prop=${command.line.prop}</ 123 Fri Jun 24 10:59:56 EST 2005 META-INF/maven/com.mycompany.app/my-webapp/pom.properties 52 Fri Jun 24 10:59:56 EST 2005 index.jsp 0 Fri Jun 24 10:59:56 EST 2005 WEB-INF/lib/ -2713 Fri Jun 24 10:59:56 EST 2005 WEB-INF/lib/my-app-1.0-SNAPSHOT.jar</pre></div> +2713 Fri Jun 24 10:59:56 EST 2005 WEB-INF/lib/my-app-1.0-SNAPSHOT.jar</pre> <p>How does this work? Firstly, the parent POM created (called <code>app</code>), has a packaging of <code>pom</code> and a list of modules defined. This tells Maven to run all operations over the set of projects instead of just the current one (to override this behaviour, you can use the <code>--non-recursive</code> command line option).</p> <p>Next, we tell the WAR that it requires the <code>my-app</code> JAR. This does a few things: it makes it available on the classpath to any code in the WAR (none in this case), it makes sure the JAR is always built before the WAR, and it indicates to the WAR plugin to include the JAR in its library directory.</p> <p>You may have noticed that <code>junit-4.11.jar</code> was a dependency, but didn't end up in the WAR. The reason for this is the <code><scope>test</scope></code> element - it is only required for testing, and so is not included in the web application as the compile time dependency <code>my-app</code> is.</p> Modified: maven/website/content/guides/getting-started/maven-in-five-minutes.html ============================================================================== --- maven/website/content/guides/getting-started/maven-in-five-minutes.html (original) +++ maven/website/content/guides/getting-started/maven-in-five-minutes.html Sat May 11 11:53:23 2024 @@ -2,17 +2,17 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M10 from content/apt/guides/getting-started/maven-in-five-minutes.apt at 2024-05-11 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M18 from content/apt/guides/getting-started/maven-in-five-minutes.apt at 2024-05-11 | Rendered using Apache Maven Fluido Skin 2.0.0-M6 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang="en"> <head> <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-M10" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M18" /> <meta name="author" content="Eric Redmond" /> <meta name="date" content="2008-01-01" /> - <title>Maven â Maven in 5 Minutes</title> + <title>Maven</title> <link rel="stylesheet" href="../../css/apache-maven-fluido-2.0.0-M6.min.css" /> <link rel="stylesheet" href="../../css/site.css" /> <link rel="stylesheet" href="../../css/print.css" media="print" /> @@ -39,8 +39,10 @@ <div class="container-fluid"> <header> <div id="banner"> - <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><img src="../../images/apache-maven-project.png" alt="Apache Maven Site" style="" /></a></div> - <div class="pull-right"><a href="../.././" id="bannerRight"><img src="../../images/maven-logo-black-on-white.png" alt="" style="" /></a></div> + <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><h1>Apache Maven Site</h1> +</a></div> + <div class="pull-right"><a href="../.././" id="bannerRight"><h1>$esc.xml( $banner.name )</h1> +</a></div> <div class="clear"><hr/></div> </div> @@ -48,7 +50,8 @@ <ul class="breadcrumb"> <li><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Maven in 5 Minutes <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/getting-started/maven-in-five-minutes.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + + <li class="active ">Maven <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/getting-started/maven-in-five-minutes.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-11</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> @@ -143,34 +146,29 @@ </div> </header> <main id="bodyColumn" class="span10" > -<section> -<h1>Maven in 5 Minutes</h1><section> +<section><a id="Maven_in_5_Minutes"></a> +<h1>Maven in 5 Minutes</h1><section><a id="Prerequisites"></a> <h2>Prerequisites</h2> -<p>You must understand how to install software on your computer. If you do not know how to do this, please ask someone at your office, school, etc. or pay someone to explain this to you. The Maven mailing lists are not the best place to ask for this advice.</p></section><section> +<p>You must understand how to install software on your computer. If you do not know how to do this, please ask someone at your office, school, etc. or pay someone to explain this to you. The Maven mailing lists are not the best place to ask for this advice.</p></section><section><a id="Installation"></a> <h2>Installation</h2> <p><i>Maven is a Java tool, so you must have <a class="externalLink" href="https://www.oracle.com/technetwork/java/javase/downloads/index.html";>Java</a> installed in order to proceed.</i></p> <p>First, <a href="../../download.html">download Maven</a> and follow the <a href="../../install.html">installation instructions</a>. After that, type the following in a terminal or in a command prompt:</p> -<div class="verbatim"> -<pre>mvn --version</pre></div> +<pre>mvn --version</pre> <p>It should print out your installed version of Maven, for example:</p> -<div class="verbatim"> <pre>Apache Maven 3.6.3 (cecedd343002696d0abb50b32b541b8a6ba2883f) Maven home: D:\apache-maven-3.6.3\apache-maven\bin\.. Java version: 1.8.0_232, vendor: AdoptOpenJDK, runtime: C:\Program Files\AdoptOpenJDK\jdk-8.0.232.09-hotspot\jre Default locale: en_US, platform encoding: Cp1250 -OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows"</pre></div> +OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows"</pre> <p>Depending upon your network setup, you may require extra configuration. Check out the <a href="../mini/guide-configuring-maven.html">Guide to Configuring Maven</a> if necessary.</p> -<p><b>If you are using Windows, you should look at</b> <a href="./windows-prerequisites.html">Windows Prerequisites</a> <b>to ensure that you are prepared to use Maven on Windows.</b></p></section><section> +<p><b>If you are using Windows, you should look at</b> <a href="./windows-prerequisites.html">Windows Prerequisites</a> <b>to ensure that you are prepared to use Maven on Windows.</b></p></section><section><a id="Creating_a_Project"></a> <h2>Creating a Project</h2> <p>You need somewhere for your project to reside. Create a directory somewhere and start a shell in that directory. On your command line, execute the following Maven goal:</p> -<div class="verbatim"> -<pre>mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false</pre></div> +<pre>mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false</pre> <p><i>If you have just installed Maven, it may take a while on the first run. This is because Maven is downloading the most recent artifacts (plugin jars and other files) into your local repository. You may also need to execute the command a couple of times before it succeeds. This is because the remote server may time out before your downloads are complete. Don't worry, there are ways to fix that.</i></p> <p>You will notice that the <i>generate</i> goal created a directory with the same name given as the artifactId. Change into that directory.</p> -<div class="verbatim"> -<pre>cd my-app</pre></div> +<pre>cd my-app</pre> <p>Under this directory you will notice the following <a href="../introduction/introduction-to-the-standard-directory-layout.html">standard project structure</a>.</p> -<div class="verbatim"> <pre>my-app |-- pom.xml `-- src @@ -185,11 +183,11 @@ OS name: "windows 10", version `-- com `-- mycompany `-- app - `-- AppTest.java</pre></div> -<p>The <code>src/main/java</code> directory contains the project source code, the <code>src/test/java</code> directory contains the test source, and the <code>pom.xml</code> file is the project's Project Object Model, or POM.</p><section> + `-- AppTest.java</pre> +<p>The <code>src/main/java</code> directory contains the project source code, the <code>src/test/java</code> directory contains the test source, and the <code>pom.xml</code> file is the project's Project Object Model, or POM.</p><section><a id="The_POM"></a> <h3>The POM</h3> <p>The <code>pom.xml</code> file is the core of a project's configuration in Maven. It is a single configuration file that contains the majority of information required to build a project in just the way you want. The POM is huge and can be daunting in its complexity, but it is not necessary to understand all of the intricacies just yet to use it effectively. This project's POM is:</p> -<div class="verbatim source"><pre class="prettyprint linenums"><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" +<pre><code><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> @@ -210,23 +208,21 @@ OS name: "windows 10", version <scope>test</scope> </dependency> </dependencies> -</project></pre></div></section><section> +</project></code></pre></section><section><a id="What_did_I_just_do.3F"></a> <h3>What did I just do?</h3> -<p>You executed the Maven goal <i>archetype:generate</i>, and passed in various parameters to that goal. The prefix <i>archetype</i> is the <a href="../../plugins/index.html">plugin</a> that provides the goal. If you are familiar with <a class="externalLink" href="http://ant.apache.org";>Ant</a>, you may conceive of this as similar to a task. This <i>archetype:generate</i> goal created a simple project based upon a <a href="/archetypes/maven-archetype-quickstart/">maven-archetype-quickstart</a> archetype. Suffice it to say for now that a <i>plugin</i> is a collection of <i>goals</i> with a general common purpose. For example the jboss-maven-plugin, whose purpose is "deal with various jboss items".</p></section><section> +<p>You executed the Maven goal <i>archetype:generate</i>, and passed in various parameters to that goal. The prefix <i>archetype</i> is the <a href="../../plugins/index.html">plugin</a> that provides the goal. If you are familiar with <a class="externalLink" href="http://ant.apache.org";>Ant</a>, you may conceive of this as similar to a task. This <i>archetype:generate</i> goal created a simple project based upon a <a href="/archetypes/maven-archetype-quickstart/">maven-archetype-quickstart</a> archetype. Suffice it to say for now that a <i>plugin</i> is a collection of <i>goals</i> with a general common purpose. For example the jboss-maven-plugin, whose purpose is "deal with various jboss items".</p></section><section><a id="Build_the_Project"></a> <h3>Build the Project</h3> -<div class="verbatim"> -<pre>mvn package</pre></div> +<pre>mvn package</pre> <p>The command line will print out various actions, and end with the following:</p> -<div class="verbatim"> <pre> ... [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 2.953 s [INFO] Finished at: 2019-11-24T13:05:10+01:00 -[INFO] ------------------------------------------------------------------------</pre></div> +[INFO] ------------------------------------------------------------------------</pre> <p>Unlike the first command executed (<i>archetype:generate</i>), the second is simply a single word - <i>package</i>. Rather than a <i>goal</i>, this is a <i>phase</i>. A phase is a step in the <a href="../introduction/introduction-to-the-lifecycle.html">build lifecycle</a>, which is an ordered sequence of phases. When a phase is given, Maven executes every phase in the sequence up to and including the one defined. For example, if you execute the <i>compile</i> phase, the phases that actually get executed are:</p> -<ol style="list-style-type: decimal"> +<ol style="list-style-type: decimal;"> <li>validate</li> <li>generate-sources</li> <li>process-sources</li> @@ -234,15 +230,13 @@ OS name: "windows 10", version <li>process-resources</li> <li>compile</li></ol> <p>You may test the newly compiled and packaged JAR with the following command:</p> -<div class="verbatim"> -<pre>java -cp target/my-app-1.0-SNAPSHOT.jar com.mycompany.app.App</pre></div> +<pre>java -cp target/my-app-1.0-SNAPSHOT.jar com.mycompany.app.App</pre> <p>Which will print the quintessential:</p> -<div class="verbatim"> -<pre>Hello World!</pre></div></section></section><section> +<pre>Hello World!</pre></section></section><section><a id="Java_9_or_later"></a> <h2>Java 9 or later</h2> <p>By default your version of Maven might use an old version of the <code>maven-compiler-plugin</code> that is not compatible with Java 9 or later versions. To target Java 9 or later, you should at least use version 3.6.0 of the <code>maven-compiler-plugin</code> and set the <code>maven.compiler.release</code> property to the Java release you are targetting (e.g. 9, 10, 11, 12, etc.).</p> <p>In the following example, we have configured our Maven project to use version 3.8.1 of <code>maven-compiler-plugin</code> and target Java 11:</p> -<div class="verbatim source"><pre class="prettyprint linenums"> <properties> +<pre><code> <properties> <maven.compiler.release>11</maven.compiler.release> </properties> @@ -256,9 +250,9 @@ OS name: "windows 10", version </plugin> </plugins> </pluginManagement> - </build></pre></div> -<p>To learn more about <code>javac</code>'s <code>--release</code> option, see <a class="externalLink" href="https://openjdk.java.net/jeps/247";>JEP 247</a>.</p></section><section> -<h2>Running Maven Tools</h2><section> + </build></code></pre> +<p>To learn more about <code>javac</code>'s <code>--release</code> option, see <a class="externalLink" href="https://openjdk.java.net/jeps/247";>JEP 247</a>.</p></section><section><a id="Running_Maven_Tools"></a> +<h2>Running Maven Tools</h2><section><a id="Maven_Phases"></a> <h3>Maven Phases</h3> <p>Although hardly a comprehensive list, these are the most common <i>default</i> lifecycle phases executed.</p> <ul> @@ -277,13 +271,11 @@ OS name: "windows 10", version <li><b>site</b>: generates site documentation for this project</li></ul> <p>Phases are actually mapped to underlying goals. The specific goals executed per phase is dependant upon the packaging type of the project. For example, <i>package</i> executes <i>jar:jar</i> if the project type is a JAR, and <i>war:war</i> if the project type is - you guessed it - a WAR.</p> <p>An interesting thing to note is that phases and goals may be executed in sequence.</p> -<div class="verbatim"> -<pre>mvn clean dependency:copy-dependencies package</pre></div> -<p>This command will clean the project, copy dependencies, and package the project (executing all phases up to <i>package</i>, of course).</p></section><section> +<pre>mvn clean dependency:copy-dependencies package</pre> +<p>This command will clean the project, copy dependencies, and package the project (executing all phases up to <i>package</i>, of course).</p></section><section><a id="Generating_the_Site"></a> <h3>Generating the Site</h3> -<div class="verbatim"> -<pre>mvn site</pre></div> -<p>This phase generates a site based upon information on the project's pom. You can look at the documentation generated under <code>target/site</code>.</p></section></section><section> +<pre>mvn site</pre> +<p>This phase generates a site based upon information on the project's pom. You can look at the documentation generated under <code>target/site</code>.</p></section></section><section><a id="Conclusion"></a> <h2>Conclusion</h2> <p>We hope this quick overview has piqued your interest in the versatility of Maven. Note that this is a very truncated quick-start guide. Now you are ready for more comprehensive details concerning the actions you have just performed. Check out the <a href="./index.html">Maven Getting Started Guide</a>.</p></section></section> </main> Modified: maven/website/content/guides/getting-started/windows-prerequisites.html ============================================================================== --- maven/website/content/guides/getting-started/windows-prerequisites.html (original) +++ maven/website/content/guides/getting-started/windows-prerequisites.html Sat May 11 11:53:23 2024 @@ -2,17 +2,17 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M10 from content/apt/guides/getting-started/windows-prerequisites.apt at 2024-05-11 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M18 from content/apt/guides/getting-started/windows-prerequisites.apt at 2024-05-11 | Rendered using Apache Maven Fluido Skin 2.0.0-M6 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang="en"> <head> <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-M10" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M18" /> <meta name="author" content="Benson Margulies" /> <meta name="date" content="2012-07-01" /> - <title>Maven â Maven on Windows</title> + <title>Maven</title> <link rel="stylesheet" href="../../css/apache-maven-fluido-2.0.0-M6.min.css" /> <link rel="stylesheet" href="../../css/site.css" /> <link rel="stylesheet" href="../../css/print.css" media="print" /> @@ -39,8 +39,10 @@ <div class="container-fluid"> <header> <div id="banner"> - <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><img src="../../images/apache-maven-project.png" alt="Apache Maven Site" style="" /></a></div> - <div class="pull-right"><a href="../.././" id="bannerRight"><img src="../../images/maven-logo-black-on-white.png" alt="" style="" /></a></div> + <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><h1>Apache Maven Site</h1> +</a></div> + <div class="pull-right"><a href="../.././" id="bannerRight"><h1>$esc.xml( $banner.name )</h1> +</a></div> <div class="clear"><hr/></div> </div> @@ -48,7 +50,8 @@ <ul class="breadcrumb"> <li><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Maven on Windows <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/getting-started/windows-prerequisites.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + + <li class="active ">Maven <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/getting-started/windows-prerequisites.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-11</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> @@ -128,19 +131,18 @@ </div> </header> <main id="bodyColumn" class="span10" > -<section> +<section><a id="Maven_on_Windows"></a> <h1>Maven on Windows</h1> -<p>Maven is a command-line tool for building Java (and other) programs. The Maven project provides a simple ZIP file containing a precompiled version of Maven for your convenience. There is no installer. It's up to you to set up your prerequisites and environment to run Maven on Windows.</p><section> +<p>Maven is a command-line tool for building Java (and other) programs. The Maven project provides a simple ZIP file containing a precompiled version of Maven for your convenience. There is no installer. It's up to you to set up your prerequisites and environment to run Maven on Windows.</p><section><a id="Prerequisites"></a> <h2>Prerequisites</h2> <p>Maven is written in Java (and primarily used to build Java programs). Thus, the major prerequisite is the Java SDK. You need to install the Java SDK (e.g. from <a class="externalLink" href="https://www.oracle.com/technetwork/java/javase/downloads/index.html";>Oracle's download site</a>).</p> <p>Once Java is installed, you must ensure that the commands from the Java SDK are in your PATH environment variable. Running, for example,</p> -<div class="verbatim"> -<pre>java -version</pre></div> -<p>must show the right version number.</p></section><section> +<pre>java -version</pre> +<p>must show the right version number.</p></section><section><a id="Maven_Unpacked"></a> <h2>Maven Unpacked</h2> -<p>You need to unpack the Maven distribution. Don't unpack it in the middle of your source code; pick some location and unpack it there. Let's assume that the path is <code>${maven.home}</code>.</p></section><section> +<p>You need to unpack the Maven distribution. Don't unpack it in the middle of your source code; pick some location and unpack it there. Let's assume that the path is <code>${maven.home}</code>.</p></section><section><a id="Maven_in_PATH"></a> <h2>Maven in PATH</h2> -<p>You run Maven by invoking a command-line tool: <code>mvn.cmd</code> from the <code>bin</code> directory of the Maven. To do this conveniently, <code>${maven.home}\bin</code> must be in your PATH, just like the Java SDK commands. You can add directories to your <code>PATH</code> in the control panel; the details vary by Windows version.</p></section><section> +<p>You run Maven by invoking a command-line tool: <code>mvn.cmd</code> from the <code>bin</code> directory of the Maven. To do this conveniently, <code>${maven.home}\bin</code> must be in your PATH, just like the Java SDK commands. You can add directories to your <code>PATH</code> in the control panel; the details vary by Windows version.</p></section><section><a id="Firewalls_and_Anti-virus"></a> <h2>Firewalls and Anti-virus</h2> <p>Firewall and Anti-virus sometimes prevent Java from running properly, or Windows Firewall (and various other Firewalls) actively prevent Java.exe from reaching out to the Internet to "download stuff" which is a key part of Maven. You may need to configure the Firewall or Anti-virus to add exceptions to allow such actions.</p></section></section> </main>
