- Documentation (trunk)
- Release Notes
- Settings Files
- Ivy Files
- Ant Tasks
- post resolve tasks
- Using standalone
- Developer doc
Here are some terms used in Ivy, with their definitions in Ivy:
- Module Descriptor
- Type of an artifact
- Artifact file name extension
- Module Revision
- Status of a revision
- Configurations of a module
- Ivy Settings
OverviewThe following illustration shows all the key terminology in one diagram:
Often organisations will use their inverted domain name as their organisation name in Ivy, since domain names by definition are unique. A company whose domain name is www.example.com might want to use com.example, or if they had multiple teams, all their organisation names could begin with com.example (e.g. com.example.rd, com.example.infra, com.example.services). The organisation name does neither really have to be an inverted domain name, nor even globally unique, but unique naming is highly recommended. Widely recognized trademark or trade name owners may choose to use their brand name instead.
Examples: org.apache, ibm, jayasoft
Note that the Ivy "organisation" is very similar to Maven POM "groupId".
Ivy is only concerned about the module deliverables known as artifacts, and the module descriptor that declares them. These deliverables, for each revision of the module, are managed in repositories. In other words, to Ivy, a module is a chain of revisions each comprising a descriptor and one or more artifacts.
Examples: hibernate-entitymanager, ant
The most common module descriptors in Ivy are Ivy Files, xml files with an Ivy specific syntax, and usually called ivy.xml.
But since Ivy is also compatible with maven 2 metadata format (called pom, for Project Object Model), pom files fall into the category of module descriptors.
And because Ivy accepts pluggable module descriptor parsers, you can use almost whatever you want as module descriptors.
Compressed package formats are often preferred because they are easier to manage, transfer and store. For the same reasons, only one or a few artifacts per module are commonly used. However, artifacts can be of any file type and any number of them can be declared in a single module.
In the Java world, common artifacts are Java archives or JAR files. In many cases, each revision of a module publishes only one artifact (like jakarta-log4j-1.2.6.tar.gz, for instance), but some of them publish many artifacts dependending on the use of the module (like apache-ant binary and source distributions in zip, gz and bz2 package formats, for instance).
Examples: ant-1.7.0-bin.zip, apache-ant-1.7.0-src.tar.gz
Type of an artifactThe artifact type is a category of a particular kind of artifact specimen. It is a classification based on the intended purpose of an artifact or why it is provided, not a category of packaging format or how the artifact is delivered.
Although the type of an artifact may (rather accidentally) imply its file format, they are two different concepts. The artifact file name extension is more closely associated with its format. For example, in the case of Java archives the artifact type "jar" indicates that it is indeed a Java archive as per the JAR File specification. The file name extension happens to be "jar" as well. On the other hand, with source code distributions, the artifact type may be "source" while the file name extensions vary from "tar.gz", "zip", "java", "c", or "xml" to pretty much anything. So, the type of an artifact is basically an abstract functional category to explain its purpose, while the artifact file name extension is a more concrete technical indication of its format and, of course, naming.
Defining appropriate artifact types for a module is up to its development organisation. Common choices may include: "jar", "binary", "bin", "rc", "exe", "dll", "source", "src", "config", "conf", "cfg", "doc", "api", "spec", "manual", "man", "data", "var", "resource", "res", "sql", "schema", "deploy", "install", "setup", "distrib", "distro", "distr", "dist", "bundle", etc.
Module descriptors are not really artifacts, but they are comparable to an artifact type, i.e. "descriptor" (an ivy file or a Maven POM).
Electronic signatures or digests are not really artifacts themselves, but can be found with them in repositories. They also are comparable to an artifact type, i.e. "digest" (md5 or sha1).
Examples: zip, tar, tar.gz, rar, jar, war, ear, txt, doc, xml, html
Module Revision and Status
Module revisionA unique revision number or version name is assigned to each delivered unique state of a module. Ivy can help in generating revision numbers for module delivery and publishing revisions to repositories, but other aspects of revision control, especially source revisioning, must be managed with a separate version control system.
Therefore, to Ivy, a revision always corresponds to a delivered version of a module. It can be a public, shared or local delivery, a release, a milestone, or an integration build, an alpha or a beta version, a nightly build, or even a continuous build. All of them are considered revisions by Ivy.
Source revisionSource files kept under a version control system (like Subversion, CVS, SourceSafe, Perforce, etc.) have a separate revisioning scheme that is independent of the module revisions visible to Ivy. Ivy is unaware of any revisions of a module's source files.
In some cases, the SCM's source revision number could be used also as the module revision number, but that usage is very rare. They are still two different concepts, even if the module revision number was wholly or partially copied from the respective source revision number.
The head, or trunk, or main stream, is also considered as a branch in Ivy.
Three statuses are defined by default in Ivy:
- integration: revisions builded by a continuous build, a nightly build, and so on, fall in this category
- milestone: revisions delivered to the public but not actually finished fall in this category
- release: a revision fully tested and labelled fall in this category
Configurations of a moduleA module configuration is a way to use or construct a module. If the same module has different dependencies based on how it's used, those distinct dependency-sets are called its configurations in Ivy.
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.
For more details on configurations and how they are used in ivy, please refer to the main concepts page.
History of settingsPrior to Ivy 2.0, the settings files were called configuration files and usually named ivyconf.xml. This resulted in confusion between module configurations and Ivy configuration files, so they were renamed to settings files. If you happen to fall on an ivyconf file or something called a configuration file, most of the time it's only unupdated information (documentation, tutorial or article). Feel free to report any problem like this if you find such an inconsistency.
Ivy can be used with complex repositories configured very finely. You can use Dependency Resolvers to do so.