A <library> defines a collection of library entries, usually jar files, which you want to use as a group. Libraries can reference other libraries, and <artifact>s and their dependencies.

By itself, a <library> does nothing. It requires a properly configured <library-policy> to get the library to interact with the Ant build script. The repositories in the policy define where to find the files in the library, and the processors in the policy create properties and references within the Ant project.

Antlion allows for the definition of a library in several places. A <libraryDef> acts as a container for multiple libraries. An <artifact> can define a set of <depends> elements, which act like libraries themselves, and can contain full library defintions.

A library may have any attribute assigned to it, to allow for ease of <entry> definition via the <attribute> processor. The id attribute works just like it does with any other Ant type, registering the library in the Ant project namespace. Certain attributes can disable the execution of specific library processors, which is described in detail here.

Nested Elements

lib-entry A library entry contains a set of attributes and/or sub-elements (whose tag name equate to the attribute name, and text data within equates to the attribute value) which are used by the repositories to discover the file corresponding to the entry. Also, some processors in the library type use the attributes to populate the Ant project with properties and references. Repositories and processors can associate special meanings to certain entries. Documentation on these attributes is in the repository or processor documentation. As of Antlion 0.6.0, this has been aliased with <entry>. Parameters Attribute Description Required type The "type" entry attribute has special uses within Antlion. If not specified, it defaults to the value jar. If the type attribute is set to dir, then the repositories should expect the entry to be a directory, rather than a file. No library A library may have a nested referenced library. The nested library will be discovered through its owning libraryDef. The processors will use the referenced library's entries in their actions. Parameters Attribute Description Required refid Reference to another library embedded in either a separate or local libraryDef. It needs to be referenced before the current library. Yes artifact A library may have a nested referenced artifact. See the <artifact> documentation for details on how to create the original artifact. The referenced artifact will be loaded as a <lib-entry> pointing directly to that artifact. An <artifact> reference entry will be automatically marked as an artifact entry, for purposes of inclusion in an artifact repository. In the internals of Antlion, the artifact looks like a <lib-entry> with the location attribute pointing to the actual file location. As such, using the <artifact> does not require an artifact repository. Referencing an artifact does not implicitly load its dependencies. Those can only be added to the library with the <dependencies> element. Parameters Attribute Description Required refid Reference to the artifact ID. Yes dependencies An artifact may define a list of library and artifact dependencies, and those dependencies may be added to a library via this element. See the <artifact> documentation for details on how to create dependencies in an artifact. The element references an artifact ID. If the artifact doesn't declare dependencies, then this element won't do anything. If you're going to use this element on a large scale build, then may we recommend the <version-check> processor. Parameters Attribute Description Required artifactRefId Reference to the artifact ID containing dependencies. As of Antlion 0.6.0, "artifact" acts as an alias for this attribute. Yes type Add the artifact's dependencies in the group with the same type value (case insensitive). If the artifact has a depdendency group without a type, then those are added, too. If this attribute is not specified, then all of the artifact's dependencies will be added to the library, regardless of their type. No

Examples

<libraryDef policyref="policy"> <library id="lib.xdoclet" group="xdoclet" version="1.1"> <entry name="xdoclet" /> <entry name="j2ee-module" /> </library> </libraryDef> Since the definition of the policy isn't listed, we cannot tell from here exactly where the jar files are taken from, and what their name is. However, we can assume that this describes a library grouping for XDoclet version 1.1 related jar files, named something like "xdoclet.jar" and "j2ee-module.jar".