   Copyright (C)  2000    Daniel A. Atkinson  <DanAtk@aol.com>
   Copyright (C)  2004    Ivano Primi  <ivprimi@libero.it>    

   This is the installation manual of the HPA Library.

   Copying and distribution of this file, with or without modification,
   are permitted in any medium without royalty provided the copyright
   notice and this notice are preserved.

***************************************************************************


INSTRUCTIONS FOR THE INSTALLATION OF THE HPA LIBRARY ON AN UNIX(R)
SYSTEM.

Before the installation of the HPA library you must make sure that the
system where you are going to install the library has already installed:
1 - The `bash' shell (or another shell sh-compatible);
2 - The `make' utility, preferably the 'GNU' version of 'make' (also
    called 'gmake');
3 - Whatever you need to compile an ANSI-C program. The compiler
    must accept the options -c (for compile only), -D (to define macros),
    -I (to specify the path where searching for non-standard include files),  
    -L (to specify the path where searching for non-standard libraries) and
    -o (to specify the output file). It would be better if it supported
    also the options -g (for debug) and -O (to produce optimized object
    code). I built up the library and tested it by using the GNU C Compiler 
    (gcc) (i worked with the versions 2.95.3 on SunOS 5.8, 
    2.95.4 on FreeBSD 4.9, 3.3.3 on NetBSD 2.0.2 and 3.3.4 
    on Slackware GNU/Linux 10.1).
    If you are interested in gcc you may get it at the address

		gcc.gnu.org		.

4.  If you want to build and install also the C++ wrapper to
    the HPA library, then you need also an ANSI-compliant
    C++ compiler. When I say ANSI-compliant, I refer to a
    recent ANSI protocol (>= 1997). I successfully compiled
    and tested the C++ wrapper by using the GNU C++ compiler
    (g++), version 3.3.4, under Slackware GNU/Linux 10.1 .
    I presume that any version of g++ >= 2.95.x should work fine.

TO THROW THE BUILDING OF THE LIBRARY HPA (WHOSE FINAL NAME WILL
BE `libhpa.a': YES, THE SUPPLIED MAKEFILE WILL ONLY CREATE A STATIC
VERSION OF THE LIBRARY) YOU HAVE TO OPEN A SHELL AND ENTER IN THE DIRECTORY
CONTAINING THE SOURCE OF THE LIBRARY (AND THIS FILE TOO). THEN, AFTER
HAVING A LOOK AT THE MAKEFILE SUPPLIED WITH THIS PACKAGE, YOU CAN
SIMPLY TRY WITH THIS COMMAND:

	make install

WHICH WILL BUILD AND INSTALL THE LIBRARY INTO '/usr/local/lib', THE NECESSARY
HEADER FILES INTO '/usr/local/include' AND THE DOCUMENTATION INTO
'/usr/local/doc/hpalib'.

REMARKS: 

	1) If you are going to use GNU make (gmake) to build and 
	   install the library, for instance if you are working on GNU/Linux, 
	   then you have to read and modify the 'GNUmakefile' in place of the
           'makefile'. The 'GNUmakefile' is in the same directory as 
           the 'makefile' and this 'INSTALL' file.

	2) The (GNU)makefile contains the definition of the macro
	   MANTSIZE_MACRO, which is very important to establish 
           the precision which the functions of the HPA library 
	   will perform their computations with. In fact, this
           macro defines the size of a variable of type 'xpr', where
           'xpr' is the numeric type defined and used by the HPA
	   library to store real values. 
	   Its size is related to the precision which HPA
	   does all its computations and stores all the numeric
	   values with. So, bigger size higher precision. However,
	   a bigger size also implies a bigger consumption of memory
	   and an harder work for the CPU. So, you should not exceed
	   with this size if your machine is not really powerful. 

You may change the root directory of installation by changing
the value of the variable PREFIX within the makefile supplied with this
package:
'make install' will put the library file 'libhpa.a' into "$PREFIX/lib",
the header files into "$PREFIX/include" and the documentation
into "$PREFIX/doc/hpalib".
If one or more of these subdirectories do not exist the installation procedure
will try to create them.
You may also change the values of the variables LIBDIR, INCLUDEDIR or/and
DOCDIR to control in a better way where the installation procedure will
put the files. Of course, all these modifications must be done before
giving the command 'make install'.
Be careful !!! If you want to install the library inside a system-directory
then you will have to launch the 'make install' command as root.

If you are a programmer and you want to contribute to the debug of the
HPA library, then you can be interested in producing
debugging informations for the code you are about to compile;
you can do this by defining the variable DEBUG_MACRO (see makefile
or GNUmakefile) as "-g" (or -g2, -g3, -ggdb if you are using the gcc compiler).

If you want to produce optimized code and gcc is your compiler ,
then you can do it by defining the variable OPT_MACRO as "-O", "-O2" or
"-O3". I always use the -O3 optimization level. I suggest you to
avoid higher optimization levels, since I have never tested the library
with them !
	
Be careful !  If gcc is your compiler then you can enable debug
and optimization at the same time (if you wish so).

IF YOU ARE INTERESTED IN HAVING ALSO THE C++ WRAPPER AND
YOU PRESUME THAT YOUR C++ COMPILER IS RECENT ENOUGH, then
you can use

        make cxx_install

in place of the simple

        make install

All the previous annotations, remarks and warnings
remain valid.  

After the installation, give the command:

'make clean'		to remove the object-files from the source directory
			of the library,

'make clobber'          to remove the object-files and the library-files
                        (these ones have a name ending by .a).
			
At last, the command

'make uninstall'

may be used to remove the library, the header files and the other
files previously installed from their destinations. Moreover, this
command will also remove the subdirectory 'hpalib' from 'PREFIX/doc'.

To have more information about using HPA library, read the documentation
contained in the ./doc directory. This documentation,
which is available in several formats (PDF, HTML and plain ASCII text),
is also installed inside 'PREFIX/doc/hpalib'.
Sorry, i do not supply the Makefile for Microsoft Windows(R) or MacOS X(R),
I only work on GNU/Linux(R), NetBSD(R) and SunOS(R).
Perhaps, the instructions before are good for MacOS X too, but i do not
know, really !

P.S.: I have successfully built and tested the HPA library on the following
      systems:

- Slackware GNU/Linux 10.1, kernel 2.4.29, gcc 3.3.4
- FreeBSD 4.9, gcc 2.95.4
- NetBSD 2.0.2, gcc 3.3.3
- SunOS 5.8, ultrasparc, gcc 2.95.3
 
