1<?xml version="1.0"?> 2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" 3 "../../build/docbook-xml/docbookx.dtd"> 4 5<book id="jmol-devel-guide" lang="en"> 6 7<bookinfo> 8 <title>Jmol Developer's Guide</title> 9 <author> 10 <othername>The Jmol Development Team</othername> 11 <affiliation> 12 <address> 13 <email>jmol-developers@lists.sourceforge.net</email> 14 </address> 15 </affiliation> 16 </author> 17 <copyright> 18 <year>2005</year> 19 <year>2006</year> 20 <holder>The Jmol Development Team</holder> 21 </copyright> 22</bookinfo> 23 24<chapter id="Prerequisites"> 25 <title>Prerequisites</title> 26 <itemizedlist> 27 <para> 28 The following package are necessary: 29 </para> 30 <listitem> 31 <para> 32 <package>Java 2 JDK 1.4</package> or <package>Java 5 JDK 1.5</package> 33 (<ulink url="http://java.sun.com/" />). 34 </para> 35 </listitem> 36 <listitem> 37 <para> 38 <package>Apache Ant</package> 39 (<ulink url="http://jakarta.apache.org/ant"/>) - not necessary if you 40 are using Eclipse with a Windows PC 41 (see <link linkend="Eclipse">below</link>). 42 </para> 43 <para> 44 On Linux/Unix/OSX try to install <package>Apache Ant</package> using 45 a package installer. 46 </para> 47 </listitem> 48 <listitem> 49 <para> 50 <package>Subversion</package> 51 - The definitive svn documentation is at 52 <ulink url="http://svnbook.red-bean.com/"/>. 53 </para> 54<!-- 55 <para> 56 On Win32 you can use <package>WinCVS</package> 57 from <ulink url="http://www.wincvs.org"/>, but a far more sophisticated 58 and much easier to use and install alternative 59 is <package>Eclipse</package> 60 from <ulink url="http://www.eclipse.org/downloads"/>. 61 See <xref linkend="Eclipse"/>, that covers Eclipse use. 62 </para> 63 <para> 64 On Mac OSX the cvs software comes on the Developer's CD, 65 which can be freely downloaded from Apple. 66 </para> 67 --> 68 </listitem> 69 </itemizedlist> 70</chapter> 71 72<chapter id="CheckingOutJmol"> 73 <title>Checking Out Jmol from SVN</title> 74 <para> 75 If you are using Eclipse, see <xref linkend="Eclipse"/>. 76 </para> 77 <para> 78 In February 2006 Jmol converted to the <command>subversion</command> version control 79 system for our source code repository, frequently referred to as 80 <command>svn</command>. The <command>svn</command> repository is still hosted by SourceForge. 81 </para> 82 <para> 83 The current development version of the Jmol source code can be checked out using: 84 <screen> 85 <prompt>~/workspace$</prompt> 86 svn checkout https://jmol.svn.sourceforge.net/svnroot/jmol/trunk/Jmol 87 </screen> 88 </para> 89 <para> 90 This creates a directory called <filename class="directory">Jmol</filename> 91 where we work on the source code: 92 <screen><prompt>~/workspace$</prompt> cd Jmol</screen> 93 </para> 94 <para> 95 To know the status of your workspace relative to the current 96 repository you can say: 97 <screen><prompt>~/workspace/Jmol$</prompt> svn status</screen> 98 </para> 99 <para> 100 To update your workspace to the current repository revision 101 use the update command 102 <screen><prompt>~/workspace/Jmol$</prompt> svn update</screen> 103 </para> 104 <para> 105 After modifying local files for testing, you can throw away 106 your local changes and revert your changes back to your 107 checkout revision: 108 <screen><prompt>~/workspace/Jmol$</prompt> svn revert</screen> 109 </para> 110 <para> 111 After developing, compiling, and testing changes locally, 112 you can commit your changes by saying: 113 <screen><prompt>~/workspace/Jmol$</prompt> svn commit</screen> 114 </para> 115 <para> 116 <orgname>Sourceforge.net</orgname> provides basic instructions how to use 117 <command>svn</command> at this page <ulink 118 url="http://sourceforge.net/docman/display_doc.php?docid=31070&group_id=1" /> 119 </para> 120 <para> 121 The definitive documentation for <command>subversion</command> is at 122 <ulink url="http://svnbook.red-bean.com/"/> 123 </para> 124 <para> 125 The home page for subversion is at <ulink url="http://subversion.tigris.org/"/>. 126 </para> 127</chapter> 128 129<chapter id="BuildingJmol"> 130 <title>Building Jmol</title> 131 <para> 132 If you are using Eclipse, see <xref linkend="Eclipse"/>. Otherwise read this 133 section carefully. In additon to the prerequisites mentioned 134 in <xref linkend="Prerequisites"/> you will of course need the Jmol source 135 code. It can be checked out from the <command>subversion</command> 136 repository as described above. 137 </para> 138 <para> 139 Once you have all the prerequisites, Jmol can be built from the top source 140 directory with the <command>ant</command> command. 141 </para> 142 <para> 143 On Linux/Unix/OSX type: 144 <screen><prompt>~/workspace/Jmol$</prompt> ant</screen> 145 </para> 146 <para> 147 Windows users not using Eclipse type: 148 <screen><prompt>C:\workspace\Jmol></prompt> ant</screen> 149 </para> 150</chapter> 151 152<chapter id="RunningJmol"> 153 <title>Running Jmol</title> 154 <para> 155 The development version of the Jmol application is normally run by simply 156 executing the jmol script in the Jmol development directory. 157 </para> 158 <para> 159 The development version of the Jmol applet is normally run by copying the 160 built <filename class="libraryfile">*.jar</filename> files into a test 161 directory and then running a web page that accesses them. 162 </para> 163 <para> 164 On Linux/Unix/OSX: 165 <screen><prompt>~/workspace/Jmol$</prompt> ./jmol</screen> 166 </para> 167 <para> 168 On Windows (not using Eclipse): 169 <screen><prompt>C:\workspace\Jmol></prompt> jmol</screen> 170 </para> 171 <para> 172 If you are using the Eclipse <acronym>IDE</acronym>, you can run the 173 application and/or the applet from within Eclipse. This allows for simpler 174 debugging. See <xref linkend="Eclipse"/> for more information. 175 </para> 176</chapter> 177 178<chapter id="CodingStandard"> 179 <title>Coding Standard</title> 180 <itemizedlist> 181 <listitem> 182 <para> 183 Your text editor should indent for you. If it doesn't then either 184 learn how to enable it or get another editor. 185 </para> 186 </listitem> 187 <listitem> 188 <para> 189 Indentation level should be <emphasis role="bold">two spaces</emphasis>. 190 <programlisting>class Foo { 191 int someClassVariable; 192 193 Foo(int evenOrOdd) { 194 someClassVariable = 99; 195 } 196 197 ... 198}</programlisting> 199 </para> 200 </listitem> 201 <listitem> 202 <para> 203 Space characters should be used instead of tabs. 204 </para> 205 </listitem> 206 <listitem> 207 <para> 208 Assignment and arithmetic operators generally contain spaces on both 209 sides. 210 <programlisting>a = b + c;</programlisting> 211 </para> 212 <para> 213 You are allowed to eliminate the spaces within expressions in order 214 to make operator precedence more clear. 215 <programlisting>int cSquared = a*a + b*b;</programlisting> 216 </para> 217 </listitem> 218 <listitem> 219 <para> 220 Spaces follow commas in argument lists. 221 <programlisting>foo(a, 3.14159, "jmol");</programlisting> 222 </para> 223 </listitem> 224 <listitem> 225 <para> 226 Lines should be no more than <emphasis role="bold">80</emphasis> 227 characters wide. 228 </para> 229 </listitem> 230 <listitem> 231 <para> 232 Open brace goes on the line that starts the block. Close brace goes 233 on a line by itself. 234 <programlisting>if (condition) { 235 ... 236 } else { 237 ... 238 } 239 240 while (condition) { 241 ... 242 }</programlisting> 243 </para> 244 </listitem> 245 <listitem> 246 <para> 247 Loop indexes start at 0, not 1. 248 </para> 249 </listitem> 250 <listitem> 251 <para> 252 The <emphasis role="bold">only</emphasis> valid comparison operators for loop 253 termination are <code><</code> and <code>>=</code> 254 ... anything else is probably a bug. If you are really 255 <emphasis role="bold">sure</emphasis> that it is not a bug then put a comment in 256 the code. 257 </para> 258 </listitem> 259 <listitem> 260 <para> 261 Use long descriptive variable names and method names. Do not be 262 afraid of typing. 263 </para> 264 </listitem> 265 <listitem> 266 <para> 267 Line-by-line comments within the code are 268 <emphasis role="bold">discouraged</emphasis> ... except in very special 269 circumstances. If you put in lots of comments like this then you may 270 find them deleted. 271 </para> 272 </listitem> 273 <listitem> 274 <para> 275 If you feel obligated to insert comments put them as javadoc before 276 the function body. 277 </para> 278 </listitem> 279 <listitem> 280 <para> 281 If your code is changing then do not put in comments. <emphasis role="bold">Bad/outdated 282 comments are worse than no comments.</emphasis> 283 </para> 284 </listitem> 285 <listitem> 286 <para> 287 You may want to look 288 at <ulink url="http://www.amazon.com/exec/obidos/ASIN/0521777682">The 289 Elements of Java Style by Vermeulen, et al</ulink>. 290 </para> 291 </listitem> 292 </itemizedlist> 293 </chapter> 294 295<chapter id="Releasing"> 296 <title>Making a release</title> 297 <para> 298 A Jmol release consists of both the application and the applet. 299 Presumably both will have been well tested. For release, we are generating 300 a number of <filename>JAR</filename> files using Java 1.1. This is to 301 provide compatibility with the Microsoft Java Runtime Environment. 302 <!-- wasn't support for MS JVM dropped? --> 303 </para> 304 <para> 305 In the <filename class="directory">Jmol-data</filename> CVS module directory 306 a number of test files are located for the input filters. All files below 307 that module should be checked prior to a release. 308 </para> 309</chapter> 310 311<chapter id="Packaging"> 312 <title>Packaging</title> 313 <para> 314 Distribution packages will be made for any platform for which a developer 315 promises to provide support. File used to create packages should be 316 commited to CVS under the Jmol/packaging directory. Currently the 317 following packages are available: 318 </para> 319 <itemizedlist> 320 <listitem> 321 <para> 322 <ulink url="http://www.debian.org">Debian</ulink> 323 (by Daniel Leidert and Egon Willighagen) 324 </para> 325 </listitem> 326 <listitem> 327 <para> 328 RPM (by Miguel Howard) 329 </para> 330 </listitem> 331 </itemizedlist> 332</chapter> 333 334<chapter id="CVS"> 335 <title>DEPRECATED - Working with Jmol's CVS</title> 336 <para> 337 This section is deprecated since Jmol has moved to <command>svn</command>. 338 </para> 339</chapter> 340 341<chapter id="Eclipse"> 342 <title>Using Eclipse</title> 343 <para> 344 See the <ulink url="http://wiki.jmol.org/index.php/Eclipse">Jmol Wiki</ulink>. 345 </para> 346</chapter> 347 348</book> 349 350 351