Quick start instructions
Detailed instructions for configuring and installing LibSBML

Quick start instructions

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.

Linux, MacOS X, and Solaris

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
Please see the section Generating documentation below for more information.

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.

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 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, and Solaris

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

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.

Configuring interfaces to Java, Lisp, 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 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.

Compiling and installing libSBML on Unix, Linux and MacOS X

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.

Making libSBML accessible to other software on Unix, Linux and MacOS X systems

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.

Additional options for configuring LibSBML

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

Configuring SWIG

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"

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

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

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
to recreate just the Java documentation, or
  make cpp-manual
to recreate just the C++ documentation, or
  make c-manual
to recreate just the C documentation, or
  make python-manual
to recreate just the Python documentation.

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