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.
In particular, on most Linux/Unix-based platforms, you must perform one of the following two steps:
ldconfig
as user 'root'. (Please
consult the man page for ldconfig
if this is unfamiliar. On
MacOS X, there is no equivalent to the ldconfig
facility.)LD_LIBRARY_PATH
in their command shells. (On MacOS X,
the variable is named DYLD_LIBRARY_PATH
.) The value of
LD_LIBRARY_PATH
or DYLD_LIBRARY_PATH
must include
the directory used as the value of the --prefix=
DIR For example, suppose that you configured libSBML to use the default
installation prefix
. 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
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
prefix/include
--prefix=
value-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 prefix is again the value of the
--prefix=
value-L
If you have the pkg-config
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
--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
Once that is done, then in addition to the instructions for configuring
the LD_LIBRARY_PATH
or DYLD_LIBRARY_PATH
variables described in the beginning of this section, 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 described in the following subsections.
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
, 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
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.
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, then in addition to the instructions for configuring
the LD_LIBRARY_PATH
or DYLD_LIBRARY_PATH
variables described at the beginning of this section, 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
DIR is the value of
the --prefix=
DIRPYTHONPATH
needs to be set as follows:
_libsbml.so
and libsbml.py
. 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 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.
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 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.)
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.
src/bindings/matlab
with
libsbml here standing in for the directory where you
unzip'ed the source distribution archive. Then, execute the command
make.bat
.
cd libsbml/src/bindings/matlab make.bat
src/bindings/matlab
, and finally run
the MATLAB script install_Win32.m
located in that
directory.
cd libsbml/src/bindings/matlab; install_Win32;