You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by jv...@apache.org on 2006/10/26 01:29:15 UTC
svn commit: r467809 [2/2] - in /maven/site/trunk/src/site/apt:
guides/mini/guide-ibiblio-upload.apt pom.apt settings.apt
Added: maven/site/trunk/src/site/apt/settings.apt
URL: http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/settings.apt?view=auto&rev=467809
==============================================================================
--- maven/site/trunk/src/site/apt/settings.apt (added)
+++ maven/site/trunk/src/site/apt/settings.apt Wed Oct 25 16:29:14 2006
@@ -0,0 +1,452 @@
+ ----
+ 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.
+
Propchange: maven/site/trunk/src/site/apt/settings.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/site/trunk/src/site/apt/settings.apt
------------------------------------------------------------------------------
svn:keywords = "Author Date Id Revision"