file: 00README		G. Moody and G. Clifford	30 November 2003
			Last revised:			29 November 2004
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.

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 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.3.11 or later, following
    the instructions at
	http://www.physionet.org/physiotools/wfdb-windows-quick-start.shtml

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-cyg-10-3.dll

    At the Matlab prompt, add paths corresponding to cygwin, gnumex and wfdb:
	addpath C:\cygwin
	addpath C:\gnumex
	addpath C:\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.  [Optional] Install GTKWave (a WFDB application for interactively viewing,
    editing, and analyzing signals and annotations) following the instructions
    at
	http://www.physionet.org/physiotools/beta/gtkwave/
    The next step will make use of GTKWave if it has been installed.

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

Under Linux, MacOS X, or Unix:

Mac OS X and Unix users, please note:  We believe that the following procedure
should work for you, but it has been tested only under GNU/Linux.  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.3.11 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 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 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, then type these
    commands in a terminal window 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 or MS-Windows, please let us know about it!
