This page will look better in a graphical browser that supports web standards, but is accessible to any browser or internet device.

-->

Building JSim From Source

Introduction

This page describes how JSim source code is structured, and how to build a JSim binary distribution from that source code. JSim source code may currently be obtained in two ways: the JSim open source distribution or the NSR CVS archive. The latter is available only to NSR collaborators. There are minor differences in the build procedure depending upon which method of source code access you use, which are noted in this document. Use of JSim source code must be in accordance with the LICENSE file found in the distribution root directory.

NOTE: This document is currently undergoing changes related to the upcoming shared source distribution (version 1.6.70).

Contents:

Version numbers:

JSim version numbers are of the form 1_6_## for public and beta releases and 1_6_##alpha# for alpha (highly preliminary) releases, where the # are integers. All copies of public and beta releases should be built from identical source, however alpha releases may vary depending on which developer was working on the code. Bug reports should only be sent for public and beta releases.

Source distribution contents:

Contents of OS specific directories. When multiple chip-architectures are supported for an OS, these files may be repeated for each architecture:

Building the complete JSim source distribution:

The following build process assumes you have a Unix-like environment with C and Fortran compilers, the make utility, with Sun's java developer kit. Amoung JSim platforms, this assumption is violated only by Windows . Here JSIMOS will refer to the appropriate operating system (linux, macos, win32), JSIMARCH will refer to the hardware architecture (i386, amd64, ia64, ppc). Java SDK, make, gcc and gfortran are expected to be available. Versions used for NSR binary distributions are:

Set environment variables:

Customize makefiles:

Build JSim via "jsbuild.all":

If you have CVS access, you may also build the fpack models via jsbuild.fpack. There will be some warning messages which have not caused any known problems.

Native libraries created during a JSim build are placed in an architecture specific directory in $JSIMSRC/NATIVE. This directory will be named either OS or OS_ARCH when OS is the operating system, and ARCH is the hardware architecture.

$JSIMSRC/build contains debug versions of the JSim programs jsim, jsbatch, jsfim and jsserver, each with the suffix .db. These versions should run correctly after a successful build.

On Macintosh, a single jsbuild.all will create either macos_i386 or macos_ppc, depending upong the local architecture. To create macos fat (universal i386 + ppc) libraries run jsbuild.all twice, once on each architecture, and place both macos_i386 and macos_ppc in $JSIMSRC/NATIVE. Then run jsbuild.fat to create the fat libraries in $JSIMSRC/NATIVE/macos. Set shell variable JSIMFAT=yes to allow the .db programs to access the fat libraries.

Creating a JSim Binary Distribution

This section describes creating a JSim binary distribution .zip file, which allows you to distribute your JSim build (see previous section) to others. Such distributions must be in accordance with license terms (above).

Examine jsbuild.osarch to determine the appropriate OSARCH strings for your distribution, e.g. linux_i386, linux_amd64, linux_ia64, macos, macos_i386, macos_ppc, win32.

Find the jre.notes file appropriate for your OSARCH and make sure a corresponding jre.zip exists in the same directory. This step is not required for:

  1. Macintosh distributions, which use the OS's built-in JRE;
  2. those with NSR CVS access, since the appropraite jre.zip is part of the CVS archive.

Run "jsdist.bin OSARCH". This will create a new .zip file in $JSIMSRC/DIST named for the JSim version number and OSARCH.

The JSim Verification Suite

$JSIMSRC/VERIFY contains verification scripts for JSim computations. See instructions in that directory. Run ". jsverify.env src" before running verify scripts to verify the debug version, or ". jsverify.env $JSIMHOME" to verify a binary distribution.

This suite is currently available only to those with NSR CVS access. In the future, we hope to provide an open source version of this suite, however it is not ready for prime time yet.

Debugging Tips

Since JSim is a complex multi-language and multi-threaded application, step-by-step program tracing has fairly limited utility. Most debugging here at NSR is done with the insertion of print and stack dump commands in appropriate code. Nevertheless, debuggers can be of use. The following is an example of a jdb session used to find the source of an infinite loop: 

      bash
      . jsbuild.path
      jdb $JSIMARGS
      run JSim.gui.GLaunch -f problem.proj
      ... interact with GUI to cause infinite loop ...
      threads       // list running threads
      suspend 0x65  // name of suspect thread
      where 0x65

Building JSim Native Libraries Only

This section is for the NSR JSim distributions administrator only.

JSim distribution from NSR use archived native libraries for win32 and macos. These libraries must be remade and rearchived whenever changes are made to files in the JSim/nonJava directory. The process is outlined below, with special notes for each operating system following:

Notes for Windows

JSim development under Windows requires the the GNU/Cygwin tools. cygwin.dll is GPL'ed, so the JSim native libraries are created using -mno-cygwin switch to prevent linking to it. Since Sun's SDK is a native windows application, which doesn't utilize cygwin, it is awkward to use existing build scripts to build the java classes.

[This page was last modified 03Mar08, 3:11 pm.]

Model development and archiving support at physiome.org provided by the following grants: NIH/NHLBI T15 HL88516-01 Modeling for Heart, Lung and Blood: From Cell to Organ, 4/1/07-3/31/11; NSF BES-0506477 Adaptive Multi-Scale Model Simulation, 8/15/05-7/31/08; NIH/NHLBI R01 HL073598 Core 3: 3D Imaging and Computer Modeling of the Respiratory Tract, 9/1/04-8/31/09; as well as prior support from NIH/NCRR P41 RR01243 Simulation Resource in Circulatory Mass Transport and Exchange, 12/1/1980-11/30/01 and NIH/NIBIB R01 EB001973 JSim: A Simulation Analysis Platform, 3/1/02-2/28/07.