
   The latest version of this document can be found at:
   http://www.pyngl.ucar.edu/Download/build_pynio_from_src.shtml


How to build PyNIO from source code

PyNIO </Nio.shtml> can only be built on UNIX systems. It has been
successfully built on systems running Linux (32 or 64-bit), MacOSX (PPC
or Intel), Windows/Cygwin, Suns using native compilers, IBMs running AIX
(32 or 64-bit), and SGIs running IRIX.

This document covers what external software packages you need for
PyNIOand how to build them, and then finally how to build PyNIO.

For information on building PyNGL from source code, see the "build PyNGL
from source code <build_pyngl_from_src.shtml>" document.

    * Download and build non-optional external software
      <#BuildNonOptionalSoftware>
          o NCL <#NCL>
          o NetCDF-3 <#NetCDF3> (don't build if using NetCDF-4)
          o JPEG <#JPEG>
          o ZLIB <#ZLIB>
          o PNG <#PNG>
          o HDF-4 <#HDF-4> 
    * Download and build optional external software <#BuildOptionalSoftware>
          o GRIB2 <#GRIB2>
          o HDF-EOS 2 <#HDFEOS2>
          o NetCDF-4 <#NetCDF4> (don't build if using NetCDF-3) 
    * Download the source code for PyNIO <#GetPyNIOSourceCode>
    * Set environment variables if necessary <#SetEnvVars>
    * Execute the 'setup.py' script <#RunSetup> 

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


    Download and build non-optional external software

/Once you download and install any external software to use with PyNIO,
you must comply with the license of that software, regardless of PyNIO's
source code license </Licenses/PyNIO_source_license.shtml>./

List of external software to install:

# NCL <http://www.ncl.ucar.edu>

See the full instructions <http://www.ncl.ucar.edu/Download/> for
building NCL from source code. NCL is a difficult package to build, so
we recommend going the binary distribution route if possible.

Note that many of the instructions for building external software for
NCL will also apply for PyNIO, so you don't need to follow these
instructions twice. Don't fret if you can't get the "ncl" executable in
$NCARG/ni/src/ncl to build; it is not needed by PyNIO. You basically
need "libnio.a" and some include files from that directory.

Make sure the NCARG_ROOT environment variable is set to the root
directory of where this software was installed.

# NetCDF-3 <http://www.unidata.ucar.edu/software/netcdf/> - do not install
if you plan to build NetCDF-4 <#NetCDF4> instead.

Download version 3.6.3 or later. (Do not download version 4.x.x.)

Once you have the netCDF source code, you can build and install it with:

  ./configure --prefix=/usr/local
  make all install

# JPEG <http://www.ijg.org/>

Download version 6b or later.

Once you have the jpeg source code, you can build and install it with:

  ./configure --prefix=/usr/local
  make all install install-lib install-headers

# zlib <http://www.zlib.net/>

Download version 1.2.3 or later.

Once you have the zlib source code, you can build and install it with:

  ./configure --prefix=/usr/local
  make all install

# libpng <http://www.libpng.org/pub/png/libpng.html>

Download version 1.2.27 (earlier versions had a serious bug) or later.

Once you have the libpng source code, build and install it with:

  ./configure  --with-pic --disable-shared --prefix=/usr/local 
  make all install

# HDF-4 <http://hdf.ncsa.uiuc.edu/products/hdf4/>

Download version 4.1 or later (do not download version 5./x.y/).
*Important note:* Normally the HDF include files get installed to
"$prefix/include". Since this will cause some netCDF include files to
get overwritten, you /must/ use the *"--includedir"* option to install
the HDF include files to "$prefix/include/hdf" instead.

