Building H5Part

• Quickstart guide for the impatient.
• Details of the Configuration Script
• Important Configure Options
• Important Environment Variables

---

Quickstart for the impatient

1. Configure:
   For the serial implementation

       ./configure
   

   For the parallel implementation configure with

       ./configure --enable-parallel
   

   If you also want to build fortran bindings, add the --enable-fortran flag to the configure line.
2. Make the Library:
   Type make to build the library. The libraries are named accordingly.
   • libH5Part.a: Serial C/C++ Library.
   • libpH5Part.a: Parallel C/C++ library.
   • libH5PartF.a: Serial F77/F90 library.
   • libpH5PartF.a: Parallel F77/F90 library.
3. Make Regression Tests and Examples:
   Just type make tests to build regression tests and/or example programs for H5Part. These tests are
   • H5PartF: Fortran example (only build if --enable-fortran is specified).
   • H5PartFpar: Parallel Fortran example (only built if both --enable-fortran and --enable-parallel are specified).
   • H5PartTest: Serial C example. This test writes a sample datafile and then reopens it for reading. It demonstrates the most basic reading/writing capabilities.
   • H5PartTestP: Parallel C example (only built if --enable-parallel is specified). This program only works as an MPI/parallel program.
   • Bench: This program will only be built if --enable-parallel is specified. It compares the performance of raw binary I/O (one file per processor), raw binary MPI-IO based parallel I/O to a single file, and the parallel H5Part/HDF5 to a single file. Generally, H5Part should be very close to the MPI-IO implementation in terms of performance, but slower than one-file-per-processor. If HDF5 is slower the MPI-IO, it would indicate that some performance tuning will be required for your platform (contact us, and we will see what we can do!).
4. Building Your Own Programs:
   There are many different subtleties to linking on various computer platforms, but typically one does the following.
   • C/C++ Serial:
     #include < H5Part.h > into your source file.
     $CC -Ipath_to_H5Part.h -Ipath_to_hdf5.h -o outfile MyFile.cc -Lpath_to_libH5Part.a -lH5Part -Lpath_to_libhdf5 -lhdf5 -lz -lsz
   • C/C++ Parallel:
     #include < H5Part.h > into your source file.
     $MPICC -Ipath_to_H5Part.h -Ipath_to_hdf5.h -DPARALLEL_IO -DH5_HAVE_PARALLEL -o outfile MyFile.cc -Lpath_to_libH5Part.a -lH5Part -Lpath_to_libhdf5 -lhdf5 -lz -lsz
   • Fortran Serial:
     include 'H5Part.inc' into your source file.
     $FC -Ipath_to_H5Part.h -Ipath_to_hdf5.h -o outfile MyFile.cc -Lpath_to_libH5PartF.a -lH5PartF -Lpath_to_libhdf5 -lhdf5 -lz -lsz -lc
   • Fortran Parallel:
     include 'H5Part.inc' into your source file.
     $MPIF90 -Ipath_to_H5Part.h -o outfile MyFile.cc -Lpath_to_libpH5PartF.a -lpH5PartF -Lpath_to_libhdf5 -lhdf5 -lz -lsz -lc

---

Details for H5Part Configure and Build

Configure Options

H5Part uses GNU Autoconf to generate a Makefile from the makefile template called Makefile.in. The configure script pays attention to the following configure options;

• --prefix=PREFIX Install files in PREFIX
• --enable-fortran By default H5part will make no attempt to build Fortran bindings. If you add the --enable-fortran flag to the ./configure line, it will create a small test program to determine how to generate the fortran bindings and then create a library that includes those bindings. You may need to set the fortran compiler by setting the FC environment variable in your shell.
• --enable-parallel The version of HDF5 that you build for Parallel I/O differs from the library you would build for serial I/O. Consequently, the H5Part libraries must be built specifically for the kind of I/O you have in mind (parallel or serial). The configure script will attempt to find an mpicc if it is available. If no mpicc is available it will use the regular C-compiler and will try to locate the location of the MPI include files and libraries. You can assist the configure program in its search by setting the MPIROOT environment variable.
• --enable-tools Builds the currently available tools
  h5pAttrib, an inspection tool that prints the number of timesteps in a file the file attributes, the step attributes, the dataset names and their values.
  h5pToGNUplot, a converter to two column ASCII format to load in GNUplot.
• --enable-python Under construction Option to build python bindings. It has not been tested.
• --help Prints configure options.

Make Options

• make
builds the libraries and test programs
• make install
builds and installs
• make clean
removes extraneous object files
• make distclean
returns configuration to unconfigured state

Environment Variables for Configure

The configuration script is of limited intelligence. Sometimes, you have to define the following environment variables in order to help it on its way. You will often only need to tell it where to find the HDF5 libraries (H5ROOT for serial or PHDF5ROOT for parallel builds). All of these environment variables can also be overidden in the Makefile that is generated by the autoconfigure script. The configure script pays attention to the following environment variables;

• CC: Use the CC environment variable to tell the configure script where to find the C compiler. You can also directly modify this variable in the Makefile that is generated by the autoconfigure
• CXX: Use the CXX environment variable to tell the configure script where to find the C++ compiler. You can also directly modify this variable in the Makefile that is generated by the autoconfigure
• FC: Use the FC environment variable to tell the configure script where to find the fortran compiler. You can also directly modify this variable in the Makefile that is generated by the autoconfigure
• MPICC: If you are building for parallel C I/O, then it is useful to tell the configure script where to find the mpicc script. Normally, mpicc is merely a wrapper script for a build using a regular C-compiler. If no mpicc is available, then the configure script will attempt to locate the mpi header files and libraries. In that case, it may be useful to define the MPI_HOME environment variable.
• MPICXXIf you are building for parallel C++
• MPIFC: If you are building for parallel Fortran I/O, then it is useful to tell the configure script where to find the parallel fortran compiler.
• MPIROOT: Set this environment variable to help the configure script to locate the MPI libraries that should be used to build the parallel version of the libraries. This variable will be ignored if configured only to build the serial implementation of the library.
• HDF5ROOT: Find the path to your serial HDF5 installation. If you are building the serial version of H5part, then you should set the PHDF5ROOT environment variable.

Common compiler environemt variables for NERSC platforms

• DaVinci: Linux ia64
CC=icc CXX=icc F90=ifort MPICC=icc MPIFC=ifort MPILIB=-L/usr/lib/ -lmpi MPIINC=-I/usr/include
• Bassi: AIX
CC=cc_r CXX=cc_r FC=xlf_r MPICC=mpcc_r MPICXX=mpcc_r MPIFC=mpxlf_r
• Jacquard: Linux x86_64
CC=pathcc CXX=pathCC FC=pathf90 MPICC=mpicc MPICXX=mpicxx MPIFC=mpif90
• Starsky.lbl.gov: (Darwin) PowerPC
CC=gcc CXX=g++ FC=g95

NOTE: You might need to set the MPI library path (MPILIB) and MPI includes (MPIIINC) if they are in non standard places. For example:
MPILIB=-L/usr/lpp/ppe.poe/lib -lmpi_r MPIINC=-I/usr/lpp/ppe.poe/include/thread

How to set the variables for configure:

It is very simple just call env with the variables together with configure. Notice the quotes in MPILIB.

% env CC=icc CXX=icc F90=ifort MPICC=icc  MPILIB=-L/usr/lib/ -lmpi MPIINC=-I/usr/include ./configure (configure options follow here)

In the worst case, you can edit the src/Makefile.am and test/Makefile.am as needed to perform the proper build.