libSBML C# API  5.20.2
Loading...
Searching...
No Matches
Related Pages
Here is a list of all related documentation pages:
[detail level 12]
 Accessing libSBML from software
 Asking questions, reporting issuesThe continued improvement of libSBML is crucially dependent on your feedback. Below are some means of discussing and sharing your experiences.

Reporting bugs and other problems

Please report problems and other issues using the issue tracker for libSBML on GitHub: https://github.com/sbmlteam/libsbml/issues.

You can also report problems on the sbml-interoperability mailing list (see next section). This may have advantages, such as that other people may also have experienced the same issue and offer a workaround more quickly than the libSBML developers can respond.

Finally, if you want to contact the libSBML developers directly, you can email them at libsbml-team@googlegroups.com.

Mailing lists, web forums, and list archives

If you use SBML (which seems likely, if you are using libSBML), we urge you to sign up for sbml-announce, the SBML announcements mailing list. It is a low-volume, broadcast-only list where new releases of SBML and other important events are announced. These announcements are not cross-posted to the other lists below, so it's important to subscribe to sbml-announce even if you subscribe to the other lists below.

In addition, if you use libSBML, we highly recommend that you subscribe or monitor the mailing list sbml-interoperability. Subscribing to this list will enable you to keep in touch with the latest developments in libSBML as well as to ask questions and share your experiences with fellow users and developers of libSBML and other SBML software. The mailing list is vigilantly moderated by humans to prevent spam and off-topic postings.

If you are interested in delving more deeply into libSBML, perhaps to make extensions and modifications, we recommend that you also subscribe or monitor the mailing list libsbml-development. Being a member of this list will enable you to keep in touch with the latest developments in libSBML as well as to ask questions and share your experiences with fellow developers and users of libSBML.

Web-based interfaces for all lists are available at http://sbml.org/Forums/, for those who prefer to interact with the list via a web forum interface. This website is also where you will find the mailing list archives. (The lists and the forums are cross-posted, and the archives are identical to each other.)

Notifications via RSS and Twitter

If you wish to get notifications of mailing list postings via RSS, an individual feed for each mailing list mentioned above is available at http://sbml.org/Forums/.

If you wish to get general announcements about SBML and its use, you may want to follow sbmlnews on Twitter.

 How to extend libSBML to support SBML packages
 Step by step summary of the implementation of an extension
 Detailed explanation of each package extension class
 LibSBML features at a glance

LibSBML is an application programming interface (API) library for reading, writing and manipulating files and data streams containing content in SBML (Systems Biology Markup Language) format. Developers can embed the library in their applications, saving themselves the work of implementing their own parsing, manipulation and validation software. At the API level, the library provides the same interface to data structures independently of whether the model originated in SBML Level 1, 2 or 3. LibSBML also fully supports all accepted SBML Level 3 packages.

Why not simply use a generic XML parsing library? After all, SBML is usually expressed in XML, and there exist plenty of XML parsers, so why not simply tell people to use one of them, rather than develop a specialized library? The answer is: while it is true that developers can use general-purpose XML libraries, there are many reasons why using a system such as libSBML is a vastly better choice. Here are just some of the features offered by libSBML:

  • Full SBML Support. All constructs in SBML Level 1, 2 and 3 Core are supported, as are the constructs defined in the officially ratified SBML Level 3 packages.
  • Unified SBML Level 3, Level 2 and Level 1 object models. All objects have getSBMLDocument(), getModel(), getLevel(), and getVersion() methods, among other things.
  • Full XML and SBML Validation. LibSBML offers extensive validation against the SBML specifications; this helps verify the correctness of SBML models in a way that goes beyond simple schema-based validation. All XML warnings and errors are logged with line and column number information and may be retrieved and manipulated programmatically. LibSBML also does not force applications to read and write valid models: SBML validation is something that must be invoked explicitly, which allows callers to do such things as store incomplete models during editing.
  • Dimensional analysis and unit checking. LibSBML implements a thorough system for dimensional analysis and checking units of quantities in a model. The validation rules for units that are specified in SBML Level 2 Version 2 and Version 3, as well as the equivalent warnings defined in SBML Level 2 Version 4 and Level 3 Version 1, are fully implemented, including checking units in mathematical formulas.
  • Support for both MathML and text-string mathematical formulas. LibSBML offers facilities for manipulating mathematical expressions in both MathML form and a text-string format. It uses an Abstract Syntax Trees (AST) representation of mathematical formulas, supporting both in-memory operations and the ability to parse and write either text-string or MathML representations. It also supports extensibility by plug-ins for SBML Level 3 packages.
  • Facilities for converting and transforming SBML. LibSBML provides various facilities that include such important functionality as converting between SBML Levels and Versions (when possible). LibSBML can also transform within-SBML constructs, such as to expand all user-defined functions in-line, replace reactions with explicit differential equations, and many other transformations. This makes many general SBML models accessible to software systems that do not directly support certain SBML constructs, or can only read certain Level/Version combinations of SBML.
  • Other domain-specific facilities. LibSBML provides many other useful facilities relevant to developing models in SBML. Examples of such operations include obtaining a count of the number of boundary condition species, determining the modifier species of a reaction (assuming the reaction provides kinetics), and constructing the stoichiometric matrix for all reactions in a model.
  • Access to SBML annotations and notes as XML objects. LibSBML offers an API to facilitate the creation and addition of MIRIAM-compatible RDF annotations inside SBML <annotation> elements. Both these kinds of annotations and the related SBML <notes> element content can be read and manipulated as XML structures or text strings.
  • Support for SBO. LibSBML provides API methods for adding and working with Systems Biology Ontology (SBO) terms in SBML models. Annotating a model with SBO terms adds semantic information that can permit better software interpretation of the model's mathematical structure and (potentially) the ability to translate a model between different mathematical frameworks.
  • Support for compressed SBML files. If an SBML file name ends in .gz, .zip or .bz2, libSBML will automatically uncompress the file upon reading it. Similarly, if the file to be written has one of those extensions, libSBML will write it out in compressed form.
  • XML parser abstraction. LibSBML relies on third-party XML parser libraries, but thanks to its implementation of an abstraction layer, libSBML can use any of three different popular XML parser libraries: Expat, Apache Xerces-C++, and libxml2. LibSBML provides identical functionality and checking of XML syntax is available no matter which one is used. SBML Documents are parsed and manipulated in the Unicode codepage for efficiency; however, strings are transcoded to the local code page for SBML structures.
  • Interfaces for C, C++, C#, Java, JavaScript, MATLAB, Octave, Perl, PHP, Python, R and Ruby (as mentioned above). The C and C++ interfaces are implemented natively; the C#, Java, JavaScript, Perl, PHP, Python, R and Ruby interfaces are implemented using SWIG, the Simplified Wrapper Interface Generator; and the MATLAB and Octave interfaces are implemented through custom hand-written code.
  • Small memory footprint and fast runtime. The parser is event-based (SAX2) and loads SBML data into C++ structures that mirror the SBML specification.
  • Portability. LibSBML is written in ISO standard C++ and C and is highly portable. It currently runs on the Linux, Mac OS X, and Microsoft Windows operating systems, but it has been known to run under FreeBSD, Solaris and iOS with little or no modifications.
  • Support for both CMake and GNU autoconf and make. For core libSBML, both build systems are supported, allowing programmers greater flexibility in configuring and embedding libSBML in their software.
  • Extensive testing. LibSBML has several thousand unit tests containing a total of over tens of thousands of individual assertions. In addition to these tests, libSBML contains over 4400 hand-written SBML XML files containing different variations of both correctly and incorrectly written SBML and XML syntax.
  • Extensive documentation. Complete API documentation is available in the "docs" subdirectory, with individual API manuals for the different programming languages support by libSBML.

