How to build PyNGL from source code

PyNGL 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, and IBMs running AIX (64-bit).

This version of PyNGL was tested with Python versions 2.6.x and 2.7.x, and NumPy versions 1.5.1 and 1.6.0. We have some precompiled binaries you can try.

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

Table of Contents

Compilers needed to build PyNGL
Set environment variables for compilers (helpful, not required)
Download and build non-optional external software
- NCL
- X11 development libraries
Download and build optional external software
- cairo
Download the source code for PyNGL
Set PyNGL-specific environment variables if necessary
Execute the 'setup.py' script
Test PyNGL
Where to get help

Compilers needed to build PyNGL

You need a Fortran 77 or 90 compiler and an ANSI C compiler to build PyNGL. We use gcc/gfortran on Linux and Mac systems.

Do not use g77 as a Fortran compiler.

Set up compiler environment variables for external software

Most of the external software packages that PyNGL depends on are configured using a "configure" script. These "configure" scripts recognize a number of standard environment variables that allow you to set compilers and compile options.

Decide what compilers and compile options you want to use, and then set the following environment variables as appropriate:

Environment variable name Description Example
CC C compiler bash/ksh:
export CC=gcc
csh/tcsh:
setenv CC gcc
CFLAGS C compile flags bash/ksh:
export CFLAGS='-O -ansi -fPIC'
csh/tcsh:
setenv CFLAGS '-O -ansi -fPIC'
FC Fortran compiler bash/ksh:
export FC=gfortran
csh/tcsh:
setenv FC gfortran
FFLAGS Fortran compile flags bash/ksh:
export FFLAGS='-fPIC'
csh/tcsh:
setenv FFLAGS '-fPIC'
F90 Fortran 90 compiler bash/ksh:
export FC=gfortran
csh/tcsh:
setenv FC gfortran
F90FLAGS Fortran 90 compile flags bash/ksh:
export F90FLAGS='-fPIC'
csh/tcsh:
setenv F90FLAGS '-fPIC'
CXX C++ compiler bash/ksh:
export CXX=g++
csh/tcsh:
setenv CXX g++
CXXFLAGS C++ compile flags bash/ksh:
export CXXFLAGS='-O -ansi -fPIC'
csh/tcsh:
setenv CXXFLAGS '-O -ansi -fPIC'
CPPFLAGS preprocessor compile flags
bash/ksh:
export CPPFLAGS='-DNDEBUG'
csh/tcsh:
setenv CXXFLAGS '-DNDEBUG'

Environment variable name	Description	Example
CC	C compiler	bash/ksh: export CC=gcc csh/tcsh: setenv CC gcc
CFLAGS	C compile flags	bash/ksh: export CFLAGS='-O -ansi -fPIC' csh/tcsh: setenv CFLAGS '-O -ansi -fPIC'
FC	Fortran compiler	bash/ksh: export FC=gfortran csh/tcsh: setenv FC gfortran
FFLAGS	Fortran compile flags	bash/ksh: export FFLAGS='-fPIC' csh/tcsh: setenv FFLAGS '-fPIC'
F90	Fortran 90 compiler	bash/ksh: export FC=gfortran csh/tcsh: setenv FC gfortran
F90FLAGS	Fortran 90 compile flags	bash/ksh: export F90FLAGS='-fPIC' csh/tcsh: setenv F90FLAGS '-fPIC'
CXX	C++ compiler	bash/ksh: export CXX=g++ csh/tcsh: setenv CXX g++
CXXFLAGS	C++ compile flags	bash/ksh: export CXXFLAGS='-O -ansi -fPIC' csh/tcsh: setenv CXXFLAGS '-O -ansi -fPIC'
CPPFLAGS	preprocessor compile flags	bash/ksh: export CPPFLAGS='-DNDEBUG' csh/tcsh: setenv CXXFLAGS '-DNDEBUG'

Download and build non-optional software

Once you download and install any external software to use with PyNGL, you must comply with the license of that software, regardless of PyNGL's source code license.

List of external software to install:

NCL
Download NCL version 6.0.0. This version of PyNGL will not build with NCL version 6.1.0. The next release of PyNGL (1.5.0) will build against 6.1.0.
See the full instructions for building NCL from either source code or binary. NCL is a difficult package to build, so we recommend downloading a precompiled binary if possible. Don't fret if you can't get the code in $NCARG/ni/src/ncl to build; it is not needed by PyNGL.
Make sure the NCARG_ROOT environment variable is set to the root directory of where this software was installed.
X11 library
You must have the X11 library (libX11.a, libX11.so) installed on your system.
This library is usually installed as part of an X developer's package, and will reside in a directory like /usr/X11R6/lib or /usr/X11R6/lib64.

Download and build optional software

cairo software

