--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/buildframework/helium/sf/doc/src/structure.rst Tue Apr 27 08:33:08 2010 +0300
@@ -0,0 +1,249 @@
+==============================
+Project Development guidelines
+==============================
+
+
+Helium now contains its Java and Python components into its structure. Its main requirements to build the delivery are:
+ * Ant 1.7.0
+ * JDK 1.6 or newer
+ * Python 2.6
+
+The project is split in several sub-modules which cover specific features.
+
+Anatomy of the project
+======================
+
+::
+
+ + builder
+ - build.xml
+ - bld.bat
+ - bld
+ + antlibs
+ Ant specific dependencies needed to execute ant properly
+ e.g: Java checkstyle, Code coverage tools
+ The jar in that folder will not be used as compilation dependencies
+ + <layer>
+ + doc
+ General documentation of the project
+ + settings
+ + ivysettings.xml
+ + deps
+ + <org>
+ + <name>
+ + <rev>
+ - <name>-<rev>.jar
+ + ...
+ + java
+ + component1
+ + componentn ...
+ + python
+ + component1
+ + componentn ...
+ + <layer> ...
+
+
+Anatomy of a Component
+======================
+
+A component is a self contained structure which implements a set of feature related to a specific domain (e.g: Diamonds, SCM). The following diagram shows
+the physical structure of a component.
+
+::
+
+ + <component_name>
+ - build.xml
+ - ivy.xml
+ + src
+ + com
+ + nokia
+ + helium
+ + <component_name>
+ + ant
+ + taskdefs
+ source of the Ant tasks
+ + types
+ source of the Ant DataType
+ + listeners
+ source of the Ant Listener
+ + conditions
+ source of the Ant Conditions
+ + tests
+ - build.xml
+ - bld.bat
+ - bld.sh
+ + antunits
+ - test_xxx.ant.xml* - Unittest implemented using AntUnit
+ + data
+ data used for the the unittests.
+ + src
+ + com
+ + nokia
+ + helium
+ + <component_name>
+ + tests
+ source of junit unittests.
+
+The build.xml
+-------------
+
+This is simplest file you must have at component level, **<name of the component>** is really important
+as it defines the future name of the jar file.
+::
+
+ <project name="<name of the component>">
+ <description>Component build file.</description>
+ <import file="../../builder/java/macros.ant.xml"/>
+ </project>
+
+The ivy.xml
+-----------
+
+The ivy.xml is used to gather the relevant dependencies to build your component, and to order
+the build of the components correctly:
+
+::
+
+ <?xml version="1.0" encoding="ISO-8859-1"?>
+ <ivy-module version="2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation="http://ant.apache.org/ivy/schemas/ivy.xsd">
+ <info
+ organisation="com.nokia.helium"
+ module="<name of the component>"
+ status="integration">
+ </info>
+ <dependencies>
+ <dependency name="<name of an another component>" rev="latest.integration" conf="default" />
+ <dependency org="dom4j" name="dom4j" rev="1.2.9" conf="default" />
+ </dependencies>
+ </ivy-module>
+
+More info about Ivy can be found from: http://ant.apache.org/ivy/
+
+Antunit files
+-------------
+
+The builder will automatically test all the antunit files from <base_component>/tests/antunits.
+Test must be written by keeping in mind that src tree must remain unmodified after the testing (please use the test.temp.dir).
+
+Example of test file:
+::
+
+ <project name="test-<component>-<feature>" xmlns:au="antlib:org.apache.ant.antunit" xmlns:hlm="http://www.nokia.com/helium">
+ <description>Helium unittests.</description>
+
+ <target name="setUp">
+ <delete dir="${test.temp.dir}" failonerror="false" />
+ <mkdir dir="${test.temp.dir}" />
+ </target>
+
+ <target name="tearDown">
+ <delete dir="${test.temp.dir}" failonerror="false" />
+ <mkdir dir="${test.temp.dir}" />
+ </target>
+
+ <target name="test-file-generation">
+ <echo message="foo-bar" file="${test.temp.dir}/demo.txt" />
+ <au:assertFileExists file="${test.temp.dir}/demo.txt" />
+ </target>
+ </project>
+
+
+
+General guidelines
+==================
+
+Source code license
+-------------------
+Each file added to the project should include the following license header.
+::
+
+ /*
+ * Copyright (c) 2007-2008 Nokia Corporation and/or its subsidiary(-ies).
+ * All rights reserved.
+ * This component and the accompanying materials are made available
+ * under the terms of the License "Eclipse Public License v1.0"
+ * which accompanies this distribution, and is available
+ * at the URL "http://www.eclipse.org/legal/epl-v10.html".
+ *
+ * Initial Contributors:
+ * Nokia Corporation - initial contribution.
+ *
+ * Contributors:
+ *
+ * Description:
+ *
+ */
+
+Documentation
+-------------
+
+All classes and methods must be documented. Ant facade classes (like Task or DataType)
+must be Antdoclet documented (preferably with usage example).
+
+You can find more information on how to document Ant task using the Antdoclet plugin on http://antdoclet.neuroning.com/.
+
+General coding guidelines
+-------------------------
+
+ * Java components must not use getProperty() with hardcoded name coming from helium (e.g: getProject().getProperty("helium.dir")), only exceptions:
+ * Ant Listeners (name of the property must be link to the listener not to helium!)
+ * Code under the legacy component.
+ * It is forbidden to share unittest data between components (else it breaks the self-contained principle).
+
+Logging
+-------
+
+Developer must preferably use standard Ant logging for any user log output.
+Internal debug logging must be implemented using Log4J framework.
+
+ * ANT Listeners must use log4j logging framework - using Ant logging system might cause some looping issues.
+ * Ant Type and Task must use the Ant logging mechanism to report to the user.
+ * Generic framework (part of the code which doesn't links to Ant directly) must use Log4J.
+ * Usage of System.out.println should be avoided.
+ * All the non-handled exceptions should be considered as errors and should be reported as such:
+ * use log("message", Project.MSG_ERR) under Ant
+ * log.error() otherwise.
+ * Exception to this rule must be clearly commented under the code.
+ * Debug information:
+ * Log4J framework (log.debug()) must be used to push information to the Helium debug log - so debug information are not
+ directly visible by the user.
+ * Ant logging framework can also be use to log Type/Task debug info (but log4j is preferred).
+ * PrintStackTrace method should be used on below scenario's:
+ * At the time of unknown exception.
+ * Should be used with exceptions other than BuildException.
+ * In case it is difficult to debug the issue with Exception.getMessage().
+ * use this method during debugging complex issue (this doesn't mean the line should remain in the code after development).
+ * When it is required to print the all the information about the occurring Exception.
+
+
+This is an example on how to use logging:
+::
+
+ import org.apache.log4j.Logger;
+
+ class MyClass extends Task {
+ private static Logger log = Logger.getLogger(MyClass.class);
+
+ public void execute() {
+ log("Executing...");
+ log.debug("some useful debug information.");
+ }
+ }
+
+
+Please find more information on Log4J from the online manual: http://logging.apache.org/log4j/1.2/manual.html.
+
+
+Exception
+---------
+
+Exceptional event reporting and handling is crutial in software development. Developer must make sure it is done accordingly
+to the framework it is currently using:
+
+ * To report a build failure under Ant the BuildException must be used.
+ But we have to keep in mind that a BuildException is not tracked because it derives from the RuntimeError type.
+ So we have to be careful with those and try to limit their puprose to the original usage: Ant build failure.
+ * It is preferable to have meaningful exception type like: FileNotFoundException.
+ * Developer should try to avoid as much as possible the throw or catch raw type of exception like Exception, RuntimeError.
+