# $Header: /cvsroot/nco/nco/doc/README,v 1.10 2002/12/02 16:23:01 zender Exp $ -*-text-*-

# Purpose: NCO README file

What is NCO?
The netCDF Operators, or NCO, are a suite of programs known as
operators. The operators facilitate manipulation and analysis of
self-describing data stored in the netCDF or HDF formats, which are
freely available (http://www.unidata.ucar.edu/packages/netcdf and
http://hdf.ncsa.uiuc.edu, respectively). Each NCO operator (e.g., 
ncks) takes netCDF or HDF input file(s), performs an operation (e.g.,
averaging, hyperslabbing, or renaming), and outputs a processed netCDF
file. Although most users of netCDF and HDF data are involved in
scientific research, these data formats, and thus NCO, are generic and
are equally useful in fields like finance. The NCO User's Guide
illustrates NCO use with examples from the field of climate modeling
and analysis. The NCO homepage is http://www.cgd.ucar.edu/cms/nco.

Installation:
NCO will run on all major UNIX systems and MS Windows.
All you need to build NCO is an ANSI-compliant C compiler, preferably gcc.
NCO installation is in a transitional period between the older,
custom Makefile builds and the newer ./configure mechanism.

Newer Autotools Configure Build Procedure:
Try the newer ./configure mechanism first by using the configure
command in the top-level NCO directory:

`cd ~/nco;./configure;make;make install'

If this does not work, please look at the slightly more complex
(and realistic) examples that we have used for your machine
architecture on our test machines. These commands are listed in the
configure.eg file in the top-level NCO directory. The output of these
commands from our test machines is available for your inspection via
anonymous FTP from

ftp://dust.ess.uci.edu/pub/zender/nco/rgr

Please send us any modifications to the configure.in script that you 
feel would be beneficial to other NCO users. 

Older Manual Makefile Build Procedure:
If none of this works for you, then try the older build mechanism.

`cd ~/nco/bld;make dir;make'

You must be using GNU make, which will default to using `Makefile'.
Makefile has some hardcoded switches which may be only valid at UCI
or NCAR, but which can serve as a template for your environment. 
First, be sure to define NETCDF_INC and NETCDF_LIB variables either 
within your environment, or at the top of Makefile. 
Within Makefile, locate the block of code which corresponds
to your machine type as defined by $PVM_ARCH and the pvmgetarch command.
Within this block you may need to edit the CC, CPPFLAGS, and LDFLAGS
arguments so they reflect the names of the compilers and linkers.  If
you are not using GNU C your C compiler may break on certain pieces of
code ('cc' on Cray works fine, 'cc' on SunOS4.1.x may break but 'acc'
should work on all Suns, and 'cc' on SGIs may break).

Read ../bld/Makefile for useful switches you can set.  
Compile with `make OPTS=D' to build debugging versions.  
Environment variables MY_OBJ_DIR, MY_INC_DIR, MY_LIB_DIR and
MY_BIN_DIR control locations of object files, include files,
libraries, and executables. 

Documentation and Bug Reports:
Please read the NCO manual before you submit a bug report!  The manual
is supplied in five different formats: Postscript (nco.ps), Texinfo
(nco.texi), Info (nco.info), HTML (nco.html), and DVI (nco.dvi).  If 
you got this from a CVS snapshot, you will need to generate the format
you want yourself with 'make nco.html', 'make nco.pdf', 'make nco.ps', etc.
Sending me questions whose answers aren't in the manual is the best
way to motivate me to write more documentation.  I would also like to
accentuate the contrapositive of this statement.

Good luck,
Charlie