source-build.html 7.88 KB
Newer Older
Matt Tucker's avatar
Matt Tucker committed
1 2 3 4
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<html>
<head>
5
<title>Openfire: Building the Source</title>
6
<link href="style.css" rel="stylesheet" type="text/css">
Matt Tucker's avatar
Matt Tucker committed
7 8
</head>

9
<body>
Matt Tucker's avatar
Matt Tucker committed
10

11 12 13 14 15 16 17 18 19 20 21 22 23
<div id="pageContainer">

<a name="top"></a>

	<div id="pageHeader">
		<div id="logo"></div>
		<h1>Building the Source</h1>
	</div>
	<div class="navigation">
		<a href="index.html">&laquo; Back to documentation index</a>
	</div>
	
	<div id="pageBody">
Matt Tucker's avatar
Matt Tucker committed
24

25 26

<p>This document provides detailed information for developers that wish to
27
compile and make changes to the Openfire source code.</p>
Matt Tucker's avatar
Matt Tucker committed
28 29

<p>For additional developer resources, please visit:
30
<a href="http://www.igniterealtime.org">
31
http://www.igniterealtime.org</a>. The Openfire build process is based on Ant. Visit the
Matt Tucker's avatar
Matt Tucker committed
32 33 34 35 36 37
<a href="http://ant.apache.org/">Ant website</a>
for more information. There is no need to download and install Ant - a version of it is included
in this distribution.
<p>
This documentation is divided into three sections:
<ol>
38 39
 <li> <a href="#source">Source</a> -- get te Openfire source code.
	<li> <a href="#setup">Setup</a> -- how to setup your environment for Openfire development.
Matt Tucker's avatar
Matt Tucker committed
40
	<li> <a href="#tasks">Build tasks</a> -- tasks that can be performed using the build program.
41

Matt Tucker's avatar
Matt Tucker committed
42 43
</ol>

44
<p><a name="source"><b><font color="#0066cc">1.</font> Get the Openfire Source</b></a><p>
Matt Tucker's avatar
Matt Tucker committed
45

46
You can get the Openfire source code by downloading a source distribution or
Matt Tucker's avatar
Matt Tucker committed
47
by checking out the source code from CVS. Instructions for both options can
48
be found on the <a href="http://www.igniterealtime.org/downloads/source.jsp">source page</a>. 
Matt Tucker's avatar
Matt Tucker committed
49 50 51 52 53 54

<p><a name="setup"><b><font color="#0066cc">2.</font> Setup Your Environment</b></a><p>

Getting your machine ready for development requires a few steps. Wherever
possible, instructions are provided for both Unix/Linux and Windows users.
<p>
55

56
<b><a name="javaSetup">Configure Java for Openfire</a></b>
Matt Tucker's avatar
Matt Tucker committed
57 58 59 60 61 62 63
<ul>
	Java 5 (JDK 1.5) must be installed and setup on your machine. To test the installation,
	open a shell in a Unix or a MS-DOS prompt in Windows. Check your version of
	Java with "java -version" -- it must version 1.5 or greater.
	If Java isn't installed, download a copy from the
	<a href="http://java.sun.com/">Java website</a>.
	<p>
64
	<font color="red">Important!</font> -- the Openfire build tool needs to know
Matt Tucker's avatar
Matt Tucker committed
65 66 67 68 69 70 71
	where Java is installed on your system. You must configure the "JAVA_HOME"
	environment variable to point to the correct directory. Instructions on
	how to set this variable for various platforms are as follows:
	<p>
	<ul>
		<li> Unix/Linux
			<ol>
72

Matt Tucker's avatar
Matt Tucker committed
73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88
				<li>Edit the ".profile" file in your home directory (or
					corresponding file for your shell).
				<li>Set the JAVA_HOME environment variable by adding the
					following line to the file:
					<p><span class="code">
					export JAVA_HOME=/usr/local/jdk1.5
					</span>
					<p>
					The value "/usr/local/jdk1.5" should be replaced with your actual
					Java directory. Be sure there are no spaces after the end of
					the directory name. Do not add an extra slash after the directory name.
				<li>Save changes to the file and then "source" it:
					<p><span class="code">
					source .profile
					</span>
					<p>
89

Matt Tucker's avatar
Matt Tucker committed
90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109
					The JAVA_HOME variable should now be configured correctly.
			</ol>
	 	<p>
		<li> WindowsNT/2000/XP
			<ol>
				<li>Navigate to your desktop and right click on "My Computer";
					choose properties.
				<li>Select the "Advanced" tab and click on the
					"Environment Variables" button.
				<li>Click the "New..." button in the System variables section.
					Enter the variable name "JAVA_HOME" and set the variable
					value to the full path of your Java installation. For example,
					"c:\jdk1.5". Be sure to not add an extra slash to the end
					of the directory name.
				<li>Click "OK" in all of the menus to accept the changes.
				<li>Close any open command prompt windows. The next time you
					open a command prompt, the "JAVA_HOME" variable will be set
					correctly.
			</ol>
		<p>
110

Matt Tucker's avatar
Matt Tucker committed
111 112 113 114 115 116 117 118 119 120 121 122 123 124
		<li> Windows95/98
			<ol>
				<li>Open your autoexec.bat file (often at "c:\autoexec.bat") using Notepad.
				<li>Add a line to the end of the file that resembles the following:
					<p><span class="code">
					set JAVA_HOME=c:\jdk1.5
					</span>
					<p>
					The value "c:\jdk1.5" should be replaced with your actual
					Java directory. Be sure there are no spaces between
					the "=" sign or after the end of the directory name. Do
					not add an extra slash after the directory name.
				<li>Save changes to autoexec.bat and restart your computer.
			</ol>
