mirror of https://github.com/apache/maven.git
o converting a few more docuements
git-svn-id: https://svn.apache.org/repos/asf/maven/components/trunk@321498 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Jason van Zyl
parent
59a16ca7c8
commit
e63e9f51e0
|
|
@ -33,10 +33,10 @@ Sections
|
|||
* {{{index.html#How do I compile my test sources and run my unit tests?}How do I compile my test sources and run my unit tests?}}
|
||||
|
||||
* {{{index.html#How do I create a JAR and install it in my local repository?}How do I create a JAR and install it in my local repository?}}
|
||||
|
||||
* {{{index.html#How do add resources to my JAR?}How do add resources to my JAR?}}
|
||||
|
||||
* {{{index.html#How do I filter resources against my POM?}How do I filter resources against my POM?}}
|
||||
|
||||
* {{{index.html#How do I filter resources against a properties file?}How do I filter resources against a properties file?}}
|
||||
* {{{index.html#How do I filter resource files?}How do I filter resource files?}}
|
||||
|
||||
* {{{index.html#How do I use external dependencies?}How do I use external dependencies?}}
|
||||
|
||||
|
|
@ -48,7 +48,9 @@ Sections
|
|||
|
||||
* {{{index.html#How do I use plug-ins?}How do I use plug-ins?}}
|
||||
|
||||
* {{{index.html#How do I control what version of plug-in I use?}How do I control what version of plug-in I use?}}
|
||||
* {{{index.html#How do I control what version of a plug-in I use?}How do I control what version of a plug-in I use?}}
|
||||
|
||||
* {{{index.html#How do I build more than one project at once?}How do I build more than one project at once?}}
|
||||
|
||||
[]
|
||||
|
||||
|
|
@ -255,8 +257,11 @@ Compiling 1 source file to <dir>/my-app/target/classes
|
|||
|
||||
+-----+
|
||||
|
||||
~~DJ When they run this the first time, it will take a LONG time because of downloading all the dependencies.
|
||||
~~DJ You really should say something about that here so they understand what's going on and don't get scared.
|
||||
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 quicker.
|
||||
|
||||
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 using the
|
||||
standard conventions the POM above is very small and you haven't explicity had to tell Maven where any of
|
||||
|
|
@ -269,8 +274,8 @@ Compiling 1 source file to <dir>/my-app/target/classes
|
|||
|
||||
* {How do I compile my test sources and run my unit tests?}
|
||||
|
||||
So you can now compile your applications 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).
|
||||
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*).
|
||||
|
||||
Execute the following command:
|
||||
|
||||
|
|
@ -288,20 +293,23 @@ m2 test
|
|||
[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]
|
||||
Compiling 1 source file to <dir>/my-app/target/classes
|
||||
[INFO] Nothing to compile - all classes are up to date
|
||||
[INFO] [resources:testResources]
|
||||
[INFO] [compiler:testCompile]
|
||||
Compiling 1 source file to <dir>/my-app/target/test-classes
|
||||
Compiling 1 source file to C:\Test\Maven2\test\my-app\target\test-classes
|
||||
...
|
||||
[INFO] [surefire:test]
|
||||
[INFO] Setting reports dir: <dir>/my-app/target/surefire-reports
|
||||
[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.005 sec
|
||||
[surefire] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0 sec
|
||||
|
||||
Results :
|
||||
[surefire] Tests run: 1, Failures: 0, Errors: 0
|
||||
|
|
@ -309,14 +317,21 @@ Results :
|
|||
[INFO] ----------------------------------------------------------------------------
|
||||
[INFO] BUILD SUCCESSFUL
|
||||
[INFO] ----------------------------------------------------------------------------
|
||||
[INFO] Total time: 2 seconds
|
||||
[INFO] Finished at: Mon Oct 03 15:06:22 GMT-05:00 2005
|
||||
[INFO] Final Memory: 2M/6M
|
||||
[INFO] Total time: 15 seconds
|
||||
[INFO] Finished at: Thu Oct 06 08:12:17 MDT 2005
|
||||
[INFO] Final Memory: 2M/8M
|
||||
[INFO] ----------------------------------------------------------------------------
|
||||
|
||||
+----+
|
||||
|
||||
If you simply want to compile your test sources you can execute the following which does not run your unit tests:
|
||||
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).
|
||||
|
||||
* 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).
|
||||
|
||||
If you simply want to compile your test sources (but not execute the tests), you can execute the following:
|
||||
|
||||
+----+
|
||||
|
||||
|
|
@ -324,7 +339,7 @@ Results :
|
|||
|
||||
+----+
|
||||
|
||||
Now that you can compile your application sources and compile your tests and execute them you'll want to move
|
||||
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?}
|
||||
|
|
@ -337,13 +352,13 @@ m2 package
|
|||
|
||||
+----+
|
||||
|
||||
If you take a look at the POM for this 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 and we'll talk more about this later.
|
||||
You can now take a look in the the <<<${basedir}/target>>> directory and you will see the generated JAR file.
|
||||
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 the <<<$\{basedir\}/target>>> directory and you will see the generated JAR file.
|
||||
|
||||
Now you'll want to install the artifact you've generated, the JAR file, in your local repository
|
||||
(<<<~/.m2/repository>>> is the default value). For more information on repositories you can refer to our
|
||||
{{{introduction-to-archetypes.html}Introduction to Repositories}} but now on to installing our artifact!
|
||||
Now you'll want to install the artifact you've generated (the JAR file) in your local repository
|
||||
(<<<~/.m2/repository>>> is the default location). For more information on repositories you can refer to our
|
||||
{{{introduction-to-repositories.html}Introduction to Repositories}} but let's move on to installing our artifact!
|
||||
To do so execute the following command:
|
||||
|
||||
+----+
|
||||
|
|
@ -392,7 +407,7 @@ Results :
|
|||
|
||||
+----+
|
||||
|
||||
Note that the surefire plugin looks for tests contained in files with a particular naming convention. By default
|
||||
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:
|
||||
|
||||
* <<<\*\*/\*Test.java>>>
|
||||
|
|
@ -405,25 +420,25 @@ Results :
|
|||
|
||||
And the default excludes are:
|
||||
|
||||
* <<<\*\*/Abstract\\*Test.java>>>
|
||||
* <<<\*\*/Abstract\*Test.java>>>
|
||||
|
||||
* <<<\*\*/Abstract\*TestCase.java>>>
|
||||
|
||||
[]
|
||||
|
||||
Now you have walked through setting up setting up a typical Maven project, building, testing, packaging and installing.
|
||||
This is likely the vast majority of what you will be doing with Maven and if you'ved 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
|
||||
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'ved 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 {{{../../ant/build-a1.xml}build file}} 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 as a user of Maven without requiring any additions to our POM as it is currently. To
|
||||
get any more functionality out of our example Ant build file you must keep making error prone additions.
|
||||
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.
|
||||
|
||||
So what else can you get for free? There are a great number of Maven plug-ins 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 execution the following command:
|
||||
time all you need to do to provide basic information about your project is execute the following command:
|
||||
|
||||
+----+
|
||||
|
||||
|
|
@ -431,16 +446,18 @@ m2 site:site
|
|||
|
||||
+----+
|
||||
|
||||
We'll touch on one more common usecase that can be satisfied which requires no changes to the POM that we have
|
||||
above which is packaging resources in JAR files. For this common task Maven again relies on the
|
||||
{{{introduction-to-the-standard-directory-layout.html}Standard Directory Layout}} which means by using
|
||||
standard Maven coventions you can package resources within JARs simply by placing resources in a standard
|
||||
* {How do add resources to my JAR?}
|
||||
|
||||
Another common usecase 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
|
||||
{{{introduction-to-the-standard-directory-layout.html}Standard Directory Layout}}, which means by using
|
||||
standard Maven coventions you can package resources within JARs simply by placing those resources in a standard
|
||||
directory structure.
|
||||
|
||||
You see below in our example we have added the directory <<<${basedir}/src/main/resources>>> into which we place
|
||||
You see below in our example we have added the directory <<<$\{basedir\}/src/main/resources>>> 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 <<<${basedir}/src/main/resources>>> directory are packaged in your JAR with the exact same
|
||||
structure starting at the base of the JAR
|
||||
placed within the <<<$\{basedir\}/src/main/resources>>> directory are packaged in your JAR with the exact same
|
||||
structure starting at the base of the JAR.
|
||||
|
||||
+----+
|
||||
|
||||
|
|
@ -485,16 +502,16 @@ my-app
|
|||
|
||||
+----+
|
||||
|
||||
As you can see the contents of <<<${basedir}/src/main/resources>>> can be found starting at the base of the
|
||||
JAR and you will see our <<<application.properties>>> file. You will also notice some other files there
|
||||
like <<<META-INF/MANIFEST.MF>>> and a <<<pom.xml>>> and <<<pom.properties>>> file. These come standard with
|
||||
generation of a JAR in Maven. You create your own manifest if you choose, but Maven will generate one by
|
||||
default for you if you don't. You may also modify the entries in the default manifest which we will touch on
|
||||
later. The <<<pom.xml>>> and <<<pom.properties>>> files are packaged up in the JAR so that each artifact
|
||||
produced by Maven is self-describing and it also allows you to utilize the metadata in your own application
|
||||
As you can see, the contents of <<<$\{basedir\}/src/main/resources>>> can be found starting at the base of the
|
||||
JAR and our <<<application.properties>>> file is there in the <<<META-INF>>> directory. You will also notice some other files there
|
||||
like <<<META-INF/MANIFEST.MF>>> as well as a <<<pom.xml>>> and <<<pom.properties>>> 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 <<<pom.xml>>> and <<<pom.properties>>> 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 utilities but the properties can be utilized using the standard
|
||||
Java API and looks like the following:
|
||||
Java API and look like the following:
|
||||
|
||||
+----+
|
||||
|
||||
|
|
@ -506,8 +523,8 @@ artifactId=my-app
|
|||
|
||||
+----+
|
||||
|
||||
To use resources with your unit tests you follow the same pattern except the directory you place resources in
|
||||
is ${basedir}/src/test/resources which are then availabe to you at the base of the classpath. So you would have a
|
||||
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 $\{basedir\}/src/test/resources. At this point you would have a
|
||||
project directory structure that would look like the following:
|
||||
|
||||
+---+
|
||||
|
|
@ -535,7 +552,7 @@ my-app
|
|||
`-- test.properties
|
||||
+---+
|
||||
|
||||
So in a unit test you could use a simple snippet of code like the following to access the resource required for
|
||||
In a unit test you could use a simple snippet of code like the following to access the resource required for
|
||||
testing:
|
||||
|
||||
+----+
|
||||
|
|
@ -551,7 +568,14 @@ InputStream is = Thread.currentThread().getContextClassLoader().getResourceAsStr
|
|||
|
||||
+----+
|
||||
|
||||
* {How do I filter resources against my POM?}
|
||||
* {How do I filter resource files?}
|
||||
|
||||
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 <<<$\{<property name}>\}>>>.
|
||||
The property can be one of the values defined in your pom.xml, a value defined in the user's settings.xml, a property
|
||||
defined in an external properties file, or a system property.
|
||||
|
||||
To have Maven filter resources when copying, simply set <<<filtering>>> to true for the resource directory in your pom.xml:
|
||||
|
||||
+----+
|
||||
|
||||
|
|
@ -564,7 +588,6 @@ InputStream is = Thread.currentThread().getContextClassLoader().getResourceAsStr
|
|||
<version>1.0-SNAPSHOT</version>
|
||||
<name>Maven Quick Start Archetype</name>
|
||||
<url>http://maven.apache.org</url>
|
||||
<description>Killer App</description>
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>junit</groupId>
|
||||
|
|
@ -585,16 +608,60 @@ InputStream is = Thread.currentThread().getContextClassLoader().getResourceAsStr
|
|||
|
||||
+----+
|
||||
|
||||
You'll notice that we had to add the <<<build>>>, <<<resources>>>, and <<<resource>>> elements which weren't there before.
|
||||
In addition, we had to explicitly state that the resources are located in the src/main/resources directory. All of this
|
||||
information was provided as default values previously, but because the default value for <<<filtering>>> is false, we had
|
||||
to add this to our pom.xml in order to override that default value and set <<<filtering>>> to true.
|
||||
|
||||
To reference a property defined in your pom.xml, 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 $\{pom.name\} refers to the name of the project,
|
||||
$\{pom.version\} refers to the version of the project, $\{pom.build.finalName\} 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 pom.xml for the values to be available here. Similarly, values in the user's settings.xml can be referenced
|
||||
using property names beginning with "settings" (for example, $\{settings.localRepository\} refers to the path of the user's
|
||||
local repository).
|
||||
|
||||
To continue our example, let's add a couple of properties to the application.properties file (which we put in the
|
||||
src/main/resources directory) whose values will be supplied when the resource is filtered:
|
||||
|
||||
+----+
|
||||
|
||||
# application.properties
|
||||
|
||||
application.name=${pom.name}
|
||||
application.version=${pom.version}
|
||||
|
||||
+----+
|
||||
|
||||
* {How do I filter resources against a properties file?}
|
||||
With that in place, you can execute the following command (process-resources is the build lifecycle phase where the resources are
|
||||
copied and filtered):
|
||||
|
||||
+----+
|
||||
|
||||
m2 process-resources
|
||||
|
||||
+----+
|
||||
|
||||
and the application.properties file under target/classes (and will eventually go into the jar) looks like this:
|
||||
|
||||
+----+
|
||||
|
||||
# application.properties
|
||||
application.name=Maven Quick Start Archetype
|
||||
application.version=1.0-SNAPSHOT
|
||||
|
||||
+----+
|
||||
|
||||
To reference a property defined in an external file, all you need to do is add a reference to this external file in your pom.xml.
|
||||
First, let's create our external properties file and call it src/main/filters/filter.properties:
|
||||
|
||||
+----+
|
||||
|
||||
# filter.properties
|
||||
my.filter.value=hello!
|
||||
|
||||
+----+
|
||||
|
||||
Next, we'll add a reference to this new file in the pom.xml:
|
||||
|
||||
+----+
|
||||
|
||||
|
|
@ -607,7 +674,6 @@ application.version=${pom.version}
|
|||
<version>1.0-SNAPSHOT</version>
|
||||
<name>Maven Quick Start Archetype</name>
|
||||
<url>http://maven.apache.org</url>
|
||||
<description>Killer App</description>
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>junit</groupId>
|
||||
|
|
@ -618,7 +684,7 @@ application.version=${pom.version}
|
|||
</dependencies>
|
||||
<build>
|
||||
<filters>
|
||||
<filter>src/main/filters/filters.properties</filter>
|
||||
<filter>src/main/filters/filter.properties</filter>
|
||||
</filters>
|
||||
<resources>
|
||||
<resource>
|
||||
|
|
@ -631,48 +697,87 @@ application.version=${pom.version}
|
|||
|
||||
+----+
|
||||
|
||||
+----+
|
||||
|
||||
# filtering.properties
|
||||
|
||||
environment=development
|
||||
|
||||
+----+
|
||||
|
||||
+----+
|
||||
|
||||
# application.properties
|
||||
|
||||
application.name=${pom.name}
|
||||
application.version=${pom.version}
|
||||
|
||||
environment=${environment}
|
||||
|
||||
+----+
|
||||
|
||||
* How do I filter against system properties
|
||||
|
||||
You simply specify the system property using the standard variable notion as show below:
|
||||
Then, if we add a reference to this property in the application.properties file:
|
||||
|
||||
+----+
|
||||
|
||||
# application.properties
|
||||
|
||||
application.name=${pom.name}
|
||||
application.version=${pom.version}
|
||||
message=${my.filter.value}
|
||||
|
||||
environment=${environment}
|
||||
+----+
|
||||
|
||||
the next execution of the <<<m2 process-resources>>> command will put our new property value into application.properties.
|
||||
As an alternative to defining the my.filter.value property in an external file, you could also have defined it in the <<<properties>>>
|
||||
section of your pom.xml and you'd get the same effect (notice I don't need the references to src/main/filters/filter.properties either):
|
||||
|
||||
+----+
|
||||
|
||||
<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/maven-v4_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>3.8.1</version>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
<build>
|
||||
<resources>
|
||||
<resource>
|
||||
<directory>src/main/resources</directory>
|
||||
<filtering>true</filtering>
|
||||
</resource>
|
||||
</resources>
|
||||
</build>
|
||||
<properties>
|
||||
<my.filter.value>hello</my.filter.value>
|
||||
</properties>
|
||||
</project>
|
||||
|
||||
+----+
|
||||
|
||||
Filtering resources can also get values from system properties; either the system properties built into Java (like java.version or
|
||||
user.home) or properties defined on the command line using the standard Java -D parameter. To continue the example, let's change
|
||||
our application.properties file to look like this:
|
||||
|
||||
+----+
|
||||
|
||||
# application.properties
|
||||
java.version=${java.version}
|
||||
command.line.prop=${command.line.prop}
|
||||
|
||||
+----+
|
||||
|
||||
Now, when you execute the following command (note the definition of the command.line.prop property on the command line), the
|
||||
application.properties file will contain the values from the system properties.
|
||||
|
||||
+----+
|
||||
|
||||
m2 process-resources "-Dcommand.line.prop=hello again"
|
||||
|
||||
+----+
|
||||
|
||||
|
||||
* {How do I use external dependencies?}
|
||||
|
||||
You probably already noticed a <<<dependencies>>> element in the POM we've been using as an example
|
||||
so you have in fact been using an external dependency but we'll here we'll go more in depth about how Maven's
|
||||
dependency management system works. For a thorough introduction please refer to our
|
||||
{{{introduction-to-archetypes.html}Introduction to Dependency Management}}.
|
||||
You've probably already noticed a <<<dependencies>>> 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
|
||||
{{{introduction-to-dependency-management.html}Introduction to Dependency Management}}.
|
||||
|
||||
The <<<dependencies>>> section of the pom.xml lists all of the external dependencies that particular 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):
|
||||
|
||||
+----+
|
||||
|
||||
|
|
@ -685,7 +790,6 @@ java.version=${java.version}
|
|||
<version>1.0-SNAPSHOT</version>
|
||||
<name>Maven Quick Start Archetype</name>
|
||||
<url>http://maven.apache.org</url>
|
||||
<description>Killer App</description>
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>junit</groupId>
|
||||
|
|
@ -693,32 +797,123 @@ java.version=${java.version}
|
|||
<version>3.8.1</version>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
<!--
|
||||
|
|
||||
| New external dependency
|
||||
|
|
||||
-->
|
||||
<dependency>
|
||||
<groupId>org.apache.codehaus.plexus</groupId>
|
||||
<artifactId>plexus-utils</artifactId>
|
||||
<version>1.0.4</version>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
<build>
|
||||
<filters>
|
||||
<filter>src/main/filters/filters.properties</filter>
|
||||
</filters>
|
||||
<resources>
|
||||
<resource>
|
||||
<directory>src/main/resources</directory>
|
||||
<filtering>true</filtering>
|
||||
</resource>
|
||||
</resources>
|
||||
</build>
|
||||
</project>
|
||||
|
||||
+----+
|
||||
|
||||
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 pom.xml for the project that built that dependency. The scope
|
||||
element indicates how your project uses that dependency, and can be values like <<<compile>>>, <<<test>>>, and <<<runtime>>>.
|
||||
For more information on everything you can specify for a dependency, see the {{{../../../maven-model/maven.html}Project Descriptor Reference}}.
|
||||
~~DJ: Does this link work? I can't find the document.
|
||||
For more information about the dependency mechanism as a whole, see {{{../../dependency-mechanism.html}Dependency Mechanism}}.
|
||||
|
||||
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 (<<<~/.m2/repository>>> is the default location) to find
|
||||
all dependencies. In a {{{How do I create a JAR and install it in my local repository?}previous section}}, 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 pom.xml:
|
||||
|
||||
+----+
|
||||
|
||||
<project>
|
||||
<groupId>com.mycompany.app</groupId>
|
||||
<artifactId>my-other-app</artifactId>
|
||||
...
|
||||
<dependencies>
|
||||
...
|
||||
<dependency>
|
||||
<groupId>com.mycompany.app</groupId>
|
||||
<artifactId>my-app</artifactId>
|
||||
<version>1.0-SNAPSHOT</version>
|
||||
<scope>compile</scope>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
</project>
|
||||
|
||||
+----+
|
||||
|
||||
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
|
||||
{{http://www.ibiblio.org/Maven2}}. You can also set up your own remote repository (maybe a central repository for your company) to
|
||||
use instead of or in addition to ibiblio. For more information on repositories you can refer to the
|
||||
{{{introduction-to-repositories.html}Introduction to Repositories}}.
|
||||
|
||||
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. We can browse ibiblio and look for it, or use Google
|
||||
to help by searching for "site:www.ibiblio.org maven2 log4j". The search shows a directory called /maven2/log4j/log4j (or
|
||||
/pub/packages/maven2/log4j/log4j). In that directory is a file called maven-metadata.xml. Here's what the maven-metadata.xml for
|
||||
log4j looks like:
|
||||
|
||||
+----+
|
||||
|
||||
<metadata>
|
||||
<groupId>log4j</groupId>
|
||||
<artifactId>log4j</artifactId>
|
||||
<version>1.1.3</version>
|
||||
<versioning>
|
||||
<versions>
|
||||
<version>1.1.3</version>
|
||||
<version>1.2.4</version>
|
||||
<version>1.2.5</version>
|
||||
<version>1.2.6</version>
|
||||
<version>1.2.7</version>
|
||||
<version>1.2.8</version>
|
||||
<version>1.2.11</version>
|
||||
<version>1.2.9</version>
|
||||
<version>1.2.12</version>
|
||||
</versions>
|
||||
</versioning>
|
||||
</metadata>
|
||||
|
||||
+----+
|
||||
|
||||
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). 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 pom.xml
|
||||
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 particular library you may be using already.
|
||||
|
||||
Now that we know the information we need, we can add the dependency to our 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/maven-v4_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>3.8.1</version>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>log4j</groupId>
|
||||
<artifactId>log4j</artifactId>
|
||||
<version>1.2.12</version>
|
||||
<scope>compile</scope>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
</project>
|
||||
|
||||
+----+
|
||||
|
||||
Now, when we compile the project (<<<m2 compile>>>), we'll see Maven download the log4j dependency for us.
|
||||
|
||||
~~DJ: Current
|
||||
|
||||
* {How do I deploy my jar in my remote repository?}
|
||||
|
||||
+----+
|
||||
|
|
@ -732,7 +927,6 @@ java.version=${java.version}
|
|||
<version>1.0-SNAPSHOT</version>
|
||||
<name>Maven Quick Start Archetype</name>
|
||||
<url>http://maven.apache.org</url>
|
||||
<description>Killer App</description>
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>junit</groupId>
|
||||
|
|
@ -1047,8 +1241,9 @@ m2 site:site site:deploy
|
|||
|
||||
* {How do I use plug-ins?}
|
||||
|
||||
* {How do I control what version of plug-in I use?}
|
||||
* {How do I control what version of a plug-in I use?}
|
||||
|
||||
~~http://docs.codehaus.org/display/MAVEN/Maven+Plugin+Matrix
|
||||
|
||||
* {How do I build more than one project at once?}
|
||||
|
||||
|
|
|
|||
|
|
@ -52,8 +52,6 @@ Documentation
|
|||
|
||||
* {{{mini/guide-multi-module.html}Guide to creating a multi-module build}}
|
||||
|
||||
* {{{mini/guide-multi-module.html~}Guide to creating a multi-module build}}
|
||||
|
||||
* {{{mini/guide-multiple-repositories.html}Guide to using Multiple Repositories}}
|
||||
|
||||
* {{{mini/guide-pom-properties.html}Guide to using POM properties}}
|
||||
|
|
|
|||
|
|
@ -8,6 +8,166 @@
|
|||
|
||||
Introduction to Repositories
|
||||
|
||||
~~ o Explain the standard layout of the m2 repository
|
||||
* Artifact Repositories
|
||||
|
||||
* http://docs.codehaus.org/pages/viewpage.action?pageId=22230
|
||||
A repository in Maven is used to hold build artifacts and dependencies of varying types.
|
||||
|
||||
There are strictly only two types of repositories: local and remote. The local repository refers to a copy
|
||||
on your own installation that is a cache of the remote downloads, and also contains the temporary
|
||||
build artifacts that you have not yet released.
|
||||
|
||||
Remote repositories refer to any other type of repository, accessed by a variety of protocols such as
|
||||
<<<file://>>> and <<<http://>>>. These repositories might be a truely remote repository
|
||||
set up by a third party to provide their artifacts for downloading (for example,
|
||||
<a href="http://www.ibiblio.org/maven/">Ibiblio</a> houses Maven's central repository).
|
||||
Other "remote" repositories may be <a href="../reference/internal-repositories.html">internal repositories</a>
|
||||
set up on a file or HTTP server within your company, used to share private artifacts between development teams
|
||||
and for releases.
|
||||
|
||||
The local and remote repositories are structured the same way so that scripts can easily be run on either
|
||||
side, or they can be synced for offline used. In general use, the layout of the repositories is completely
|
||||
transparent to the Maven user, however.
|
||||
|
||||
* Why not Store JARs in CVS?
|
||||
|
||||
It is not recommended that you store your JARs in CVS. Maven tries to
|
||||
promote the notion of a user local repository where JARs, or any
|
||||
project artifacts, can be stored and used for any number of builds.
|
||||
Many projects have dependencies such as XML parsers and standard utilities that
|
||||
are often replicated in typical builds. With Maven these standard utilities
|
||||
can be stored in your local repository and shared by any number of builds.
|
||||
|
||||
This has the following advantages:
|
||||
|
||||
* <<It uses less storage>> - while a repository is typically quite large, because each JAR is only kept
|
||||
in the one place it is actually saving space, even though it may not seem that way</li>
|
||||
|
||||
* <<It makes checking out a project quicker>> - initial checkout, and to a small degree updating, a
|
||||
project will be faster if there are no large binary files in CVS. While they may need to be downloaded
|
||||
again afterwards anyway, this only happens once and may not be necessary for some common JARs already in
|
||||
place.
|
||||
|
||||
* <<No need for versioning>> - CVS and other source control systems are designed for versioning files,
|
||||
but external dependencies typically don't change, or if they do their filename changes anyway to indicate the
|
||||
new version. Storing these in CVS doesn't have any added benefit over keeping them in a local artifact cache.
|
||||
|
||||
|
||||
* Using Repositories
|
||||
|
||||
In general, you should not need to do anything with the local repository on a regular basis, except clean
|
||||
it out if you are short on disk space (or erase it completely if you are willing to download everything again).
|
||||
|
||||
For the remote repositories, they are used for both downloading and uploading (if you have the permission to
|
||||
do so).
|
||||
|
||||
** Downloading from a Remote Repository">
|
||||
|
||||
Downloading in Maven is triggered by a project declaring a dependency that is not present in the local
|
||||
repository (or for a <<<SNAPSHOT>>>, when the remote repository contains one that is newer).
|
||||
By default, Maven will download from Ibiblio.
|
||||
|
||||
To override this, you need to specify a <<<repositories>>> element as follows:
|
||||
|
||||
+----+
|
||||
|
||||
<project>
|
||||
...
|
||||
<repositories>
|
||||
<repository>
|
||||
<id></id>
|
||||
<url></url>
|
||||
</repository>
|
||||
</repositories>
|
||||
...
|
||||
</project>
|
||||
|
||||
+----+
|
||||
|
||||
You can set this in your <code>~/build.properties</code> file to globally use a certain mirror, however
|
||||
note that it is common for a project to customise the repository in their <code>project.properties</code>
|
||||
and that your setting will take precedence. If you find that dependencies are not being found, check you
|
||||
have not overridden the remote repository.
|
||||
|
||||
(Future versions should allow you to use a setting of
|
||||
<<<${maven.repo.remote},http://planetmirror.com/maven>>>, but currently this causes an infinite recursion).
|
||||
|
||||
For more information on dependencies, see <a href="managing-dependencies.html">Handling Dependencies</a>.
|
||||
|
||||
* Building Offline
|
||||
|
||||
If you find you need to build your projects offline you can either use the offline switch on the CLI:
|
||||
|
||||
+---+
|
||||
|
||||
m2 -o package
|
||||
|
||||
+---+
|
||||
|
||||
Note that many plugins will honour the offline setting and not perform any operations that would connect to
|
||||
the internet. Some examples are resolving Javadoc links and link checking the site.
|
||||
|
||||
* Uploading to a Remote Repository">
|
||||
|
||||
While this is possible for any type of remote repository, you must have the permission to do so.
|
||||
To have someone upload to the central Maven repository, see {{../guide/guide-ibiblio-upload.html}Uploading to Ibiblio}}.
|
||||
|
||||
Internal Repositories
|
||||
|
||||
When using Maven, particularly in a corporate environment, connecting to the internet to download dependencies
|
||||
is not acceptable for security, speed or bandwidth reasons. For that reason, it is desirable to set up an
|
||||
internal repository to house a copy of artifacts, and to publish private artifacts to.
|
||||
|
||||
Such an internal repository can be downloaded from using HTTP or the file system (using a <code>file://</code>
|
||||
URL), and uploaded to using SCP, FTP, or a file copy.
|
||||
|
||||
Note that as far as Maven is concerned, there is nothing special about this repository: it is another
|
||||
<<remote repository>> that contains artifacts to download to a user's local cache, and is a publish
|
||||
destination for artifact releases.
|
||||
|
||||
Additionally, you may want to share the repository server with your generated project sites. For more
|
||||
information on creating and deploying sites, see <a href="../using/site.html">Creating a Site</a>.
|
||||
|
||||
* Setting up the Internal Repository
|
||||
|
||||
To set up an internal repository just requires that you have a place to put it, and then start copying
|
||||
required artifacts there using the same layout as in a remote repository such as {{{http://www.ibiblio.org/maven/}Ibiblio}}.
|
||||
|
||||
It is <not> recommended that you scrape or <<<rsync://>>> a full copy of Ibiblio as there is a large amount
|
||||
of data there. You can use a program such as <a href="http://maven-proxy.codehaus.org/">Maven Proxy</a>,
|
||||
running on your internal repository's server, to download from the internet as required and then hold
|
||||
the artifacts in your internal repository for faster downloading later.
|
||||
|
||||
The other options available are to manually download and vet releases, then copy them to the internal
|
||||
repository, or to have Maven download them for a user, and manually upload the vetted artifacts to the
|
||||
internal repository which is used for releases. This step is the only one available for artifacts where
|
||||
the license forbids their distribution automatically, such as several J2EE JARs provided by Sun.
|
||||
Refer to the {{{../mini/guide-coping-with-sun-jars.html}Guide to coping with SUN JARs}} document for more information.
|
||||
|
||||
It should be noted that Maven intends to include enhanced support for such features in the future,
|
||||
including click through licenses on downloading, and verification of signatures.
|
||||
|
||||
* Using the Internal Repository
|
||||
|
||||
Using the internal repository is quite simple. Simply make a change to add a <<<repositories>>> element:
|
||||
|
||||
+----+
|
||||
|
||||
<project>
|
||||
...
|
||||
<repositories>
|
||||
<repository>
|
||||
<id></id>
|
||||
<repository>
|
||||
</repositories>
|
||||
...
|
||||
</project>
|
||||
|
||||
+----+
|
||||
|
||||
* Deploying to the Internal Repository
|
||||
|
||||
One of the most important reasons to have one or more internal repositories is to be able to publish
|
||||
your own private releases to share.
|
||||
|
||||
To publish to the repository, you will need to have access via one of SCP, SFTP, FTP, or the filesystem.
|
||||
For example, to set up an SCP transfer. ~~ show the scp example.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,9 @@
|
|||
#!/bin/sh
|
||||
|
||||
toc=`pwd`/index.apt
|
||||
|
||||
find . -name '*~' -exec rm -rf {} \;
|
||||
|
||||
#
|
||||
# Top matter
|
||||
#
|
||||
|
|
@ -103,4 +106,4 @@ echo " * {{{development/guide-m2-development.html}Guide to Developing Maven 2.x}
|
|||
echo " " >> $toc
|
||||
echo " * {{{development/guide-building-m2.html}Guide to Building Maven 2.x}}" >> $toc
|
||||
|
||||
cat tail.apt >> $toc
|
||||
cat tail.txt >> $toc
|
||||
|
|
|
|||
|
|
@ -0,0 +1,44 @@
|
|||
------
|
||||
Maven Features
|
||||
------
|
||||
Jason van Zyl
|
||||
------
|
||||
12 October 2005
|
||||
------
|
||||
|
||||
Feature Summary
|
||||
|
||||
The following are the key features of Maven in a nutshell:
|
||||
|
||||
* Model based builds:
|
||||
Maven is able to build any number of projects into predefined output types
|
||||
such as a JAR, WAR, or distribution based on metadata about the project, without
|
||||
any need to do any scripting in most cases.
|
||||
|
||||
* Coherent site of project information:
|
||||
Using the same metadata as for the build process, Maven is able to generate a
|
||||
web site or PDF including any documentation you care to add, and adds to that
|
||||
standard reports about the state of development of the project.
|
||||
Examples of this information can be seen at the bottom of the left-hand navigation of
|
||||
this site under the "Project Information" and "Project Reports" submenus.
|
||||
|
||||
* Release management and distribution publication:
|
||||
Without much additional configuration, Maven will integrate with your source control
|
||||
system such as CVS and manage the release of a project based on a certain tag.
|
||||
It can also publish this to a distribution location for use by other projects.
|
||||
Maven is able to publish individual outputs such as a JAR, an archive including other
|
||||
dependencies and documentation, or as a source distribution.
|
||||
|
||||
* Dependency management:
|
||||
Maven encourages the use of a central repository of JARs and other dependencies. Maven
|
||||
comes with a mechanism that your project's clients can use to
|
||||
download any JARs required for building your project from a
|
||||
central JAR repository much like Perl's CPAN. This allows users
|
||||
of Maven to reuse JARs across projects and encourages communication
|
||||
between projects to ensure backward compatibility issues are
|
||||
dealt with. We are collaborating with the folks at {{{http://www.ibiblio.org}Ibiblio}} who have graciously
|
||||
allowed the central repository to live on their servers.
|
||||
|
||||
[]
|
||||
|
||||
~~ this needs to be greatly expanded and is too detailed here ... jvz
|
||||
|
|
@ -0,0 +1,135 @@
|
|||
------
|
||||
What is Maven?
|
||||
------
|
||||
Jason van Zyl
|
||||
------
|
||||
12 October 2005
|
||||
------
|
||||
|
||||
Introduction
|
||||
|
||||
Maven was originally started as an attempt to simplify the build
|
||||
processes in the Jakarta Turbine project. There were several
|
||||
projects each with their own Ant build files that were all slightly
|
||||
different and JARs were checked into CVS. We wanted a standard way to
|
||||
build the projects, a clear definition of what the project consisted
|
||||
of, an easy way to publish project information and a way to share JARs
|
||||
across several projects.
|
||||
|
||||
What resulted is a tool that can now be used for building and managing
|
||||
any Java-based project. We hope that we have created something that
|
||||
will make the day-to-day work of Java developers easier and generally
|
||||
help with the comprehension of any Java-based project.
|
||||
|
||||
Maven's Objectives
|
||||
|
||||
Maven's primary goal is to allow a developer to comprehend the
|
||||
complete state of a development effort in the shortest period of
|
||||
time. In order to attain this goal there are several areas of concern
|
||||
that Maven attempts to deal with:
|
||||
|
||||
* Making the build process easy
|
||||
|
||||
* Providing a uniform build system
|
||||
|
||||
* Providing quality project information
|
||||
|
||||
* Providing guidelines for best practices development
|
||||
|
||||
* Allowing transparent migration to new features
|
||||
|
||||
* Making the build process easy
|
||||
|
||||
While using Maven doesn't eliminate the need to know about the
|
||||
underlying mechanisms, Maven does provide a lot of shielding
|
||||
from the details.
|
||||
|
||||
* Providing a uniform build system
|
||||
|
||||
Maven allows a project to build using its project object model (POM) and
|
||||
a set of plugins that are shared by all projects using
|
||||
Maven, providing a uniform build system. Once you familiarize yourself
|
||||
with how one Maven project builds you automatically know how all Maven
|
||||
projects build saving you immense amounts of time when trying to
|
||||
navigate many projects.
|
||||
|
||||
* Providing quality project information
|
||||
|
||||
Maven provides plenty of useful project information that is in
|
||||
part taken from your POM and in part generated from your project's
|
||||
sources. For example, Maven can provide:
|
||||
|
||||
* Change log document created directly from source control
|
||||
|
||||
* Cross referenced sources
|
||||
|
||||
* Mailing lists
|
||||
|
||||
* Dependency list
|
||||
|
||||
* Unit test reports including coverage
|
||||
|
||||
[]
|
||||
|
||||
As Maven improves the information set provided will improve, all of
|
||||
which will be transparent to users of Maven.
|
||||
|
||||
Other products can also provide Maven plugins to allow their set of
|
||||
project information alongside some of the standard information given by
|
||||
Maven, all still based from the POM.
|
||||
|
||||
* Providing guidelines for best practices development
|
||||
|
||||
Maven aims to gather current principles for best practices development, and
|
||||
make it easy to guide a project in that direction.
|
||||
|
||||
For example, specification, execution, and reporting of unit tests are part of
|
||||
the normal build cycle using Maven.
|
||||
Current unit testing best practices were used as guidelines:
|
||||
|
||||
* Keeping your test source code in a separate, but parallel source tree
|
||||
|
||||
* Using test case naming conventions to locate and execute tests
|
||||
|
||||
* Have test cases setup their environment and don't rely on customizing the build for test preparation.
|
||||
|
||||
[]
|
||||
|
||||
Maven also aims to assist in project workflow such as release management and
|
||||
issue tracking.
|
||||
|
||||
Maven also suggests some guidelines on how to layout your project's directory structure
|
||||
so that once you learn the layout you can easily navigate any other project that uses
|
||||
Maven and the same defaults.
|
||||
|
||||
* Allowing transparent migration to new features
|
||||
|
||||
Maven provides an easy way for Maven clients to update their installations
|
||||
so that they can take advantage of any changes that been made to
|
||||
Maven itself.
|
||||
|
||||
Installation of new or updated plugins from third parties or Maven itself has
|
||||
been made trivial for this reason.
|
||||
|
||||
What is Maven Not?
|
||||
|
||||
You may have heard some of the following things about Maven:
|
||||
|
||||
* Maven is a site and documentation tool
|
||||
|
||||
* Maven extends Ant to let you download dependencies
|
||||
|
||||
* Maven is a set of reusable Ant scriptlets
|
||||
|
||||
[]
|
||||
|
||||
While Maven does these things, as you can read above in the "What is Maven?" section,
|
||||
these are not the only features Maven has, and it's objectives are quite different.
|
||||
|
||||
Maven does encourage best practices, but we realise that some projects may not fit with
|
||||
these ideals for historical reasons. While Maven is designed to be flexible, to an extent, in these
|
||||
situations and to the needs of different projects, it can not cater to every situation without making
|
||||
compromises to the integrity of its objectives.
|
||||
|
||||
If you decide to use Maven, and have an unusual build structure that you cannot reorganise, you may
|
||||
have to forgo some features or the use of Maven altogether.
|
||||
Loading…
Reference in New Issue