<span class="since">(since 2.0)</span> The settings declaration is used to configure ivy with an xml settings file. See [[configuration Settings Files]] for details about the settings file itself.<br/><br/> Multiple settings can be defined in a build script. Every task can reference its own settings. All Ivy variables set during the settings are available in the Ant project as long as they were not set in Ant before (Ant properties are immutable). Moreover, the variables are exposed under two names: the variable name, and the variable name suffixed by dot + the settings id (if any). For instance, if you load a settings with the id 'myid', and define a variable my.variable=my.value in the Ivy settings, both my.variable and my.variable.myid will now be available as properties in Ant and equal to 'my.value'. If you later load another settings with the id 'yourid', and in this settings assign the variable 'my.variable' the value 'your.value', in the Ant project you will have: <code> my.variable=my.value my.variable.myid=my.value my.variable.yourid=your.value </code> <h2>Attributes</h2> <table class="ant"> <thead> <tr><th class="ant-att">Attribute</th><th class="ant-desc">Description</th><th class="ant-req">Required</th></tr> </thead> <tbody> <tr><td>id</td><td>The settings id useable in the refId attributes of the ivy task that needs a setting. Note that the ivy tasks will search by default for the settings with the id "ivy.instance".</td><td>Yes</td></tr> <tr><td>file</td><td>path to the settings file to use</td> <td rowspan="2">No. If a file is provided, url is ignored. If none are provided, then it attempts to find a file at ${ivy.settings.file}, and if this file does not exist, it uses a <a href="../tutorial/defaultconf.html">default settings file</a></td></tr> <tr><td>url</td><td>url of the settings file to use</td></tr> <tr><td>host</td><td>http authentication host</td><td rowspan="4">No, unless authentication is required</td></tr> <tr><td>realm</td><td>http authentication realm</td></tr> <tr><td>username</td><td>http authentication user name</td></tr> <tr><td>passwd</td><td>http authentication password</td></tr> </tbody> </table> <h2>HTTP Authentication</h2> <i>Note: HTTP Authentication can be used only if <a href="http://jakarta.apache.org/commons/httpclient/">commons-httpclient.jar</a> is in your classpath</i> If any of the url you use in ivy (especially in dependency resolvers) need http authentication, then you have to provide the host, realm, username and passwd attributes of the configure task. These settings will then be used in any further call to ivy tasks.<br/><br/> <h2>Multiple classloader</h2> A special attention should be applied when you have a multi-project build with <i>subant</i> call, using ivy task loaded by a <i>typedef</i>. Indeed in this situation, it is possible to pass settings reference to a subbuild. When you do that, you should take of the classloader. The ivy task of your subant should not be defined in a different classloader than the parent one. This can be achieved by using the <i>loader</i> parameter of the antlib declaration, or avoid to reload the ivy antlib in the subbuild (place the taskdef in a target only executed when the antlib is not yet loaded).<br/><br/> <h2>Examples</h2> <h3>Simplest settings</h3> <code><ivy:settings id="ivy.instance"/></code> Use either ${ivy.settings.file} if it exists, or the <a href="../samples/ivysettings-default.xml">default settings file</a><br> This simplest setting is implicit. <h3>Configure with a file</h3> <code><ivy:settings id="ivy.instance" file="mysettings.xml" /></code> <h3>Configure with an url</h3> <code><ivy:settings id="ivy.instance" url="http://mysite.com/mysettings.xml" /></code> <h3>Configure multiple URLs which require autentication</h3> <code> <ivy:settings id="authenticated.settings" file="path/to/my/ivysettings.xml"> <credentials host="myhost.com" realm="My Realm" username="myuser" passwd="mypasswd" /> <credentials host="yourhost.com" realm="Your Realm" username="myuser" passwd="myotherpasswd" /> </ivy:configure> </code> <h3>Configure 2 different settings</h3> You can use multiple ivy settings during a build. In that case, every ivy task has specify the settings that it mmust use. <code> <ivy:settings id="ivy.normal.settings" file="normal_settings.xml" /> <ivy:settings id="ivy.release.settings" file="release_settings.xml" /> </code>