mirror of https://github.com/apache/maven.git
source format only
This commit is contained in:
Manfred Moser
rfscholte
parent
1fcc45afe3
commit
bdb5b52ca4
|
|
@ -1,41 +1,49 @@
|
|||
# Maven Wrapper
|
||||
|
||||
The Maven Wrapper is an easy way to ensure a user of your Maven build has everything necessary to run your Maven build.
|
||||
Why might this be necessary? Maven to date has been very stable for users, is available on most systems or is easy to
|
||||
procure: but with many of the recent changes in Maven it will be easier for users to have a fully encapsulated build
|
||||
setup provided by the project. With the Maven Wrapper this is very easy to do and it's a great idea borrowed from Gradle.
|
||||
The Maven Wrapper is an easy way to ensure a user of your Maven build has
|
||||
everything necessary to run your Maven build.
|
||||
|
||||
The easiest way to setup the Maven Wrapper for your project is to use the [Takari Maven Plugin][1] with its provided
|
||||
`wrapper` goal. To add or update all the necessary Maven Wrapper files to your project execute the following command:
|
||||
_Why might this be necessary?_ Maven to date has been very stable for users, is
|
||||
available on most systems or is easy to procure: but with many of the recent
|
||||
changes in Maven it will be easier for users to have a fully encapsulated build
|
||||
setup provided by the project. With the Maven Wrapper this is very easy to do
|
||||
and it's a great idea borrowed from Gradle.
|
||||
|
||||
```
|
||||
The easiest way to setup the Maven Wrapper for your project is to use the
|
||||
[Takari Maven Plugin][1] with its provided `wrapper` goal. To add or update all
|
||||
the necessary Maven Wrapper files to your project execute the following command:
|
||||
|
||||
```bash
|
||||
mvn -N io.takari:maven:0.7.6:wrapper
|
||||
```
|
||||
|
||||
> Note: The default usage should be `mvn -N io.takari:maven:wrapper` but for some
|
||||
> users this seem to result in usage of an old version of the wrapper and therefore
|
||||
> installation of older Maven defaults and so on.
|
||||
> Note: The default usage should be `mvn -N io.takari:maven:wrapper` but for
|
||||
> some users this seem to result in usage of an old version of the wrapper and
|
||||
> therefore installation of older Maven defaults and so on.
|
||||
|
||||
Normally you instruct users to run the `mvn` command like the following:
|
||||
|
||||
```
|
||||
$ mvn clean install
|
||||
```bash
|
||||
mvn clean install
|
||||
```
|
||||
|
||||
But now, with a Maven Wrapper setup, you can instruct users to run wrapper scripts:
|
||||
But now, with a Maven Wrapper setup, you can instruct users to run wrapper
|
||||
scripts:
|
||||
|
||||
```
|
||||
$ ./mvnw clean install
|
||||
```bash
|
||||
./mvnw clean install
|
||||
```
|
||||
|
||||
or on Windows
|
||||
|
||||
```
|
||||
$ mvnw.cmd clean install
|
||||
```bash
|
||||
mvnw.cmd clean install
|
||||
```
|
||||
|
||||
A normal Maven build will be executed with the one important change that if the user doesn't have the necessary version
|
||||
of Maven specified in `.mvn/wrapper/maven-wrapper.properties` it will be downloaded for the user first.
|
||||
A normal Maven build will be executed with the one important change that if the
|
||||
user doesn't have the necessary version of Maven specified in
|
||||
`.mvn/wrapper/maven-wrapper.properties` it will be downloaded for the user
|
||||
first.
|
||||
|
||||
## Supported Systems
|
||||
|
||||
|
|
@ -53,17 +61,20 @@ For all those *nix operating systems, various shells should work including
|
|||
* dash
|
||||
* zsh
|
||||
|
||||
In terms of Apache Maven versions itself, the wrapper should work with any Maven 3.x version and it defaults to the
|
||||
latest release - currently 3.6.1. We do NOT plan to support the deprecated, EOL'ed Maven 2.x.
|
||||
In terms of Apache Maven versions itself, the wrapper should work with any Maven
|
||||
3.x version and it defaults to the latest release - currently 3.6.1. We do NOT
|
||||
plan to support the deprecated, EOL'ed Maven 2.x.
|
||||
|
||||
The maven-wrapper itself is compiled to work with Java 5. The Takari Maven Plugin for installation however uses Java 7.
|
||||
Once the wrapper is installed with the plugin you should be able to use the wrapper on the project with Java 5 and up.
|
||||
This is however not really tested by the committers.
|
||||
The maven-wrapper itself is compiled to work with Java 5. The Takari Maven
|
||||
Plugin for installation however uses Java 7. Once the wrapper is installed with
|
||||
the plugin you should be able to use the wrapper on the project with Java 5 and
|
||||
up. This is however not really tested by the committers.
|
||||
|
||||
## Changes
|
||||
|
||||
Please check out the [changelog](./CHANGELOG.md) for more information about our releases.
|
||||
|
||||
Please check out the [changelog](./CHANGELOG.md) for more information about our
|
||||
releases.
|
||||
|
||||
## Verbose Mode
|
||||
|
||||
The wrapper supports a verbose mode in which it outputs further information. It
|
||||
|
|
@ -74,8 +85,8 @@ By default it is off.
|
|||
## Usage without Binary JAR
|
||||
|
||||
By default, the Maven Wrapper JAR archive is added to the using project as small
|
||||
binary file `.mvn/wrapper/maven-wrapper.jar`. It is used to bootstrap the download and
|
||||
invocation of Maven from the wrapper shell scripts.
|
||||
binary file `.mvn/wrapper/maven-wrapper.jar`. It is used to bootstrap the
|
||||
download and invocation of Maven from the wrapper shell scripts.
|
||||
|
||||
If your project is not allowed to contain binary files like this, you can
|
||||
configure your version control system to exclude checkin/commit of the wrapper
|
||||
|
|
@ -83,32 +94,36 @@ jar.
|
|||
|
||||
If the JAR is not found to be available by the scripts they will attempt to
|
||||
download the file from the URL specified in
|
||||
`.mvn/wrapper/maven-wrapper.properties` under `wrapperUrl` and put it in place. The
|
||||
download is attempted via curl, wget and, as last resort, by compiling the
|
||||
`./mvn/wrapper/MavenWrapperDownloader.java` file and executing the resulting class.
|
||||
`.mvn/wrapper/maven-wrapper.properties` under `wrapperUrl` and put it in place.
|
||||
The download is attempted via curl, wget and, as last resort, by compiling the
|
||||
`./mvn/wrapper/MavenWrapperDownloader.java` file and executing the resulting
|
||||
class.
|
||||
|
||||
If your Maven repository is password protected you can specify your username via the
|
||||
environment variable `MVNW_USERNAME` and the password via the environment
|
||||
If your Maven repository is password protected you can specify your username via
|
||||
the environment variable `MVNW_USERNAME` and the password via the environment
|
||||
variable `MVNW_PASSWORD`.
|
||||
|
||||
## Using a Different Version of Maven
|
||||
|
||||
To switch the version of Maven used to build a project you can initialize it using
|
||||
To switch the version of Maven used to build a project you can initialize it
|
||||
using:
|
||||
|
||||
```
|
||||
```bash
|
||||
mvn -N io.takari:maven:0.7.6:wrapper -Dmaven=3.3.3
|
||||
```
|
||||
|
||||
which works for any version except snapshots. Once you have a wrapper you can change its version by setting the
|
||||
`distributionUrl` in `.mvn/wrapper/maven-wrapper.properties`, e.g.
|
||||
which works for any version except snapshots. Once you have a wrapper you can
|
||||
change its version by setting the `distributionUrl` in
|
||||
`.mvn/wrapper/maven-wrapper.properties`, e.g.
|
||||
|
||||
```
|
||||
```bash
|
||||
distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.5.4/apache-maven-3.5.4-bin.zip
|
||||
```
|
||||
|
||||
## Using Basic Authentication for Distribution Download
|
||||
|
||||
To download Maven from a location that requires Basic Authentication you have 2 options:
|
||||
To download Maven from a location that requires Basic Authentication you have 2
|
||||
options:
|
||||
|
||||
1. Set the environment variables MVNW_USERNAME and MVNW_PASSWORD
|
||||
|
||||
|
|
@ -117,8 +132,6 @@ To download Maven from a location that requires Basic Authentication you have 2
|
|||
2. add user and password to the distributionUrl like that:
|
||||
`distributionUrl=https://username:password@<yourserver>/maven2/org/apache/maven/apache-maven/3.2.1/apache-maven-3.2.1-bin.zip`
|
||||
|
||||
|
||||
|
||||
[1]: https://github.com/takari/takari-maven-plugin
|
||||
|
||||
## Specifying Maven Distribution Base Path
|
||||
|
|
@ -150,13 +163,14 @@ used.
|
|||
|
||||
To test Maven wrapper usage:
|
||||
|
||||
- ensure you are building on a Unix filesystem with correct mounting for executable flag setting
|
||||
- ensure you are building on a Unix filesystem with correct mounting for
|
||||
executable flag setting
|
||||
- build the maven-wrapper as snapshot version
|
||||
- update version in takari-maven-plugin
|
||||
- build takari-maven-plugin
|
||||
- use on test project with takari-maven-plugin version
|
||||
|
||||
```
|
||||
```bash
|
||||
mvn -N -X io.takari:maven:0.7.6-SNAPSHOT:wrapper
|
||||
```
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue