C++ and C Java Python MATLAB Octave Perl Common Lisp

Once libSBML has been installed on a computer, you will still need to link your software with libSBML to make its API accessible from your software. (Note that this is separate from the issue of your software being able to find libSBML at run time; see the section about accessing libSBML for more information.) This section provides information about how to do that.

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:

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 prefix/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

In addition to the instructions for configuring the LD_LIBRARY_PATH or DYLD_LIBRARY_PATH variables (see the section about accessing libSBML), Java applications separately need to have their class search paths 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 described in the following subsections.

On Linux, MacOS 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, the libsbmlj.jar file will end up as /usr/local/lib/libsbml.jar and your environment variable would at minimum need to be set as follows:

  CLASSPATH=.:/usr/local/lib/libsbmlj.jar

On Windows systems

The instructions are essentially the same as for the case of Linux and similar systems, but the name of the .jar file is different on Windows systems: it is called sbmlj.jar. For example, if you had installed libSBML into C:\libsbml on your system, you might set your environment variable as follows:

  CLASSPATH=.;C:\libsbml\sbmlj.jar

Note: to set an environmental variable in Windows, use the System option in the Control Panel.

Python

In addition to the instructions for configuring the LD_LIBRARY_PATH or DYLD_LIBRARY_PATH variables (see the section about accessing libSBML), Python needs another environment variable named PYTHONPATH to be set according to where the libSBML Python binaries have been installed. Unfortunately, this variable's value is confusing to set. On Unix-based systems at least, if prefix is the value of the --prefix=value 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=prefix/lib/version/site-packages/libsbml:prefix/lib/version/site-packages
for sh-based shells such as Bash, or
set PYTHONPATH = prefix/lib/version/site-packages/libsbml:prefix/lib/version/site-packages
for csh-based shells. What is crucial in both cases is that the two directories listed on the path are the directories containing the files _libsbml.so and libsbml.py.

Once both the library path environment variable and PYTHONPATH have 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

On Linux, MacOS 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 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, 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 MacOS X system and you have configured libSBML to install itself into /usr/local. Then the files TranslateSBML.mexmaci and CheckAndConvert.m will have been installed as /usr/local/lib/TranslateSBML.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.)

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.

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, there are two possible approaches.

Octave

(Documentation unfinished.)

Perl

(Documentation unfinished.)

Common Lisp

(Documentation unfinished.)