Apache
/
maven
mirror of https://github.com/apache/maven.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

add configuration doco 

git-svn-id: https://svn.apache.org/repos/asf/maven/components/trunk@163907 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Brett Leslie Porter 2005-04-12 01:44:37 +00:00
parent 4361a69db0
commit 2e7bdd7681
6 changed files with 541 additions and 202 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

117
maven-site/src/site/xdoc/configuration.xml
View File

@ -6,8 +6,123 @@
<body> <body>
<section name="Configuring Maven"> <section name="Configuring Maven">
<p> <p>
... Maven configuration occurs at 3 levels:
</p> </p>
<ul>
<li>
<i>Project</i> - most static configuration occurs in
<code>pom.xml</code>
</li>
<li>
<i>Installation</i> - this is configuration added once for a Maven installation (not supported in the initial Technology Preview)
</li>
<li>
<i>User</i> - this is configuration specific to a particular user
</li>
</ul>
<p>
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.
</p>
<p>
<b>Note: </b> the installation and user configuration can not be used to add shared project information -
for example setting
<code>&lt;organization&gt;</code> or
<code>&lt;distributionManagement&gt;</code> company-wide.
For this, you should have your projects inherit from a company-wide parent
<code>pom.xml</code>.
<!-- TODO: versioning doc that discusses this -->
</p>
<p>
User configuration is specified in
<code>${user.home}/.m2/settings.xml</code>. A
<a href="settings-descriptor.html">full reference</a> to the
configuration file is available. This section will show how to make some common configurations.
</p>
<p style="font-weight: bold; font-size: larger">
Configuring your Local Repository
</p>
<p>
The local repository is part of a profile in your user configuration. You can have multiple profiles, with one
set to active so that you can switch environments.
</p>
<source><![CDATA[
<settings>
.
.
<profiles>
<profile>
<active>true</active>
<localRepository>/path/to/local/repo</localRepository>
</profile>
</profiles>
.
.]]></source>
<p>
The local repository must be an absolute path.
</p>
<p style="font-weight: bold; font-size: larger">
Configuring a Proxy
</p>
<p>
You can configure a proxy to use for some or all of your HTTP requests in Maven 2.0. The username and
password are only required if your proxy requires basic authentication (note that later alphas will support
storing your passwords in a secured keystore - in the mean time, please ensure your <code>settings.xml</code>
file is secured with permissions appropriate for your operating system).
</p>
<p>
The <code>nonProxyHosts</code> setting accepts wild cards, and each host not to proxy is separated by the
<code>|</code> character. This matches the
<a href="http://java.sun.com/j2se/1.4.2/docs/guide/net/properties.html">JDK configuration</a> equivalent.
</p>
<source><![CDATA[
<settings>
.
.
<proxies>
<proxy>
<active>true</active>
<protocol>http</protocol>
<host>http://proxy.somewhere.com</host>
<port>8080</port>
<username>proxyuser</username>
<password>somepassword</password>
<nonProxyHosts>www.google.com|*.somewhere.com</nonProxyHosts>
</proxy>
</proxies>
.
.]]></source>
<p style="font-weight: bold; font-size: larger">
Deployment Settings
</p>
<p>
Repositories to deploy to are defined in a project in the <code>&lt;distributionManagement&gt;</code> 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 <code>id</code> that matches that of the
deployment repository in the project.
</p>
<p>
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:
</p>
<source><![CDATA[
<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>
.
.]]></source>
</section> </section>
</body> </body>
</document> </document>

10
maven-site/src/site/xdoc/index.xml
View File

