from PhysioNet, the research resource for complex physiologic signals


WFDB quick start for MS-Windows

(This document has been reorganized. The old version is still available here.)

There are several ways to install the WFDB Software Package on Windows. Read this section to find out about the differences!

We use and recommend gcc, the free GNU compiler collection, to build the package from sources. If you wish to use another compiler, you are on your own. Your feedback is welcome, but we do not use any commercial compilers, and we cannot help you learn how to use them.

Cygwin vs. MinGW: Two projects provide gcc on Windows. Cygwin is "a collection of tools that provide a Linux look and feel environment for Windows, using a DLL (cygwin1.dll) that acts as a Linux [POSIX] API layer providing substantial Linux API functionality." Building the WFDB Software Package using Cygwin assures that WFDB applications will behave on MS-Windows as much as possible like they do on other platforms. The entire WFDB Software Package, including WAVE, can be built easily under Cygwin.

MinGW, "a minimalist development environment for native MS-Windows libraries and applications", packages gcc without POSIX emulation. MinGW gcc can build a WFDB DLL that depends only on the native libraries provided with MS-Windows. You might need a native Windows version of the WFDB library if you wish to link it to other code that must also be linked with Windows native libraries. It is not possible to build or use WAVE on Windows without Cygwin, however, since it relies on the XView GUI toolkit, which is dependent on POSIX.

32 or 64 bits: The WFDB Software Package, except for WAVE, has been developed and used extensively in both 32-bit and 64-bit environments. On a 64-bit platform, it is possible to build and run either 32-bit or 64-bit WFDB executable binaries; on a 32-bit platform, only 32-bit binaries may be built or run. Since XView is a 32-bit toolkit, it is not possible to build a 64-bit WAVE, but it is possible to build and run a 32-bit WAVE with Cygwin/32 on either 32- or 64-bit Windows.

Both Cygwin and MinGW introduced 64-bit versions of their software in 2013, but neither of these is as complete or extensively tested as the 32-bit versions. We have not tested them ourselves, and we welcome feedback from users.

Source vs. precompiled: Binary packages are provided as a convenience and may not be up-to-date; we strongly recommend following the simple procedure described below for compiling the software from the sources instead. If you plan to compile WFDB applications that are not included in the binary package, please start with the sources, and read the note below. It is necessary to start with the sources if you wish to experiment with 64-bit versions of the WFDB software on Windows.

Click on your choice of the installation methods below:

Build from sources Install precompiled binaries
32-bit64-bit 32-bit64-bit
Cygwin/32
build and install
Cygwin/64
build and install
Cygwin/32
install from binaries
n/a
MinGW/32
build and install
n/a MinGW/32
install from binaries
n/a

You may need "administrator" permissions to install software on Windows, depending on configuration. Right-click on the installer or terminal icon and select "Run as administrator" to launch it.

Read the manuals. Really! :-) If you want to write your own software to work with PhysioBank data, begin with the WFDB Programmer's Guide. To learn about the wide variety of existing software that can be used to study PhysioBank data, read the WFDB Applications Guide and the WAVE User's Guide.

Cygwin/32 build and install (including WAVE)

  1. Install 32-bit Cygwin (version 1.7 or later) 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 curl, cygutils-extra, diffutils, gcc, gv, libX11-devel, libcurl-devel, libexpat-devel, make, openssl-devel, sunrpc, xview-devel, and X-start-menu-icons packages (these are not installed by default in a minimal Cygwin installation).

    If you are updating a previous Cygwin/32 installation of the WFDB Software Package, we recommend updating your Cygwin installation first, using Cygwin's setup-x86 tool.

  2. Open a Cygwin terminal window, and leave it open for the remainder of the steps below. To open a Cygwin window, either click on the Cygwin desktop icon, or find and run c:\cygwin\cygwin.bat. Perform the remainder of the installation by typing the commands as shown below into this window. Do not use an MS-DOS window for this purpose.
  3. Download and unpack the WFDB sources by typing this command:
    curl http://physionet.org/physiotools/wfdb.tar.gz | tar xvz
    
    This creates a directory with a name of the form wfdb-10.m.n within your working directory. Look at the list of files printed by the command above to determine the name of the directory for the next step.
  4. Enter the directory created in the previous step and configure the package:
    cd wfdb-10.m.n
    ./configure
    
    (In the cd command, replace wfdb-10.m.n with the name of the directory as printed by the previous command.)
  5. Compile and install the package:
    make install
    
    The binaries will be installed in /usr/bin (accessible from outside the Cygwin environment as c:\cygwin\usr\bin). Be sure that this bin directory is in your PATH.
  6. Test the package:
    make check
    
    This step compiles a short program that exercises the WFDB library, prints a summary of test results, and prompts you to press <Enter>. After you have done so, the WFDB applications are tested. The tests are very short (typically less than a second each), except that the last one (xform using NETFILES) may take up to a minute if you have a slow or inoperative Internet connection. If any application test fails, its output can be found in the checkpkg subdirectory of the WFDB source tree; compare this output with the files of the same names that can be found in the checkpkg/expected subdirectory.
  7. Make the WFDB library available for other applications:
    ln -sf /usr/bin/libwfdb.dll.a /usr/lib
    
  8. Test WAVE (see below).