Users of libSBML often find its features convenient to use for more than simply supporting SBML. For example, many software packages provide users with the ability to express mathematical expressions for such things as reaction rate expressions, and these packages' interfaces often let users type in the formulas directly as text strings. LibSBML's API for mathematical formulas, with its support for text-string based input, thus saves application programmers the work of developing their own formula manipulation and translation facilities.

LibSBML is distributed in both source-code form and as precompiled dynamic libraries for the Microsoft Windows, Linux and Apple Mac OS X operating systems; they are available from the SBML project site on SourceForge.net.

 Building and installing libSBML

This section explains how to build libSBML from the source distribution.

Table of contents

1. Building libSBML under Linux, Mac OS X, FreeBSD, Solaris and Cygwin
2. Building libSBML under Windows
3. Files installed by libSBML, and their locations
4. What to do if problems arise

1. Procedures for Linux, Mac OS X, FreeBSD, Solaris and Cygwin

LibSBML supports two build systems: CMake, and GNU autoconf plus GNU make. CMake is preferred and is the only one supported for building SBML Level 3 package extensions; the use of GNU autoconf and GNU make is deprecated but is currently still used to build the documentation. In all cases below, you will need to download the libSBML source code archive from the download area on GitHub then unpack the archive somewhere on your computer.

1.1 Configuring using CMake

CMake is a cross-platform build configuration system that can be used to generate makefiles as well as project files for common development environments such as Visual Studio, Eclipse, Xcode and CodeBlocks. If you do not already have CMake installed on your system, please make sure to download and install a copy of CMake 3.10 or later from cmake.org on your computer system.

Next, start up the CMake graphical user interface (GUI). This is a configuration tool that allows you to select options for configuring your libSBML build and then generate makefiles for running the actual build. The GUI will look something similar to the following screenshot:

Screenshot of CMake when it first starts up. Shown here is the Mac OS X version of CMake; it will look similar but not identical on other operating systems.

In the CMake GUI interface, first click on the Browse Source... button and navigate to the directory where you unpacked the libSBML source code archive on your file system. Next, check the value of the field Where to build the binaries. We use so-called “out-of-source builds” for libSBML, meaning that CMake will place compiled binary files in a separate build directory, not intermixed with the source files. If the field for the build directory in the CMake GUI is blank, or CMake filled it with a different value than what you prefer, click on the Browse Build... button to change the directory.

After filling in the fields at the top of the interface, click on the Configure button. If this is the first time you have executed CMake's Configure command in the libSBML source directory, you may see a dialog such as the following, asking you whether it can create a subdirectory where it will compile libSBML. Click on the "Yes" button if the directory location is acceptable.

Dialog presented by CMake before it creates the subdirectory that it will use to compile libSBML.

After the dialog above, CMake should then display a dialog similar to the next one.

Screenshot of the Configure screen under Mac OS X.

Unless you have special requirements, select the default choices of "Unix Makefiles" and "Use default native compilers", then click the Done button. This will close the selection dialog, whereupon CMake will read the libSBML configuration files and populate the options area in the CMake GUI with various options for controlling how libSBML is built. These new options are displayed in red, as illustrated in the following screenshot.

Screenshot of the CMake interface after the configuration step.

