-------------------------------------------------------------------------
NeXus - a common format for neutron and X-ray scattering data
             http://www.neutron.anl.gov/NeXus/
-------------------------------------------------------------------------

Installation Instructions
=========================

Unix (including Mac OS X)
----
1) Ensure that you have current versions of the HDF4 and/or the HDF5 
   libraries.  It is now possible to link the NeXus libraries against 
   either or both libraries, depending on the selected make option.
 
   The libraries, which are available as precompiled binaries for a wide
   range of systems, may be downloaded from:
   
    http://hdf.ncsa.uiuc.edu/

   The NeXus libraries link against the following libraries:
   
   HDF4: libmfhdf.a, libdf.a, libjpeg.a, libz.a
   HDF5: libhdf5.a, libz.a
   
   The libjpeg and libz libraries may be separately installed
   (e.g in /usr/lib).  
   
2) Edit the file "makefile_options" to set the compilation and linking
   options for your system, e.g. the name of the compiler and the path
   to the NeXus source code and HDF libraries.  Some examples are
   provided.
   
     N.B. You will need to edit the make files themselves if you do not
          have a Fortran 77 compiler, i.e. remove all Fortran targets.

3) Run the makefile with one of the following target:

   make lib45        - Version linking to both HDF4 and HDF5
   make lib4         - Version only linking to HDF4
   make lib5         - Version only linking to HDF5
   
   This will create the library libNeXus.a, containing both the C and 
   Fortran 77 APIs, as well as NXbrowse and the C and F77 test programs.

4) If you have a Fortran 90 compiler, run the makefile again:

   make libf90       - Fortran 90 library
   
   This creates a separate library, libNeXus90.a and a Fortran 90
   version of the test program.
   
     N.B. libNeXus90.a contains the complete (F90+C) NeXus library.  You
          do not need to link to libNeXus.a as well.  

5) Run the test programs to check the installation.

   ./napi4_test      - Tests C creation of NXtest.nx4, an HDF4 file
   ./napi5_test      - Tests C creation of NXtest.nx5, an HDF5 file
   ./napif_test      - Tests F77 creation of NXtest.nxs (currently HDF4)
   ./NXtest          - Tests F90 creation of NXtest.nxs (currently HDF5)
   
   In all cases, the output should look like the following:

 Number of global attributes:  4
    NeXus_version = 2.0.0.
    file_name = NXtest.nx5
    HDF5_Version = 1.4.3
    file_time = 2002-05-17 14:40:24-0600
 Group: entry(NXentry) contains  8 items
    ch_data( 4)
    Values : NeXus data
    Subgroup: data(NXdata)
    i1_data(20)
    Values :   1  2  3  4
    i2_data(22)
    Values :   1000  2000  3000  4000
    i4_data(24)
    Values :      1000000     2000000     3000000     4000000
    r4_data( 5)
    Values :    1.00   2.00   3.00   4.00
           :    5.00   6.00   7.00   8.00
           :    9.00  10.00  11.00  12.00
           :   13.00  14.00  15.00  16.00
           :   17.00  18.00  19.00  20.00
    r8_data( 6)
    Values :    1.00   2.00   3.00   4.00
           :    5.00   6.00   7.00   8.00
           :    9.00  10.00  11.00  12.00
           :   13.00  14.00  15.00  16.00
           :   17.00  18.00  19.00  20.00
       ch_attribute : NeXus
       i4_attribute :    42
       r4_attribute :   3.141593
    Subgroup: sample(NXsample)
 Link Check OK

   There are small differences in the formatting of the C and Fortran 
   files.  All of them may be viewed by NXbrowse using, e.g.:
   
   ./NXbrowse NXtest.nxs

6) Move NXbrowse, libNeXus.a, and/or libNeXus90.a to standard locations
   for future linking.  You will need to link NeXus utilities to both 
   the NeXus and HDF4/5 libraries.  See the make files for examples.
   
Windows
-------
   See README.WIN32.

VMS
---
1) There is no VMS version of HDF5, so it is only possible to link to 
   the HDF4 libraries.  Ensure that you have the current versions, 
   which are available as precompiled binaries at:
   
    http://hdf.ncsa.uiuc.edu/

   The NeXus libraries link against the following libraries:
   
2) Edit MAKE_VMS.COM to specify the correct location of the HDF 
   libraries, and comment out either the F77 or F90 options if necessary.
   
3) If you are installing the Fortran 90 library, edit NXtest.f90 to 
   replace NXACC_CREATE5 with NXACC_CREATE4 in the first call to NXopen.

