1. Quick start instructions
2. Detailed instructions for configuring and installing LibSBML
3. Files installed by libSBML, and their locations
4. What to do after building and installing libSBML

1. Quick start instructions

Compatibility warning: The default XML parser library used by libSBML is libxml2. If you chose to use another XML parser library instead, 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 and above, are known to work properly, and all Expat versions above 1.95.8 are also known to work.

Avoiding work by using ready-to-install binaries

Check the download site for libSBML on SourceForge.net for possible installation packages for your operating system. We supply ready-to-install precompiled binaries for many systems, so that you may be able to save yourself the time and trouble of following the remaining instructions on this page.

Building libSBML on Linux, MacOS X, FreeBSD, Solaris, and Cygwin

If there is no installer for your system, or you prefer to build libSBML from the source distribution, proceed as follows. Download and unzip the source code archive somewhere on your file system, and in a shell (terminal), cd into the directory thereby created (e.g., libsbml-4.1.0). If you only want to build the C and C++ interfaces and install libSBML into /usr/local (the default), then configuring libSBML is simply a matter of executing the following command:

  ./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 program will terminate with an error explaining it cannot find libxml2. In that case, you can inform the configure program to use the Expat or Xerces libraries instead. For Expat, use the following command:

  ./configure --with-expat

And for Xerces, use

  ./configure --with-xerces