In this panel, you can set values for various libSBML configuration/build options. To find out the meaning of a particular option, hover your mouse/pointer over the item for a few seconds until a tooltip appears—it will provide a short description of the option under the cursor. There are numerous options available; below, we point out just a few that are especially popular for customization:

  • CMAKE_INSTALL_PREFIX: the location into which the compiled libSBML libraries. After clicking on this field, you can type a directory path directly into the field or click on the square ... icon to invoke a file/open dialog.
  • WITH_JAVA, WITH_PYTHON, etc.: toggle whether to build the language bindings for programming languages supported by libSBML, such as C#, Java, JavaScript, MATLAB, Octave, Perl, Python, R, Ruby, and possibly others. If you need to indicate an explicit path to the interpreter (e.g., for Python), click the "Advanced" checkbox in the upper part of the CMake GUI to gain access to additional configuration options. (For Python, they are PYTHON_EXECUTABLE, PYTHON_INCLUDE_DIR and PYTHON_LIBRARY.)
  • ENABLE_COMP, ENABLE_QUAL, etc.: toggle whether support for various SBML Level 3 packages is included. The names following the ENABLE_ part are the package nicknames: “comp” for the Hierarchical Model Composition package, “qual” for the Qualitative Models package, and so on.
  • WITH_EXPAT, WITH_XERCES: by default, libSBML will use the libxml2 XML library. If you prefer to use Expat (version 1.95.8 or greater) or Xerces (version 2.7.0 or greater), select one of these options instead, and set WITH_LIBXML to false.

Note that selecting options and configuring libSBML using the GUI actually involves a two-step process:

  1. Select options in the panel.
  2. Click on CMake's Configure button. This causes CMake to process the configuration options, and if the chosen options require additional information, CMake will update the list in the window and highlight some items in red. This indicates that CMake requests you to make additional choices, provide additional information or resolve conflicting choices.
You may need to iterate in between the two steps above, setting options and clicking the Configure button, until there are no options left in red and the Generate button becomes enabled.

Once you are satisfied with the options selected and there are no more red items the dialog box, click on the Generate button. This will cause CMake to create configuration files for the compilation environment you selected in the beginning (e.g., Visual Studio under Windows, or regular Unix makefiles under Mac OS or Linux, and so on). The files will be placed in the "build" directory you indicated in the second line of the CMake GUI.

Now please proceed to Section 1.3, Compiling and installing LibSBML.

1.2 Configuring using GNU Make

Warning: the use of GNU autoconf and GNU make is deprecated. It cannot be used to properly build the libSBML packages, and it has only been retained to build the libSBML documentation. Please use the CMake-based build system unless you are attempting to build the documentation.

First, in a shell (terminal), cd into the directory where you unpacked the libSBML source code archive. (It will have a name such as libSBML-5.20.2-Source.)

1.2.a Basic configuration for Linux, Mac OS X, Solaris, and Cygwin

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

LibSBML requires a separate XML library for low-level XML tokenizing and Unicode support. 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. (Important: libSBML needs the development libraries for libxml2, not only the runtime library, which on systems such as Linux means that you need to have installed both the basic libxml2 distribution and the -dev distribution. These distributions typically have the root names libxml2 and libxml2-dev, often followed by a version number.)

Instead of using libxml2, you can inform the configure program to use the Expat or Xerces libraries. 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. To use Expat, run the libSBML configuration program as follows:

./configure --with-expat

And for Xerces, use

./configure --with-xerces

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.

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

1.2.b Interfaces for C#, Java, JavaScript, MATLAB, Octave, Perl, Python, R 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, JavaScript, MATLAB, Octave, Perl, Python, R and/or Ruby, you need to supply additional options to configure. These options are --with-csharp, --with-java, --with-javascript, --with-matlab, --with-octave, --with-perl, --with-python, --with-r, and --with-ruby, respectively. As with other configure options discussed above, all of these accept an optional prefix argument; for example, on a Mac OS X 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

Some of the language interfaces provide additional configuration options besides the basic --with-language option. In particular, for Python and C#, there are options allowing you to specify the language interpreter that should be used, which is important for systems that have multiple versions installed. For example, to indicate that you want to use the Apple-supplied version of Python 2.6 on a Mac OS X 10.7 system (which has versions 2.5, 2.6 and 2.7 located in /usr/bin), you could use the following options:

./configure --with-python --with-python-interpreter=/usr/bin/python2.6