Cygwin/64 build and install (excluding WAVE)

  1. Install 64-bit Cygwin (version 1.7 or later) 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 curl, cygutils-extra, diffutils, gcc, gv, libX11-devel, libcurl-devel, libexpat-devel, make, and openssl-devel packages (these are not installed by default in a minimal Cygwin installation).

    If you are updating a previous Cygwin/64 installation of the WFDB Software Package, we recommend updating your Cygwin installation first, using Cygwin's setup-x86_64 tool.

  2. Open a Cygwin terminal window, and leave it open for the remainder of the steps below. To open a Cygwin window, either click on the Cygwin desktop icon, or find and run c:\cygwin\cygwin.bat. Perform the remainder of the installation by typing the commands as shown below into this window. Do not use an MS-DOS window for this purpose.
  3. Download and unpack the WFDB sources by typing this command:
    curl http://physionet.org/physiotools/wfdb.tar.gz | tar xvz
    
    This creates a directory with a name of the form wfdb-10.m.n within your working directory. Look at the list of files printed by the command above to determine the name of the directory for the next step.
  4. Enter the directory created in the previous step and configure the package:
    cd wfdb-10.m.n
    ./configure
    
    (In the cd command, replace wfdb-10.m.n with the name of the directory as printed by the previous command.)
  5. Compile and install the package:
    make install
    
    The binaries will be installed in /usr/bin (accessible from outside the Cygwin environment as c:\cygwin\usr\bin). Be sure that this bin directory is in your PATH.
  6. Test the package:
    make check
    
  7. Make the WFDB library available for other applications:
    ln -sf /usr/bin/libwfdb.dll.a /usr/lib
    

Cygwin/32 install precompiled binaries (including WAVE)

  1. Install 32-bit Cygwin (version 1.7 or later) 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 curl, cygutils-extra, diffutils, gcc, gv, libX11-devel, libcurl-devel, libexpat-devel, make, openssl-devel, sunrpc, xview-devel, and X-start-menu-icons packages (these are not installed by default in a minimal Cygwin installation).

    If you are updating a previous Cygwin/32 installation of the WFDB Software Package, we recommend updating your Cygwin installation first, using Cygwin's setup-x86 tool.

  2. Open a Cygwin terminal window, either by clicking on the Cygwin desktop icon, or by finding and running c:\cygwin\cygwin.bat. Perform the remainder of the installation by typing the commands as shown below into this window. Do not use an MS-DOS window for this purpose.
  3. To install the precompiled binaries, type (or copy-and-paste) this two-line command into the Cygwin terminal window:
    curl http://physionet.org/physiotools/binaries/windows/wfdb-CYGWIN.tar.gz | \
      tar xvz -C /usr --strip-components=2
    
    Note that the '\' at the end of the first line indicates that the command continues on the next line. The command will not begin to run until you have entered both lines.

MinGW/32 build and install (excluding WAVE)

  1. Install MinGW and MSYS using the automated installer tool (mingw-get-inst, also called the "Graphical User Interface Installer" or the "GUI first time installer tool") following the instructions here. Be sure to select the option to use the latest available packages. Use the default installation directory (c:\mingw), and choose all of the optional components.
  2. Download the most recent curl source tarball from curl.haxx.se. As of November 2013, the most recent version was curl-7.33.0.tar.gz. Save it in your MinGW home directory (by default, c:\MinGW\msys\1.0\home\User).
  3. Download the most recent WFDB source tarball, and save it in your MinGW home directory.
  4. Open a MinGW terminal window by clicking on Start → Programs → MinGW → MinGW Shell. Perform the remaining steps of the installation by typing into this window. Do not use an MS-DOS window for this purpose.
  5. Install the expat library:
    mingw-get install libexpat
    
    This is needed to build the WFDB-XML applications.
  6. You may optionally install OpenSSL if you wish to use the compiled library or applications to read data via HTTPS (for example, directly from your PhysioNetWorks projects). OpenSSL is not required by WFDB applications for reading data from local files or from web servers via HTTP. See the curl web site for details on OpenSSL and other optional libraries.
  7. Unpack the tarballs using these commands:
    tar xfvz curl*.tar.gz
    tar xfvz wfdb.tar.gz
    
    These commands will create two directories, named curl-7.x.y and wfdb-10.m.n, where x, y, m and n will depend on the version numbers of the packages you have downloaded.
  8. Compile and install the curl package first:
         cd curl-7.y.z
         ./configure --prefix=/usr/local
         make
         make install
    
    The ./configure and make commands may require several minutes each.
  9. Compile and install the WFDB Software Package after installing curl:
         cd ../wfdb-10.m.n
         ./configure --prefix=/usr/local
         make
         make install
    
  10. Test the package:
    make check
    

