1. Setting your library search path

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.

How to configure most Linux platforms

There are two common approaches to solving the problem under Linux.

Using 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.
Setting environment variables: Ensure that each user sets the environment variable 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. If you built libSBML yourself using CMake, the path consists of /lib appended to the value used for the CMAKE_INSTALL_PREFIX configuration variable. If you built libSBML using GNU make, the path is DIR/lib, where DIR is the value used for the configuration option --prefix=DIR.
For example, suppose you used the default installation prefix /usr/local/. 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
```

How to configure Microsoft Windows platforms:

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.

2. Linking with or importing libSBML

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.

C++ and C

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=DIR option (if you used configure 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:

The flag -IDIR/include needs to be supplied to the compiler. In addition, it may be necessary to supply a second -I flag with the directory containing the include files of the XML parser being used by libSBML. For example, if you are using the Xerces XML parser and you compiled and installed Xerces in /usr/local, then when compiling your software to use libSBML, you will also need to add the flag -I/usr/local/include.
The flags -LDIR/lib -lsbml -lstdc++ -lm need to be supplied to the compiler or linker. In addition, you may need to supply a corresponding -L flag value to tell the linker where to find the XML parser library being used by libSBML.

If you have the pkg-config utility, the steps above can be substantially simplified. First, make sure that your 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 with the --cflags and/or --libs flags in your compilation/linking command. Here is an example:

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 pkg-config --cflags --libs libsbml and substituting in place the flags returned by the command.

C#

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;

Java

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.

Step 1: (maybe) set the run-time library search path

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 to the directory containing the libSBML library files. (This directory is the one containing the .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)

Step 2: set your application's Java class search path

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:

Java on Linux, Mac OS X and similar Unix-like systems:
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 option passed to the Java interpreter when it is started. As an example of the former approach, if you had configured libSBML to be installed into /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
```
Java on Windows systems:
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

Step 3: load the libSBML JNI library in the application

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);
    }
  }

}

JavaScript

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 environment variable to the location of where the libSBML module is installed. The value of NODE_PATH depends on the installation directory used during the libSBML configuration step. If you built libSBML yourself using CMake, the path is /lib/node appended to the value used for the CMAKE_INSTALL_PREFIX configuration variable. If you built libSBML using GNU make, the path is DIR/lib/node, where DIR is the value used for the configuration option --prefix=DIR. Once the NODE_PATH environment variable is set, Node.js should be able to access the libSBML module very simply as in the following example:

var sbml = require('sbml')

Alternatively, if setting the environment variable NODE_PATH is inconvenient, you can supply a full path to the Node require statement to load the libSBML module:

var sbml = require('/usr/local/lib/node/sbml')

MATLAB

The instructions for MATLAB depend on the operating system you are using.

MATLAB on Linux, Mac OS X and similar Unix-like systems

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.

MATLAB on Windows systems

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:

Start MATLAB.
Within MATLAB, change directory to the directory in your libSBML source tree containing the MATLAB code. This directory will be libsbml/src/bindings/matlab, where libsbml is the root of your libSBML source directory on your computer.
Execute buildSBML in MATLAB.
Execute 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.

Python

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 used a libSBML Python installer

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 *

If you did not use an installer

In this case, libSBML must first be configured, compiled and installed as described in the building instructions. Once that is done, your Python interpreter will need one more thing to find libSBML: a correctly set 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 option given during configuration of libSBML (the default value is /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/libsbml

If 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.

R

As described in the downloading instructions, we provide ready-built installers for the libSBML R language interface that you can download from our GitHub 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.

Using the R GUI: In the R menu "Packages" or "Packages & Data" (depending on your operating system), select the "Package Installer" item. You will be presented with an interface that lets you install a local binary package. Use the interface to navigate to the directory where you copied the libSBML archive file, and select the archive file for installation.
Using a shell command: Suppose that the path to the libSBML R archive on your computer is archive. Execute the following command in a terminal/shell window (note: not in the R command line interpreter!):
```
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.

Table of Contents