Please run configure --help to obtain a list of the possible options offered by configure.

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 repository on GitHub, 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 (Mac OS 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.

A warning about Java versions: we have been unable to successfully compile the libSBML Java interface using the GNU Compiler for Java (gcj), at least in the case of gcj version 4.4.3 under Ubuntu Linux version 10.10. We do not recommend using gcj with libSBML for this reason.

1.2.c 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 Mac OS 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.

1.2.d Creating universal binaries on Mac OS X

Apple Macintosh operating systems versions 10.4–10.6 provide 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 Mac OS 10.5, the libSBML option above will construct a universal binary containing 32-bit PowerPC and 32-bit Intel x86 binaries; on Mac OS 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 Mac OS X, the optional argument to --enable-universal-binary can be used to accomplish the same goals as the two other individual options.

1.2.e Configuring for SWIG

Important: libSBML is known to work with SWIG version 2.0.0 or later; earlier versions are known not to work. You must use version 2.0.0 or later.

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

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

1.2.g 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.8.4 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 Mac OS 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.

1.2.h Configuring for software unit testing

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 install Check, you may first want to examine whether it is easily available via a software package manager for your system (e.g., Synaptic under Ubuntu Linux, MacPorts or Fink under Mac OS X, etc.); if not, you can also download Check from http://check.sf.net/.

(Note: 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.

1.3 Compiling and installing libSBML

After the configuration step (and if you are using CMake, the generation of the makefiles), the final steps are to run the compilation process followed by a command to install libSBML on your system.

1.3.a Using CMake

If you are using CMake, then in a terminal/shell window, first cd into the "build" directory that you indicated to CMake in the second line of the CMake GUI during the configuration step described in Section 1.1, Configuring using CMake above. For instance, if your "build" directory is simply named build and you placed it in a subdirectory of the libSBML source directory (let SRC stand for that directory), you would simply do the following:

cd SRC/build

Next, execute the following command to compile libSBML:

make                # Note: use 'gmake' on FreeBSD

If all went well and libSBML compiled without errors, you can use the following command to install libSBML on your computer:

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

Once the libSBML files are installed as described 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 section on making libSBML accessible to your software, provided elsewhere in this documentation.

1.3.b Using GNU make

Important: parallel GNU make builds of libSBML are not supported at this time. Attempting to use the -j option with make will not work properly and will not complete, but will also not produce diagnostics that indicate the cause of the failure (thus making it difficult to understand what went wrong). Do not use the -j option with GNU make.

If you are using GNU make and not using CMake, in a terminal/shell window, cd to the top level of the libSBML source directory. In the following example, let SRC stand for that directory:

cd SRC

Next, execute the following commands to compile libSBML:

make                # Note: use 'gmake' on FreeBSD

If all went well and libSBML compiled without errors, you can use the following command to install libSBML on your computer:

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

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 separate section on making libSBML accessible to your software provided elsewhere in this documentation.

1.3.c Debugging build problems

If something went wrong during the build step and the compilation of libSBML stopped with an error, it may be useful to get more information in order to debug the process.

  • If you use CMake: When building libSBML with CMake, you can easily run the build with verbose debugging output by giving the argument VERBOSE=1 in the make step:
    make VERBOSE=1
    
  • If you use GNU make: When building libSBML with GNU make, you can use the argument --debug=b to get additional debugging information without the overwhelming amount of output produced by make -d. In other words, you can use the following command:
    make --debug=b
    

If you need to contact the libSBML Team for help with debugging a failing libSBML build, it will greatly help us to get a record of the debugging output from a clean build. On Linux, Mac OS X and Cygwin, you can use the convenient script command to record input and output in a terminal shell, and then email us the output.

  • If you use CMake:
    make clean          # Clean everything to get a fresh build
    script              # Start recording everything in the shell
    make VERBOSE=1      # Build with debugging on
    exit                # Stop recording the script
    
  • If you use GNU make:
    make clean          # Clean everything to get a fresh build
    script              # Start recording everything in the shell
    make --debug=b      # Build with debugging on
    exit                # Stop recording the script
    

Don't forget to type exit!

Once you type exit, the script command will stop and leave a file named "typescript" in the current directory. Please include the "typescript" when contacting the libSBML Team with questions about build failures.

1.4 Advanced configuration options

Whether you use CMake or GNU make, there are some additional advanced options that are uncommonly used, but still worth explaining. We list the options below using their names as they appear in the CMake configuration screen; the alternative configure approach uses slightly different command-line flag names, but still similar to the names below.

  • LIBSBML_SHARED_VERSION: This flag controls whether the version number should be written into the libSBML shared library.
  • LIBSBML_USE_STRICT_INCLUDES: This flag is intended for libSBML developers; it permits faster recompilation of libSBML by reducing the files that are #include'd in certain ways, such that changing a single libSBML class does not cause as many dependencies to be triggered. This option makes no difference to compilation except when you make changes to libSBML class definitions and recompile libSBML, so there is no advantage for regular user code to enable this option.

2. Procedures for Windows

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.

2.1 Configuring using CMake

To create configurations suitable for compiling libSBML using the native Windows build tools, we recommend using CMake to generate them. (If you do not already have CMake installed on your system, please begin by downloading a copy of CMake version 2.8.4 or later from cmake.org.) Once you have CMake installed, also download and unzip the libSBML source code archive from the download area on GitHub.net and save the archive somewhere on your file system, then unpack it.

Before going further, an issue on Windows concerns the dependency libraries on which libSBML depends. CMake will try to find all the dependencies for the default options, which leads to problems if they do not exist. We recommend Windows users download the dependencies we have prepackaged at the following download location:

https://sourceforge.net/projects/sbml/files/libsbml/win-dependencies

Download and extract this file into the same folder where you unpacked the libSBML source distribution. CMake will look for these dependencies in a folder called dependencies directly below the libSBML root folder.

Once you have the libSBML sources and the dependency libraries unpacked on your system, start up the CMake graphical user interface (GUI). It will look something like the following screenshot:

Screenshot of CMake when it first starts up.

Click on the Browse Source... button and navigate to the directory where you unpacked the libSBML source code archive on your file system. CMake should automatically fill in the next line, Where to build the binaries, using a subdirectory named build within the directory where your source code is located. (If it does not, fill in the field in the CMake interface yourself.) Then, click on the Configure button. CMake should display a dialog similar to the following.

Screenshot of the Configure screen under Microsoft Windows 7. Choose the settings appropriate for the build environment you are using and click the Finish button.

After you close the configuration screen, CMake will populate the options area with various options it reads from the libSBML configuration files. These new options are displayed in red, as illustrated in the following screenshot.

Screenshot of the CMake interface after the configuration step.

In this panel, you can set values for various libSBML configuration/build options. For example, you can set the location into which the compiled libSBML libraries will be installed by clicking on the line for CMAKE_INSTALL_PREFIX and replacing the default value with a value of your choosing. To find out the meaning of a particular option, hover your mouse/pointer over the item for a few seconds until the tooltip text appears.

Select the options with which you wish to build libSBML. All the options for configuring libSBML, including language bindings and SBML Level 3 packages, are listed here and may be selected/deselected as required. For instance, to include the Java language bindings, click the check-box for WITH_JAVA. Once you are done configuring, click on CMake's Configure button. CMake will process the configuration, and if it lacks any information, it will highlight the options in red. You may need to iterate between setting options and clicking the Configure button until there are no options left in red and the Generate button becomes enabled.

Next, click on the Generate button. This will cause CMake to create project configuration files ("Solutions") for the compilation environment you selected in the beginning (e.g., Visual Studio 2010).

2.2 Compiling and installing using MSVC

The MSVC Solution will contain a number of projects files, depending on the configuration selected. The following screenshot illustrates what you should see when you use the Solution Explorer in MSVC, and some of the most important targets that you will find there:

Screenshot of MSVC's Solution Explorer when viewing the MSVC Solution files generated using CMake.

  • ALL_BUILD: This target builds all the libSBML project files; that is, all projects except the ones that involve installation, packaging or testing.
  • INSTALL: This target will install the compiled binaries to the directory specified for the CMAKE_INSTALL_PREFIX option of the CMake configuration step.
  • ZERO_CHECK: This target is merely a verification project; it is used to check whether there have been any changes to the configuration since the last time it was run. It is invoked automatically whenever any other target is being built.
  • PACKAGE: This target creates binary installers for libSBML. If the Nullsoft scriptable installation system, NSIS (http://nsis.sf.net) is available, an installer is created for the current platform. Most users will not need to use this build target/Solution.
  • RUN_TESTS: This target can be used to test all the libraries built. It is only available if the WITH_CHECK option is selected during the CMake configuration step. (Note: the libcheck library upon which this facility depends is incompatible with MSVC 7, so you will need to use a newer version of MSVC if you want to try RUN_TESTS.) The checks will fail if Windows is unable to locate the dynamic libraries, or for each language binding if it is unable to locate both the binding library and the libSBML native library.

Other projects generated by the libSBML CMake configuration system and listed in the MSVC Solution explorer are named to indicate the intended target. Some examples include the following:

  • binding_python_lib: builds the Python language bindings _libsbml.pyd file.
  • binding_java_classes: builds the Java language bindings class JAR file.
  • example_c_convertSBML: builds the convertSBML example program in C.
  • example_java_addCVTerms: builds the addCVTerms example program in Java.
  • test_sbml_math: builds the tests in the libSBML src/math subdirectory.

A typical procedure for building libSBML using MSVC consistes of performing the following steps:

  1. Select and run the ALL_BUILD target. After a successful build, MSVC will put the libSBML library files and DLL into the Release subdirectory of the location specified using CMake. This includes the language bindings, which will be placed in a subdirectory of the Release directory. For example, C# files will appear in Release/csharp.
  2. Select and run the INSTALL target. This will install the compiled libSBML library and associated files into the directory determined by the CMAKE_INSTALL_PREFIX CMake configuration variable.

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 on Making libSBML accessible to your software provided on a separate page of this documentation.

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:

Names of core libSBML object files
Type of file Linux/Unix-based OS Mac OS X Windows
Dynamically-linked libsbml.so.5 libsbml.5.dylib libsbml.dll
Statically-linked libsbml.a libsbml.a libsbml.lib
Libtool control file libsbml.la libsbml.la N/A

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 Mac OS 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
libsbmlj.jar
JavaScript (Node.js module) sbml.node sbml.node sbml.node
MATLAB (Intel 32-bit) TranslateSBML.mexglx
OutputSBML.mexglx
TranslateSBML.mexmaci
OutputSBML.mexmaci
TranslateSBML.mexw32
OutputSBML.mexw32
(Intel 64-bit) TranslateSBML.mexa64
OutputSBML.mexa64
TranslateSBML.mexmaci64
OutputSBML.mexmaci64
TranslateSBML.mexw64
OutputSBML.mexw64
(PPC) N/A

TranslateSBML.mexmac
OutputSBML.mexmac
N/A

(Additional files) CheckAndConvert.m
Contents.m
ConvertFormulaToMathML.m
isSBML_Model.m
isoctave.m
CheckAndConvert.m
Contents.m
ConvertFormulaToMathML.m
isSBML_Model.m
isoctave.m
CheckAndConvert.m
Contents.m
ConvertFormulaToMathML.m
isSBML_Model.m
isoctave.m
Octave TranslateSBML.mex
OutputSBML.mex
CheckAndConvert.m Contents.m
ConvertFormulaToMathML.m
isSBML_Model.m
isoctave.m
TranslateSBML.mex
OutputSBML.mex
CheckAndConvert.m Contents.m
ConvertFormulaToMathML.m
isSBML_Model.m
isoctave.m
TranslateSBML.mex
OutputSBML.mex
CheckAndConvert.m Contents.m
ConvertFormulaToMathML.m
isSBML_Model.m
isoctave.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
R libSBML.rdb
libSBML.rdx
libSBML
libSBML.rdb
libSBML.rdx
libSBML.so
libSBML.rdb
libSBML.rdx
libSBML.dll
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/
JavaScript DIR/lib/node/
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
(Ubuntu)
(native C++ library)
(Python module file)
(Compiled module file)
(Path configuration file)
DIR/lib/python-version/dist-packages/libsbml/
DIR/lib/python-version/dist-packages/libsbml/
DIR/lib/python-version/dist-packages/libsbml/
DIR/lib/python-version/dist-packages/
Python
(Other Linux distributions)
(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)
R DIR/lib/R/site-library/libSBML/
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 if problems arise

Given the large number of variables that are involved in installing libSBML (e.g., operating systems versions, library versions, etc.), it is not impossible that issues arise when you try to get libSBML working. We offer the following tips for what to do if you encounter problems:

  1. Check the list of known issues elsewhere in this manual. There, we try to describe the known problems, limitations and possible pitfalls in using libSBML.
  2. Ask for help on the libSBML and SBML mailing lists.
  3. Contact the developers directly by sending email to libsbml-team@googlegroups.com. Please make sure to include the following information:
    • The version of libSBML you are using,
    • The operating system, and operating system version, that you are using,
    • The programming language you are using,
    • A description of what you are trying to do, and
    • A copy of any error messages or other diagnostic messages printed by libSBML or your compiler or any other software involved in the problem. If the problem occurs while compiling libSBML, please follow the instructions in section 1.3.c Debugging build problems on how to produce a record of the output produced during compilation.
 Known issues and pitfallsThis section documents the following known problems, limitations, and possible pitfalls in using libSBML:

Potential for language bindings to link old versions of libSBML by accident

At application run-time, the language bindings for C#, Java, JavaScript, Perl, PHP, Python and others must be able to dynamically link the core libSBML library file (i.e., libsbml.so, libsbml.dylib or libsbml.dll, depending on your operating system). If a user's environment includes an old version of this library file, and it is picked up at run-time instead of the correct library version, linking may fail with mysterious errors about undefined symbols. Users and developers are cautioned to make sure that their installations have matched versions of libSBML components and are free of older versions that may be picked up inadvertently.

Some versions of MATLAB include a conflicting version of libstdc++

Some versions of MATLAB produced for Linux include a version of the stdc++ library that conflicts with the version provided by the operating system. This copy of the library is installed in MATLAB's own directories. This may cause a conflict not in building libSBML, but running MATLAB code that use libSBML, such as TranslateSBML (the MATLAB interface function provided as part of libSBML). The result is that MATLAB will produce an error messages such as "libSBML is not linked" or "/unix/bin/glnxa64/../../sys/os/glnxa64/libstdc++.so.6: version `GLIBCXX_3.4.11' not found".

The solution is to preload the system stdc++ library before invoking MATLAB. You can accomplish this by setting the Linux environment variable LD_PRELOAD to the path of the system's libstdc++ library file. You must first locate this file on your particular operating system. Giving a precise recipe for finding the file is difficult because it differs slightly by operating system, but it is often found in a subdirectory of /usr/lib and will be named libstdc++.so.6.

Once you know the path to the stdc++ library file, set the value of LD_PRELOAD This will take the form of the following:

export LD_PRELOAD=/path/to/system/libstdc++
for sh-based shells such as Bash, or
setenv LD_PRELOAD /path/to/system/libstdc++
for csh-based shells.

Explicit freeing of memory when using static MSVC runtimes

On MS Windows, when using libSBML compiled against a static MSVC runtime library, it is not possible to use the standard free() function call to free memory allocated and returned by libSBML. Without the ability to use free() to free the string returned by libSBML, the calling application will leak memory. An example of typical code where one would want to free the returned by libSBML is the following:

   char * formula = SBML_formulaToString(astNode);
   /* ... do some work with formula here ... */
   free(formula);

To cope with this issue, beginning with version 4.2, libSBML provides a special function for this situation: util_free().

Name collisions in mathematical expressions

In the C-like, text-based, formula expression syntax supported by libSBML and used in SBML Level 1, four constants are reserved words: true, false, exponentiale and pi. Most of them will not easily lead to a name collision, but unfortunately, the character sequence pi is also sometimes used as a species identifier by biological modelers (e.g., to use "Pi" to represent a phosphate ion). If the string "pi" or "Pi" appears in a text string passed to a libSBML method that interprets formulas, it will be interpreted as the mathematical constant π (pi). For example, the expression 2 * Pi will yield

<math xmlns="http://www.w3.org/1998/Math/MathML">
  <apply>
    <times/>
    <cn type="integer"> 2 </cn>
    <pi/>
  </apply>
</math>

This problem exists for all four of the constants mentioned above, but is most commonly encountered in the context of "pi". Currently, the only ways to avoid this problem are either to avoid using the strings "pi" and "Pi" in this context, or to avoid using the text-string expressions altogether and instead use ASTs. All libSBML methods that accept text-string mathematical formulas have variants that accept ASTs instead.

Differences in XML parser behavior

The different parsers supported by libSBML (Xerces, Expat, libxml2) behave slightly differently when reading files, and the differences are difficult for libSBML to hide. The following are the differences of which we are currently aware:

  1. Libxml2 version 2.6.16 on Mac OS X, which is the default version of libxml installed on Macs in /usr/lib up through at least Mac OS 10.5.8, fails to report uses of undefined namespaces in an XML document. This means that a construct such as n:attribute, where n is a namespace prefix that is not defined, will be silently ignored. As a result, libSBML cannot catch and report this error when libSBML has been configured with this version of libxml2. We know of no workaround at this time if you are using a system with libxml2 2.6.16, except to compile your own copy of libxml2 or use another parser library. (Incredibly enough, libxml 2.6.16 built from original sources on a Mac does report the error. The only explanation is that that Apple ships a modified version of libxml 2.6.16 in versions of the operating system up through 10.5.8.)
  2. Expat and libxml2 tend to quit earlier than Xerces when they encounter an XML error in an input stream, whereas Xerces tends to process the input further and report an error as being on the element in which the XML error occurs. The result is that the first error reported by libSBML is sometimes different depending on which of the underlying XML parsers is being used. In our tests, this affects almost exclusively low-level XML syntax errors (such as start/end tag mismatches, unterminated strings) and not SBML errors per se, although a basic XML error can of course mask other, more substantive errors. The exceptional cases (the reason for the "almost" in the previous sentence) concern SBML Level 2 Versions 3 and 4 validation rules 10309 (detection of metaid syntax), and rules 10802, 10803, 21004 and 21005 (detection of disallowed XML constructs inside <notes> and <annotation> elements).
  3. Some versions of libxml2 behave incorrectly when given a blank namespace (e.g., the use of xmlns=" ", with a space character). Versions of libxml prior 2.7.7 will report this as an invalid or undefined XML namespace, but in fact a namespace URI containing a single space is valid (albeit not a very useful one). This highlights another issue: different versions of the underlying XML parsers may behave differently in the face of unusual (though not necessarily illegal) inputs.
  4. Expat 2.1.0 appears to have a configuration issue. If CMake is used to compile the Expat library but GNU configure is used to configure libSBML, configure will report the following:
    checking for Expat version >= 1.95.8... 
    *** The Expat header file (version 2.1.0) does not match
    *** the Expat library found (version 2.0.1).
    
    However, if the GNU ./configure, make & make install are also used to build the Expat library (i.e., instead of using CMake for them), the header mismatch is avoided.

Cannot report a failure of validation rule #10312

The SBML Level 3 Version 1 Core specification defines validation rule #10312 as being The value of a "name" attribute must always conform to the syntax of type string. Unfortunately, given the way that all three XML parser libraries (libxml2, Expat, and Xerces) work, it is impossible for libSBML to ever report this error directly. The kinds of SBML input that would lead to a failure of this validation rule cause the XML parsers to report overly general errors of the "XML content not well formed" variety, and libSBML cannot determine the true root cause. As a result, libSBML cannot detect when rule #10312 is breached.

Different error number (either 20413 or 20409) may be reported depending on Level of SBML in use

In SBML Level 3 Version 1 Core, validation rule #20413 (concerning whether the ListOfUnits container element can be empty) subsumes what was validation rule #20409 in the specifications for SBML Level 2 Versions 2–4. Rule #20409 does not exist in Level 3. The consequence of this difference in the specifications is that an application may receive different validation error numbers for the same situation depending on whether it is dealing with a Level 2 or a Level 3 model.

Possible unexpected make uninstall behavior

The libSBML make uninstall command on Linux, Mac OS, Cygwin, and Solaris only knows about the features most recently configured into libSBML. If you run configure, then make install, then run configure again with different options, and finally try make uninstall, the result will be to attempt removing the files implied by the most recent run of configure, not the files installed by the original make install.

Conversion to/from SBML Level 1 Version 1 is not supported

The method setLevelAndVersion() on the class SBMLDocument performs conversion between versions and levels of SBML (to the extent possible within technical and practical limits). However, conversion to/from SBML Level 1 Version 1 is not supported.

Line/column numbers are not always accurate

LibSBML includes methods to report the line and column number where an object or an error situation appears in a file. However, the accuracy of the line and column numbers cannot be guaranteed by libSBML. Many factors affect how accurate the line/column information ultimately is. For example, sometimes, the underlying XML parsers can only report such information for the parent XML element where an error occurs, and not for the specific point where the problem occurs. In other situations, some parsers report invalid line and/or column numbers altogether. If this occurs and libSBML can detect that it has occurred, the line and/or column number reported by SBMLError and XMLError will be set to either 0 or the value of the maximum unsigned long integer representable on the platform where libSBML is running. The probability that a true line or column number in a real-life SBML model would equal this value is vanishingly small; thus, if an application encounters these values in an XMLError object, it can assume no valid line/column number could be provided by libSBML in that situation.

Sometimes, the libsbml_wrap.cpp files are not recreated

Many of the language bindings in libSBML are created using SWIG, a language wrapper generator. The output of SWIG for libSBML is a file named libsbml_wrap.cpp in the respective language binding's subdirectory (e.g., src/bindings/java), sometimes in combination with other files, depending on the language in question. If you obtained your copy of libSBML as a distribution archive (e.g., from GitHub), this file will already be present in the distribution. If, instead, you obtained your copy of libSBML from the SVN source tree, you will need to have SWIG available on your system in order to regenerate the libsbml_wrap.cpp file. In both cases, all things should work fine.

If you modify the libSBML source files yourself (and in particular, files upon which the SWIG binding code depends), the makefile rules should always automatically cause the appropriate libsbml_wrap.cpp files to be recreated. However, sometimes the makefile rules do not regenerate the wrapper files when they should. This happens very rarely, and under conditions that the libSBML developers have had a very hard time reproducing consistently. In some versions of libSBML, it seemed to happen slightly more often under cygwin.

When a version skew occurs with the language binding wrapper files, either the compilation phase or the link phase will fail, often with cryptic and mysterious errors about missing methods. Often it is possible to guess that the language bindings are the problem from the error messages.

The solution is to delete the libsbml_wrap.cpp file(s), and when the Java interface is involved, also delete the src/bindings/java/java-files subdirectory. Re-running make will regenerate the files and (if the problem was indeed due to the SWIG binding files being out of date) compilation/linking will work.

We emphasize that this problem should not affect normal users of libSBML, only the libSBML developers and those are are venturing into developing new features in libSBML.

Some libsbml_wrap.cpp files produce compile-time warnings

As mentioned above, many of the language bindings in libSBML are created using SWIG, a language wrapper generator. The output of SWIG for libSBML is a file named libsbml_wrap.cpp in the respective language binding's subdirectory (e.g., src/bindings/java).

In some cases, the libsbml_wrap.cpp file produced by SWIG will cause compilers to issue warnings during compilation. The following is an example from the Ruby language bindings compiled on Mac OS X 10.9 using plain make:

libsbml_wrap.cpp:4802:13: warning: unused variable 'r' [-Wunused-variable]
      VALUE r = Qnil;
            ^
libsbml_wrap.cpp:4957:9: warning: unused variable 'type' [-Wunused-variable]
  VALUE type = TYPE(obj);
        ^

The warnings are about harmless issues. Unfortunately, there is very little that libSBML can do about these warnings, since they come from code auto-generated by SWIG.

Difficulty configuring libSBML with MacPorts version of libcheck under Mac OS X 10.6

If you are using the GNU Makefile approach to configuring libSBML, and attempt to configure libSBML 5.x for certain combinations of language bindings under MacOS 10.6 (aka "Snow Leopard"), it can become a real challenge to achieve binary compatibility for all libraries concerned. A case in point is attempting to build 32-bit MATLAB bindings simultaneously with the Check library (libcheck), which some Mac OS X users will have installed using the MacPorts system. Unless you build libcheck as a universal binary, here's what will probably happen when you run the libSBML configure program:

  1. Upon running configure with options such as --with-matlab=/Applications/MATLAB_R2010a.app --with-check=/opt/local, you will get the following error:
    libSBML needs to be built explicitly to include a 32-bit (i386) version, 
    because your copy of MATLAB is a 32-bit version.  By default, MacOS 10.6+ 
    (Snow Leopard) builds everything as 64-bit (x86_64) binaries.  Please add 
    either 
        --enable-m32 
    or 
        --enable-universal-binary="-arch i386 -arch x86_64" 
    to your configure options, re-run the configure step, and recompile.  If 
    you get a compilation error, please check whether you have a private 
    version of a dependent library (e.g., expat, libxml, or xerces) that was 
    built only as a 64-bit version, and either remove, recompile or replace it 
    it before proceeding further. 
    
  2. If you then proceed to add the universal binary flag as suggested, configure will quit with a different error:
    checking for Check version >= 0.9.2... *** Could not run Check test program, trying to find out why... 
    *** The test program compiled, but did not run.  This usually 
    *** means that the run-time linker is not finding libcheck, but 
    *** could also be the result of mixing binary architectures 
    *** (e.g., trying to use a 32-bit check library while compiling 
    *** in a 64-bit environment).  At this point, it is best to 
    *** look in the file 'config.log' for clues about what happened. 
    *** 
    *** If the problem is due to the first issue, will may need 
    *** to set your LD_LIBRARY_PATH environment variable, or 
    *** edit /etc/ld.so.conf to point to the installed 
    *** location, and also run ldconfig if that is required on 
    *** your operating system.  If the problem is due to the 
    *** second (mixing architectures), you may need to obtain a 
    *** different copy of libcheck or recompile it for this 
    *** machine architecture. 
    *** 
    *** If you have an old version of Check installed, it is best 
    *** to remove it, although you may also be able to get things 
    *** to work by modifying you value of LD_LIBRARY_PATH.
    

Here's what's happening. MacOSX 10.6 builds 64-binary objects by default, and both the MATLAB R2010a installation and MacPort's libcheck are 32-bit binaries. If you enable libSBML's universal binary flag, it will fix the MATLAB compatibility issue, but at the point where libSBML attempts to test linking with libcheck, it discovers that libcheck is not available as a universal binary, and so the test fails.

The simplest solution is to use a universal (fat) binary version of libcheck. You can do this in two ways: build your own copy of the Check library from the source distribution, or reconfigure your MacPorts installation to build universal binaries and then recreate libcheck. If you choose the former option (building from the Check sources), the following configuration command for Check should work (including the backslash in the first line):

env CFLAGS="-arch ppc -arch i386 -arch x86_64" \
LDFLAGS="-arch ppc -arch i386 -arch x86_64"  \
./configure --with-pic --with-gnu-ld --disable-dependency-tracking

If, instead, you choose the latter route (changing your MacPorts configuration and reinstalling its version of libcheck), here are the steps to do that:

  1. (If you have already installed MacPorts' libcheck) Uninstall libcheck using sudo port uninstall check.
  2. (Re)build libcheck using the command sudo port install check +universal.

After doing the above, you should be able to re-run libSBML's configure with the MATLAB and libcheck flags, and it should successfully configure libSBML.

MATLAB on Windows has issues with unicode filenames

Using MATLAB on a Windows system unicode filenames can prove problematic. There appears to be an issue with MATLAB failing to correctly pass along such filenames when typed directly into the workspace. It is possible to use unicode filenames directly via the dialogs that OutputSBML / TranslateSBML open up; but only if the relevant executable and the file are in the same directory.

Parallel builds with GNU make are not supported

Parallel GNU make builds of libSBML are not supported at this time. Attempting to use the -j option with make will not work properly and will not complete, but will also not produce diagnostics that indicate the cause of the failure (thus making it difficult to understand what went wrong). Do not use the -j option with GNU make.

Bug in GCC 5.1 and 5.2 causes free() errors in Python interface

There is a known bug in GCC versions 5.1 and 5.2 which results in the problem that calling the copy constructor of a base class in the constructor of derived classes produces crashing code. The problem manifests itself in libSBML when using a language binding such as the Python interface, and leads to the following error:
>>> from libsbml import *
>>> reader = SBMLReader()
>>> doc = reader.readSBML('MODEL1504280000_URNs.xml')
*** Error in `python': free(): invalid pointer: 0x00007ffda7deb2a8 ***
Aborted (core dumped)
There are four work-arounds for this problem:
  1. Do not use gcc versions 5.1 or 5.2 (use a different version).
  2. Use the clang compiler instead of gcc.
  3. Use gcc with the option -D_GLIBCXX_USE_CXX11_ABI=0.
  4. Use gcc with the option -fno-elide-constructors.
 Working with mathThis section describes libSBML's facilities for working with SBML representations of mathematical expressions
 Additional complete example programsThe libSBML distribution comes with the following selection of complete example programs in the top-level file directory named examples/csharp
 Mathematical Expressions and their ManipulationThis section describes libSBML's facilities for working with SBML representations of mathematical expressions
 Reading and writing SBML content from your softwareThis section summarizes how to read and write SBML content using the facilities provided by the libSBML C# API