build/README.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
   2
   3 <html>
   4 <head>
   5         <title>Smack Source Distribution</title>
   6     <style type="text/css">
   7         BODY {
   8             font-size : 100%;
   9         }
  10         BODY, TD, TH {
  11             font-family : tahoma, verdana, arial, helvetica, sans-serif;
  12             font-size : 0.8em;
  13         }
  14         A:hover {
  15             text-decoration : none;
  16         }
  17         TT {
  18             font-family : courier new, monospace;
  19             font-weight : bold;
  20             color : #060;
  21         }
  22         PRE, CODE {
  23             font-family : courier new, monospace;
  24             font-size : 100%;
  25         }
  26     </style>
  27 </head>
  28
  29 <body>
  30
  31 <font size=4>
  32 Smack Source Distribution<br>
  33 </font><br>
  34 <p>
  35
  36 This document provides detailed information for developers that wish to
  37 compile and make changes to the Smack source code.
  38
  39 <p>For additional developer resources, please visit:
  40 <a href="http://www.jivesoftware.org/smack/">
  41 http://www.jivesoftware.org/smack/</a>. The Smack build process is based on Ant. Visit the
  42 <a href="http://jakarta.apache.org/ant/index.html">Ant website</a>
  43 for more information and downloads.
  44 <p>
  45 This documentation is divided into two sections:
  46 <ol>
  47         <li> <a href="#setup">Setup</a> -- how to setup your environment for Smack development.
  48         <li> <a href="#tasks">Build tasks</a> -- tasks that can be performed using the build program.
  49 </ol>
  50
  51 <p><a name="setup"><b><font color="#0066cc">1.</font> Setup Your Environment</b></a><p>
  52
  53 Getting your machine ready for Smack development requires a few steps. Wherever
  54 possible, instructions are provided for both Unix/Linux and Windows users.
  55 <p>
  56 <b><a name="javaSetup">Configure Java</a></b>
  57 <ul>
  58         Java 5 (JDK 1.5 or later) must be installed and setup on your machine. To test the installation,
  59         open a shell in a Unix or a MS-DOS prompt in Windows. Check your version of
  60         Java with "java -version" -- it must version 1.5 or greater.
  61         If Java isn't installed, download a copy from the
  62         <a href="http://java.sun.com/">Java website</a>.
  63         <p>
  64         <font color="red">Important!</font> -- the Smack build tool needs to know
  65         where Java is installed on your system. You must configure the "JAVA_HOME"
  66         environment variable to point to the correct directory. Instructions on
  67         how to set this variable for various platforms are as follows:
  68         <p>
  69         <ul>
  70                 <li> Unix/Linux
  71                         <ol>
  72                                 <li>Edit the ".profile" file in your home directory (or
  73                                         corresponding file for your shell).
  74                                 <li>Set the JAVA_HOME environment variable by adding the
  75                                         following line to the file:
  76                                         <p><code>
  77                                         export JAVA_HOME=/usr/local/jdk1.5
  78                                         </code><font face="verdana, arial, helvetica" size=2>
  79                                         <p>
  80                                         The value "/usr/local/jdk1.5" should be replaced with your actual
  81                                         Java directory. Be sure there are no spaces after the end of
  82                                         the directory name. Do not add an extra slash after the directory name.
  83                                 <li>Save changes to the file and then "source" it:
  84                                         <p></font><code>
  85                                         source .profile
  86                                         </code><font face="verdana, arial, helvetica" size=2>
  87                                         <p>
  88                                         The JAVA_HOME variable should now be configured correctly.</font>
  89                         </ol>
  90          </li>
  91          <p>
  92                 <li> Windows
  93                         <ol>
  94                                 <li>Navigate to your desktop and right click on "My Computer";
  95                                         choose properties.
  96                                 <li>Select the "Advanced" tab and click on the
  97                                         "Environment Variables" button.
  98                                 <li>Click the "New..." button in the System variables section.
  99                                         Enter the variable name "JAVA_HOME" and set the variable
 100                                         value to the full path of your Java installation. For example,
 101                                         "c:\jdk1.5". Be sure to not add an extra slash to the end
 102                                         of the directory name.
 103                                 <li>Click "OK" in all of the menus to accept the changes.
 104                                 <li>Close any open command prompt windows. The next time you
 105                                         open a command prompt, the "JAVA_HOME" variable will be set
 106                                         correctly.
 107                         </ol>
 108         </ul>
 109 </ul>
 110
 111 <b><a name="antSetup">Configure Ant</a></b>
 112 <ul>
 113 Download the Ant build tool from the <a href="http://ant.apache.org">Ant website</a>. Follow
 114 the setup instructions for your operating system.
 115 </ul>
 116
 117 <p><b><a name="checkout">Test the Build Script</a></b><p>
 118 <ul>
 119 Navigate into the subdirectory of this distribution named "build" via the command-line.<p>
 120
 121 <table border=0 cellpadding=2 cellspacing=0><td bgcolor="#EEEEEE">
 122 <font face="verdana, arial, helvetica" size=2>
 123 <font color="red">Linux/Unix users only:</font>You must make the ant script
 124 executable. From the build directory, type:
 125 <p></font><code>
 126 chmod u+x ant
 127 </code>
 128 </td></table>
 129
 130 <p>
 131 Now, invoke the build tool to compile the Smack source code
 132
 133 <p>
 134 <font face="verdana, arial, helvetica" size=2> Windows:</font><code> ant  <br>
 135 </code><font face="verdana, arial, helvetica" size=2>
 136 Unix/Linux:</font><code> ./ant
 137 </code><font face="verdana, arial, helvetica" size=2>
 138 <p>
 139
 140 If the build tool is invoked correctly and Smack compiles, you've correctly
 141 configured your copy of the Smack developer distribution.
 142 </font>
 143 </ul>
 144
 145 <p><b>Finished!</b><p>
 146 <ul>
 147 If you've gotten this far, you've finished setting up the Smack developer
 148 distribution. Now, read below to learn about all of the tasks that you can perform
 149 with the build tool.
 150 </ul>
 151
 152 <br><br>
 153
 154 <p><b><a name="tasks"><font color="#0066cc">2.</font> Build Tasks</a></b><p>
 155
 156         The list of build tasks is below. All build commands should be
 157         run from the "build" directory of your Smack distribution.
 158
 159         <br><br>
 160
 161         For a list of the commands and a brief description from the command line, type
 162         <code>ant -projecthelp</code>. For more complete help, read the documentation below.
 163
 164         <br><br>
 165
 166         To execute a build task, type <code>ant [options] targetname</code> where "targetname" is
 167         one of the targets listed below:
 168
 169         <ul>
 170         <li><a href="#noparams"><i>Default</i></a>
 171         <li><a href="#compile">compile</a>
 172         <li><a href="#jar">jar</a>
 173         <li><a href="#javadoc">javadoc</a>
 174         <li><a href="#clean">clean</a>
 175         </ul>
 176 <p>
 177 Each task is documented with a syntax guide and description. Optional paramaters
 178 for each task are enclosed with braces.
 179
 180 <!--COMPILE-->
 181 <p><b><a name="noparams"><i>Default</i></a></b>
 182 <ul>
 183 <i>Syntax:</i><p>
 184
 185 <code>
 186 ant<br>
 187 </code>
 188
 189 <p><i>Description:</i></p>
 190
 191 Equivalent of calling "ant <a href="#jar">jar</a>".
 192
 193 <p>[<a href="#tasks">return to task list</a>]
 194 </ul>
 195
 196 <!--COMPILE-->
 197 <p><b><a name="compile">compile</a></b>
 198 <ul>
 199 <i>Syntax:</i><p>
 200
 201 <code>
 202 ant compile <br>
 203 </code>
 204
 205 <p><i>Description:</i></p>
 206
 207 Compiles all the Smack source code.
 208 The build directory is the "target/classes" directory under your Smack source distribution.
 209
 210 <p>[<a href="#tasks">return to task list</a>]
 211 </ul>
 212
 213
 214 <!--JAR-->
 215 <p><b><a name="jar">jar</a></b>
 216 <ul>
 217 <i>Syntax:</i><p>
 218
 219 <code>
 220 ant jar <br>
 221 </code>
 222
 223 <p><i>Description:</i></p>
 224
 225 Bundles the Smack class files into a JAR file (smack.jar)
 226 that is suitable for adding
 227 into the classpath of an application server.
 228 <p>[<a href="#tasks">return to task list</a>]
 229 </ul>
 230
 231
 232 <!--JAVADOC-->
 233 <p><b><a name="javadoc">javadoc</a></b>
 234 <ul>
 235 <i>Syntax:</i><p>
 236
 237 <code>
 238 ant javadoc <br>
 239 </code>
 240
 241 <p><i>Description:</i></p>
 242
 243 JavaDocs all Smack source code in the source directory.
 244
 245 <p>[<a href="#tasks">return to task list</a>]
 246 </ul>
 247
 248 <!--CLEAN-->
 249 <p><b><a name="clean">clean</a></b>
 250 <ul>
 251 <i>Syntax:</i><p>
 252
 253 <code>
 254 ant clean<br>
 255 </code>
 256
 257 <p><i>Description:</i></p>
 258
 259 Cleans your Smack distribution directory by deleting compiled class files, the
 260 smack.jar file and Javadoc files.<p>
 261
 262 <p>[<a href="#tasks">return to task list</a>]
 263 </ul>
 264
 265 </body>
 266 </html>