Keros Environment 1.2

Conventions

Project Conventions

Keros strives to adhere to various conventions as described below.

Directory names

Directory names should reflect the contents of those directories:

lib: where applicable, all necessary 3rd party libraries.
src: root directory for all source files.
src/dev: root directory where releasable development work is developed.
src/dev/ant: Ant source files.
src/dev/doc: documentation.
src/dev/resources: root directory for all resource files.
src/dev/resources/en_US: messages for the U.S. locale.
src/dev/xsl: all XSLT transformations.
src/test: root directory for all unit test cases.
src/test/ant: directory containing Ant unit test cases.
src/test/java: directory containing Java code to test availability of Find Bugs.
src/test/javac: directory containing JavaCC code to test the ability to generate parsers.
src/test/resources: directory containing resource related data for unit tests.

File names

Files adhere to the following naming conventions:

Ant scripts: keros*.xml - i.e. keros.xml (reusable scripting) or keros-project.xml (development related).
Resource files: keros*-messages.xml - i.e. keros-messages.xml or keros-project-messages.xml. It is important to note that resources belong in a directory named after the appropriate locale - for example en_US for the United States.

Property Names

Properties are named as follows:

File based: [xml file name].[type].[property name] - for example keros-project.locale.HOME
Macrodef based: [xml file name].[macro name].[property name] - for example keros.svn-xml-log.SVN_LOG_DIR

Properties

User Definable Properties

User definable properties are those that can be defined value outside Keros. If not defined, reasonable default values are used.

There are three ways to express values for user definable properties:

System properties, for example using the -D command line option when invoking Ant or java:

ant -Dkeros-project.java.src.DIR_NAME=MySrcDir

Environment variables:

export keros-project.java.src.DIR_NAME=MySrcDir
ant

Ant properties:

"Fixed" Properties

Fixed properties are those that are set by Keros to predefined values. Often fixed properties are expressed using some user definable properties to create values. Please note: if a fixed property currently has a value, it is reset with a new one as defined by Keros.

Variables

Variables are properties used within macrodef's. These properties will always be overwritten for each call of a macrodef. The naming convention reflects [XML file name (minus dot XML)].[macrodef name].[variable name] - for example keros.unpack-bz2.BZ2_TAR_FILE_NAME

Deriving Directory Information

Properties holding directory information are typically named using a summation strategy: definition of a directory name and a "home" using this name. Additionally, directories may be defined relative to a "root" or home directory. For example:

keros-project.project.HOME = [some directory]
keros-project.assembly.DIR_NAME = "assembly"
keros-project.assembly.HOME = "${keros-project.project.HOME}/${keros-project.assembly.DIR_NAME}"

Building and "skipping"

The build script, keros-project.xml, contains reusable targets and dependencies that follow a named pattern in the form of [xml file name].verb.noun (for example keros-project.document.svn). To skip execution of targets (either directly or through a dependency), most targets make use of the unless attribute. For example <target name = "keros-project.document.svn" unless = "keros-project.document.svn.SKIP"...> Here are a few examples:

Target Name	Unless Attribute
keros-project.document.svn	keros-project.document.svn.SKIP
keros-project.compile.java	keros-project.compile.java.SKIP
keros-project.jar.java	keros-project.jar.SKIP