asciidoc/use/settings.adoc

////
   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

     https://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.
////

[*__since 2.0__*]

The settings declaration is used to configure Ivy with a settings XML file. The difference with the link:../use/configure{outfilesuffix}[configure] task is that when using the settings declaration, the configuration of Ivy will be done when the settings are first needed (for instance, when you do a resolve), while the configure task will perform a configuration of Ivy instantly, which makes it easier to see the problem if something goes wrong.

See link:../settings{outfilesuffix}[Settings Files] for details about the settings file itself.

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.

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:
[source,properties]
----
my.variable=my.value
my.variable.myid=my.value
my.variable.yourid=your.value
----

== Attributes

[options="header",cols="15%,50%,35%"]
|=======
|Attribute|Description|Required
|id|The settings id usable in the `settingsRef` attributes of the Ivy task that needs a setting.|No, defaults to `ivy.instance`
|file|path to the settings file to use
.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 link:../tutorial/defaultconf{outfilesuffix}[default settings file]
|url|URL of the settings file to use
|host|HTTP authentication host
.4+.^|No, unless authentication is required
|realm|HTTP authentication realm
|username|HTTP authentication user name
|passwd|HTTP authentication password
|=======

== HTTP Authentication

__Note__: HTTP authentication can be used only if link:https://hc.apache.org/httpcomponents-client-ga/index.html[HttpComponents HttpClient library] (minimum of 4.5.3 version) and its link:https://hc.apache.org/httpcomponents-client-4.5.x/dependency-management.html[dependencies] are in your classpath.

If any of the URLs you use in Ivy (especially in dependency resolvers) needs 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.

== Multiple classloader

A special attention should be applied when you have a multi-project build with `subant` call, using Ivy task loaded by a `typedef`.  Indeed in this situation, it is possible to pass settings reference to a subbuild.  When you do that, you should take care 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 `loader` 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).

== Examples

=== Simplest settings

[source,xml]
----
<ivy:settings/>
----

Use either `${ivy.settings.file}` if it exists, or the link:../samples/ivysettings-default.xml[default settings file]

This simplest setting is implicit.

=== Configure with a file

[source,xml]
----
<ivy:settings file="mysettings.xml"/>
----

=== Configure with an URL

[source,xml]
----
<ivy:settings url="http://mysite.com/mysettings.xml"/>
----

=== Configure multiple realms which require authentication

[source,xml]
----
<ivy: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:settings>
----

=== Configure 2 different settings

You can use multiple Ivy settings during a build. Then every Ivy task should specify the settings it uses using the `settingsRef` attribute.

[source,xml]
----
 <ivy:settings id="ivy.normal.settings" file="normal_settings.xml"/>
 <ivy:settings id="ivy.release.settings" file="release_settings.xml"/>

 <ivy:resolve settingsRef="ivy.normal.settings"/>
 <ivy:resolve settingsRef="ivy.release.settings"/>
----