file: 00README		G. Moody and G. Clifford	30 November 2003
			Last revised:			 1 December 2007
WFDB_tools quick start

This package of software was written by Jonas Carlson, who has contributed it
to PhysioNet for free use and redistribution.  The WFDB_tools package allows
Matlab R13 users to use the WFDB library to read and write digitized signals
and annotations such as those available from PhysioNet.

Version 0.5.3.1 differs from 0.5.3 only in that a missing 'n' that caused a
compilation error in example4.m has been added to that file, and additional
instructions have been added to those in step 4b for Linux, MacOS X, and Unix
users below; thanks to David Linker for both of these changes.  If you have
previously installed version 0.5.3 successfully, it is not necessary to update
your installation to 0.5.3.1.

These notes provide a highly condensed set of instructions for installing
WFDB_tools under MS-Windows, Linux, MacOS X, and other versions of Unix.
(Installation has been tested under Linux, MacOS X 10.4.10, and MS-Windows XP
only.)  Please see
	http://www.physionet.org/physiotools/matlab/wfdb_tools/
for further information about this software.

Under MS-Windows:

1.  Install the Cygwin software package, following the instructions at
	http://cygwin.com/ 

    Install Cygwin in a location that does not have any spaces in its
    pathname. The default and preferred location is c:\cygwin. Do not use
    locations under "Program Files", "Documents and Settings", or any other
    directory containing a space in its name. Be sure to select and
    install the gcc, binutils, make, and perl packages from the Devel category
    (these are not installed by default in a minimal Cygwin installation).

    (This procedure has been tested using Cygwin 1.5.5;  if you have an
    older version previously installed, we recommend updating it to 1.5.5
    or later.)

2.  Install the WFDB software package, version 10.4.1 or later, following
    the instructions at
	http://www.physionet.org/physiotools/wfdb-windows-quick-start.shtml
    If you will be using Matlab R14 or later, install the standard (Cygwin)
    version first, then install a set of native Windows binaries as described
    near the end of the Windows quick start guide.

3.  Install Matlab R13 or later if you have not already done so.  These
    wrappers will not work with older versions of Matlab.

4.  If you have not already done so, download
	http://www.physionet.org/physiotools/matlab/WFDB_tools.tar.gz

     In a Cygwin window, navigate to the directory containing WFDB_tools.tar.gz
     and unpack it by running the command
	tar xfvz WFDB_tools.tar.gz
     This command creates a new directory named WFDB_tools-X.Y.Z, where
     X, Y, and Z depend on the version number of the package you have
     downloaded.  For example, the name is WFDB_tools-0.5.3 for version 0.5.3.

     Enter this directory by typing
	cd WFDB_tools-0.5.3
     (or whatever version is correct).  In the following steps, "this
     directory" means your local copy of the WFDB_tools-X.Y.Z directory
     (which is the current directory if you have followed these instructions).
     
You can use the precompiled .dll files provided in the "windows" directory, or
you can recompile them from the .c sources provided in the "src" directory.
Choose only one of steps 5a and 5b:

5a. [To use the precompiled .dll files]  Copy all of the files from the
    "windows" and "help" directories into this directory.

5b. [To recompile the .dll files from the .c sources]  Copy all of the files
    from the "src" and "help" directories into this directory.

    Install gnumex following the instructions at
	http://gnumex.sourceforge.net/

    Be sure to start Matlab from within a Cygwin terminal emulator to
    ensure that the environment variables are set appropriately before
    running the gnumex configuration script from the Matlab prompt.  Accept
    the defaults offered by gnumex (Cygwin linking, generate mex dll, use
    C/C++ for compilation, safe compile) to create mexopts.bat.  Copy
    mexopts.bat into the directory containing the WFDB_tools files (where
    this README is located).

    Edit the copy of mexopts.bat, changing the line that sets GM_ADD_LIBS
    (below "Added libraries for linking") so that it reads:
	set GM_ADD_LIBS=wfdb-10.4.dll

    At the Matlab prompt, add paths corresponding to cygwin, gnumex and wfdb:
	addpath C:\cygwin
	addpath C:\gnumex
	addpath C:\cygwin\opt\wfdb\bin
    (substituting the locations where these packages are installed on your
    system).

    Finally, ensure that your current directory is the one that contains this
    README file, and run:
	make_WFDB_dlls
    within Matlab to compile the WFDB_tools dlls.

