location of hdf5 header files

[Darren Weber]

On Thu, Oct 8, 2009 at 12:53 PM, Jochen Küpper <
kuepper.jochen at googlemail.com> wrote:

> On 08.10.2009, at 21:46, Darren Weber wrote:
>
>  On Thu, Oct 8, 2009 at 12:16 PM, Ryan Schmidt <ryandesign at macports.org>
>> wrote:
>> On Oct 8, 2009, at 13:37, Darren Weber wrote:
>>
>> In cursory exploration of /opt/local/include/, it appears that many, if
>> not all, of the hdf5 header files are located at the root of
>> /opt/local/include/.  Is that a mistake?  Should the hdf5 include files get
>> stored into something like /opt/local/include/hdf5/?
>>
>> Using "port contents hdf5 | grep \\.h$" I would agree that all this port's
>> headers are in ${prefix}/include. Is that a problem? Would it be better to
>> have them in a subdirectory? The port doesn't seem to do anything to change
>> the header location at present, so it just installs them where the developer
>> of that software thought they should go. Is there a problem you're trying to
>> solve by moving the headers?
>>
>>
>>
>> Ah, it's not a current problem that prevents or interference with other
>> ports within MacPorts, ASFAIK.
>>
>> Firstly, it's a convenience.  When using ctags or any IDE system to
>> analyze a set of header files (for programming autocompletion), it is
>> convenient to have the headers in a package specific path within the general
>> ${prefix}/include path.  This is especially true for large packages, like
>> wx*, vtk*, InsightToolkit*, etc.
>>
>> Secondly, it's a safety-net.  At the very least, it is significant and
>> important that any headers located in the generic ${prefix}/include have
>> some kind of unique naming convention, like a prefix in their file name, to
>> avoid any conflicts with other software packages.  The hdf5 package appears
>> to have  the file prefix of "H5" to distinguish it from other packages.
>>  However, a two-char prefix is not exactly a reliable unique identifier,
>> especially on a file system that is not case sensitive.  To avoid potential
>> conflicts with other software packages, it may be preferable to locate the
>> headers within ${prefix}/include/hdf5/.  An additional layer may be added by
>> using ${prefix}/include/hdf5-${ver} where ver=1.6 (as of the current
>> writing, we have hdf5 @ 1.6.9).  The version specific path should allow
>> multiple versions of the library to co-exist in the ports tree (in this
>> regard, we have seen some issues with versions of the hdf5 port in relation
>> to the netcdf port).
>>
>
> But you then have to teach your compiler where to find the headers
> individually for all these packets...  Software written for hdf5 generally
> assumes that
>  #include <H5...>
> works and no
>  #include <hdf5-1.x/H5...>
> is necessary...
>
> I think it's fine as it is, until there is a actual name clash.
> Then it should be fixed upstream and all software has to be adopted to the
> new naming scheme...
>
>


Yes, it's best practice to avoid #includes like this:
#include <hdf5-1.x/H5...>

Rather, the common and perhaps preferred method to avoid such #include code
styles is to use an include path as an argument to the compiler.  This is
the way to provide code that can build on various systems and it's the
purpose of autoconf and similar tools to figure out where to find the
libraries if they are not specified using some form of include path option
(gcc has the -I and -L options).

For example, assume a source file contains:
#include "H5ArrayType.h"

This file may be compiled on any distribution (where the package maintainers
determine where stuff goes), using the convention of specific include path
options for autoconf-like tools or the compiler suite.

If the hdf5 libs are located in /opt/local/, that is the path to provide,
eg:
gcc -I/opt/local ...

Software developers do "suggest" the default locations for the include and
lib files in the default settings for autoconf and like tools (perhaps they
provide a install shell script with defaults).  The defaults are often
consistent with a general consensus on where things go, like /usr/local and
such.  Note that MacPorts already discards the general consensus for using
/usr/* paths, for good reason too.  It is just a consensus, not a rule of
law.  The beauty of path specifications for autoconf and compilers is that
the source code can be developed independently of the installation location
for the headers/libs and, furthermore, package distribution systems can use
ANY path configuration (e.g., AFAIK fink uses /sw/*).

Getting back to the main point here, in the case of hdf5, there are multiple
ports related to this software package:

[ me at XXX ~ ]$ port search hdf
h4h5tools @2.0 (science)
    HDF4 to HDF5 conversion tools.
hdf4 @4.2r4 (science)
    file format for storing scientific data and utilities
hdf5 @1.6.9 (science)
    HDF5 general purpose library and file format for storing scientific data
hdf5-18 @1.8.3 (science)
    HDF5 general purpose library and file format for storing scientific data
hdfeos @2.15v1.00 (science)
    HDF-EOS library built on HDF4
py25-tables @2.1.2 (python, python, science)
    Python package for HDF5 file access.
py26-tables @2.1.2 (python, python, science)
    Python package for HDF5 file access.

Now, if a program in another package distribution depends on a hdf* library,
unless the MacPorts system uses specific include/lib paths, how do we know
whether it is building against hdf4, hdf5, or hdf5-18?  (Of course, we can
use otool, that's not the point here; the point is, how do we specify the
dependency exactly?)  Do all these package versions have different header
file prefixes so they can coexist in ${prefix}/include/?  (If so, and they
are some kind of custom hack within MacPorts, then that is likely to break
source code that assumes a standard file name convention for the hdf4 or
hdf5 libraries.)   Furthermore, if you design a new port for MacPorts that
does depend on ONE of these libraries, how can you be clear about specifying
that dependency (obviously, you can specify port:hdf...), but what about
specifics in the Portfile for any include or lib paths in the configure
phase?

My preference:

A. When coding a new port that depends on hdf5 @ 1.6.x, specify a port
dependency on port:hdf5-16 and specify to the configure phase that the
include path is ${prefix}/include/hdf5-1.6

B. When coding a new port that depends on hdf5 @ 1.8.x, specify a port
dependency on port:hdf5-18 and specify to the configure phase that the
include path is ${prefix}/include/hdf5-1.8

C. There may be a port called simply hdf5 (or hdf4), with no version
specific suffix in the name.  Any dependency on that port would be port:hdf5
and the configure include path would be ${prefix}/include/hdf5 (and that
path might actually be a symlink to the "latest" version specific include
path).

Take care,
Darren

P.S., It's odd that the hdf5 port is @ 1.6.x, whereas the hdf5-18 port is a
later version.  In general, the consensus in MacPorts appears to be that
ports with a generic name, like hdf5, contain the latest version available.
Any prior releases assume a version specific port name.  Suggestion: the
port name "hdf5" always contains the latest (stable) release; the port name
"hdf5-devel" contains the latest development version (not necessarily
stable); any prior version specific releases are named
"hdf5-${major}${minor}", like hdf5-16.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.macosforge.org/pipermail/macports-users/attachments/20091008/4db92c09/attachment.html>