Chapter 2: Installation

2.1 Installation from sources

These instructions are both for Unix/Linux and Windows systems. If you are using Windows, it is assumed that you are using a recent version of MS Visual C++ (>= 6.0) compiler. A GCC compiler is assumed for Unix, but other compilers should work as well.

Extensions in PyTables has been made using Pyrex (see ) and C language. You can rebuild everything from scratch if you got Pyrex installed, but this is not necessary, as the Pyrex compiled source is included in the distribution. In order to do that, merely replace setup.py script in these instructions by setup-pyrex.py.

To compile PyTables you will need a recent version of HDF5 (C flavor) library and numarray (see ) package. Although you won't need Numerical Python (see ) in order to compile PyTables, it is supported; you will only need a reasonably recent version of it (>= 21.x). PyTables has been successfully tested with Numeric 21.3, 22.0 and 23.0. If you already have Numeric installed, the test driver module will detect it and will run the tests for Numeric automatically.

1. First, make sure that you have HDF5 1.6.x and numarray 0.6 or higher installed (I'm using HDF5 1.6.0 and numarray 0.7 currently). If don't, you can find them at
   http://hdf.ncsa.uiuc.edu/HDF5 and http://www.pfdubois.com/numpy. Compile/install them.

   Optionally, consider to install the excellent LZO and UCL compression libraries (see and section 5.2).

   Unix

   setup.py will detect HDF5, LZO or UCL libraries and include files under /usr or /usr/local; this will catch installations from RPMs, DEBs and most hand installations under Unix. If setup.py can't find your libhdf5 (or any other library you may wish) or if you have several versions installed and want to select one of them, then you can give it a hint either in the environment (using the HDF5_DIR environment variable or LZO_DIR and UCL_DIR for the optional libraries) or on the command line by specifying the directory containing the include and lib directory. For example:

   		  --hdf5=/stuff/hdf5-1.6.0
   		  --ucl=/stuff/ucl-1.0.1
   		

   If your HDF5 library was built as shared library, and if this shared library is not in the runtime load path, then you can specify the additional linker flags needed to find the shared library on the command line as well. For example:

   		  --lflags="-Xlinker -rpath -Xlinker /stuff/hdf5-1.6.0/lib"
   		

   or perhaps just

   		  --lflags="-R /stuff/hdf5-1.6.0/lib"
   		

   Check your compiler and linker documentation for correct syntax.

   It is also possible to specify linking against different libraries with the --libs switch:

   		  --libs="-lhdf5-1.6.5"
   		  --libs="-lhdf5-1.6.5 -lnsl"
   		

   Windows

   If you are using Windows, and don't want to compile the libraries by hand, there are available binary packages for them. You can fetch the HDF5 and numarray binaries from their homes.

   For the HDF5 you must manually copy the hdf5dll.dll and szipdll.dll files to a directory in your PATH environment variable (for example C:\WINDOWS\SYSTEM).

   Besides, you may want to fetch the LZO and UCL binaries from:
   http://gnuwin32.sourceforge.net/. Normally, you will only need to fetch and install the <package>-<version>-bin.zip file, although in some cases the headers are in <package>-<version>-lib.zip file.

   As before, you will need to copy manually the lzo.dll or ucl.dll to a directory in the PATH, so that they can be found by PyTables extensions.

   setup.py will need that you inform it about where the library stubs (.lib) are installed as well as the header files (.h). To tell setup.py where the stubs and headers are, set the next environment variables:

   HDF5_DIR

   Points to the HDF5 main directory (where the include/ and dll/ directories hangs). Mandatory.

   LZO_DIR

   Points to the LZO main directory (where the include/ and lib/ directories hangs). Optional.

   UCL_DIR

   Points to the UCL main directory (where the include/ and lib/ directories hangs). Optional.

   For example:

   		  set HDF5_DIR=c:\stuff\5-160-win2k\c\release
   		  set LZO_DIR=c:\stuff\lzo-1-07
   		  set UCL_DIR=c:\stuff\ucl-1-01
   		

   Or you can pass this info to setup.py within the command line by specifying the directory containing the include and lib directory. For example:

   		  --hdf5=c:\stuff\5-160-win2k\c\release --lzo=c:\stuff\lzo-1-07
   		  --ucl=c:\stuff\ucl-1-01
   		

2. From the main PyTables distribution directory run this command, (plus any extra flags needed as discussed above):

   	      python setup.py build_ext --inplace
   	    

   depending on the compiler flags used when compiling your Python executable, there may appear lots of warnings. Don't worry, almost all of them are caused by variables declared but never used. That's normal in Pyrex extensions.

3. To run the test suite change into the test directory and run this command:

   Unix

   In the shell sh and its variants:

   		  PYTHONPATH=..  
   		  export PYTHONPATH
   		  python test_all.py
   		

   Windows

   Open a DOS terminal and write:

   		  set PYTHONPATH=..  
   		  python test_all.py
   		

   If you would like to see some verbose output from the tests simply add the flag -v and/or the word verbose to the command line. You can also run just the tests in a particular test module. For example:

   	      python test_types.py -v
   	    

   If there is some test that do not pass, please, run the failing test module with all verbosity enabled (flags -v verbose), and send back the output to developers.

   If you run into problems because Python can't load the HDF5, or any other shared library:

   Unix

   Try to set the LD_LIBRARY_PATH environment variable to point to the directory where the libraries are.

   Windows

   Put the DLL libraries (hdf5dll.dll and, optionally, lzo.dll and ucl.dll) on a directory listed on your PATH environment variable. The setup.py should already warned you about that.

4. To install the entire PyTables Python package, change back to the root distribution directory and run this command as the root user (remember to add any extra flags needed):

   	      python setup.py install
   	    

That's it!. Now, proceed with the next chapter to see how to use PyTables.

2.2 Binary installation (Windows)

This section is only intended for Windows platforms. If you have Unix, or want to compile PyTables for Windows, jump to the section 2.1.

That's it!. Now, proceed with the next chapter to see how to use PyTables.