Maven Getting Started Guide I

Download and Installation instructions.

Sections

• What is Maven?
• How can Maven benefit my development process?
• How do I setup Maven?
• How do I make my first Maven project?
• How do I compile my application sources?
• How do I compile my test sources and run my unit tests?
• How do I create a JAR and install it in my local repository?
• What is a SNAPSHOT version?
• How do I use plugins?
• How do I add resources to my JAR?
• How do I filter resource files?
• How do I use external dependencies?
• How do I deploy my jar in my remote repository?
• How do I create documentation?
• How do I build other types of projects?
• How do I build more than one project at once?

What is Maven?

At first glance Maven can appear to be many things, but in a nutshell Maven is an attempt to apply patterns to a project’s build infrastructure in order to promote comprehension and productivity by providing a clear path in the use of best practices. Maven is essentially a project management and comprehension tool and as such provides a way to help with managing:

乍看起来，Maven似乎有很多东西，但简而言之，Maven尝试将模式应用于项目的构建基础结构，以通过提供最佳实践的清晰路径来提高理解力和生产率。Maven本质上是一个项目管理和理解工具，因此提供了一种帮助管理的方法：

• Builds
• Documentation
• Reporting
• Dependencies
• SCMs
• Releases
• Distribution

How can Maven benefit my development process?

Maven can provide benefits for your build process by employing standard conventions and practices to accelerate your development cycle while at the same time helping you achieve a higher rate of success.

How do I setup Maven?

The defaults for Maven are often sufficient, but if you need to change the cache location or are behind a HTTP proxy, you will need to create configuration. See the Guide to Configuring Maven for more information.

How do I make my first Maven project?

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 an original pattern or model from which all other things of the same kind are made. 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 Introduction to Archetypes.

在Maven中，原型是项目的模板，该模板与一些用户输入相结合，以生成可以根据用户需求量身定制的工作Maven项目

On to creating your first project! In order to create the simplest of Maven projects, execute the following from the command line:

mvn -B archetype:generate \
  -DarchetypeGroupId=org.apache.maven.archetypes \
  -DgroupId=com.mycompany.app \
  -DartifactId=my-app

Once you have executed this command, you will notice a few things have happened. First, you will notice that a directory named my-app has been created for the new project, and this directory contains a file named pom.xml that should look like this:

一旦执行了此命令，您将注意到发生了一些事情。首先，您会注意到已经为新项目创建了名为my-app的目录，并且该目录包含名为pom.xml的文件，该文件应如下所示：

<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>
  <groupId>com.mycompany.app</groupId>
  <artifactId>my-app</artifactId>
  <packaging>jar</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>Maven Quick Start Archetype</name>
  <url>http://maven.apache.org</url>
  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>4.11</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>

pom.xml 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 Introduction to the POM.

pom.xml包含此项目的项目对象模型(POM)。POM是Maven中的基本工作单元。要记住这一点很重要，因为Maven本质上是以项目为中心的，因为一切都围绕项目的概念而运作。简而言之，POM包含有关您的项目的所有重要信息，并且实质上是一站式购买以查找与您的项目相关的任何信息。了解POM非常重要，因此鼓励新用户参考POM简介。

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:

这是一个非常简单的POM，但仍显示每个POM包含的关键元素，因此让我们逐步了解它们，以使您熟悉POM的要点：

• project This is the top-level element in all Maven pom.xml files.

  这是所有Maven pom.xml文件中的顶级元素

• modelVersion This element indicates what version of the object model this POM is using. The version of the model itself changes very infrequently but it is mandatory in order to ensure stability of use if and when the Maven developers deem it necessary to change the model.

  该元素指示此POM使用的对象模型的版本。模型本身的版本很少更改，但是在Maven开发人员认为有必要更改模型时，为了确保使用的稳定性，它是强制性的

• groupId This element indicates the unique identifier of the organization or group that created the project. The groupId is one of the key identifiers of a project and is typically based on the fully qualified domain name of your organization. For example org.apache.maven.plugins is the designated groupId for all Maven plugins.

  此元素指示创建项目的组织或组的唯一标识符。groupId是项目的关键标识符之一，通常基于组织的完全限定域名。例如，org.apache.maven.plugins是所有Maven插件的指定groupId

• artifactId This element indicates the unique base name of the primary artifact being generated by this project. The primary artifact for a project is typically a JAR file. Secondary artifacts like source bundles also use the artifactId as part of their final name. A typical artifact produced by Maven would have the form -. (for example, myapp-1.0.jar).

  该元素指示此项目正在生成的主要工件的唯一基础名称。项目的主要工件通常是一个JAR文件。诸如源包之类的辅助工件也使用artifactId作为其最终名称的一部分。Maven生成的典型工件将具有-。的形式（例如，myapp-1.0.jar）

