| ------ |
| Guide to Configuring Maven |
| ------ |
| Brett Porter |
| ------ |
| 2005-04-12 |
| ------ |
| |
| ~~ Licensed to the Apache Software Foundation (ASF) under one |
| ~~ or more contributor license agreements. See the NOTICE file |
| ~~ distributed with this work for additional information |
| ~~ regarding copyright ownership. The ASF licenses this file |
| ~~ to you under the Apache License, Version 2.0 (the |
| ~~ "License"); you may not use this file except in compliance |
| ~~ with the License. You may obtain a copy of the License at |
| ~~ |
| ~~ http://www.apache.org/licenses/LICENSE-2.0 |
| ~~ |
| ~~ Unless required by applicable law or agreed to in writing, |
| ~~ software distributed under the License is distributed on an |
| ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| ~~ KIND, either express or implied. See the License for the |
| ~~ specific language governing permissions and limitations |
| ~~ under the License. |
| |
| ~~ NOTE: For help with the syntax of this file, see: |
| ~~ http://maven.apache.org/doxia/references/apt-format.html |
| |
| Configuring Maven |
| |
| Maven configuration occurs at 3 levels: |
| |
| * <Project> - most static configuration occurs in <<<pom.xml>>> |
| |
| * <Installation> - this is configuration added once for a Maven installation |
| |
| * <User> - this is configuration specific to a particular user |
| |
| The separation is quite clear - the project defines information that applies to the project, no matter who is |
| building it, while the others both define settings for the current environment. |
| |
| <<Note:>> the installation and user configuration cannot be used to add shared project information - |
| for example, setting <<<\<organization\>>>> or <<<\<distributionManagement\>>>> company-wide. |
| |
| For this, you should have your projects inherit from a company-wide parent <<<pom.xml>>>. |
| |
| ~~TODO: versioning doc that discusses this |
| |
| You can specify your user configuration in <<<$\{user.home\}/.m2/settings.xml>>>. A |
| {{{../../maven-settings/settings.html}full reference}} to the configuration file is available. This section will show how |
| to make some common configurations. Note that the file is not required - defaults will be used if it is not found. |
| |
| * Configuring your Local Repository |
| |
| The location of your local repository can be changed in your user configuration. |
| The default value is <<<$\{user.home\}/.m2/repository/>>>. |
| |
| +-------------+ |
| <settings> |
| ... |
| <localRepository>/path/to/local/repo/</localRepository> |
| ... |
| </settings> |
| +-------------+ |
| |
| <<Note:>> The local repository must be an absolute path. |
| |
| * Configuring a Proxy |
| |
| Proxy configuration can also be specified in the settings file. |
| |
| For more information, see the {{{./guide-proxies.html} Guide to using a Proxy}}. |
| |
| * Configuring Parallel Artifact Resolution |
| |
| By default, Maven 2.1.0+ will download up to 5 artifacts (from different groups) at once. To change the size of the thread pool, start Maven using |
| <<<-Dmaven.artifact.threads>>>. For example, to only download single artifacts at a time: |
| |
| ---- |
| mvn -Dmaven.artifact.threads=1 verify |
| ---- |
| |
| You may wish to set this option permanently, in which case you can use the <<<MAVEN_OPTS>>> environment variable. For example: |
| |
| ---- |
| export MAVEN_OPTS=-Dmaven.artifact.threads=3 |
| ---- |
| |
| * Security and Deployment Settings |
| |
| Repositories to deploy to are defined in a project in the <<<\<distributionManagement\>>>> section. |
| However, you cannot put your username, password, or other security settings in that project. For that reason, |
| you should add a server definition to your own settings with an |
| <<<id>>> that matches that of the deployment repository in the project. |
| |
| In addition, some repositories may require authorization to download from, so the corresponding settings can |
| be specified in a <<<server>>> element in the same way. |
| |
| Which settings are required will depend on the type of repository you are deploying to. As of the first release, |
| only SCP deployments and file deployments are supported by default, so only the following SCP configuration |
| is needed: |
| |
| +-------------+ |
| <settings> |
| ... |
| <servers> |
| <server> |
| <id>repo1</id> |
| <username>repouser</username> |
| <!-- other optional elements: |
| <password>my_login_password</password> |
| <privateKey>/path/to/identity</privateKey> (default is ~/.ssh/id_dsa) |
| <passphrase>my_key_passphrase</passphrase> |
| --> |
| </server> |
| ... |
| </servers> |
| ... |
| </settings> |
| +-------------+ |
| |
| To encrypt passwords in these sections, refer to {{{./guide-encryption.html} Encryption Settings}}. |
| |
| * Using Mirrors for Repositories |
| |
| Repositories can be declared inside a project, which means that if you have your own custom repositories, those |
| sharing your project easily get the right settings out of the box. However, you may want to use an alternative |
| mirror for a particular repository without changing the project files. Refer to {{{./guide-mirror-settings.html} Guide to Mirror Settings}} |
| for more details. |
| |
| |
| * Profiles |
| |
| Repository configuration can also be put into a profile. You can have multiple |
| profiles, with one set to active so that you can easily switch environments. |
| Read more about profiles in {{{../introduction/introduction-to-profiles.html}Introduction to Build Profiles}}. |
| |
| |
| |
| |
| * Optional configuration |
| |
| Maven will work for most tasks with the above configuration, however if you have any environmental specific configuration outside of individual |
| projects then you will need to configure settings. The following sections refer to what is available. |
| |
| |
| ** Settings |
| |
| Maven has a settings file located in the Maven installation and/or user home directory that configure environmental specifics such as: |
| |
| * HTTP proxy server |
| |
| * repository manager location |
| |
| * server authentication and passwords |
| |
| * other configuration properties |
| |
| [] |
| |
| For information on this file, see the {{{/settings.html}Settings reference}} |
| |
| ** Security |
| |
| As of Maven 2.1.0+, you can encrypt passwords in your settings file, however you must first configure a master password. For more information on |
| both server passwords and the master password, see the {{{./guide-encryption.html}Guide to Password Encryption}}. |
| |
| ** Toolchains |
| |
| As of Maven 2.0.9+, you can build a project using a specific version of JDK independent from the one Maven is running with. |
| For more information, see the {{{./guide-using-toolchains.html}Guide to Using Toolchains}}. |