Start with J-Sim

July 5, 2006

System Requirement

The system requirement for running J-Sim is a Java Virtual Machine (JVM) and J2SDK1.4-compliant class library. For better stability and performance, we strongly recommend that Sun's J2SDK 1.4 or later be used.  One can always benefit from multiple-processor machines with an enormous amount of system memories, but we have tested J-Sim on some low-profile PC's (Celeron-466 with 96MB RAM, PII-400 with 128 RAM) and are reasonably satisfied with the performance.

For Linux users, good alternatives are Blackdown's JDK at http://www.blackdown.org and IBM's Developer Kit for Linux at http://www.ibm.com/java.

Download J-Sim

The most recent major release is release 1.3.  Starting from this release, binary class files are not included in the package.  After downloading the package, you need to compile it either using "make" or "Apache Ant".  See the sections below for details.  (If you need an opinion, Apache Ant is highly recommended for the task as it is easier to maintain and runs much faster than "make".)

Patches may be released between major releases.  Please check this page for available patches.

A separate, binary only, package is available at http://www.j-sim.org/v1.3/, looking for "j-sim1.3*_binary.tgz".  Refer to the included README file for how to use this package.

Note: J-Sim v1.3 is not compatible with Sun's JDK 5.0.  To make it work, apply patch 4 or later.  After the patch is applied, recompile the source and ignore all the warnings.

Install J-Sim on Unix/Linux

  1. Unpack the archive to a directory (the J-Sim root).
  2. Set up environment variables J_SIM, CLASSPATH, JAVA_HOME, and IS_UNIX:
	J_SIM=... 	# the J-Sim root
	CLASSPATH=.:$J_SIM/classes:$J_SIM/jars/tcl.zip:$J_SIM/jars/jython.jar
	JAVA_HOME=... 	# javac and javadoc should be in $JAVA_HOME/bin
	IS_UNIX=... 	# can be anything
The first two are for running J-Sim, and the last two for compiling sources.
  1. Compile the source by
	make

or

	ant compile

if you have Apache Ant installed (see the "Compile The Sources with Apache Ant" section below).

Install J-Sim on Windows

  1. Unpack the archive to a directory (the J-Sim root).
  2. Modify the J-Sim root directory (J_SIM), and Java home directory (JAVA_HOME) in "setcpath.bat".
  3. Run the "setcpath.bat" script to set environment variables JAVA_HOME, J_SIM and CLASSPATH before using the package. The first two variables are for GNU make. The last one is for running J-Sim.

    4. One may set these variables whenever and wherever is appropriate (for example, C:\autoexec.bat for Windows 9x, the environment variables applet in the "System" control panel for Windows NT) so that one does not need to run the above script every time starting J-Sim.
  4. Compile the source by
	make

if you have "make" facilities installed on Windows (check "GNU utilities for Win32"), or

	ant compile

if you have Apache Ant installed (see the "Compile The Sources with Apache Ant" section below).

Run J-Sim

Use the following command to start a J-Sim session:

	java drcl.ruv.System ?<script>? ?<argument>...?

Or

	java drcl.ruv.System -n ?<script>? ?<argument>...?

where <script> is the initial script to run with. With the option "-n", J-Sim terminal output is disabled and the output only goes to the standard output.

For example:

	java drcl.ruv.System test.tcl 10 "arg2"

The above command starts J-Sim with the script "test.tcl" which in turn takes 10 and "arg2" as its input arguments.

Now, try:

	java drcl.ruv.System

If you see a terminal window, titled "TCL0", pop up, the installation has succeeded.  Check the J-Sim version with the "jsim" command.  The following is a screen dump from running J-Sim on Mandrake Linux:

You may proceed to read the tutorial now. Enjoy and have fun.

J-Sim can also be run without invoking the interactive terminal. This can be useful when running several scripts in a batch:

	java drcl.ruv.System -ue ?<script>? ?<argument>...?

The "-e" option exits the session when simulation is done.

Directory Structure

This J-Sim package uses the makefile setup described in "A Complete Makefile Setup for Java". The setup uses the GnuMake syntax. As described in the html file:

"GnuMake is the default make system on the Linux platform, it is available
on all UNIX platforms, and a Microsoft Windows version can be downloaded
from here."

The directores are structured as follows:

	src/ 		source files (*.java, *.gif, *.tcl...)
	classes/	compiled files (*.classes, *.gif, *.tcl...)
	jars/ 		third-party jar files
	data/ 		simulation data files such as topology files
	script/ 	example/testing scripts
	make/ 		common makefile, make log...

Each sub-directory in $J_SIM/src corresponds to a Java package. Each java package needs a package makefile to be placed in the same directory. The makefile is basically a list of all the sources files in the package. Examples can be found in any directory.

Compile The Sources with "make"

At the J-Sim root directory or a sub-directory under src/, use: 
	make

to compile the sources; 

	make clean

to remove all the binary files. 

For details of setting up GNU-Make makefiles in Java, please refer to "A Complete Makefile Setup for Java".

Compile The Sources with "Apache Ant"

At the J-Sim root directory, use: 

	ant compile

to compile the sources; 

	ant clean

to remove all the binary files. 

The build file is at $J_SIM/build.xml.  For details of Apache Ant, please refer to http://ant.apache.org/.

~ END ~