asciidoc/ivyfile.adoc - ant-ivy - Git at Google

 ////
    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 use is entirely based on _module descriptors_ known as "Ivy files". Ivy files are XML files, usually called ivy.xml, containing the description of the dependencies of a module, its published artifacts and its configurations.

 Here is the simplest Ivy file you can write:

 [source,xml]
 ----
 <ivy-module version="2.0">
   <info organisation="myorg"
         module="mymodule"/>
 </ivy-module>
 ----

 If you want to see a sample module descriptor using almost all possibilities of Ivy files, check this one, link:samples/ivy-sample-xslt.xml[with] or link:samples/ivy-sample.xml[without] XSLT.

 Before beginning the reference itself, it is required to have in mind the terminology defined in the link:reference{outfilesuffix}[main page] of this reference documentation.

 For those familiar with XML schema, the schema used to validate Ivy files can be found link:http://ant.apache.org/ivy/schemas/ivy.xsd[here]. For those using XSD aware IDE, you can declare the XSD in your Ivy files to benefit from code completion / validation:

 [source,xml]
 ----
 <?xml version="1.0" encoding="UTF-8"?>
 <ivy-module version="2.0"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:noNamespaceSchemaLocation=
                    "http://ant.apache.org/ivy/schemas/ivy.xsd">
   <info organisation="myorg"
         module="mymodule"/>
 </ivy-module>
 ----

 == Dynamic and [[resolved]]resolved Ivy files

 A module descriptor (Ivy file) is needed both before and after the publication of each revision of the module. Depending on the case, a module descriptor can be either _dynamic_ or _resolved_.

 === Dynamic descriptor for module development

 During the module development time, between publications, the descriptor helps in managing all the possibly changing dependencies of the module. For that purpose, development time Ivy files can declare dynamic dependencies to allow for a greater flexibility of use. link:ivyfile/dependency{outfilesuffix}#revision[Dynamic revision] references like `latest.integration` or `1.0.+` are possible and may resolve to different artifacts at different times. Variables can be used for even more flexibility. Development time Ivy files are hence called _dynamic_, because they can produce different results over time. The dynamic Ivy files are normally considered source files and kept with them (under SCM control).

 === Resolved descriptors for publishing

 At each publication, another kind of a module descriptor is needed to document the dependencies of the particular published revision of the module. For that purpose, the descriptor usually needs to be fixed as its dependencies should no longer change. In doing so, the published module revision gets fixed, explicitly resolved dependencies. No variables are allowed either. Such publication-friendly, static Ivy files are called _resolved_, because they should always produce the same results. The resolved Ivy files are comparable to published artifacts and are kept with them in a repository.

 Resolved Ivy files are generated from their original dynamic Ivy files via the link:use/deliver{outfilesuffix}[deliver] task.

 Note that although it is technically possible to publish module revisions with dynamic Ivy files, it is not a generally recommended practice.

 == Hierarchical Index

 * *ivy-module*
     ** link:ivyfile/info{outfilesuffix}[info]
         *** link:ivyfile/license{outfilesuffix}[license]
         *** link:ivyfile/ivyauthor{outfilesuffix}[ivyauthor]
         *** link:ivyfile/repository{outfilesuffix}[repository]
         *** link:ivyfile/description{outfilesuffix}[description]
     ** link:ivyfile/configurations{outfilesuffix}[configurations]
         *** link:ivyfile/conf{outfilesuffix}[conf]
     ** link:ivyfile/publications{outfilesuffix}[publications]
         *** link:ivyfile/artifact{outfilesuffix}[artifact]
             **** link:ivyfile/artifact-conf{outfilesuffix}[conf]
     ** link:ivyfile/dependencies{outfilesuffix}[dependencies]
         *** link:ivyfile/dependency{outfilesuffix}[dependency]
             **** link:ivyfile/dependency-conf{outfilesuffix}[conf]
                 ***** link:ivyfile/mapped{outfilesuffix}[mapped]
             **** link:ivyfile/dependency-artifact{outfilesuffix}[artifact]
                 ***** link:ivyfile/dependency-artifact-conf{outfilesuffix}[conf]
             **** link:ivyfile/dependency-artifact{outfilesuffix}[include]
                 ***** link:ivyfile/dependency-artifact-conf{outfilesuffix}[conf]
             **** link:ivyfile/artifact-exclude{outfilesuffix}[exclude]
                 ***** link:ivyfile/artifact-exclude-conf{outfilesuffix}[conf]
         *** link:ivyfile/exclude{outfilesuffix}[exclude]
         *** link:ivyfile/override{outfilesuffix}[override]
         *** link:ivyfile/conflict{outfilesuffix}[conflict]
     ** link:ivyfile/conflicts{outfilesuffix}[conflicts]
         *** link:ivyfile/manager{outfilesuffix}[manager]

 == ivy-module

 *Tag:* ivy-module

 The root tag of any Ivy file (module descriptor).

 === Attributes

 [options="header",cols="15%,50%,35%"]
 |=======
 |Attribute|Description|Required
 |version|the version of the Ivy file specification - should be '2.0' with current version of Ivy|Yes
 |=======

 === Child elements

 [options="header"]
 |=======
 |Element|Description|Cardinality
 |link:ivyfile/info{outfilesuffix}[info]|contains information about the described module|1
 |link:ivyfile/configurations{outfilesuffix}[configurations]|container for configuration elements|0..1
 |link:ivyfile/publications{outfilesuffix}[publications]|container for published artifact elements|0..1
 |link:ivyfile/dependencies{outfilesuffix}[dependencies]|container for dependency elements|0..1
 |link:ivyfile/conflicts{outfilesuffix}[conflicts]|section to configure the conflict managers to use|0..1
 |=======
	////
	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 use is entirely based on _module descriptors_ known as "Ivy files". Ivy files are XML files, usually called ivy.xml, containing the description of the dependencies of a module, its published artifacts and its configurations.

	Here is the simplest Ivy file you can write:

	[source,xml]
	----
	<ivy-module version="2.0">
	<info organisation="myorg"
	module="mymodule"/>
	</ivy-module>
	----

	If you want to see a sample module descriptor using almost all possibilities of Ivy files, check this one, link:samples/ivy-sample-xslt.xml[with] or link:samples/ivy-sample.xml[without] XSLT.

	Before beginning the reference itself, it is required to have in mind the terminology defined in the link:reference{outfilesuffix}[main page] of this reference documentation.

	For those familiar with XML schema, the schema used to validate Ivy files can be found link:http://ant.apache.org/ivy/schemas/ivy.xsd[here]. For those using XSD aware IDE, you can declare the XSD in your Ivy files to benefit from code completion / validation:

	[source,xml]
	----
	<?xml version="1.0" encoding="UTF-8"?>
	<ivy-module version="2.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:noNamespaceSchemaLocation=
	"http://ant.apache.org/ivy/schemas/ivy.xsd">
	<info organisation="myorg"
	module="mymodule"/>
	</ivy-module>
	----

	== Dynamic and [[resolved]]resolved Ivy files

	A module descriptor (Ivy file) is needed both before and after the publication of each revision of the module. Depending on the case, a module descriptor can be either _dynamic_ or _resolved_.

	=== Dynamic descriptor for module development

	During the module development time, between publications, the descriptor helps in managing all the possibly changing dependencies of the module. For that purpose, development time Ivy files can declare dynamic dependencies to allow for a greater flexibility of use. link:ivyfile/dependency{outfilesuffix}#revision[Dynamic revision] references like `latest.integration` or `1.0.+` are possible and may resolve to different artifacts at different times. Variables can be used for even more flexibility. Development time Ivy files are hence called _dynamic_, because they can produce different results over time. The dynamic Ivy files are normally considered source files and kept with them (under SCM control).

	=== Resolved descriptors for publishing

	At each publication, another kind of a module descriptor is needed to document the dependencies of the particular published revision of the module. For that purpose, the descriptor usually needs to be fixed as its dependencies should no longer change. In doing so, the published module revision gets fixed, explicitly resolved dependencies. No variables are allowed either. Such publication-friendly, static Ivy files are called _resolved_, because they should always produce the same results. The resolved Ivy files are comparable to published artifacts and are kept with them in a repository.

	Resolved Ivy files are generated from their original dynamic Ivy files via the link:use/deliver{outfilesuffix}[deliver] task.

	Note that although it is technically possible to publish module revisions with dynamic Ivy files, it is not a generally recommended practice.

	== Hierarchical Index

	* ivy-module
	** link:ivyfile/info{outfilesuffix}[info]
	*** link:ivyfile/license{outfilesuffix}[license]
	*** link:ivyfile/ivyauthor{outfilesuffix}[ivyauthor]
	*** link:ivyfile/repository{outfilesuffix}[repository]
	*** link:ivyfile/description{outfilesuffix}[description]
	** link:ivyfile/configurations{outfilesuffix}[configurations]
	*** link:ivyfile/conf{outfilesuffix}[conf]
	** link:ivyfile/publications{outfilesuffix}[publications]
	*** link:ivyfile/artifact{outfilesuffix}[artifact]
	**** link:ivyfile/artifact-conf{outfilesuffix}[conf]
	** link:ivyfile/dependencies{outfilesuffix}[dependencies]
	*** link:ivyfile/dependency{outfilesuffix}[dependency]
	**** link:ivyfile/dependency-conf{outfilesuffix}[conf]
	***** link:ivyfile/mapped{outfilesuffix}[mapped]
	**** link:ivyfile/dependency-artifact{outfilesuffix}[artifact]
	***** link:ivyfile/dependency-artifact-conf{outfilesuffix}[conf]
	**** link:ivyfile/dependency-artifact{outfilesuffix}[include]
	***** link:ivyfile/dependency-artifact-conf{outfilesuffix}[conf]
	**** link:ivyfile/artifact-exclude{outfilesuffix}[exclude]
	***** link:ivyfile/artifact-exclude-conf{outfilesuffix}[conf]
	*** link:ivyfile/exclude{outfilesuffix}[exclude]
	*** link:ivyfile/override{outfilesuffix}[override]
	*** link:ivyfile/conflict{outfilesuffix}[conflict]
	** link:ivyfile/conflicts{outfilesuffix}[conflicts]
	*** link:ivyfile/manager{outfilesuffix}[manager]

	== ivy-module

	Tag: ivy-module

	The root tag of any Ivy file (module descriptor).

	=== Attributes

	[options="header",cols="15%,50%,35%"]
	\|=======
	\|Attribute\|Description\|Required
	\|version\|the version of the Ivy file specification - should be '2.0' with current version of Ivy\|Yes
	\|=======

	=== Child elements

	[options="header"]
	\|=======
	\|Element\|Description\|Cardinality
	\|link:ivyfile/info{outfilesuffix}[info]\|contains information about the described module\|1
	\|link:ivyfile/configurations{outfilesuffix}[configurations]\|container for configuration elements\|0..1
	\|link:ivyfile/publications{outfilesuffix}[publications]\|container for published artifact elements\|0..1
	\|link:ivyfile/dependencies{outfilesuffix}[dependencies]\|container for dependency elements\|0..1
	\|link:ivyfile/conflicts{outfilesuffix}[conflicts]\|section to configure the conflict managers to use\|0..1
	\|=======