6.  To be able to use the WFDB_tools from any directory, add the directory
    containing the WFDB_tools dlls to your path, by typing at the Matlab
    prompt:
	addpath C:\WFDB_tools
    (substituting the name of the directory containing the .dll files).

7.  Test the WFDB_tools by running "example.m" (in the "examples" directory)
    from the Matlab prompt.

Under Linux, MacOS X, or Unix:

Unix users, please note: We believe that the following procedure
should work for you, but it has been tested only under GNU/Linux and MacOS X.
Please let us know if you try it on another platform.  We would
appreciate success reports as well as problem reports; please be sure
to tell us what versions of your OS, the WFDB software package, and
the WFDB_tools package you have used.

1.  Install the WFDB software package, version 10.4.1 or later, following
    the instructions at
	http://www.physionet.org/physiotools/wfdb-linux-quick-start.shtml
    (look in http://www.physionet.org/physiotools/wfdb.shtml for pointers
    if your platform is not GNU/Linux).

2.  Install Matlab R13 or later if you have not already done so.  These
    wrappers will not work with older versions of Matlab.

3.  If you have not already done so, download
	http://www.physionet.org/physiotools/matlab/WFDB_tools.tar.gz

     In a terminal window, navigate to the directory containing
     WFDB_tools.tar.gz and unpack it by running the command
	tar xfvz WFDB_tools.tar.gz
     This command creates a new directory named WFDB_tools-X.Y.Z, where
     X, Y, and Z depend on the version number of the package you have
     downloaded.  For example, the name is WFDB_tools-0.5.3.1 for version
     0.5.3.1.

     Enter this directory by typing
	cd WFDB_tools-0.5.3.1
     (or whatever version is correct).  In the following steps, "this
     directory" means your local copy of the WFDB_tools-X.Y.Z directory
     (which is the current directory if you have followed these instructions).

You may be able to use the precompiled .mexglx files provided in the "linux"
directory (compiled under Red Hat Linux 9 for the x86 platform, using gcc
version 3.2.2).  If you have a different platform, you will need to compile
.mexglx files for your platform from the .c sources provided in the "src"
directory.  Choose only one of steps 3a and 3b:

4a. [To use the precompiled .mexglx files]  Copy all of the files from the
    "linux" and "help" directories into this directory.

4b. [To recompile the .mexglx files from the .c sources]  Copy all of the files
    from the "src" and "help" directories into this directory.  Find the
    location of the "mex" compiler and add it to your PATH; for example, on
    Mac OS X 10.4.10, the "mex" compiler for Matlab R2007b will probably be
    in /Applications/MATLAB_R2007b/bin, so (in a terminal window) type
	PATH=/Applications/MATLAB_R2007b/bin:$PATH
    The location will vary, depending on your installation, so substitute the
    actual location of your "mex" in the command above before running it. Then,
    in the same window, type these commands from within this directory:
	make clean
	make

5.  To be able to use the WFDB_tools from any directory, add the directory
    containing the compiled WFDB_tools files to your path, by typing at the
    Matlab prompt:
	addpath /home/fred/WFDB_tools
    (substituting the name of the directory containing the .mexglx files).

6.  Test the WFDB_tools by running "example.m" (in the "examples" directory)
    from the Matlab prompt.

If you are successful in compiling and using these wrappers under any
platform other than GNU/Linux, Mac OS X, or MS-Windows, please let us know
about it!
