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": [ + + ] + } ] }, {