asciidoc/use/info.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.
 ////

 [*__since 1.4__*]

 The `info` task eases the access to some essential data contained in an Ivy file without performing a dependency resolution.

 The information is retrieved by setting Ant properties:

 [options="header",cols="30%,50%"]
 |=======
 |Property|Description
 |ivy.organisation|The organisation of the module, as found in the link:../ivyfile/info{outfilesuffix}[info] tag of the Ivy file parsed.
 |ivy.module|The name of the module, as found in the link:../ivyfile/info{outfilesuffix}[info] tag of the Ivy file parsed.
 |ivy.branch|The branch of the module if any, as found in the link:../ivyfile/info{outfilesuffix}[info] tag of the Ivy file parsed.
 |ivy.revision|The revision of the module, as found in the link:../ivyfile/info{outfilesuffix}[info] tag of the Ivy file parsed.
 |ivy.status|The status of the module, as found in the link:../ivyfile/info{outfilesuffix}[info] tag of the Ivy file parsed.
 |ivy.publication|The publication time of the module, as found in the link:../ivyfile/info{outfilesuffix}[info] tag of the Ivy file parsed. (*__since 2.2__*)
 |ivy.extra.__[any extra attribute]__|Corresponding extra attribute value, as found in the link:../ivyfile/info{outfilesuffix}[info] tag of the Ivy file parsed
 |ivy.configurations|A comma separated list of configurations of the module, as declared in the link:../ivyfile/configurations{outfilesuffix}[configurations] section
 |ivy.public.configurations|A comma separated list of public configurations of the module, as declared in the link:../ivyfile/configurations{outfilesuffix}[configurations] section
 |ivy.configuration.__[config name]__.desc|For each configuration with a description, a property is created containing this description. (*__since 2.2__*)
 |ivy.artifact.__[index]__.name|For each published artifact, a property is created containing its name. (*__since 2.2__*)
 |ivy.artifact.__[index]__.type|For each published artifact, a property is created containing its type. (*__since 2.2__*)
 |ivy.artifact.__[index]__.ext|For each published artifact, a property is created containing its ext. (*__since 2.2__*)
 |ivy.artifact.__[index]__.conf|For each published artifact, a property is created containing its conf. (*__since 2.2__*)
 |ivy.artifact.__[index]__.extra.__[any extra attribute]__|For each extra attribute of the published artifact, a property is created containing its name. (*__since 2.2__*)
 |=======

 [*__since 2.0__*]

 This task has been enhanced to allow you to retrieve information about Ivy modules in a repository.  Instead of specifying a local Ivy file you may specify the organisation, module, revision pattern and (optionally) the branch of the Ivy module in the repository you wish to retrieve the information for.

 The revision pattern is what is used when declaring a link:../ivyfile/dependency{outfilesuffix}[dependency] on a module, identical to how the link:findrevision{outfilesuffix}[findrevision] task works.  In fact, this task can now be used in place of the findrevision task.

 If no matching module is found then no property values are set.

 You may now also set the property attribute to change the first part of the property names that are set by this task e.g. if you set the property attribute to `mymodule` this task will set the Ant properties `mymodule.organisation`, `mymodule.module`, `mymodule.revision` etc.

 (*__since 2.2__*) This task has been enhanced to also retrieve detailed information about the module's published artifacts, as well as the publication time.

 == Attributes

 [options="header",cols="15%,50%,35%"]
 |=======
 |Attribute|Description|Required
 |file|the Ivy file to parse|Yes, if you wish to parse an Ivy file.
 No, if you are retrieving information about a module from an Ivy repository.
 |organisation|the organisation of the module to find (*__since 2.0__*)|No, if you wish to parse an Ivy file.
 Yes, if you are retrieving information about a module from an Ivy repository.
 |module|the the name of the module to find (*__since 2.0__*)|No, if you wish to parse an Ivy file.
 Yes, if you are retrieving information about a module from an Ivy repository.
 |branch|the branch of the module to find (*__since 2.0__*)|No, defaults to the default branch for the given module if you are retrieving information about a module from an Ivy repository.
 |revision|the revision constraint to apply (*__since 2.0__*)|No, if you wish to parse an Ivy file.
 Yes, if you are retrieving information about a module from an Ivy repository.
 |property|the name to use as the base of the property names set by this task (*__since 2.0__*)|No, will default to `ivy` if not set.
 |settingsRef|A reference to Ivy settings that must be used by this task (*__since 2.0__*)|No, defaults to `ivy.instance`.
 |=======

 == Examples

 Given this `ivy.xml` file:

 [source,xml]
 ----
 <ivy-module version="1.0" xmlns:e="http://ant.apache.org/ivy/extra">
     <info organisation="apache"
           module="info-all"
           branch="trunk"
           revision="1.0"
           status="release"
           e:myextraatt="myvalue"/>
     <configurations>
         <conf name="default"/>
         <conf name="test"/>
         <conf name="private" visibility="private"/>
     </configurations>
     <publications>
         <artifact name="thing1" type="jar" ext="jar" conf="default" e:data="main"/>
         <artifact name="thing2" type="jar" ext="jar" conf="default" e:data="client"/>
     </publications>
     <dependencies>
         <dependency org="org1" name="mod1.2" rev="2.0"/>
     </dependencies>
 </ivy-module>
 ----

 [source,xml]
 ----
 <ivy:info file="${basedir}/path/to/ivy.xml"/>
 ----

 Parses `+++${basedir}/path/to/ivy.xml+++` and set properties as described above accordingly:

 [source,properties]
 ----
 ivy.organisation=apache
 ivy.module=info-all
 ivy.branch=trunk
 ivy.revision=1.0
 ivy.status=release
 ivy.extra.myextraatt=myvalue
 ivy.configurations=default, test, private
 ivy.public.configurations=default, test
 ivy.artifact.1.name=thing1
 ivy.artifact.1.type=jar
 ivy.artifact.1.ext=jar
 ivy.artifact.1.conf=default
 ivy.artifact.1.extra.data=main
 ivy.artifact.2.name=thing2
 ivy.artifact.2.type=jar
 ivy.artifact.2.ext=jar
 ivy.artifact.2.conf=default
 ivy.artifact.2.extra.data=client
 ----

 Given the same Ivy module in a repository:

 [source,xml]
 ----
 <ivy:info organisation="apache" module="info-all" revision="1.0"/>
 ----

 will set the exact same set of properties as above.  Using:

 [source,xml]
 ----
 <ivy:info organisation="apache" module="info-all" revision="1.0" property="infotest"/>
 ----

 will set:

 [source,properties]
 ----
 infotest.organisation=apache
 infotest.module=info-all
 infotest.branch=trunk
 infotest.revision=1.0
 infotest.status=release
 infotest.extra.myextraatt=myvalue
 infotest.configurations=default, test, private
 infotest.public.configurations=default, test
 infotest.artifact.1.name=thing1
 infotest.artifact.1.type=jar
 infotest.artifact.1.ext=jar
 infotest.artifact.1.conf=default
 infotest.artifact.1.extra.data=main
 infotest.artifact.2.name=thing2
 infotest.artifact.2.type=jar
 infotest.artifact.2.ext=jar
 infotest.artifact.2.conf=default
 infotest.artifact.2.extra.data=client
 ----
	////
	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 1.4__]

	The `info` task eases the access to some essential data contained in an Ivy file without performing a dependency resolution.

	The information is retrieved by setting Ant properties:

	[options="header",cols="30%,50%"]
	\|=======
	\|Property\|Description
	\|ivy.organisation\|The organisation of the module, as found in the link:../ivyfile/info{outfilesuffix}[info] tag of the Ivy file parsed.
	\|ivy.module\|The name of the module, as found in the link:../ivyfile/info{outfilesuffix}[info] tag of the Ivy file parsed.
	\|ivy.branch\|The branch of the module if any, as found in the link:../ivyfile/info{outfilesuffix}[info] tag of the Ivy file parsed.
	\|ivy.revision\|The revision of the module, as found in the link:../ivyfile/info{outfilesuffix}[info] tag of the Ivy file parsed.
	\|ivy.status\|The status of the module, as found in the link:../ivyfile/info{outfilesuffix}[info] tag of the Ivy file parsed.
	\|ivy.publication\|The publication time of the module, as found in the link:../ivyfile/info{outfilesuffix}[info] tag of the Ivy file parsed. (__since 2.2__)
	\|ivy.extra.__[any extra attribute]__\|Corresponding extra attribute value, as found in the link:../ivyfile/info{outfilesuffix}[info] tag of the Ivy file parsed
	\|ivy.configurations\|A comma separated list of configurations of the module, as declared in the link:../ivyfile/configurations{outfilesuffix}[configurations] section
	\|ivy.public.configurations\|A comma separated list of public configurations of the module, as declared in the link:../ivyfile/configurations{outfilesuffix}[configurations] section
	\|ivy.configuration.__[config name]__.desc\|For each configuration with a description, a property is created containing this description. (__since 2.2__)
	\|ivy.artifact.__[index]__.name\|For each published artifact, a property is created containing its name. (__since 2.2__)
	\|ivy.artifact.__[index]__.type\|For each published artifact, a property is created containing its type. (__since 2.2__)
	\|ivy.artifact.__[index]__.ext\|For each published artifact, a property is created containing its ext. (__since 2.2__)
	\|ivy.artifact.__[index]__.conf\|For each published artifact, a property is created containing its conf. (__since 2.2__)
	\|ivy.artifact.__[index]__.extra.__[any extra attribute]__\|For each extra attribute of the published artifact, a property is created containing its name. (__since 2.2__)
	\|=======

	[__since 2.0__]

	This task has been enhanced to allow you to retrieve information about Ivy modules in a repository. Instead of specifying a local Ivy file you may specify the organisation, module, revision pattern and (optionally) the branch of the Ivy module in the repository you wish to retrieve the information for.

	The revision pattern is what is used when declaring a link:../ivyfile/dependency{outfilesuffix}[dependency] on a module, identical to how the link:findrevision{outfilesuffix}[findrevision] task works. In fact, this task can now be used in place of the findrevision task.

	If no matching module is found then no property values are set.

	You may now also set the property attribute to change the first part of the property names that are set by this task e.g. if you set the property attribute to `mymodule` this task will set the Ant properties `mymodule.organisation`, `mymodule.module`, `mymodule.revision` etc.

	(__since 2.2__) This task has been enhanced to also retrieve detailed information about the module's published artifacts, as well as the publication time.

	== Attributes

	[options="header",cols="15%,50%,35%"]
	\|=======
	\|Attribute\|Description\|Required
	\|file\|the Ivy file to parse\|Yes, if you wish to parse an Ivy file.
	No, if you are retrieving information about a module from an Ivy repository.
	\|organisation\|the organisation of the module to find (__since 2.0__)\|No, if you wish to parse an Ivy file.
	Yes, if you are retrieving information about a module from an Ivy repository.
	\|module\|the the name of the module to find (__since 2.0__)\|No, if you wish to parse an Ivy file.
	Yes, if you are retrieving information about a module from an Ivy repository.
	\|branch\|the branch of the module to find (__since 2.0__)\|No, defaults to the default branch for the given module if you are retrieving information about a module from an Ivy repository.
	\|revision\|the revision constraint to apply (__since 2.0__)\|No, if you wish to parse an Ivy file.
	Yes, if you are retrieving information about a module from an Ivy repository.
	\|property\|the name to use as the base of the property names set by this task (__since 2.0__)\|No, will default to `ivy` if not set.
	\|settingsRef\|A reference to Ivy settings that must be used by this task (__since 2.0__)\|No, defaults to `ivy.instance`.
	\|=======

	== Examples

	Given this `ivy.xml` file:

	[source,xml]
	----
	<ivy-module version="1.0" xmlns:e="http://ant.apache.org/ivy/extra">
	<info organisation="apache"
	module="info-all"
	branch="trunk"
	revision="1.0"
	status="release"
	e:myextraatt="myvalue"/>
	<configurations>
	<conf name="default"/>
	<conf name="test"/>
	<conf name="private" visibility="private"/>
	</configurations>
	<publications>
	<artifact name="thing1" type="jar" ext="jar" conf="default" e:data="main"/>
	<artifact name="thing2" type="jar" ext="jar" conf="default" e:data="client"/>
	</publications>
	<dependencies>
	<dependency org="org1" name="mod1.2" rev="2.0"/>
	</dependencies>
	</ivy-module>
	----

	[source,xml]
	----
	<ivy:info file="${basedir}/path/to/ivy.xml"/>
	----

	Parses `+++${basedir}/path/to/ivy.xml+++` and set properties as described above accordingly:

	[source,properties]
	----
	ivy.organisation=apache
	ivy.module=info-all
	ivy.branch=trunk
	ivy.revision=1.0
	ivy.status=release
	ivy.extra.myextraatt=myvalue
	ivy.configurations=default, test, private
	ivy.public.configurations=default, test
	ivy.artifact.1.name=thing1
	ivy.artifact.1.type=jar
	ivy.artifact.1.ext=jar
	ivy.artifact.1.conf=default
	ivy.artifact.1.extra.data=main
	ivy.artifact.2.name=thing2
	ivy.artifact.2.type=jar
	ivy.artifact.2.ext=jar
	ivy.artifact.2.conf=default
	ivy.artifact.2.extra.data=client
	----

	Given the same Ivy module in a repository:

	[source,xml]
	----
	<ivy:info organisation="apache" module="info-all" revision="1.0"/>
	----

	will set the exact same set of properties as above. Using:

	[source,xml]
	----
	<ivy:info organisation="apache" module="info-all" revision="1.0" property="infotest"/>
	----

	will set:

	[source,properties]
	----
	infotest.organisation=apache
	infotest.module=info-all
	infotest.branch=trunk
	infotest.revision=1.0
	infotest.status=release
	infotest.extra.myextraatt=myvalue
	infotest.configurations=default, test, private
	infotest.public.configurations=default, test
	infotest.artifact.1.name=thing1
	infotest.artifact.1.type=jar
	infotest.artifact.1.ext=jar
	infotest.artifact.1.conf=default
	infotest.artifact.1.extra.data=main
	infotest.artifact.2.name=thing2
	infotest.artifact.2.type=jar
	infotest.artifact.2.ext=jar
	infotest.artifact.2.conf=default
	infotest.artifact.2.extra.data=client
	----