Last modified: 25 September 2013
Tool Name: h5cc and h5pcc
Syntax:
  `h5cc [`OPTIONS`]` <compile line>
  `h5pcc [`OPTIONS`]` <compile_line>

Purpose:
  Helper scripts to compile HDF5 applications.

Description:
  `h5cc` and `h5pcc` can be used in much the same way as `mpicc` by MPICH is used to compile an HDF5 program. These tools take care of specifying on the command line the locations of the HDF5 header files and libraries. `h5cc` is for use in serial computing environments; `h5pcc` is for parallel environments.

  `h5cc` and `h5pcc` subsume all other compiler scripts in that if you have used a set of scripts to compile the HDF5 library, then `h5cc` and `h5pcc` also use those scripts. For example, when compiling an MPICH program, you use the `mpicc` script. If you have built HDF5 using MPICH, then `h5cc` uses the MPICH program for compilation.

  Some programs use HDF5 in only a few modules. It is not necessary to use `h5cc` or `h5pcc` to compile those modules which do not use HDF5. In fact, since `h5cc` and `h5pcc` are only convenience scripts, you can still compile HDF5 modules in the normal manner, though you will have to specify the HDF5 libraries and include paths yourself. Use the `-show` option to see the details. For example, running `h5cc` for an HDF5 library built using `gcc` with `--disable-shared`, `zlib` and `szlib`, all installed in `/usr/local/lib` would provide this compile command:

      gcc -D_FILE_OFFSET_BITS=64 -D_LARGEFILE_SOURCE -D_LARGEFILE64_SOURCE      \
          -D_BSD_SOURCE -L/usr/local/lib /usr/local/lib/libhdf5_hl.a            \
          /usr/local/lib/libhdf5.a /usr/local/lib/libsz.a /usr/local/lib/libz.a \
          -lm -W1,-rpath -W1,/usr/local/lib   [OPTIONS] <compile line>

  An example of how to use `h5cc` to compile the program `hdf_prog`, which consists of the modules `prog1.c` and `prog2.c` and uses the HDF5 shared library, would be as follows. `h5pcc` is used in an identical manner.

           # h5cc -c prog1.c
           # h5cc -c prog2.c
           # h5cc -shlib -o hdf_prog prog1.o prog2.o

Options and Parameters:

`-help` | Prints a help message.
`-echo` | Show all the shell commands executed.
`-prefix=DIR` | Use the directory `DIR` to find the HDF5 `lib/` and `include/` subdirectories. Default: prefix specified when configuring HDF5.
`-show` | Show the commands without executing them.
`-shlib` | Compile using shared HDF5 libraries. Default for HDF5 built without static libraries.
`-noshlib` | Compile using static HDF5 libraries. Default for HDF5 built with static libraries.
<compile line> | The normal compile line options for your compiler. `h5cc` and `h5pcc` use the the same compiler you used to compile HDF5. Check your compiler's manual for more information on which options are needed.

Environment Variables:
  When set, these environment variables override some of the built-in `h5cc` and `h5pcc` defaults.

  `HDF5_CC` | Use a different C compiler.
  `HDF5_CLINKER` | Use a different linker.
  `HDF5_USE_SHLIB=[yes|no]` | Use shared version of the HDF5 library. Default: no, except when HDF5 built with only shared libraries.
  `HDF5_CPPFLAGS` | Use additional preprocessor flags.
  `HDF5_CFLAGS` | Use additional C compiler flags.
  `HDF5_LDFLAGS` | Use additional library paths.
  `HDF5_LIBS` | Use additional libraries.

  The last four of these environment variables have corresponding variables with names ending in `BASE` that can also be set by editing their values in the "Things You Can Modify to Override HDF5 Library Build Components" section of the `h5cc` and `h5pcc` scripts.

  Note that adding library paths to `HDF5_LDFLAGS` where another HDF5 version is located may link your program with that other HDF5 Library version.

Exit Status:

  0 | Succeeded.
  > 0 | An error occurred.

History:

Release | Change
1.8.12 | Tool modified to switch default to link to shared libraries when HDF5 configured with `--disable-static`.
1.8.6 | Four compiler flags and environment variables added.
1.8.5 | Tool exit status codes updated.