| ---- |
| Settings Reference |
| ----- |
| Eric Redmond |
| ----- |
| 10 September 2006 |
| ----- |
| |
| Settings Reference |
| |
| [[1]] {{{#Introduction}Introduction}} |
| |
| [[1]] {{{#Quick Overview}Quick Overview}} |
| |
| [[2]] {{{#Settings Details}Settings Details}} |
| |
| [[1]] {{{#Simple Values}Simple Values}} |
| |
| [[2]] {{{#Servers}Servers}} |
| |
| [[3]] {{{#Mirrors}Mirrors}} |
| |
| [[4]] {{{#Proxies}Proxies}} |
| |
| [[5]] {{{#Profiles}Profiles}} |
| |
| [[1]] {{{#Activation}Activation}} |
| |
| [[2]] {{{#Repositories}Repositories}} |
| |
| [[3]] {{{#Plugin Repositories}Plugin Repositories}} |
| |
| [[6]] {{{#Active Profiles}Active Profiles}} |
| |
| [] |
| |
| {Introduction} |
| |
| * {Quick Overview} |
| |
| The <<<settings>>> element in the <<<settings.xml>>> file contains elements used to define values |
| which configure Maven execution in various ways, like the <<<pom.xml>>>, but should not be bundled to |
| any specific project, or distributed to an audience. These include values such as the local repository |
| location, alternate remote repository servers, and authentication information. There are two |
| locations where a <<<settings.xml>>> file may live: |
| |
| * The Maven install: <<<$M2_HOME/conf/settings.xml>>> |
| |
| * A user's install: <<<$\{user.dir\}/.m2/settings.xml>>> |
| |
| [] |
| |
| Here is an overview of the top elements under <<<settings>>>: |
| |
| +------------------------------------+ |
| <settings> |
| <localRepository/> |
| <interactiveMode/> |
| <usePluginRegistry/> |
| <offline/> |
| <pluginGroups/> |
| <servers/> |
| <mirrors/> |
| <proxies/> |
| <profiles/> |
| <activeProfiles/> |
| </settings> |
| +------------------------------------+ |
| |
| {Settings Details} |
| |
| * {Simple Values} |
| |
| Half of the top-level <<<settings>>> elements are simple values, representing a range of |
| values which describe elements of the build system that are active full-time. |
| |
| +------------------------------------+ |
| <settings> |
| <localRepository>${user.dir}/.m2/repository</localRepository> |
| <interactiveMode>true</interactiveMode> |
| <usePluginRegistry>false</usePluginRegistry> |
| <offline>false</offline> |
| <pluginGroups> |
| <pluginGroup>org.codehaus.mojo</pluginGroup> |
| </pluginGroups> |
| ... |
| </settings> |
| +------------------------------------+ |
| |
| * <<localRepository>>: |
| This value is the path of this build system's local repository. The default value is |
| <<<${user.dir}/.m2/repository>>>. This element is especially useful for a main build |
| server allowing all logged-in users to build from a common local repository. |
| |
| * <<interactiveMode>>: |
| <<<true>>> if Maven should attempt to interact with the user for input, <<<false>>> if not. |
| Defaults to <<<true>>>. |
| |
| * <<usePluginRegistry>>: |
| <<<true>>> if Maven should use the <<<$\{user.dir\}/.m2/plugin-registry.xml>>> file to manage plugin |
| versions, defaults to <<<false>>>. <Note that for the current version of Maven 2.0, the |
| plugin-registry.xml file should not be depended upon. Consider it dormant for now.> |
| |
| * <<offline>>: |
| <<<true>>> if this build system should operate in offline mode, defaults to <<<false>>>. |
| This element is useful for build servers which cannot connect to a remote repository, |
| either because of network setup or security reasons. |
| |
| * <<pluginGroups>>: |
| This element contains a list of <<<pluginGroup>>> elements, each contains a groupId. The |
| list is searched when a plugin is used and the groupId is not provided in the command line. |
| This list contains <<<org.apache.maven.plugins>>> by default. For example, given the above |
| settings the Maven command-line may execute <<<org.codehaus.mojo:castor-maven-plugin:generate>>> |
| with the truncated command: |
| |
| ------------------------------------ |
| mvn castor-maven-plugin:generate |
| ------------------------------------ |
| |
| [] |
| |
| * {Servers} |
| |
| The <<<distributionManagement>>> element of the POM defines the repositories for deploment. |
| However, certain settings such as <<<username>>> and <<<password>>> should not be distributed |
| along with the <<<pom.xml>>>. This type of information should exist on the build server in the |
| <<<settings.xml>>>. |
| |
| +------------------------------------+ |
| <settings> |
| ... |
| <servers> |
| <server> |
| <id>server001</id> |
| <username>my_login</username> |
| <password>my_password</password> |
| <privateKey>${usr.home}/.ssh/id_dsa</privateKey> |
| <passphrase>some_passphrase</passphrase> |
| <filePermissions>664</filePermissions> |
| <directoryPermissions>775</directoryPermissions> |
| <configuration></configuration> |
| </server> |
| </servers> |
| ... |
| </settings> |
| +------------------------------------+ |
| |
| * <<id>>: |
| This is the ID of the server <(not of the user to login as)> that matches the <<<distributionManagement>>> |
| <<<repository>>> element's <<<id>>>. |
| |
| * <<username>>, <<password>>: |
| These elements appear as a pair denoting the login and password required to authenticate to this |
| server. |
| |
| * <<privateKey>>, <<passphrase>>: |
| Like the previous two elements, this pair specifies a path to a private key (default is |
| <<<${usr.home}/.ssh/id_dsa>>>) and a <<<passphrase>>>, if required. The <<<passphrase>>> and <<<password>>> elements |
| may be externalized in the future, but for now they must be set plain-text in the <<<settings.xml>>> file. |
| |
| * <<filePermissions>>, <<directoryPermissions>>: |
| When a repository file or directory is created on deployment, these are the permissions to use. |
| The legal values of each is a three digit number corrosponding to *nix file permissions, ie. 664, or 775. |
| |
| [] |
| |
| * {Mirrors} |
| |
| +------------------------------------+ |
| <settings> |
| ... |
| <mirrors> |
| <mirror> |
| <id>planetmirror.com</id> |
| <name>PlanetMirror Australia</name> |
| <url>http://downloads.planetmirror.com/pub/maven2</url> |
| <mirrorOf>central</mirrorOf> |
| </mirror> |
| </mirrors> |
| ... |
| </settings> |
| +------------------------------------+ |
| |
| * <<id>>, <<name>>: |
| The unique identifier and readable name of this mirror. The <<<id>>> is used to differentiate between |
| <<<mirror>>> elements. |
| |
| * <<url>>: |
| The base URL of this mirror. The build system will use prepend this URL to connect to a |
| repository rather than the default server URL. |
| |
| * <<mirrorOf>>: |
| The <<<id>>> of the server that this is a mirror of. For example, to point to a mirror |
| of the Maven <<<central>>> server ({{http://repo1.maven.org/maven2}}), set this element to |
| <<<central>>>. This must not match the mirror <<<id>>>. |
| |
| [] |
| |
| * {Proxies} |
| |
| +------------------------------------+ |
| <settings> |
| ... |
| <proxies> |
| <proxy> |
| <id>myproxy</id> |
| <active>true</active> |
| <protocol>http</protocol> |
| <host>proxy.somewhere.com</host> |
| <port>8080</port> |
| <username>proxyuser</username> |
| <password>somepassword</password> |
| <nonProxyHosts>*.google.com|ibiblio.org</nonProxyHosts> |
| </proxy> |
| </proxies> |
| ... |
| </settings> |
| +------------------------------------+ |
| |
| * <<id>>: |
| The unique identifier for this proxy. This is used to differentiate between <<<proxy>>> elements. |
| |
| * <<active>>: |
| <<<true>>> if this proxy is active. This is useful for declaring a set of proxies, but only one may be |
| active at a time. |
| |
| * <<protocol>>, <<host>>, <<port>>: |
| The <<<protocol://host:port>>> of the proxy, seperated into discrete elements. |
| |
| * <<username>>, <<password>>: |
| These elements appear as a pair denoting the login and password required to authenticate to this |
| proxy server. |
| |
| * <<nonProxyHosts>>: |
| This is a list of hosts which should not be proxied. The delimiter of the list is the expected type of |
| the proxy server; the example above is pipe delimited - comma delimited is also common. |
| |
| [] |
| |
| * {Profiles} |
| |
| The <<<profile>>> element in the <<<settings.xml>>> is a truncated version of the <<<pom.xml>>> |
| <<<profile>>> element. It consists of the <<<activation>>>, <<<repositories>>>, <<<pluginRepositories>>> |
| and <<<properties>>> elements. The <<<profile>>> elements only include these four elements because they |
| concerns themselves with the build system as a whole (which is the role of the <<<settings.xml>>> file), |
| not about individual project object model settings. |
| |
| If a profile is active from <<<settings>>>, its values will override any equivalently ID'd profiles in a |
| POM or <<<profiles.xml>>> file. |
| |
| ** {Activation} |
| |
| Activations are the key of a profile. Like the POM's profiles, the power of a profile comes from its ability |
| to modify some values only under certain circumstances; those circumstances are specified via an <<<activation>>> |
| element. |
| |
| +------------------------------------+ |
| <settings> |
| ... |
| <profiles> |
| <profile> |
| <id>test</id> |
| <activation> |
| <activeByDefault>false</activeByDefault> |
| <jdk>1.5</jdk> |
| <os> |
| <name>Windows XP</name> |
| <family>Windows</family> |
| <arch>x86</arch> |
| <version>5.1.2600</version> |
| </os> |
| <property> |
| <name>mavenVersion</name> |
| <value>2.0.3</value> |
| </property> |
| <file> |
| <exists>${basedir}/file2.properties</exists> |
| <missing>${basedir}/file1.properties</missing> |
| </file> |
| </activation> |
| ... |
| </profile> |
| </profiles> |
| ... |
| </settings> |
| +------------------------------------+ |
| |
| Activation occurs when all specified criteria have been met, though not all are required at once. |
| |
| * <<jdk>>: |
| <<<activation>>> has a built in, Java-centric check in the <<<jdk>>> element. This will activate if the test |
| is run under a jdk version number that matches the prefix given. In the above example, <<<1.5.0_06>>> |
| will match. |
| |
| * <<os>>: |
| The <<<os>>> element can define some operating system specific properties shown above. |
| |
| * <<property>>: |
| The <<<profile>>> will activate if Maven detects a property (a value which can be dereferenced within the POM by <<<$\{name\}>>>) |
| of the corresponding <<<name=value>>> pair. |
| |
| * <<file>>: |
| Finally, a given filename may activate the <<<profile>>> by the <<<existence>>> of a file, or if it |
| is <<<missing>>>. |
| |
| [] |
| |
| The <<<activation>>> element is not the only way that a <<<profile>>> may be activated. |
| The <<<settings.xml>>> file's <<<activeProfile>>> element may contain the profile's <<<id>>>. They may also be |
| activated explicitly through the command line via a comma separated list after the <<<P>>> flag (e.g. <<<-P test>>>). |
| |
| <To see which profile will activate in a certain build, use the> <<<maven-help-plugin>>>. |
| |
| ------- |
| mvn help:active-profiles |
| ------- |
| |
| ** Properties |
| |
| Maven properties are value placeholder, like properties in Ant. Their values are accessible |
| anywhere within a POM by using the notation <<<$\{X\}>>>, where <<<X>>> is the property. |
| They come in five different styles, all accessible from the <<<settings.xml>>> file: |
| |
| [[1]] <<<env.X>>>: Prefixing a variable with "env." will return the shells environment variable. For example, |
| <<<$\{env.PATH\}>>> contains the $path environment variable (<<<%PATH%>>> in Windows). |
| |
| [[2]] <<<project.x>>>: A dot (.) notated path in the POM will contain the corresponding elements value. |
| For example: <<<\<project\>\<version\>1.0\</version\>\</project\>>>> is accessible via |
| <<<$\{project.version\}>>>. |
| |
| [[3]] <<<settings.x>>>: A dot (.) notated path in the <<<settings.xml>>> will contain the corresponding elements value. |
| For example: <<<\<settings\>\<offline\>false\</offline\>\</settings\>>>> is accessible via |
| <<<$\{settings.offline\}>>>. |
| |
| [[4]] Java System Properties: All properties accessible via <<<java.lang.System.getProperties()>>> are |
| available as POM properties, such as <<<$\{java.home\}>>>. |
| |
| [[5]] <<<x>>>: Set within a \<properties /\> element or an external files, the value may be used as <<<$\{someVar\}>>>. |
| |
| [] |
| |
| +------------------------------------+ |
| <settings> |
| ... |
| <profiles> |
| <profile> |
| ... |
| <properties> |
| <user.install>${user.dir}/our-project</user.install> |
| </properties> |
| ... |
| </profile> |
| </profiles> |
| ... |
| </settings> |
| +------------------------------------+ |
| |
| The property <<<${user.install}>>> is accessible from a POM if this profile is active. |
| |
| ** {Repositories} |
| |
| Repositories are remote collections of projects from which Maven uses to populate the local repository |
| of the build system. It is from this local repository that Maven calls it plugins and dependencies. |
| Different remote repositories may contain different projects, and under the active profile they may |
| be searched for a matching release or snapshot artifact. |
| |
| +------------------------------------+ |
| <settings> |
| ... |
| <profiles> |
| <profile> |
| ... |
| <repositories> |
| <repository> |
| <id>codehausSnapshots</id> |
| <name>Codehaus Snapshots</name> |
| <releases> |
| <enabled>false</enabled> |
| <updatePolicy>always</updatePolicy> |
| <checksumPolicy>warn</checksumPolicy> |
| </releases> |
| <snapshots> |
| <enabled>true</enabled> |
| <updatePolicy>never</updatePolicy> |
| <checksumPolicy>fail</checksumPolicy> |
| </snapshots> |
| <url>http://snapshots.maven.codehaus.org/maven2</url> |
| <layout>default</layout> |
| </repository> |
| </repositories> |
| <pluginRepositories> |
| ... |
| </pluginRepositories> |
| ... |
| </profile> |
| </profiles> |
| ... |
| </settings> |
| +------------------------------------+ |
| |
| * <<releases>>, <<snapshots>>: |
| These are the policies for each type of artifact, Release or snapshot. With these two sets, a POM |
| has the power to alter the policies for each type independent of the other within a single repository. |
| For example, one may decide to enable only snapshot downloads, possibly for development purposes. |
| |
| * <<enabled>>: |
| <<<true>>> or <<<false>>> for whether this repository is enabled for the respective |
| type (<<<releases>>> or <<<snapshots>>>). |
| |
| * <<updatePolicy>>: |
| This element specifies how often updates should attempt to occur. Maven will compare the local |
| POMs timestamp (stored in a repositorys maven-metadata file) to the remote. The choices are: |
| <<<always>>>, <<<daily>>> (default), <<<interval:X>>> (where X is an integer in minutes) or <<<never>>>. |
| |
| * <<checksumPolicy>>: |
| When Maven deploys files to the repository, it also deploys corresponding checksum files. Your options |
| are to <<<ignore>>>, <<<fail>>>, or <<<warn>>> on missing or incorrect checksums. |
| |
| * <<layout>>: |
| In the above description of repositories, it was mentioned that they all follow a common layout. This |
| is mostly correct. Maven 2 has a default layout for its repositories; however, Maven 1.x had a different |
| layout. Use this element to specify which if it is <<<default>>> or <<<legacy>>>. |
| |
| ** {Plugin Repositories} |
| |
| Repositories are home to two major types of artifacts. The first are artifacts that are used as |
| dependencies of other artifacts. These are the majority of plugins that reside within central. |
| The other type of artifact is plugins. Maven plugins are themselves a special type of artifact. |
| Because of this, plugin repositories may be separated from other repositories (although, I have |
| yet to hear a convincing argument for doing so). In any case, the structure of the <<<pluginRepositories>>> |
| element block is similar to the <<<repositories>>> element. The <<<pluginRepository>>> elements each specify a |
| remote location of where Maven can find new plugins. |
| |
| * {Active Profiles} |
| |
| +------------------------------------+ |
| <settings> |
| ... |
| <activeProfiles> |
| <activeProfile>env-test</activeProfile> |
| </activeProfiles> |
| </settings> |
| +------------------------------------+ |
| |
| The final piece of the <<<settings.xml>>> puzzle is the <<<activeProfiles>>> element. This contains |
| a set of <<<activeProfile>>> elements, which each have a value of a <<<profile>>> <<<id>>>. Any |
| <<<profile>>> <<<id>>> defined as an <<<activeProfile>>> will be active, reguardless of |
| any environment settings. If no matching profile is found nothing will happen. For example, if |
| <<<env-test>>> is an <<<activeProfile>>>, a profile in a <<<pom.xml>>> (or <<<profile.xml>>> with a |
| corrosponding <<<id>>> will be active. If no such profile is found then execution will continue |
| as normal. |
| |