========== libSBML C# API ==========

----------------------------------------------------------------------
1. Authors
----------------------------------------------------------------------

* Frank Bergmann (fbergman@u.washington.edu)
* Akiya Jouraku  (jouraku@bio.keio.ac.jp)

----------------------------------------------------------------------
2. Description
----------------------------------------------------------------------

This module provides C# application programming interface (API) for 
libSBML library. 
Most of the native C++ classes/functions (except for classes/functions
used for internal use) are wrapped by using SWIG (http://www.swig.org).

Currently, the reference documentation for libSBML C# API is not available
due to the lack of support for automatically generating the C# API
documentation from C++ header files.
However, since the libSBML C# API is very similar to the libSBML Java API, 
the Java API documentation (*) may be helpful as a guide for using the
libSBML C# API until the documentation of C# API has been written. 

 ---------------------------------------------------
 (*) http://sbml.org/Software/libSBML/docs/java-api/
 ---------------------------------------------------

----------------------------------------------------------------------
3. Building
----------------------------------------------------------------------

===========
(Windows)
===========

  ------------------------------------------------------------------
  (NOTE) Currently, libSBML C# API is not supported on Cygwin/MinGW.
  ------------------------------------------------------------------ 

  This directory contains the following solution files for Microsoft 
  Visual Studio which load all the relevant projects below.

    [for Visual Studio 2005 or later]

      CSharp_binding_win32-expat.sln
      CSharp_binding_win32-libxml.sln
      CSharp_binding_win32-xerces.sln

    [for Visual Studio 2003 or later]

      CSharp_binding_win32-expat-vs2003.sln
      CSharp_binding_win32-libxml-vs2003.sln
      CSharp_binding_win32-xerces-vs2003.sln

  By using each solution file, you can build two DLL files ("libsbmlcs.dll"
  and "libsbmlcsP.dll") required for building and running a program using 
  libSBML C# API.

  The following softwares are required to build the DLL files by using
  the above solution files:


   ----------------------------------------------------------------- 
   1) Microsoft Visual Studio 2003 or later
   2) One of the following XML parser libraries

      1. Xerces (http://xerces.apache.org/xerces-c/)
      2. Expat  (http://sourceforge.net/projects/expat/)
      3. LibXML (http://xmlsoft.org/)

   3) Zlib  (http://zlib.net/)  
            (http://www.winimage.com/zLibDll/)

   4) Bzip2 (http://www.bzip.org/)
            (http://gnuwin32.sourceforge.net/packages/bzip2.htm)
   ----------------------------------------------------------------- 


  Each of the following Visual C++ project files builds a native C++ DLL 
  file ("libsbmlcs.dll") which is required to run a program using libSBML
  C# API.
  Each project file builds the DLL file with a different underlying XML 
  parser (Xerces, Expat, or LibXML2)

    [for Visual C++ 2005 or later]

      CSharp_binding_win32-expat.vcproj   (uses Expat)
      CSharp_binding_win32-libxml.vcproj  (uses LibXML2)
      CSharp_binding_win32-xerces.vcproj  (uses Xerces)

    [for Visual C++ 2003 or later]

      CSharp_binding_win32-expat-vs2003.vcproj  (uses Expat)
      CSharp_binding_win32-libxml-vs2003.vcproj (uses LibXML2)
      CSharp_binding_win32-xerces-vs2003.vcproj (uses Xerces)


  Each of the following Visual C# project files builds a C# DLL file 
  ("libsbmlcsP.dll") which is required to build or run a program 
  using libSBML C# API.

      CSharp_binding_cspDLL.csproj        (for Visual C# 2005 or later)
      CSharp_binding_cspDLL-vs2003.csproj (for Visual C# 2003 or later)

  The C# DLL file provides libSBML C# API (the C# proxy classes internally
  invoke a corresponding native C++ wrapper function to use the corresponding 
  libSBML C++ API.)

  Each of the following Visual C# project files builds a simple test program
  ("TestRW.exe") which reads/writes SBML files by using libSBML C# API.

     CSharp_binding_TestRW.csproj        (for Visual C# 2005 or later)
     CSharp_binding_TestRW-vs2003.csproj (for Visual C# 2003 or later)

  This directory contains a batch file ("runTestRW.bat") which runs the 
  test program.
  ("runTestRW.bat" may need to be modified. See the file for the detail.)

  The following Visual C# 2005 project file builds a test runner program
  ("libSBMLCSTestRunner.exe") which internally compiles the libSBML C# test
  files located in "test" directory and runs each test program.

    libSBMLCSTestRunner-vs2005.csproj

  This directory contains a batch file ("runTestRunner.bat") which runs the 
  test runner program.
  ("runTestRunner.bat" may need to be modified. See the file for the detail.)


==================================================
(Linux,  MacOSX, and other UNIX-based platforms)
==================================================

libSBML C# API can also be used on non-Windows platforms. 

Currently, we recommend to use Mono C# (http://www.mono-project.com/Main_Page) 
to build libSBML C# libraries/programs and to run the programs using the
libSBML C# API on non-Windows platforms.

 (NOTE: Currently, libSBML C# API doesn't seem to work with Portable.NET.)

You can build and install libSBML C# library files as follows: 

  1) Run configure script (in the top directory of libSBML source tree) 
     with "--with-csharp" option.


       % ./configure --with-csharp ...


     You may need to set a base directory path to your installed Mono C#
     (e.g. --with-csharp=/usr/local/) if the Mono C# is not installed in 
     the system directory.

    "--with-swig" option is also required if you want to recreate SWIG
    generated wrapper files for libSBML C#.


  2) Run make.

       % make

     The following two shared library files will be generated in this
     directory if the build succeeds.
     
       1) libsbmlcs.so 
          - C++ shared library file which provides wrapper functions for
            libSBML C# API
          - required when running a program using libSBML C# API
 
       2) libsbmlcsP.dll
          - C# DLL file which provides libSBML C# API (The C# proxy classes
            internally invoke a corresponding native C++ wrapper function
            (provided by the "libsbmlcs.so") to use the corresponding
             libSBML C++ API.).
          - required when building or running a program using libSBML C# API

     If the configure script was invoked with "--with-check" option, you can
     build and run two test programs (TestRW.exe and TestRunner.exe) by
     running "make check".


  3) Run make install.

      % make install

     The two library files will be installed in ${prefix}/lib/mono/libsbmlcsP/
      directory.
     (By default (without --prefix option), the prefix is /usr/local/.)
      

----------------------------------------------------------------------
4. Introduction
----------------------------------------------------------------------

Here is a simple example that reads an SBML file and prints any errors
encountered.

======================================================
namespace LibSBMLExample
{
  using libsbml;
  using System;

  public class Example
  {
    public static void Main (string[] args)
    {
      // read an SBML file
      SBMLReader   reader  = new SBMLReader();
      SBMLDocument sbmlDoc = reader.readSBML(args[0]);

      // get the number of errors
      long errors = sbmlDoc.getNumErrors();

      Console.WriteLine(" filename: {0}", args[0]);
      Console.WriteLine(" error(s): {0}", errors );

      if ( errors > 0)
      {
        // print errors
        sbmlDoc.printErrors(libsbml.cerr); 
      }
      Environment.Exit(errors);        
    }
  }
}
========================================================

The code implements a "Example" class in a "LibSBMLExample" namespace.

First, "using libsbml" directive is used to permit the use of types in
the "libsbml" namespace (the namespace of libSBML C# module) without
qualification in the "LibSBMLExample" namespace.

Next, in the body of the Main function, the line


  SBMLReader   reader  = new SBMLReader();


creates an SBMLReader object which is used to read an SBML file.
The next line


  SBMLDocument sbmlDoc = reader.readSBML(args[0]);


reads the given SBML file and sets a returned SBMLDocument object.
libSBML uses the class SBMLDocument as a top-level container for
storing SBML content and data associated with it (such as warnings and
error messages).
A subsequent call to the SBMLDocument.getNumErrors() method returns
the number of errors encountered (if any), and the call to
SBMLDocument.printErrors() mehtod prints them to the standard error
output stream.


----------------------------------------------------------------------
5. Compiling/Running a C# program with libSBML C# API
----------------------------------------------------------------------

==============
(Windows)
==============

You can build a C# source file which uses libSBML C# API by using Microsoft
Visual C# on Windows.
The libSBML C# DLL ("libsbmlcsP.dll") is required to compile the C# source
file.

You need to put required DLLs in your DLL search path to run a
executable file which uses libSBML C# API. The required DLLs are the
libSBML C# DLL file ("libsbmlcsP.dll"), the native C++ DLL file
("libsbmlcs.dll") and other DLL files (zlib1.dll, bzip2.dll, and a
corresponding DLL file for the underlying XML parser.)

=================================================
(Linux, MacOSX, and other UNIX-based platforms)
=================================================

You can build a C# source file which uses libSBML C# API by using Mono C#
compiler on Linux, MacOSX and other UNIX-based platforms.

For example, you can build a C# source file ("Test.cs") and generate an 
executable file ("Test.exe") as follows:


  % gmcs -target:exe -out:Test.exe -r:libsbmlcsP.dll Test.cs

    (NOTE: the "mcs" compiler can also be used to compile against the C# 1.0 
     and 2.0 code with the exception of generics and nullable types.
     Please see the man page of "mcs" for the detail.)


You may need to use "-L" option to set the path to a directory in which 
"libsbmlcsP.dll" located if the file is not installed in the system directory.

You can run the executable file by using "mono" command.
For example, you can run the executable file ("Test.exe") as follows:


  % mono Test.exe 


You must make sure the following configurations to run the executable file:

  1) make sure that "libsbmlcsP.dll" is located in the same path to the
     executable file.

     Alternatively, you can use an environment variable "MONO_PATH" to set
     the path to "libsbmlcsP.dll". However, this solution is not recommended 
     by Mono development team because it breaks the assembly loader in subtle 
     ways. See the man page of "mono" for the detail.

  2) make sure that your dynamic library search path variable includes the
     directory in which the "libsbml.so" ("libsbml.dylib" on MacOSX) and 
     "libsbmlcs.so" are located.

     As an example, if you were running under Linux and you configured
     libSBML with a prefix of '/usr/local' and did a normal "make install",
     and you were using the typical sh or bash shell in your terminal, you
     would need to execute

        export LD_LIBRARY_PATH="/usr/local/lib/mono/libsbmlcsP:$LD_LIBRARY_PATH"

     ('DYLD_LIBRARY_PATH' is used instead of 'LD_LIBRARY_PATH' on MacOSX.)

     or put the above in your shell's initialization file (.bashrc or
     .profile in your home directory) and cause the shell to re-read the
     initialization file. 

----------------------------------------------------------------------
6. Example programs
----------------------------------------------------------------------

You can find example C# programs which use libSBML C# API in
"examples/csharp/" directory.

Also, you can find C# programs used for unit tests in the "test" 
directory in this directory.

----------------------------------------------------------------------
7.  Licensing, Copyrights and Distribution
----------------------------------------------------------------------

The terms of redistribution for this software are stated in the files
LICENSE.txt and  COPYING.txt at the top level of the libSBML distribution.


-----------------------------------------------------------------------------
Last Modified: $Date: 2009-01-03 18:26:05 -0800 (Sat, 03 Jan 2009) $
Last Modified By: $Author: mhucka $
$HeadURL: http://sbml.svn.sourceforge.net/svnroot/sbml/trunk/libsbml/src/bindings/csharp/00README.txt $
-----------------------------------------------------------------------------

