As of libSBML version 3.0.1, the default XML parser library used by libSBML is libxml2. If you are using the Xerces XML library, beware there is a known bug in Xerces 2.6.0 that cannot be worked around at this time and causes errors in software using it. Xerces versions 2.2 2.5 and 2.7.0 are known to work properly.
At a shell (terminal) command prompt, unzip the distribution, cd
into the directory thereby created (e.g., libsbml-3.0.2
),
and first type:
./configure
It will by default attempt to use the libxml2 XML library; if you do not have libxml2 version 2.6.16 or later on your system, the configure step will fail. In that case, you can try using the Expat or Xerces libraries instead. For Expat, use
./configure --with-expat
and for Xerces, use
./configure --with-xerces
By default, libSBML only builds the C and C++ API. If you want to
configure libSBML to build the Java, Lisp, Python, Perl, MATLAB, Octave,
and/or Ruby APIs as well, add the flags --with-java
,
--with-lisp
, --with-python
,
--with-perl
, --with-matlab
,
--with-octave
, and/or --with-ruby
(respectively)
to the configure command. You can combine options.
Depending on your system, you may need to tell the configure
program where to find some of these extra components by adding a
directory path after the option. For example, if you wish to use a
copy of Java whose components are in /usr/local
(with
files in /usr/local/lib
), use
./configure --with-expat --with-python --with-java=/usr/local
Once you've successfully configured libSBML, run the following two commands to build and install it:
make make install
To compile C or C++ programs that use libSBML with GCC, use a
command such as the following, where -lsbml
tells the
compiler to link with the installed libSBML library:
gcc -o myapp.c myapp.c -lsbml
If your compiler returns an error about being unable to find the
library, please refer to the section on accessing
libSBML below for information about ldconfig
,
LD_LIBRARY_PATH
/DYLD_LIBRARY_PATH
, and related
matters.
Documentation for libSBML is available as a separate download from
the same locations as the libSBML distribution (namely, the SBML
project on SourceForge
and the SBML.org website). You may also regenerate the
documentation from the source code distribution if you have Doxygen version 1.5.4 installed and have
configured libSBML with the --with-doxygen
flag. Then
you can execute the following to generate and install the libSBML
documentation files:
make install-docs
We should point out at the outset that the main developers have been using only Windows XP, and do not have direct experience building libSBML under other versions of Windows. Users do report some success on other versions of Windows, but your results may vary.
Download and run the self-extracting windows installer for
libSBML. There are debug (libsbmld
) and release
(libsbml
) versions of libSBML, with .dll
and
.lib
files for both versions in the
win32/bin
subdirectory of the libSBML distribution.
Header files are located in the subdirectory
win32/include/sbml
.
Users of Visual C++ should make their Visual C++ projects link
with the files libsbml.lib
or libsbmld.lib
and generate code for the Multithreaded DLL or Debug Multithreaded DLL
version of the VC++ runtime, respectively.
LibSBML requires a separate XML library for low-level XML tokenizing and Unicode support. As of libSBML 3.0, it supports the Xerces-C++, Expat, and libXML XML libraries on Linux, Windows, MacOS X and Solaris. Many Linux and other UNIX-like systems provide one or more of these libraries either as part of their standard distribution or as an optional RPM, Debian, Mandrake or other package. (Libxml2 appears to be the most commonly available library on Linux and MacOSX systems.) For more information, see http://xml.apache.org/xerces-c/ for Xerces, http://expat.sf.net for Expat, and http://xmlsoft.org for libxml2.
If you have obtained the libSBML source code distribution, then at
your Linux, MacOS X or Solaris command prompt, unpack the
distribution, cd into the directory created (e.g.,
libsbml-3.0.0
), and type the following command in a terminal
shell window to configure libSBML for your system:
./configure
To specify Expat or Xerces explicitly rather than the default libxml2, use a command such as the following instead:
./configure --with-expat
./configure --with-xerces
If your copy of libxml2, Expat, or Xerces is installed in a
non-standard location on your computer system (e.g., a private home
directory), configure
may not be able to find it by itself.
In this case, configure
needs to be told explicitly where to
find the libraries. Use the following forms:
./configure --with-libxml="DIR"
./configure --with-xerces="DIR"
./configure --with-expat="DIR"
where DIR is the parent directory of where the
include
and lib
directories of Xerces, Expat
or libxml2 (whichever one you are trying to use) is located. For
example, on MacOS X, if you used Fink to install Expat in Fink's
default software tree, you would configure libSBML using the following
command:
./configure --with-expat="/sw"
During the installation phase (i.e., when running make
install
, discussed below), the default libSBML installation
commands will copy header files to
/usr/local/include/sbml
, the (shared and static) library files
to /usr/local/lib
, and documentation files in various
formats to /usr/local/share/doc/libsbml-VERSION
, by
default. To specify a different installation location, use the
--prefix
argument to configure. For example,
./configure --prefix="/my/favorite/path"
Of course, you can combine the flags to configure, giving both
--prefix
and --with-expat
or
--with-xerces
or --with-libxml
to set both
options.
LibSBML's core is written in C and C++, but libSBML comes with APIs for
other languages as well. To enable the library extensions for Java,
Python, Lisp, MATLAB, Octave, and/or Ruby, you need to supply additional
options to configure
. These options are
--with-java
, --with-lisp
,
--with-perl
, --with-python
,
--with-matlab
, --with-octave
, and
--with-ruby
, respectively. As with other configure options
discussed above, all of these accept an optional prefix argument; for
example, on a MacOS 10.4 Intel-based system with MATLAB version R2007b
installed in its default location of
/Applications/MATLAB_R2007b
, the proper argument would be
./configure --with-matlab=/Applications/MATLAB_R2007b
If you want to build multiple language bindings for libSBML, combine multiple flags together as in the following example:
./configure --with-java --with-python
The libSBML distribution ships with certain interface files provided, so that you do not need to have the software necessary to recreate them. However, if you obtained the libSBML distribution from CVS or want to recreate the files deliberately, you may need to configure libSBML to use SWIG to regenerate the libSBML language interfaces. Please see the section below on using SWIG.
Finally, note that these additional language bindings are
implemented via foreign function interfaces in the respective
languages; in all cases, the basic C/C++ libSBML library still must be
compiled and installed. The language binding files are not standalone
implementations. For instance, the Java language API files consist of
a file named libsbmlj.jar
and a native object library
file named libsbmlj.jnilib
; both of these must
be installed and shipped with applications along with the
basic libSBML library file.
Once configured, building should be very easy. Simply execute the following commands at your Linux, MacOS X or Solaris command prompt:
make make install
Note that you will probably have to perform the make install
command as the user 'root' on your system if you used the default
installation directory ( /usr/local
) or you set
--prefix
to a system directory that only root is permitted to
write into.
Depending on your operating system, the basic libSBML shared object
library file installed by the commands above will be a file named
libsbml.so
or libsbml.dylib
, and a static library
named libsbml.a
will be installed as well. If you have
compiled additional language extensions with libSBML, these files will also
be installed in the same directory. For example, as discussed above, the
Java language API files consist of a file named libsbmlj.jar
and a native object library file named libsbmlj.jnilib
; these
will be installed in the same directory as the core libSBML library file.
If all went as it should, libSBML should end up compiled and
installed on your system, in either the default location
(/usr/local/
) or in the location you indicated during the
configuration step as explained above.
Once the libSBML files are installed as described in the previous
section, you may need to do one more configuration step so that you and
your users' software can find the libSBML library files at run time.
On most Linux-based platforms, this must be done either by running the
system program ldconfig
as user 'root' (consult the man page
for ldconfig
if this is unfamiliar), or else each user must
set the environment variable LD_LIBRARY_PATH
in their command
shells. (On MacOS X, the variable is named
DYLD_LIBRARY_PATH
. Also, there is no equivalent on
MacOS X to the ldconfig
facility.) The path added to the
LD_LIBRARY_PATH
or DYLD_LIBRARY_PATH
variable
must be the directory used as the value of the
--prefix=
DIR option used during the
configure
step discussed above.
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 with errors about being unable to find it.
In addition to the --prefix
and other options already
described, the libSBML configuration command supports the options
described below.
Important: At this time, libSBML is known to work only with the latest stable version of SWIG (1.3.33); earlier versions are known not to work. You must use at least version 1.3.33.
SWIG is the Simplified Wrapper and Interface Generator
and in libSBML it is used to create the bindings for Java, Python, and
other programming languages. More information about SWIG is available
from http://www.swig.org. To
configure libSBML to use SWIG, use the --with-swig
option
to configure
. If your copy of SWIG is installed in a
location where configure
cannot find it on its own, you
can specify it as an optional argument to the --with-swig
option as in the following example:
./configure --with-swig="DIR"
libSBML provides built-in facilities for testing itself. To run the
unit tests, a second library is required, libcheck
(version
0.9.2 or higher). Check is a very lightweight C unit test
framework based on the xUnit framework popularized by Kent Beck and eXtreme
Programming. Check is quite small and once installed, it consists of
only two files: libcheck.a
and check.h
. To
download Check, visit http://check.sf.net/.
(Note #1: Debian users can find Check as a standard add-on package
(.deb
). As of 11 Feb. 2007, MacOS X users
cannot use Fink's
version of check because it is an old version, 0.8.x. LibSBML needs
version 0.9.x.)
(Note #2: If you are using g++ version 3.3, you will need to avoid using Check version 0.9.5, and instead use version 0.9.2. The problem is an incompatibility between Check 0.9.5 and earlier versions of g++. It appears that the compatibility problems in Check 0.9.5 disappear with versions of g++ after 3.3.)
To enable the unit testing facilities in libSBML, add the
--with-check
flag to the configure command:
./configure --with-check
Following this, you must build libSBML and then you can run the tests:
make make check
The make check step is optional and will build and run an extensive suite of unit tests to verify all facets of the library. These tests are meant primarily for developers of libSBML and running them is not required for the library to function properly. All tests should pass with no failures or errors. If for some reason this is not the case on your system, please submit a bug report using the mechanisms described in the section titled "Bug Reports, Mailing Lists, and Related Topics" elsewhere in this manual.
LibSBML comes with extensive documentation, and the document you
are currently reading is part of it. Because the documentation is
large and regenerating it requires the use of software tools that not
all users may have, the authors of libSBML supply a separate
downloadable archive containing only the documentation. The
documentation archive file has a name of the form
libsbml-VERSION-docs.zip
, where
VERSION
is the version of libSBML. After you
download it, you can simply unzip the file in the same location as
your libSBML source directory (or alternatively, in any other location
that suits you). We recommend downloading the ready-made
documentation archive as the easiest way to get the libSBML
documentation.
The same documentation files should also be available online at http://sbml.org/software/libsbml/, although this online copy normally corresponds to the last stable release of libSBML and may not be up-to-date with the latest version of libSBML in CVS.
If you wish to generate the documentation yourself, you will need the following software tools in addition to a Unix-like environment (or Cygwin under Windows):
--with-doxygen
to the configure
program.
Warning: this option is unlike the other configuration
options, in that if the optional pathname argument is supplied, the
pathname must be the path to the Doxygen executable itself,
not the path to the directory where Doxygen is located. In other
words, in using the optional argument, you should end up with
something such as the following,
./configure --with-doxygen=/sw/bin/doxygen
.dmg
image), you will have
to point configure
to the doxygen executable inside the
package for Doxygen:
./configure --with-doxygen=/Applications/Doxygen.app/Contents/Resources/doxygen
--with-java
option to configure
.
Once libSBML is configured as above, you can generate the
documentation files by running make docs
from the top
level of the libSBML source directory to regenerate all the
documentation files. Alternatively, you can moving to the
docs/src
subdirectory and execute
make java-manual
make cpp-manual
make c-manual
make python-manual
The Windows distributions of libSBML come in the form of both
precompiled binaries (with a self-extracting installer), and source
code. The precompiled binaries come ready-to-use and only need to be
installed. The source distribution is a .zip
file
containing the libSBML code that must be extracted in a directory on
your system, compiled and installed.
As mentioned above, libSBML requires that the libxml2, Xerces-C, or
Expat XML parsing libraries be available on your computer prior to
attempting to compile libSBML. The DLL file for libxml2, Xerces, or Expat
must be placed in the win32/bin
subdirectory of the libSBML
directory.
To build libsbml on Windows:
<libsbml>/win32/MSVC7/libsbml.sln
.
libsbml/include
Note: you will also need to add the path to the include files relevant to the XML Parser library.
libsbml/win32/bin