@ -16,7 +16,7 @@
<small>(685K)</small> <small>(685K)</small>
<br/> <br/>
</p> </p>
<ul style="margin-top: 0"> <ul style="margin-top: 0; list-style-type: disc">
<li style="font-size: smaller"> <li style="font-size: smaller">
<a href="download.html#requirements">System Requirements</a> <a href="download.html#requirements">System Requirements</a>
</li> </li>
@ -39,7 +39,7 @@
Maven 2.0 is a rewrite of the popular Maven application to achieve a number of goals, and to provide a stable Maven 2.0 is a rewrite of the popular Maven application to achieve a number of goals, and to provide a stable
basis to take it into the future. It is currently available as a Technology Preview. basis to take it into the future. It is currently available as a Technology Preview.
</p> </p>
<ul style="list-style-type: square"> <ul>
<li> <li>
<i> <i>
<a href="about.html#what-is-maven">What is Maven?</a> <a href="about.html#what-is-maven">What is Maven?</a>
@ -83,7 +83,7 @@
Maven 1.0 users will likely have a lot of questions about Maven 2.0 and how it will impact the future of Maven Maven 1.0 users will likely have a lot of questions about Maven 2.0 and how it will impact the future of Maven
1.0. 1.0.
</p> </p>
<ul style="list-style-type: square"> <ul>
<li> <li>
<i> <i>
<a href="maven1.html#">What's changed?</a> <a href="maven1.html#">What's changed?</a>
@ -111,7 +111,7 @@
<p> <p>
Maven is now simpler than ever to use! Maven is now simpler than ever to use!
</p> </p>
<ul style="list-style-type: square"> <ul>
<li> <li>
<i> <i>
<a href="getting-started.html">Getting Started</a> <a href="getting-started.html">Getting Started</a>
@ -122,12 +122,12 @@
<a href="general.html">General FAQ</a> <a href="general.html">General FAQ</a>
</i> </i>
</li> </li>
<!-- TODO
<li> <li>
<i> <i>
<a href="configuration.html">Configuring Maven</a> <a href="configuration.html">Configuring Maven</a>
</i> </i>
</li> </li>
<!-- TODO
<li> <li>
<i> <i>
<a href="archetypes.html">Generating a Template Project: Archetypes</a> <a href="archetypes.html">Generating a Template Project: Archetypes</a>

1
maven-site/src/site/xdoc/navigation.xml
View File

@ -22,6 +22,7 @@
</menu> </menu>
<menu name="Reference"> <menu name="Reference">
<item name="Project Descriptor" href="project-descriptor.html"/> <item name="Project Descriptor" href="project-descriptor.html"/>
<item name="Settings Descriptor" href="settings-descriptor.html"/>
<item name="Available Plugins" href="plugin-list.html"/> <item name="Available Plugins" href="plugin-list.html"/>
</menu> </menu>
</body> </body>

3
maven-site/src/site/xdoc/project-descriptor.xml
View File

@ -202,8 +202,7 @@
<a href="#Dependency">&lt;dependency&gt;</a> <a href="#Dependency">&lt;dependency&gt;</a>
<a href="#dependencies">&lt;/dependencies&gt;</a> <a href="#dependencies">&lt;/dependencies&gt;</a>
<a href="#DependencyManagement">&lt;dependencyManagement&gt;</a> <a href="#DependencyManagement">&lt;dependencyManagement&gt;</a>
<a href="#Model">&lt;model&gt;</a> <a href="#Model">&lt;model&gt;</a></source>
</source>
</p> </p>
<section name="Model"> <section name="Model">
<p> <p>

221
maven-site/src/site/xdoc/settings-descriptor.xml Normal file
View File

