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

= Ivy Settings

In order to work as you want, Ivy sometimes needs some settings. Actually, Ivy can work with no specific settings at all, see the link:tutorial/defaultconf{outfilesuffix}[default settings documentation] for details about that. But Ivy is able to work in very different contexts. You just have to configure it properly.

Settings are specified through an XML file, usually called `ivysettings.xml`. To configure Ivy from Ant, you just have to use the link:use/settings{outfilesuffix}[settings] datatype with the path of your settings file.

In addition certain link:systemproperties{outfilesuffix}[Java system properties] affect the XML parsing behavior of Ivy.

Here is an example of the settings file:

[source, xml]
----

<ivysettings>
        <properties file="${ivy.settings.dir}/ivysettings-file.properties"/>
        <settings defaultResolver="ibiblio"/>
        <caches  defaultCacheDir="${cache.dir}" checkUpToDate="false"/>
        <resolvers>
                <ibiblio name="ibiblio"/>
                <filesystem name="internal">
                        <ivy pattern="${repository.dir}/[module]/ivy-[revision].xml"/>
                        <artifact pattern="${repository.dir}/[module]/[artifact]-[revision].[ext]"/>
                </filesystem>
        </resolvers>
        <modules>
                <module organisation="jayasoft" name=".*" resolver="internal"/>
        </modules>
</ivysettings>

----
__Note: To work, this settings file needs a property file named ivysettings-file.properties in the same directory as the settings file, with Ivy variables you want in it.__


Mainly, the settings enable you to configure the default cache directory used by Ivy and the dependency resolvers that it will use to resolve dependencies.

Some useful variables are available for use in settings files:


* ivy.settings.dir +
 this variable references the directory in which the settings file itself is. This is available if the settings has been loaded as a file. In case of a URL, it takes the part before the last slash of the URL, if any. If the URL has no slash, then this variable is not set.

* ivy.settings.file +
 the path of the settings file itself if it has been loaded as a file only. If it has been loaded as a URL, this variable is not set.

* ivy.settings.url +
 the URL pointing to the settings file. This is set both when it has been loaded as a file or a URL.


(*__since 1.4__*) Note that all link:https://docs.oracle.com/javase/7/docs/api/java/lang/System.html#getProperties()[Java system properties] are available as Ivy variables in your settings file.


== Settings file structure


The settings file is structured in some parts and left open in others. In fact, each resolver has its own structure, thus it's not the settings file itself which defines the structure for the resolvers.

**ivysettings**

    * link:settings/property{outfilesuffix}[property]
    * link:settings/properties{outfilesuffix}[properties]
    * link:settings/settings{outfilesuffix}[settings]
    * link:settings/include{outfilesuffix}[include]
    * link:settings/classpath{outfilesuffix}[classpath]
    * link:settings/typedef{outfilesuffix}[typedef]
    * link:settings/credentials{outfilesuffix}[credentials]
    * link:settings/signers{outfilesuffix}[signers]
    * link:settings/lock-strategies{outfilesuffix}[lock-strategies]
    * link:settings/caches{outfilesuffix}[caches]
        ** link:settings/caches/cache{outfilesuffix}[cache]
    * link:settings/latest-strategies{outfilesuffix}[latest-strategies]
    * link:settings/parsers{outfilesuffix}[parsers]
    * link:settings/namespaces{outfilesuffix}[namespaces]
        ** link:settings/namespace{outfilesuffix}[namespace]
            *** link:settings/namespace/rule{outfilesuffix}[rule]
                **** link:settings/namespace/fromtosystem{outfilesuffix}[fromsystem]
                    ***** link:settings/namespace/src{outfilesuffix}[src]
                    ***** link:settings/namespace/dest{outfilesuffix}[dest]
                **** link:settings/namespace/fromtosystem{outfilesuffix}[tosystem]
                    ***** link:settings/namespace/src{outfilesuffix}[src]
                    ***** link:settings/namespace/dest{outfilesuffix}[dest]
    * link:settings/macrodef{outfilesuffix}[macrodef]
        ** link:settings/macrodef/attribute{outfilesuffix}[attribute]
        ** any resolver
    * link:settings/resolvers{outfilesuffix}[resolvers]
        ** any resolver
    * link:settings/conflict-managers{outfilesuffix}[conflict-managers]
    * link:settings/modules{outfilesuffix}[modules]
        ** link:settings/module{outfilesuffix}[module]
    * link:settings/outputters{outfilesuffix}[outputters]
    * link:settings/statuses{outfilesuffix}[statuses]
        ** link:settings/status{outfilesuffix}[status]
    * link:settings/triggers{outfilesuffix}[triggers]
    * link:settings/version-matchers{outfilesuffix}[version-matchers]
    * link:settings/timeout-constraints{outfilesuffix}[timeout-constraints]
        ** link:settings/timeout-constraint{outfilesuffix}[timeout-constraint]


== ivysettings

*Tag:* ivysettings

Root tag of any Ivy settings file.

=== Child elements


[options="header"]
|=======
|Element|Description|Cardinality
|link:settings/property{outfilesuffix}[property]|set an Ivy variable|0..n
|link:settings/properties{outfilesuffix}[properties]|loads a properties file as Ivy variables|0..n
|link:settings/settings{outfilesuffix}[settings]|configures Ivy with some defaults|0..1
|link:settings/include{outfilesuffix}[include]|includes another settings file|0..n
|link:settings/classpath{outfilesuffix}[classpath]|add a location in the classpath used to load plugins|0..n
|link:settings/typedef{outfilesuffix}[typedef]|defines new types in Ivy|0..n
|link:settings/lock-strategies{outfilesuffix}[lock-strategies]|defines lock strategies|0..1
|link:settings/caches{outfilesuffix}[caches]|defines repository cache managers|0..1
|link:settings/latest-strategies{outfilesuffix}[latest-strategies]|defines latest strategies|0..1
|link:settings/parsers{outfilesuffix}[parsers]|defines module descriptor parsers|0..1
|link:settings/namespaces{outfilesuffix}[namespaces]|defines new namespaces|0..1
|link:settings/macrodef{outfilesuffix}[macrodef]|defines a new macro resolver|0..n
|link:settings/resolvers{outfilesuffix}[resolvers]|defines dependency resolvers|0..1
|link:settings/conflict-managers{outfilesuffix}[conflict-managers]|defines conflict managers|0..1
|link:settings/modules{outfilesuffix}[modules]|defines rules between modules and dependency resolvers|0..1
|link:settings/outputters{outfilesuffix}[outputters]|defines the list of available report outputters|0..1
|link:settings/statuses{outfilesuffix}[statuses]|defines the list of available statuses|0..1
|link:settings/triggers{outfilesuffix}[triggers]|register triggers on Ivy events|0..1
|link:settings/version-matchers{outfilesuffix}[version-matchers]|defines new version matchers|0..1
|link:settings/timeout-constraints{outfilesuffix}[timeout-constraints]|defines the list of available timeout-constraints|0..n
|=======