1. Quick start instructions Linux, MacOS X, and Solaris Windows
2. Detailed instructions for configuring and installing LibSBML Configuring libSBML for Linux, MacOS X, and Solaris Configuring libSBML interfaces to C#, Java, Perl, Python, MATLAB, Octave and Ruby Additional configuration options Creating universal binaries on MacOS Configuring for SWIG Configuring for unit testing Configuring support for compression Configuring for generating documentation Compiling and installing LibSBML on Unix, Linux and MacOS X Configuring and building for Windows
3. Files installed by libSBML, and their locations
4. What to do after building and installing libSBML

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

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.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.39 or later; earlier versions are known not to work. You must use version 1.3.39 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

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

LibSBML also includes project files for MSVC8; the build process is identical to that listed above, but uses files from the `/win32/MSVC8/` directory.

## 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 | 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` | `libsbml.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 | 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` `libsbmlj.jar`
MATLAB | (Intel) (PPC) (Additional files) | `TranslateSBML.mexglx` N/A `CheckAndConvert.m` | `TranslateSBML.mexmaci` `TranslateSBML.mexmac` `CheckAndConvert.m` | `TranslateSBML.mexw32` 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 | (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/`v-perl`/`platform`/auto/libSBML/` DIR`/lib/perl5/site_perl/`v-perl`/`platform`/` DIR`/lib/perl5/site_perl/`v-perl`/`platform`/` | (2)
Python | (native C++ library) (Python module file) (Compiled module file) (Path configuration file) | DIR`/lib/`v-python`/site-packages/libsbml/` DIR`/lib/`v-python`/site-packages/libsbml/` DIR`/lib/`v-python`/site-packages/libsbml/` DIR`/lib/`v-python`/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 v-perl refers to the version number of the Perl executable against which libSBML was configured. The placeholder v-python 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.