#*****************************************************************************
# 
#			  NCSA HDF version 3.10r3
#				Dec 6, 1990
#
# NCSA HDF Version 3.10r3 source code and documentation are in the public
# domain.  Specifically, we give to the public domain all rights for future
# licensing of the source code, all resale rights, and all publishing rights.
# 
# We ask, but do not require, that the following message be included in all
# derived works:
# 
# Portions developed at the National Center for Supercomputing Applications at
# the University of Illinois at Urbana-Champaign.
# 
# THE UNIVERSITY OF ILLINOIS GIVES NO WARRANTY, EXPRESSED OR IMPLIED, FOR THE
# SOFTWARE AND/OR DOCUMENTATION PROVIDED, INCLUDING, WITHOUT LIMITATION,
# WARRANTY OF MERCHANTABILITY AND WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE
# 
#*****************************************************************************

This file contains hints that may be helpful in building the HDF library
and utilities.  Much of the information contained herein has been provided
by colleagues outside of NCSA who have ported HDF to platforms that are
not officially supported at NCSA.  Many of the machines referred to here 
are not officially supported by NCSA because we do not have these machines 
to debug or test the HDF software on.

Contents:

        defining MACHINE type when compiling
        Fortran short names
        #pragma
        UNICOS
        SGI, IRIS4D
        DECStations (3100 & 5000) with Ultrix
        STELLAR
        APOLLO
        Convex
        nonSUN
        Amiga
        IBM PC
        3B15
        Installation experience (Sun4)        

** a common mistake is not defining the MACHINE type when compiling a file
that includes "df.h", e.g.
	cc -c file.c			(wrong)
as opposed to
	cc -c -DSUN file.c		(right)
for an installed "dfi.h", "df.h", you might want to add
	#define SUN
(or whatever machine type) in dfi.h


**  Fortran short names --

If your Fortran compiler only accepts maximum 7 character
function names: 

The Bourne shell script short.sh truncates the fortran files
so that all functions names are 7 or less characters longs.
Alternately or if you are not running UNIX, you could use an
editor to remove everything after the "CEND7MAX" line in the
Fortran  source files.

** #pragma --

Some compilers are not very tolerant of #pragma.  Since we inserted 
some of these directives in dfsd.c to increase the speed on Crays,
you need to edit the file (dfsd.c) to fix the problem.  Specifically:.

	MIPS C compiler version 2.1 can handle it, but earlier 
	MIPS compilers may not.  If you comment out the line 
	with #pragma on it, the problem should go away.

	UNICOS will not compile the #pragma if it is indented.  
	If the #pragma is indented, delete the leading spaces to 
	make it work. 


** UNICOS --

See above about short Fortran function names.
See above about #pragma.


** SGI, IRIS4D --

The standard MIPS C compiler available to the SGI machine is
not very tolerant of "#pragma"s.  See above about #pragma.

** DECStations (3100 and 5000) with Ultrix --

Use the makefile MAKE.DECST.

Do not specify a machine type if you are compiling on a DECStation.
The compiler automatically defines a machine type as MIPSEL, and
the dfi.h contains a section of code to set the appropriate
parameters accordingly.

Note: if you got the source before 10/3/90, make the following
change: Look in the MIPSEL segment of dfi.h. You'll see a
        #define DFmovmem(from, to, len) memcpy(from, to, len)
Change this to:
        #define DFmovmem(from, to, len) memcpy(to, from, len)


See above about #pragma.


** STELLAR

To port to Stellar:

Change Makefile, as follows:

	#define SUN 
	comment out references to pixrect
	get rid of references to ranlib


** APOLLO

Do not use ftn to compile the fortran stubs.


** Convex

Convex machines support two different floating point representations,
a standard IEEE representation and a Convex representation.  HDF
currently does NOT support the Convex representation.

** nonSUN

If you have selected SUN as your machine type, but your machine is
not really a Sun, you should deleted the following line in hdfrseq.c:
	#include <pixrect/pixrect_hs.h>
and remove all lines in hdfrseq.c that are between
	#ifdef SUN
and
	#endif /* SUN */

Also comment out the
	GLIBS = -lpixrect
line in the Makefile.


** Amiga

A user who ported HDF 3.1 to an Amiga has shared with us information
about his port, as well as all of the files that he had to change and
some test files.  This material can be found in the directory 
HDF/contrib/amiga on the anonymous ftp server.


