Building SmartFrog

A guide to building the SmartFrog Framework

1. Introduction

This document describes how to build the SmartFrog framework from its source files. It describes how to set up the development system, and how to execute the build scripts.

2. Building the System

Here are the requirements and steps to build SmartFrog.

2.1 Hardware and Operating System Requirements

You will need a system capable of running Java at a reasonable speed. We find that SmartFrog can be build perfectly adequately on systems of around 500Mhz with 256MB of RAM, but faster and bigger are obviously better.

In theory, SmartFrog can be built on any platform capable of running a current version of Java. In practice, we use Linux and Windows, and it's best to stick to Windows 2000 or above.

2.2 Software Requirements

SmartFrog has very lightweight requirements in terms of what software must be installed in order to build the system, but you do need to have the following:

Java JDK

JDK version 1.4.2 is required. Once this is installed, set the JAVA_HOME environment variable to point to the installation directory, e.g.

export JAVA_HOME=/usr/java/jdk1.4.2 (Linux)

Also set the PATH environment variable to include the Java binaries directory, e.g.

export PATH=$PATH:/usr/java/jdk1.4.2/bin (Linux)

(For Windows, just use the method of setting environment variables supported by your version of the OS. On Windows XP, this is accessed via “My Computer” / right clicks for "Properties" / "Advanced" tab / "Environment Variables" button.)

Jakarta Ant

We require Ant version 1.6.5. Once installed, add the Ant binary directory to the PATH, e.g.:

export PATH=$PATH:/usr/bin/Ant1.6.5/bin (Linux)

Open SSL

OpenSSL is only required if you need to create a certification authority for securing SmartFrog hosts and SmartFrog code. Most of the build scripts will run without it, so you may not need this to get started. OpenSSL (version 0.9.5a or later) is required to set up a certification authority to initialize the security infrastructure.

If you do install it, the openSLL binaries directory must be added to the system PATH.

2.3 Downloading SmartFrog

SmartFrog can be downloaded in two ways

Subversion Access

The complete SmartFrog source can be checked out from the SourceForge.net Subversion repository by following the instructions given below.

svn checkout https://svn.sourceforge.net/svnroot/smartfrog/trunk/core

To update your working copy

svn update

To browse the repository:

http://svn.sourceforge.net/viewvc/smartfrog/trunk/core/

Recomended Subversion client software:

http://sourceforge.net/docs/B01#svn_client

To get more information about Subversion visit: http://svnbook.red-bean.com/

Packaged Releases

SmartFrog source and binaries can be downloaded from http://sourceforge.net/projects/smartfrog

2.4 Building SmartFrog

SmartFrog can be build in two ways

CVS Repository

When SmartFrog is checked out from the SourceForge.net CVS repository, there is a top level directory, e.g. <cvs_directory>/core”, which is the top level directory.

The schema of the final directory structure would look like:

<cvs_directory>\core

                        |---- smartfrog

                           |--- dist

...

                        |---- components

...

                        |---- testharness

...

To build the system (SmartFrog core and components), in either Linux or Windows, follow the steps:

cd <cvs_directory>/core
ant dist components

To install all the SmartFrog components in the SmartFrog core distribution after they are build follow the steps:

cd <cvs_directory>/core
ant install

Packaged Releases

When SmartFrog is unpacked from its tarball or zip file, there is a top level directory, e.g. <install_dir>/SmartFrog, which we'll refer to as the top directory. The packaged releases can also be unpacked in a top level directory like <install_dir>/core/SmartFrog to make the paths same as in CVS Repository checkout.

The schema of the final directory structure would look like:

<install_dir>\core

                        |---- smartfrog

                           |--- dist

To build the system (SmartFrog core), in either Linux or Windows, follow the steps:

cd <install_dir>/SmartFrog
ant

If all is well, the system should build.

You can perform a quick test of the system by changing directory to the "dist" directory under <install_dir>/SmartFrog and executing the following scripts from the command line as follows:

Starting a SmartFrog daemon:

bin/sfDaemon (Linux)
bin\sfdaemon (Windows)

This should bring up the SmartFrog Daemon display window.

Deploying a test application in localhost:

·               \bin\sfStart localhost test org/smartfrog/examples/subprocesses/subprocess.sf

Terminating the deployed application:

·               \bin\sfTerminate localhost test

Stopping the SmartFrog Daemon:

·               \bin\sfStopDaemon localhost

3. Testing SmartFrog

SmartFrog core and components can be tested by running unit and system tests. These tests are written as JUnit tests which needs the JUnit version 3.8.1 available at http://sourceforge.net/projects/junit. The junit.jar file needs to be placed in the Ant lib directory i.e. <ant_install_dir>/lib.

To run the tests for SmartFrog components, copy the jar files of all the components from their respective dist/lib directories i.e. core/components/<component>dist/lib directory to core/smartfrog/dist/lib directory and then run the tests.

The unit and system tests can be run by following the steps:

cd <cvs_directory>/core
ant cc

This will run all the tests and generate the test reports which can be viewed at core/testharness/build/test/report/index.html.

These above mentioned testing instructions apply to the full SmartFrog checkout from Sourceforge.net CVS repository. The packaged releases do not contain tests.

4. Troubleshooting

Make sure all the tools are stable builds of at least the minimum required version.

When in doubt, make sure you have correctly installed each tool, and that it is running without errors. Run "java -version", and "ant", and check for sensible output.

Double-check environment variables.

The build may fail if your PATH environment variable contains quotes ("), and you are using Cygwin tools. Quotes are not properly translated when passed down to cygwin sub-shells.

To get diagnostics information when the SmartFrog daemon fails run the following script from the command line as follows:

smartfrog -d -e >diagnostics.txt ( Please send this file attached when reporting problems to SmartFrog’s support list)

SmartFrog support distribution list.

mailto:smartfrog-support@lists.sourceforge.net

SmartFrog developer distribution list:

mailto: smartfrog-developer@lists.sourceforge.net