Obtaining dependent libraries and programs for JSim
Introduction: what is needed
JSim version 2.03 and above require the main libraries and java
bindings from libSBML,
and the utility program sbtranslate from the Antimony package for full
functionality. This document describes how to obtain what you need from
those packages.
The core JSim program requires libsbml to perform its SBML/MML translations. This means that we need:
libsbml, the core C++ library;libsbmlj, the SWIG-based wrapper Java-to-C++ library; andlibsbmlj.jar, the java code that calls the SWIG library.
In addition, the Antimony program sbtranslate is used to
perform the Antimony/MML translation, as well as (potentially)
Antimony/MML/CellML translations. This is an external executable that
also uses libsbml internally, as well as (potentially) the CellML API.
Antimony binary distributions can also be used in any form, as long as
'sbtranslate' works. Again, if space is an issue, you may wish to
ensure that sbtranslate uses the same version of libsbml that you use
above. However, if the binary distribution of libsbml is being used,
this will not use the libsbml library at all (as it is statically linked
to libsbmlj instead), so it is not even necessary to ensure that the
version of libsbml being used is the same! If space is indeed an issue,
you'll need to compile from source, and at that point, you might as well
compile libsbml at the same time.
Extracting from binaries
Visit the libSBML home page, and follow the 'Download libSBML' link (which currently (September 2011) points to the 5.0.0 version). Assuming you are assembling binaries for distribution in the 'canonical' JSIMAUXLIB folders, you can get the two files you need (the libsbmlj library and the libsbmlj.jar file) from these distributions: follow the instructions for installation, and copy any of the libsbml.jar files (they should be functionally identical, if not actually identical) into $JSIMSRC/third/server/, and [libsbmlj.dll|libsbmlj.dylib|libsbmlj.so] into $JSIMAUXLIB/[win32|macos|linux]/.
Next, visit the Antimony home page, and download any binary installers you find there (there will almost certainly be one for Windows, there may be one for MacOSX, and there probably will not be one for linux). Again, follow the instructions provided, and find the 'sbtranslate' executable. Copy this and *all* associated libraries into $JSIMAUXLIB. Assuming the version you download works with CellML, this will include several different libraries for that (including libxml2), plus the libsbml library, plus (on windows) two dll's needed to work with Visual Studio-compiled programs. Assuming you downloaded the binaries for libsbml, the libsbml library provided here may be the same or it may be different from the other; it won't matter, as libsbmlj is completely self-contained.
Building from source
Assuming either that space is an issue, or that the above binaries do not work or are not provided on your platform, you may need to build things from source. This should actually be fairly straightforward, as libSBML, Antimony, and even the CellML API now use CMake as their build system.
The first step, then, is to obtain CMake for all platforms on which you wish to build from source. If it is not already available on your system, you can get it from cmake.org. libSBML requires CMake version 2.8.0 or higher.
Next, get the libsbml source from https://sourceforge.net/projects/sbml/files/libsbml/. As of this writing, the most recent was 5.0.0.
Unzip the file and cd into that directory. Now we need to change
the java bindings from linking to the static version to linking to the
dynamic version. Edit
[libsbml]/src/bindings/java/CMakeLists.txt and search for
'-static'. In 5.0.0, this line looked like:
target_link_libraries(binding_java_lib ${LIBSBML_LIBRARY}-static )
Delete the '-static' bit, so it looks like:
target_link_libraries(binding_java_lib ${LIBSBML_LIBRARY} )
The deal here is that the name of the static libsbml library is
'libsbml-static.a' and the name of the dynamic libsbml library is
'libsbml.so' (or whatever)--deleting '-static' will make it look for the
dynamic one. This will save space, but will require that you always
update both libsbml and sbtranslate at the same time in the future
Next, we need a few programs and libraries: SWIG, and an XML parser--I went with 'expat'; other options are 'libxml' and 'xerces'. As of this writing, a bug in the CellML API makes using CellML and libsbml-with-libxml together impossible, so if a goal is to use sbtranslate's CellML translation capabilities, you should use expat or xerces.
SWIG came pre-installed on most systems on which I tested, but version 1.3.31 (which came on baggins) had a bug in it that prevented compiling ('buffer overflow error'); the more recent 2.0.3 worked fine for me. I compiled it from source; the only warning here is that it will also need something called 'pcre', available from ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/. 'Configure' in the SWIG directory gave me easy-to-follow directions; I downloaded PCRE into the SWIG working directory, then ran, from that directory, Tools/pcre-build.sh and this configured and compiled pcre. Then I ran 'configure', 'make', and 'make install' from that same directory to get SWIG up and running, with
configure --prefix=/User/lpsmith/swig/so it would compile into where I wanted it.
One word of caution here: If you want to be able to use a single libsbml.jar file, you will need the same version of SWIG everywhere you build. Otherwise, the bindings can end up being different from one another. So I would recommend going with 2.0.3 (or whatever the latest is) on all three systems.
expat and libxml came preinstalled on baggins; the only issue is that it's a dynamic library so you'd have to bundle it up with everything else. If you wanted to compile it static and link that into libsbml instead, you'd have one less file to deal with in distributing.
Building libsbml
So! Assuming you have all that, we're ready to compile. We're going
to run cmake--if you're in a console window you'll want to run
'ccmake' (cmake for consoles); if you're actually at the
computer in question, you can run 'cmake-gui' which is
prettier and has a slightly better UI.
In any event, cd into the libsbml directory (libsbml-5.0.0/, *not* libsbml-5.0.0/src/), then create a new directory in which to build; I usually use the creative name 'build':
cd libsbml-5.0.0/; mkdir build; cd buildThen from that working directory, run ccmake or cmake-gui with the argument '..' for 'up one directory':
cmake-gui ..(you're pointing at the root 'CMakeLists.txt' file)
Now hit the 'configure' button (cmake-gui) or 'c' (ccmake) and it'll churn a bit and make you a list of options. If you're on Windows, it'll ask which type of build system you want to use--I tend to use Visual Studio for my projects, but cygwin is also available, if you have that installed. For me, using ccmake on baggins, I see:
CMAKE_BUILD_TYPE *Release CMAKE_INSTALL_PREFIX */usr/local CMAKE_OSX_ARCHITECTURES * CMAKE_OSX_DEPLOYMENT_TARGET * CMAKE_OSX_SYSROOT */Developer/SDKs/MacOSX10.5.sdk ENABLE_LAYOUT *OFF ENABLE_UNIVERSAL *OFF EXTRA_LIBS * LIBBZ_INCLUDE_DIR */usr/include LIBBZ_LIBRARY */usr/lib/libbz2.dylib LIBXML_INCLUDE_DIR */usr/include/libxml2 LIBXML_LIBRARY */usr/lib/libxml2.dylib LIBZ_INCLUDE_DIR */usr/include LIBZ_LIBRARY */usr/lib/libz.dylib SWIG_EXECUTABLE */usr/bin/swig WITH_BZIP2 *ON WITH_CHECK *OFF WITH_CPP_NAMESPACE *OFF WITH_CSHARP *OFF WITH_DOXYGEN *OFF WITH_EXAMPLES *OFF WITH_EXPAT *OFF WITH_JAVA *OFF WITH_LIBXML *ON WITH_MATLAB *OFF WITH_OCTAVE *OFF WITH_PERL *OFF WITH_PYTHON *OFF WITH_RUBY *OFF WITH_SWIG *ON WITH_XERCES *OFF WITH_ZLIB *ONwith instructions on how to change these at the bottom. In the GUI, all the 'ON/OFF' options are check marks. We do indeed want to change some of the options here: from the top:
The first thing you probably should do is change the compiler from 'c++' to 'g++', since that's more likely to be what was used for other projects. So switch to the 'advanced view'--this is a button in the GUI, and the 't' button (for 'toggle') in ccmake. Find CMAKE_CXX_COMPILER and switch it to g++ (probably /usr/bin/g++) and hit 'compile' again. (When you change the compiler, all the other options get reset, so we have to do this first).
Next, if you're on a 64-bit system, you'll need to compile to a 32-bit architecture to be compatible with the rest of JSim. To do this, you'll again need to be in the 'advanced view'. Find 'CMAKE_CXX_FLAGS' and add '-m32', and find 'CMAKE_C_FLAGS' and add '-m32' there, too. (Note: if you compiled libexpat yourself, you'll need to do the same thing there. I edited the Makefile after running 'configure' and just added '-m32' to all the various CFLAGS and CXXFLAGS.) After changing these options, my ccmake screen here looks like:
CMAKE_AR /usr/bin/ar CMAKE_BUILD_TYPE Release CMAKE_COLOR_MAKEFILE ON CMAKE_CXX_COMPILER /usr/bin/g++ CMAKE_CXX_FLAGS -m32 CMAKE_CXX_FLAGS_DEBUG -g CMAKE_CXX_FLAGS_MINSIZEREL -Os -DNDEBUG CMAKE_CXX_FLAGS_RELEASE -O3 -DNDEBUG CMAKE_CXX_FLAGS_RELWITHDEBINFO -O2 -g CMAKE_C_COMPILER /usr/bin/gcc CMAKE_C_FLAGS -m32 CMAKE_C_FLAGS_DEBUG -g CMAKE_C_FLAGS_MINSIZEREL -Os -DNDEBUG CMAKE_C_FLAGS_RELEASE -O3 -DNDEBUG CMAKE_C_FLAGS_RELWITHDEBINFO -O2 -gAfter you've done this, toggle back to the regular view.
Next, set CMAKE_INSTALL_PREFIX to where you want libsbml installed. I tend to use '../install', which will build it in [libsbml]/install/
If your installed version of SWIG is old, you'll need to change 'SWIG_EXECUTABLE' to the version you compiled. For me, this was /Users/lpsmith/swig/bin/swig
Since space is an issue, we're going to turn off the automatic reading of .zip and .bz files: turn off both WITH_BZIP2 and WITH_ZLIB.
If you're compiling on a mac and want universal binaries (which you probably do), set ENABLE_UNIVERSAL to ON.
To get the java bindings, turn on WITH_JAVA. (note: 'WITH_SWIG' is required if you want Java; it's on by default and you can and should leave it on.)
There are three options for using a particular xml library: WITH_LIBXML, WITH_EXPAT, and WITH_XERCES. Exactly one of these should be turned on, and the other two should be turned off. By default, WITH_LIBXML is on, but CellML also uses libxml in a way that's incompatible with libsbml's use of it, so if you want CellML translation, turn that off, and turn on either expat or xerces. For me, this was 'WITH_EXPAT'.
Now hit the Configure button (or 'c') again. This will pop up new options if you changed the xml parsing library, namely, the directory where it found it. For me when compiling on linux, it found expat installed, but I went ahead and changed it to a version I compiled myself:
LIBEXPAT_INCLUDE_DIR /user3/lpsmith/expat/include LIBEXPAT_LIBRARY /user3/lpsmith/expat/lib/libexpat.soIt will also find SWIG_DIR and SWIG_VERSION based on the version of SWIG_EXECUTABLE you set.
f you're on a mac, you'll also want to change CMAKE_OSX_ARCHITECTURES. JSim doesn't handle 64-bit yet, and jbb is moving away from his ppc, so for now we only need the i386: delete the amd64 and ppc option and just leave 'i386'. This kind of defeats the purpose of the 'ENABLE_UNIVERSAL' option, but I'd use it anyway as it's more explicit--if you don't, you might end up with a 64-bit version.
Hit 'configure' again, and if there are no further issues, you will now be able to hit 'g'/the 'Generate' button. If no such option appears, try hitting 'configure' again and looking for unset variables you think sound important. My final version on a mac looked like:
CMAKE_BUILD_TYPE Release CMAKE_INSTALL_PREFIX ../install CMAKE_OSX_ARCHITECTURES i386; CMAKE_OSX_DEPLOYMENT_TARGET CMAKE_OSX_SYSROOT /Developer/SDKs/MacOSX10.5.sdk ENABLE_LAYOUT OFF ENABLE_UNIVERSAL ON EXTRA_LIBS LIBBZ_INCLUDE_DIR /usr/include LIBBZ_LIBRARY /usr/lib/libbz2.dylib LIBEXPAT_INCLUDE_DIR /usr/include LIBEXPAT_LIBRARY /usr/lib/libexpat.dylib LIBXML_INCLUDE_DIR /usr/include/libxml2 LIBXML_LIBRARY /usr/lib/libxml2.dylib LIBZ_INCLUDE_DIR /usr/include LIBZ_LIBRARY /usr/lib/libz.dylib SWIG_DIR /Users/lpsmith/swig/share/swig/2.0.3 SWIG_EXECUTABLE /users/lpsmith/swig/bin/swig SWIG_VERSION 2.0.3 WITH_BZIP2 OFF WITH_CHECK OFF WITH_CPP_NAMESPACE OFF WITH_CSHARP OFF WITH_DOXYGEN OFF WITH_EXAMPLES OFF WITH_EXPAT ON WITH_JAVA ON WITH_LIBXML OFF WITH_MATLAB OFF WITH_OCTAVE OFF WITH_PERL OFF WITH_PYTHON OFF WITH_RUBY OFF WITH_SWIG ON WITH_XERCES OFF WITH_ZLIB OFFNote that it doesn't matter that LIBBZ_LIBRARY etc. are set: since 'WITH_BZIP2' is off, it won't use it. If you didn't have it on your system and it's set to something like NOTFOUND this is OK.
After you've generated output, you'll then have Makefiles in your build/ directory. If you configured it for Visual Studio, you can load it up there; otherwise, you'll probably want to type 'make' now. If you want to see what's going on, type:
make VERBOSE=trueIf you leave off the VERBOSE bit, it'll still work, just be more mysterious.
Finally, install!
make installand it'll put it in ../install or wherever you pointed it!
For Windows/visual studio, the above instructions can still be followed. The only thing to keep in mind is that once you are in VS, you'll need to change the project to 'Release' yourself, since by default it'll always come up 'Debug'. Hitting 'build' will build everything, and building the INSTALL target will install it.
The files we will actually need in JSim are three:
[install]/share/libsbml/bindings/java/libsbmlj.jar [install]/share/libsbml/bindings/java/libsbmlj.dylib (or .so or .dll) [install]/lib/libsbml.dylib (or .so or .dll)Note that on a Mac, the 5.0.0 CMake build would create bindings/java/libsbmlj.dylib, but this was changed in svn (so presumably for all future versions of the library) to create bindings/java/libsbmlj.jnilib It is the exact same file, and it is fine if you rename one to the other.
The .jar file goes in [JSim]/third/server/
And the other two go in [jsimauxlib]/[system]/
You'll need to re-run jsbuild.j to get the new .jar file (I think) and after that, you're good to go!
Building sbtranslate (Antimony)
Instructions for building sbtranslate are available on Antimony's website: http://antimony.sourceforge.net/antimony-installation.html. You should already have everything you need from building libsbml, with the exception of the CellML SDK. I'm not going to try to tell you how to build CellML here, because that's too complicated. My advice is to try downloading the SDK for your platform, and if it works, great, and if not, turn off Antimony's ability to translate CellML (by turning off 'WITH_CELLML' in CMake). If I recall correctly, the current version of JSim doesn't even attempt to use sbtranslate to translate CellML anyway.
A few other things of note:
- Point LIBSBML_INCLUDE_DIR to wherever you installed libsbml/include/
- Point LIBSBML_LIBRARY to wherever you installed libsbml/lib/libsbml.[whatever]
- Point CELLML_API_INSTALL_DIR to wherever you copied the CellML SDK.
- You don't need WITH_COMP_SBML, WITH_QTANTIMONY, WITH_SBW, or WITH_SBW_TRANSLATOR: turn all of these off.
Once you build sbtranslate, you'll need to put that plus all its
dependencies into [jsimauxlib]/[system]/. The dependencies
are:
- sbtranslate
- libantimony
- libsbml (which should already be there)
- If you have included CellML:
- libannotools
- libceleds
- libcellml
- libcevas
- libcuses
- libmalaes
- libtelicems
That's it!
[This page was last modified 29Sep11, 3:35 pm.]
Model development and archiving support at physiome.org provided by the following grants: NIH/NIBIB BE08407 Software Integration, JSim and SBW 6/1/09-5/31/13; 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.
