You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@maven.apache.org by br...@apache.org on 2005/03/03 14:39:30 UTC
svn commit: r156037 - in maven/maven-1/core/trunk/xdocs: navigation.xml
reference/internal-repositories.xml using/managing-dependencies.xml
using/migrating.xml using/repositories.xml
Author: brett
Date: Thu Mar 3 05:39:27 2005
New Revision: 156037
URL: http://svn.apache.org/viewcvs?view=rev&rev=156037
Log:
dependency and repository documentation
Added:
maven/maven-1/core/trunk/xdocs/using/managing-dependencies.xml (with props)
Modified:
maven/maven-1/core/trunk/xdocs/navigation.xml
maven/maven-1/core/trunk/xdocs/reference/internal-repositories.xml
maven/maven-1/core/trunk/xdocs/using/migrating.xml
maven/maven-1/core/trunk/xdocs/using/repositories.xml
Modified: maven/maven-1/core/trunk/xdocs/navigation.xml
URL: http://svn.apache.org/viewcvs/maven/maven-1/core/trunk/xdocs/navigation.xml?view=diff&r1=156036&r2=156037
==============================================================================
--- maven/maven-1/core/trunk/xdocs/navigation.xml (original)
+++ maven/maven-1/core/trunk/xdocs/navigation.xml Thu Mar 3 05:39:27 2005
@@ -71,6 +71,7 @@
<item name="Making Releases" href="/using/releasing.html" />
<item name="Web Applications" href="/using/war.html" />
<item name="Multiple Modules" href="/using/multiproject.html" />
+ <item name="Handling Dependencies" href="/using/managing-dependencies.html" />
<item name="Migrating from Ant" href="/using/migrating.html" />
<item name="Best Practices" href="/using/bestpractices.html" />
</item>
Modified: maven/maven-1/core/trunk/xdocs/reference/internal-repositories.xml
URL: http://svn.apache.org/viewcvs/maven/maven-1/core/trunk/xdocs/reference/internal-repositories.xml?view=diff&r1=156036&r2=156037
==============================================================================
--- maven/maven-1/core/trunk/xdocs/reference/internal-repositories.xml (original)
+++ maven/maven-1/core/trunk/xdocs/reference/internal-repositories.xml Thu Mar 3 05:39:27 2005
@@ -25,7 +25,6 @@
</properties>
<body>
- <!-- TODO: should this be part of repositories in using, or at least linked to it? -->
<section name="Internal Repositories">
<p>
When using Maven, particularly in a corporate environment, connecting to the internet to download dependencies
Added: maven/maven-1/core/trunk/xdocs/using/managing-dependencies.xml
URL: http://svn.apache.org/viewcvs/maven/maven-1/core/trunk/xdocs/using/managing-dependencies.xml?view=auto&rev=156037
==============================================================================
--- maven/maven-1/core/trunk/xdocs/using/managing-dependencies.xml (added)
+++ maven/maven-1/core/trunk/xdocs/using/managing-dependencies.xml Thu Mar 3 05:39:27 2005
@@ -0,0 +1,151 @@
+<?xml version="1.0"?>
+<!--
+/*
+ * Copyright 2001-2005 The Apache Software Foundation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+ -->
+
+<document>
+
+ <properties>
+ <title>Handling Dependencies</title>
+ <author email="jason@zenplex.com">Jason van Zyl</author>
+ <author email="brett@apache.org">Brett Porter</author>
+ </properties>
+
+ <body>
+ <section name="Handling Dependencies">
+ <p>
+ One benefit of Maven is that it can make you much more aware of dependencies your project has on other libraries.
+ This outlines some ways to keep track of your dependencies, and to keep them in sync.
+ This is particularly the case in a multiproject scenario.
+ </p>
+ <subsection name="Overriding Stated Dependencies">
+ <p>
+ You may find it convenient, or necessary, at times to override the
+ dependencies stated in a given POM. You may wish to use JAR artifacts
+ somewhere in the filesystem or you may wish simply to override the stated
+ version of a given JAR artifact. For this Maven provides
+ an easy way for you to select which artifacts you want to use for
+ building.
+ </p>
+
+ <p>
+ In order to use the JAR override feature, you must set the
+ <code>maven.jar.override</code> property to
+ <code>on</code>. Once this property is
+ set you can specify JAR override directives in any of the properties
+ files that maven processes.
+ </p>
+
+ <p>
+ There are two type of JAR override directives. The first form allows
+ you to specify a specific JAR artifact path for a given artifactId; the
+ second allows you to specify a specific version of a JAR artifact that
+ exists in your local repository. The two forms are as follows:
+ </p>
+
+ <source><![CDATA[maven.jar.artifactId = [path]
+maven.jar.artifactId = [version]]]></source>
+
+ <p>
+ Below is an example of what a properties file might look like that
+ contains JAR override directives:
+ </p>
+
+ <source><![CDATA[maven.jar.override = on
+
+# Jars set explicity by path.
+maven.jar.a = ${basedir}/lib/a.jar
+maven.jar.b = ${basedir}/lib/b.jar
+
+# Jars set explicity by version.
+maven.jar.classworlds = 1.0-beta-1]]></source>
+ </subsection>
+
+ <subsection name="Version Consistency">
+ <p>
+ The version override is of particular assistance when you are attempting to maintain a consistent version across
+ different subprojects, and is a much better alternative to using entities or property interpolation.
+ </p>
+ <p>
+ The situation is that you have a number of subprojects using similar, but not identical dependencies - but that
+ when a particular dependency is used you want to ensure the version is consistent.
+ </p>
+ <p>
+ You can use inheritence to set up the structure, but can't put the dependency in the parent POM as all subprojects
+ will inherit that particular dependency whether they want it or not.
+ </p>
+ <p>
+ The best way to implement it is to put the dependency in each subproject as required, but put the <i>version
+ override</i> in the parent POM. Wherever the dependency appears, that version will be used, but the dependency
+ will not be used unless it is actually declared.
+ </p>
+ </subsection>
+
+ <subsection name="Using SNAPSHOT Dependencies">
+ <p>
+ In Maven versions containing the keyword <code>SNAPSHOT</code> are considered special.
+ They approximate the latest development build of a project that has been deployed to the repository.
+ If a project that you depend on is changing frequently you can state
+ in your POM that you wish to try and keep up with that project by declaring
+ it a SNAPSHOT dependency. So, for example, you may be trying to stay abreast
+ of changes in
+ <a href="http://jakarta.apache.org/commons/jelly/">Jelly</a> so
+ you might put the following in your POM:
+ </p>
+ <source><![CDATA[<dependency>
+ <groupId>commons-jelly</groupId>
+ <artifactId>commons-jelly</artifactId>
+ <version>SNAPSHOT</version>
+</dependency>]]></source>
+
+ <p>
+ Assuming that project is publishing a version called <code>SNAPSHOT</code> (which happens when the
+ <code>jar:deploy-snapshot</code> goal is called), then each time you build Maven will check the remote
+ repository for changes in that JAR and download it again if a newer version is available.
+ </p>
+
+ <p>
+ If you are working offline Maven will warn you that your SNAPSHOT dependencies may be out of date. This is
+ just a warning, and as the remote copy often does not change frequently can be ignored.
+ </p>
+
+ <p>
+ <b>Note:</b> the version need only contain the word <code>SNAPSHOT</code> - it does not need to equal it
+ exactly. It is traditional to append it to a version to indicate "development towards version X". For example,
+ <code>1.2-SNAPSHOT</code> is the development version between 1.1 and 1.2.
+ </p>
+ </subsection>
+
+ <subsection name="Keeping Track of Dependencies">
+ <p>
+ Maven provides two site reports that can assist in keeping track of dependencies.
+ </p>
+ <p>
+ The standard dependency report included in the "Project Info" section of every site lists out the information
+ for each dependency in the project, including those inherited. This is mostly useful to new users of your
+ application or library that wish to see what additional dependencies they will require to use it.
+ </p>
+ <p>
+ The other report is given by the multiproject plugin, and is called the <i>Dependency Convergence Report</i>.
+ This report will look for matching dependencies with different versions in your multiproject set up, so that
+ you can synchronize those using different versions. The section above on <a href="#Version_Consistency">Version
+ Consistency</a> can help automate this.
+ </p>
+ </subsection>
+ </section>
+ </body>
+</document>
Propchange: maven/maven-1/core/trunk/xdocs/using/managing-dependencies.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/maven-1/core/trunk/xdocs/using/managing-dependencies.xml
------------------------------------------------------------------------------
svn:executable = *
Propchange: maven/maven-1/core/trunk/xdocs/using/managing-dependencies.xml
------------------------------------------------------------------------------
svn:keywords = "Author Date Id Revision"
Modified: maven/maven-1/core/trunk/xdocs/using/migrating.xml
URL: http://svn.apache.org/viewcvs/maven/maven-1/core/trunk/xdocs/using/migrating.xml?view=diff&r1=156036&r2=156037
==============================================================================
--- maven/maven-1/core/trunk/xdocs/using/migrating.xml (original)
+++ maven/maven-1/core/trunk/xdocs/using/migrating.xml Thu Mar 3 05:39:27 2005
@@ -31,9 +31,9 @@
do that. It will not touch on the reasons for using Maven over Ant, or whether Maven or Ant is better for your
project - these issues are discussed in <a href="../start/maven-for-ant-users.html">Maven for Ant Users.</a>
</p>
- <subsection name="Calling Ant Scripts from Maven">
+ <subsection name="Getting Started - Creating a Project Descriptor">
<p>
- Often, people want to get their feet wet with Maven by using it to do the standard things, but to use their
+ Sometimes people want to get their feet wet with Maven by using it to do the standard things, but to use their
existing Ant build that is working fine for complex tasks. This is possible.
</p>
<p>
@@ -41,6 +41,31 @@
<a href="../reference/project-descriptor.html">project file</a> with the information you need to do
the Maven tasks you are using.
</p>
+ <p>
+ Even when you are already using Ant, this project file can be set up like any other new project. For a
+ tutorial on doing so, see the <a href="../start/ten-minute-test.html">Getting Started</a> guide to creating a
+ project.
+ </p>
+ </subsection>
+ <subsection name="Using Existing Libraries">
+ <p>
+ Often, an Ant project will look for dependent libraries to add to the classpath in a known location on the
+ filysystem (often a subdirectory of the build checked out of source control along with the source code).
+ In some cases, the <code><get/></code> task is used to retrieve them remotely.
+ </p>
+ <p>
+ It is recommended that you establish repositories and let Maven take care of this. If the dependencies are
+ not in the Maven central repository, set up an <a href="../reference/internal-repositories.html">internal
+ repository</a>. Publish your resulting artifacts to that repository also.
+ </p>
+ <p>
+ However, if there is a necessaity to maintain the file based approach, or you wish to start with that to keep
+ the number of changes down, you can use JAR overrides to have Maven look for dependencies on the file system.
+ For more information, see <a href="managing-dependencies.html#Overriding_Stated_Dependencies">Handling
+ Dependencies</a>.
+ </p>
+ </subsection>
+ <subsection name="Calling Ant Scripts from Maven">
<p>
In the same directory as this
<code>project.xml</code> file (and probably in the same place as your ant build)
Modified: maven/maven-1/core/trunk/xdocs/using/repositories.xml
URL: http://svn.apache.org/viewcvs/maven/maven-1/core/trunk/xdocs/using/repositories.xml?view=diff&r1=156036&r2=156037
==============================================================================
--- maven/maven-1/core/trunk/xdocs/using/repositories.xml (original)
+++ maven/maven-1/core/trunk/xdocs/using/repositories.xml Thu Mar 3 05:39:27 2005
@@ -1,7 +1,7 @@
<?xml version="1.0"?>
<!--
/*
- * Copyright 2001-2004 The Apache Software Foundation.
+ * Copyright 2001-2005 The Apache Software Foundation.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -108,155 +108,41 @@
<code>${maven.repo.remote},http://planetmirror.com/maven</code>, but currently this causes an infinite
recursion).
</p>
- </subsection>
- <subsection name="Uploading to a Remote Repository">
<p>
- While this is possible for any type of remote repository, you must have the permission to do so. Usually,
- you will only be attempting to upload a release of your own application to an internal repository.
- See <a href="../reference/internal-repositories.html">internal repositories</a> for more information.
+ For more information on dependencies, see <a href="managing-dependencies.html">Handling Dependencies</a>.
</p>
</subsection>
- </section>
-
-<!-- TODO: not net used, but belongs elsewhere
- <subsection name="Overriding Stated Dependencies">
- <p>
- You may find it convenient, or necessary, at times to override the
- dependencies stated in a given POM. You may wish to use JAR artifacts
- somewhere in the filesystem or you may wish simply to override the stated
- version of a given JAR artifact. For this Maven provides
- an easy way for you to select which artifacts you want to use for
- building. It is highly recommended that you set up your own local
- repository: but in cases where expediency is a concern, or you are
- migrating from an Ant build the JAR override feature may come
- in handy.
- </p>
-
- <p>
- In order to use the JAR override feature, you must set the
- <code>maven.jar.override</code> property to <code>on</code>. Once this property is
- set you can specify JAR override directives in any of the properties
- files that maven processes.
- </p>
-
- <p>
- There are two type of JAR override directives. The first form allows
- you to specify a specific JAR artifact path for a given artifactId; the
- second allows you to specify a specific version of a JAR artifact that
- exists in your local repository. The two forms are as follows:
- </p>
-
-<source><![CDATA[
-
-maven.jar.artifactId = [path]
-
-maven.jar.artifactId = [version]
-
-]]></source>
-
- <p>
- Below is an example of what a properties file might look like that
- contains JAR override directives:
- </p>
-
-<source><![CDATA[
-# M A V E N J A R O V E R R I D E
-maven.jar.override = on
-
-# Jars set explicity by path.
-maven.jar.a = ${basedir}/lib/a.jar
-maven.jar.b = ${basedir}/lib/b.jar
-
-# Jars set explicity by version.
-maven.jar.classworlds = 1.0-beta-1
-]]></source>
- </subsection>
-
- <subsection name="Using SNAPSHOT Dependencies">
- <p>
- In Maven SNAPSHOTs are artifacts that aproximate the latest build of a particular
- project. If a project that you depend on is changing frequently you can state
- in your POM that you wish to try and keep up with that project by declaring
- it a SNAPSHOT dependency. So, for example, you may be trying to stay abreast
- of changes in <a href="http://jakarta.apache.org/commons/jelly/">Jelly</a> so
- you might put the following in your POM:
- </p>
-<source><![CDATA[
-<project>
- ...
- <dependencies>
-
- <dependency>
- <groupId>commons-jelly</groupId>
- <artifactId>commons-jelly</artifactId>
- <version>SNAPSHOT</version>
- </dependency>
-
- </dependencies>
- ...
-</project>
-]]></source>
-
- <p>
- This tells Maven that you are always looking to use the latest build of
- Jelly that is available in the Maven repository. Internally to Maven
- SNAPSHOT dependencies are always considered failed dependencies. That
- being the case Maven will always try to retrieve a copy of a SNAPSHOT
- dependency from the Maven repository. If you are working offline Maven
- will warn you that your SNAPSHOT dependencies may be out of date.
- </p>
-
- </subsection>
-
<subsection name="Building Offline">
<p>
If you find you need to build your projects offline you can either
use the offline switch on the CLI:
</p>
- <source><![CDATA[
-maven -o jar:jar
- ]]></source>
- <p>
- which is equivalent to:
- </p>
- <source><![CDATA[
-maven -Dmaven.mode.online=false jar:jar
- ]]></source>
+ <source><![CDATA[maven -o jar:jar]]></source>
<p>
- Or you can set <code>maven.mode.online</code> to
- <code>false</code> in a <a href="#Properties Processing">property file</a>.
+ This is equivalent to:
</p>
+ <source><![CDATA[maven -Dmaven.mode.online=false jar:jar]]></source>
<p>
- In online mode, maven always downloads SNAPSHOT dependencies, see
- <a href="#Using SNAPSHOT Dependencies">Using SNAPSHOT Dependencies</a>.
- If the snapshots in your local repository are younger than the ones
- on the server, you propably don't want that maven overwrites you local
- snapshot jars.
- To avoid downloading, set this property:
+ Or you can set
+ <code>maven.mode.online</code> to
+ <code>false</code> in your <code>build.properties</code> file to ensure you always work offline.
</p>
- <source><![CDATA[
-maven.repo.remote.enabled=false
- ]]></source>
<p>
- In maven beta 9, this property does not work (but it's fixed in newer releases).
- Clearing the property <code>maven.repo.remote</code> by setting:
+ Note that many plugins will honour the offline setting and not perform any operations that would connect to
+ the internet. Some examples are resolving Javadoc links and link checking the site.
</p>
- <source><![CDATA[
-maven.repo.remote.enabled=
- ]]></source>
<p>
- via CLI or a property file has the same effect.
+ If you would like normal operations to succeed, but for no dependency downloading to occur, set the
+ <code>maven.repo.remote.enabled</code> property to <code>false</code>.
</p>
+ </subsection>
+ <subsection name="Uploading to a Remote Repository">
<p>
- Using <code>maven.repo.remote.enabled=false</code> and
- <code>maven.mode.online=true</code> is the combination to use if one needs a working
- "-link" option for the javadoc plugin plus no download of snapshot/any jars.
+ While this is possible for any type of remote repository, you must have the permission to do so. Usually,
+ you will only be attempting to upload a release of your own application to an internal repository.
+ See <a href="../reference/internal-repositories.html">internal repositories</a> for more information.
</p>
-
</subsection>
-
</section>
--->
-
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org