Settings Files


In order to work as you want, ivy sometimes needs some settings. Actually, ivy can work with no specific settings at all, see the 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 settings datatype with the path of your settings file.

Here is an example of the settings file: 
<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>

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

Some useful variables are available in settings files:
  • ivy.settings.dir
    • this variable references the directory in which the ivysettings 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 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. Indeed, each resolver has its own structure, thus it's not the settings file itself which defines the structure for the resolvers.
ivysettings
    property
    properties
    settings
    include
    classpath
    typedef
    credentials
    lock-strategies
    caches
        cache
    latest-strategies
    version-matchers
    triggers
    parsers
    conflict-managers
    outputters
    namespaces
        namespace
            rule
                fromsystem
                    src
                    dest
                tosystem
                    src
                    dest
    macrodef
        attribute
        any resolver
    resolvers
        any resolver
    modules
        module
    statuses
        status

ivysettings

Tag: ivysettings

Root tag of any ivysettings file.

Child elements

ElementDescriptionCardinality
propertyset an ivy variable 0..n
propertiesloads a properties file as ivy variables 0..n
settingsconfigures ivy with some defaults 0..1
includeincludes another settings file 0..n
classpathadd a location in the classpath used to load plugins 0..n
typedefdefines new types in ivy 0..n
lock-strategiesdefines lock strategies 0..1
cachesdefines repository cache managers 0..1
latest-strategiesdefines latest strategies 0..1
parsersdefines module descriptor parsers 0..1
version-matchersdefines new version matchers 0..1
triggersregister triggers on ivy events 0..1
namespacesdefines new namespaces 0..1
macrodefdefines a new macro resolver 0..n
resolversdefines dependency resolvers 0..1
conflict-managersdefines conflicts managers 0..1
modulesdefines rules between modules and dependency resolvers 0..1
outputtersdefines the list of available report outputters 0..1
statusesdefines the list of available statuses 0..1