Keros 1.2

"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 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 is a macrodef 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 is a macrodef 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.

Application Version Number

Keros can place the current version number of your application into documentation for you. To do so, simply define the property keros-project.release.VERSION with a meaningful value and place an "at sign" keros-project.release.VERSION "at sign" (using no spaces) within your HTML documentation (Keros will copy your documentation and do pattern substitution for you). Please note: Here "at sign" refers to the character @ and literally surrounds the text keros-project.release.VERSION.

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).

Sub-projects

Keros has the capability to build sub-projects. By default, it starts from the directory of a project's build.xml (that imports keros-project.xml) calling out to each build.xml found below this directory. The default target is invoked for each. The included files and start directory can be overridden by defining the properties keros-project.sub-project.HOME and keros-project.sub-project.INCLUDES. You may also force this to not run by defining the property keros-project.sub-projects.SKIP (set it to any value).

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.

Releases

Keros will generate various release types: java, document, and source (each utilizes the macrodef release). All define their own paths that are used when building the release type to copy files to include in the release. Each path is defined by an id and a property whose value is that of the id for the path. For example, consider the source release. The following represents its path, path property and target:

<path id = "keros-project.release.source.path.REF_ID" description = "Default path for a source release.">
    <fileset dir = "${keros-project.project.HOME}" includes = "${keros-project.src.DIR_NAME}/**"   excludes = "${keros-project.src.release.EXCLUDES}"/>
    <fileset dir = "${keros-project.project.HOME}" includes = "${keros-project.test.DIR_NAME}/**" excludes = "${keros-project.src.release.EXCLUDES}"/>
    <fileset dir = "${keros-project.project.HOME}" includes = "${keros-project.lib.DIR_NAME}/**"   excludes = "${keros-project.src.release.EXCLUDES}"/>
    <fileset dir = "${keros-project.project.HOME}" includes = "build.xml"/>
    <fileset dir = "${keros-project.project.HOME}" includes = "ivy.xml"/>
</path>

<keros:auto-property property = "keros-project.release.source.PATH" default = "keros-project.release.source.path.REF_ID" description = "Property that holds the name of the source release's path ref id."/>

<target name = "keros-project.release.source" unless = "keros-project.release.source.SKIP" description = "Create a source release">
    <keros:release base-file = "${keros-project.release.src.FILE_NAME}" base-dir = "${keros-project.src.release.BASE_DIR}" dir = "${keros-project.src.release.generated.HOME}" stage-dir = "${keros-project.release.HOME}">
        <keros:release-fileset>
            <path refid = "${keros-project.release.source.PATH}"/>
        </keros:release-fileset>
    </keros:release>
</target>

As can be seen, a source release uses whatever path is contained in the property ${keros-project.release.source.PATH}. To modify what files are included as part of a release, modify the appropriate property and define your own path. Here is an example that includes the 1.2 release of Keros as part of a source release:

<path id = "jplate.release.source.path.REF_ID" description = "Source path for JPlate...">
    <path refid = "keros-project.release.source.path.REF_ID"/>
    <fileset dir = "${keros.build.HOME}" includes = "${jplate.keros.HOME}/**"/>
</path>

<keros:set-property property = "keros-project.release.source.PATH" value = "jplate.release.source.path.REF_ID"/>

Building Keros

There are a few ways to build Keros:

Get the latest source from Subversion: svn co https://keros.svn.sourceforge.net/svnroot/keros/trunk
Get the source for this release from Subversion: svn co https://keros.svn.sourceforge.net/svnroot/keros/branches/keros-1.2
Download the source. Please note if you download the source you will need to skip building the Subversion log as there will not be the appropriate files/directories in this download (you will get an error). To do so, simply define the environment variable keros-project.document.svn.SKIP setting it to any value.

Once you have a copy of the source (and unpacked if you downloaded), execute Ant against the build.xml contained in the same directory holding the directory entitled src. No additional parameters are required.