Author: xavier
Date: Fri Jan 4 07:10:36 2008
New Revision: 608880
URL: http://svn.apache.org/viewvc?rev=608880&view=rev
Log:
update documentation according to recent cache management changes
Added:
ant/ivy/core/trunk/doc/configuration/caches/
ant/ivy/core/trunk/doc/configuration/caches.html (with props)
ant/ivy/core/trunk/doc/configuration/caches/cache.html (with props)
Removed:
ant/ivy/core/trunk/doc/configuration/cacheDefaults.html
Modified:
ant/ivy/core/trunk/doc/concept.html
ant/ivy/core/trunk/doc/configuration.html
ant/ivy/core/trunk/doc/configuration/conf.html
ant/ivy/core/trunk/doc/toc.json
Modified: ant/ivy/core/trunk/doc/concept.html
URL:
http://svn.apache.org/viewvc/ant/ivy/core/trunk/doc/concept.html?rev=608880&r1=608879&r2=608880&view=diff
==============================================================================
--- ant/ivy/core/trunk/doc/concept.html (original)
+++ ant/ivy/core/trunk/doc/concept.html Fri Jan 4 07:10:36 2008
@@ -231,11 +231,27 @@
See the <a href="configuration/conf.html">configuration page</a> to see how to
configure the circular dependency strategy you want to use.
-<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.
+<h1>Cache and Change Management</h1>
+Ivy heavily relies on local cache(s) to avoid accessing remote repositories
too often, thus saving a low of network bandwidth and time.
+
+<h2><a name="cache">Cache types</a></h2>
+Ivy cache is composed of two different parts:
+<ul>
+<li>the repository cache</li>
+The repository cache is where Ivy stores data downloaded from module
repositories, along with some meta information concerning these artifacts, like
their original location.
+This part of the cache can be shared if you use a well suited
[[configuration/lock-strategies lock strategy]].
+<li>the resolution cache</li>
+This part of the cache is used to store resolution data, which is used by Ivy
to reuse the results of a resolve process.
+This part of the cache is overwritten each time a new resolve is performed,
and should never be used by multiple processes at the same time.
+</ul>
+
+While there is always only one resolution cache, you can
[[configuration/caches define multiple repository caches]], each
[[configuration/resolvers resolver]] being able to use a separate cache.
+
+<h2><a name="change">Change management</a></h2>
+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>
+<h3>Changes 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.
Modified: ant/ivy/core/trunk/doc/configuration.html
URL:
http://svn.apache.org/viewvc/ant/ivy/core/trunk/doc/configuration.html?rev=608880&r1=608879&r2=608880&view=diff
==============================================================================
--- ant/ivy/core/trunk/doc/configuration.html (original)
+++ ant/ivy/core/trunk/doc/configuration.html Fri Jan 4 07:10:36 2008
@@ -33,8 +33,7 @@
<code type="xml">
<ivysettings>
<properties file="${ivy.settings.dir}/ivysettings-file.properties" />
- <settings defaultResolver="ibiblio" checkUpToDate="false" />
- <cacheDefaults defaultBasedir="${cache.dir}" />
+ <settings defaultCache="${cache.dir}" defaultResolver="ibiblio"
checkUpToDate="false" />
<resolvers>
<ibiblio name="ibiblio" />
<filesystem name="internal">
@@ -70,11 +69,12 @@
<a href="configuration/property.html">property</a>
<a href="configuration/properties.html">properties</a>
<a href="configuration/conf.html">settings</a>
- <a href="configuration/cacheDefaults.html">cacheDefaults</a>
<a href="configuration/include.html">include</a>
<a href="configuration/classpath.html">classpath</a>
<a href="configuration/typedef.html">typedef</a>
<a href="configuration/lock-strategies.html">lock-strategies</a>
+ <a href="configuration/caches.html">caches</a>
+ <a href="configuration/caches/cache.html">cache</a>
<a href="configuration/latest-strategies.html">latest-strategies</a>
<a href="configuration/version-matchers.html">version-matchers</a>
<a href="configuration/triggers.html">triggers</a>
@@ -117,8 +117,6 @@
<td>0..n</td></tr>
<tr><td><a href="configuration/conf.html">settings</a></td><td>configures
ivy with some defaults</td>
<td>0..1</td></tr>
- <tr><td><a
href="configuration/cacheDefaults.html">cacheDefaults</a></td><td>set up
default values for cache(s)</td>
- <td>0..1</td></tr>
<tr><td><a href="configuration/include.html">include</a></td><td>includes
another settings file</td>
<td>0..n</td></tr>
<tr><td><a href="configuration/classpath.html">classpath</a></td><td>add a
location in the classpath used to load plugins</td>
@@ -127,6 +125,8 @@
<td>0..n</td></tr>
<tr><td><a
href="configuration/lock-strategies.html">lock-strategies</a></td><td>defines
lock strategies</td>
<td>0..1</td></tr>
+ <tr><td><a href="configuration/caches.html">caches</a></td><td>defines
repository cache managers</td>
+ <td>0..1</td></tr>
<tr><td><a
href="configuration/latest-strategies.html">latest-strategies</a></td><td>defines
latest strategies</td>
<td>0..1</td></tr>
<tr><td><a href="configuration/parsers.html">parsers</a></td><td>defines
module descriptor parsers</td>
@@ -150,9 +150,7 @@
<tr><td><a href="configuration/statuses.html">statuses</a></td><td>defines
the list of available statuses</td>
<td>0..1</td></tr>
</tbody>
-</table>
-
- </textarea>
+</table></textarea>
<script type="text/javascript">xooki.postProcess();</script>
</body>
</html>
Added: ant/ivy/core/trunk/doc/configuration/caches.html
URL:
http://svn.apache.org/viewvc/ant/ivy/core/trunk/doc/configuration/caches.html?rev=608880&view=auto
==============================================================================
--- ant/ivy/core/trunk/doc/configuration/caches.html (added)
+++ ant/ivy/core/trunk/doc/configuration/caches.html Fri Jan 4 07:10:36 2008
@@ -0,0 +1,79 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd";>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+-->
+<html>
+<head>
+ <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
+ <script type="text/javascript">var xookiConfig = {level: 1};</script>
+ <script type="text/javascript" src="../xooki/xooki.js"></script>
+</head>
+<body>
+ <textarea id="xooki-source">
+<b>Tag:</b> caches
+
+Defines the list of available repository cache instances. <span
class="since">since 2.0</span>.
+
+By default, Ivy defines one repository cache instance, called 'default-cache',
and using the defaults cache settings defined using attributes on this tag.
This default instance is defined as long as you don't define your own default
cache using the 'default' attribute, and have at least one dependency resolver
which doesn't specify which cache instance to use.
+
+Since repository cache implementation are pluggable, you can either define new
cache instances based on the default implementation provided in Ivy using the
cache child element, or use custom cache implementations using child elements
as you have defined using [[configuration/typedef]].
+
+<em>ivyPattern</em> and <em>artifactPattern</em> are used to configure the
default way Ivy stores ivy files and artifacts in repository cache(s). Usually
you do not have to change this, unless you want to use the cache directly from
another tool, which is not recommended. These patterns are relative to the
repository cache base directory.
+
+<h1>Attributes</h1>
+<table class="ivy-attributes">
+<thead>
+ <tr><th class="ivy-att">Attribute</th><th
class="ivy-att-desc">Description</th><th class="ivy-att-req">Required</th></tr>
+</thead>
+<tbody>
+ <tr><td>default</td><td>the name of the default cache to use on all
resolvers not defining the cache instance to use</td>
+ <td>No, defaults to a default cache manager instance named
'default-cache'</td></tr>
+ <tr><td>basedir</td><td>the path of the default directory to use to put
repository cache data. <strong>This should not point to a directory used as a
repository!</strong></td>
+ <td>No, defaults to defaultCache defined in
[[configuration/conf]]</td></tr>
+ <tr><td>ivyPattern</td><td>default pattern used to indicate where ivy
files should be put in the repository cache(s)</td>
+ <td>No, defaults to
[organisation]/[module]/ivy-[revision].xml</td></tr>
+ <tr><td>artifactPattern</td><td>default pattern used to indicate where
artifact files should be put in repository cache(s)</td>
+ <td>No, defaults to
[organisation]/[module]/[type]s/[artifact]-[revision].[ext]</td></tr>
+ <tr><td>lockStragegy</td><td>the name of the default
[[configuration/lock-strategies lock strategy]] to use when accessing
repository cache(s)</td>
+ <td>No, defaults to <em>no-lock</em></td></tr>
+</tbody>
+</table>
+<h1>Child elements</h1>
+<table class="ivy-children">
+<thead>
+ <tr><th class="ivy-chld">Element</th><th
class="ivy-chld-desc">Description</th><th
class="ivy-chld-card">Cardinality</th></tr>
+</thead>
+<tbody>
+ <tr><td><a href="caches/cache.html">cache</a></td><td>defines a new
repository cache instance, based on the default repository cache
implementation</td>
+ <td>0..n</td></tr>
+ <tr><td><em>any cache</em></td><td>defines a new repository cache
instance</td>
+ <td>0..n</td></tr>
+</tbody>
+</table>
+<h1>Examples</h1>
+<code type="xml">
+<caches>
+ <cache name="mycache" basedir="path/to/my/cache/1" />
+ <cache name="mycache2" basedir="path/to/my/cache/2" />
+</caches>
+</code>
+Define 2 cache instances, named mycache and mycache2, using two different
directories as base directory, and using the default patterns and lock
strategies. The default cache instance will still be defined as long as at
least one dependency resolver does not declare which cache manager to use.
+<hr/></textarea>
+<script type="text/javascript">xooki.postProcess();</script>
+</body>
+</html>
Propchange: ant/ivy/core/trunk/doc/configuration/caches.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: ant/ivy/core/trunk/doc/configuration/caches/cache.html
URL:
http://svn.apache.org/viewvc/ant/ivy/core/trunk/doc/configuration/caches/cache.html?rev=608880&view=auto
==============================================================================
--- ant/ivy/core/trunk/doc/configuration/caches/cache.html (added)
+++ ant/ivy/core/trunk/doc/configuration/caches/cache.html Fri Jan 4 07:10:36
2008
@@ -0,0 +1,56 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd";>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+-->
+<html>
+<head>
+ <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
+ <script type="text/javascript">var xookiConfig = {level: 2};</script>
+ <script type="text/javascript" src="../../xooki/xooki.js"></script>
+</head>
+<body>
+ <textarea id="xooki-source">
+<b>Tag:</b> cache
+
+Defines a repository cache instance based on the default repository cache
implementation.
+
+The default repository cache implementation caches files on the local
filesystem in subdirectories of a configured base directory.
+
+<h1>Attributes</h1>
+<table class="ivy-attributes">
+<thead>
+ <tr><th class="ivy-att">Attribute</th><th
class="ivy-att-desc">Description</th><th class="ivy-att-req">Required</th></tr>
+</thead>
+<tbody>
+ <tr><td>name</td><td>name of the cache instance</td>
+ <td>Yes</td></tr>
+ <tr><td>basedir</td><td>the path of the base directory to use to put
repository cache data. <strong>This should not point to a directory used as a
repository!</strong></td>
+ <td>No, defaults to basedir defined in
[[configuration/caches]]</td></tr>
+ <tr><td>ivyPattern</td><td>the pattern to use to store cached ivy
files</td>
+ <td>No, defaults to default cache ivy pattern as configured in
[[configuration/caches]]</td></tr>
+ <tr><td>artifactPattern</td><td>the pattern to use to store cached
artifacts</td>
+ <td>No, defaults to default cache artifact pattern as configured in
[[configuration/caches]]</td></tr>
+ <tr><td>lockStrategy</td><td>the name of the
[[configuration/lock-strategies lock strategy]] to use for this cache</td>
+ <td>No, defaults to default lock strategy as configured in
[[configuration/caches]]</td></tr>
+</tbody>
+</table>
+
+</textarea>
+<script type="text/javascript">xooki.postProcess();</script>
+</body>
+</html>
Propchange: ant/ivy/core/trunk/doc/configuration/caches/cache.html
------------------------------------------------------------------------------
svn:eol-style = native
Modified: ant/ivy/core/trunk/doc/configuration/conf.html
URL:
http://svn.apache.org/viewvc/ant/ivy/core/trunk/doc/configuration/conf.html?rev=608880&r1=608879&r2=608880&view=diff
==============================================================================
--- ant/ivy/core/trunk/doc/configuration/conf.html (original)
+++ ant/ivy/core/trunk/doc/configuration/conf.html Fri Jan 4 07:10:36 2008
@@ -29,10 +29,8 @@
Configures some important ivy info: default cache, default resolver, ...
-Default cache is used whenever a cache is not provided. It usually points to a
directory in your filesystem. <strong>This should not point to a directory used
as a repository!</strong>
-<span class="since">Since 2.0</span> Once the settings are loaded, the value
of the defaultCache (either configured or the default value) is stored in an
Ivy variable: ivy.cache.dir.
-<span class="since">Since 2.0</span> A new [[configuration/cache]] tag is
provided where you can fully configure the cache. As of 2.0 beta 1, we
recommend using the cache tag even though configuring using the attributes
available on this tag is still possible.
-
+Default cache is the default directory used for both the resolution and
repository cache(s). It usually points to a directory in your filesystem. If
you want to isolate resolution cache from repository cache, we recommend
setting both the resolutionCacheDir attribute on this tag and the basedir
attribute on [[configuration/caches]] instead of using defaultCache.
+See [[concept cache concept]] for details on Ivy cache concept.
Default resolver is used whenever nothing else is configured in the modules
section of the configuration file. It should give the name of a dependency
resolver defined in the resolvers section of the configuration file.
@@ -52,8 +50,10 @@
<tr><th class="ivy-att">Attribute</th><th
class="ivy-att-desc">Description</th><th class="ivy-att-req">Required</th></tr>
</thead>
<tbody>
- <tr><td>defaultCache</td><td>a path to a directory to use as default
cache. <i>We recommend using the basedir on the [[configuration/cache]] tag
instead</i></td>
+ <tr><td>defaultCache</td><td>a path to a directory to use as default
basedir for both resolution and repository cache(s)</td>
<td>No, defaults to .ivy2/cache in user home</td></tr>
+ <tr><td>resolutionCacheDir</td><td>the path of the directory to use to put
all resolution cache data <span class="since">since 2.0</span></td>
+ <td>No, defaults to defaultCache</td></tr>
<tr><td>defaultResolver</td><td>the name of the default resolver to
use</td>
<td>No, but all modules should be configured in the modules section if
not provided</td></tr>
<tr><td>defaultLatestStrategy</td><td>the name of the default latest
strategy to use</td>
@@ -76,8 +76,7 @@
<td>No, defaults to false</td></tr>
</tbody>
</table>
-
- </textarea>
+</textarea>
<script type="text/javascript">xooki.postProcess();</script>
</body>
</html>
Modified: ant/ivy/core/trunk/doc/toc.json
URL:
http://svn.apache.org/viewvc/ant/ivy/core/trunk/doc/toc.json?rev=608880&r1=608879&r2=608880&view=diff
==============================================================================
--- ant/ivy/core/trunk/doc/toc.json (original)
+++ ant/ivy/core/trunk/doc/toc.json Fri Jan 4 07:10:36 2008
@@ -165,13 +165,6 @@
]
},
{
- "id":"configuration/cacheDefaults",
- "title":"cacheDefaults",
- "children": [
-
- ]
- },
- {
"id":"configuration/include",
"title":"include",
"children": [
@@ -197,6 +190,19 @@
"title":"lock-strategies",
"children": [
+ ]
+ },
+ {
+ "id":"configuration/caches",
+ "title":"caches",
+ "children": [
+ {
+ "id":"configuration/caches/cache",
+ "title":"cache",
+ "children": [
+
+ ]
+ }
]
},
{
