mirror of https://github.com/apache/maven.git
documentation enhancements, and added transitive dependencies document
git-svn-id: https://svn.apache.org/repos/asf/maven/components/trunk@163955 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Brett Leslie Porter
parent
2a143e22e6
commit
6055b99a56
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,113 @@
|
|||
<document>
|
||||
<properties>
|
||||
<title>Dependency Mechanism</title>
|
||||
<author email="brett@apache.org">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>
|
||||
|
||||
|
|
@ -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>
|
||||
|
|
|
|||
|
|
@ -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 @@ m2 archetype:create
|
|||
</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>
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
|
|||
|
|
@ -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">
|
||||
|
|
|
|||
Loading…
Reference in New Issue