125

Matt Tucker's avatar
Matt Tucker committed
126 127 128 129 130
	</ul>
</ul>

<p><b><a name="ant">Install the Ant Build Tool</a></b><p>

131
The Openfire build process uses Ant, so that tool must be installed
Matt Tucker's avatar
Matt Tucker committed
132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149
and configured on your computer. First download Ant from: 
<a href="http://ant.apache.org/">http://ant.apache.org</a>. Next, follow
the <a href="http://ant.apache.org/manual/installlist.html">installation instructions</a>.

<p><b><a name="checkout">Test the Build Script</a></b><p>
<ul>
Navigate into the subdirectory of this distribution named "build" via the command-line.<p>

<table border="0" cellpadding="2" cellspacing="0"><td bgcolor="#EEEEEE">
<font face="verdana, arial, helvetica" size="2">
<font color="red">Linux/Unix users only:</font>You must make the ant script
executable. From the build directory, type:
<p></font><code>
chmod u+x ant
</code>
</td></table>

<p>
150
Now, invoke the build tool to compile the Openfire source code
Matt Tucker's avatar
Matt Tucker committed
151 152 153

<p>
Windows:<span class="code"> ant  <br> </span><br clear="left">
154

Matt Tucker's avatar
Matt Tucker committed
155 156 157
Unix/Linux:<span class="code"> ./ant </span>
<p>

158 159
If the build tool is invoked correctly and Openfire compiles, you've correctly
configured your copy of the Openfire source distribution.
Matt Tucker's avatar
Matt Tucker committed
160 161 162 163 164

</ul>

<p><b>Finished!</b><p>
<ul>
165
If you've gotten this far, you've finished setting up the Openfire source
166
distribution. Now, read below to learn about some of the tasks that you can perform
Matt Tucker's avatar
Matt Tucker committed
167 168 169 170 171 172 173
with the build tool.
</ul>

<br><br>

<p><b><a name="tasks"><font color="#0066cc">3.</font> Build Tasks</a></b><p>

174
	The list of common build tasks is below. All build commands should be
175
	run from the "build" directory of your Openfire distribution.
Matt Tucker's avatar
Matt Tucker committed
176 177 178

	<br><br>

179
	For a full list of the commands and a brief description from the command line, type
Matt Tucker's avatar
Matt Tucker committed
180
	<code>ant -projecthelp</code>. For more complete help on several commands, 
181
    read the documentation below.
Matt Tucker's avatar
Matt Tucker committed
182 183 184 185 186 187 188

	<br><br>

	To execute a build task, type <code>ant [options] targetname</code> where "targetname" is
	one of the targets listed below:

	<ul>
189

Matt Tucker's avatar
Matt Tucker committed
190
        <li><a href="#noparams"><i>Default</i></a>
191
        <li><a href="#openfire">openfire</a>
Matt Tucker's avatar
Matt Tucker committed
192 193 194 195 196 197 198 199 200
        <li><a href="#plugins">plugins</a>
        <li><a href="#clean">clean</a>
	</ul>
<p>
Each task is documented with a syntax guide and description. Optional paramaters
for each task are enclosed with braces. If you would like to permanently set the
value of a property, add it to build/build.xml file.

<!-- default -->
201

Matt Tucker's avatar
Matt Tucker committed
202 203 204 205 206 207 208 209
<p><b><a name="noparams"><i>Default</i></a></b>
<ul>
<i>Syntax:</i><p>

<span class="code"> ant <br></span>

<p><i>Description:</i></p>

210
Equivalent of calling "ant <a href="#jar">openfire</a>".
Matt Tucker's avatar
Matt Tucker committed
211

212

Matt Tucker's avatar
Matt Tucker committed
213 214 215 216 217
<p>[<a href="#tasks">return to task list</a>]
</ul>


<!--JAR-->
218
<p><b><a name="openfire">openfire</a></b>
Matt Tucker's avatar
Matt Tucker committed
219 220 221
<ul>
<i>Syntax:</i><p>

222
<span class="code"> ant openfire <br></span>
Matt Tucker's avatar
Matt Tucker committed
223 224 225

<p><i>Description:</i></p>

226 227
Builds Openfire into the <tt>target/openfire</tt> directory. You can then launch
Openfire using the scripts in <tt>target/openfire/bin</tt>.
Matt Tucker's avatar
Matt Tucker committed
228 229 230 231 232
<p>[<a href="#tasks">return to task list</a>]
</ul>

<!--PLUGINS-->
<p><b><a name="jar">plugins</a></b>
233

Matt Tucker's avatar
Matt Tucker committed
234 235 236 237 238 239 240
<ul>
<i>Syntax:</i><p>

<span class="code"> ant plugins <br></span>

<p><i>Description:</i></p>

241
Builds all plugins into the <tt>target/openfire/plugins</tt> directory.
Matt Tucker's avatar
Matt Tucker committed
242
<p>[<a href="#tasks">return to task list</a>]
243

Matt Tucker's avatar
Matt Tucker committed
244 245 246 247 248 249 250 251 252 253 254
</ul>

<!--CLEAN-->
<p><b><a name="clean">clean</a></b>
<ul>
<i>Syntax:</i><p>

<span class="code"> ant clean <br></span>

<p><i>Description:</i></p>

255
Cleans all artifacts of the build process.<p>
Matt Tucker's avatar
Matt Tucker committed
256 257 258 259

<p>[<a href="#tasks">return to task list</a>]
</ul>

260 261 262 263 264

	</div>

</div>

Matt Tucker's avatar
Matt Tucker committed
265 266
</body>
</html>