Author: xavier
Date: Wed Nov 21 10:23:06 2007
New Revision: 597169
URL: http://svn.apache.org/viewvc?rev=597169&view=rev
Log:
update and improve doc on cache and change management
Modified:
incubator/ivy/core/trunk/doc/concept.html
incubator/ivy/core/trunk/doc/configuration/resolvers.html
incubator/ivy/core/trunk/doc/ivyfile/dependency.html
incubator/ivy/core/trunk/doc/terminology.html
Modified: incubator/ivy/core/trunk/doc/concept.html
URL:
http://svn.apache.org/viewvc/incubator/ivy/core/trunk/doc/concept.html?rev=597169&r1=597168&r2=597169&view=diff
==============================================================================
--- incubator/ivy/core/trunk/doc/concept.html (original)
+++ incubator/ivy/core/trunk/doc/concept.html Wed Nov 21 10:23:06 2007
@@ -230,7 +230,23 @@
</ul>
See the <a href="configuration/conf.html">configuration page</a> to see how to
configure the circular dependency strategy you want to use.
- </textarea>
+
+<h1><a name="change">Cache and Change Management</a></h1>
+Ivy heavily relies on a local cache to avoid accessing remote repositories too
often, thus saving a low of network bandwidth and time. To optimize the
dependency resolution and the way the cache is used, Ivy assumes by default
that a revision never changes. So once Ivy has a module in its cache (metadata
and artifacts), it trusts the cache and do not even query the repository. This
optimization is very useful in most cases, and causes no problem as long as you
respect this paradigm: a revision never changes. Besides performance, there are
several [[bestpractices good reasons]] to follow this principle.
+
+However, depending on your current build system and your dependency management
strategy, you may prefer to update sometimes your modules. There are two kind
of changes to consider:
+<h3>change in module metadata</h3>
+Since pretty often module metadata are not considered by module providers with
as much attention as their API or behavior (if they even provide module
metadata), it happens more than we would like that we have to update module
metadata: a dependency has been forgotten, or another one is missing, ...
+
+In this case, setting checkModified="true" on your dependency resolver will be
the solution. This flag tells to Ivy to check if module metadata has been
modified compared to the cache. Ivy first checks the metadata last modified
timestamp on the repository to download it only if necessary, and then update
it when needed.
+<h3>Changes in artifacts</h3>
+Some people, especially those coming from maven 2 land, like to use one
special revision to handle often updated modules. In maven 2 this is called a
SNAPSHOT version, and some argue that it helps saves disk space to keep only
one version for the high number of intermediary builds you can make whilst
developing.
+
+Ivy supports this kind of approach with the notion of changing revision. A
changing revision is just that: a revision for which Ivy should consider that
the artifacts may change over time. To handle this, you can either specify a
dependency as changing on the [[ivyfile/dependency]] tag, or use the
changingPattern and changingMatcher attributes on your
[[configuration/resolvers]] to indicate which revision or group of revisions
should be considered as changing.
+
+Once Ivy knows that a revision is changing, it will follow this principle to
avoid checking your repository too often: if the module metadata has not
changed, it will considered the whole module (including artifacts) as not
changed. Even if the module descriptor file has changed, it will check the
publication data of the module to see if this is a new publication of the same
revision or not. Then if the publication date has changed, it will check the
artifacts last modified timestamps, and download them accordingly.
+
+So if you want to use changing revisions, use the [[ant:publish]] task to
publish your modules, it will take care of updating the publication date, and
everything will work fine. And remember to set checkModified=true" on your
resolver too!</textarea>
<script type="text/javascript">xooki.postProcess();</script>
</body>
</html>
Modified: incubator/ivy/core/trunk/doc/configuration/resolvers.html
URL:
http://svn.apache.org/viewvc/incubator/ivy/core/trunk/doc/configuration/resolvers.html?rev=597169&r1=597168&r2=597169&view=diff
==============================================================================
--- incubator/ivy/core/trunk/doc/configuration/resolvers.html (original)
+++ incubator/ivy/core/trunk/doc/configuration/resolvers.html Wed Nov 21
10:23:06 2007
@@ -95,12 +95,12 @@
<td>No</td>
<td>Yes</td>
</tr>
- <tr><td>changingPattern</td><td>Indicates for which revision pattern this
resolver should check lastmodified date to know if an artifact file is up to
date. <span class="since">since 1.4</span></td>
+ <tr><td>changingPattern</td><td>Indicates for which revision pattern this
resolver should check lastmodified date to know if an artifact file is up to
date. <span class="since">since 1.4</span>. See <a
href="../concept.html#change">cache and change management</a> for details.</td>
<td>No, defaults to none</td>
<td>Yes</td>
<td>Yes</td>
</tr>
- <tr><td>changingMatcher</td><td>The name of the <a
href="../concept.html#matcher">pattern matcher</a> to use to match a revision
against the configured changingPattern. <span class="since">since
1.4</span></td>
+ <tr><td>changingMatcher</td><td>The name of the <a
href="../concept.html#matcher">pattern matcher</a> to use to match a revision
against the configured changingPattern. <span class="since">since 1.4</span>.
See <a href="../concept.html#change">cache and change management</a> for
details.</td>
<td>No, defaults to exactOrRegexp</td>
<td>Yes</td>
<td>Yes</td>
Modified: incubator/ivy/core/trunk/doc/ivyfile/dependency.html
URL:
http://svn.apache.org/viewvc/incubator/ivy/core/trunk/doc/ivyfile/dependency.html?rev=597169&r1=597168&r2=597169&view=diff
==============================================================================
--- incubator/ivy/core/trunk/doc/ivyfile/dependency.html (original)
+++ incubator/ivy/core/trunk/doc/ivyfile/dependency.html Wed Nov 21 10:23:06
2007
@@ -114,12 +114,12 @@
<h2>Artifact restriction</h2>
Moreover, the dependency element also supports an artifact restriction feature
(since 0.6).
-See <a href="#dependency-artifact">dependency artifact restriction</a> for
details. <br/><br/>
+See <a href="#dependency-artifact">dependency artifact restriction</a> for
details.
<h2>Forcing revision</h2>
Finally, the dependency element also supports an a force attribute (since
0.8), which gives an indication
-to conflicts manager to force the revision of a dependency to the one given
here.<br/>
-See <a href="../ivyfile/conflicts.html">conflicts manager</a> for details.
<br/><br/>
+to conflicts manager to force the revision of a dependency to the one given
here.
+See <a href="../ivyfile/conflicts.html">conflicts manager</a> for details.
<span class="since">since 1.4</span> this tag supports <a
href="../concept.html#extra">extra attributes</a>
<h1>Attributes</h1>
@@ -143,7 +143,7 @@
<td>No, defaults to defaultconf attribute of dependencies element if
neither conf attribute nor conf children element is given</td></tr>
<tr><td>transitive</td><td>true to resolve this dependency transitively,
false otherwise (<span class="since">since 1.2</span>)</td>
<td>No, defaults to true</td></tr>
- <tr><td>changing</td><td>true if the dependency artifacts may change
without revision change, false otherwise (<span class="since">since
1.2</span>). Artifacts update will be looked after only if the publication date
of the ivy file has changed. Note that this is not a recommended use and that
it avoid some cache optimization in ivy.</td>
+ <tr><td>changing</td><td>true if the dependency artifacts may change
without revision change, false otherwise (<span class="since">since
1.2</span>). See <a href="../concept.html#change">cache and change
management</a> for details.</td>
<td>No, defaults to false</td></tr>
</tbody>
</table>
Modified: incubator/ivy/core/trunk/doc/terminology.html
URL:
http://svn.apache.org/viewvc/incubator/ivy/core/trunk/doc/terminology.html?rev=597169&r1=597168&r2=597169&view=diff
==============================================================================
--- incubator/ivy/core/trunk/doc/terminology.html (original)
+++ incubator/ivy/core/trunk/doc/terminology.html Wed Nov 21 10:23:06 2007
@@ -26,12 +26,6 @@
<body>
<textarea id="xooki-source">
Here are some terms used in Ivy, with their definitions in Ivy:<br/>
-<h2>Ivy file</h2>
-An ivy file is an xml file which is used to describe dependencies of a module
(see below). It is usually named ivy.xml.
-<h2>Settings</h2>
-Ivy settings files are xml files used to configure ivy to indicate where the
dependencies can be found and how.
-<em>Prior to Ivy 2.0, these files were called configuration files and usually
named ivyconf.xml. This resulted in a confusion between module configurations
and configuration files, so they have been renamed in settings files.
-If you happen to fall on an ivyconf file or something called a configuration
file, most of the time it's only a problem of update of the
doc/tutorial/article. Feel free to report any problem like this if you find
such inconsistencies in this documentation.</em>
<h2>Organisation</h2>
An organisation is either a company or a simple group of person
which produce software. Ivy handle only one level of organisation, so you
cannot
@@ -72,6 +66,20 @@
<li>release: revision fully tested and labelled fall in this category</li>
</ul>
<span class="since">since 1.4</span> This list is <a
href="configuration/statuses.html">configurable</a> in your configuration file.
+<h2>Module descriptor or metadata</h2>
+A generic way to identify what describes a module: the identifier
(organisation, name, branch, revision), the published artifacts and the
dependencies.
+
+The most common module descriptors in Ivy are [[ivyfile]], xml files with an
Ivy specific syntax, and usually called ivy.xml.
+
+But since Ivy is also compatible with maven 2 metadata format (called pom, for
Project Object Model), pom files falls into the category of module descriptors.
+
+And because Ivy accepts pluggable module descriptor parsers, you can use
almost whatever you want as module descriptors.
+
+<h2>Settings</h2>
+Ivy settings files are xml files used to configure ivy to indicate where the
modules can be found and how.
+<em>Prior to Ivy 2.0, these files were called configuration files and usually
named ivyconf.xml. This resulted in a confusion between module configurations
and configuration files, so they have been renamed in settings files.
+If you happen to fall on an ivyconf file or something called a configuration
file, most of the time it's only a problem of update of the
doc/tutorial/article. Feel free to report any problem like this if you find
such inconsistencies in this documentation.</em>
+
<h2>Repository</h2>
What is called a repository in Ivy is a location where Ivy is able to find
your modules artifacts and metadata (i.e. ivy files in most cases).
Ivy can be used with complex repositories configured very finely. You can use
<a href="concept.html">Dependency Resolvers</a> to do so.
