NCO Homepage
Author: Charles S. Zender
Keywords: NCO Homepage, netCDF, netCDF operator, GCM, HDF, scientific data

## Hints to Build-from-Source:

Generic Build Hints:
- The two NCO build mechanisms: NCO has two build mechanisms: (1) GNU configure and (2) a custom Makefile (`nco/bld/Makefile`) designed for hand-editing. Try the traditional GNU `configure` method first, i.e., `./configure;make;make check;make install`. This method involves no hand-editing of makefiles, but trouble-free builds with it are less common than we would like. The file `nco/configure.eg` contains a table which describes the success you can expect building NCO with the `configure` mechanism. If the simple `configure` recipe above does not work, savvy users may find it straightforward to modify and use the following, more advanced `configure` recipe: `

      # gcc/g++ Sysadmins use/modify this to install/update NCO in /usr/local, based on netCDF4 also in /usr/local (works on givre 20100727):
      export GNU_TRP=`~/nco/autobld/config.guess`
      cd ~/nco;/bin/rm -f *.${GNU_TRP}.foo;make distclean
      CPPFLAGS='-DHAVE_NETCDF4_H -I/usr/local/include' LDFLAGS='-L/usr/local/lib' ./configure --prefix='/usr/local' --enable-ncap2 --enable-netcdf4 > nco.configure.${GNU_TRP}.foo 2>&1
      /bin/cp -f config.log nco.config.log.${GNU_TRP}.foo
      /bin/cp -f libtool nco.libtool.${GNU_TRP}.foo
      make clean;make > nco.make.${GNU_TRP}.foo 2>&1
      make check >> nco.make.${GNU_TRP}.foo 2>&1
      sudo make install >> nco.make.${GNU_TRP}.foo 2>&1

  ` This is the recipe that the developers use to test `configure` on their machines. Please contribute patches required to get the `configure` mechanism working properly for NCO on your platform. The regressions archive contains gory details of successful (and failed) builds for many platforms. Plaform-specific build hints (CentOS, Mac OS X, RHEL, Solaris) are listed below.
  All platforms continue to work fine with the `nco/bld/Makefile` method: `

      export MY_BIN_DIR='/home/username/bin' # Executables installed here
      export MY_OBJ_DIR='/home/username/obj' # Object files placed here
      export MY_LIB_DIR='/home/username/lib' # Libraries built here
      mkdir -p ${MY_BIN_DIR} ${MY_OBJ_DIR} ${MY_LIB_DIR}
      cd ~/nco/bld
      make dir
      make all
      make ncap2
      make test

  ` Disadvantages are that `nco/bld/Makefile` (1) Usually requires editing to fix your platforms paths; (2) Does not support shared libraries; and (3) Requires a degree from Hogwarts to understand.
- Duplicate symbols errors: When building NCO with the netCDF4 library and headers, some compilers emit errors due to duplicate symbol definitions. This arises because of the complexity of the build system. Essentially, NCO has to define some netCDF API prototypes itself to handle the corner case where the netCDF4 distribution is used to build netCDF3 libraries. We have tried to address this issue using `autoconf/configure` but it is beyond our abilities. The fix is to manually tell NCO that the netCDF4 header file `netcdf.h` is in fact being used so that NCO should not attempt to define these prototypes. Do this, e.g., with `CPPFLAGS='-DHAVE_NETCDF4_H'` or `USR_TKN='-DHAVE_NETCDF4_H'` if you use `configure`.
- Build Chain Version Incompatibilities: NCO requires GNU `make` version ≥ 3.78.1 to support target-specific variable values in `bld/Makefile`. NCO most often fails to build because `ncap` fails to build. Two of the most common reasons that `ncap` fails to build are (1) GNU `bison` is out-of-date (upgrade `bison`) and (2) `--enable-optimize-*` is specified to `configure` (do not specify it).
- C99-compliance & old compilers: NCO versions ≥ 2.9.8 require the compiler to support the 1999 ISO C-Standard called C99. NCO takes advantage of two C99 features, restricted pointers and designated initializers. To build NCO versions ≥ 2.9.8 without a C99-compliant compiler, simply undefine the `restrict` type qualifier before compiling NCO. Do this, e.g., with `CPPFLAGS='-Drestrict='`. More details on C99 compatibility are in the header file `nco/src/nco/nco.h`.
- Old netCDF libraries: NCO versions ≥ 3.0.0 require netCDF versions ≥ 3.6 to take advantage of the new 64-bit offset file type. The library and include directories (e.g., `/usr/lib` and `/usr/include`, respectively) for netCDF version ≥ 3.6 must be on the path searched by the compiler, and must precede the locations of any older netCDF installations. To build NCO versions ≥ 3.0.0 with older netCDF versions < 3.6, simply define the pre-processor token `NC_64BIT_OFFSET` to `0` before compiling NCO. Do this, e.g., with `CPPFLAGS='-DNC_64BIT_OFFSET=0'` or `USR_TKN='-DNC_64BIT_OFFSET=0'` if you use `configure` or `bld/Makefile`, respectively. Users attempting to build NCO with OPeNDAP versions ≤ 3.6.x may need this workaround because OPeNDAP did not fully support netCDF version 3.6.x functionality until OPeNDAP versions ≥ 3.7.0. (The indicator for this problem is a build error like `"nco_fl_utl.c", line 30.20: 1506-045 (S) Undeclared identifier NC_64BIT_OFFSET`.) All modern NCO versions require netCDF versions ≥ 3.5.0 to support `nc_type NC_NAT` in NCO source code. NCO versions 3.9.0 and greater (May, 2007) require netCDF versions ≥ 3.6.0 to resolve the `nc_inq_format()` function.
- `ncap` build hints: `ncap` is a sophisticated and somewhat fragile program. `ncap` requires `flex` to build correctly. AT&T `lex` will not work because it does not understand `EOF` rules used in `ncap_lex.l`. `bison` version 1.29 (the default version on early Mac OS X) is buggy and does not parse `ncap_yacc.y` correctly; previous and later `bison`'s work correctly. `bison` version 1.25 will not build `ncap` on Solaris. Please upgrade `bison` to the latest version (e.g., 1.875+) before reporting `ncap` build problems. If `ncap` keeps you from building NCO, and you do not need `ncap`, configure with `--disable-ncap` (and know that `ncwa` will fail to build as a result).
- Build Hints with GSL:
  NCO versions 3.9.6— support automatic building and linking for GSL versions 1.4—. Earlier GSL versions are not supported.
