1 ============================== |
|
2 Project Development guidelines |
|
3 ============================== |
|
4 |
|
5 |
|
6 Helium now contains its Java and Python components into its structure. Its main requirements to build the delivery are: |
|
7 * Ant 1.7.0 |
|
8 * JDK 1.6 or newer |
|
9 * Python 2.6 |
|
10 |
|
11 The project is split in several sub-modules which cover specific features. |
|
12 |
|
13 Anatomy of the project |
|
14 ====================== |
|
15 |
|
16 :: |
|
17 |
|
18 + builder |
|
19 - build.xml |
|
20 - bld.bat |
|
21 - bld |
|
22 + antlibs |
|
23 Ant specific dependencies needed to execute ant properly |
|
24 e.g: Java checkstyle, Code coverage tools |
|
25 The jar in that folder will not be used as compilation dependencies |
|
26 + <layer> |
|
27 + doc |
|
28 General documentation of the project |
|
29 + settings |
|
30 + ivysettings.xml |
|
31 + deps |
|
32 + <org> |
|
33 + <name> |
|
34 + <rev> |
|
35 - <name>-<rev>.jar |
|
36 + ... |
|
37 + java |
|
38 + component1 |
|
39 + componentn ... |
|
40 + python |
|
41 + component1 |
|
42 + componentn ... |
|
43 + <layer> ... |
|
44 |
|
45 |
|
46 Anatomy of a Component |
|
47 ====================== |
|
48 |
|
49 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 |
|
50 the physical structure of a component. |
|
51 |
|
52 :: |
|
53 |
|
54 + <component_name> |
|
55 - build.xml |
|
56 - ivy.xml |
|
57 + src |
|
58 + com |
|
59 + nokia |
|
60 + helium |
|
61 + <component_name> |
|
62 + ant |
|
63 + taskdefs |
|
64 source of the Ant tasks |
|
65 + types |
|
66 source of the Ant DataType |
|
67 + listeners |
|
68 source of the Ant Listener |
|
69 + conditions |
|
70 source of the Ant Conditions |
|
71 + tests |
|
72 - build.xml |
|
73 - bld.bat |
|
74 - bld.sh |
|
75 + antunits |
|
76 - test_xxx.ant.xml* - Unittest implemented using AntUnit |
|
77 + data |
|
78 data used for the the unittests. |
|
79 + src |
|
80 + com |
|
81 + nokia |
|
82 + helium |
|
83 + <component_name> |
|
84 + tests |
|
85 source of junit unittests. |
|
86 |
|
87 The build.xml |
|
88 ------------- |
|
89 |
|
90 This is simplest file you must have at component level, **<name of the component>** is really important |
|
91 as it defines the future name of the jar file. |
|
92 :: |
|
93 |
|
94 <project name="<name of the component>"> |
|
95 <description>Component build file.</description> |
|
96 <import file="../../builder/java/macros.ant.xml"/> |
|
97 </project> |
|
98 |
|
99 The ivy.xml |
|
100 ----------- |
|
101 |
|
102 The ivy.xml is used to gather the relevant dependencies to build your component, and to order |
|
103 the build of the components correctly: |
|
104 |
|
105 :: |
|
106 |
|
107 <?xml version="1.0" encoding="ISO-8859-1"?> |
|
108 <ivy-module version="2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
|
109 xsi:noNamespaceSchemaLocation="http://ant.apache.org/ivy/schemas/ivy.xsd"> |
|
110 <info |
|
111 organisation="com.nokia.helium" |
|
112 module="<name of the component>" |
|
113 status="integration"> |
|
114 </info> |
|
115 <dependencies> |
|
116 <dependency name="<name of an another component>" rev="latest.integration" conf="default" /> |
|
117 <dependency org="dom4j" name="dom4j" rev="1.2.9" conf="default" /> |
|
118 </dependencies> |
|
119 </ivy-module> |
|
120 |
|
121 More info about Ivy can be found from: http://ant.apache.org/ivy/ |
|
122 |
|
123 Antunit files |
|
124 ------------- |
|
125 |
|
126 The builder will automatically test all the antunit files from <base_component>/tests/antunits. |
|
127 Test must be written by keeping in mind that src tree must remain unmodified after the testing (please use the test.temp.dir). |
|
128 |
|
129 Example of test file: |
|
130 :: |
|
131 |
|
132 <project name="test-<component>-<feature>" xmlns:au="antlib:org.apache.ant.antunit" xmlns:hlm="http://www.nokia.com/helium"> |
|
133 <description>Helium unittests.</description> |
|
134 |
|
135 <target name="setUp"> |
|
136 <delete dir="${test.temp.dir}" failonerror="false" /> |
|
137 <mkdir dir="${test.temp.dir}" /> |
|
138 </target> |
|
139 |
|
140 <target name="tearDown"> |
|
141 <delete dir="${test.temp.dir}" failonerror="false" /> |
|
142 <mkdir dir="${test.temp.dir}" /> |
|
143 </target> |
|
144 |
|
145 <target name="test-file-generation"> |
|
146 <echo message="foo-bar" file="${test.temp.dir}/demo.txt" /> |
|
147 <au:assertFileExists file="${test.temp.dir}/demo.txt" /> |
|
148 </target> |
|
149 </project> |
|
150 |
|
151 |
|
152 |
|
153 General guidelines |
|
154 ================== |
|
155 |
|
156 Source code license |
|
157 ------------------- |
|
158 Each file added to the project should include the following license header. |
|
159 :: |
|
160 |
|
161 /* |
|
162 * Copyright (c) 2007-2008 Nokia Corporation and/or its subsidiary(-ies). |
|
163 * All rights reserved. |
|
164 * This component and the accompanying materials are made available |
|
165 * under the terms of the License "Eclipse Public License v1.0" |
|
166 * which accompanies this distribution, and is available |
|
167 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
168 * |
|
169 * Initial Contributors: |
|
170 * Nokia Corporation - initial contribution. |
|
171 * |
|
172 * Contributors: |
|
173 * |
|
174 * Description: |
|
175 * |
|
176 */ |
|
177 |
|
178 Documentation |
|
179 ------------- |
|
180 |
|
181 All classes and methods must be documented. Ant facade classes (like Task or DataType) |
|
182 must be Antdoclet documented (preferably with usage example). |
|
183 |
|
184 You can find more information on how to document Ant task using the Antdoclet plugin on http://antdoclet.neuroning.com/. |
|
185 |
|
186 General coding guidelines |
|
187 ------------------------- |
|
188 |
|
189 * Java components must not use getProperty() with hardcoded name coming from helium (e.g: getProject().getProperty("helium.dir")), only exceptions: |
|
190 * Ant Listeners (name of the property must be link to the listener not to helium!) |
|
191 * Code under the legacy component. |
|
192 * It is forbidden to share unittest data between components (else it breaks the self-contained principle). |
|
193 |
|
194 Logging |
|
195 ------- |
|
196 |
|
197 Developer must preferably use standard Ant logging for any user log output. |
|
198 Internal debug logging must be implemented using Log4J framework. |
|
199 |
|
200 * ANT Listeners must use log4j logging framework - using Ant logging system might cause some looping issues. |
|
201 * Ant Type and Task must use the Ant logging mechanism to report to the user. |
|
202 * Generic framework (part of the code which doesn't links to Ant directly) must use Log4J. |
|
203 * Usage of System.out.println should be avoided. |
|
204 * All the non-handled exceptions should be considered as errors and should be reported as such: |
|
205 * use log("message", Project.MSG_ERR) under Ant |
|
206 * log.error() otherwise. |
|
207 * Exception to this rule must be clearly commented under the code. |
|
208 * Debug information: |
|
209 * Log4J framework (log.debug()) must be used to push information to the Helium debug log - so debug information are not |
|
210 directly visible by the user. |
|
211 * Ant logging framework can also be use to log Type/Task debug info (but log4j is preferred). |
|
212 * PrintStackTrace method should be used on below scenario's: |
|
213 * At the time of unknown exception. |
|
214 * Should be used with exceptions other than BuildException. |
|
215 * In case it is difficult to debug the issue with Exception.getMessage(). |
|
216 * use this method during debugging complex issue (this doesn't mean the line should remain in the code after development). |
|
217 * When it is required to print the all the information about the occurring Exception. |
|
218 |
|
219 |
|
220 This is an example on how to use logging: |
|
221 :: |
|
222 |
|
223 import org.apache.log4j.Logger; |
|
224 |
|
225 class MyClass extends Task { |
|
226 private static Logger log = Logger.getLogger(MyClass.class); |
|
227 |
|
228 public void execute() { |
|
229 log("Executing..."); |
|
230 log.debug("some useful debug information."); |
|
231 } |
|
232 } |
|
233 |
|
234 |
|
235 Please find more information on Log4J from the online manual: http://logging.apache.org/log4j/1.2/manual.html. |
|
236 |
|
237 |
|
238 Exception |
|
239 --------- |
|
240 |
|
241 Exceptional event reporting and handling is crutial in software development. Developer must make sure it is done accordingly |
|
242 to the framework it is currently using: |
|
243 |
|
244 * To report a build failure under Ant the BuildException must be used. |
|
245 But we have to keep in mind that a BuildException is not tracked because it derives from the RuntimeError type. |
|
246 So we have to be careful with those and try to limit their puprose to the original usage: Ant build failure. |
|
247 * It is preferable to have meaningful exception type like: FileNotFoundException. |
|
248 * Developer should try to avoid as much as possible the throw or catch raw type of exception like Exception, RuntimeError. |
|
249 |
|