If, in addition to the C and C++ interfaces, you want to configure libSBML to build the C#, Java, Python, Perl, MATLAB, Octave, and/or Ruby APIs as well, then add the flags --with-csharp, --with-java, --with-python, --with-perl, --with-matlab, --with-octave, and/or --with-ruby (respectively) to the configure program. You can supply more than one of these flags at the same time.

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, to use a copy of Java whose components are in /usr/local (with the executable programs in /usr/local/bin and library 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               # Note: use 'gmake' on FreeBSD
  make install       # Note: use 'gmake install' on FreeBSD

To call and access libSBML from your software application, please refer to the instructions in the section titled Making libSBML accessible to your software.

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; please see the instructions in section Configuring for generating documentation below.

Building libSBML on Windows

For building libSBML on Windows, the libSBML source distribution includes project files for several versions of Microsoft Visual Studio running on Windows XP (32-bit), Windows Vista (64-bit) or Windows 7 (64-bit). Please see the instructions in the section below for information about how to use these to build libSBML on Windows.

2. Detailed instructions for configuring and installing LibSBML

LibSBML requires a separate XML library for low-level XML tokenizing and Unicode support. For this, it supports the Xerces-C++, Expat, and libXML XML libraries on Linux, Windows, MacOS X, FreeBSD, Solaris and Cygwin. 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 distributions. (Libxml2 appears to be the most commonly available library on Linux and MacOS X 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.

As already noted, there is a bug in Xerces 2.6.0 that cannot be worked around. Xerces versions 2.2 – 2.5, and 2.7.0 and above, are known to work properly. Expat version 1.95.8 and above, and libxml2 version 2.6.16 and above, are all known to work.

Configuring for Linux, MacOS X, FreeBSD, Solaris, and Cygwin

If you have obtained the libSBML source code distribution, then at your Linux, MacOS X, FreeBSD, Solaris or Cygwin terminal command prompt, unpack the distribution, and cd into the directory created (e.g., libsbml-4.1.0). If you only want to build the C and C++ interfaces and install the results in /usr/local (the default), then configuring libSBML is simply a matter of executing the following command:

  ./configure

To specify Expat or Xerces explicitly rather than the default libxml2, use a command such as the following instead:

  ./configure --with-expat
or
  ./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"
or
  ./configure --with-xerces="DIR"
or
  ./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"

By default, during the installation phase (i.e., when running make install, discussed below), the 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 to /usr/local/share/doc/libsbml-VERSION (where VERSION is the version number of libSBML). To specify a different installation location instead of the default, use the --prefix argument to the configure program. 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.

Configuring interfaces to C#, Java, Perl, Python, MATLAB, Octave, and Ruby

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 C#, Java, Perl, Python, MATLAB, Octave, and/or Ruby, you need to supply additional options to configure. These options are --with-csharp, --with-java, --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.5 Intel-based system with MATLAB version R2010a installed in its default location of /Applications/MATLAB_R2010a.app, the proper argument would be

  ./configure --with-matlab=/Applications/MATLAB_R2010a.app

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 the project SVN repository on SourceForge, or you 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 core 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 (depending on the operating system) libsbmlj.jnilib (MacOS X), libsbml.so (Linux), or sbmlj.dll (Windows); both of these must be installed and shipped with applications along with the core libSBML library file. Please refer to section Files installed by libSBML, and their locations) for an explanation of the name and location of the libSBML library file under different operating systems.

Additional configuration options

In addition to the --prefix and other options already described, the libSBML configuration command supports the options described below.

Creating 32- and/or 64-bit binaries

On some hardware and operating system combinations, it is possible to compile 64-bit as well as 32-bit versions of programs. Normally, the most sensible default will be chosen by the systems' compilers automatically, but when you download third-party software or compile your own, sometimes it becomes necessary to select specific versions. LibSBML is no exception. To make it easier to build libSBML explicitly in a 32-bit or 64-bit version, configure offers the two optional arguments --enable-m32 and --enable-m64, respectively.

Whether you need to do this depends very much on your hardware, operating system, and the format of other libraries and programs on your system. Currently, the most common situation where this issue arises is on 64-bit systems where not all libraries (e.g., the XML parser libraries) are available in 64-bit format. Then, libSBML needs to be configured to be built as a 32-bit binary:

  ./configure --enable-m32

The two options --enable-m32 and --enable-m64 cannot be used together; if they are both given, then the 32-bit option is silently ignored. On MacOS X systems, where it is in fact possible to build so-called universal (or "fat") binaries containing both 32-bit and 64-bit executable code, a separate option is available for configure and is discussed in the next section.

Creating universal binaries on MacOS X

Apple Macintosh operating systems after 2005 have provided the option of building binaries that can run natively on either PowerPC or x86 (Intel) architectures, as well as in either 32-bit or 64-bit versions. Compiling a library to be a so-called universal binary containing multiple versions of the object code requires the use of special options at compilation time. To configure libSBML to be built as a universal binary, specify the optional argument --enable-universal-binary to configure. The following example illustrates how to do this:

  ./configure --enable-universal-binary

By default, on MacOS 10.5, the libSBML option above will construct a universal binary containing 32-bit PowerPC and 32-bit Intel x86 binaries; on MacOS 10.6, this becomes 32-bit PowerPC, 32-bit x86, and 64-bit x86 binaries. If you want to build universal binaries with a different combination of CPU architectures, then you can specify it as an optional argument to the --enable-universal-binary option. For example, universal binaries will be built with i386, ppc, x86_64 and ppc64 architectures in the following example:

  ./configure --enable-universal-binary="-arch i386 -arch ppc -arch x86_64 -arch ppc64"

Beware that building with this option turn on results in the creation of larger libSBML binary files, because the files contain essentially two copies of the same code (one for each architecture).

Finally, if both --enable-universal-binary and either --enable-m32 or --enable-m64 are given, the latter two options are ignored and the option for universal binaries takes precedence. This is justified because, on MacOS X, the optional argument to --enable-universal-binary can be used to accomplish the same goals as the two other individual options.

Configuring SWIG

Important: libSBML is known to work with SWIG version 1.3.40 or later; earlier versions are known not to work. You must use version 1.3.40 or later (The latest stable version is recommended).

SWIG is the Simplified Wrapper and Interface Generator and in libSBML it is used to create the bindings for C#, Java, Python, and other programming languages. 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"

Configuring the unit testing system

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                   # Note: use 'gmake' on FreeBSD
  make check             # Note: use 'gmake check' on FreeBSD

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.

Configuring support for compression

LibSBML provides built-in support for reading and writing compressed SBML files. This facility works transparently: if a given SBML filename ends with one of the suffixes recognized for a compressed file (namely, .gz, .zip, or .bz2), the libSBML readSBML() method will automatically decompress the file upon reading it and the writeSBML() method will compress the file upon writing it. (Files whose names have no extensions are read and written in uncompressed form.)

These features are enabled by default if the required libraries can be found on your system. The libraries are the zlib library (for the gzip and zip formats) and the bzip2 library (for the bzip2 format). If the libSBML configure program cannot find the libraries in the locations where it searches by default, you can inform the configure program where to look by adding the flag --with-zlib=DIR where DIR is the parent directory of the lib directory where the zlib library is located, and/or the flag --with-bzip2=DIR where DIR is the parent directory of the lib directory where the bzip2 library is located.

To selectively disable specific library checks and format support, add the option --with-zlib=no and/or --with-bzip2=no to the configure program invocation. Or, to completely disable compression support and checking for both libraries, add the --enable-compression=no option to configure:

  ./configure --enable-compression=no

Configuring for generating documentation

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 development version of libSBML in the SVN repository on SourceForge.

If you would like to generate the documentation yourself, you will need the following software tools in addition to a Unix-like environment (or Cygwin under Windows):

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                   # Note: use 'gmake java-manual' on FreeBSD
to recreate just the Java documentation, or
  make cpp-manual                    # Note: use 'gmake cpp-manual' on FreeBSD
to recreate just the C++ documentation, or
  make c-manual                      # Note: use 'gmake c-manual' on FreeBSD
to recreate just the C documentation, or
  make python-manual                 # Note: use 'gmake python-manual' on FreeBSD
to recreate just the Python documentation.

Compiling and installing libSBML on Unix, Linux and MacOS X

Once configured, building and installing libSBML should be very easy. Simply execute the following commands at your Linux, MacOS X or Solaris command prompt:

  make                      # Note: use 'gmake' on FreeBSD
  make install              # Note: use 'gmake install' on FreeBSD

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. (A quick way to run a command as root is to use the sudo command; i.e., run sudo make install.)

Please refer to the section titled "Files installed by libSBML, and their locations" for information about the locations where the installation step copies the various libSBML files.

Configuring and building for Windows

The source libSBML distribution, obtainable from the project download site on SourceForge.net, is a .zip file that must be extracted in a directory on your system, compiled and installed. There are two ways to compile libSBML under Windows: using the native Windows compilation tools from Microsoft, and using the Cygwin environment. In this section, we focus on using the native Windows environment because this appears to be the more popular approach used by Windows-based users of libSBML. Cygwin users can follow essentially the same instructions as for other Unix environments given above.

Prerequisites

The source distribution includes project files for Microsoft Visual Studio; version 7.1 (2003) is the minimum version of MSVC needed. In addition, to compile LibSBML, you must have certain other libraries installed that are not included in the source code distribution. They must be obtained separately if you do not already have them on your system:

  1. XML parser library: LibSBML requires an underlying XML parser library. It can use libxml2, Xerces-C, or Expat. Whichever one you choose, the DLL file for the parser library must be placed in the win32/bin subdirectory of the libSBML directory prior to attempting to compile libSBML.
  2. Compression libraries: In addition to an XML parser library, LibSBML also needs the compression libraries zlib and bzip2 if you wish to include support for reading and writing compressed SBML files. This is not a requirement, and the support for compression can optionally be turned off.

Compilation

The libSBML win subdirectory contains several subdirectories with names of the form msvcX; these subdirectories organize the project files for different Microsoft Visual Studio versions. For example, win/msvc7 contains the project files for MSVC version 7. Within the individual project directories msvcX, there are several subdirectories with names of the form msvcX/LANG, each containing the project files for a specific version XML parser library, as well as a common subdirectory containing files that are not parser-library-dependent. All told, this directory organization has the following structure:

win
/batch-files
/msvc7
/common
/...
/expat
/libsbml.vcproj
/libsbml_csharp.vcproj
/libsbml_java.vcproj
/libsbml_perl.vcproj
/libsbml_python.vcproj
/libxml
/...
/xerces
/...
/msvc8
/...
/msvc9
/...

The batch-files subdirectory contains Windows batch files to perform various actions, such as to create the include directory of header files used by libSBML, as well as to invoke SWIG, and perform other tasks. These batch files may need to be edited to use pathnames relevant to a particular system.

A few additional points are worth noting here. First, the project files include support for the proposed SBML Level 2 Layout extension by Gauges et al. Second, the project files in msvc8 support a 64-bit Windows configuration. And finally, the libSBML developers have not tested any native Windows-compatible compilers besides the Microsoft Visual Studio series. If you succeed in using compilation environment, please let the libSBML developers know so that we can include support in future versions of libSBML.

To build libSBML on Windows, follow these steps:

  1. Choose and open the required project(s) from within the MSVC IDE.
  2. Given the variation in Windows systems, the paths to the header files and libraries are not hard-coded into these project files. To inform MSVC where to find the files, use the Tools->Options menu item in the IDE, and select Projects/Directories. Paths to header files and library files can then be added. Once added, these are remembered by the IDE.
  3. You will also need to add paths to the header files and library files for any of the third-party libraries used.
  4. Compile.

After a successful build, MSVC will put the libSBML library files and DLL into the win/bin subdirectory.

Language bindings when building under Windows

The MSVC projects call a prebuild event to generate the necessary files using SWIG. Although the source distribution for libSBML contains these files, they are actually prebuilt on a Unix system, and in some cases there are differences between these and the SWIG files intended for a native Windows environment. We recommend that you rebuild these files using swigwin (the native Windows version of SWIG). This will happen automatically when building the relevant project. You will need to edit the relevant runSWIG_ batch file to establish the correct path to your swigwin installation.

Any language binding library/DLL files will be placed in a subdirectory of the win/bin directory. For example, C# files will appear in win/bin/csharp. Where the language binding also involves a language specific file (e.g., a JAR file for Java), these will be found in the relevant src/bindings/ directory (e.g., src/bindings/java/java-files).

3. Files installed by libSBML version 4.x, and their locations

If all went as it should, the libSBML object files 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. The core libSBML library object files will have slightly different names depending on the operating system in use. The following table summarizes the possibilities; note that these names changed slightly between libSBML 3.x and 4.x to incorporate the version number:

Names of core libSBML 4.x object files
Type of file Linux/Unix-based OS MacOS X Windows
Dynamically-linked libsbml.so.4 libsbml.4.dylib libsbml.dll
Statically-linked libsbml.a libsbml.a libsbml.lib
Libtool control file libsbml.la libsbml.la sbmlj.la

If you have compiled additional language extensions with libSBML, these files will be installed as well, but their names and locations depend on the particular language extension. The following two tables summarize the possibilities. The first table lists the names of the files, while the second table below lists the pathnames where those files will be installed.

Names of language extension object files
Language Linux/Unix-based OS MacOS X Windows
C# (unmanaged C++ DLL)
(managed C# DLL)
libsbmlcs.so
libsbmlcsP.dll
libsbmlcs.so
libsbmlcsP.dll
libsbmlcs.dll
libsbmlcsP.dll
Java (native C++ library)
(Java JAR file)
libsbmlj.so
libsbmlj.jar
libsbmlj.jnilib
libsbmlj.jar
sbmlj.dll
sbmlj.jar
MATLAB (Intel 32-bit)
(Intel 64-bit)
(PPC)
(Additional files)
TranslateSBML.mexglx
TranslateSBML.mexa64
N/A
CheckAndConvert.m
TranslateSBML.mexmaci
TranslateSBML.mexmaci64
TranslateSBML.mexmac
CheckAndConvert.m
TranslateSBML.mexw32
TranslateSBML.mexw64
N/A
CheckAndConvert.m
Octave TranslateSBML.mex
CheckAndConvert.m
TranslateSBML.mex
CheckAndConvert.m
TranslateSBML.mex
CheckAndConvert.m
Perl (native C++ library)
(Perl module file)
(Other files)
LibSBML.so
LibSBML.pm
LibSBML.pod
.packlist
LibSBML.bundle
LibSBML.pm
LibSBML.pod
.packlist
LibSBML.dll
LibSBML.pm
LibSBML.pod
.packlist
Python 2.3–2.4 (native C++ library)
(Python module file)
(Compiled module file)
(Path configuration file)
_libsbml.so
libsbml.py
libsbml.pyc
libsbml.pth
_libsbml.so
libsbml.py
libsbml.pyc
libsbml.pth
_libsbml.dll
libsbml.py
libsbml.pyc
libsbml.pth
Python 2.5–2.7 (native C++ library)
(Python module file)
(Compiled module file)
(Path configuration file)
_libsbml.so
libsbml.py
libsbml.pyc
libsbml.pth
_libsbml.so
libsbml.py
libsbml.pyc
libsbml.pth
_libsbml.pyd
libsbml.py
libsbml.pyc
libsbml.pth
Ruby libSBML.so libSBML.bundle libSBML.dll
Legend: N/A = not available.

The next table gives the locations of the files listed in the table above for Linux/Unix-based operating systems. The pathnames shown here are relative to the prefix directory used in configuring libSBML (meaning the value DIR given to the --prefix=DIR option to the configure program discussed above).

Language Directories Notes
C# (unmanaged C++ DLL)
(managed C# DLL)
DIR/lib/mono/libsbmlcsP/
DIR/lib/mono/libsbmlcsP/
Java (native C++ library)
(Java JAR file)
DIR/lib/
DIR/share/java/
MATLAB DIR/lib/
Octave DIR/lib/octave/site/oct/platform/ (1)
Perl (native C++ library)
(Perl module file)
(Other files)
DIR/lib/perl5/site_perl/perl-version/platform/auto/libSBML/
DIR/lib/perl5/site_perl/perl-version/platform/
DIR/lib/perl5/site_perl/perl-version/platform/
(2)
Python (native C++ library)
(Python module file)
(Compiled module file)
(Path configuration file)
DIR/lib/python-version/site-packages/libsbml/
DIR/lib/python-version/site-packages/libsbml/
DIR/lib/python-version/site-packages/libsbml/
DIR/lib/python-version/site-packages/
(2)
Ruby DIR/lib/ruby/site_ruby/ruby-version/platform/
Legend: The placeholder platform stands for a platform-specific directory name; the exact string depends on the combination of your operating system, machine architecture, programming language, and the versions of all of these. The placeholder perl-version refers to the version number of the Perl executable against which libSBML was configured. The placeholder python-version refers to the version number of the Python executable against which libSBML was configured. The placeholder ruby-version refers to the version number of the Ruby executable against which libSBML was configured. Note that none of these values are actually under the control of libSBML; they are set by the operating system and programming language package conventions.

Additional notes:
(1) The Octave installation directory actually depends on how Octave was configured at build time. If your installation of Octave came as a precompiled binary, the package directory may in fact be different from what is shown here.
(2) The directory component lib may be replaced by lib64 on some 64-bit operating systems (e.g., CentOS 5.2 x86-64).

4. What to do after building and installing libSBML

Once the libSBML files are installed as described in the sections above, you may need to perform additional steps so that software can find the libSBML library files at run time. Please see the instructions in the the section titled Making libSBML accessible to your software.