** IBM PC

Hello,
	I have just finished the port of HDF to the IBM PC.  I have tested
only the standard HDF routines, the palette routines, and the RIG routines.
The scientific data set routines, the annotation routines and the 24 bit
image routines may still be slightly buggy.

  The code for this port can be found in HDF/src/pc_beta.

Things to watch out for:
1)	If you need large amounts of memory space for your image, use
	halloc((long)x,(int)y) to allocate x*y amount of bytes
	for your use.  A typical call I use is:  
		p=halloc((long)size, (int)1);	
	This allocates 'size' number of bytes where size can be a very
	large number.  Use hfree((char *)p) to free the memory you allocate
	with halloc().  Don't free halloc'ed things with free(), or
	malloc'ed things with hfree(), you will probably hang your machine.

2)	When you open an image file, remember to open it in binary mode.
	i.e.:
		fp=fopen("filename.img","wb");
	or
		fp=fopen("filename.img","rb");
	If you don't do this, every time you write or read a carriage 
	return character, a line feed will be appended or attempted to
	be stripped off the file, depending whether you are writing or
	reading the file.
3)	Most of the time, the HDF routines I haven't tested assume that an
	integer is 32-bits long.  This is not true on the PC, they are
	only 16-bits long.  This can cause potential problems when trying
	to index a byte in an image array with an integer, because most
	images are significantly larger than 32k (the point at which
	integers turn negative on the PC).  Most of the
	time this can be fixed by changing the variable used to index the
	array to a long.  DFIMCOMP.c has extensive examples of this kind
	of fix-up if you need to perform them.
4)	The various routines in HDF of the form DFputxxxx() and DFaddxxxx() 
	(DFPputpal(), DFPaddpal(), DFR8putimage(), DFR8addimage(), etc.)
	are meant to be used in the following way:  Only use DFputxxxx() 
	for the first xxxx to be put into a new HDF file, use DFaddxxxx()
	for further additions to the file.  For already existing files,
	it is alright to do a DFopen() on the file and then call 
	DFaddxxxx() to add the xxxx to the HDF file.

	I would suggest using the utility routines we provide as examples of 
the way to use HDF calls.  As always we appreciate your feedback and
suggestions for further versions of HDF.  Please keep me up to date on any
bugs you find in the routines so I can fix them and post the bug-fixes.

			Thanks for your patience,
					Quincey Koziol
					NCSA
koziol@ncsa.uiuc.edu


** 3B15

From garnett@d.cs.okstate.edu Mon Feb 19 19:37:13 1990
From: John Garnett Computing and Informatio <garnett@d.cs.okstate.edu>
To: mfolk@NCSA.NCSA.UIUC.EDU

Dr. Folk,

I finally received access to a computer account that has enough
disk space to ftp HDF and compile it.  This note is to let you
know what I have discovered so far about trying to compile
HDF on an AT&T 3B15 running AT&T's UNIX System V.3.2

First of all, the 3B15 won't compile any module that includes the
#include file <sys/file.h> unless the #include file <sys/types.h>
is included prior to <sys/file.h>.  This was easy enough to fix by
adding the appropriate line to the dfi.h file.  Replace

#include <sys/file.h>

with

#include <sys/types.h>
#include <sys/file.h>

Secondly, since the HDF Makefile does not have a MACHINE= type of
3B15 available, I used the SUN definition.  This appears to work well,
although I haven't yet tested the library.  By the way, the 3B15 doesn't
have bcopy().

