Building Jiplet from Source HowTo

Introduction

This How-To describes how you build the jiplet container from the sources. From this howto, you’ll learn how to setup the source code on your computer and build the jiplet container from the sources.

Content

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 system 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, if you are using Windows, it may translate to C:\jiplet-standalone\bin.
  3. We have used $JIPLET_HOME or similar names to specify environmental variables. While installing/configuring, you will need to replace these variables with the actual values for your machine. For example, in this document, the variable $JIPLET_HOME has been used to specify the directory where the jiplet container code binary is installed. We have commonly used the following variables:
      1. $JAVA_HOME – directory where the Java Runtime Environment (JRE) is installed.
      2. $JIPLET_HOME – directory where the Jiplet Container software is installed.
      3. $JBOSS_HOME – directory where JBOSS is installed.
      4. $TOMCAT_HOME – directory where Tomcat is installed.
      5. $HOST – host name/IP address of the system where the jiplet container is installed.
      6. $RUN – the JBOSS run mode (default, minimal, all, etc.).
      7. $ANT_HOME – the directory where Ant is installed.
      8. $GWT_HOME – the directory where GWT (Google Web Toolkit) is installed.
  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.

Top

Software you need to build the jiplet container

Most of the tools you need to perform the build is already included with the source distribution. But, you need the following additional software tools to build the jiplet container from the sources:

  1. Java Software Development Kit (JDK) version 1.5 or later: 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 the latest stable release of Ant from http://ant.apache.org and install it as per the instructions provided by the site.
  3. Google Web Toolkit (GWT): You can download it from http://code.google.com/webtoolkit/ and install it as per the instructions provided by the site. We use GWT 1.5 or later. The Jiplet Console does not work with GWT 1.4.

Top

Download and install the source code

The first step is to download the source code. You have two choices for downloading the source code.

  1. Download the source package provided in a zip format from the Jiplet project download page. There 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 jiplet-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 jiplet will be created under the cafesip directory.
  2. You can also download the latest snap-shot of the jiplet 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 “jiplet” under the “cafesip” directory.
    • On Linux systems, run the two commands (each on one line):

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

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

    • If you are using Windows, you will have to run a procedure that is equivalent of the above command. The procedure will depend on the tool you are using. Take a look at the Eclipse Setup Howto for how to download the source using the Subclipse Eclipse plugin.

Top

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. GWT_HOME: Create this variable with the value containing the full path name of the directory where the Google Web Toolkit is installed. (For example:C:\Program Files\gwt-windows-1.5.3).
  2. JAVA_HOME: Create a variable with the value containing the full path name of the JDK 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.

Top

Run the build

The build process compiles the sources and generates the distributions. After you setup 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. If the variables are not set properly, correct the problem before proceeding.  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 %VARIABLE% is the name of the variable. The system should display the value for the variable.
  3. Change directory to the “jiplet” 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 2 minutes – will depend on the system you are using) and should complete without errors.

  5. The build is now complete. You will find the packages in the ZIP format in the “jiplet” directory.

Top

Ant options and targets

If you examine the build.xml file located in the jiplet directory, you will find that you can specify the build properties in the file “build.properties”. Open this file with an editor, check out the various targets and run them.

There are also a number of other targets to perform parts of the build. These targets are necessary when you are doing the development on the jiplet 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.

If you are a contributor or if you want to make serious changes to the jiplet container, setup a total development environment using the Eclipse IDE. Instructions on how to setup the environment is explained in details here.

Top

VN:R_U [1.9.20_1166]
Rating: 0.0/10 (0 votes cast)

Leave a Reply