libSBML C API
libSBML 5.8.0 C API
|
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.
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.
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.)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/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/libOn Mac OS X, this would instead be
setenv DYLD_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.
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.
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:
-I
DIR/include
--prefix=
DIR-I
/usr/local
, then when compiling your software
to use libSBML, you will also need to add the flag
-I/usr/local/include
-L
/lib -lsbml
-lstdc++ -lm
need to be supplied to the compiler or linker,
where DIR is again the value of the
--prefix=
DIR-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.
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
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
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.
.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:
You must either (1) set your CLASSPATH
environment
variable to include the .jar
file, or (2) the file must be
listed in the -classpath
/usr/local
(e.g., by using
--prefix=/usr/local
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
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.
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); } } }
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
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. If DIR is the value of the
--prefix=
DIRPYTHONPATH
needs to be set as
follows on Ubuntu 11 systems:
export PYTHONPATH=DIR/lib/version/site-packagesand as follows for other Linux systems:
export PYTHONPATH=DIR/lib/version/dist-packagesThe above is for sh-based shells such as Bash; if you use csh-based shells, then the appropriate syntax is instead
setenv PYTHONPATH DIR/lib/version/site-packagesand
setenv PYTHONPATH DIR/lib/version/dist-packagesfor Ubuntu 11 and non-Ubuntu systems, respectively. In other words, the
PYTHONPATH
environment variable needs to be set to the
site-packages
dist-packages
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.
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
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.
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.
TranslateSBML
and OutputSBML
. These will
be accessible after you restart MATLAB and even when you are no longer in
the libSBML directory.
--with-csharp
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
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.
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;