For versions older than 4.2r2, make sure the environment variable
'CFLAGS' has -DHAVE_NETCDF included (you can remove it after you are
done with this build, but it won't hurt the other builds). For example:

  export CFLAGS="$CFLAGS -DHAVE_NETCDF"

or

  setenv CFLAGS "$CFLAGS -DHAVE_NETCDF"

Then, build and install HDF-4 with:

 ./configure --prefix=/usr/local --with-zlib=/usr/local \
       --with-jpeg=/usr/local --includedir=/usr/local/include/hdf 
  make all install

The paths used for the "--with-zlib" and "--with-jpeg" options must be
set to whatever you used above for these two software packages.

For versions 4.2r2 and higher:

It's not necessary to alter the 'CFLAGS' environment variable to build
this version. Instead, use the --disable-netcdf option:

 ./configure --prefix=/usr/local --with-zlib=/usr/local \
       --with-jpeg=/usr/local --includedir=/usr/local/include/hdf \
       --disable-netcdf
  make all install

Regardless of which version of HDF-4 you download, the paths used for
the "--with-zlib" and "--with-jpeg" options must be set to whatever you
used above for these two software packages. If you choose to build HDF-4
with the szip compression library, be sure to add
"--with-szip=/usr/local" (or whatever location you used when building
it) to the configuration process.

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


    Download and build optional external software, if needed

# GRIB2

If you need support for reading GRIB2
<http://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc.shtml> files,
then you will need to download and install the following packages:

    * Jasper <http://www.ece.uvic.ca/~mdadams/jasper/> - Download
      version 1.900 or later.

      Once you have the Jasper source code, you can build and install it
      with:

        ./configure --prefix=/usr/local
        make all install

    * g2clib <http://www.nco.ncep.noaa.gov/pmb/codes/GRIB2/> - Download
      version 1.0.4 or later. There's a bug in version 1.0.4, so
      additionally download a modified version of the file
      "g2_unpack2.c" and put it in the "g2clib-1.0.4" directory. If you
      download a different version of g2clib, be sure you incorporate
      the changed g2_unpack2.c file, rather than just copying it over.

      Once you have the g2clib source code and the modified file, make
      changes to "makefile" to:

         1. change the compiler (CC line) and flags (CFLAGS lines)
         2. make sure the DEFS line has both "-DUSE_JPEG2000" and
            "-DUSE_PNG"
         3. add the appropriate location of the Jasper/libpng include
            files to the "INC" line 

      Now type:

        make all
        cp libgrib2c.a /usr/local/lib
        cp grib2.h /usr/local/include

# HDF-EOS 2 software

If you need support for reading HDF-EOS 2
<http://hdf.ncsa.uiuc.edu/hdfeos.html> files, then you will need to
download and install the following packages:

    * HDFEOS 2 <http://www.hdfeos.org/software/> - Download version
      2.14.v1 or later. You may need to edit the file
      "bin/INSTALL-HDFEOS" to make sure it uses the correct compilers
      and compile options. Then run:

        bin/INSTALL-HDFEOS

      Answer questions about location of HDF-4 lib and include files.
      You must specify the "hdf" subdir for the include directory (for
      example, "/usr/local/include/hdf").

      Pay attention to where "libhdfeos.a" file gets installed under the
      hdfeos/lib directory, and copy this file to your library
      installation directory. Do the same for the include files. Do
      *not* copy libGctp.a! For example, on a linux machine, you would
      type:

        cp lib/linux/libhdfeos.a /usr/local/lib/.
        cp include/*.h /usr/local/include/.

    * gctp <http://edcftp.cr.usgs.gov/pub//software/gctpc/> - Download
      latest version available.

        cd gctp/src

      Copy the appropriate make/xxxx/ file to "makefile", edit as
      necessary, and be sure to change LIBDIR appropriately
      (/usr/local/lib). Then type:

        make
        cp libGctp.a /usr/local/lib/.
        cp *.h /usr/local/include/. 

# NetCDF-4 - not needed if you don't need classic NetCDF-4 support

This build will overwrite a NetCDF-3 installation if you have one.

If you need support for reading/writing classic NetCDF-4
<http://www.unidata.ucar.edu/software/netcdf/> files, then you will need
to download and install the following packages:

    * szip <http://www.compressconsult.com/szip/> - Download version 2.0
      or later.

        ./configure --prefix=/usr/local  --disable-shared
        make all install >& make-output

    * HDF5 <http://hdf.ncsa.uiuc.edu/products/hdf5/> - Download version
      1.8.1 or later.

        ./configure --with-zlib=/usr/local --with-szlib=/usr/local --prefix=/usr/local --disable-shared
        make all install >& make-output

    * NetCDF-4 <http://www.unidata.ucar.edu/software/netcdf/netcdf-4/> -
      Download version 4.0 or later.

        ./configure --with-hdf5=/usr/local --with-zlib=/usr/local --with-szlib=/usr/local --prefix=/usr/local --disable-f90 \
             --enable-netcdf-4
        make all install >& make-output

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


    Download the source code for PyNIO

Accessing, downloading, and/or using PyNIO implies acceptance of the
PyNIO source code license </Licenses/PyNIO_source_license.shtml>.

To download the PyNIO source code, follow the instructions at:

    * http://www.pyngl.ucar.edu/Download/ * 

The source code you download will be a single compressed tar file called
something like "PyNIO-1.3.0b1.tar.gz". Move this file to a temporary
directory where you have plenty of disk space (around 250 megabytes to
hold all of the source code, object files, binaries, and so on). Then,
uncompress and untar the file as follows:

  gunzip PyNIO-1.3.0b1.tar.gz
  tar -xvf PyNIO-1.3.0b1.tar

The above steps will create a directory called "PyNIO-1.3.0b1".

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


    Set environment variables if necessary

To build PyNIO, you must set the NCARG_ROOT environment variable to the
root directory of where NCL was installed.

Then, depending on what optional packages (GRIB2, NetCDF-4, HDFEOS) you
decided to install, you will need to set some environment variables so
the PyNIO installation knows about them.

First, you need to set one or more of the following environment
variables to "1" if you build this software package and want to include
it in PyNIO:

setenv HAS_GRIB2 1
setenv HAS_HDFEOS 1
setenv HAS_NETCDF4 1

Furthermore, to help PyNIO locate the installed software, you must set
the corresponding environment variables to the root directory of that
installed software:

GRIB2_PREFIX
HDFEOS_PREFIX
NETCDF4_PREFIX

You only need to set one of these if the paths are all the same.

Finally, you may need to help the PyNIO installation find the location
of any system Fortran libraries needed to resolve symbols between C and
Fortran code. For example, "-lgfortran" is needed if you built the
software with gfortran, "-lg2c" if g77 was used, and "-lf95" for g95.
Use F2CLIBS to indicate the library name (don't include the "-l"), and
F2CLIBS_PREFIX to point to the location. For example:

setenv F2CLIBS gfortran
setenv F2CLIBS_PREFIX /usr/local/lib

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


    Execute the 'setup.py' script

Type:

python setup.py install

to build and install PyNIO. Go back to the "test software
<index.shtml#TestSoftware>" section in the download section for
information on testing PyNIO.

If you have problems, send email to pyngl-talk
<http://mailman.ucar.edu/mailman/listinfo/pyngl-talk> (you must be a
member to post). We will add a trouble-shooting guide once we see what
kind of problems people have.

