file: README		I. Henry and G. Moody	23 August 2005
			Last revised:		12 July 2011

Name: wfdb-swig

NOTICE: This release is BETA software; use it at your own risk!  In particular
note that the wrappers for the .NET languages must be compiled manually, and
the documentation has not been completely updated to reflect the current status
of this package.  This version has been released to coincide with the release
of version 10.5.x of the WFDB Software Package, which should be installed on
your system in order to make successful use of the wfdb-swig package.

Purpose:

Wrappers are fragments of "glue code" that allow functions or subroutines
written in one language to be invoked by code written in another ("target")
language.

The WFDB library (http://physionet.org/physiotools/wfdb.shtml) is a collection
of specialized functions that provide uniform access to digitized signals and
annotations in a wide variety of formats, including those in PhysioBank
(http://physionet.org/physiobank/).  The WFDB library is written in C and
includes bindings for C++ and wrappers for Fortran.

The wfdb-swig package provides wrappers that permit programs written in several
other programming languages to use the WFDB library.  The wrappers are
generated automatically using the Simplified Wrapper Interface Generator
(SWIG).  Tested target languages include Perl5, Python, and Java; previous
versions also were successfully tested with .NET languages (C# and Visual
Basic), but the current version of libtool may be incompatible with the
existing code for compiling WFDB SWIG wrappers for C#.

It may also be possible to generate wrappers for other languages
supported by SWIG, including Guile, mzScheme, Octave, PHP, Ruby, and Tcl.

Matlab wrappers are not provided by this package, but the WFDB Toolkit for
Matlab (http://physionet.org/physiotools/matlab/wfdb-swig-matlab/) uses
the Java wrappers from Matlab.

Authors: 

Isaac Henry (ihenry@physionet.org), George Moody (george@physionet.org)

Background literature:

The SWIG web site (http://www.swig.org/)
The WFDB Programmer's Guide (http://www.physionet.org/physiotools/wpg/)

Platforms:

GNU/Linux (development) Mac OS X, MS Windows.  Other platforms supported by
SWIG should also work but have not been tested.

Code organization:

The SWIG interface file wfdb.i defines the WFDB API and provides the
information needed by SWIG to create the wrappers.  The generated
wrapper code for each language is stored in a subdirectory (wfdb-java,
wfdb-perl, etc.) together with other files needed for that language.  See the
README files in the language-specific subdirectories for details.

URLs:
The supported version of the WFDB-SWIG package is hosted on PhysioNet, at
    http://physionet.org/physiotools/wfdb-swig.shtml
Development versions are also available at
    http://code.google.com/p/wfdb-swig/

Installation:

See INSTALL in this directory.

Testing:

The C programming examples from the WFDB Programmer's Guide have been
translated to each tested language and are located in the 'examples'
directory.  To test the wrappers after installing them, use 'make check'
as described in INSTALL, or test them more extensively by comparing the outputs
of these examples against those of the original C examples, which are included
in the 'examples' directory of the WFDB Software Package.

Further work:

Updating/modifying the wrappers

The wrappers will need to be regenerated for new versions of WFDB if the WFDB
API changes in any way, such as by addition of new public functions, constants,
macros, or data types.  Such changes are signalled by a new major or minor
WFDB version number (for example, the wrappers need to be regenerated when
upgrading from WFDB 10.3.x to 10.4).  Versions that differ by release number
only (e.g., 10.4.0 and 10.4.1) share the same API and can use the same set of
wrappers.

When using the normal installation procedure (see INSTALL), the wrappers are
regenerated automatically by SWIG as needed, based on the contents of the SWIG
interface file, wfdb.i.  Language-specific interface files may also be located
in each subdirectory (e.g. wfdb-java/javadoc.i). Source files (*.c, *.java,
*.cs, *.py, and so on) are auto-generated by SWIG and should not be edited
manually UNDER ANY CIRCUMSTANCES.

Since wfdb.i includes wfdb.h (the C-language WFDB library API), new or modified
functions, constants, and data types that may appear in new versions of the
WFDB library are picked up automatically, and no changes to the SWIG interface
files are required.  Macros, however, are not automatically wrapped by SWIG; if
necessary, they can be implemented as C functions in wfdb.i, as was done in
Isaac Henry's original version of these wrappers for use with WFDB library
version 10.3.  Beginning with WFDB library version 10.4, automatically
wrappable function equivalents are provided for all public macros, so it should
no longer be necessary to modify wfdb.i for this purpose.

Creating wrappers for other target languages

This package currently contains wrappers for Perl, Python, and Java.
Follow these examples to generate wrappers for other languages supported by
SWIG; if you are successful, please write to wfdb-swig@physionet.org to let us
know what you did and how you did it.

Language-specific documentation

At present SWIG does not support generation of language specific documentation
(such as javadoc).  Future versions of SWIG may add this functionality.