- Build Hints with DAP:
  NCO versions 3.9.9— support automatic building and linking for DAP supplied from libnetcdf versions 4.1-beta1 and beyond
  NCO versions 3.1.3— support automatic building and linking for OPeNDAP versions 3.6.x and GCC versions 4.0+.
  NCO versions 3.0.1—3.1.2 support automatic building and linking for OPeNDAP versions 3.5.x and GCC versions 3.4+.
  NCO versions 2.8.5—3.0.0 support automatic building and linking for OPeNDAP versions 3.4.x and GCC versions 3.3+.
  NCO versions ?.?.?—2.8.4 support automatic building and linking for DODS versions 3.2.x and GCC versions 3.2+.
  No other version combinations are supported.
- `libnco_c++` build hints: `libnco_c++` requires a good C++ compiler to build correctly. Few people need `libnco_c++`, so the workaround is not to build it. This is done by configuring with `--disable-nco_cplusplus`.

Platform-Specific Build Hints:
- AIX build hints: NCO versions 2.8.7+ do not build with autotools under AIX when `--enable-optimize-*` is selected. The workaround is to not use `--enable-optimize-*`. NCO versions 2.9.7+ do not build shared libraries with AIX xlc compilers because of silly AIX library dependencies activated by OpenMP directives. The workaround is to configure with `--disable-shared`.
- IRIX build hints: The most common problem with building on SGI IRIX is an out-of-date toolchain.
- Mac OS X build hints: Mac OS X users report success building NCO without patches so long as they (1) Install the latest version of `bison`, (2) Disable shared libraries and (3) Disable extended regular expressions. This is done with `./configure --disable-regex --disable-shared` Building NCO with shared libraries on Mac OS X on may be possible. To try, first re-build and re-install the netCDF library using `CFLAGS=-fno-common`. Apparently netCDF, unlike most codes, does not set this automatically. Then build NCO normally. Mac OS X ships with a broken version of the POSIX `cut` utility which causes many NCO regression tests to appear to fail. In fact the NCO commands succeed, but the `cut` output fails. The workaround is not to heed the regression tests, or to install a working `cut`, e.g., from the GNU `coreutils` package.
- RHEL build hints: Scripts for generating executables for recent (4.0.x, ~2011) versions of NCO for RedHat Enterprise Linux 5 (RHEL5) and CentOS5 platforms are described here. Older information on building x86_64 RPMs is available here.
- Solaris build hints: All recent NCO versions build with autotools on Solaris 2.7—2.9. The most common problem with building on Solaris with `cc`/`CC` is that `bison` may be out-of-date. Install an up-to-date `bison` (e.g., 1.875+). Solaris 2.10, i.e., Solaris10, had the audacity to change the prototype of the `ctime_r()` function and so does not build NCO 3.0.1. The fix is to upgrade to the current NCO version.
- SX build hints: NEC SX does not understand the `S_ISLNK` macro, preferring instead the (non-POSIX) `S_IFLNK` macro. This macro appears in the file `nco_fl_utl.c`. The patch I wrote for this may be broken. Will someone with NEC SX please send us a working patch?
- Windows build hints: Building on Microsoft Windows is possible with Cygwin. The resulting executables will behave normally on local files, but will not have some (most?) of NCO's network functionality (e.g., `scp`, OPeNDAP). See the User's Guide for more details.