Look what Java and SIP can do
 (SIP)Java = ∞
Home     News     Projects     Downloads     Support     Contact
SipExchange Home

Javadocs

SipExchange Basics

Developing your own Service

SipExchange Architecture

CafeSip.org Java Coding Conventions

CafeSip Contributor Howto

Building from Source Howto

Introduction

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.

Content
  1. Conventions
  2. Software you need to build SipExchange
  3. Download and install the source code
  4. Unpack the source code
  5. Setup the build environment
  6. Run the build
  7. Deploy the build
  8. Ant options and targets

Conventions

  1. 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.
  2. 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.
  3. 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:
    1. $JAVA_HOME - directory where the Java Runtime Environment (JRE) is installed.
    2. $SIPEXCHANGE_HOME - directory where the SipExchange software is unpacked.
    3. $JBOSS_HOME - directory where JBOSS is installed.
    4. $HOST - host name/IP address of the system where the jiplet container is installed.
    5. $RUN - the JBOSS run mode (default, minimal, all, etc.)
  4. 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.

Software you need to build SipExchange

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:
  1. Java Software Development Kit (J2SDK) version 1.5: You can download this software from http://www.java.com and install it using the instructions provided by the site.
  2. Ant: You can download Ant from http://ant.apache.org and install it using the instructions provided by the site. Make sure that you have downloaded the latest stable version of Ant.
Top

Download and install the source code

The first step is to download the source code from the CafeSip web site. The CafeSip download site is hosted by SourceForge.net (http://www.sourceforge.net/projects/cafesip). Note that the CafeSip project at SourceForge contains sub-projects. Make sure you select the sipexchange project You have two choices for downloading the source code.
  1. Download 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.zip where 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.
    •  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 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. 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.
  2. 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. 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, you can create it under your "My Documents" directory or you can create it under your C:\ root directory.
    • Create a sub-directory called "sipexchange" under the "cafesip" directory.
    • On Linux systems, run the command:

           $ cd $CAFESIP_HOME
           $ svn co http://cafesip.svn.sourceforge.net/svnroot/cafesip/sipexchange/trunk sipexchange

      Note: The latest source code in the trunk directory may not be stable and may not even compile. Morever, 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 .
Top

Unpack the source code

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:
  1. 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.
  2. Unpack the distribution under the cafesip directory. A new directory called sipexchange will be created under the cafesip directory.

Setup the build environment

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:
  1. CAFESIP_HOME: Create this variable with the value containing the full path name of the "cafesip" directory your created above. (For example: /home/amit/cafesip or C:\cafesip).
  2. JAVA_HOME: Create a variable with the value containing the full path name of the J2SDK top-level directory.
  3. 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.

Run the build

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:
  1. Open a terminal. Use the "Command Prompt" utility on the Windows environment. On Linux, use an xterm.
  2. 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.
  3. Change directory to the "sipexchange" directory under the "cafesip" directory that you created above. Use the "cd" command.
  4. Run the command:

          $ ant

    This command should take a few moments (about a minute - will depend on the system you are using) and should complete without errors.
  5. The build is now complete. You will find the package in the ZIP format in the "sipexchange" directory.
Top

Deploying the build

Before you can deploy the software on the Jboss server, please make sure that you have installed the SipExchange and the rest of the prerequisite software as instructed in the Installation howto with the following exceptions:
  1. If you have not downloaded the binary distribution, you will ot find the directory - $SIPEXCHANGE_HOME/setup. You can pickup the files mentioned in the installation howto from the $SIPEXCHANGE_HOME/conf directory instead.
  2. Follow the instructions until you have reached the section - Deploying SipExchange on Jboss. Once you have reached this point, follow the alternative instructions provided below.
We have provided a target in the Ant script to deploy the application on the Jboss server. This will make it easy for you to deploy the application the first time and after you have made changes. Once you have deployed the application by running the ant target, if the Jboss server is running, the server will automatically re-deploy the application. Otherwise, the application will be deployed when Jboss starts up. To deploy the application follow the steps below:
  1. Setup an environment variable called JBOSS_HOME. The variable must contain the full path name of the directory where the Jboss application server is installed. If you are using Eclipse for development, remember to restart Eclipse after setting the variable.
  2. Run the ant target - deploy-jboss:

        $ ant deploy-jboss

Ant options and targets

If you examine the build.xml file 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.

Top

Search this website 


Send questions or comments about this web site to webmaster@cafesip.org.
Copyright © 2005, CafeSip.org.
Licensed under the CafeSip License.
The CafeSip.org projects, web site and web facilities have been sponsored by QUIK Computing

Top of page