If you need support for creating PNG files, then you will need to download and install cairo, which has dependencies on several other packages:

libpng
Download version 1.2.27 (earlier versions had a serious bug) or later
Once you have the libpng source code, you can build and install it with:
```
  ./configure  --with-pic --prefix=/usr/local 
  make all install
```
pkg-config - Download version 0.25 or later.
Once you have the pkg-config source code, you can build and install it with:
```
  ./configure --prefix=/usr/local
  make all install
```
Make sure that the location of pkg-config is on your search path and library path. For example, if you installed pkg-config to "/usr/local", then you also need to do the following:
From tcsh or csh:
```
  setenv PKG_CONFIG_PATH /usr/local/lib/pkgconfig
  setenv LD_LIBRARY_PATH /usr/local/cairo/lib
  set path=(/usr/local/bin $path)
```
From ksh or bash:
```
  export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
  export LD_LIBRARY_PATH=/usr/local/cairo/lib
  export PATH=/usr/local/bin:$PATH
```
[On a Mac, use DYLD_LIBRARY_PATH instead of LD_LIBRARY_PATH.]
fontconfig - Download version 2.8.0 or later.
Once you have the fontconfig source code, you can build and install it with:
```
  ./configure --prefix=/usr/local
  make all install
```
FreeType - Download version 2.4.4 or later.
Once you have the FreeType source code, you can build and install it with:
```
  ./configure --prefix=/usr/local
  make all install
```
pixman - Download version 0.21.2 or later.
Once you have the pixman source code, you can build and install it with:
```
  ./configure --prefix=/usr/local
  make all install
```
Expat - Download version 2.0.1 or later.
This software may not be needed, but the instructions are here in case you need expat to get cairo support into PyNGL.
Once you have the expat source code, you can build and install it with:
```
  ./configure --prefix=/usr/local
  make all install
```
cairo - Download version 1.8.8 or later.
You can't build cairo until you have installed fontconfig, FreeType, pixman, and pkg-config.
Make sure the "pkg-config" you built is on your search path. For example, if you installed it to /usr/local, then /usr/local/bin needs to be in your search path.
From tcsh or csh:
```
  setenv PATH /usr/local/bin:$PATH
  which pkg-config
```
From ksh or bash:
```
  export PATH=/usr/local/bin:$PATH
  which pkg-config
```
Once you have the cairo source code, you can build and install it with:
```
  ./configure --prefix=/usr/local
  make all install
```
zlib - needed for cairo support
Download version 1.2.5 or later.
Once you have the zlib source code, you can build and install it with:
```
  ./configure --prefix=/usr/local
  make all install
```

Download the source code for PyNGL

Accessing, downloading, and/or using PyNGL implies acceptance of the PyNGL source code license.

To download the PyNGL source code, follow the instructions at the URL:

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

The source code you download will be a single compressed tar file called something like "PyNGL-1.4.0.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 PyNGL-1.4.0.tar.gz
  tar -xvf PyNGL-1.4.0.tar

The above steps will create a directory called "PyNGL-1.4.0".

Set PyNGL-specific environment variables if necessary

To build PyNGL, at a minimum, you must set the NCARG_ROOT environment variable to the root directory of where NCL was installed.

If you optionally want cairo support, then you need to set HAS_CAIRO to 1:

setenv HAS_CAIRO 1

export HAS_CAIRO=1

You may need to set additional environment variables to help the PyNGL source find necessary external software:

CAIRO_PREFIX
FREETYPE_PREFIX

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

Finally, you may need to help the PyNGL 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, or "-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

export F2CLIBS=gfortran
export F2CLIBS_PREFIX=/usr/local/lib

Execute the 'setup.py' script

Type:

python setup.py install

to build and install PyNGL.

Test PyNGL

To quickly test if PyNGL can be imported without errors, type "python" at the UNIX prompt and then "import Nio" at the python prompt. You should get the python prompt back with no errors. For more extensive PyNGL tests, you can run any one of the examples in the gallery by typing:

   pynglex example_name

For example:

   pynglex ngl01p

Note that some of these examples depend on PyNIO, and will not run unless you install PyNIO, or use another package to read in the data files.

For a list of all the examples, type:

   pynglex -l

The default for most of these examples is to send the output to a PostScript file using the example name, with a ".ps" appended. To change the output to an X11 window or a PDF file, use the "-w" option:

   pynglex -w x11 ngl01p
   pynglex -w pdf ngl01p

Note that if the output file contains multiple frames and you are sending the output to an X11 window, you need to click on the window with your left mouse button to advance the next frame. Or, you can position your mouse over the window and hit <RETURN>.

If you have problems, send email to 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.

Where to get help

If you are having problems building or installing PyNGL, send email to pyngl-talk@ucar.edu. You need to be a member in order to post.