Once the libSBML files are installed as described in the installation instructions, you may need to do additional configuration steps so that software applications can find the libSBML library files at run time. This section provides information about how to do that.

Run-time environment configuration
Compiling software to use libSBML
- C++ and C
- Java
- Python
- MATLAB
- C#
- Ruby
- Perl
- Octave

1. Run-time environment configuration

Whether you downloaded a ready-built libSBML installation, or you followed the installation instructions, copies of the different libSBML files will end up in appropriate destination directories on your computer. However, this does not necessarily guarantee that a given software application will be able to find those files when it runs. The run-time environment must be properly configured first.

On most Linux/Unix-based platforms:

Either do the following:

Unless using Mac OS X systems, run the program ldconfig as user 'root'. (Please consult the man page for ldconfig if this is unfamiliar. On Mac OS X, there is no equivalent to the ldconfig facility.)

or do the following:

Ensure that each user sets the environment variable LD_LIBRARY_PATH in their command shells. (On Mac OS X, the variable is named DYLD_LIBRARY_PATH.) The value of LD_LIBRARY_PATH or DYLD_LIBRARY_PATH must include the directory DIR used as the value of the --prefix=DIR option used during the libSBML configuration step. For example, suppose that you configured libSBML to use the default installation prefix /usr/local/. Then in csh-based command shells under Linux, if the ldconfig step is not performed, you may have to set the variable as follows (perhaps in your .cshrc file):
```
setenv LD_LIBRARY_PATH /usr/local/lib
```

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

If your run-time environment and the run-time environment for your software applications do not know to look in the installation directory for libSBML, programs that require libSBML will fail to run and report errors about being unable to find libSBML.

2. Compiling software to use libSBML

If you configured libSBML to provide additional language interfaces (such as Java, Python, etc.), then you may also need to perform the following steps to make the language bindings available to software on your computer.

C++ and C

If libSBML has been configured normally, then compiling C++ or C software to use it is a matter of supplying certain compilation and linking options. There are two main sets of settings:

The flag -IDIR/include needs to be supplied to the compiler, where DIR is the value of the --prefix=DIR option given during configuration of libSBML. 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, where DIR is again the value of the --prefix=DIR option given during configuration of libSBML. 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.

Java

First, note that by default, libSBML only builds the C and C++ APIs. To build the Java API as well, libSBML has to be configured with the --with-java flag as described in the installation instructions.

The Java interface for libSBML is implemented partly as pure Java and partly as Java Native Interface (JNI) code. Once libSBML is configured and built using the --with-java flag described above, and libSBML has been installed on a computer, three more steps are required to use the Java-libSBML interface in an application.

Step 1: set LD_LIBRARY_PATH (Linux), DYLD_LIBRARY_PATH (Mac OS X), or PATH (Windows)

First, please follow the instructions for configuring the LD_LIBRARY_PATH (under Linux, Unix, Cygwin), DYLD_LIBRARY_PATH (under Mac OS X) or PATH (under Windows) variables described in the beginning of this section. This is necessary so that, before the operating system starts a Java application, the system loaders can find libSBML's native library components.

Step 2: adjust the application's class search path

Java applications separately need to have their class search paths include the libSBML .jar and binary object files. 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 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 install itself into /usr/local (e.g., by using --prefix=/usr/local when configuring libSBML), the libsbmlj.jar file will end up as /usr/local/share/java/libsbmlj.jar 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.

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 somewhere in your application, usually in the application's main class. The following example illustrates one way of 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
  {
    String varname;
    String shlibname;

    if (System.getProperty("os.name").startsWith("Mac OS"))
    {
      varname = "DYLD_LIBRARY_PATH";    // We're on a Mac.
      shlibname = "libsbmlj.jnilib and/or libsbml.dylib";
    }
    else
    {
      varname = "LD_LIBRARY_PATH";      // We're not on a Mac.
      shlibname = "libsbmlj.so and/or libsbml.so";
    }

    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:");
      e.printStackTrace();
      System.err.println("Please check the value of your " + varname +
			 " environment variable and/or" +
                         " your 'java.library.path' system property" +
                         " (depending on which one you are using) to" +
                         " make sure it lists all the directories needed to" +
                         " find the " + shlibname + " library file and the" +
                         " 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'.");
      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);
    }
  }

}

Python

First, note that by default, libSBML only builds the C and C++ APIs. To build the Python API as well, libSBML has to be configured with the --with-python flag as described in the installation instructions.

Once that is done, and libSBML has been installed on your system, then Python needs just one more thing to be informed where to find the libSBML package: it needs the environment variable named PYTHONPATH to be set. On Unix-based systems at least, if DIR is the value of the --prefix=DIR option given during configuration of libSBML and version is the version of your copy of Python, then the value of PYTHONPATH needs to be set as follows:

export PYTHONPATH=DIR/lib/version/site-packages

for sh-based shells such as Bash, or

setenv PYTHONPATH DIR/lib/version/site-packages

for csh-based shells. In other words, the PYTHONPATH environment variable needs to be set to the site-packages directory path where the libSBML library has been installed. Please see the section titled "Files installed by libSBML, and their locations" elsewhere in this manual for more information about the files installed for 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 almost certainly means that the environment variables have 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.

MATLAB

First, note that by default, libSBML only builds the C and C++ APIs. To build the MATLAB API as well, libSBML has to be configured with the --with-matlab flag as described in the installation instructions.

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

As with the other cases described above, the first configuration step necessary for users is to make sure that their LD_LIBRARY_PATH or DYLD_LIBRARY_PATH environment variable (see the relevant section in the installation instructions) is set to the directory where the libSBML shared library object is installed. When the MATLAB bindings are enabled in libSBML, this 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. The LD_LIBRARY_PATH/DYLD_LIBRARY_PATH environment variable must 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.)

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.

C#

First, as mentioned for some of the other languages described on this page, please be aware that libSBML by default only builds the C and C++ APIs. To build the C# API as well, libSBML has to be configured with the --with-csharp flag as described in the installation instructions.

The C# interface for libSBML is implemented partly as pure C# and partly as native code. Once libSBML is configured and built using the --with-csharp flag described above, and libSBML has been installed on a computer, two more steps are required to use the C#-libSBML interface in an application.

Step 1: set LD_LIBRARY_PATH (Linux), DYLD_LIBRARY_PATH (Mac OS X), or PATH (Windows)

First, please follow the instructions for configuring the LD_LIBRARY_PATH (under Linux, Unix, Cygwin), DYLD_LIBRARY_PATH (under Mac OS X) or PATH (under Windows) variables described in the beginning of this section. This is necessary so that, before the operating system starts a C# application, the system loaders can find libSBML's native library components.

Step 2: 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;

On most Linux/Unix-based platforms:

On Microsoft Windows platforms:

Step 1: set LD_LIBRARY_PATH (Linux), DYLD_LIBRARY_PATH (Mac OS X), or PATH (Windows)

Step 2: adjust the application's class search path

Step 3: load the libSBML JNI library in the application

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

MATLAB on Windows systems

Step 1: set LD_LIBRARY_PATH (Linux), DYLD_LIBRARY_PATH (Mac OS X), or PATH (Windows)

Step 2: place the managed library libsbmlcsP.dll into your application's directory

Step 2: place the managed library `libsbmlcsP.dll` into your application's directory