Keros 1.0

"How To"

How To

This section describes how to use portions of Keros but does not describe it all. In most cases, there is sufficiently generated HTML from the included XML files (described below as Ant Doc) that should show enough information to be understandable and usable.

Running Keros

Utilizing Third Party Libraries

Portions of Keros rely upon third party libraries (refer to the project requirements). In order to utilize those libraries, Ant versions prior to 1.7.1 require the inclusion of the libraries as follows:

ant -lib <path of libraries> [task to execute]

For example, assuming that Keros is installed on a Linux system in /home/shared/keros-1.0 and user sfloess is running Keros:

ant -lib /home/sfloess/.keros/1.0/lib:/home/shared/keros-1.0/lib/find-bugs:/home/shared/keros-1.0/lib/ivy [task to execute]

Third party libraries used by Keros and managed by Ivy are, by default, stored in [user's home directory]/.keros/[Keros version number]/lib. Non-Ivy: managed libraries are stored within the Keros "unpacked" release directory in a subdirectory entitled lib. Currently there are two included libraries: Ivy: and Find Bugs. For future reference: Ivy will most likely be included in all Keros releases. However, due to an issue with Find Bugs (some problem with dependencies and a POM file) it had to be included (this may change in future Keros releases).

To determine the version of Ant used, enter the following on the command line:

ant -version

Please note: Ant versions 1.7.1 and later require no configuration - meaning the lib directory will be "automagically" extrapolated. Earlier versions have a bug dealing with taskdef's, scriptdef's and classpath (meaning the classpath is ignored in the taskdef declaration).

Include Keros

As described in the summary, Keros is reusable - simply include the portions needed:

Macros are provided that act like reusable functions for cross platform scripting. For example, assume one wishes to create a property named CURRENT_TIME whose prefix is "The current date is: " plus the current date/time. The following script illustrates this:

<project name = "ComputeCurrentTime"  xmlns:keros = "http://keros.sourceforge.net/keros">
	<import  file = "/some/dir/to/keros/ant/keros.xml"/>

	<keros:compute-timestamp  property = "CURRENT_TIME"  prefix = "The current date is:  "/>

	<echo  message = "${CURRENT_TIME}"/>
</project>

XSLT's are provided to convert Ant scripts and/or Subversion log files to HTML. Additionally utility XSLT functions are included as well. The section below, Generate Documentation, provides further examples.

A project environment that can perform such things as generating code, compiling Java, generating documentation and releases, etc. For example, assume one has development needs that include JavaCC generation and Java compilation. The following Ant script will support this functionality:

<project  name = "ExampleOne"  default = "Main"  xmlns:keros = "http://keros.sourceforge.net/keros">
	<import file = "/some/dir/to/keros/ant/keros-project.xml"/>
	<target  name = "Main"  depends = "keros-project.generate.parser2java, keros-project.compile.java"/>
</project>

Please note: this is a contrived example but illustrates the simplicity in reusing the build portion of Keros. The following will do the same as above:

<project  name = "ExampleOne"  default = "Main"  xmlns:keros = "http://keros.sourceforge.net">
	<import file = "/some/dir/to/keros/ant/keros-project.xml"/>
	<target  name = "Main"  depends = "keros-project.compile"/>
</project>

Generate Documentation

Keros can generate HTML documentation as found below.

Ant Doc

Ant Doc is a macrodef that performs a similar function to Java Doc - usage is expressed in an XML comment preceeding the following elements: import, taskdef, macrodef, scriptdef, and target. Keywords are expanded to represent more meaningful HTML representations as follows:

Keyword	HTML Replacement
@Attributes	<p/><b>Attributes</b>
@Elements	<p/><b>Elements</b>
@Example	<p/><b>Example</b>
@Result	<p/><b>Result</b>
@{	<code>@{
}	}</code>
@attribute:	<br/>
@result:	<br/>
Please note:	<i>Please note:</i>

Consider the following example from assert-equal comment header:

    

When applied using Ant Doc, the HTML result is as follows:

Determines if @{str1} is equal to @{str2}. If the two are not equal, message defined in @{error-msg} is displayed.

Attributes
@{str1} = compared to @{str2}.
@{str2} = compared to @{str1}.
@{error-msg} = if @{str1} not equal to @{str2}, the message when failing will be displayed.

Please note: Ant Doc by itself simply performs a replace of the aforementioned keywords on all files contained within a directory. Therefore, ideally one should use this macrodef after HTML documentation has been generated to a directory. The macrodef's ant2htmlWithNavLinks and ant2html first generate HTML from Ant scripts and then run Ant Doc against the generated HTML.

The following example illustrates using Ant Doc on a directory entitled /some/generated/dir (this is also an example of a cross-platform script):

<project  name = "AntDocExample"  xmlns:keros = "http://keros.sourceforge.net">
	<import file = "/some/dir/to/keros/ant/keros.xml"/>
	<keros:antDoc  dir = "/some/generated/dir"/>
</project>

After executing, all the files contained in /some/generated/dir will have the keywords defined above replaced as described.

Ant To HTML

Ant To HTML and Ant To HTML With Navigation Links are macrodefs for converting Ant scripts to HTML documents. Both macrodef's make use of the same XSLT for HTML conversion. Additionally, after conversion both call Ant Doc against the converted HTML files.

The following example illustrates using Ant To HTML to convert an Ant script, /some/project/dir/build.xml, to HTML:

<project  name = "Ant2htmlExample"  xmlns:keros = "http://keros.sourceforge.net">
	<import file = "/some/dir/to/keros/ant/keros.xml"/>
	<keros:ant2html  basedir = "/some/project/dir"  destdir = /some/output/dir"  includes = "build.xml"/>
</project>

The HTML conversion is generated to /some/output/dir/build.html. If there had been a number of Ant scripts to convert, the includes attribute might resemble:

<project  name = "Ant2htmlExample"  xmlns:keros = "http://keros.sourceforge.net">
	<import file = "/some/dir/to/keros/ant/keros.xml"/>
	<keros:ant2html  basedir = "/some/project/dir"  destdir = /some/output/dir"  includes = "**/*.xml"/>
</project>

Subversion To HTML

Subversion To HTML and Subversion To HTML With Navigation Links are macrodefs for converting Subversion logs to HTML documents. Both macrodef's make use of the same XSLT for HTML conversion.

The following example illustrates using Subversion To HTML to convert the Subversion log a project starting with the initial check in all the way through the current check in:

<project  name = "Svn2htmlExample"  xmlns:keros = "http://keros.sourceforge.net">
	<import file = "/some/dir/to/keros/ant/documentation-macros.xml"/>
	<keros:ant2html  srcdir = "/some/project/dir"  destdir = /some/output/dir"/>
</project

Above, srcdir is a directory where Subversion files are checked out and destdir is the directory where the converted HTML will be generated.

Java Projects

Ivy

When utilizing Ivy one needs to "resolve" and then "retrieve." Please refer to the Ivy documentation for further clarification. However, the following snippet illustrates this:

    <dirname file = "${ant.file}" property = "HOME"/>

    <import file = "../keros-1.0/ant/keros.xml" description = "Need Keros for building"/>

    <ivy:resolve   type = "jar" file = "${HOME}/ivy.xml"/>
    <ivy:retrieve type = "jar" file = "${HOME}/ivy.xml" pattern = "../lib/[artifact].[ext]"/>

    <import file = "../keros-1.0/ant/keros-project.xml" description = "Need Keros for building"/>

Please note: keros.xml is imported first (this contains the definition of Ivy) and lastly keros-project.xml is imported (this contains project related functionality such as a automagic Java compilation).

Compiling Java

Depending on where Ivy downloads artifacts (such as Jars), the Java "library" property will need to reflect this directory. Please examine the following code snippet:

    <property name = "keros-project.lib.HOME" value = "../lib"/>

    <dirname file = "${ant.file}" property = "HOME"/>

    <import file = "../keros-1.0/ant/keros.xml" description = "Need Keros for building"/>

    <ivy:resolve   type = "jar" file = "${HOME}/ivy.xml"/>
    <ivy:retrieve type = "jar" file = "${HOME}/ivy.xml" pattern = "../lib/[artifact].[ext]"/>

    <import file = "../keros-1.0/ant/keros-project.xml" description = "Need Keros for building"/>

Above, Ivy is defined to retrieve to the directory ../lib. Therefore in order for the Keros target keros-project.compile.java to compile correctly the Java "library" property, keros-project.lib.HOME, is set to ../lib.

Directories

Keros defines properties denoting default directory locations (for example keros-project.lib.HOME) and denoted with the word "HOME." Should the defaults not reflect a project's actual directory, one should specify the property's value prior to including keros.xml and/or keros-project.xml. Above in Compiling Java, keros-project.lib.HOME defines the library home to be ../lib.

Building Keros

To build Keros simply download the latest source release and use the included build.xml with no targets defined on the command line.