libSBML C++ API
5.18.0
|
Once the libSBML files are installed, you may need to take additional steps so that software applications can find the libSBML library files at run time. This section provides information about how to do that.
Installing libSBML puts copies of the libSBML native object files in
appropriate destinations on your computer. (By "native object files", we
mean files such as libsbml.so
, libsbml.5.dylib
,
libsbml.dll
, etc.) On Mac OS X, this should be
enough; a software application should be able to find the libSBML library
file(s) when it runs. On Linux and Windows, that may not be enough to let a
software application find the libSBML library files—you may need to
take additional steps. This may be the case even if your application can
find other libSBML components such as the language-specific interface
(e.g., the libSBML JAR file in the Java case, or the libsbml.py
file in the Python case).
If your run-time environment and the run-time environment for your software applications do not know to look in the directory where libSBML was installed, programs that require libSBML will fail to run and report errors about being unable to find libSBML.
There are two common approaches to solving the problem under Linux.
ldconfig
: Run the program ldconfig
as user 'root' on your computer. (Please consult the man page for
ldconfig
if this is unfamiliar.) This will configure the system
for all users.LD_LIBRARY_PATH
in their terminal shells.
If you downloaded a ready-to-run libSBML installer, the default where the
libSBML library is installed is /usr/local/lib
/lib
appended to the value used for the
CMAKE_INSTALL_PREFIX
/lib
--prefix=
DIR For example, suppose you used the default installation prefix
. Then in csh-based command shells
under Linux, you may have to set the variable as follows (perhaps in your
.cshrc
file):
setenv LD_LIBRARY_PATH /usr/local/lib
Set the PATH
environment variable to include the
directory of the libSBML native library. To set an environmental variable
in Windows, use the System option in the Windows Control
Panel.
Once your library search path is configured so that processes on your computer can find the libSBML library files, the last step is to link or import libSBML into your software application. Different steps apply to different interface languages.
Compiling C++ or C software to use libSBML is usually a matter of
supplying certain options during compilation and linking. Let DIR stand for the directory used during the libSBML configuration step as the value
of the --prefix=
DIRconfigure
to configure libSBML) or
CMAKE_INSTALL_PREFIX
(if you used CMake). There are two main sets of settings
on Unix-like systems such as Linux:
-IDIR/include
-I
/usr/local
, then when compiling your software to use libSBML,
you will also need to add the flag
-I/usr/local/include
-LDIR/lib -lsbml
-lstdc++ -lm
-L
If you have the pkg-config
PKG_CONFIG_PATH
environment variable includes the path to
the directory DIR/lib/pkgconfig
(which is the
directory where the file libsbml.pc
will be installed by
libSBML's make install
step). Then, you can run
pkg-config
--cflags
--libs
g++ `pkg-config --cflags --libs libsbml` myprogram.cpp
Note the use of the backward quote in the shell command above; it
has the effect of running the command
and substituting in place the flags returned by
the command.
The C# interface for libSBML is implemented partly as pure C# and partly
as native code. To use it in an application, an additional step must be
performed after libSBML is installed and the your library search path is set
as described above. The step is to place the managed library
libsbmlcsP.dll
into your application's directory.
C# applications need to be compiled by referencing the managed library
libsbmlcsP.dll
. This will also copy this managed library into
the application's output directory. Once the managed library is referenced,
and the native library can be found in the PATH
(or, on Windows
systems, if it is in the same directory as the executable), the C# bindings
can be used in any .Net language program by simply including the libSBML
namespace. The following C# code fragment illustrates how to use the
namespace:
using namespace libsbml;
The Java interface for libSBML is implemented partly as pure Java and partly as Java Native Interface (JNI) code. To use it in an application, additional steps must be taken after libSBML is installed on your computer.
If you used the binary installers we provide for libSBML, or configured
your system's library search path manually, applications should be able to
find the libSBML library files at run time. If this is not the case, you can
explicitly tell your Java interpreter where to find libSBML by setting the
flag -Djava.library.path
.jnilib
, .dylib
and/or .dll
files
for libSBML, depending on the operating system—not the JAR
file.)
For example, suppose that you configured libSBML to be installed into
/usr/local
on a Linux system. Then, you could start your
application using a command that begins as follows:
java -Djava.library.path=/usr/local/lib -cp .:/usr/local/share/java/libsbmlj.jar APPLICATION
If the library search path is not set correctly, applications
will encounter a java.lang.UnsatisfiedLinkError
at run time when
they attempt to call System.loadLibrary("sbmlj")
(discussed in
Step 3 below). Here is an example of such an error message printed by
the Java interpreter:
Exception in thread "main" java.lang.UnsatisfiedLinkError: no libsbmlj in java.library.path at java.lang.ClassLoader.loadLibrary(ClassLoader.java:1764) at java.lang.Runtime.loadLibrary0(Runtime.java:823) at java.lang.System.loadLibrary(System.java:1044) at test.(test.java:31)
Java applications separately also need to have their
class search paths set up such that they include the libSBML
.jar
file. This is often most easily done by setting the
CLASSPATH
environment variable, but other methods are possible.
The exact recipe also depends on the operating system in use, as follows:
You must either (1) set your
CLASSPATH
environment variable to include the .jar
file, or (2) the libSBML .jar
file must be listed in the
-classpath
/usr/local
, the
libsbmlj.jar
file will end up as
/usr/local/share/java/libsbmlj.jar
on Linux and
Mac OS X and your environment variable would at minimum need to be
set as follows:
CLASSPATH=.:/usr/local/share/java/libsbmlj.jar
The instructions are essentially the same as
for the case of Linux and similar systems, although the syntax for setting
environment variables is slightly different. For example, if you had
installed libSBML into C:\libsbml
on your system, you might set
your environment variable as follows:
CLASSPATH=.;C:\libsbml\libsbmlj.jar
Note: to set an environmental variable in Windows, use the System option in the Control Panel.
If the Java class search path is not set, then your application
will encounter a java.lang.ClassNotFoundException
error at run
time when it first attempts to access a libSBML class. Here is an example
of such an error message:
Exception in thread "main" java.lang.NoClassDefFoundError: org/sbml/libsbml/XMLOutputStream at test.main(test.java:15) Caused by: java.lang.ClassNotFoundException: org.sbml.libsbml.XMLOutputStream at java.net.URLClassLoader$1.run(URLClassLoader.java:202) at java.security.AccessController.doPrivileged(Native Method) at java.net.URLClassLoader.findClass(URLClassLoader.java:190) at java.lang.ClassLoader.loadClass(ClassLoader.java:306) at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:301) at java.lang.ClassLoader.loadClass(ClassLoader.java:247) ... 1 more
Finally, because of how JNI works in Java, an explicit call to
System.loadLibrary
is needed in an application to load the
native language library portion of libSBML. This involves putting a Java
static
block of code somewhere in your application, usually in
the application's main class. The following is an example of the minimum
code for doing this:
import org.sbml.libsbml.*;
public class YourMainApplicationClass
{
public static void main (String[] args)
{
/* Whatever your application does here ... */
}
/**
* The following static block is needed in order to load the
* libSBML Java interface library when the application starts.
*/
static
{
System.loadLibrary("sbmlj");
}
}
For real applications, it is often useful to catch run-time exceptions and try to interpret the causes on users' behalf. The following is a more elaborate example of code to load libSBML that tries to catch exceptions at run-time, interpret their meaning, and provide informative error messages about their causes. (Note that the following is an entirely optional replacement for the simpler version above.)
import org.sbml.libsbml.*; public class YourMainApplicationClass { public static void main (String[] args) { /* Whatever your application does here ... */ } /** * The following static block is needed in order to load the * libSBML Java interface library when the application starts. */ static { try { System.loadLibrary("sbmlj"); // For extra safety, check that the jar file is in the classpath. Class.forName("org.sbml.libsbml.libsbml"); } catch (UnsatisfiedLinkError e) { System.err.println("Error encountered while attempting to load libSBML:"); System.err.println("Please check the value of your " + (System.getProperty("os.name").startsWith("Mac OS") ? "DYLD_LIBRARY_PATH" : "LD_LIBRARY_PATH") + " environment variable and/or your" + " 'java.library.path' system property (depending on" + " which one you are using) to make sure it list the" + " directories needed to find the " + System.mapLibraryName("sbmlj") + " library file and" + " libraries it depends upon (e.g., the XML parser)."); System.exit(1); } catch (ClassNotFoundException e) { System.err.println("Error: unable to load the file 'libsbmlj.jar'." + " It is likely that your -classpath command line " + " setting or your CLASSPATH environment variable " + " do not include the file 'libsbmlj.jar'."); e.printStackTrace(); System.exit(1); } catch (SecurityException e) { System.err.println("Error encountered while attempting to load libSBML:"); e.printStackTrace(); System.err.println("Could not load the libSBML library files due to a"+ " security exception.\n"); System.exit(1); } } }
The libSBML JavaScript interface is currently only designed to be used
with Node.js. After you
have installed libSBML on your system, you may need to perform one more step
to enable you and your users to access libSBML from Node.js: inform Node.js
where to find the libSBML module. One approach to doing this is to set the
NODE_PATH
NODE_PATH
/lib/node
CMAKE_INSTALL_PREFIX
/lib/node
--prefix=
DIRNODE_PATH
var sbml = require('sbml')
Alternatively, if setting the environment variable
NODE_PATH
require
statement to load the libSBML module:
var sbml = require('/usr/local/lib/node/sbml')
The instructions for MATLAB depend on the operating system you are using.
The installation directory is also the same one where the additional
files TranslateSBML
.extension,
OutputSBML
.extension and CheckAndConvert.m
will have been placed. These files implement the MATLAB interface to
libSBML. On Linux and Unix-based systems including Mac OS X, the
LD_LIBRARY_PATH
/DYLD_LIBRARY_PATH
environment
variable may need to be set in the terminal shell from which MATLAB is
started prior to starting MATLAB. (Otherwise, MATLAB itself will not "see"
the value of the variable.)
Important: some versions of MATLAB produced for Linux include a version of the stdc++ library that conflicts with the version provided by the operating system, causing a mystifying error when MATLAB tries to run or compile code involving libSBML. Please see the section in the Known Issues document for more information.
An additional step is necessary in the MATLAB environment itself:
adding the same directory to the list of directories that MATLAB searches
to find functions. If DIR is the
directory where the libSBML shared library as well as
TranslateSBML
.extension,
OutputSBML
.extension, and
CheckAndConvert.m
have been installed, then the following
MATLAB command must be executed:
addpath('DIR');
For example, suppose you are using an Intel-based Mac OS X system
and you have configured libSBML to install itself into
/usr/local
. Then the files
TranslateSBML.mexmaci
, OutputSBML.mexmaci
and CheckAndConvert.m
will have been installed as
/usr/local/lib/TranslateSBML.mexmaci
,
/usr/local/lib/OutpuSBML.mexmaci
and
/usr/local/lib/CheckAndConvert.m
. You will need to set
your DYLD_LIBRARY_PATH
environment variable to
/usr/local/lib
, and also execute the following command
(or an equivalent) in MATLAB:
addpath('/usr/local/lib');
To save the trouble of having to type the command above each
time you start MATLAB, you may wish to put it in your
startup.m
file (i.e., the file MATLAB uses for user
initialization). Please refer to the MATLAB documentation for more
information about startup.m
and where it is located.
Most Windows users will probably prefer to install libSBML using the
self-extracting installer provided separately and available for downloading
from the same servers as the libSBML source code distribution. The
installer will take care of placing the MATLAB files in directories where
MATLAB can find them. Nothing further needs to be done in that case. You
should be able to start MATLAB at will, and be able to invoke functions
like TranslateSBML
and OutputSBML
.
If you are compiling and installing libSBML from the sources, or else want/need to install the MATLAB bindings directly from the libSBML source distribution on Windows, follow these simple steps:
libsbml/src/bindings/matlab
, where
libsbml
is the root of your
libSBML source directory on your computer.
buildSBML
in MATLAB.
installSBML
in MATLAB.
After these steps, you should be able to invoke functions such as
TranslateSBML
and OutputSBML
. These will be
accessible after you restart MATLAB and even when you are no longer in the
libSBML directory.
As described in the downloading
instructions, we provide three ways for you to get the libSBML Python
language interface easily without having to configure and build libSBML
manually from sources. You can use (1) PyPI, the Python Package Index; (2)
binary packages for use with standard Linux installation tools such as
yum
and apt-get
; or (3) executable installers for
Windows.
If you downloaded one of the ready-to-use Python installers for libSBML, you should not need to do anything more: you should be able to access libSBML from your Python interpreter by importing it like any other Python module. In other words, the following should work:
from libsbml import *
PYTHONPATH
environment variable. To cope with the fact that different Unix-like systems
(including Mac OS X) use different conventions for where they
install Python modules, the following is a general-purpose setting for
PYTHONPATH
. Here, DIR
represents the value of the --prefix=
DIR/usr/local
) and
version is the version of your copy of
Python (this might be, e.g., 2.7
). If you use sh-based
shells such as Bash, put this in your shell's initialization file or execute
it in your shell before starting the Python interpreter:
PYSITE=DIR/lib/version/site-packages PYDIST=DIR/lib/version/dist-packages export PYTHONPATH=$PYTHONPATH:$PYSITE:$PYSITE/libsbml:$PYDIST:$PYDIST/libsbmlIf you use csh-based shells instead of Bash or other sh-based shells, then the appropriate syntax is the following:
set PYSITE = DIR/lib/version/site-packages set PYDIST = DIR/lib/version/dist-packages setenv PYTHONPATH ${PYTHONPATH}:${PYSITE}:${PYSITE}/libsbml:${PYDIST}:${PYDIST}/libsbml
Once the PYTHONPATH
variable has been set, you should be
able to start the Python interpreter and type the following command to
import the libSBML package for Python:
from libsbml import *
If Python produces an import error or a failure in linking a new module, it
probably means that PYTHONPATH
has not been set correctly.
It may also mean that the read/write permissions of the installed library
files or a directory in the hierarchy containing them are such that you are
not allowed to access the files. In that case, please consult your systems
administrator or (if you have administrator priviledges) reset the
permissions yourself.
As described in the downloading instructions, we provide ready-built installers for the libSBML R language interface that you can download from our SourceForge download page. If you use one of the installers, you do not need to do anything more to set up and use libSBML for R on your system.
Alternatively, you can also build the R bindings yourself following the compilation instructions. If you do, make sure to configure your CMake or GNU make build with the option to enable the libSBML R interface. Following the build, one more step is required to make your R installation find the libSBML interface: you must invoke a command in R, supplying it with the path to this archive file. You can do this in one of two ways: either using the R graphical interface, or a shell command.
R CMD INSTALL archive
In the command above, R
is the executable for the
command-line version of R; we assume it is accessible from your shell's
command line, but if it is not accessible by simply typing R
, you
may need to supply the full path to R
.
From this point forward, you should be able to call on libSBML functions from within your copy of R. You can test whether the installation was successful by trying the following command in R:
library('libSBML')
If R does not report an error when you execute this command, then the libSBML R interface is probably installed correctly.