ant-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From xav...@apache.org
Subject svn commit: r673330 - in /ant/ivy/core/trunk/doc: images/ivy-terminology.odg images/ivy-terminology.png terminology.html
Date Wed, 02 Jul 2008 09:27:47 GMT
Author: xavier
Date: Wed Jul  2 02:27:46 2008
New Revision: 673330

URL: http://svn.apache.org/viewvc?rev=673330&view=rev
Log:
IMPROVEMENT: Ivy terminology elaboration and illustration (IVY-852) (thanks to Sakari Maaranen)

Added:
    ant/ivy/core/trunk/doc/images/ivy-terminology.odg   (with props)
    ant/ivy/core/trunk/doc/images/ivy-terminology.png   (with props)
Modified:
    ant/ivy/core/trunk/doc/terminology.html

Added: ant/ivy/core/trunk/doc/images/ivy-terminology.odg
URL: http://svn.apache.org/viewvc/ant/ivy/core/trunk/doc/images/ivy-terminology.odg?rev=673330&view=auto
==============================================================================
Binary file - no diff available.

Propchange: ant/ivy/core/trunk/doc/images/ivy-terminology.odg
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: ant/ivy/core/trunk/doc/images/ivy-terminology.png
URL: http://svn.apache.org/viewvc/ant/ivy/core/trunk/doc/images/ivy-terminology.png?rev=673330&view=auto
==============================================================================
Binary file - no diff available.

Propchange: ant/ivy/core/trunk/doc/images/ivy-terminology.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Modified: ant/ivy/core/trunk/doc/terminology.html
URL: http://svn.apache.org/viewvc/ant/ivy/core/trunk/doc/terminology.html?rev=673330&r1=673329&r2=673330&view=diff
==============================================================================
--- ant/ivy/core/trunk/doc/terminology.html (original)
+++ ant/ivy/core/trunk/doc/terminology.html Wed Jul  2 02:27:46 2008
@@ -25,65 +25,110 @@
 </head>
 <body>
 	<textarea id="xooki-source">
-Here are some terms used in Ivy, with their definitions in Ivy:<br/>
-<h2>Organisation</h2>
-An organisation is either a company or a simple group of person
-which produce software. Ivy handle only one level of organisation, so you cannot
-describe a company hierarchy with this concept. But it is used to group sofware
-produced by a same team, just to help find and classify them.<br/>
-<i>Examples: apache, ibm, jayasoft</i>
-<h2>Module</h2>
-A module in ivy is a piece of software that is reusable, and that 
-follow a unique cycle of revision. <br/>
-<i>Examples: hibernate, ant, ...</i>
-<h2>Artifact</h2>
-An artifact is a single file produced by a company when releasing a module. In 
-the java world, common artifacts are jars. In many cases, each revision of a 
-module publish only one artifact (like log4j, for instance), but some of them
-publish many artifacts dependending on the use of the module (like ant, for instance).
-<h2>Revision</h2>
-A revision corresponds to one delivery of a module. It can either be a delivery
-of a release, a milestone, a beta version, a nightly build, or even a continuous
-build. All of them are considered revisions in ivy.
-<h2><a name="branch">Branch</a></h2>
-A branch corresponds to the standard meaning of a branch (or sometimes stream) in source
control management tools.
-The head, or trunk, or main stream, is also considered as a branch in Ivy.
-<h2>Configuration</h2>
-A module 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 differents ways to use or build a module
-are called in ivy configurations. 
-
-For more details on configurations and how they are used in ivy, please refer to the <a
href="concept.html">main concepts page</a>.
-<h2>Status</h2>
-A module status indicates how stable a module revision can be considered. It can 
-be used to consolidate the status of all the dependencies of a module, to prevent
-the use of an integration revision of a dependency in the release of your module.
-Three statuses are defined by default in ivy:
+Here are some terms used in Ivy, with their definitions in Ivy:
 <ul>
-<li>integration: revisions builded by a continuous build, a nightly build, and so on,
fall in this category</li>
-<li>milestone: revisions delivered to the public but not actually finished fall in
this category</li>
-<li>release: revision fully tested and labelled fall in this category</li>
+<li><a href="#organisation">Organisation</a></li>
+<li><a href="#module">Module</a></li>
+<li><a href="#descriptor">Module Descriptor</a></li>
+<li><a href="#artifact">Artifact</a></li>
+<li><a href="#type">Type of an artifact</a></li>
+<li><a href="#extension">Artifact file name extension</a></li>
+<li><a href="#revision">Module Revision</a></li>
+<li><a href="#branch">Branch</a></li>
+<li><a href="#status">Status of a revision</a></li>
+<li><a href="#configurations">Configurations of a module</a></li>
+<li><a href="#settings">Ivy Settings</a></li>
+<li><a href="#repository">Repository</a></li>
 </ul>