Thirdly, it appears that all of the UTILS were setup to link against
libpixrect which I am guessing is a SUN graphics library.  As it turned
out, only the first .c file in the UTILS list required this library so
I was able to compile the remaining UTILS by commenting out the first one
and editing LIBS= not to include libpixrect. (as you can probably tell
by now, I don't have immediate access to a SUN).



John Garnett


** Installation Experience (Sun4)

The following report from a user has useful suggestions of changes
you may need to make when installing HDF on your system.  Note that
this installation was for a HDF 3.00 on a Sun 4, but similar changes 
will need to be made for others.

From: rim@marvin.ri.ccf.org (Robert M. Cothren)
To: mfolk@ncsa.uiuc.edu
Subject: HDF suggestions

I down loaded HDF and and the he editor to my Sun 4/110 last Friday,
and successfully build both packages.  Although I have not had much of
a chance to work with the software, I can already tell that it will be
very useful to us.

I have a few picky little suggestions -- all having to do with the
Makefiles...

I downloaded the file hdf3.00.tar.Z from zaphod.ncsa.uiuc.edu.  If
that is not the latest version, then this message can probably be
ignored.

--------------------

For the file ./hdf/Makefile:

The install: and cleanup: macros both fail because LIBS is defined to
include the "-lpixrect" library option for cc.

I have changed the Makefile to load the header files and library in
the standard /usr/include and /usr/lib locations.  This change caused
a rather simple problem: ranlib $(LIBDIR)/* tries to run on every file
in /usr/lib ... not a pretty sight.

I also added the link for hdfseq to the install macro.

Here is the output of diff -c1 listing the exact changes I made to the
file to build it at my site.  Obviously the first changes to INCDIR,
LIBDIR, and BINDIR are unnecessary for many sites.

*** Makefile    Fri Jun 15 17:45:01 1990
--- Makefile.orig       Fri Jun 15 17:09:33 1990
***************
*** 17,21 ****
  SRCDIR=.
! INCDIR=/usr/include
! LIBDIR=/usr/lib
! BINDIR=/usr/local/bin

--- 17,21 ----
  SRCDIR=.
! INCDIR=../include
! LIBDIR=../lib
! BINDIR=../bin

***************
*** 25,29 ****
  #GLIBS=
- HDFLIB        = libdf.a
  GLIBS = -lpixrect
! LIBS  = $(HDFLIB) $(GLIBS)

--- 25,28 ----
  #GLIBS=
  GLIBS = -lpixrect
! LIBS  = libdf.a $(GLIBS)

***************
*** 51,53 ****
        df24F.o df24Ff.o dfpFf.o dfpF.o
! OBJS=${COBJS}

--- 50,52 ----
        df24F.o df24Ff.o dfpFf.o dfpF.o
! OBJS=${COBJS} ${FOBJS}

***************
*** 105,112 ****

! install: $(HFILES) $(HDFLIB) $(UTILS)
        cp $(HFILES) $(INCDIR)
!       cp $(HDFLIB) $(LIBDIR)
!       ranlib $(LIBDIR)/$(HDFLIB)
        cp $(UTILS) $(BINDIR)
-       ln -s $(BINDIR)/hdfrseq $(BINDIR)/hdfseq

--- 104,110 ----

! install: $(HFILES) $(LIBS) $(UTILS)
        cp $(HFILES) $(INCDIR)
!       cp $(LIBS) $(LIBDIR)
!       ranlib $(LIBDIR)/*
        cp $(UTILS) $(BINDIR)

***************
*** 116,118 ****
  cleanup:
!       -${RM} $(OFILES) $(HDFLIB) $(UTILS)

--- 114,116 ----
  cleanup:
!       -${RM} $(OFILES) $(LIBS) $(UTILS)


--------------------

For the file ./hdfed/Makefile:

The definition for MACHINE is left out.

cx, in the current directory, is not necessarily on the path.

Both of these are trivial problems, and needed no real thought to fix.
The diff -c1 output listing the exact changes I made to build he at my
site follow.

*** Makefile    Mon Jun 18 08:55:27 1990
--- Makefile.orig       Mon Jun 18 08:48:54 1990
***************
*** 3,9 ****
  # for Suns, un-comment this line
! LIBS  = -L../lib -ldf -lpixrect
! # LIBS        = -L../lib -ldf

- MACHINE = SUN
-
  CC    = cc
--- 3,7 ----
  # for Suns, un-comment this line
! # LIBS        = -L../lib -ldf -lpixrect
! LIBS  = -L../lib -ldf

  CC    = cc
***************
*** 29,31 ****
  he.x: $(SRCS)
!       ./cx $(SRCS) > he.x

--- 27,29 ----
  he.x: $(SRCS)
!       cx $(SRCS) > he.x



--------------------

We are also making use of ximage and pcshow.  Thanks for make such
useful tools available at a cost even I can afford.  Keep up the good
work!

------------------------------

Robert M. Cothren
rim@marvin.ri.ccf.org
current replies: cothren@ccisd2.ccf.org

Cleveland Clinic Foundation
Cleveland, Ohio
216-444-3586
