asciidoc/ivyfile/conf.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.
 ////

 *Tag:* conf *Parent:* link:../ivyfile/configurations{outfilesuffix}[configurations]

 Declares a configuration of this module. As described in the reference page, a configuration is a way to use or construct a module. Some modules may be used in different ways (think about hibernate which can be used inside or outside an application server), and this way may alter the artifacts you need (in the case of hibernate, jta.jar is needed only if it is used outside an application server). Moreover, a module may need some other modules and artifacts only at build time, and some others at runtime. All those different ways to use or build a module are called module configurations in Ivy.

 The `conf` element in the configurations section declares one configuration. This declaration gives the name of the configuration declared, its visibility and the other configurations of the module it extends.

 `visibility` is used to indicate whether or not a configuration can be used from other modules depending on this one. Thus a private configuration is only used for internal purpose (maybe at build time), and other modules cannot declare to depend on it.

 A configuration can also extend one or several other ones of the same module. When a configuration extends another one, then all artifacts required in the extended configuration will also be required in the configuration that extends the other one. For instance, if configuration B extends configuration A, and if artifacts art1 and art2 are required in configuration A, then they will be automatically required in configuration B. On the other hand, artifacts required in configuration B are not necessarily required in configuration A.

 This notion is very helpful to define configurations which are similar with some differences.

 [*__since 1.4__*]

 The extends attribute can use the following wildcards:

 [cols="15%,50%"]
 |=======
 |`*`|all other configurations
 |`*(public)`|all other public configurations
 |`*(private)`|all other private configurations
 |=======

 A whole configuration can be declared as non transitive, so that all dependencies resolved in this configuration will be resolved with transitivity disabled. Note that the transitivity is disabled for all the configuration dependencies (including those obtained because this conf extends other ones), and only for this configuration (which means that a conf extending this one with transitivity enabled will get transitive dependencies even for dependencies being part of the non transitive configuration).
 This is very useful to build a compile configuration, for instance, forcing the dependency declaration on each direct dependency, with no risk to forget some because of transitivity.

 This tag supports link:../concept{outfilesuffix}#extra[extra attributes].

 == Attributes

 [options="header",cols="15%,50%,35%"]
 |=======
 |Attribute|Description|Required
 |name|the name of the declared configuration|Yes
 |description|a description for the declared configuration|No
 |visibility|the visibility of the declared configuration.

 `public` means that this configuration can be used by other modules, while `private` means that this configuration is used only in the module itself, and is not exposed to other modules|No, defaults to `public`
 |extends|a comma separated list of configurations of this module that the current configuration extends|No, defaults to none
 |transitive|a boolean to indicate if this conf is transitive or not (*__since 1.4__*)|No, defaults to `true`
 |deprecated|indicates that this conf has been deprecated by giving the date of the deprecation.

 It should be given in this format: `yyyyMMddHHmmss`|No, by default the conf is not deprecated
 |=======

 == Examples

 [source,xml]
 ----
 <conf name="core" visibility="private"/>
 <conf name="compile" extends="core" transitive="false" visibility="private"/>
 <conf name="runtime" extends="compile" description="everything needed to run this module"/>
 ----

 Declares three configurations, `core`, `compile` and `runtime`, with only the `runtime` one accessible from other modules, and with the `compile` one being non transitive.

 Therefore the `core` configuration will only be composed of dependencies declared in the `core` configuration itself, the `compile` configuration will be composed of all dependencies required in either `core` or `compile` configuration, but without transitivity (neither for core nor compile dependencies), and `runtime` will be composed of all dependencies, all transitively, including the dependencies declared only in `compile`.
	////
	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.
	////

	Tag: conf Parent: link:../ivyfile/configurations{outfilesuffix}[configurations]

	Declares a configuration of this module. As described in the reference page, a configuration is a way to use or construct a module. Some modules may be used in different ways (think about hibernate which can be used inside or outside an application server), and this way may alter the artifacts you need (in the case of hibernate, jta.jar is needed only if it is used outside an application server). Moreover, a module may need some other modules and artifacts only at build time, and some others at runtime. All those different ways to use or build a module are called module configurations in Ivy.

	The `conf` element in the configurations section declares one configuration. This declaration gives the name of the configuration declared, its visibility and the other configurations of the module it extends.

	`visibility` is used to indicate whether or not a configuration can be used from other modules depending on this one. Thus a private configuration is only used for internal purpose (maybe at build time), and other modules cannot declare to depend on it.

	A configuration can also extend one or several other ones of the same module. When a configuration extends another one, then all artifacts required in the extended configuration will also be required in the configuration that extends the other one. For instance, if configuration B extends configuration A, and if artifacts art1 and art2 are required in configuration A, then they will be automatically required in configuration B. On the other hand, artifacts required in configuration B are not necessarily required in configuration A.

	This notion is very helpful to define configurations which are similar with some differences.

	[__since 1.4__]

	The extends attribute can use the following wildcards:

	[cols="15%,50%"]
	\|=======
	\|`*`\|all other configurations
	\|`*(public)`\|all other public configurations
	\|`*(private)`\|all other private configurations
	\|=======

	A whole configuration can be declared as non transitive, so that all dependencies resolved in this configuration will be resolved with transitivity disabled. Note that the transitivity is disabled for all the configuration dependencies (including those obtained because this conf extends other ones), and only for this configuration (which means that a conf extending this one with transitivity enabled will get transitive dependencies even for dependencies being part of the non transitive configuration).
	This is very useful to build a compile configuration, for instance, forcing the dependency declaration on each direct dependency, with no risk to forget some because of transitivity.

	This tag supports link:../concept{outfilesuffix}#extra[extra attributes].

	== Attributes

	[options="header",cols="15%,50%,35%"]
	\|=======
	\|Attribute\|Description\|Required
	\|name\|the name of the declared configuration\|Yes
	\|description\|a description for the declared configuration\|No
	\|visibility\|the visibility of the declared configuration.

	`public` means that this configuration can be used by other modules, while `private` means that this configuration is used only in the module itself, and is not exposed to other modules\|No, defaults to `public`
	\|extends\|a comma separated list of configurations of this module that the current configuration extends\|No, defaults to none
	\|transitive\|a boolean to indicate if this conf is transitive or not (__since 1.4__)\|No, defaults to `true`
	\|deprecated\|indicates that this conf has been deprecated by giving the date of the deprecation.

	It should be given in this format: `yyyyMMddHHmmss`\|No, by default the conf is not deprecated
	\|=======

	== Examples

	[source,xml]
	----
	<conf name="core" visibility="private"/>
	<conf name="compile" extends="core" transitive="false" visibility="private"/>
	<conf name="runtime" extends="compile" description="everything needed to run this module"/>
	----

	Declares three configurations, `core`, `compile` and `runtime`, with only the `runtime` one accessible from other modules, and with the `compile` one being non transitive.

	Therefore the `core` configuration will only be composed of dependencies declared in the `core` configuration itself, the `compile` configuration will be composed of all dependencies required in either `core` or `compile` configuration, but without transitivity (neither for core nor compile dependencies), and `runtime` will be composed of all dependencies, all transitively, including the dependencies declared only in `compile`.