-<span class="since">since 1.4</span> This list is <a href="configuration/statuses.html">configurable</a>
in your configuration file.
-<h2>Module descriptor or metadata</h2>
-A generic way to identify what describes a module: the identifier (organisation, name, branch,
revision), the published artifacts and the dependencies.
+
+<h1>Overview</h1>
+The following <a name="illustration">illustration</a> shows all the key terminology
in one diagram:
+
+<p><img alt="terminology illustration" src="images/ivy-terminology.png" width="587"
height="1040" vspace="16"/></p>
+
+<h1><a name="organisation">Organisation</a></h1>
+An organisation is either a company, an individual, or simply any group of people that produces
software. In principle, Ivy handles only a single level of organisation meaning that they
have a flat namespace in Ivy module descriptors. So, with Ivy descriptors, you can only describe
a tree-like organisation structure, if you use a hierarchical naming convention. The organisation
name is used for keeping together software produced by the same team, just to help locate
their published works.
+
+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.
+
+<i>Examples: org.apache, ibm, jayasoft</i>
+
+Note that the Ivy "organisation" is very similar to Maven POM "groupId".
+</dd>
+<h1><a name="module">Module</a></h1>
+A module is a self-contained, reusable unit of software that, as a whole unit, follows a
revision control scheme.
+
+Ivy is only concerned about the module deliverables known as <em>artifacts</em>,
and the <em>module descriptor</em> that declares them. These deliverables, for
each <em>revision</em> of the module, are managed in <em>repositories</em>.
In other words, to Ivy, a module is a chain of revisions each comprising a descriptor and
one or more artifacts.
+
+<i>Examples: hibernate-entitymanager, ant</i>
+<h2><a name="descriptor">Module Descriptor</a></h2>
+A <em>module descriptor</em> is a generic way of identifying what describes a
module: the identifier (organisation, module name, branch and revision), the published artifacts,
possible configurations and their dependencies.
 
 The most common module descriptors in Ivy are [[ivyfile]], 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 falls into the category of module descriptors.
 
 And because Ivy accepts pluggable module descriptor parsers, you can use almost whatever
you want as module descriptors.
+<h1><a name="artifact">Artifact</a></h1>
+An artifact is <em>a single file</em> ready for delivery with the publication
of a module revision, as a product of development.
+
+Compressed package formats are often preferred because they are easier to manage, transfer
and storage. 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).
+
+<i>Examples: ant-1.7.0-bin.zip, apache-ant-1.7.0-src.tar.gz </i>
+<h2><a name="type">Type</a> of an artifact</h2>
+The 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 <em>why</em> is it provided, not
a category of packaging format or <em>how</em> is the artifact delivered.
 
-<h2>Settings</h2>
-Ivy settings files are xml files used to configure ivy to indicate where the modules can
be found and how. 
-<em>Prior to Ivy 2.0, these files were called configuration files and usually named
ivyconf.xml. This resulted in a confusion between module configurations and configuration
files, so they have been renamed in settings files. 
-If you happen to fall on an ivyconf file or something called a configuration file, most of
the time it's only a problem of update of the doc/tutorial/article. Feel free to report any
problem like this if you find such inconsistencies in this documentation.</em>
+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).
+<h2><a name="extension">Artifact file name extension</a></h2>
+In some cases the artifact type already implies its file name extension, but not always.
More generic types may include several different file formats, e.g. documentation can contain
tarballs, zip packages or any common document formats.
+
+<i>Examples: zip, tar, tar.gz, rar, jar, war, ear, txt, doc, xml, html</i>
+<h1>Module <a name="revision">Revision</a> and Status</h1>
+<h2>Module revision</h2>
+A 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 <em>revision</em> always corresponds to <em>a delivered
version of a module</em>. 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.
+<h3><i>Source revision</i></h3>
+Source files kept under a version control system (like Subversion, CVS, SourceSafe, Perforce,
etc.) have a separate revisioning scheme that is independent of the <em>module revisions</em>
visible to Ivy. Ivy is unaware of any revisions of a module's source files.
+
+In some cases, the SCM's <em>source revision</em> number could be used also as
the <em>module revision</em> 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.
+<h2><a name="branch">Branch</a></h2>
+A branch corresponds to the standard meaning of a branch (or sometimes stream) in source
control management tools.
+The head, or trunk, or main stream, is also considered as a branch in Ivy.
+<h2><a name="status">Status of a revision</a></h2>
+A module's status indicates how stable a module revision can be considered. It can be used
to consolidate the status of all the dependencies of a module, to prevent the use of an integration
revision of a dependency in the release of your module.
+
+Three statuses are defined by default in Ivy:
+<ul>
+<li><strong>integration</strong>: revisions builded by a continuous build,
a nightly build, and so on, fall in this category</li>
+<li><strong>milestone</strong>: revisions delivered to the public but not
actually finished fall in this category</li>
+<li><strong>release</strong>: a revision fully tested and labelled fall
in this category</li>
+</ul>
+<span class="since">Since 1.4</span> This list is <a href="configuration/statuses.html">configurable</a>
in your settings file.
+<h1><a name="configurations">Configurations</a> of a module</h1>
+A <em>module configuration</em> 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 differents ways to use or build a module are called in ivy configurations.

+
+For more details on configurations and how they are used in ivy, please refer to the <a
href="concept.html">main concepts page</a>.
+<h1><a name="settings">Ivy Settings</a></h1>
+Ivy settings files are xml files used to configure ivy to indicate where the modules can
be found and how.
+<h3><i>History of settings</i></h3>
+<i>Prior to Ivy 2.0, the settings files were called configuration files and usually
named ivyconf.xml. This resulted in a 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 inconsistencies
in this documentation.</i>
 
-<h2>Repository</h2>
-What is called a repository in Ivy is a location where Ivy is able to find your modules artifacts
and metadata (i.e. ivy files in most cases).
+<h1><a name="repository">Repository</a></h1>
+What is called a <em>repository</em> in Ivy is a distribution site location where
Ivy is able to find your required modules' artifacts and descriptors (i.e. Ivy files in most
cases).
 Ivy can be used with complex repositories configured very finely. You can use <a href="concept.html">Dependency
Resolvers</a> to do so.
-	</textarea>
+</textarea>
 <script type="text/javascript">xooki.postProcess();</script>
 </body>
 </html>



Mime
View raw message