brett 2004/12/01 03:46:46
Modified: xdocs faq.fml navigation.xml
xdocs/reference project-descriptor.xml properties.xml
repository-upload.xml
xdocs/start install.xml quick-start.xml
xdocs/using developing-plugins.xml
Log:
add the properties reference, spruce the project descriptor, and other tidy up
Revision Changes Path
1.15 +37 -7 maven/xdocs/faq.fml
Index: faq.fml
===================================================================
RCS file: /home/cvs/maven/xdocs/faq.fml,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- faq.fml 30 Nov 2004 13:13:13 -0000 1.14
+++ faq.fml 1 Dec 2004 11:46:45 -0000 1.15
@@ -242,7 +242,39 @@
<ant:taskdef>]]></source>
</answer>
</faq>
-<!-- TODO: why local repository per user? -->
+
+ <faq id="share-local-repository">
+ <question>I share a development machine. How can I share the local
repository to save downloading?</question>
+ <answer>
+ <p>
+ It is recommended that you <b>do not</b> share your local
repository. The reason for this is that as you
+ build your projects, part of the process is usually to install
your changes there for sharing with other
+ projects you are working on that depend on it.
+ </p>
+ <p>
+ If you share this with multiple developers, you will have to
communicate with them about when you will
+ be developing a certain project to ensure your changes don't
clash, and ensure each person is always
+ completely up to date.
+ </p>
+ <p>
+ Usually, it is better to work with a shared remote repository that
you run yourself. This means that
+ dependencies are only downloaded once from the internet, and then
downloaded to the local cache for each
+ developer as they need it. Company artifacts can also be published
there.
+ </p>
+ <p>
+ See <a href="using/repositories.html">Working with
Repositories</a> for more information.
+ </p>
+ <p>
+ If after this you really want to share a local repository, you can
set the <code>maven.repo.local</code>
+ property. This is a directory (not a URL). The directory pointed
to must be readable by all of the users
+ and may need to be writable if the users will be allowed to
download dependencies or publish their changes.
+ The file system mask must also be set correctly so that changes
retain the correct permissions.
+ </p>
+ <p>
+ Please note that this solution will not be supported by the Maven
Users Mailing List, however.
+ </p>
+ </answer>
+ </faq>
</part>
<part id="ibiblio">
@@ -293,8 +325,8 @@
<question>How do I get or set plugin properties from Jelly?</question>
<answer>
<p>Plugin properties can be used with the following tags:
- <a
href="/reference/maven-jelly-tags/tags.html#maven:get">maven:get</a> and
- <a
href="/reference/maven-jelly-tags/tags.html#maven:set">maven:set</a>.
+ <a href="jelly-tags/tags.html#maven:get">maven:get</a> and
+ <a href="jelly-tags/tags.html#maven:set">maven:set</a>.
(These replace the deprecated versions of
<code>${pom.getPluginContext(...).get/setVariable()}</code>
and <code>maven:pluginVar</code>.)</p>
<p>Example:</p>
@@ -510,7 +542,7 @@
<faq id="filtering-resources">
<question>How can I filter properties into resource files as part of
the build?</question>
<answer>
-<!-- TODO: add to using somewhere, and reference. Also add warning about
reproducible artifacts... -->
+<!-- TODO: filters: add to using somewhere, and reference. Also add warning
about reproducible artifacts... -->
<p>
This can now be done using resource filtering. See this wiki entry
for more information:
<a
href="http://wiki.codehaus.org/maven/FilteringResources";>http://wiki.codehaus.org/maven/FilteringResources</a>.
@@ -614,10 +646,8 @@
<p>You typically need to set your HTTP proxy host and port details
so that Maven can tunnel through your
HTTP Proxy. To do this you typically need to set the
<code>maven.proxy.host</code> and
<code>maven.proxy.port</code> properties.</p>
-<!-- TODO: proxy details link
See the
- <a href="./reference/user-guide.html#Using Proxies">User Guide</a>
for more details.
--->
+ <a href="./reference/properties.html#Proxy_Properties">Properties
Reference</a> for more details.
</answer>
</faq>
</part>
1.54 +0 -1 maven/xdocs/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/maven/xdocs/navigation.xml,v
retrieving revision 1.53
retrieving revision 1.54
diff -u -r1.53 -r1.54
--- navigation.xml 30 Nov 2004 13:13:13 -0000 1.53
+++ navigation.xml 1 Dec 2004 11:46:45 -0000 1.54
@@ -64,7 +64,6 @@
<item name="Migrating from Ant"
href="/using/migrating.html" />
<item name="FAQ" href="/faq.html" />
<item name="Writing a Plugin"
href="/using/developing-plugins.html" />
-<!-- TODO: not the right section or name... -->
<item name="Working with Repositories"
href="/using/repositories.html" />
</menu>
1.39 +74 -106 maven/xdocs/reference/project-descriptor.xml
Index: project-descriptor.xml
===================================================================
RCS file: /home/cvs/maven/xdocs/reference/project-descriptor.xml,v
retrieving revision 1.38
retrieving revision 1.39
diff -u -r1.38 -r1.39
--- project-descriptor.xml 30 Nov 2004 13:13:13 -0000 1.38
+++ project-descriptor.xml 1 Dec 2004 11:46:45 -0000 1.39
@@ -26,10 +26,9 @@
<title>Maven Project Descriptors</title>
</properties>
- <!-- TODO [later]: we want to autogenerate this using modello ASAP -->
+ <!-- TODO [later]: we want to autogenerate this using modello ASAP -
update the modello descriptions to use this
+ where appropriate -->
<!-- TODO [later]: in pom reference, mention which are and are not
inherited -->
- <!-- TODO: descriptions need to be vetted. Some are too long, and far too
many reference specific plugins.
- Needs to become just basic description and other useful documentation
moved before using modello instead -->
<body>
<section name="Maven Project Descriptors">
<p>
@@ -52,7 +51,7 @@
<a href="#project" class="required"><project></a>
<a href="#extend" class="optional"><extend/></a>
<a href="#pomVersion"><pomVersion/></a>
- <a href="#id"><id/></a>
+ <a href="#artifactId"><artifactId/></a>
<a href="#name" title="short name for the project"><name/></a>
<a href="#groupId"><groupId/></a>
<a href="#currentVersion"><currentVersion/></a>
@@ -223,34 +222,28 @@
<tr>
<td><a name="pomVersion">pomVersion</a></td>
<td>
- The current version of the Maven project descriptor. This
- version number enables Maven to automatically update an
- out-of-date project descriptor when a new version is
- available. This version number should not be changed after
- the descriptor has been created. Maven will update it
- automatically.
+ The current version of the Maven project descriptor.
+ For Maven 1.0.x, this should be <code>3</code>.
</td>
</tr>
<tr>
- <td><a name="id">id</a></td>
+ <td><a name="artifactId">artifactId</a> (or id)</td>
<td>
- The short name of the project. This value is used when
- naming <a href="plugins/java/index.html">jars</a> and <a
- href="plugins/dist/index.html">distribution files</a>.
+ The identifier of the project, unique within the group. This
value is used when
+ naming artifacts such as jars and distribution files.
</td>
</tr>
<tr>
<td><a name="name">name</a></td>
<td>
- The full name of the project. This value is used when
- generating <a href="plugins/javadoc/index.html">JavaDoc</a>
- titles.
+ The full name of the project. This should be a human readable
name to identify
+ the project by.
</td>
</tr>
<tr>
- <td><a name="groupId">groupId</a></td>
+ <td><a name="groupId">groupId</a> (or id)</td>
<td>
- The short name of the project group. This value is used to group
+ The unique name of the project group. This value is used to group
all jars for a project in one directory. For more info look at
the
<a href="glossary.html#GroupId">glossary</a>.
</td>
@@ -258,9 +251,8 @@
<tr>
<td><a name="currentVersion">currentVersion</a></td>
<td>
- The current version of the project. This value is used when
- naming <a href="plugins/java/index.html">jars</a> and <a
- href="plugins/dist/index.html">distribution files</a>.
+ The current version of the project. This should end in -SNAPSHOT
+ until the release of that version is made.
</td>
</tr>
<tr>
@@ -274,15 +266,13 @@
<td><a name="inceptionYear">inceptionYear</a></td>
<td>
The year of the project's inception specified with 4 digits.
- This value is used when generating <a
- href="plugins/javadoc/index.html">JavaDoc</a> copyright
- notices.
+ This value is used when generating copyright notices on the site.
</td>
</tr>
<tr>
<td><a name="package">package</a></td>
<td>
- The Java package name of the project. This value is used
+ The Java package name of the project. This value is used
when generating <a
href="plugins/javadoc/index.html">JavaDoc</a>.
</td>
@@ -310,7 +300,7 @@
<td>
Optional. A detailed description of the project.
This description is used as the default to generate the
- <a href="plugins/site/index.html">front page</a> of the
project's web site, and is
+ front page of the project's web site, and is
shown when <code>maven --usage</code> is called on the project.
While this element can be specified as CDATA to enable the use
of HTML tags
within the description, you are encouraged to provide an
alternative home page using
@@ -341,25 +331,25 @@
<td><a name="siteAddress">siteAddress</a></td>
<td>
Optional. The hostname of the web server that hosts the
project's web
- site. This is used when the web site is <a
- href="plugins/site/index.html">deployed</a>.
+ site. This is used when the web site is deployed.
+ See the <a href="plugins/site/index.html">site plugin</a> for
more information.
</td>
</tr>
<tr>
<td><a name="siteDirectory">siteDirectory</a></td>
<td>
Optional. The directory on the web server where the public web
site
- for this project resides. This is used when the web site is <a
- href="plugins/site/index.html">deployed</a>.
+ for this project resides. This is used when the web site is
deployed.
+ See the <a href="plugins/site/index.html">site plugin</a> for
more information.
</td>
</tr>
<tr>
<td><a name="distributionSite">distributionSite</a></td>
<td>
- Optional. The server server where the final
+ Optional. The server where the final
distributions will be published. This is used when the
- distributions are
- <a href="plugins/dist/index.html">deployed</a>.
+ distributions are deployed.
+ See the <a href="plugins/dist/index.html">dist plugin</a> for
more information.
<p>
If this isn't defined, the central repository is used instead
as
determined by <code>maven.repo.central</code> and
@@ -372,74 +362,65 @@
<td>
Optional. The directory on the web server where the final
distributions will be published. This is used when the
- distributions are
- <a href="plugins/dist/index.html">deployed</a>.
+ distributions are deployed. Ignored if <a
href="#distributionSite">distributionSite</a> is not specified.
+ See the <a href="plugins/dist/index.html">dist plugin</a> for
more information.
</td>
</tr>
<tr>
<td><a href="#repository">repository</a></td>
<td>
Information relating to the source configuration
- management system used by this project.
+ management system used by this project, eg CVS.
</td>
</tr>
<tr>
<td><a href="#versions">versions</a></td>
<td>
Optional. Contains information on previous versions of the
- project. This information is used when invoking the <a
- href="plugins/dist/index.html"><code>maven:dist</code></a>
- target.
+ project.
</td>
</tr>
<tr>
<td><a href="#branches">branches</a></td>
<td>
Optional. Contains information on branches of the
- project. This information is used when invoking the <a
- href="plugins/dist/index.html"><code>maven:dist</code></a>
- target.
+ project.
</td>
</tr>
<tr>
<td><a href="#mailingLists">mailingLists</a></td>
<td>
- Contains information about a project's mailing lists. This
- is used to generate the
- <a href="plugins/site/index.html">Mailing lists</a> page of
- the project's web site.
+ Optional. Contains information about a project's mailing lists.
+ These will be listed on the project web site.
</td>
</tr>
<tr>
<td><a href="#developers">developers</a></td>
<td>
- Describes the committers to a project. This is used to
- generate the <a href="plugins/site/index.html">Project Team</a>
- page of the project's web site.
+ Describes the active committers of a project. This is used to
+ generate the Project Team page of the project's web site.
</td>
</tr>
<tr>
<td><a href="#contributors">contributors</a></td>
<td>
- Describes the contributors to a project. This is used to
generate
- the <a href="plugins/site/index.html">Project Team</a> page of
- the project's web site.
+ Optional. Describes the contributors to a project. This is used
to generate
+ the Project Team page of the project's web site.
</td>
</tr>
<tr>
<td><a href="#licenses">licenses</a></td>
<td>
- Describes the licenses for this project. This is used to
generate
- the <a href="plugins/site/index.html">License</a> page of
- the project's web site. Typically the licenses listed for the
project
+ Optional. Describes the licenses for this project. This is used
to generate
+ the License page of the project's web site. Typically the
licenses listed for the project
are that of the project itself, and not of dependencies.
</td>
</tr>
<tr>
<td><a href="#dependencies">dependencies</a></td>
<td>
- Describes the dependencies to a project. This is used to
- when building a project.
+ Describes the dependencies to a project. This is used to
construct the classpath
+ when building a project. These dependencies will be downloaded
if they do not exist locally.
</td>
</tr>
<tr>
@@ -502,11 +483,9 @@
<tr>
<td><a name="repository_connection">connection</a></td>
<td>
- <p>Optional. The source configuration management system URL
+ <p>The source configuration management system URL
that describes the repository and how to connect to the
- repository. This is used by Maven when <a
- href="plugins/dist/index.html">building versions</a>
- from specific ID.
+ repository.
</p>
<p>The format of this element is as follows:
<pre>scm:<provider>:<provider-parameters></pre>
@@ -591,10 +570,7 @@
<tr>
<td><a name="version_id">id</a></td>
<td>
- A unique identifier for a version. This ID is
- used to specify the version that <a
-
href="plugins/dist/index.html"><code>maven:dist</code></a>
- builds.
+ A unique identifier for a version.
</td>
</tr>
<tr>
@@ -697,7 +673,7 @@
</tr>
<tr>
<td><a name="developer_id">id</a></td>
- <td>The username of the developer.</td>
+ <td>The username of the developer if they have SSH access to
CVS, for example.</td>
</tr>
<tr>
<td><a name="developer_email">email</a></td>
@@ -723,7 +699,7 @@
<td><a name="developer_timezone">timezone</a></td>
<td>
The timezone the developer is in. This is a number in the range
- -14 to 14.
+ -14 to 14, giving the offest from GMT.
</td>
</tr>
</table>
@@ -768,7 +744,7 @@
<td><a name="contributor_timezone">timezone</a></td>
<td>
The timezone the contributor is in. This is a number in the
range
- -14 to 14.
+ -14 to 14, giving the offest from GMT.
</td>
</tr>
</table>
@@ -835,9 +811,7 @@
the dependency element to construct the URL to download from. This
URL is
defined as:
</p>
- <source>
-${repo}/${groupId}/${type}s/${artifactId}-${version}.${type}
- </source>
+
<source>${repo}/${groupId}/${type}s/${artifactId}-${version}.${type}</source>
<p>
Where
<dl>
@@ -937,9 +911,7 @@
An address to which notifications regarding the status of builds
for this project can be sent. This is intended for use by tools
which do unattended builds, for example those providing for
- continuous integration. Currently this is used by the
- <a href="plugins/gump/">gump plugin</a>
- target.
+ continuous integration.
</td>
</tr>
<tr>
@@ -1017,17 +989,15 @@
An example below always excludes the classes beginning with
<code>EJS</code>
and <code>_</code>.
</p>
- <source><![CDATA[
- <sourceModifications>
- <sourceModification>
- <className>FakeClass</className>
- <excludes>
- <exclude>**/EJS*.java</exclude>
- <exclude>**/_*.java</exclude>
- </excludes>
- </sourceModification>
- </sourceModifications>
-]]></source>
+ <source><![CDATA[<sourceModifications>
+ <sourceModification>
+ <className>FakeClass</className>
+ <excludes>
+ <exclude>**/EJS*.java</exclude>
+ <exclude>**/_*.java</exclude>
+ </excludes>
+ </sourceModification>
+</sourceModifications>]]></source>
</subsection>
<subsection name="sourceModification">
<table>
@@ -1085,24 +1055,21 @@
<p>
Here's an example <code>resources</code> block:
</p>
- <source><![CDATA[
- <!-- J A R R E S O U R C E S -->
- <!-- Resources that are packaged up inside the JAR file -->
- <resources>
- <resource>
- <directory>${basedir}/src/resources/misc</directory>
- <includes>
- <include>*.xsd</include>
- </includes>
- </resource>
- <resource>
- <directory>${basedir}/src/resources/logging</directory>
- <includes>
- <include>log4j.properties</include>
- </includes>
- </resource>
- </resources>
-]]></source>
+ <source><![CDATA[<!-- Resources that are packaged up inside the JAR
file -->
+<resources>
+ <resource>
+ <directory>${basedir}/src/resources/misc</directory>
+ <includes>
+ <include>*.xsd</include>
+ </includes>
+ </resource>
+ <resource>
+ <directory>${basedir}/src/resources/logging</directory>
+ <includes>
+ <include>log4j.properties</include>
+ </includes>
+ </resource>
+</resources>]]></source>
</subsection>
<subsection name="resource">
@@ -1144,7 +1111,7 @@
<td><a name="include">include</a></td>
<td>
This element specifies an
- <a
href="http://ant.apache.org/manual/CoreTypes/patternset.html";>Ant pattern</a>
+ <a
href="http://ant.apache.org/manual/CoreTypes/patternset.html";>pattern set</a>
of files to include in a list.
</td>
</tr>
@@ -1157,7 +1124,7 @@
<td><a name="exclude">exclude</a></td>
<td>
This element specifies an
- <a
href="http://ant.apache.org/manual/CoreTypes/patternset.html";>Ant pattern</a>
+ <a
href="http://ant.apache.org/manual/CoreTypes/patternset.html";>pattern set</a>
of files to exclude from a list.
</td>
</tr>
@@ -1189,3 +1156,4 @@
</section>
</body>
</document>
+
1.10 +337 -271 maven/xdocs/reference/properties.xml
Index: properties.xml
===================================================================
RCS file: /home/cvs/maven/xdocs/reference/properties.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- properties.xml 22 Nov 2004 11:52:58 -0000 1.9
+++ properties.xml 1 Dec 2004 11:46:45 -0000 1.10
@@ -26,335 +26,401 @@
</properties>
<body>
-
-<!-- TODO
- <subsection name="Properties Processing">
+ <section name="Properties Reference">
+ <p>
+ In Maven, properties are used to customise the behaviour of Maven
and its plugins.
+ </p>
+ <subsection name="Property Processing">
<p>
- The properties files in Maven are processed in the following order:
+ Maven supports a hierarchy of different properties to allow
specifying defaults and
+ overriding them at the appropriate level.
</p>
-
<p>
- <ul>
- <li>Plug-in default properties are processed</li>
- <li>${project.home}/project.properties</li>
- <li>${project.home}/build.properties</li>
- <li>${user.home}/build.properties</li>
+ The properties files in Maven are processed in the following order:
+ <ol>
+ <li>Built-in properties are processed</li>
+ <li><code>${basedir}/project.properties</code>
(<code>basedir</code> is replaced by the directory where the
<code>project.xml</code> file in use resides)</li>
+ <li><code>${basedir}/build.properties</code></li>
+ <li><code>${user.home}/build.properties</code></li>
<li>System properties</li>
- </ul>
+ </ol>
</p>
-
<p>
- Where the last definition wins. So, Maven moves through this
sequence
- of properties files overriding any previously defined properties
with
- newer definitions. In this sequence your
<code>${user.home}/build.properties</code>
- has the final say in the list of properties files processed. We
will call the
- list of properties files that Maven processes the standard
properties file set.
+ The built-in properties are specified in the
<code>plugin.properties</code> file of a plugin, or in
+ <code>defaults.properties</code> within Maven itself.
</p>
-
<p>
- In addition, System properties are processed after the above chain
of
- properties files are processed. So, a property specified on the CLI
- using the <code>-Dproperty=value</code> convention will override
any
- previous definition of that property.
+ Both the <code>project.properties</code> and
<code>build.properties</code> files in the project
+ directory are also inherited along with the related
<code>project.xml</code> file.
</p>
-
- </subsection>
-
- <subsection name="Behavioural Properties">
<p>
- The following is a list of properties that change the way Maven
works.
+ The last definition takes precedence, so
<code>${user.home}/build.properties</code> will override
+ anything specified in a project, and properties given on the
command line using <code>-D</code> will
+ override everything.
</p>
-
<p>
- <table>
- <tr>
- <th>Property</th>
- <th>Description</th>
- <th>Default Value</th>
- </tr>
-
- <tr>
- <td>maven.build.dest</td>
- <td>
- The directory where generated classes go.
- </td>
- <td>${maven.build.dir}/classes</td>
- </tr>
-
- <tr>
- <td>maven.build.dir</td>
- <td>
- The directory where generated output, e.g. class files,
documentation,
- unit test reports etc goes.
- <p>
- <strong>CAUTION:</strong>
- Changing default maven.build.dir value in your
${user.home}/build.properties
- might allow one some control of individual project
directory layouts.
- However this practice will interfere with the bootstrap of
Maven from source
- code, as it expects the jar created to be in
<code>${basedir}/target/</code>.
- </p>
- </td>
- <td>${basedir}/target</td>
- </tr>
-
- <tr>
- <td>maven.build.src</td>
- <td>
- The directory where generated source goes.
- </td>
- <td>${maven.build.dir}/src</td>
- </tr>
-
- <tr>
- <td>maven.conf.dir</td>
- <td>
- The directory that holds configuration files.
- </td>
- <td>${basedir}/conf</td>
- </tr>
-
- <tr>
- <td>maven.docs.dest</td>
- <td>
- The output directory for the generated html from reports.
- </td>
- <td>${maven.build.dir}/docs</td>
- </tr>
-
- <tr>
- <td>maven.docs.omitXmlDeclaration</td>
- <td>
- Whether generated documentation should have an xml
declaration, e.g.
- <source><?xml version="1.0"?></source>
- </td>
- <td>false</td>
- </tr>
-
- <tr>
- <td>maven.docs.outputencoding</td>
- <td>
- The character encoding for generated documentation.
- </td>
- <td>ISO-8859-1</td>
- </tr>
-
- <tr>
- <td>maven.docs.src</td>
- <td>
- The directory for user supplied documentation.
- </td>
- <td>${basedir}/xdocs</td>
- </tr>
-
- <tr>
- <td>maven.gen.docs</td>
- <td>
- The directory where generated xdocs that need to be
transformed to html
- are placed.
- </td>
- <td>${maven.build.dir}/generated-xdocs</td>
- </tr>
-
- <tr>
- <td>maven.home.local</td>
- <td>
- The directory on the local machine maven uses to write user
specific details
- to, such as expanded plugins and cache data.
- </td>
- <td>${user.home}/.maven</td>
- </tr>
-
- <tr>
- <td>maven.mode.online</td>
- <td>
- Whether you are connected to the internet or not.
- </td>
- <td>true</td>
- </tr>
-
- <tr>
- <td>maven.plugin.dir</td>
- <td>
- Where maven can find it's plugins.
- </td>
- <td>${maven.home}/plugins</td>
- </tr>
-
- <tr>
- <td>maven.plugin.user.dir</td>
- <td>
- Where maven can find plugins for this user only.
- </td>
- <td>${maven.home.local}/plugins</td>
- </tr>
-
- <tr>
- <td>maven.plugin.unpacked.dir</td>
- <td>
- Where maven expands installed plugins for processing.
- </td>
- <td>${maven.home.local}/cache</td>
- </tr>
-
- <tr>
- <td>maven.repo.central</td>
- <td>
- This is the host that Maven will attempt to
- deploy the distribution to during a
- dist:deploy.
- </td>
- <td>None</td>
- </tr>
-
- <tr>
- <td>maven.repo.central.directory</td>
- <td>
- This is the directory that Maven will copy the
- distribution to during a dist:deploy.
- </td>
- <td>None</td>
- </tr>
-
- <tr>
- <td>maven.repo.local</td>
- <td>
- The repository on the local machine maven should use to store
- downloaded artifacts (jars etc).
- </td>
- <td>${maven.home.local}/repository</td>
- </tr>
-
- <tr>
- <td>maven.repo.remote</td>
- <td>
- The repository maven should use to download artifacts
- (jars etc) that it can't find in the local repository.
- You should set this to one of the <a
href="/faq.html#ibiblio-mirrors">mirrors</a>.
- </td>
- <td>http://www.ibiblio.org/maven</td>
- </tr>
-
- <tr>
- <td>maven.repo.remote.enabled</td>
- <td>
- Whether or not a remote repository should be used.
- </td>
- <td>true</td>
- </tr>
-
- <tr>
- <td>maven.scp.executable</td>
- <td>
- The executable to use for secure copies.
- </td>
- <td>scp</td>
- </tr>
-
- <tr>
- <td>maven.src.dir</td>
- <td>
- The base directory for source code.
- </td>
- <td>${basedir}/src</td>
- </tr>
-
- <tr>
- <td>maven.ssh.executable</td>
- <td>
- The executable to use for executing commands remotely.
- </td>
- <td>ssh</td>
- </tr>
-
- </table>
+ <b>Note:</b> there are no per-user defaults, as there has not been
a property shown where this concept
+ makes sense. Currently, there are also no site-wide defaults,
however this is planned for future versions
+ of Maven.
+ </p>
+ <p>
+ The following table explains how each file should be used.
</p>
+ <table>
+ <tr>
+ <td><code>${basedir}/project.properties</code></td>
+ <td>
+ These are properties specific to the project and can be used
to set the values for
+ plugin and Maven properties that are appropriate for that
project.
+ This file should be checked into your source repository and
distributed.
+ </td>
+ </tr>
+ <tr>
+ <td><code>${basedir}/build.properties</code></td>
+ <td>
+ These are properties specific to the project, but also the
user running it. It is for
+ overriding values in the <code>project.properties</code> for
this user only.
+ It should <i>not</i> be checked into the source repository. If
a user is required to
+ set any of these properties for a build to run properly, a
<code>build.properties.sample</code>
+ file should be created and checked into the source repository
as a courtesy.
+ </td>
+ </tr>
+ <tr>
+ <td><code>${user.home}/build.properties</code></td>
+ <td>
+ These are properties specific to the user but shared among all
projects.
+ This typically specifies remote repositories to download from
and upload to,
+ proxy settings, file system locations, and so on.
+ </td>
+ </tr>
+ </table>
+ </subsection>
+ </section>
+ <section name="Built-in Maven Properties">
+ <p>
+ The following properties are built-in to Maven and apply to all
projects.
+ </p>
+ <subsection name="Maven Configuration Properties">
+ <table>
+ <tr>
+ <th>Property</th>
+ <th>Description</th>
+ <th>Default Value</th>
+ </tr>
+ <tr>
+ <td><code>maven.home.local</code></td>
+ <td>
+ The directory on the local machine Maven uses to write user
specific details
+ to, such as expanded plugins and cache data.
+ </td>
+ <td><code>${user.home}/.maven</code></td>
+ </tr>
+
+ <tr>
+ <td><code>maven.plugin.dir</code></td>
+ <td>
+ Where Maven can find it's plugins.
+ </td>
+ <td><code>${maven.home}/plugins</code></td>
+ </tr>
+
+ <tr>
+ <td><code>maven.plugin.user.dir</code></td>
+ <td>
+ Where Maven can find plugins for this user only.
+ </td>
+ <td><code>${maven.home.local}/plugins</code></td>
+ </tr>
+
+ <tr>
+ <td><code>maven.plugin.unpacked.dir</code></td>
+ <td>
+ Where Maven expands installed plugins for processing.
+ </td>
+ <td><code>${maven.home.local}/cache</code></td>
+ </tr>
+
+ <tr>
+ <td><code>maven.repo.local</code></td>
+ <td>
+ The repository on the local machine Maven should use to store
+ downloaded artifacts (jars etc).
+ </td>
+ <td><code>${maven.home.local}/repository</code></td>
+ </tr>
+ </table>
</subsection>
+ <subsection name="Build Structure Properties">
+ <table>
+ <tr>
+ <th>Property</th>
+ <th>Description</th>
+ <th>Default Value</th>
+ </tr>
+
+ <tr>
+ <td><code>maven.build.dir</code></td>
+ <td>
+ The directory where generated output, e.g. class files,
documentation,
+ unit test reports etc goes.
+ </td>
+ <td><code>${basedir}/target</code></td>
+ </tr>
- <subsection name="Using Proxies">
+ <tr>
+ <td><code>maven.build.dest</code></td>
+ <td>
+ The directory where generated classes go.
+ </td>
+ <td><code>${maven.build.dir}/classes</code></td>
+ </tr>
+
+ <tr>
+ <td><code>maven.build.src</code></td>
+ <td>
+ The directory where generated source goes.
+ <b>DEPRECATED</b>: Currently unused.
+ </td>
+ <td><code>${maven.build.dir}/src</code></td>
+ </tr>
+
+ <tr>
+ <td><code>maven.conf.dir</code></td>
+ <td>
+ The directory that holds configuration files.
+ <b>DEPRECATED</b>: Currently unused.
+ </td>
+ <td><code>${basedir}/conf</code></td>
+ </tr>
+
+ <tr>
+ <td><code>maven.src.dir</code></td>
+ <td>
+ The base directory for source code.
+ <b>DEPRECATED</b>: Currently unused.
+ </td>
+ <td><code>${basedir}/src</code></td>
+ </tr>
+ </table>
+ </subsection>
+ <subsection name="Documentation Properties">
+ <table>
+ <tr>
+ <th>Property</th>
+ <th>Description</th>
+ <th>Default Value</th>
+ </tr>
+ <tr>
+ <td><code>maven.docs.dest</code></td>
+ <td>
+ The output directory for the generated HTML for the site
documentation.
+ </td>
+ <td><code>${maven.build.dir}/docs</code></td>
+ </tr>
+
+ <tr>
+ <td><code>maven.docs.omitXmlDeclaration</code></td>
+ <td>
+ Whether generated documentation should have an xml
declaration, e.g.
+ <source><?xml version="1.0"?></source>
+ </td>
+ <td><code>false</code></td>
+ </tr>
+
+ <tr>
+ <td><code>maven.docs.outputencoding</code></td>
+ <td>
+ The character encoding for generated documentation.
+ </td>
+ <td><code>ISO-8859-1</code></td>
+ </tr>
+
+ <tr>
+ <td><code>maven.docs.src</code></td>
+ <td>
+ The directory for user supplied documentation.
+ </td>
+ <td><code>${basedir}/xdocs</code></td>
+ </tr>
+
+ <tr>
+ <td><code>maven.gen.docs</code></td>
+ <td>
+ The directory where generated xdocs that need to be
transformed to HTML
+ are placed.
+ </td>
+ <td><code>${maven.build.dir}/generated-xdocs</code></td>
+ </tr>
+ </table>
+ </subsection>
+ <subsection name="Connection Properties">
<p>
- If you only have access via a proxy then Maven obeys the following
- properties.
+ Please refer to <a href="../using/repositories.html">Working with
Repositories</a> for more information.
</p>
-
<table>
<tr>
- <th>Proxy Properties</th>
+ <th>Property</th>
<th>Description</th>
+ <th>Default Value</th>
+ </tr>
+
+ <tr>
+ <td><code>maven.mode.online</code></td>
+ <td>
+ Whether you are connected to the internet or not.
+ </td>
+ <td><code>true</code></td>
+ </tr>
+
+ <tr>
+ <td><code>maven.repo.remote</code></td>
+ <td>
+ The repository maven should use to download artifacts
+ (jars etc) that it can't find in the local repository.
+ You should set this to one of the <a
href="/faq.html#ibiblio-mirrors">Ibiblio mirrors</a>.
+ You can also specify multiple repositories, separated by
commas.
+ </td>
+ <td><code>http://www.ibiblio.org/maven</code></td>
</tr>
+
<tr>
- <td>maven.proxy.host</td>
+ <td><code>maven.repo.remote.enabled</code></td>
+ <td>
+ Whether or not a remote repository should be used.
+ </td>
+ <td><code>true</code></td>
+ </tr>
+ </table>
+ </subsection>
+ <subsection name="Proxy Properties">
+ <p>
+ If you do require a proxy, the most appropriate place to set these
+ values would be in your <code>${user.home}/build.properties</code>
+ file.
+ </p>
+ <table>
+ <tr>
+ <th>Property</th>
+ <th>Description</th>
+ <th>Default Value</th>
+ </tr>
+ <tr>
+ <td><code>maven.proxy.host</code></td>
<td>
The IP or address of your proxy.
</td>
+ <td>-</td>
</tr>
<tr>
- <td>maven.proxy.port</td>
+ <td><code>maven.proxy.port</code></td>
<td>
The port number of your proxy.
</td>
+ <td>-</td>
</tr>
<tr>
- <td>maven.proxy.username</td>
+ <td><code>maven.proxy.username</code></td>
<td>
User name if your proxy requires authentication.
</td>
+ <td>-</td>
</tr>
<tr>
- <td>maven.proxy.password</td>
+ <td><code>maven.proxy.password</code></td>
<td>
Password if your proxy requires authentication.
</td>
+ <td>-</td>
</tr>
<tr>
- <td>maven.proxy.ntlm.host</td>
+ <td><code>maven.proxy.ntlm.host</code></td>
<td>
The host to use if you are using NTLM authentication.
</td>
+ <td>-</td>
</tr>
<tr>
- <td>maven.proxy.ntlm.domain</td>
+ <td><code>maven.proxy.ntlm.domain</code></td>
<td>
The NT domain to use if you are using NTLM authentication.
</td>
+ <td>-</td>
</tr>
</table>
-
- <p>
- If you do require a proxy, the most appropriate place to set these
- values would be in your <code>${user.home}/build.properties</code>
- file.
- </p>
-
-<source><![CDATA[
-# ${user.home}/build.properties
-.
-.
-maven.proxy.host = my.proxyserver.com
-maven.proxy.port = 8080
-maven.proxy.username = username
-maven.proxy.password = password
-.
-.
-]]></source>
-
</subsection>
-
- <subsection name="Using Multiple Remote Repositories">
+ <subsection name="Deployment Properties">
<p>
- You can specify the use of multiple remote repositories in any of
- the properties files processed by Maven by using something like
- the following:
+ <b>DEPRECATED</b>: The following have all been deprecated in
favour of using the relevant elements in the
+ POM, and the properties of the <a
href="plugins/artifact/">artifact plugin</a>.
</p>
-
-<source><![CDATA[
-maven.repo.remote =
http://www.ibiblio.org/maven/,http://www.mycompany.com/maven/
-]]></source>
-
+ <table>
+ <tr>
+ <th>Property</th>
+ <th>Description</th>
+ <th>Default Value</th>
+ </tr>
+
+ <tr>
+ <td><code>maven.repo.central</code></td>
+ <td>
+ This is the host that Maven will attempt to deploy to. This is
deprecated in
+ favour of <code>distributionSite</code> and
<code>siteAddress</code>.
+ </td>
+ <td>-</td>
+ </tr>
+
+ <tr>
+ <td><code>maven.repo.central.directory</code></td>
+ <td>
+ This is the directory that Maven will attempt to deploy to.
This is deprecated in
+ favour of <code>distributionDirectory</code> and
<code>siteDirectory</code>.
+ </td>
+ <td>-</td>
+ </tr>
+
+ <tr>
+ <td><code>maven.scp.executable</code></td>
+ <td>
+ The executable to use for secure copies.
+ </td>
+ <td><code>scp</code></td>
+ </tr>
+
+ <tr>
+ <td><code>maven.ssh.executable</code></td>
+ <td>
+ The executable to use for executing commands remotely.
+ </td>
+ <td><code>ssh</code></td>
+ </tr>
+
+ <tr>
+ <td><code>maven.username</code></td>
+ <td>
+ The remote username to log in as when deploying.
+ </td>
+ <td>-</td>
+ </tr>
+
+ <tr>
+ <td><code>maven.remote.group</code></td>
+ <td>
+ The group to set the artifact to once deployed.
+ </td>
+ <td><code>maven</code></td>
+ </tr>
+ </table>
</subsection>
-
</section>
--->
+
+ <section name="Built-in Plugin Properties">
+ <p>
+ Each plugin has a set of built in properties. For a reference of
these properties, you can find a
+ "Properties" link in the left hand navigation of the <a
href="plugins/">plugin documentation</a> of
+ each individual plugin.
+ </p>
+ </section>
</body>
</document>
1.2 +7 -8 maven/xdocs/reference/repository-upload.xml
Index: repository-upload.xml
===================================================================
RCS file: /home/cvs/maven/xdocs/reference/repository-upload.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- repository-upload.xml 22 Nov 2004 11:52:58 -0000 1.1
+++ repository-upload.xml 1 Dec 2004 11:46:45 -0000 1.2
@@ -57,8 +57,8 @@
</p>
<source><![CDATA[LICENSE.txt
- project.xml
- foo-1.0.jar (or whatever artifact is referred to in the
project.xml)]]></source>
+project.xml
+foo-1.0.jar (or whatever artifact is referred to in the
project.xml)]]></source>
<p>
Note that the bundle will be read by a script, so it must follow
the above format. Also,
@@ -87,14 +87,13 @@
description field might look like:
</p>
- <source><![CDATA[
- http://wiggle.sourceforge.net/downloads/wiggle-1.0-bundle.jar
+
<source><![CDATA[http://wiggle.sourceforge.net/downloads/wiggle-1.0-bundle.jar
- http://wiggle.sourceforge.net
- http://wiggle.sourceforge.net/team-list.html
+http://wiggle.sourceforge.net
+http://wiggle.sourceforge.net/team-list.html
- Wiggle is a fantastic new piece of software for automating the
- clipping of nose hairs. Please upload!]]></source>
+Wiggle is a fantastic new piece of software for automating the
+clipping of nose hairs. Please upload!]]></source>
</subsection>
1.23 +6 -1 maven/xdocs/start/install.xml
Index: install.xml
===================================================================
RCS file: /home/cvs/maven/xdocs/start/install.xml,v
retrieving revision 1.22
retrieving revision 1.23
diff -u -r1.22 -r1.23
--- install.xml 22 Nov 2004 11:59:54 -0000 1.22
+++ install.xml 1 Dec 2004 11:46:45 -0000 1.23
@@ -41,6 +41,12 @@
</ul>
</p>
+ <p>
+ The final optional step is to set up a
<code>${user.home}/build.properties</code> file
+ to customise your Maven installation. For information on the
properties you can use, see
+ the <a href="../reference/properties.html">Properties Reference</a>.
+ </p>
+
<subsection name="Windows Installer">
<p>
Installing from the Windows Installer behaves like other Windows
Installers:
@@ -120,7 +126,6 @@
</subsection>
</section>
-<!-- TODO: build.properties setup - refer to properties reference -->
</body>
</document>
1.5 +4 -3 maven/xdocs/start/quick-start.xml
Index: quick-start.xml
===================================================================
RCS file: /home/cvs/maven/xdocs/start/quick-start.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- quick-start.xml 30 Nov 2004 13:13:13 -0000 1.4
+++ quick-start.xml 1 Dec 2004 11:46:45 -0000 1.5
@@ -49,7 +49,7 @@
</ol>
</p>
<p>
- The ... <!-- TODO: properties link --> document explains how to
configure Maven to use
+ The <a href="../reference/properties.html">Properties
Reference</a> explains how to configure Maven to use
different locations for the cache and download repository. By
default, these reside under
<code>${user.home}/.maven</code>.
</p>
@@ -110,8 +110,7 @@
</ul>
</p>
<p>
- <!-- TODO: verify jar actually has all these -->
- For more information on the JAR plugin, including FAQs, examples
and references for goals and properties,
+ For more information on the JAR plugin, including references for
goals and properties,
see the <a href="../reference/plugins/jar/">jar plugin
documentation</a>.
</p>
<p>
@@ -141,6 +140,8 @@
<p>
As for any plugin, more information on the <code>site</code> goals
can be
seen in the <a href="../reference/plugins/site/">site plugin
documentation</a>.
+ In addition to a goal and property reference, some plugins also
have their own set
+ of FAQs and examples.
</p>
<p>
To clean up after a build and start fresh, simply run:
1.4 +1 -1 maven/xdocs/using/developing-plugins.xml
Index: developing-plugins.xml
===================================================================
RCS file: /home/cvs/maven/xdocs/using/developing-plugins.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- developing-plugins.xml 30 Nov 2004 13:13:13 -0000 1.3
+++ developing-plugins.xml 1 Dec 2004 11:46:45 -0000 1.4
@@ -176,7 +176,7 @@
<p>
This property will be read from a variety of different places:
<code>project.properties</code> for the
current project, <code>build.properties</code> from your home
directory, or a system property as above.
- The order of precedence is given in ... <!-- TODO: link -->
+ The order of precedence is given in the <a
href="../reference/properties.html">Properties Reference</a>.
</p>
</subsection>
<subsection name="Using Plugin Resources">
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
