brett 2005/04/15 04:08:17
Modified: maven-site/src/site/xdoc docs-required.xml
getting-started.xml index.xml navigation.xml
maven-model maven.mdo
Added: maven-site/src/site/xdoc dependencies.xml
Log:
documentation enhancements, and added transitive dependencies document
Revision Changes Path
1.2 +3 -2
maven-components/maven-site/src/site/xdoc/docs-required.xml
Index: docs-required.xml
===================================================================
RCS file:
/home/cvs/maven-components/maven-site/src/site/xdoc/docs-required.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- docs-required.xml 14 Apr 2005 06:28:59 -0000 1.1
+++ docs-required.xml 15 Apr 2005 11:08:16 -0000 1.2
@@ -13,13 +13,14 @@
</p>
<p style="font-size: larger; font-weight: bold">Documentation for
users</p>
<ul>
- <li>transitive dependencies</li>
- <li>dependency scope</li>
<li>new SNAPSHOT handling -
<i>partially done on Brett's blog</i>
</li>
<li>deployment mechanism</li>
<li>build lifecycle documentation</li>
+ <li>dependency management</li>
+ <li>plugin management</li>
+ <li>plugin configuration</li>
</ul>
<p style="font-size: larger; font-weight: bold">Documentation for
plugin authors</p>
<ul>
1.6 +7 -1
maven-components/maven-site/src/site/xdoc/getting-started.xml
Index: getting-started.xml
===================================================================
RCS file:
/home/cvs/maven-components/maven-site/src/site/xdoc/getting-started.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- getting-started.xml 11 Apr 2005 16:30:57 -0000 1.5
+++ getting-started.xml 15 Apr 2005 11:08:16 -0000 1.6
@@ -10,6 +10,11 @@
to build any project that requires Maven 2.0. It assumed that you
have already
<a href="download.html">Downloaded and Installed</a> a Maven 2.0
release.
</p>
+ <p>
+ If you are behind a proxy, make sure that you've read
+ <a href="configuration.html">Configuring Maven</a> first
+ for instructions on how to configure your proxy.
+ </p>
<subsection name="Creating a Project Skeleton">
<p>
The first step is to create a Maven 2.0 project to work on. Run
the following command:
@@ -249,7 +254,8 @@
</p>
<source>m2 clean:clean install</source>
<p>
- <b>Note: </b> If you didn't remove the <code>warName</code> plugin
configuration, this will have
+ <b>Note: </b> If you didn't remove the
+ <code>warName</code> plugin configuration, this will have
failed due to a bug. Please remove that section, and try again.
</p>
<p>
1.11 +5 -0 maven-components/maven-site/src/site/xdoc/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/maven-components/maven-site/src/site/xdoc/index.xml,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- index.xml 14 Apr 2005 06:28:59 -0000 1.10
+++ index.xml 15 Apr 2005 11:08:16 -0000 1.11
@@ -127,6 +127,11 @@
<a href="configuration.html">Configuring Maven</a>
</i>
</li>
+ <li>
+ <i>
+ <a href="dependencies.html">Dependency Mechanism</a>
+ </i>
+ </li>
<!-- TODO
<li>
<i>
1.8 +2 -3 maven-components/maven-site/src/site/xdoc/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/maven-components/maven-site/src/site/xdoc/navigation.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- navigation.xml 14 Apr 2005 06:28:59 -0000 1.7
+++ navigation.xml 15 Apr 2005 11:08:16 -0000 1.8
@@ -15,9 +15,8 @@
</menu>
<menu name="User's Guide">
<item name="Getting Started" href="getting-started.html"/>
- <!-- TODO
- <item name="Configuration" href="configuration.html"/>
- -->
+ <item name="Configuration" href="configuration.html"/>
+ <item name="Dependency Mechanism" href="dependencies.html"/>
<item name="Developing Plugins with Marmalade"
href="developing-plugins-with-marmalade.html"/>
</menu>
<menu name="Reference">
1.1
maven-components/maven-site/src/site/xdoc/dependencies.xml
Index: dependencies.xml
===================================================================
<document>
<properties>
<title>Dependency Mechanism</title>
<author email="[EMAIL PROTECTED]">Brett Porter</author>
</properties>
<body>
<section name="Dependency Mechanism">
<p>
There are many aspects to working with dependencies in Maven. While
it is not the sole focus of Maven, it
does comprise a large and important part of the system.
</p>
<p>
This document is currently in the process of being written, so not
all facets are covered.
</p>
<subsection name="Transitive Dependencies">
<p>
Transitive dependencies are a new feature in Maven 2.0. This allows
you to avoid needing to discover and
specify the libraries that your own dependencies require, and
including them automatically.
</p>
<p>
This feature is facilitated by reading the project files of your
dependencies from the remote repositories
specified. In general, all dependencies of those projects are used
in your project, as are any that the
project inherits from its parents, or from its dependencies, and so
on.
</p>
<p>
There is no limit to the number of levels that dependencies can be
gathered from, and will only cause a problem
if a cyclic dependency is discovered.
</p>
<p>
With transitive dependencies, the graph of included libraries can
quickly grow quite large. For this reason,
there are some additional features that will limit which
dependencies are included:
</p>
<ul>
<li>
<i>Dependency mediation</i> - this determines what version of a
dependency will be used when multiple
different ones are encountered. Currently, Maven 2.0 only
supports using the "nearest definition" - so
you can always guarantee a version by declaring it explicitly in
the project's POM.
</li>
<li>
<i>Dependency scope</i> - this allows you to only include
dependencies appropriate for the current stage
of the build. This is described in more detail below.
</li>
</ul>
<p>
More features are planned, such as different mediation techniques
and conflict management as well as reporting,
in later alpha versions of Maven 2.0.
</p>
</subsection>
<subsection name="Dependency Scope">
<p>
Dependency scope is used to limit the transitivity of a depedency,
and also to affect the classpath used for
various build tasks.
</p>
<p>
There are 3 scopes available:
</p>
<ul>
<li>
<b>compile</b> - this is the default scope, used if none is
specified. Compile dependencies are available
in all classpaths.
</li>
<li>
<b>runtime</b> - this scope indicates that the dependency is not
required for compilation, but is for execution.
It is in the runtime and test classpaths, but not the compile
classpath.
</li>
<li>
<b>test</b> - this scope indicates that the dependency is not
required for normal use of the application, and
is only available for the test compilation and execution phases.
</li>
</ul>
<p>
Each of the scopes affects transitive dependencies in different
ways, as is demonstrated in the table below.
If a dependency is set to the scope in the left column,
dependencies with the scope across the top row will
result in a dependency in the main project with the scope listed at
the intersection. If no scope is listed,
it means the dependency will be omitted.
</p>
<table>
<tr>
<th></th>
<th>compile</th>
<th>runtime</th>
<th>test</th>
</tr>
<tr>
<th>compile</th>
<td>compile</td>
<td>runtime</td>
<td>-</td>
</tr>
<tr>
<th>runtime</th>
<td>compile (*)</td>
<td>runtime</td>
<td>-</td>
</tr>
<tr>
<th>test</th>
<td>test</td>
<td>test</td>
<td>-</td>
</tr>
</table>
<p>
<b>(*) Note: </b> it is intended that this should be runtime
instead, so that all compile dependencies must
be explicitly listed - however, there is the case where the library
you depend on extends a class from another
library, forcing you to have available at compile time. For this
reason, compile time dependencies remain
as compile scope even when they are transitive.
</p>
</subsection>
</section>
</body>
</document>
1.98 +1 -1 maven-components/maven-model/maven.mdo
Index: maven.mdo
===================================================================
RCS file: /home/cvs/maven-components/maven-model/maven.mdo,v
retrieving revision 1.97
retrieving revision 1.98
diff -u -r1.97 -r1.98
--- maven.mdo 9 Apr 2005 02:07:15 -0000 1.97
+++ maven.mdo 15 Apr 2005 11:08:16 -0000 1.98
@@ -1092,7 +1092,7 @@
<name>scope</name>
<version>4.0.0</version>
<description>
- The scope of the dependency - build, compile, test, runtime.
Used to
+ The scope of the dependency - compile, runtime, test. Used to
calculate the various classpaths used for testing, etc. and for
determining which artifacts to include in a distribution of this
project.