@ -0,0 +1,221 @@
<?xml version="1.0"?>
<document>
<properties>
<author email="dev@modello.codehaus.org">Maven Development Team</author>
<title>Maven Model Documentation</title>
</properties>
<body>
<section name="Descriptor with links">
<p>
<source>
<a href="#Settings">&lt;settings&gt;</a>
<a href="#jdks">&lt;jdks&gt;</a>
<a href="#Jdk">&lt;jdk&gt;</a>
<a href="#Jdk">&lt;active/&gt;</a>
<a href="#Jdk">&lt;version/&gt;</a>
<a href="#Jdk">&lt;javaHome/&gt;</a>
<a href="#Jdk">&lt;jdk&gt;</a>
<a href="#jdks">&lt;/jdks&gt;</a>
<a href="#proxies">&lt;proxies&gt;</a>
<a href="#Proxy">&lt;proxy&gt;</a>
<a href="#Proxy">&lt;active/&gt;</a>
<a href="#Proxy">&lt;protocol/&gt;</a>
<a href="#Proxy">&lt;username/&gt;</a>
<a href="#Proxy">&lt;password/&gt;</a>
<a href="#Proxy">&lt;port/&gt;</a>
<a href="#Proxy">&lt;host/&gt;</a>
<a href="#Proxy">&lt;nonProxyHosts/&gt;</a>
<a href="#Proxy">&lt;proxy&gt;</a>
<a href="#proxies">&lt;/proxies&gt;</a>
<a href="#servers">&lt;servers&gt;</a>
<a href="#Server">&lt;server&gt;</a>
<a href="#Server">&lt;id/&gt;</a>
<a href="#Server">&lt;username/&gt;</a>
<a href="#Server">&lt;password/&gt;</a>
<a href="#Server">&lt;privateKey/&gt;</a>
<a href="#Server">&lt;passphrase/&gt;</a>
<a href="#Server">&lt;server&gt;</a>
<a href="#servers">&lt;/servers&gt;</a>
<a href="#profiles">&lt;profiles&gt;</a>
<a href="#Profile">&lt;profile&gt;</a>
<a href="#Profile">&lt;active/&gt;</a>
<a href="#Profile">&lt;localRepository/&gt;</a>
<a href="#Profile">&lt;passwordStore/&gt;</a>
<a href="#Profile">&lt;profile&gt;</a>
<a href="#profiles">&lt;/profiles&gt;</a>
<a href="#Settings">&lt;settings&gt;</a></source>
</p>
<section name="Settings">
<p>
<table>
<tr>
<th>Element</th>
<th>Description</th>
</tr>
<tr>
<td>jdks</td>
<td>
Configuration for different java environment profiles. One good use
for this might be to configure both JDK 1.4 and JDK 1.5 to work with
maven. Profiles will allow switching of entire java environments
based on the profile id, either in the defaults section below, or on
the command line.
</td>
</tr>
<tr>
<td>proxies</td>
<td>
Configuration for different proxy profiles. Multiple proxy profiles
might come in handy for anyone working from a notebook or other
mobile platform, to enable easy switching of entire proxy
configurations by simply specifying the profile id, again either from
the command line or from the defaults section below.
</td>
</tr>
<tr>
<td>servers</td>
<td>
Configuration of server-specific settings, mainly authentication
method. This allows configuration of authentication on a per-server
basis.
</td>
</tr>
<tr>
<td>profiles</td>
<td>
Configuration for different runtime profiles for maven itself. For
example, this will allow plugin developers to switch from a "work"
local repository to a "testing" local repository. It may also allow
configuration of such things as password keystore, etc. Once again,
the active profile will be switchable via either the defaults section
or the command line (read: system properties).
</td>
</tr>
</table>
</p>
</section>
<section name="Jdk">
<p>
<table>
<tr>
<th>Element</th>
<th>Description</th>
</tr>
<tr>
<td>active</td>
<td>Whether this JDK is the active one.</td>
</tr>
<tr>
<td>version</td>
<td>The JDK major version (eg. '1.4').</td>
</tr>
<tr>
<td>javaHome</td>
<td>The JDK home.</td>
</tr>
</table>
</p>
</section>
<section name="Proxy">
<p>
<table>
<tr>
<th>Element</th>
<th>Description</th>
</tr>
<tr>
<td>active</td>
<td>Whether this proxy configuration is the active one.</td>
</tr>
<tr>
<td>protocol</td>
<td>The proxy protocol.</td>
</tr>
<tr>
<td>username</td>
<td>The proxy user.</td>
</tr>
<tr>
<td>password</td>
<td>The proxy password.</td>
</tr>
<tr>
<td>port</td>
<td>The proxy port.</td>
</tr>
<tr>
<td>host</td>
<td>The proxy host.</td>
</tr>
<tr>
<td>nonProxyHosts</td>
<td>
The list of non-proxied hosts (usually
comma-delimited).
</td>
</tr>
</table>
</p>
</section>
<section name="Server">
<p>
<table>
<tr>
<th>Element</th>
<th>Description</th>
</tr>
<tr>
<td>id</td>
<td>
The ID of this configuration for indicating the default or "active"
profile.
</td>
</tr>
<tr>
<td>username</td>
<td>The username used to authenticate.</td>
</tr>
<tr>
<td>password</td>
<td>
The password used in conjunction with the username to authenticate.
</td>
</tr>
<tr>
<td>privateKey</td>
<td>The private key location used to authenticate.</td>
</tr>
<tr>
<td>passphrase</td>
<td>
The passphrase used in conjunction with the privateKey to authenticate.
</td>
</tr>
</table>
</p>
</section>
<section name="Profile">
<p>
<table>
<tr>
<th>Element</th>
<th>Description</th>
</tr>
<tr>
<td>active</td>
<td>Whether this is the active maven profile.</td>
</tr>
<tr>
<td>localRepository</td>
<td>The local repository.</td>
</tr>
<tr>
<td>passwordStore</td>
<td>The keystore used to store passwords.</td>
</tr>
</table>
</p>
</section>
</section>
</body>
</document>

3
maven-site/src/site/xdoc/style/project.css
View File

@ -3,3 +3,6 @@ a.externalLink, a.externalLink:link, a.externalLink:visited, a.externalLink:acti
padding-right: 0; padding-right: 0;
} }
body ul {
list-style-type: square;
}