This How-To describes how you build SipExchange from the sources. From this howto, you’ll learn how to setup the source code on your computer and build SipExchange from the sources.
- We have used the term “directory” to specify a file location. This is a common Unix convention. In the Windows environment, the term “folder” is used to mean the same thing.
- We have used the Unix directory naming convention in this document. In the Unix environment, a directory hierarchy is specified by the “/” separator. In the Windows environment, the “\” separator is used. In addition, Unix systems do not use drive letters as in Windows. If you are using Windows, you will need to modify the commands accordingly. For example, if we stated $JIPLET_HOME/bin and you are using Windows, it may translate to C:\jiplet-standalone\bin.
- We have used $SIPEXCHANGE_HOME or similar names to specify variables. While installing/configuring, you will need to replace these variables with the actual value. For example, in this document, the variable $SIPEXCHANGE_HOME has been used to specify the directory where the SipExchange code binary is unpackaged. We have commonly used the following variables:
- $JAVA_HOME – directory where the Java Runtime Environment (JRE) is installed.
- $SIPEXCHANGE_HOME – directory where the SipExchange software is unpacked.
- $JBOSS_HOME – directory where JBOSS is installed.
- $HOST – host name/IP address of the system where the jiplet container is installed.
- $RUN – the JBOSS run mode (default, minimal, all, etc.)
- Commands are specified using bold. You need to enter the command by typing/pasting the command and pressing the Enter/Return key. Although in the Unix world this may seem natural, in the Windows environment, lots of users are lost when it comes to entering a command. Also, the prompts “#” or “C:\>” are shown, do not enter them.
Most of the tools you need to perform a build are already included with the source distribution. But you need the following additional software tools to build SipExchange from the sources:
- Java Software Development Kit (JDK) version 1.5: You can download this software from http://www.java.com and install it using the instructions provided by the site.
- Ant version 1.7: You can download Ant from http://ant.apache.org and install it using the instructions provided by the site.
- Google Web Toolkit (GWT) version 1.5: You can download Ant from http://code.google.com/webtoolkit/ and install it using the instructions provided by the site.
The first step is to download the source code from the SipExchange download page. You have two choices for downloading the source code.
- Download and unpack the source package provided in a zip format. We have provided the source for the officially released versions in zip format that you can download along with the binary packages. The source package is called sipexchange-src-x.x.x.zipwhere x.x.x is the version number you want to download. The documentation in this site only pertains to the latest stable version. So, if you decide to download an earlier version, there may be some differences between the documentation and the actual code in place and you need to figure how to handle it on your own.
- Create a directory called “cafesip”. You can create it under your home directory (example: /home/amit/cafesip) on Linux. For windows, we recommend that you create it under your “My Documents” directory. Make sure you have about 150MB of free disk space.
- Unpack the distribution under the “cafesip” directory. A new directory called sipexchange will be created under the cafesip directory. On Windows, you can use the tools that may be included with your operating system or use a commercially available tool like WINZIP. You can also use the jar tool included with the JDK. If you are using Linux, you can use the unzip utility included with your Linux distribution or use the jar tool included with the JDK.
- You can also download the latest snap-shot of the SipExchange source code by accessing the Subversion code repository provided by Sourceforge.
- You will need a subversion client for downloading the software. If you are using Linux, a subversion client called “svn” is already provided with most Linux distributions. For Windows or other operating systems, you need to download a subversion client. Take a look at the Subversion site – http://subversion.tigris.org/ for options.
- Create a directory called “cafesip”. You can create it under your home directory (example: /home/amit/cafesip) on Linux. For windows, we suggest that you create it under your “My Documents” directory.
- Create a sub-directory called “sipexchange” under the “cafesip” directory.
- On Linux systems, run the commands:
$ cd $CAFESIP_HOME
$ svn co http://cafesip.svn.sourceforge.net/svnroot/cafesip/sipexchange/trunk sipexchangeOn Windows, you will have to do something similar in concept but the exact steps depend on what tool you are using.
On entering the command, it will take some time to download the source code from the repository depending on the available bandwidth.
Note: The latest source code in the trunk directory may not be stable and may not even compile. In addition, the document may not even match up. If you want to download the source code that we consider stable, download the software from the URL: http://cafesip.svn.sourceforge.net/svnroot/cafesip/sipexchange/labels/stable .
The source code is in zip format. On Windows, to unpack the distribution, you can use the tools that may be included with your operating system or use a commercially available tool like WINZIP. You can also use the jar tool included with the J2SDK. If you are using Linux, you can use the unzip utility included with your Linux distribution or use the jar tool included with the J2SDK. Also, make sure you have about 100MB of free disk space. The following are the steps for unpacking:
- Create a directory called “cafesip”. You can create it under your home directory (example: /home/amit/cafesip) on Linux. For windows, you can create it under your “My Documents” directory or you can create it under your C:\ root directory.
- Unpack the distribution under the cafesip directory. A new directory called sipexchange will be created under the cafesip directory.
To build the source code, you need to setup certain environmental variables. On Linux, environmental variables can be set by using the “export” or the “setenv” command (depending on your shell). By modifying your startup script (.bashrc, .bash_profile, /etc/profile, etc.), you can make sure that the environment variables remain set every time you login. On Windows, you can right click on the “My Computer” icon and select the “properties” menu item. Select the “Advanced” tab and select “Environment Variables” to setup the environment variables. Note that environment variable names are case-sensitive.
You need to setup the following environment variables:
- JAVA_HOME: Create this variable with the value containing the full path name of the JDK top-level directory.
- GWT_HOME: Create this variable with the value containing the full path name of the GWT top-level directory.
- JBOSS_HOME: Create this variable with the value containing the full path name of the Jboss top-level directory. This is optional and is required only if you want to deploy to a local Jboss server.
- DEVELOPMENT: Create this variable with values “true” or “false”. This is optional. If you set the value to “true”, it provides additional tools like Cobertura Code Coverage, etc.
- PATH: To the path variable, append the full path name of the ant binary directory. The ant binary directory path name is $ANT_HOME/bin. Substitute $ANT_HOME with the full path name of the directory where Ant is installed and replace “/” with “\” for the Windows environment.
- ANT_OPTS: Create this variable with the value – “-Xmx512M”.
The build process compiles the sources and generates the distributions. After you set up the environment as described above, perform the following steps to run the build:
- Open a terminal. Use the “Command Prompt” utility on the Windows environment. On Linux, use an xterm.
- Check if the environment variables are set properly. To check:On the Linux environment, run the “echo $VARIABLE” command where VARIABLE is the name of the variable. The system should display the value for the variable.On the Windows environment, run the “echo %VARIABLE% command where VARIABLE is the name of the variable. The system should display the value for the variable.If the variables are not set properly, please correct the problem before proceeding.
- Change directory to the “sipexchange” directory under the “cafesip” directory that you created above. Use the “cd” command.
- Run the command:
$ antThis command should take a few minutes and should complete without errors.
- The build is now complete. You will find the package in the ZIP format in the “sipexchange” directory.
Before you can deploy the software on the Jboss server, please make sure that you have installed the SipExchange binary distribution and the rest of the prerequisite software as instructed in the Installation howto. To deploy the application follow the steps below:
- Make sure that the JBOSS_HOME environment variable is set.
- Run the commands:
$ cd $SIPEXCHANGE_HOME # replace $SIPEXCHANGE_HOME with the full path name of the top-level SipExchange directory.
$ ant -f deploy.ant deploy
If you want to update the software from the CafeSip Subversion repository, run the build, install the software and run the tests (basically everything) using a single command, follow the steps below:
- Make sure that the MySQL server is running.
- In the root directory of SipExchange source distribution, you will find a file called, private.template.properties. Copy this file to another file called private.properties in the same directory.
- Edit the file using a text editor and enter the correct values for the properties in this file. The instructions are provided in the file.
- run the ant command:
$ ant -f ci.ant
- The ant command will take about 10 minutes. At the end, all tests must pass. You can find reports generated by the test run in the subdirectory – reports.
- The test scripts generate some dummy users and domains. Please cleanup the data from the user interface.
If you examine the build.xml file and other files with .ant extensions located in the sipexchange directory, you will find that you can specify the build properties in the file “build.properties”. Open this file with an editor to modify the properties and re-run the ant command.
There are also a number of other ant targets to perform parts of the build. These targets are necessary when you are doing the development on SipExchange because you may not want to run the complete build every time you make some changes. Read the build.xml to understand what options you have.