4) Run MAKE_VMS.COM (i.e. type @MAKE_VMS) to build the NeXus libraries 
   and utilities.

5) Run the test programs to check the installation.

   $ RUN NAPI4_TEST           (Tests C creation of NXtest.nx4)
   $ RUN NAPIF_TEST or NXtest (Tests Fortran creation of NXtest.nxs)

6) Install the NeXus libraries NEXUS.OLB and/or NEXUS90.OLB, and the 
   include (or module) files in a standard location for building other 
   NeXus programs.
   
Included Files
==============
napi.c           - ANSI C source code of NeXus API
napi.h           - ANSI C header file of NeXus API
napi4.c          - ANSI C source code for HDF4 version of NeXus API
napi4.h          - ANSI C header file for HDF4 version of NeXus API
napi5.c          - ANSI C source code for HDF5 version of NeXus API
napi5.h          - ANSI C header file for HDF5 version of NeXus API
napi4_test.c     - Test code of C API (using HDF4 API)
napi5_test.c     - Test code of C API (using HDF5 API)
NXbrowse.c       - Simple interactive NeXus browser
NXtoXML.c        - Utility to convert NeXus file to XML
NXtoDTD.c        - Utility to produce a metaDTD file from a NeXus file
napif.f          - Fortran 77 wrapper for NeXus API
napif.inc        - Fortran 77 include file
napif_test.f     - Test code of Fortran 77 API
NXmodule.f90     - Fortran 90 wrapper module for NeXus API
NXUmodule.f90    - Fortran 90 utilities module
NXtest.f90       - Test code of Fortran 90 API
Makefile         - Make file for building NeXus libraries and utilities
makefile_options - Compilation and linking options for the make files
makefile_hdf45   - Make file for HDF4 and HDF5 combined version
makefile_hdf4    - Make file for HDF4 version alone
makefile_hdf5    - Make file for HDF5 version alone
makefile_f90     - Make file for Fortran 90 library
make_vms.com     - Command file to build HDF4 targets on VMS

hdf45_4          - Directory containing MS Visual Studio projects (HDF4)
hdf45_5          - Directory containing MS Visual Studio projects (HDF5)
hdf45_45         - Directory containing MS Visual Studio projects (Both)

jnexus           - Directory containing Java API

napi.tex         - LaTeX documentation of C API (somewhat out-of-date)
NXdict.tex       - LaTeX documentation of NeXus data dictionary
NXdict           - Directory containing NeXus dictionary code

ReleaseNotes     - Version information
README           - This file
README.FORTRAN   - Notes on Fortran 77 wrapper
README.FORTRAN90 - Notes on Fortran 90 wrapper
README.WIN32     - Microsoft Windows specific notes
gnu_license.txt  - GNU Lesser General Public License

napi.tar.gz      - gzipped tar file containing all of the above

Comments to : ROsborn@anl.gov

Argonne National Laboratory is operated by The University of Chicago for
the U.S. Department of Energy under contract W-31-109-ENG-38.
LEGAL POSTLUDE
--------------
The NeXus API is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published 
by the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.

The NeXus API is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.

DISCLAIMER OF LIABILITY: This document was prepared as an account of
work sponsored by an agency of the U.S. Government. Neither the U.S.
Government nor any agency thereof, nor the University of Chicago, nor
any of their employees or officers, makes any warranty, express or
implied, or assumes any legal liability or responsibility for the
accuracy, completeness, or usefulness of any information, apparatus,
product, or process disclosed, or represents that its use would not
infringe privately owned rights. 

DISCLAIMER OF ENDORSEMENT: Reference to any specific commercial
product, process, or service by trade name, trademark, manufacturer,
or otherwise does not necessarily constitute or imply its endorsement,
recommendation, or favoring by the U.S. Government or any agency
thereof. The views and opinions of document authors do not necessarily
state or reflect those of the U.S. Government or any agency thereof,
Argonne National Laboratory, or the University of Chicago.

COPYRIGHT STATUS: Documents authored by Argonne National Laboratory
employees resulted from work under U.S. Government contract
W-31-109-ENG-38 and are subject to the following license: the
Government is granted for itself and others acting on its behalf a
paid-up, nonexclusive, irrevokable worldwide license in these
documents to reproduce, prepare derivative works, and perform publicly
and display publicly by or on behalf of the Government.

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

$Id: README,v 1.9 2002/09/15 03:33:32 nexus Exp $
