ant-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From xav...@apache.org
Subject svn commit: r608880 - in /ant/ivy/core/trunk/doc: concept.html configuration.html configuration/cacheDefaults.html configuration/caches.html configuration/caches/ configuration/caches/cache.html configuration/conf.html toc.json
Date Fri, 04 Jan 2008 15:10:38 GMT
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": [
+
+                                  ]
+                              }
                             ]
                         },
                         {



Mime
View raw message