1. Quick start instructions

The default XML parser library used by libSBML is libxml2. If you chose to use the Xerces XML 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.

Linux, MacOS X, FreeBSD, and Solaris

First, for MacOS X and Linux, check the download site for libSBML on SourceForge.net for possible installation packages for these operating systems. You may be able to download and install a precompiled copy of libSBML for your system.

If there is no installer for your system, or you prefer to build libSBML from the source distribution, proceed as follows. At a shell (terminal) command prompt, unzip the distribution, and cd into the directory thereby created (e.g., libsbml-3.4.0). If you only want to build the C and C++ interfaces, 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 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++ APIs. If you want to configure libSBML to build the C#, Java, Python, Perl, MATLAB, Octave, and/or Ruby APIs as well, 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, 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               # 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.

Windows

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.

2. Detailed instructions for configuring and installing LibSBML

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, FreeBSD 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.

Configuring for Linux, MacOS X, FreeBSD, and Solaris

As mentioned above, for MacOS X and Linux, check the download site for libSBML on SourceForge.net for possible installation packages for these operating systems. You may be able to download and install a precompiled copy of libSBML for your system, and void the process of building libSBML from source files.

If you have obtained the libSBML source code distribution, then at your Linux, MacOS X, FreeBSD or Solaris terminal command prompt, unpack the distribution, and cd into the directory created (e.g., libsbml-3.4.0). If you only want to build the C and C++ interfaces, 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

  ./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 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.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 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), 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 universal binaries on MacOS

Apple Macintosh operating systems after 2005 have provided the option of building binaries that can run natively on either PowerPC or x86 (Intel) architectures. Compiling a library to be a so-called universal binary requires the use of special options at compilation time. To build libSBML 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

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). By default, universal binaries are built by C/C++ compiler with -arch i386 -arch ppc options (i.e., 32-bit x86 and PowerPC architectures). 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"

Configuring SWIG

Important: libSBML is known to work with SWIG version 1.3.33 or later; earlier versions are known not to work. You must use version 1.3.33 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):

• For the C, C++ and Python API documentation: You will need Doxygen version 1.5.8 or later and a reasonably complete installation of LaTeX. You will also need to configure libSBML to use Doxygen by supplying the option --with-doxygen to the configure program. Tip for Macintosh users: if you are on a MacOS X system and you installed the binary distribution of Doxygen from the .dmg image provided by Doxygen's author, you will need to point configure to the doxygen executable inside the package for Doxygen:

    ./configure --with-doxygen=/Applications/Doxygen.app/Contents/Resources
  

• For the Java API documentation: You will need Javadoc version 1.5 (also known as version 5.0, confusingly enough), which should have come supplied with your installation of Java 1.5 or later. No additional configuration of libSBML is needed beyond supplying the --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                   # Note: use 'gmake java-manual' on FreeBSD

  make cpp-manual                    # Note: use 'gmake cpp-manual' on FreeBSD

  make c-manual                      # Note: use 'gmake c-manual' on FreeBSD

  make python-manual                 # Note: use 'gmake python-manual' on FreeBSD

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 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:

1. In Visual Studio 7, open <libsbml>/win32/MSVC7/libsbml.sln. (This file provides the configuration for building with the Xerces XML parser; alternatively, you can use <libsbml>/win32/MSVC7/libsbml_expat.sln to build against the Expat parser or <libsbml>/win32/MSVC7/libsbml_xml.sln to build against the libxml2 XML parser.)
2. Select Tools->Options, and select Projects/Directories. The screen for indicating which directories contain project-relevant files appears.
3. At "Show Directories For:", select "Include Files". Add the following if it's not already shown: libsbml/include

   Note: you will also need to add the path to the include files relevant to the XML Parser library.

4. At "Show Directories For:", select "Library Files". Add the following if it's not already shown: libsbml/win32/bin
5. Select Build->Rebuild All from the Visual Studio main menu.

3. Files installed by libSBML, 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:

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.

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).

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.