• packaging This element indicates the package type to be used by this artifact (e.g. JAR, WAR, EAR, etc.). This not only means if the artifact produced is JAR, WAR, or EAR but can also indicate a specific lifecycle to use as part of the build process. (The lifecycle is a topic we will deal with further on in the guide. For now, just keep in mind that the indicated packaging of a project can play a part in customizing the build lifecycle.) The default value for the packaging element is JAR so you do not have to specify this for most projects.

  此元素指示此工件使用的包类型（例如JAR，WAR，EAR等）。这不仅意味着生成的工件是JAR，WAR还是EAR，而且还可以指示要在构建过程中使用的特定生命周期。（生命周期是我们将在指南中进一步处理的主题。现在，请记住，项目的指定包装可以在定制构建生命周期中发挥作用。）Packaging元素的默认值为JAR。因此您不必为大多数项目指定此设置

• version This element indicates the version of the artifact generated by the project. Maven goes a long way to help you with version management and you will often see the SNAPSHOT designator in a version, which indicates that a project is in a state of development. We will discuss the use of snapshots and how they work further on in this guide.

  该元素指示项目生成的工件的版本。Maven在帮助您进行版本管理方面大有帮助，您经常会在版本中看到SNAPSHOT标记，这表明项目处于开发状态。在本指南中，我们将讨论快照的用法以及快照的进一步工作方式。

• name This element indicates the display name used for the project. This is often used in Maven’s generated documentation.

  此元素指示用于项目的显示名称。这通常在Maven的生成文档中使用。

• url This element indicates where the project’s site can be found. This is often used in Maven’s generated documentation.

  此元素指示可以在哪里找到项目的站点。这通常在Maven的生成文档中使用。

• description This element provides a basic description of your project. This is often used in Maven’s generated documentation.

  此元素提供您的项目的基本描述。这通常在Maven的生成文档中使用。

Now let’s get back to the project at hand. After the archetype generation of your first project you will also notice that the following directory structure has been created:

my-app
|-- pom.xml
`-- src
    |-- main
    |   `-- java
    |       `-- com
    |           `-- mycompany
    |               `-- app
    |                   `-- App.java
    `-- test
        `-- java
            `-- com
                `-- mycompany
                    `-- app
                        `-- AppTest.java

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 ${basedir}/src/main/java and test sources reside in ${basedir}/src/test/java, where ${basedir} represents the directory containing pom.xml).

如您所见，从原型创建的项目具有一个POM，一个用于应用程序源的源树和一个用于测试源的源树。这是Maven项目的标准布局（应用程序源位于$ {basedir}/src/main/java中，测试源位于$basedir/src/test/java中，其中${basedir}代表包含pom的目录.xml）

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 Introduction to the Standard Directory Layout.

如果要手动创建Maven项目，则这是建议使用的目录结构。这是一个Maven约定

Now that we have a POM, some application sources, and some test sources you are probably asking…

How do I compile my application sources?

Change to the directory where pom.xml is created by archetype:generate and execute the following command to compile your application sources:

mvn compile

Upon executing this command you should see output like the following:

[INFO] ----------------------------------------------------------------------------
[INFO] Building Maven Quick Start Archetype
[INFO]    task-segment: [compile]
[INFO] ----------------------------------------------------------------------------
[INFO] artifact org.apache.maven.plugins:maven-resources-plugin: \
  checking for updates from central
...
[INFO] artifact org.apache.maven.plugins:maven-compiler-plugin: \
  checking for updates from central
...
[INFO] [resources:resources]
...
[INFO] [compiler:compile]
Compiling 1 source file to <dir>/my-app/target/classes
[INFO] ----------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ----------------------------------------------------------------------------
[INFO] Total time: 3 minutes 54 seconds
[INFO] Finished at: Fri Sep 23 15:48:34 GMT-05:00 2005
[INFO] Final Memory: 2M/6M
[INFO] ----------------------------------------------------------------------------

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.

第一次执行此（或任何其他）命令时，Maven将需要下载执行该命令所需的所有插件和相关依赖项。在全新安装的Maven中，这可能需要一段时间（在上面的输出中，它花费了将近4分钟）。如果再次执行命令，Maven现在将拥有所需的内容，因此它不需要下载任何新内容，并且能够更快地执行命令.

As you can see from the output, the compiled classes were placed in ${basedir}/target/classes, 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 Ant to accomplish the same thing.

从输出中可以看到，已编译的类放在${basedir}/target/classes中，这是Maven使用的另一个标准约定。因此，如果您是一个敏锐的观察者，您会注意到，使用标准约定，上面的POM很小，您不必显式地告诉Maven您的任何来源或输出应该去哪里。通过遵循标准的Maven约定，您可以轻松完成很多工作！

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!

