------
 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 clean install
----

  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}}.