This 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
- Some versions of MATLAB include a conflicting version of libstdc++
- Explicit freeing of memory when using static MSVC runtimes
- Name collisions in mathematical expressions
- Differences in XML parser behavior
- Cannot report a failure of validation rule #10312
- Different error number (either 20413 or 20409) may be reported depending on Level of SBML
- Possible unexpected `make uninstall` behavior
- Conversion to/from SBML Level 1 Version 1 is not supported
- Line/column numbers are not always accurate
- Sometimes, the libsbml_wrap.cpp files are not recreated
- Some libsbml_wrap.cpp files produce compile-time warnings
- Difficulty configuring libSBML with MacPorts version of libcheck under Mac OS X 10.6
- MATLAB on Windows has issues with unicode filenames
- Parallel builds with GNU `make` are not supported
- Bug in GCC 5.1 and 5.2 causes `free()` errors in Python interface

## 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 SourceForge), 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`.