所显示的Ant脚本的大小与上面显示的POM几乎相同

How do I compile my test sources and run my unit tests?

Execute the following command:

mvn test

Upon executing this command you should see output like the following:

[INFO] ----------------------------------------------------------------------------
[INFO] Building Maven Quick Start Archetype
[INFO]    task-segment: [test]
[INFO] ----------------------------------------------------------------------------
[INFO] artifact org.apache.maven.plugins:maven-surefire-plugin: \
  checking for updates from central
...
[INFO] [resources:resources]
[INFO] [compiler:compile]
[INFO] Nothing to compile - all classes are up to date
[INFO] [resources:testResources]
[INFO] [compiler:testCompile]
Compiling 1 source file to C:\Test\Maven2\test\my-app\target\test-classes
...
[INFO] [surefire:test]
[INFO] Setting reports dir: C:\Test\Maven2\test\my-app\target/surefire-reports
 
-------------------------------------------------------
 T E S T S
-------------------------------------------------------
[surefire] Running com.mycompany.app.AppTest
[surefire] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0 sec
 
Results :
[surefire] Tests run: 1, Failures: 0, Errors: 0
 
[INFO] ----------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ----------------------------------------------------------------------------
[INFO] Total time: 15 seconds
[INFO] Finished at: Thu Oct 06 08:12:17 MDT 2005
[INFO] Final Memory: 2M/8M
[INFO] ----------------------------------------------------------------------------

Some things to notice about the output:

• 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).

  这次，Maven下载了更多的依赖项。这些是执行测试所必需的依赖项和插件（它已经具有编译所需的依赖项，因此不会再次下载它们）

• 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).

  在编译和执行测试之前，Maven会编译主代码（所有这些类都是最新的，因为自上次编译以来我们没有进行任何更改）

If you simply want to compile your test sources (but not execute the tests), you can execute the following:

如果只想编译测试源（而不执行测试），则可以执行以下操作：

mvn test-compile

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 …

How do I create a JAR and install it in my local repository?

Making a JAR file is straight forward enough and can be accomplished by executing the following command:

mvn package

If you take a look at the POM for your project you will notice the packaging element is set to jar. This is how Maven knows to produce a JAR file from the above command (we’ll talk more about this later). You can now take a look in the ${basedir}/target directory and you will see the generated JAR file.

如果查看项目的POM，您会注意到packaging元素设置为jar。这就是Maven知道如何通过上述命令生成JAR文件的方式。现在，可以在${basedir}/target目录中查看，您将看到生成的JAR文件。

Now you’ll want to install the artifact you’ve generated (the JAR file) in your local repository (${user.home}/.m2/repository is the default location). For more information on repositories you can refer to our Introduction to Repositories but let’s move on to installing our artifact! To do so execute the following command:

现在，您要在本地存储库中安装生成的工件（JAR文件）（${user.home}/.m2/ repository是默认位置）有关存储库的更多信息，您可以参考存储库简介，继续安装我们的工件！为此，请执行以下命令：

mvn install

Upon executing this command you should see the following output:

[INFO] ----------------------------------------------------------------------------
[INFO] Building Maven Quick Start Archetype
[INFO]    task-segment: [install]
[INFO] ----------------------------------------------------------------------------
[INFO] [resources:resources]
[INFO] [compiler:compile]
Compiling 1 source file to <dir>/my-app/target/classes
[INFO] [resources:testResources]
[INFO] [compiler:testCompile]
Compiling 1 source file to <dir>/my-app/target/test-classes
[INFO] [surefire:test]
[INFO] Setting reports dir: <dir>/my-app/target/surefire-reports
 
-------------------------------------------------------
 T E S T S
-------------------------------------------------------
[surefire] Running com.mycompany.app.AppTest
[surefire] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.001 sec
 
Results :
[surefire] Tests run: 1, Failures: 0, Errors: 0
 
[INFO] [jar:jar]
[INFO] Building jar: <dir>/my-app/target/my-app-1.0-SNAPSHOT.jar
[INFO] [install:install]
[INFO] Installing <dir>/my-app/target/my-app-1.0-SNAPSHOT.jar to \
   <local-repository>/com/mycompany/app/my-app/1.0-SNAPSHOT/my-app-1.0-SNAPSHOT.jar
[INFO] ----------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ----------------------------------------------------------------------------
[INFO] Total time: 5 seconds
[INFO] Finished at: Tue Oct 04 13:20:32 GMT-05:00 2005
[INFO] Final Memory: 3M/8M
[INFO] ----------------------------------------------------------------------------

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: