Documentation: Provide an example of building and linking a user app

[milancurcic]

When trying to build an example program, I ran into linking issues. For example, in build/ directory, if I do:

$ cat test.f90 
use h5fortran
call h5write('golt.h5','/x', [1,2,3,4,5,6])
end
$ gfortran test.f90 -Iinclude -L. -lh5fortran

I get many linker errors. I'm an HDF5 n00b, but I understand I need to link to the HDF5 library. So I search the system and find libraries in usr/lib/x86_64-linux-gnu/hdf5/serial. Great! But now I'm not sure which libraries I need and which I don't. There are several:

$ ls /usr/lib/x86_64-linux-gnu/hdf5/serial
include    libhdf5_cpp.a      libhdf5_fortran.so  libhdf5_hl_cpp.so     libhdf5_hl.so
lib        libhdf5_cpp.so     libhdf5_hl.a        libhdf5hl_fortran.a   libhdf5.settings
libhdf5.a  libhdf5_fortran.a  libhdf5_hl_cpp.a    libhdf5hl_fortran.so  libhdf5.so

Specifically, do I need the C library? Fortran library? Both? And what are these hl libraries? So I try various combinations until I get to the one that makes the linker happy:

$ gfortran test.f90 -Iinclude -L. -lh5fortran -L/usr/lib/x86_64-linux-gnu/hdf5/serial -lhdf5_fortran -lhdf5hl_fortran

You get the idea: The Usage subsection of the README should explain how to link a user program with all the libraries that are needed.

openjournals/joss-reviews#2842

[scivision]

Yes I added to readme.md, that if one isn't using CMake for their own project, they can use the HDF5 compiler wrapper like:

h5fc -I~/h5fortran/include myprogram.f90 ~/h5fortran/lib/libh5fortran.a

[milancurcic]

Okay, thanks I found it (and it worked), although it's quite buried at the bottom of the CMake section. Can you place it in its own section so its more visible? I don't know what's a good section name. "Non-CMake"? "Other build systems"?

[scivision]

yes I made a "compiler wrapper" section for this

[milancurcic]

Great, thanks.