Building NCL: Helpful Hints

This document is intended to supplement the online documentation that discusses how to install NCL from source code:

http://www.ncl.ucar.edu/Download/build_from_src.shtml

There is a lot of information there, as it's not a trivial process to build and install even the minimum software necessary to properly create NCL and its associated tools. More often than not, the above document will answer questions you may have and reference problems already encountered. Please read it thoroughly.

Here are some helpful hints, based on numerous builds of NCL on a variety of different computers with a lot of different compilers.

• When you installed NCL in the past, you were installing a precompiled binary with some supporting files. This means that all non-optional software upon which NCL depends was built in to the binary. The base non-optional software may be installed on your host; if not, you have to install it prior to building NCL.

• Installing non-optional and optional software in one location; that is, with the same root directory, such as '/usr/local' is a good idea if you can do so. It allows you to 'point' to one location when referencing libraries, include files and such for building NCL.

• The non-optional software is noted in the documentation, along with suggested configuration and build commands. Non-optional software includes:

§ netCDF-3 or netCDF-4

§ jpeg

§ zlib

§ HDF-4

§ szlib (necessary if you build HDF-4 with szip compression)

These non-optional software packages are generally easily configured, and allow the builder to set environment variables that define compilers and their options. Take the time to learn a bit about your compilers and their options to not only make configuring and building software easier, but also to create applications and libraries that are tuned to your particular computing environment.

A special note on HDF4 software: Normally the HDF include files would get installed to the ‘include’ directory of your chosen root directory. Since this will cause some netCDF include files to be overwritten when installing HDF, you must use the "--includedir" option to install the HDF include files to an "hdf" subdirectory.

Another special note related to HDF software: Be sure to edit the source files NclHDF.c and NclHDFEOS.c and remove the following line from each:

#include <hdf/netcdf.h>

This will be fixed in the next release of NCL.

• As with non-optional software, the installation of optional software requires the same forethought and care. The online documentation referenced above clearly describes what is required for proper configuration and installation of these software packages.

§ If you choose to install and use the netCDF-4 software, the HDF-5 software is also required. This does not mean that HDF-5 supercedes the HDF-4 installation you have already completed! There are portions of NCL functionality that require HDF-4 functionality.

§ Installing netCDF-4 software will necessarily supercede the use of netCDF-3, and may overwrite that software installation if you use the default software configuration. If you want to preserve an installation of netCDF-3 software, take care when configuring netCDF-4.

§ The software required for OPeNDAP functionality is sometimes already present on a host system. Take care to install the necessary libraries for OPeNDAP functionality in the same root directory already chosen for non-optional software.

§ Also note that a portion of the OPeNDAP software (in particular, libnc-dap) is currently not compatible with netCDF-4 software. You will need to have netCDF-3 libraries and header files installed if you choose to have OPeNDAP functionality. This may require you to explicitly install both netCDF-3 and netCDF-4 one level below your chosen root installation directory.

• NCL code depends on Fortran blockdata variables being initialized correctly. If you're not sure if your Fortran compiler will do this correctly, run the tests provided, as noted in the documentation.

• If it’s necessary to modify NCL configuration files to properly describe your host system, compilers and library and header locations, take care to not add locations such as compiler-specific library and header directories. The compilers themselves should know about them already; error messages that indicate such things cannot be found point to an improper compiler installation. As well, list any locations for libraries and header files that you wish to reference in the ArchRecLibSearch and ArchRecIncSearch definitions. For example, this is the proper place to reference X11 libraries and header files locations.

• When you run the 'make' process for NCL, be sure to capture the output to a log file, as the documentation demonstrates. It is far easier to go back and look through a log file for errors if something doesn’t build correctly, than scrolling through windows full of text. It is often helpful to search the resultant ‘make’ output for words like fatal and error to more quickly locate problems. There will be warning messages generated throughout the build process; generally they are harmless.

• When setting up your interactive environment to run NCL, the online documentation shows how to do this if your interactive environment is a c-shell (‘csh’ or similar) command interpreter. If you are using a Bourne-shell (‘sh’ or similar), please use:

§ export NCARG_ROOT=/usr/local

§ export PATH=$NCARG_ROOT:$PATH

§ export MANPATH=$NCARG_ROOT/man:$MANPATH

• More often than not, the above document will answer questions you may have and reference problems already encountered. Please read it thoroughly.

We welcome any feedback you have regarding this document, our online documentation, and NCL. Please contact us at any time with your questions and comments.