MinGW/32 install precompiled binaries (excluding WAVE)

  1. Install MinGW and MSYS using the automated installer tool (mingw-get-inst, also called the "Graphical User Interface Installer" or the "GUI first time installer tool") following the instructions here. Be sure to select the option to use the latest available packages. Use the default installation directory (c:\mingw), and choose all of the optional components.
  2. Download the most recent WFDB MinGW/32 binary tarball, and save it in your MinGW home directory.
  3. Open a MinGW terminal window by clicking on Start → Programs → MinGW → MinGW Shell. Perform the remaining steps of the installation by typing into this window. Do not use an MS-DOS window for this purpose.
  4. Install the expat library:
    mingw-get install libexpat
    
    This is needed to run the WFDB-XML applications.
  5. To install the precompiled binaries, type (or copy-and-paste) this command into the MinGW terminal window:
    tar xfvz wfdb-MINGW.tar.gz -C /usr --strip-components=2
    

Notes:

  1. The native Windows applications and libraries created by this procedure are installed in c:\MinGW\msys\1.0\usr\local\bin.
  2. Copy the libraries and applications to a directory in your Windows PATH, or add their location to your Windows PATH, if you want to run them using cmd.exe (as, for example, in a DOS box). Avoid installing them in any location that has a space in its pathname.

Compiling and linking your applications with the WFDB library

If you wish to compile your own WFDB applications, or others that are not available in binary format, please begin by compiling and installing the WFDB software package sources, as described above. Once you have done so, copy app/Makefile (a text file contained in the WFDB source package) to the directory that contains the source for the application you wish to compile. Note that app/Makefile is customized based on the installation choices that you make when you run ./configure before compiling the WFDB software package, so it's important to copy the customized version of this file from your copy of the WFDB sources only after running ./configure.

If the application is contained in a single source file (for example, myprogram.c) in the same directory as this customized Makefile, you can compile it and link it with the WFDB library using a command such as

make myprogram
This method is recommended since it can be difficult to construct the proper gcc command line manually. As part of the output of make, you will see the gcc command line it constructs, and you can follow this model for subsequent compilations if you prefer not to use make.

If you need to compile an application contained in several source files, use the command generated by make for a single source file compilation and replace the single source name with those of your multiple source files, separated by spaces. Note that the output file name (the argument of gcc's -o option) should not include the .exe suffix.

The WFDB Software Package also includes wfdb-config, a tiny application that helps to construct gcc command lines without using make. Study the example in wfdb-config(1) to see how to use it.

Using a compiler other than gcc

Use MinGW's gcc to produce WFDB and curl DLLs in Windows native format. You can use any other compiler that is compatible with Windows DLLs to compile application code and link it to these WFDB and curl DLLs, and to other third-party DLLs if you wish.

It is not possible to compile or use WAVE under MS-Windows except by using Cygwin gcc and the Cygwin X11 and XView libraries.

As noted at the top of this page, compiling the WFDB software with a compiler other than gcc is unsupported.

If you do not use gcc, you must do one of the following:

If you do neither of these steps, your compiler will generate a defective WFDB DLL that assumes that files are always opened in so-called text mode, resulting in errors when reading and writing signal and annotation files (which are binary files). You can check to see if this has happened by running the command

    rdsamp -r 100s

which should yield 21600 numbered lines of output, ending with

     21596	  982	  995
     21597	  978	  989
     21598	  975	  988
     21599	  975	  989

If the output ends after 940 lines, you have a defective WFDB DLL and you will need to follow the instructions above to correct the problem.

Testing WAVE

If you installed the WFDB Software Package using Cygwin/32, you can try out WAVE by starting the Cygwin X server and then running (in an xterm window, such as the one that opens when you start the X server) the command:

wave -r mitdb/200 -a atr

Note that WAVE's menus (marked with a ∇) are opened using a right click. Annotation editing requires the use of the middle button; if your mouse has only two buttons, you may be able to simulate a middle button click by "chording" (press both buttons at the same time, then release them; see this note for details if necessary).

If you have not used WAVE before, you may want to follow through the tutorial material in the beginning of the WAVE User's Guide.

Acknowledgments

Thanks to Albert Titus, for the tip about launching with administrator privileges; Ben McClelland, for information about Cygwin's XView packages; Deborah Jaye, for early testing and feedback on Cygwin/64; and many others who have tested previous versions of these notes.